Previous Page | Next Page

Statements

FILENAME Statement


Associates a SAS fileref with an external file or an output device, disassociates a fileref and external file, or lists attributes of external files.
Valid: anywhere
Category: Data Access
See: FILENAME Statement under Windows UNIX OpenVMS z/OS
Syntax
Arguments
Options
Operating Environment Options
Details
Operating Environment Information
Definitions
Reading Delimited Data from an External File
[1]Associating a Fileref with an External File
[2]Associating a Fileref with a Terminal, Printer, Universal Printer, or Plotter
[3]Disassociating a Fileref from an External File
[4]Writing File Attributes to the SAS Log
Comparisons
Examples
Example 1: Specifying a Fileref or a Physical Filename
Example 2: Using a FILENAME and a LIBNAME Statement
Example 3: Associating a Fileref with an Aggregate Storage Location
Example 4: Routing PUT Statement Output
Example 5: Specifying an Encoding When Reading an External File
Example 6: Specifying an Encoding When Writing to an External File
See Also

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.  [cautionend]

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): Reference Guide.

Default: SAS assumes that an external file is in the same encoding as the session encoding.
Featured in: Specifying an Encoding When Reading an External File and Specifying an Encoding When Writing to an External File
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.  [cautionend]

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.

Tip: If you do not specify the printer name in the FILENAME statement, the PRINTERPATH options control which Universal Printer is used and the destination of the output.

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.  [cautionend]

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.  [cautionend]

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.  [cautionend]

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.   [cautionend]


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 Associating a Fileref with an Aggregate Storage Location.

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.  [cautionend]

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.


Reading Delimited Data from an External File

Any time a text file originates from anywhere other than the local encoding environment, it might be necessary to specify the ENCODING= option in either EBCDIC or ASCII environments.

For example, when you read an EBCDIC text file on an ASCII platform, it is recommended that you specify the ENCODING= option in the FILENAME statement. However, if you use the DSD and DLM options in the FILENAME statement, the ENCODING= option is a requirement because these options require certain characters in the session encoding (such as quotation marks, commas, and blanks).

The use of encoding-specific informats should be reserved for use with true binary files. That is, they contain both character and non-character fields.


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

Syntax

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:

Syntax

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:

Syntax

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:

Syntax

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.

Syntax

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 $20. +6 jansales febsales
            marsales;
   run;

   data jansales;
         /* physical filename in quotation marks */
      infile 'your-input-file';
      input salesrep $20. +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 library that has been associated with the libref SAVE.

   filename green 'your-input-file';
   libname save 'SAS-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.  [cautionend]

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 $20. +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 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 $20. +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-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-library'; 

filename outfile 'external-file' encoding="utf-8";                                                                                             

data _null_; 
   set myfiles.cars;                                                                                                                          
   file outfile;                                                                                                     
   put Make Model Year;                                                                                                           
run;

See Also

Statements:

FILE Statement

%INCLUDE Statement

INFILE Statement

FILENAME Statement, CATALOG Access Method

FILENAME Statement, EMAIL (SMTP) Access Method

FILENAME Statement, FTP Access Method

FILENAME Statement, SOCKET Access Method

FILENAME Statement, SFTP Access Method

FILENAME Statement, URL Access Method

LIBNAME Statement

SAS Windowing Interface Commands:

FILE and INCLUDE

Previous Page | Next Page | Top of Page

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