The Output Delivery System | SAS/STAT 9.1 Users Guide, Volumes 1-7

Output Objects and ODS Destinations

All SAS procedures produce output objects that the Output Delivery System delivers to various ODS destinations , according to the default specifications for the procedure or to your own specifications.

All output objects (for example, a table of parameter estimates) consist of two component parts :

the data component, which consists of the results computed by a SAS procedure
the template, which contains rules for formatting and displaying the results

When you invoke a SAS procedure, the procedure sends all output to the Output Delivery System. ODS then routes the output to all open destinations. You define the form that the output should take when you specify an ODS destination. Some supported destinations are as follows :

LISTING destination (the standard SAS listing), which is the default
HTML destination, for hypertext markup language
RTF, for inclusion in Microsoft Word
PDF, PostScript, and PCL, for high-fidelity printers
OUTPUT destination, SAS data set
DOCUMENT destination, for modifying and replaying your output without rerunning the procedure that created it

You can activate multiple ODS destinations at the same time, so that a single procedure step can route output to multiple destinations. If you do not supply any ODS statements, ODS delivers all output to the SAS listing, which is the default.

Each output object has an associated template that defines its presentation format. You can modify the presentation of the output by using the TEMPLATE procedure to alter these templates or to create new templates. You can also specify stylistic elements for ODS destinations, such as cell formats and headers, column ordering, colors, and fonts. For detailed information, refer to the chapter titled The Template Procedure in the SAS Output Delivery System User s Guide.

Using the Output Delivery System

The ODS statement is a global statement that enables you to provide instructions to the Output Delivery System. You can use ODS statements to specify options for different ODS destinations, select templates to format your output, and select and exclude output. You can also display the names of individual output tables as they are generated.

In order to select, exclude, or modify a table, you must first know its name . You can obtain the table names in several ways:

For any SAS/STAT procedure, you can obtain table names from the individual procedure chapter or from the individual procedure section of the SAS online Help system.
For any SAS procedure, you can use the SAS Explorer window to view the names of the tables created in your SAS run (see the section Using ODS with the SAS Explorer on page 277 for more information).
For any SAS procedure, you can use the ODS TRACE statement to find the names of tables created in your SAS run. The ODS TRACE statement writes identifying information to the SAS log (or, optionally , to the SAS listing) for each generated output table.

Specify the ODS TRACE ON statement prior to the procedure statements that create the output for which you want information. For example, the following statements write the trace record for the specific tables created in this REG procedure step.

  ods trace on;   proc reg;   model y=x;   model z=x;   run;   ods trace off;

By default, the trace record is written to the SAS log, as displayed in Figure 14.1. Alternatively, you can specify the LISTING option, which writes the information, interleaved with the procedure output, to the SAS listing (see Example 14.3).

  ods trace on;   proc reg;   model y=x;   model z=x;   run;   .   .   .   Output Added:   -------------   Name:       ParameterEstimates   Label:      Parameter Estimates   Template:   Stat.REG.ParameterEstimates   Path:       Reg.MODEL1.Fit.y.ParameterEstimates   -------------   .   .   .   Output Added:   -------------   Name:       ParameterEstimates   Label:      Parameter Estimates   Template:   Stat.REG.ParameterEstimates   Path:       Reg.MODEL2.Fit.z.ParameterEstimates   -------------

Figure 14.1: Partial Contents of the SAS Log: Result of the ODS TRACE ON Statement

Figure 14.1 displays the trace record, which contains the name of each created table and its associated label, template, and path. The label provides a description of the table. The template name displays the name of the template used to format the table. The path shows the output hierarchy to which the table belongs.

The fully qualified path is given in the trace record. A partially qualified path consists of any part of the full path that begins immediately after a period (.) and continues to the end of the full path.

For example, the full path for the parameter estimates for the first model in the preceding regression analysis is

  Reg.Model1.Fit.y.ParameterEstimates

Therefore, partially qualified paths for the table are

  Model1.fit.y.ParameterEstimates   fit.y.ParameterEstimates   y.ParameterEstimates

To refer to a table (in order to select or exclude it from display, for example), specify either the table name or the table s fully or partially qualified path. You may want to use qualified paths when your SAS program creates several tables that have the same name, as in the preceding example. In such a case, you can use a partially qualified path to select a subset of tables, or you can use a fully qualified path to select a particular table.

You specify the tables that ODS selects or excludes with the ODS SELECT or ODS EXCLUDE statement. Suppose that you want to display only the tables of parameter estimates from the preceding regression analysis. You can give any of the following statements (before invoking the REG procedure) to display both tables of parameter estimates. For this example, these statements are equivalent:

  ods select Reg.Model1.Fit.y.ParameterEstimates   Reg.Model1.Fit.z.ParameterEstimates;   ods select y.ParameterEstimates z.ParameterEstimates;   ods select ParameterEstimates;

The first ODS SELECT statement specifies the full path for both tables. The second statement specifies the partially qualified path for both tables. The third statement specifies the single name ParameterEstimates, which is shared by both tables.

The Output Delivery System records the specified table names in its internal selection or exclusion list. ODS then processes the output it receives. Note that ODS maintains an overall selection or exclusion list that pertains to all ODS destinations, and it maintains a separate selection or exclusion list for each ODS destination. The list for a specific destination provides the primary filtering step. Restrictions you specify in the overall list are added to the destination-specific lists.

Suppose, for example, that your LISTING exclusion list (that is, the list of tables you want to exclude from the SAS listing) contains the FitStatistics table, which you specify with the statement

  ods listing exclude FitStatistics;

Suppose also that your overall selection list (that is, the list of tables you want to select for all destinations) contains the tables FitStatistics and ParameterEstimates, which you specify with the statement

  ods select ParameterEstimates FitStatistics;

The Output Delivery System then sends only the ParameterEstimates and FitStatistics tables to all open destinations except the SAS listing. It sends only the ParameterEstimates table to the SAS listing because the table FitStatistics is excluded from that destination.

Some SAS procedures, such as the REG or the GLM procedure, support run-group processing, which means that a RUN statement does not end the procedure. A QUIT statement explicitly ends such procedures; if you omit the QUIT statement, a PROC or a DATA statement implicitly ends such procedures. When you use the Output Delivery System with procedures that support run- group processing, it is good programming practice to specify a QUIT statement at the end of the procedure. This causes ODS to clear the selection or exclusion list, and you are less likely to encounter unexpected results.

Using ODS with the SAS Explorer

The SAS Explorer enables you to examine the various parts of the SAS System. Figure 14.2 displays the Results window from the SAS Explorer. The Results node retains a running record of your output as it is generated during your SAS session. Figure 14.2 displays the output hierarchy when the preceding statements are executed.

Figure 14.2: The Results Window from the SAS Explorer

When you click on the output table names in the Results window, you link directly to the output in the output window or, if you specify the HTML destination, in an HTML browser. The items on the left-hand side of the Results node are output directories. The items on the right-hand side of the Results node are the names of the actual output objects. You can also use the Explorer to determine names of the templates associated with each output table.

Controlling Output Appearance with Templates

A template is an abstract description of how output should appear when it is formatted. Templates describe several characteristics of the output, including headers, column ordering, style information, justification, and formats. All SAS/STAT procedures have templates, which are stored in the SASHELP library.

You can create or modify a template with the TEMPLATE procedure. For example, you can specify different column headings or different orderings of columns in a table. You can find the template associated with a particular output table or column by using the ODS TRACE statement or the SAS Explorer.

You can display the contents of a template by executing the following statements:

  proc template;   source    TemplateName    ;   run;

where TemplateName is the name of the template.

Suppose you want to change the way all of the analysis of variance tests are displayed by the GLM procedure. You can redefine the templates that the procedure uses with PROC TEMPLATE. For example, in order to have the SS and MS columns always displayed with more digits, you can redefine the columns used by the procedure to display them:

  proc template;   edit Stat.GLM.SS;   format=Best16.;   end;   edit Stat.GLM.MS;   format=Best16.;   end;   run;

The BEST w . format enables you to display the most information about a value, according to the available field width. The BEST16. format specifies a field width of 16. Refer to the chapter on formats in the SAS Language Reference: Dictionary for detailed information.

When you run PROC TEMPLATE to modify or edit a template, the template is stored in your SASUSER library (see Example 14.10). You can then modify the path that ODS uses to look up templates with the ODS PATH statement in order to access these new templates in a later SAS session. This means that you can create a default set of templates to modify the presentation format for all your SAS output. (Note that you can specify the SHOW option in the ODS PATH statement to determine the current path.)

It is important to note the difference between a style template and a column or table template. A column or table template applies to the specific columns or tables that reference the template. For example, the preceding statements that modify the Stat.GLM.SS and Stat.GLM.MS templates provide an example of modifying specific column templates.

A style template applies to an entire SAS job and can be specified with the STYLE= option in a valid ODS destination, such as HTML, RTF, or PDF. Notice that style definitions do not apply to the LISTING destination, which uses the SAS monospace format. For example, you can specify a style as follows:

  ods html style=Styles.Brown;

A style template controls stylistic elements such as colors, fonts, and presentation attributes. When you use a style template, you ensure that all your output shares a consistent presentation style.

You can also reference style information in table templates for individual headers and data cells . You can modify either type of template with the TEMPLATE procedure. For information on creating your own styles, refer to the SAS Output Delivery System User s Guide.

Interaction between ODS and the NOPRINT Option

Most SAS/STAT procedures support a NOPRINT option that you can use when you want to create an output data set but do not want any displayed output. Typically, you use an OUTPUT statement in addition to the procedure s NOPRINT option to create a data set and suppress displayed output.

You can also use the Output Delivery System to create output data sets by using the ODS OUTPUT statement. However, if you specify the NOPRINT option, the procedure may not send any output to the Output Delivery System. Therefore, when you want to create output data sets through ODS (using the ODS OUTPUT statement), and you want to suppress the display of all output, specify

  ods select none;

or close the active ODS destinations by entering the command

  ods    DestinationName    close;

where DestinationName is the name of the active ODS destination (for example, ODS HTML CLOSE).

Note: The ODS statement does not instruct a procedure to generate output: instead, it specifies how the Output Delivery System should manage the table once it is created. You must ensure that the proper options are in effect. For example, the following code does not create the requested data set Parms .

  proc glm;   ods output ParameterEstimates=Parms;   class x;   model y=x;   run;   quit;

When you execute these statements, the following message is displayed in the log:

  WARNING: Output 'ParameterEstimates' was not created.

The data set Parms is not created because the table of parameter estimates is generated only when the SOLUTION option is specified in the MODEL statement in the GLM procedure.

Compatibility Issues with Version 6 Prototypes

In Version 6, the MIXED and GENMOD procedures use a prototype of the Output Delivery System. This prototype provides the MAKE statement in order to create data sets from output tables, and this statement remains supported in these procedures. However, the new mechanism to create SAS data sets from output tables is the ODS OUTPUT statement for all procedures.
The Version 6 prototype of the ODS output hierarchy is stored in a SAS catalog. The latest version of SAS software has a more flexible item-store file type used to store templates and ODS output.
The Version 6 prototype ODS uses two macro variables ( _DISK_ and _PRINT_ ) to regulate the saving of an output hierarchy. The latest version of SAS software uses the global ODS statement to accomplish this task.
The Version 6 PROC TEMPLATE and PROC OUTPUT syntax is not compatible with the latest version of SAS software.