Chapter Contents

Previous

Next

Using Selection and Exclusion Lists

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). Default List for Each ODS Destination shows the default lists:

Default List for Each ODS Destination

ODS Destination	Default List
Listing	SELECT ALL
HTML	SELECT ALL
Output	EXCLUDE ALL
Overall	SELECT ALL

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

• a full path (shown as the path in the trace record).

• a partial path. A partial 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 instance, if the full path is

  
     Univariate.City_Pop_90.TestsForLocation

  partial paths are

  
     City_Pop_90.TestsForLocation

  
     TestsForLocation

• a label (surrounded by quotation marks).

• a label path. (The trace record shows the label path only if you specify the LABEL option in the ODS TRACE statement.)

• a partial label path. A partial label path consists of any part of the label that begins immediately after a period (.) and continues to the end of the label. For instance, if the label path is

  
     "The UNIVARIATE Procedure"."CityPop_90"."Tests For Location"

  partial label paths are

  
     "CityPop_90"."Tests For Location" 

  
     "Tests For Location"

• a mixture of labels and paths.

• any of these specifications followed by a pound sign (#) and a number. For example, TestsForLocation#3 refers to the third output object named TestsForLocation.

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 (see Directing an Output Object to a Destination). For each destination, ODS first asks if the list for that destination includes the object. If it does not, ODS does not send the output object to that destination. If the list for that destination does include the object, ODS reads the overall list. If the overall list includes the object, ODS sends it to the destination. If the overall list does not include the object, ODS does not send it to the destination.

Directing an Output Object to a Destination

Note:    Although you can maintain a selection list for one destination and an exclusion 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:

• ODS automatically modifies lists at certain points in your SAS session.

• You explicitly modify a list when you submit a statement, like the ODS SELECT statement, that is designed to modify a 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 run-group boundaries as well as step boundaries. 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.

Automatic Modification of Lists for the Overall, HTML, and Listing Destinations

At each step boundary, 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 a step boundary. You must explicitly modify such a list (see Explicit Modification of Lists for the Overall, HTML, and Listing Destinations).

Automatically Modifying the Overall List at a Step Boundary illustrates how ODS modifies several different lists for the overall destination at a step boundary.

Automatically Modifying the Overall List at a Step Boundary

Initial List	List after a Step Boundary
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

Explicit Modification of Lists for the Overall, HTML, and Listing Destinations

There are three ways to explicitly modify the list for the Overall, HTML, or Listing Destination with the ODS EXCLUDE and ODS SELECT statements:

• Change the list from a selection list to an exclusion list or from an exclusion list to a selection list. In this case, only the ODS statement that you use determines the contents of the new list.

• Change the scope of the list with the ALL or the NONE argument. In this case, only the ODS statement that you use determines the contents of the list.

• Specify individual objects in the ODS SELECT or the ODS EXCLUDE statement without changing the list from one type to another. In this case, you add new items to the list or change whether or not the PERSIST option is used with an item.

  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.

• ODS SELECT ALL

• ODS SELECT NONE

• ODS EXCLUDE ALL

• ODS EXCLUDE NONE

Explicitly Modifying the List for the HTML Destination illustrates these ways of modifying the HTML list.

Explicitly Modifying the List for the HTML Destination

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

Automatic Modification of the List for the Output Destination

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

• whether BY-group processing is in effect

• whether the PERSIST= option is in effect.

Automatically Modifying the List for the Output Destination

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 at a step boundary.
Yes	Not used	Closes all open data sets and removes all objects from the list at a run-group boundary or a step boundary. 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 at a step boundary. 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.

Explicit Modification of the List for the Output Destination

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.

• ODS OUTPUT CLEAR

• ODS SELECT ALL

• ODS SELECT NONE

• ODS EXCLUDE ALL

• ODS EXCLUDE NONE

Resetting Lists when RUN-Group Processing Is in Effect

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. What Happens When You Leave Off the QUIT Statement? and Using a Selection List with Multiple Procedure Steps illustrate the difference that a QUIT statement makes.

What Happens When You Leave Off the QUIT Statement?

Chapter Contents

Previous

Next

Top of Page

Copyright © 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.