FILE, ODS

FILE, ODS

Defines the structure of the data component that holds the results of the DATA step and binds that component to a template to produce an output object. ODS sends this object to all open ODS destinations, each of which formats the object appropriately. Also controls what happens when the PUT statement tries to write past the end of a line.

Valid: in a DATA step

Category: File-handling

Type: Executable

Requirement: If you use the ODS option, you must use the fileref PRINT in the FILE statement.

Restriction: The DELIMITER= and DSD options have no effect on the ODS option. You cannot use _FILE_=, FILEVAR=, HEADER=, or PAD with the ODS option.

Syntax
Arguments
Options
ODS Suboptions
Details
See Also

Syntax

FILE PRINT <ODS<=(ODS-option(s))>><overflow-control><N=1 | pagesize>;

Arguments

PRINT

is a reserved fileref that directs the output that is produced by any PUT statements to procedure output.

Restriction:

You must use PRINT in a FILE statement that uses the ODS option.

Options

N=1 | PAGESIZE

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

1

specifies that the buffer can hold only one line at a time. Any code that moves the pointer to a new line causes SAS to write the contents of the buffer to the data component. Once the data are in the data component, you cannot alter them with the PUT statement.

PAGESIZE

specifies that the buffer can hold the whole page at once.

Alias:

ODS<=(ODS-suboptions)>

defines the structure of the data component that holds the results of the DATA step and binds that component to a template to produce an output object. ODS sends this object to all open ODS destinations, each of which formats the object appropriately. For information on the ODS-suboptions, see ODS Suboptions.

Default:

If you do not specify any suboptions, the DATA step uses a default template (base.datastep.table) that is stored in the SASHELP data library. This template 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.

Without suboptions, the default template uses the variable's label as its column header. If no label exists, the template uses the variable's name as the column header.

Restriction:

You must use the fileref PRINT with the ODS option.

overflow-control

determines what the PUT statement does when pointer controls tell it to write past the last column in the buffer. Overflow-control is one of the following:

DROPOVER: does not write items that are directed to columns beyond the last column in the buffer. A message in the log at the end of the DATA step informs you if data were not written to the buffer.
FLOWOVER: moves the pointer to a new line when an item is directed to a column beyond the last column in the buffer, writes the next item in the first column of the new line, and continues to process the PUT statement.
STOPOVER: stops processing the DATA step immediately if a PUT statement attempts to write to a column beyond the last column in the buffer. SAS discards the data item, writes the portion of the line that was built before the error occurred, and issues an error message.

Default:

FLOWOVER

ODS Suboptions

You can use any combination of the following suboptions with the ODS= option in the FILE statement:

To do this... Use this suboption

Specify one or more columns for the data component COLUMNS= or VARIABLES=

Specify default values for column attributes that exist in the template but that get their values from the data component DYNAMIC=

Assert that all column definitions in the template can or cannot be used by more than one variable GENERIC=

Specify a column header to use for any column that does not have a column header 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 template to use with the data component to produce the output object TEMPLATE=

To do this...	Use this suboption
Specify one or more columns for the data component	COLUMNS= or VARIABLES=
Specify default values for column attributes that exist in the template but that get their values from the data component	DYNAMIC=
Assert that all column definitions in the template can or cannot be used by more than one variable	GENERIC=
Specify a column header to use for any column that does not have a column header 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 template 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. Each column-specification associates a DATA step variable with a column that is defined in the template. The order of the columns in the data component is determined by their order in the COLUMNS= suboption.

Note: By default, the order of the columns in the output object is determined by their order in the template, not by their order in the data component. You can override this order by using the ORDER_DATA option in the PROC TEMPLATE step that creates the template. The default DATA step template uses this option. [cautionend]

Each column-specification has this general form:

column-name<=variable-name><(attribute(s))>

column-name

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

Restriction:	column-name must conform to the rules for SAS variable names. The first character must be a letter or an underscore. Subsequent characters can be letters, numbers, or underscores.
Tip:	You can use list notation (for example, `score1`-`score5`) to specify a range of column names.

variable-name

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

Default:	If you omit variable-name, ODS looks for a DATA step variable named column-name to place in the specified column. If no such variable exists, ODS returns an error.
Tip:	You can use list notation (for example, `score1`-`score5`) to specify a range of variable names.

attribute

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. You assign attributes with the following suboptions.

DYNAMIC=dynamic-specification(s)

specifies a value for a column attribute that exists in the template but that gets its value from the data component. For details, see the discussion of DYNAMIC=.

FORMAT=format-name

specifies a format for this particular column.

Default:

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

a format that is specified in a column definition in a template.
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)

GENERIC=ON|OFF

asserts that the DATA step does or does not use this column definition for multiple variables. For details, see GENERIC=.

LABEL='column-label'

specifies a label for this particular column. For details, see LABEL= .

Default:	If you do not specify COLUMNS= or VARIABLES=, 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 COLUMNS= suboption in a FILE statement.
Interaction:	You can use either the COLUMNS= suboption or the VARIABLES= suboption to associate variables with columns. However, you cannot use both suboptions in the same FILE statement.

DYNAMIC=(dynamic-specification(s))

specifies default values for dynamic attributes values. Columns that do not contain their own DYNAMIC= specifications use these.

A dynamic attribute value is defined in the template. 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 template and the data component, it substitutes the appropriate value from the data component for the value's name in the template.

Each dynamic-specification has the following form:

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

dynamic-value-name: is the name that the template 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 template when it creates the output object.
constant: specifies a constant to assign to dynamic-value-name and to pass to ODS to substitute for the placeholder in the template when it creates the output object.

Default:	If you omit variable-name and constant, then the DATA step looks for a variable name that matches 'dynamic-value-name'.
Tip:	By default, DYNAMIC= applies to all columns in the data component. You can override this specification for an individual column by specifying DYNAMIC= as an attribute for that column in the COLUMNS= or the VARIABLES= suboption.

GENERIC=ON | OFF

asserts that the DATA step does or does not use all column definitions for multiple variables.

ON: asserts that the DATA step uses all column definitions for multiple variables.
OFF: asserts that the DATA step uses no column definitions for multiple variables.

Default:	OFF
Interaction:	If you do not specify a template (see TEMPLATE= ), GENERIC= is set to ON.
Restriction:	To have ODS recognize the column names as a match, the GENERIC= specification must match the GENERIC= specification in the template that you are using.
Tip:	By default, GENERIC= applies to all columns in the data component. You can override this specification for an individual column by specifying GENERIC= as an attribute for that column in the COLUMNS= or the VARIABLES= suboption.

LABEL='column-label'

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

Default:

ODS uses for the column header the first of these labels that it finds:

a label that is specified with HEADER= for a particular column in the template.
a label that is specified for a particular column with LABEL= in the COLUMNS= or VARIABLES= suboption.
a label that is specified with LABEL= in the ODS= option.
a label that is assigned with the LABEL statement in the DATA step.
If no label is specified, the contents of the template determines whether the column header contains the variable name or is blank.

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 these items that ODS finds:

the object's label (see OBJECTLABEL= )
the current title if it is not the default title, "The SAS System"
the object's name
the string FilePrint#, where # 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 on these rules, see "Appendix 1: Rules for Words and Names in the SAS Language" in SAS Language Reference: Dictionary.

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 these 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 the discussion of OBJECT=).
the string FilePrint#, where # increases by 1 for each DATA step that you run in the current SAS process without specifying an object name or an object label.

TEMPLATE='template-name'

specifies the template to use with the data component to produce the output object.

template-name

is the path to the template. SAS stores a template as an item in an item store. By default, ODS first looks for template-name in SASUSER.TEMPLAT. If it doesn't find the template there, it looks in SASHELP.TMPLMST. You can change the locations that it searches with the ODS PATH statement.

Default:	The default template (base.datastep.table) that is stored in the SASUSER SAS data library.
Interaction:	When you use the default template, GENERIC= is set to on for all columns in the data component. (See GENERIC=).

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

Each variable-specification has this general form:

variable-name<=column-name><(attribute(s))>

variable-name

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

Tip: You can use list notation (for example, score1-score5) to specify a range of variable names.

column-name

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

Default:	If you omit column-name, ODS looks for a column in the template that is named variable-name and places the variable in that column. If no such column exists, ODS returns an error.
Restriction:	Column-name must match a column name in the template that you are using. It must also conform to the rules for SAS variable names. For information on these rules, see "Appendix 1: Rules for Words and Names in the SAS Language" in SAS Language Reference: Dictionary.
Tip:	You can use list notation (for example, `score1`-`score5`) to specify a range of column names.

attribute

Restriction:	You can use only one VARIABLES= suboption in a FILE statement.
Interaction:	You can use either the COLUMNS= suboption or the VARIABLES= suboption to associate variables with columns. However, you cannot use both suboptions in the same FILE statement.
Tip:	VARIABLES= is primarily for use with the default DATA step template. When you are using the default template, the DATA step can map variables to the appropriate column in the template so you don't need to specify a column name.

Details

Within the DATA step, the ODS option in the FILE statement and the _ODS_ option in the PUT statement provide connections with the Output Delivery System (ODS). You use both of these connections to route the results of a DATA step to ODS. By default, when the DATA step uses ODS, ODS writes output objects to the procedure output and places links to them in the Results folder. You can use global ODS statements to write to other ODS destinations.

The FILE and PUT statements interact in the following way:

The ODS option in the FILE statement defines the structure of the data component that holds the results of the DATA step.
The _ODS_ option in the PUT statement writes values (as specified by the ODS option in the FILE statement) into a special buffer. This buffer is written to the data component.
The ODS option in the FILE statement binds the data component to a template to produce an output object. ODS sends this object to all open ODS destinations, each of which formats the object appropriately.

The ODS destinations are controlled by the global ODS statements. You can use an existing template or create your own with the TEMPLATE. procedure.

For details on using the Output Delivery System, see The Complete Guide to the SAS Output Delivery System.

See Also

Statements:

FILE

PUT, _ODS_

Chapter Contents
Previous
Next
Top of Page

Valid:	in a DATA step
Category:	File-handling
Type:	Executable
Requirement:	If you use the ODS option, you must use the fileref PRINT in the FILE statement.
Restriction:	The DELIMITER= and DSD options have no effect on the ODS option. You cannot use _FILE_=, FILEVAR=, HEADER=, or PAD with the ODS option.