SAS/GRAPH Software: Reference

Using the Output Delivery System (ODS) with SAS/GRAPH Software

Using ODS with SAS/GRAPH has numerous advantages over generating Web output with the HTML or WEBFRAME device drivers. With ODS, you can

name the body file(s) for storing the ODS output (see Specifying Body Files for Displaying Graphs)
determine whether titles and footnotes are written to the GIF files or the HTML files (see Controlling Titles and Footnotes with ODS Output)
combine graphics and non-graphics output in your Web page (see Adding Non-graphics Output to a Web Page)
generate a Table of Contents to link to the output (see Linking to Output through a Table of Contents)
generate a Table of Pages to link to the output (see Linking to Output through a Table of Pages)
use HTML frames to display the Table of Contents or Table of Pages (see Using Frames to Display ODS Output)
create drill-down graphs (see About Drill-down Graphs).

These sections only briefly discuss ODS as it is used with SAS/GRAPH. For a more detailed discussion of ODS, see The Complete Guide to the SAS Output Delivery System.

At a minimum, to use ODS with SAS/GRAPH, you

specify DEVICE=GIF on a GOPTIONS statement. The GIF device driver creates a GIF file for each GRSEG generated in the SAS program. In Version 7, the GIF driver is the only device driver available for use with ODS. Future releases will provide additional device drivers.
use the ODS HTML statement to specify the ODS options you want to use. At a minimum, you must use the BODY= option to specify a body file.
run a graphics procedure.
close the HTML destination by specifying ODS HTML CLOSE.

Operating Environment Information: In mainframe environments, you must also use the PATH= option with the URL= suboption to specify a valid URL for accessing output in a Web browser. [cautend]

Managing ODS Destinations

ODS supports multiple destinations for procedure output. When using ODS with SAS/GRAPH, you manage two locations:

Listing destination produces graphs, but does not integrate them with the non-graphics output from the SAS program.

HTML destination produces graphs and an HTML file that reference those graphs. When you view the HTML file in a browser, you cannot tell that the graphics are not part of the HTML file. This provides a mechanism for integrating non-graphics and graphics output.

ODS destinations can be open or closed. When a destination is open, ODS can send output to it, and when a destination is closed, ODS cannot send output to it. An open destination always uses system resources.

By default, the Listing destination is open, and the HTML destination is closed. Thus, when you do not specify the ODS HTML statement, procedure output is written to the Listing destination, rendering output the same way it has been rendered in all earlier releases of the SAS System. Specifying the ODS HTML statement opens the HTML destination, but it has no effect on the Listing destination, which remains open unless you explicitly close it.

If both the Listing and the HTML destinations are open when you use the GIF driver to generate graphics for the Web, the following output is generated:

HTML destination Listing destination

The GIF driver creates a GIF file for each graph. Each file's name corresponds to the name of the GRSEG entry for the same graph. The GIF driver creates a GIF file named sasgraph.gif and writes or appends to it (depending on the GSFMODE= setting) each time it generates a graph.

All the HTML files specified on the ODS HTML statement are created. Only the GIF files created in the HTML destination are referenced in the HTML files. If you specify the GIF driver on the TARGET= graphics option rather than the DEVICE= graphics option, the GRAPH window is opened to display the GRSEG output.
Note: TARGET= is for occasions when you need a graph in two different formats. You specify one device driver on DEVICE= and the second on TARGET=. [cautend]

HTML destination	Listing destination
The GIF driver creates a GIF file for each graph. Each file's name corresponds to the name of the GRSEG entry for the same graph.	The GIF driver creates a GIF file named sasgraph.gif and writes or appends to it (depending on the GSFMODE= setting) each time it generates a graph.
All the HTML files specified on the ODS HTML statement are created. Only the GIF files created in the HTML destination are referenced in the HTML files.	If you specify the GIF driver on the TARGET= graphics option rather than the DEVICE= graphics option, the GRAPH window is opened to display the GRSEG output. Note: TARGET= is for occasions when you need a graph in two different formats. You specify one device driver on DEVICE= and the second on TARGET=.

Output in the Listing destination is superfluous for Web use for the following reasons:

The file sasgraph.gif is not referenced in an HTML file.
Previewing GRSEGs in the GRAPH window is not a reliable way to proofread the graphs for use with the Web because the GRAPH window and a Web browser render graphs differently.

When using SAS/GRAPH procedures with ODS, it is good practice to conserve system resources by closing the Listing destination before issuing the ODS HTML statement. When the Listing destination is closed, a GRSEG entry for each graph is still saved in the active catalog, but file sasgraph.gif is not created, and the GRAPH window is not opened when you use TARGET=GIF to specify the GIF device driver.

After generating ODS output, you must close the HTML destination before you can view that output. A typical ODS session with SAS/GRAPH should be structured like this:

/* specify the output location */
filename odsout 'path-to-Web-server';
goptions device=gif;

/* close the listing destination */
ods listing close;

/* open the html destination */
ods html path=odsout body='myfile.htm';

/* SAS/GRAPH program code */

/* close the html destination */
ods html close;

/* open the listing destination */
ods listing;

Note: For more information on ODS destinations, see The Complete Guide to the SAS Output Delivery System. [cautend]

ODS and Procedures that Support RUN-Group Processing

When you use ODS, it is wise to specify a QUIT statement at the end of every procedure that supports RUN-group processing. If you end every procedure step explicitly, rather than waiting for the next PROC or DATA step to end it for you, the QUIT statement will cause the selection list to clear, and you will be less likely to encounter unexpected results.

Specifying Body Files for Displaying Graphs

When you use ODS with SAS/GRAPH, you specify a body file to reference the graphics output. A body file is simply an HTML file that is created by ODS to contain non-graphics output and to reference graphics output so that it displays as if it were part of the HTML file. You can use many body files during the SAS session, although only one at a time can be open. Displaying a Body File in a Browser shows a body file that references charts that were generated by procedure GCHART.

Displaying a Body File in a Browser

[IMAGE]

To open a body file, use the ODS HTML statement's BODY= option. The following code creates a body file named sales.htm, which is created in the output location specified on the FILENAME statement (see Specifying Output Locations for HTML and GIF Files). A more complete ODS example is shown in Example 2: Using ODS with SAS/GRAPH.

filename odsout 'path-to-Web-server';
goptions device=gif;
ods html body='sales.htm' path=odsout;

The body file remains open and all graphics and non-graphics output is written to it until the HTML destination is closed or another body file is opened.

To direct output to multiple body files, use an ODS HTML statement with the BODY= option each time you want to close the current body file and open another:

filename odsout 'path-to-Web-server';
goptions device=gif;

ods html body='sales.htm' path=odsout;

/* code whose output goes to sales.htm */

ods html body='costs.htm' path=odsout;

/* code whose output goes to costs.htm */

ods html close;

If you use BY-group processing on a graphics procedure, a separate graph is generated for each value of the BY variable. In that case, all the graphs will be referenced in the same body file, unless you use the ODS HTML statement's NEWFILE= option to start a new body file for each graph:

 /* use newfile= to open a new */
 /* body file for each graph */
filename odsout 'path-to-Web-server';
goptions device=gif;
ods html body='sales.htm' path=odsout
    newfile=output;

NEWFILE=OUTPUT opens a new body file for each new graph that is generated, whether the graphs are generated with BY-group processing or by multiple procedure runs. The new body files are named by appending consecutive numbers to the name you specify in the BODY= option. In the example above, the initial body file is named sales.htm, and the additional body files that are created will be named sales1.htm, sales2.htm, and so on.

To determine the appearance of output on the Web page, the body file uses table definitions and style definitions. The output in this document shows output with the default definitions. Other definitions are available. You can also create your own. For information on table definitions and style definitions, see The Complete Guide to the SAS Output Delivery System.

Controlling Titles and Footnotes with ODS Output

By default, titles and footnotes are stored as part of the image in the GIF file. To direct them to the body file instead, use the NOGTITLE and NOGFOOTNOTE options in the ODS HTML statement. When titles and/or footnotes are directed to the body file, they do not appear in the GIF file image.

/* direct titles and footnotes */
/* to the html file            */
filename odsout 'path-to-Web-server';
goptions device=gif;
ods html body='sales.htm' path=odsout
    nogtitle nogfootnote;

Titles and footnotes in the body file are rendered as separate HTML tables near the top and bottom of each page of HTML output.

Note: With NOGTITLE and NOGFOOTNOTE, if either titles or footnotes take up much more vertical space than the other, the text on a vertical axis may not be centered properly relative to the axis tick marks. If this happens, you may not want to specify the option. [cautend]

Adding Non-graphics Output to a Web Page

When you open a body file in ODS, all graphics and non-graphics output is referenced in that body file until the HTML destination is closed or another body file is opened. Thus, you do not have to do anything special to combine graphics and non-graphics output. Simply open a body file and run the procedures whose output you want to combine:

filename odsout 'path-to-Web-server';
goptions device=gif;

/* close the listing destination */
ods listing close;

/* open html destination and a body file */
ods html body='sales.htm' path=odsout;

/* generate graphics and */
/* non-graphics output   */
/* using the current data set */
proc gchart;
     vbar3d state / sumvar=sales;
run;
quit;

proc print noobs;
run;

/* close the html destination,  */
ods html close;
/* open the listing destination */
ods listing;

In this example, the GCHART procedure output is referenced in the body file, and then the PRINT procedure output is written below it. The two outputs appear together on the same Web page when file sales.htm is viewed in a browser.

For a more complete example, see Example 9. Combining Graphs and Reports in a Web Page.

Linking to Output through a Table of Contents

With ODS, you can create a contents file to link to the graphics and non-graphics output generated during a SAS session. A contents file is simply a file that uses a Table of Contents to link to output. You can use multiple contents files during the SAS session, although only one at a time can be open.

Displaying a Contents File in a Browser

[IMAGE]

To create a contents file, specify a name for the file in the ODS HTML statement's CONTENTS= option.

The following code creates a contents file named salesCon.htm, which is created in the output location specified in the FILENAME statement (see Specifying Output Locations for HTML and GIF Files). A more complete ODS example is shown in Example 2: Using ODS with SAS/GRAPH.

filename odsout 'path-to-Web-server';
goptions device=gif;
ods html body='sales.htm' path=odsout
    contents='salesCon.htm';

The contents file remains open and links are written to it for all graphics and non-graphics output that is generated by the SAS program until one of the following occurs:

The HTML destination is closed.
Another contents file is opened. To open a new contents file, specify another ODS HTML statement and use CONTENTS= to specify the new file's name.

For graphics procedures, use the DESCRIPTION= option to specify the text to be displayed for the links to that procedure's output. If you don't use DESCRIPTION=, the procedure's default description text is used.

To use the Table of Contents, view the contents file in the browser. When you select a link from the Table of Contents, the browser goes to the target output referenced by that link. To use the Table of Contents again, you must use the browser's Back button or some other mechanism to return to the contents page. If your browser supports HTML frames, you can keep the Table of Contents visible and its links accessible at all times by displaying the contents page in a frame (see Using Frames to Display ODS Output).

Linking to Output through a Table of Pages

With ODS, you can create a page file to link to the graphics and non-graphics output generated during a SAS session. A page file is simply a file that uses a Table of Pages (page references) to link to output. You can use multiple page files during the SAS session, although only one at a time can be open.

Displaying a Page File in a Browser

[IMAGE]

To create a page file, specify a name for the file in the ODS HTML statement's PAGE= option.

The following code creates a page file named salePage.htm, which is created in the output location specified in the FILENAME statement (see Specifying Output Locations for HTML and GIF Files. For a more complete ODS example, see Example 2: Using ODS with SAS/GRAPH.

filename odsout 'path-to-Web-server';
goptions device=gif;
ods html body='sales.htm' path=odsout
    page='salePage.htm';

The page file remains open and links are written to it for all graphics and non-graphics output that is generated by the SAS program until one of the following occurs:

The HTML destination is closed.
Another page file is opened. To open a new page file, specify another ODS HTML statement and use PAGE= to specify the new file's name.

To use the Table of Pages, view the page file in the browser. When you select a link from the Table of Pages, the browser goes to the target output referenced by that link. To use the Table of Pages again, you must use the browser's Back button or some other mechanism to return to the page file. If your browser supports HTML frames, you can keep the Table of Pages visible and its links accessible at all times by displaying the page file in a frame.

Using Frames to Display ODS Output

With ODS, you can create a frame file to display a Table of Contents and/or a Table of Pages. A frame file is simply a file that uses two frames: one to reference a contents file and/or a page file, and a second to display output that is selected from the table of contents or pages. To use a frame file, your browser must support HTML frames. Displaying a Frame File in a Browser shows a frame file that is displaying a Table of Contents.

Displaying a Frame File in a Browser

[IMAGE]

To create a frame file, specify a name for the file on the ODS HTML statement's FRAME= option. You must also use the options CONTENTS=, PAGE=, or both to provide a table to display in the left frame.

The following code creates a frame file named saleFram.htm, which is created in the output location specified on the FILENAME statement (see Specifying Output Locations for HTML and GIF Files). A more complete ODS example is shown in Example 2: Using ODS with SAS/GRAPH.

filename odsout 'path-to-Web-server';
goptions device=gif;
ods html body='sales.htm' path=odsout
    contents='saleCon.htm'
    frame='saleFram.htm';

To use the frame file, view the frame file in the browser. When you select a link from the Table of Contents or Table of Pages, the content of the right frame changes to display the output that is the target of the selected link, but the links from the contents or pages remain accessible in the left frame.

Chapter Contents
Previous
Next
Top of Page

Listing destination	produces graphs, but does not integrate them with the non-graphics output from the SAS program.
HTML destination	produces graphs and an HTML file that reference those graphs. When you view the HTML file in a browser, you cannot tell that the graphics are not part of the HTML file. This provides a mechanism for integrating non-graphics and graphics output.