The Output Delivery System (ODS)

The Output Delivery System (ODS) enables SAS procedures to generate output in several formats. One of these output formats is HTML. You can use ODS in your Application Dispatcher programs to easily create Web pages containing HTML and graphics. This page discusses features and options of ODS that are appropriate for the Application Dispatcher environment. ODS can be used in other SAS environments and can generate other forms of output. For more information about ODS, refer to the SAS Output Delivery System: User's Guide.

Creating Web Output with ODS

HTML output is enabled with the ODS HTML statement. The ODS HTML statement can create

an HTML file (called the body file) that contains the results from the procedures run in your Application Dispatcher program
a table of contents that links to the body file
a table of pages that links to the body file
a frameset that displays the table of contents, the table of pages, and the body file.

ODS might also generate additional HTML or image files if you split the output across multiple body pages or you use embedded GIF or JPEG images to display graphics.

The HTTP protocol used by the Application Dispatcher can deliver only one output file back to the Web browser per request. This output file is written to the _WEBOUT fileref. Because ODS generates multiple output files in many cases, the extra files must be stored in a temporary location and retrieved by the Web browser in subsequent requests. The Application Server automatically creates a unique temporary catalog for every request for this purpose. The two-level catalog name is defined in the special macro variable _TMPCAT. ODS must also put hyperlinks and inline image links into the HTML that it generates that retrieves the files from the temporary catalog. The special macro variable _REPLAY contains the base URL used to create these links.

To enable the above features, any Application Dispatcher program that uses ODS to generate HTML should include the following options in the ODS HTML statement:

ods html path=&_tmpcat (url=&_replay) rs=none ...;

Note: The RS=none option forces ODS to perform record based output and is required when writing to the _WEBOUT fileref or to a catalog entry.

ODS is capable of creating a number of different layouts for your output. All layouts have one thing in common: the "primary" page must be returned directly to your Web browser (via the _WEBOUT fileref). The page written to the _WEBOUT fileref must be preceded by an HTTP header with the appropriate content-type field.

Starting with Release 8.2, the automatic HTTP header generation feature recognizes some ODS output types and generates appropriate content-type headers. Supported output types include HTML, GIF, and JPEG. An appropriate content type must be manually set with APPSRV_HEADER function for all other output types.

If you are writing to _WEBOUT using PUT statements while ODS has _WEBOUT open, when you execute the code the PUT statement data might be out of sequence with the data generated by ODS. This problem occurs because both your code and ODS are opening the same fileref at the same time. This problem can be fixed by inserting your PUT statements before you open ODS, closing ODS while you write directly to the fileref, or using the ODS HTML TEXT="string" option to write data. The following code is an example of how you can use the ODS HTML TEXT="string" option to write data:

ods listing close;
ods html body=_webout path=&_tmpcat
   (url=&_replay) Style=Banker;
... other code ...
ods html text='<p align="center"> </p>' ;
ods html text='<p align="center"><b>Test.
   If you see this in order, it worked.</b></p>';
... other code ...
ods html close;

Layout Examples

Overview of Layout Examples

The following annotated examples illustrate how to return various ODS layouts to your Web browser. For these examples, the following data set is used:

data stocks;
length symbol $4 price 8.;
input @1 symbol price;
label symbol = 'Symbol'
   price = 'Share Price';
format price 7.2;
cards;
AMD 23.50
BORL 9.31
CA 47.25
CPQ 32.06
DELL 139.88
GTW 44.00
HWP 67.00
IBM 104.44
INTC 89.69
MSFT 84.75
ORCL 24.63
SUNW 47.63
;
run;

The examples are

Body Only

When you return only the body output to your Web browser, the page is rendered as a single, unframed page. Sample code to produce such output is shown below.

ods listing close;
ods html body=_webout
      path=&_tmpcat (url=&_replay) rs=none;
   title 'Stock Prices';
   proc print data=stocks label noobs; run; quit;
ods html close;

Because the body file is the only file created, it is the primary file and is directed to the fileref _WEBOUT.

Body and Table of Contents

You can return the Table of Contents (or Table of Pages) and the body file using ODS framed output. In this case, the file created by the ODS HTML FRAME option is the primary file, and it must be directed to _WEBOUT. Other files are stored in the temporary catalog in the WORK library and are replayed automatically at the proper time.

The sample code below illustrates the creation of a Table of Contents in addition to the body file.

ods listing close;
ods html frame=_webout
      body=b.html
      contents=c.html
      path=&_tmpcat (url=&_replay)
      rs=none charset=' ';
   title 'Stock Prices';
   proc print data=stocks label noobs; run; quit;
   proc contents data=stocks; run; quit;
ods html close;

Note: The charset=' ' option eliminates the CHARSET value in the <META> tag. For more information about using the CHARSET option, see SAS Note #23971 at support.sas.com/kb.

The body and contents files are directed to the temporary catalog and are named B.HTML and C.HTML, respectively. You can choose any valid SAS name for the entries, but the object type must be HTML. Do not enclose the name in quotes or it is interpreted to be an external file rather than a catalog entry.

Table of Contents Only

You might want to return only the Table of Contents to your Web browser to avoid using HTML frames. The page is rendered as a single, unframed page. Links on the Table of Contents page enable you to load body output to the Web browser. A simple modification to the previous example drops the FRAME keyword and makes the contents file the primary file that is returned to _WEBOUT.

ods listing close;
ods html contents=_webout
      body=b.html
      path=&_tmpcat (url=&_replay)
      rs=none charset=' ';
   title 'Stock Prices';
   proc print data=stocks label noobs; run; quit;
   proc contents data=stocks; run; quit;
ods html close;

Note: The

charset='
                        '

option eliminates the CHARSET value in the <META> tag. For more information about using the CHARSET option, see SAS Note #23971 at support.sas.com/kb.

When you click on an item in the Table of Contents, the body file is replayed from the temporary WORK catalog.

Graphics and Text

The code below returns framed output consisting of the Table of Contents and the body, which contains integrated graphics and text. Note that no special ODS keywords were required to create and store the graphic images. This example is essentially the same as the Body and Table of Contents example with some SAS/GRAPH code added.

ods listing close;
ods html frame=_webout
      body=b.html
      contents=c.html
      path=&_tmpcat (url=&_replay)
      rs=none charset=' ';
   goptions reset=all;
   goptions device=gif
      colors=(red orange yellow ligr green blue)
      ctext=black cback=white;
   title 'Stock Prices';
   axis1 major=none minor=none value=none;
   proc gchart data=stocks;
      hbar3d symbol / sumvar=price
         subgroup=symbol
         shape=cylinder
         patternid=subgroup
         raxis=axis1;
      run; quit;
   title;
   proc print data=stocks label noobs; run; quit;
   proc contents data=stocks; run; quit;
ods html close;

Note: The

charset='
                        '

option eliminates the CHARSET value in the <META> tag. For more information about using the CHARSET option, see SAS Note #23971 at support.sas.com/kb.

Cleaning Up

HTML and graphics created by ODS in the _TMPCAT catalog must eventually be deleted. The Application Server handles this task automatically. By default, a temporary catalog is deleted if it is not used for a period of 15 minutes. This time-out value can be changed with the SESSION TIMEOUT=seconds option on PROC APPSRV, or with the APPSRVSET('session timeout',seconds) DATA step function. All temporary catalogs are deleted immediately when a server is stopped.