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:	DATA step
Category:	File-handling
Type:	Executable
Default:	ODS sends the output object to all open ODS destinations.
Note:	This syntax shows only the ODS form of the FILE statement. For the complete syntax, see FILE Statement in SAS Statements: Reference.

Syntax

Details

Restrictions When Using the FILE Statement with ODS

Using Options and Suboptions

Without ODS Suboptions

Syntax

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

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.

See: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:ODS Suboptions for information about the ODS suboptions

Optional Arguments

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

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=ON \| OFF 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.

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.

Requirement:You must enclose a column-name in parentheses.

Tip:You can use list notation (for example, score1-score5) to specify multiple column names.

Example: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.

Example: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.

Restrictions:You can use only one COLUMNS= suboption in a FILE PRINT ODS statement.

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.

Tips: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.

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=.

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.

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: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

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.

Tips: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.

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 Attribute Statements.

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 the HEADER= attribute for a particular column in the table definition (see HEADER=))
a label that is specified for a particular column with the LABEL= suboption in the COLUMNS= or VARIABLES= suboption
a label that is specified with the 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.

Example: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.

Example: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.

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=.

Tips: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.

You can change the locations in which ODS searches for the table-definition-name by using the ODS PATH statement.

Example: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.

Examples:Producing ODS Output That Contains Selected Variables

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.
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.

Restrictions:You can use only one VARIABLES= suboption in a FILE PRINT ODS statement.

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.

Tips: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=.

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.

Examples:Producing ODS Output That Contains Selected Variables

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.

See:DYNAMIC= suboption

DYNAMIC Statement

Example:Creating and Using a User-Defined Table Definition Template

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)

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

Example:Creating and Using a User-Defined Table Definition Template

GENERIC=ON | OFF: specifies whether the DATA step uses this column definition for multiple variables.

Default:OFF

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 Attribute Statements.

See:GENERIC= suboption

Example:Creating and Using a User-Defined Table Definition Template

LABEL='column-label': specifies a label for the specified column.

See:LABEL= suboption

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:

These arguments affect only listing output:
- FOOTNOTES and NOFOOTNOTES
- LINESIZE
- PAGESIZE
- TITLE and NOTITLES
Do not use these arguments:
- DELIMITER=
- DLMSTR=
- DSD
- _FILE_=
- FILEVAR=
- HEADER=
- PAD

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;

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.

FILE Statement for ODS

Syntax

Required Arguments

Optional Arguments

ODS Suboptions

Attribute Suboptions

Details

Restrictions When Using the FILE Statement with ODS

Using Options and Suboptions

Without ODS Suboptions

See Also