|The Complete Guide to the SAS Output Delivery System|
For each ODS destination, ODS maintains either a selection list (a list of output objects to send to the destination) or an exclusion list (a list of output objects to exclude from the destination). ODS also maintains an overall selection list or an overall exclusion list. You can use these lists to control which output objects go to which ODS destinations.
To see the contents of the lists use the ODS SHOW statement, which writes the lists to the SAS log (see ODS SHOW Statement). The following table shows the default lists:
|ODS Destination||Default List|
|How to Specify an Output Object|
In order to work with selection and exclusion lists, you must know how to specify an output object.
To specify an output object, you need to know what output objects your SAS program produces. The ODS TRACE statement writes to the SAS log a trace record that includes the path, the label, and other information about each output object that is produced. (See ODS TRACE Statement.) You can specify an output object as
Univariate.City_Pop_90.TestsForLocationpartial paths are
"The UNIVARIATE Procedure"."CityPop_90" ."Tests For Location"partial label paths are
"CityPop_90"."Tests For Location"
"Tests For Location"
|How ODS Determines the Destinations for an Output Object|
As each output object is produced, ODS uses the selection and
exclusion lists to determine which destination or destinations to send it
to. The following figure illustrates this process:
Directing an Output Object to a Destination
Note: Although you can maintain a selection list for one destination and
list for another, it is easier to understand the results if you maintain the
same types of lists for all the destinations that you route output to.
|Modifying Selection and Exclusion Lists|
There are two ways to modify a selection or exclusion list:
The Output destination behaves differently from the other destinations. Its selection list associates output objects with SAS data sets. As the objects are created, ODS sends them to the Output destination and creates the data sets. Whenever ODS closes a data set, it must remove the data set and the corresponding output objects from the selection list to avoid writing over the data set. In addition, in order to accommodate BY-group processing and RUN-group processing, ODS must sometimes modify the list for the output destination at the end of a run-group as well as at the end of a procedure or DATA step. Therefore, the maintenance of the lists for the Output destination differs from the maintenance of the lists for other destinations.
This section explains automatic and explicit modifications
of the lists for each destination.
At the end of each DATA step that uses ODS and at the end of each procedure step, ODS removes from the list all output objects that were not specified with the PERSIST option (see ODS EXCLUDE Statement and ODS SELECT Statement). If ODS removes all objects from the list, it sets the list to its default of SELECT ALL. If any items in the list are specified with PERSIST, they remain in the list, and the resulting list is used.
If the list contains the argument ALL or NONE, it is not modified at the end of a procedure or DATA step. You must explicitly modify such a list (see Explicit Modification of Lists All Destinations except the Output Destination).
The following table illustrates how ODS modifies several different lists for the overall destination when a DATA step that uses ODS or a procedure step ends.
|Initial list||List after a DATA or procedure step ends|
|select moments quantiles||select all|
|exclude moments quantiles||select all|
|select moments(persist) quantiles||select moments(persist)|
|exclude moments(persist) quantiles||exclude moments(persist)|
|exclude all||exclude all|
There are three ways to explicitly modify the list for the Overall, HTML, Listing, or Printer destination with the ODS EXCLUDE and ODS SELECT statements:
Note: You cannot remove
items from the list this way.
In addition, the following statements not only explicitly reset the overall list as specified, but they also set the list for each individual destination to its default.
The following table illustrates these ways of modifying the HTML list:
|If the initial list for the HTML destination is ...||And you specify ...||The new list for the HTML destination is ...|
|select moments(persist) quantiles||ods html exclude moments;||exclude moments|
|select moments(persist) quantiles||ods html select all;||select all|
|select moments(persist) quantiles||ods html select moments extremeobs(persist);||select moments quantiles extremeobs(persist)|
|select moments(persist) quantiles||ods select all;||select all|
ODS automatically removes an object from the Output selection list when it closes the data set that it is making from that object. The time at which the data set is closed depends on
|BY-group processing?||PERSIST=||How ODS Modifies the List|
|No||Not used||Closes the data set and removes the output object from
the list as soon as it has made the data set.
Removes all objects from the list when a DATA step that uses ODS or a procedure ends.
|Yes||Not used||Closes all open data sets and removes all objects from the list when a run-group ends or when a DATA step that uses ODS or a procedure ends. This configuration lets you put data from multiple BY groups into one data set.|
|Yes or no||RUN||Closes all open data sets and removes all objects from the list when a DATA step that uses ODS or a procedure ends. This configuration lets you put data from multiple run groups into one data set.|
|Yes or no||PROC||Closes all open data sets and removes all objects from the list at the end of the SAS session.|
You modify the list for the Output destination with the ODS OUTPUT statement (see ODS OUTPUT Statement). Use ODS OUTPUT with one or more data-set-specifications to add objects to the list or to modify the associations between output objects and data sets.
The following statements always reset the list for the Output destination to EXCLUDE ALL.
Remember that for procedures that support RUN-group processing (such as DATASETS, GLM, and REG), the RUN statement does not end the procedure. A QUIT statement explicitly ends such a procedure. If you omit a QUIT statement, a PROC or DATA statement implicitly ends such a procedure step.
When you are using ODS, it is wise to specify a QUIT statement at the end of every procedure that supports run-group processing. If you end every such procedure step explicitly, rather than waiting for the next PROC or DATA step to end it for you, the QUIT statement resets the selection list. The following figure illustrates the difference that a QUIT statement makes:
What Happens When You Leave Off the QUIT Statement?
For an example of a SAS program that illustrates how the lists are written and cleared, see Using a Selection List with Multiple Procedure Steps.
Top of Page
Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.