Previous Page | Next Page

Dictionary of ODS Language Statements

FILE Statement for ODS


Creates an ODS output object by binding the data component to the table definition (template). As an option, the FILE Statement lists the variables to include in the ODS output, and it specifies options that control the way that the variables are formatted.
Valid: in a DATA step
Category: File-handling
Type: Executable
Default: ODS sends the output object to all open ODS destinations.
Syntax
Required Arguments
Options
Without ODS Suboptions
ODS Suboptions
Attribute Suboptions
Details
Restrictions When Using the FILE Statement with ODS
Using Options and Suboptions
See Also

Syntax

FILE PRINT ODS <=(ODS-suboption(s))><options> ;

Note:   

This syntax shows only the ODS form of the FILE statement. For the complete syntax, see the FILE statement in SAS Language Reference: Dictionary.  [cautionend]


Required Arguments

PRINT

is a reserved fileref that you must use when you direct output to ODS.

Requirement: You must use PRINT in a FILE statement that uses the ODS option.
Featured in: Example 1: Creating a Report with the DATA Step and the Default Table Definition
ODS<=(ODS-suboptions)>

defines the structure of the data component and binds the data component to a table definition. The result is an ODS output object. ODS sends this object to all open ODS destinations.

See also: ODS Suboptions for information about the ODS suboptions
Featured in: All examples

Options

N=number

specifies the number of lines that are available to the output pointer in the current iteration of the DATA step.

overflow-control

determines the PUT statement behavior when the output pointer attempts to move past the last ODS column in the buffer.

overflow-control is one of the following:

DROPOVER

discards items when a PUT statement attempts to write beyond the last ODS column in the buffer. A message in the log at the end of the DATA step informs you if data was not written to the buffer.

FLOWOVER

moves the output pointer to a new line if a PUT statement attempts to write an item beyond the last ODS column in the buffer. The PUT statement writes the next item in the first ODS column of the new line.

STOPOVER

stops processing the DATA step immediately if a PUT statement attempts to write beyond the last ODS column in the buffer. SAS discards the data item, writes the portion of the buffer that was built before the error occurred, and issues an error message.

Default: FLOWOVER


Without ODS Suboptions

If you do not specify any ODS suboptions, the DATA step uses a default table definition (BASE.DATASTEP.TABLE) that is stored in the SASHELP.TMPLMST template store. This definition defines two generic columns: one for character variables and one for numeric variables. ODS associates each variable in the DATA step with one of these columns and displays the variables in the order in which they are defined in the DATA step.

If there are no suboptions, the default table definition uses the variable's label as its column heading. If no label exists, the definition uses the variable's name as the column heading.


ODS Suboptions

Task Suboption
Specify one or more columns for the data component COLUMNS= or VARIABLES=
Specify default values for dynamic-attribute values DYNAMIC=
Specify whether all column definitions in the table definition can be used by more than one variable GENERIC=
Specify a column heading to use for any column that does not have a column heading specified in the COLUMNS= or VARIABLES= suboption LABEL=
Specify a name for the output object that the DATA step produces OBJECT=
Specify a label for the output object that the DATA step produces OBJECTLABEL=
Specify the table definition to use with the data component to produce the output object TEMPLATE=

COLUMNS=(column-specification(s))

specifies one or more columns for the data component and determines their order in the data component.

Restriction: You can use only one COLUMNS= suboption in a FILE PRINT ODS statement.
Restriction: You can use either the COLUMNS= suboption or the VARIABLES= suboption, but not both, in a single FILE PRINT ODS statement.
Requirement: You must enclose a column-specification in parentheses.
Tip: The order of the columns in the output object is determined by their order in the table definition, not by their order in the data component.
Tip: To override the default order, use the ORDER_DATA= table attribute in the PROC TEMPLATE step that creates the definition. The default DATA step table definition uses this attribute. For more information, see the discussion of ORDER_DATA= table attribute.
Tip: If you do not specify COLUMNS= or VARIABLES=, then the order of columns in the data component matches the order of the corresponding variables in the program data vector.

Each column-specification associates a DATA step variable with a column that is defined in the table definition. column-specification has this general form:

(column-name-1<=variable-name-1<(attribute-suboptions)>> <... column-name-n<=variable-name-n<(attribute-suboptions)>>>)
column-name

is the name of a column. This name must match the name that is defined in the table definition that you use.

Restriction: column-name must conform to the rules for SAS variable names. For information, see the SAS Language Reference: Dictionary.
Requirement: You must enclose a column-name in parentheses.
Tip: You can use list notation (for example, score1-score5) to specify multiple column names.
Featured in: Example 4: Creating and Using a User-Defined Table Definition Template
variable-name

specifies a variable in the DATA step to place in the specified column.

Default: If you omit variable-name, then ODS looks for a DATA step variable named column-name to place in the specified column. If no such variable exists, then ODS returns an error.
Tip: You can use list notation (for example, score1-score5) to specify a range of variable names.
Featured in: Example 4: Creating and Using a User-Defined Table Definition Template
(attribute-suboptions)

assigns a characteristic, such as a label or a format, to a particular column in the data component. These individual specifications override any attributes that are set by the DATA step.

The following table lists the attribute suboptions that are available for the COLUMNS= suboption. For a complete description, see Attribute Suboptions.

Task Attribute Suboption
Specify a value for the variable defined by the DYNAMIC statement in a table template DYNAMIC=
Specify a format for the current column FORMAT=
Specify whether the DATA step uses this column definition for multiple variables GENERIC=
Specify a label for a particular column LABEL=

Requirement: You must enclose attribute-suboptions in parentheses.
DYNAMIC=(dynamic-specification(s))

specifies default values for dynamic-attribute values.

A dynamic-attribute value is defined in the table definition. Its name serves as a placeholder for the value that is supplied to the data component with the DYNAMIC= suboption. When ODS creates the output object from the table definition and the data component, it substitutes the appropriate value from the data component for the value's name in the table definition.

Each dynamic-specification has the following form:

dynamic-value-name<=variable-name | constant>
dynamic-value-name

is the name that the table definition gives to a dynamic-attribute value.

variable-name

specifies a variable whose value is assigned to dynamic-value-name and passed to ODS to substitute for the placeholder in the table definition when it creates the output object.

constant

specifies a constant to assign to dynamic-value-name and pass to ODS to substitute for the placeholder in the table definition when it creates the output object.

Default: By default, the DYNAMIC= suboption applies to all columns in the data component.
Interaction: Columns that do not contain their own DYNAMIC= suboption specifications use these dynamic-specifications.
Tip: You can override the default specification for an individual column by specifying the DYNAMIC= suboption as an attribute for that column in the COLUMNS= or the VARIABLES= suboption.
See also: DYNAMIC Statement
GENERIC=ON | OFF

indicates whether the DATA step uses all column definitions for multiple variables.

ON

indicates that the DATA step uses all column definitions for multiple variables.

OFF

indicates that the DATA step uses no column definitions for multiple variables.

Default: OFF
Default: By default, the GENERIC= suboption applies to all columns in the data component.
Restriction: ODS does not recognize the column names as a match unless you specify the (COLUMNS=(GENERIC=ON)) suboption.
Interaction: If you do not specify a table definition, the GENERIC= suboption is set to ON.
Tip: To override the default specification for an individual column, specify the GENERIC= suboption as an attribute for that column in the COLUMNS= or the VARIABLES= suboption.
Tip: The GENERIC= option in the DATA step is used in conjunction with the GENERIC= column attribute in the table template. See the GENERIC= column attribute in Column Attributes.
LABEL='column-label'

specifies a label for any column that does not have a label specified in the COLUMNS= or VARIABLES= suboption.

Default: If you use the LABEL= suboption, ODS uses the first of these labels that it finds:

  • a label that is specified with HEADER= attribute for a particular column in the table definition (see HEADER= column attribute)

  • a label that is specified for a particular column with LABEL= suboption in the COLUMNS= or VARIABLES= suboption

  • a label that is specified with LABEL= suboption in the ODS= option

  • a label that is assigned with the LABEL statement in the DATA step
Tip: If you omit the LABEL= suboption, the contents of the table definition determines whether the column heading contains the variable name or is blank.
Featured in: Example 3: Assigning Attributes to Columns in ODS Output
OBJECT= object-name

specifies a name for the output object.

The Results window and the HTML contents file both contain a description of, and a link to, each output object. The description contains the first of the following items that ODS finds:

  • the object's label

  • the current title if it is not the default title, "The SAS System"

  • the object's name

  • the string FilePrint#, in which # increases by 1 for each DATA step that you run in the current SAS process without specifying an object name or an object label

Restriction: object-name must conform to the rules for SAS variable names. For information about these rules, see Rules for Words and Names in the SAS Language in SAS Language Reference: Concepts.
OBJECTLABEL='object-label'

specifies a label for the output object.

The Results window and the HTML contents file both contain a description of, and a link to, each output object. The description contains the first of the following items that ODS finds:

  • the object's label

  • the current title if it is not the default title, "The SAS System"

  • the object's name (see OBJECT=)

  • the string FilePrint#, in which # increases by 1 for each DATA step that you run in the current SAS process without specifying an object name or an object label

Requirement: You must enclose an object-label in quotation marks.
Featured in: Example 3: Assigning Attributes to Columns in ODS Output
TEMPLATE= 'table-definition-name'

specifies the table definition to use with the data component to produce the output object.

table-definition-name

is the path to the table definition. SAS stores a table definition as an item in an item store.

Default: If you do not specify the TEMPLATE= option, ODS uses BASE.DATASTEP.TABLE, the default table definition.
Default: If you do specify the TEMPLATE= suboption, ODS first looks for table-definition-name in SASUSER.TEMPLAT, and then it looks in SASHELP.TMPLMST.
Requirement: You must enclose a table-definition-name in quotation marks.
Interaction: When you use the default table definition, the GENERIC= suboption is set to ON for all columns in the data component. For more information, see GENERIC=.
Tip: When you use the BASE.DATASTEP.TABLE template, character values are left-justified. If you want character values to be right-justified, specify the BASE.DATASTEP.TABLENOJUST template.
Tip: You can change the locations in which ODS searches for the table-definition-name by using the ODS PATH statement.
Featured in: Example 4: Creating and Using a User-Defined Table Definition Template
VARIABLES=(variable-specification(s))

specifies one or more columns for the data component of the output object. Each variable-specification associates a DATA step variable with a column that is defined in the table definition. The variable-specification value has this general form:

(variable-name-1<=column-name-1<(attribute-suboptions)>> <... variable-name-n<=column-name-n<(attribute-suboptions)>>>)

variable-name

specifies a variable in the DATA step to use as a column in the data component.

Tip: You can use list notation (for example, score1-score5) to specify a range of variable names.
Featured in: Example 2: Producing ODS Output That Contains Selected Variables and Example 3: Assigning Attributes to Columns in ODS Output
column-name

is the name of a column. This name must match a name that is defined in the table definition.

Default: If you are using the default table definition and you omit column-name, then ODS uses the variable label to name the column. If the variable has no label, then ODS uses the variable name.
Default: If you use a table definition other than the default table definition and you omit column-name, ODS looks in the table definition for a column that is named variable-name and places the variable in that column. ODS returns an error if no such column exists.
Restriction: column-name must match a column name in the table definition that you are using. It must also conform to the rules for SAS variable names. For information about these rules, see Rules for Words and Names in the SAS Language in SAS Language Reference: Concepts.
Tip: You can use list notation (for example, score1-score5) to specify a range of column names.
(attribute-suboptions)

assigns a characteristic, such as a label or a format, to a particular column in the data component. These individual specifications override any attributes that are set in the DATA step for the entire data component.

The following table lists the attribute suboptions available for the VARIABLES= suboption. For a complete description, see Attribute Suboptions.

Task Attribute Suboption
Specify a value for the variable defined by the DYNAMIC statement in a table template DYNAMIC=
Specify a format for the current column FORMAT=
Specify whether the DATA step uses this column definition for multiple variables GENERIC=
Specify a label for a particular column LABEL=

Default: If you specify the VARIABLES= suboption, the order of the columns in the output object is determined by their order in the table definition, not by their order in the data component. If you do not specify COLUMNS= or VARIABLES= suboptions, the order of columns in the data component matches the order of the corresponding variables in the program data vector.
Restriction: You can use only one VARIABLES= suboption in a FILE PRINT ODS statement.
Restriction: You can use either the COLUMNS= suboption or the VARIABLES= suboption to associate variables with columns, but you cannot use both suboptions in the same FILE PRINT ODS statement.
Tip: To override the default order, use the ORDER_DATA table attribute in the PROC TEMPLATE step that creates the definition. The default DATA step table definition uses this attribute. For more information see the ORDER_DATA= table attribute.
Tip: The VARIABLES= suboption is for use primarily with the default DATA step table definition. When you use the default definition, the DATA step can map variables to the appropriate column in the definition so you do not need to specify a column name.
Featured in: Example 2: Producing ODS Output That Contains Selected Variables and Example 3: Assigning Attributes to Columns in ODS Output.

Attribute Suboptions

DYNAMIC=dynamic-specification(s)

specifies a value for the variable defined by the DYNAMIC statement in a table template.

Main discussion: DYNAMIC=
Featured in: Example 4: Creating and Using a User-Defined Table Definition Template
See also: DYNAMIC Statement
FORMAT=format-name

specifies a format for the current column.

Default: ODS uses the first of these formats for the variable that it finds:

  • for nongeneric columns, a format that is specified in the column definition

  • a format that is specified in the FORMAT= column attribute

  • a format that is specified in a FORMAT statement

  • the default format ($w. for character variables; BEST12. for numeric variables)
Featured in: Example 4: Creating and Using a User-Defined Table Definition Template

Note:   Formats for generic columns that are specified in the table definition are ignored by the DATA step interface to ODS.  [cautionend]

GENERIC=ON | OFF

specifies whether the DATA step uses this column definition for multiple variables.

Default: OFF
Main discussion: GENERIC=
Featured in: Example 4: Creating and Using a User-Defined Table Definition Template
See also: GENERIC
Tip: The GENERIC= option in the DATA step is used in conjunction with the GENERIC= column attribute in the table template. See the GENERIC= column attribute in Column Attributes.
LABEL='column-label'

specifies a label for the specified column.

Main discussion: LABEL=
Featured in: Example 3: Assigning Attributes to Columns in ODS Output
Details


Restrictions When Using the FILE Statement with ODS

The following restrictions apply to the FILE statement when you use it with ODS:


Using Options and Suboptions

Options apply to all columns and suboptions apply to specific columns.

For example, both of the following DATA steps produce the same output. This DATA step specifies the suboption GENERIC=ON for every column. 

Data Step Using the GENERIC=ON Suboption

data _null_;
   set top3list;
      file print ods = (
      template='means.topn'
      columns=(
         class=school(generic=on)
         class=year(generic=on)
         sum=moneyRaised_sum(generic=on)
         mean=moneyRaised_mean(generic=on)
         raised=moneyRaised_1(generic=on)
         raised=moneyRaised_2(generic=on)
         raised=moneyRaised_3(generic=on)
         name=name_1(generic=on)
         name=name_2(generic=on)
         name=name_3(generic=on)
         school=school_1(generic=on)
         school=school_2(generic=on)
         school=school_3(generic=on)
         year=year_1(generic=on)
         year=year_2(generic=on)
         year=year_3(generic=on)
         )
      );
 
    put _ods_;
run;

This DATA step uses the GENERIC=ON option, which has to be specified only once. 

Data Step Using the GENERIC=ON Option


data _null_;
   set top3list;
      file print ods = (
      template='means.topn'
      generic=on
      columns=(
         class=school
         class=year
         sum=moneyRaised_sum
         mean=moneyRaised_mean
         raised=moneyRaised_1
         raised=moneyRaised_2
         raised=moneyRaised_3
         name=name_1
         name=name_2
         name=name_3
         school=school_1
         school=school_2
         school=school_3
         year=year_1
         year=year_2
         year=year_3
         )
      );
 
    put _ods_;
run;

See Also

Statement:

PUT Statement for ODS

Output Delivery System and the DATA Step

Examples

Previous Page | Next Page | Top of Page

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