SAS 9.1 Language Reference Dictionary, Volumes 1, 2 and 3

2017-07-07 02:10:07

Associates a SAS fileref with an external file or an output device; disassociates a fileref and external file; lists attributes of external files

Valid: anywhere

Category: Data Access

See: FILENAME Statement in the documentation for your operating environment

Syntax

[ 1]

FILENAME fileref < device-type > external-file <ENCODING= encoding-value >

< options >< operating-environment-options >;

[ 2]

FILENAME fileref < device-type >< options > < operating-environment-options >;

[ 3]

FILENAME fileref CLEAR _ALL_ CLEAR;

[ 4]

FILENAME fileref LIST _ALL_ LIST;

Arguments

fileref

is any SAS name that you use when you assign a new fileref. When you disassociate a currently assigned fileref or when you list file attributes with the FILENAME statement, specify a fileref that was previously assigned with a FILENAME statement or an operating environment-level command.

Tip: The association between a fileref and an external file lasts only for the duration of the SAS session or until you change it or discontinue it by using another FILENAME statement. Change the fileref for a file as often as you want.

external-file

is the physical name of an external file. The physical name is the name that is recognized by the operating environment.

Operating Environment Information: For details about specifying the physical names of external files, see the SAS documentation for your operating environment.

Tip: Specify external-file when you assign a fileref to an external file.

Tip: You can associate a fileref with a single file or with an aggregate file storage location.

ENCODING= encoding-value

specifies the encoding to use when SAS is reading from or writing to an external file. The value for ENCODING= indicates that the external file has a different encoding from the current session encoding.

When you read data from an external file, SAS transcodes the data from the specified encoding to the session encoding. When you write data to an external file, SAS transcodes the data from the session encoding to the specified encoding.

For valid encoding values, see Encoding Values in SAS Language Elements in SAS National Language Support (NLS): User s Guide .

Default: SAS assumes that an external file is in the same encoding as the session encoding.

Featured in: Example 5 on page 1174 and Example 6 on page 1175

device-type

specifies the type of device or the access method that is used if the fileref points to an input or output device or location that is not a physical file:

DISK	specifies that the device is a disk drive. Tip: When you assign a fileref to a file on disk, you are not required to specify DISK.
DUMMY	specifies that the output to the file is discarded. Tip: Specifying DUMMY can be useful for testing.
GTERM	indicates that the output device type is a graphics device that will receive graphics data.
PIPE	specifies an unnamed pipe. Note: Some operating environments do not support pipes.
PLOTTER	specifies an unbuffered graphics output device.
PRINTER	specifies a printer or printer spool file.
TAPE	specifies a tape drive.
TEMP	creates a temporary file that exists only as long as the filename is assigned. The temporary file can be accessed only through the logical name and is available only while the logical name exists. Restriction: Do not specify a physical pathname. If you do, SAS returns an error. Tip: Files manipulated by the TEMP device can have the same attributes and behave identically to DISK files.
TERMINAL	specifies the user s terminal.
UPRINTER	specifies a Universal Printing printer definition name.

Operating Environment Information: Additional specifications might be required when you specify some devices. See the SAS documentation for your operating environment before specifying a value other than DISK. Values in addition to the ones listed here might be available in some operating environments.

CLEAR

disassociates one or more currently assigned filerefs .

Tip: Specify fileref to disassociate a single fileref. Specify _ALL_ to disassociate all currently assigned filerefs.

_ALL_

specifies that the CLEAR or LIST argument applies to all currently assigned filerefs.

LIST

writes the attributes of one or more files to the SAS log.

Interaction: Specify fileref to list the attributes of a single file. Specify _ALL_ to list the attributes of all files that have filerefs in your current session.

Options

RECFM= record-format

specifies the record format of the external file.

Operating Environment Information: Values for record-format are dependent on the operating environment. For details, see the SAS documentation for your operating environment.

Operating Environment Options

Operating environment options specify details, such as file attributes and processing attributes, that are specific to your operating environment.

Operating Environment Information: For a list of valid specifications, see the SAS documentation for your operating environment.

Details

Operating Environment Information

Operating Environment Information: Using the FILENAME statement requires operating environment-specific information. See the SAS documentation for your operating environment before using this statement. Note also that commands are available in some operating environments that associate a fileref with a file and that break that association.

Definitions

external file

is a file that is created and maintained in the operating environment from which you need to read data, SAS programming statements, or autocall macros, or to which you want to write output. An external file can be a single file or an aggregate storage location that contains many individual external files. See Example 3 on page 1173.

Operating Environment Information: Different operating environments call an aggregate grouping of files by different names, such as a directory, a MACLIB, or a partitioned data set. For details about specifying external files, see the SAS documentation for your operating environment.

fileref

(a file reference name) is a shorthand reference to an external file. After you associate a fileref with an external file, you can use it as a shorthand reference for that file in SAS programming statements (such as INFILE, FILE, and %INCLUDE) and in other commands and statements in SAS software that access external files.

[ 1]

Associating a Fileref with an External File Use this form of the FILENAME statement to associate a fileref with an external file on disk:

FILENAME fileref external-file < operating-environment-options >;

To associate a fileref with a file other than a disk file, you might need to specify a device type, depending on your operating environment, as shown in this form:

FILENAME fileref < device-type >< operating-environment-options >;

The association between a fileref and an external file lasts only for the duration of the SAS session or until you change it or discontinue it with another FILENAME statement. Change the fileref for a file as often as you want.

To specify a character-set encoding, use the following form:

FILENAME fileref < device-type >< operating-environment-options >;

[ 2]	Associating a Fileref with a Terminal, Printer, Universal Printer, or Plotter To associate a fileref with an output device, use this form: FILENAME fileref device-type < operating-environment-options >;

[ 3]

Disassociating a Fileref from an External File To disassociate a fileref from a file, use a FILENAME statement, specifying the fileref and the CLEAR option.

[ 4]

Writing File Attributes to the SAS Log Use a FILENAME statement to write the attributes of one or more external files to the SAS log. Specify fileref to list the attributes of one file; use _ALL_ to list the attributes of all the files that have been assigned filerefs in your current SAS session.

FILENAME fileref LIST _ALL_ LIST;

Comparisons

The FILENAME statement assigns a fileref to an external file. The LIBNAME statement assigns a libref to a SAS data set or to a DBMS file that can be accessed like a SAS data set.

Examples

Example 1: Specifying a Fileref or a Physical Filename

You can specify an external file either by associating a fileref with the file and then specifying the fileref or by specifying the physical filename in quotation marks:

filename sales ' your-input-file '; data jansales; /* specifying a fileref */ infile sales; input salesrep . +6 jansales febsales marsales; run; data jansales; /* physical filename in quotation marks */ infile ' your-input-file '; input salesrep . +6 jansales febsales marsales; run;

Example 2: Using a FILENAME and a LIBNAME Statement

This example reads data from a file that has been associated with the fileref GREEN and creates a permanent SAS data set stored in a SAS data library that has been associated with the libref SAVE.

filename green ' your-input-file '; libname save ' SAS-data-library '; data save.vegetable; infile green; input lettuce cabbage broccoli; run;

Example 3: Associating a Fileref with an Aggregate Storage Location

If you associate a fileref with an aggregate storage location, use the fileref, followed in parentheses by an individual filename, to read from or write to any of the individual external files that are stored there.

Operating Environment Information: Some operating environments allow you to read from but not write to members of aggregate storage locations. For details, see the SAS documentation for your operating environment.

In this example, each DATA step reads from an external file (REGION1 and REGION2, respectively) that is stored in the same aggregate storage location and that is referenced by the fileref SALES.

filename sales ' aggregate-storage-location '; data total1; infile sales(region1); input machine $ jansales febsales marsales; totsale=jansales+febsales+marsales; run; data total2; infile sales(region2); input machine $ jansales febsales marsales; totsale=jansales+febsales+marsales; run;

Example 4: Routing PUT Statement Output

In this example, the FILENAME statement associates the fileref OUT with a printer that is specified with an operating environment-dependent option. The FILE statement directs PUT statement output to that printer.

filename out printer operating-environment-option ; data sales; file out print; input salesrep . +6 jansales febsales marsales; put _infile_; datalines; Jones, E. A. 124357 155321 167895 Lee, C. R. 111245 127564 143255 Desmond, R. T. 97631 101345 117865 ;

You can use the FILENAME and FILE statements to route PUT statement output to several different devices during the same session. To route PUT statement output to your display monitor, use the TERMINAL option in the FILENAME statement, as shown here:

filename show terminal; data sales; file show; input salesrep . +6 jansales febsales marsales; put _infile_; datalines; Jones, E. A. 124357 155321 167895 Lee, C. R. 111245 127564 143255 Desmond, R. T. 97631 101345 117865 ;

Example 5: Specifying an Encoding When Reading an External File

This example creates a SAS data set from an external file. The external file is in UTF-8 character-set encoding, and the current SAS session is in the Wlatin1 encoding. By default, SAS assumes that an external file is in the same encoding as the session encoding, which causes the character data to be written to the new SAS data set incorrectly.

To tell SAS what encoding to use when reading the external file, specify the ENCODING= option. When you tell SAS that the external file is in UTF-8, SAS then transcodes the external file from UTF-8 to the current session encoding when writing to the new SAS data set. Therefore, the data is written to the new data set correctly in Wlatin1.

libname myfiles ' SAS-data-library '; filename extfile ' external-file ' encoding="utf-8" ; data myfiles.unicode; infile extfile; input Make $ Model $ Year; run;

Example 6: Specifying an Encoding When Writing to an External File

This example creates an external file from a SAS data set. The current session encoding is Wlatin1, but the external file s encoding needs to be UTF-8. By default, SAS writes the external file using the current session encoding.

To tell SAS what encoding to use when writing data to the external file, specify the ENCODING= option. When you tell SAS that the external file is to be in UTF-8 encoding, SAS then transcodes the data from Wlatin1 to the specified UTF-8 encoding when writing to the external file.

libname myfiles ' SAS-data-library '; filename outfile ' external-file ' encoding="utf-8" ; data _null_; set myfiles.cars; file outfile; put Make Model Year; run;