SAS Companion for UNIX Environments

Assigning Filerefs with the FILENAME Statement

The most common way to assign a fileref to an external file or device is with the FILENAME statement. There are several forms of the FILENAME statement, depending on the type of device you want to access.

FILENAME fileref <device-type> 'external-file' <host-options>;

FILENAME fileref device-type <'external-file'><host-options>;

FILENAME fileref CLEAR | _ALL_ CLEAR;

FILENAME fileref LIST | _ALL_ LIST;

FILENAME fileref ("pathname-1" ... "pathname-n");

FILENAME fileref directory-name;

FILENAME fileref <access-method> 'external-file' access-information;

fileref

is the name by which you reference the file.

device-type

specifies a device, such as a disk, terminal, printer, pipe, and so on. The device-type keyword must follow fileref and precede pathname. Device Information in the FILENAME Statement describes the valid device types. DISK is the default device type.

'external-file'

differs according to device type. Device Information in the FILENAME Statement shows the information appropriate to each device. Remember that UNIX filenames are case-sensitive. See Specifying Pathnames for more information.

"pathname-n"

are pathnames for the files that you want to access with the same fileref. Use this form of the FILENAME statement when you want to concatenate filenames. Concatenating filenames is available only for DISK files, so you do not have to specify the device-type. Separate the pathnames with either commas or blank spaces. Enclose each pathname in quotes. Character Substitutions in Pathnames shows character substitutions you can use when specifying a pathname. If the fileref that you are defining is to be used for input, then you can also use wildcards as described in Using Wildcards in Pathnames (Input Only). Remember that UNIX filenames are case-sensitive.

directory-name

specifies the directory that contains the files that you want to access. For more information, see Assigning a Fileref to a Directory (Using Aggregate Syntax).

host-options

control how the external file is processed. See FILENAME for an explanation of these options.

access-method

can be CATALOG, SOCKET, FTP, or URL. Device Information in the FILENAME Statement describes the information expected by these access methods.

access-information

differs according to the access method. Device Information in the FILENAME Statement shows the information appropriate to each access method.

_ALL_

refers to all filerefs currently defined. You can use this keyword when you are listing or clearing filerefs.

CLEAR

clears the specified fileref or, if you specify _ALL_, clears all filerefs that are currently defined.

Note: When you clear a fileref that is defined by an environment variable, the variable remains defined but is no longer considered a fileref. You can still reuse it, either as a fileref or a libref. See Using Environment Variables to Assign Filerefs for more information. [cautionend]

LIST

prints to the SAS log the pathname of the specified fileref or, if you specify _ALL_, lists the definition for all filerefs that are currently defined. Filerefs defined as environment variables appear only if you have already used those filerefs in a SAS statement. If you are using the Bourne shell or the Korn shell, the SAS System cannot determine the name of a preopened file, so it displays the following string instead of a filename:

<File Descriptor number>

See Using Environment Variables to Assign Filerefs for more information.

Device Information in the FILENAME Statement
Device or Access Method Function External-file

CATALOG references a SAS catalog as a flat file. is a valid two-, three-, or four-part SAS catalog name followed by catalog options needed. Refer to SAS Language Reference: Dictionary for a description of catalog options.

DISK associates the fileref with a DISK file. is either the pathname for a single file, or if you are concatenating filenames, a list of pathnames separated by blanks or commas and enclosed in parentheses. The level of specification depends on your location in the file system. Character Substitutions in Pathnames shows character substitutions that you can use when specifying a UNIX pathname. See Using DISK Files for more information.

DUMMY associates a fileref with a null device. none. See Debugging Code With DUMMY Devices for more information.

EMAIL sends electronic mail to an address. is an address and email options. See Sending Electronic Mail from Within the SAS System (EMAIL) for more information.

FTP reads or writes to a file from any machine on a network that is running an FTP server. is the pathname of the external file on the remote machine followed by FTP options. See Assigning Filerefs to Files on Other Systems (FTP and SOCKET access types) and SAS Language Reference: Dictionary for more information. If you are transferring a file from the OS/390 operating environment and you want to access the file by using one of the S370 formats, the file must be of type RECFM=U before you transfer it to UNIX.

PIPE reads input from or writes output to a UNIX command. is a UNIX command. See Reading from and Writing to UNIX Commands (PIPE) and Routing Output for details.

PLOTTER sends output to a plotter. is a device name and plotter options. See Using PRTFILE and PRINT with a Filerefand Using the PRINTTO Procedure for details.

PRINTER sends output to a printer. is a device name and printer options. See Sending Output to PRINTER Devices, Using PRTFILE and PRINT with a Fileref, and Using the PRINTTO Procedure for details.

SOCKET reads and writes information over a TCP/IP socket. depends on whether the SAS application is a server application or a client application. In a client application, external-file is the name or IP address of the host and the TCP/IP port number to connect to followed by any TCP/IP options. In a server application, it is the port number to create for listening, followed by the SERVER keyword, and then any TCP/IP options. See Assigning Filerefs to Files on Other Systems (FTP and SOCKET access types) and SAS Language Reference: Dictionary for details.

TAPE associates a fileref with a tape. is the pathname for a tape device. The name specified should be the name of the special file associated with the tape device. See Processing Files on TAPE for more information.

TEMP associates a fileref with an external file stored in the WORK data library. none. See Using Temporary Files (TEMP Device Type) for more information.

TERMINAL associates a fileref with a terminal. is the pathname of a terminal. See Accessing TERMINAL Devices Directly for more information.

URL allows you to access remote files using the URL of the file. is the name of the file that you want to read from or write to on a URL server. The URL must be in one of these forms:
http://hostname/file http://hostname:portno/file
Refer to SAS Language Reference: Dictionary for more information.

XPRINTER sends output to the default printer that was set up through the Printer Setup dialog. none. See Routing Output for more information.

***Device Information in the FILENAME Statement***
Device or Access Method	Function	External-file
CATALOG	references a SAS catalog as a flat file.	is a valid two-, three-, or four-part SAS catalog name followed by catalog options needed. Refer to SAS Language Reference: Dictionary for a description of catalog options.
DISK	associates the fileref with a DISK file.	is either the pathname for a single file, or if you are concatenating filenames, a list of pathnames separated by blanks or commas and enclosed in parentheses. The level of specification depends on your location in the file system. Character Substitutions in Pathnames shows character substitutions that you can use when specifying a UNIX pathname. See Using DISK Files for more information.
DUMMY	associates a fileref with a null device.	none. See Debugging Code With DUMMY Devices for more information.
EMAIL	sends electronic mail to an address.	is an address and email options. See Sending Electronic Mail from Within the SAS System (EMAIL) for more information.
FTP	reads or writes to a file from any machine on a network that is running an FTP server.	is the pathname of the external file on the remote machine followed by FTP options. See Assigning Filerefs to Files on Other Systems (FTP and SOCKET access types) and SAS Language Reference: Dictionary for more information. If you are transferring a file from the OS/390 operating environment and you want to access the file by using one of the S370 formats, the file must be of type RECFM=U before you transfer it to UNIX.
PIPE	reads input from or writes output to a UNIX command.	is a UNIX command. See Reading from and Writing to UNIX Commands (PIPE) and Routing Output for details.
PLOTTER	sends output to a plotter.	is a device name and plotter options. See Using PRTFILE and PRINT with a Filerefand Using the PRINTTO Procedure for details.
PRINTER	sends output to a printer.	is a device name and printer options. See Sending Output to PRINTER Devices, Using PRTFILE and PRINT with a Fileref, and Using the PRINTTO Procedure for details.
SOCKET	reads and writes information over a TCP/IP socket.	depends on whether the SAS application is a server application or a client application. In a client application, external-file is the name or IP address of the host and the TCP/IP port number to connect to followed by any TCP/IP options. In a server application, it is the port number to create for listening, followed by the SERVER keyword, and then any TCP/IP options. See Assigning Filerefs to Files on Other Systems (FTP and SOCKET access types) and SAS Language Reference: Dictionary for details.
TAPE	associates a fileref with a tape.	is the pathname for a tape device. The name specified should be the name of the special file associated with the tape device. See Processing Files on TAPE for more information.
TEMP	associates a fileref with an external file stored in the WORK data library.	none. See Using Temporary Files (TEMP Device Type) for more information.
TERMINAL	associates a fileref with a terminal.	is the pathname of a terminal. See Accessing TERMINAL Devices Directly for more information.
URL	allows you to access remote files using the URL of the file.	is the name of the file that you want to read from or write to on a URL server. The URL must be in one of these forms: http://hostname/file http://hostname:portno/file Refer to SAS Language Reference: Dictionary for more information.
XPRINTER	sends output to the default printer that was set up through the Printer Setup dialog.	none. See Routing Output for more information.

Using DISK Files

The most common use of the FILENAME statement is to access DISK files. The FILENAME syntax for a DISK file is

FILENAME fileref <DISK> 'pathname' <options>;

The following FILENAME statement associates the fileref MYFILE with the external file /users/mydir/myfile, which is stored on a disk device:

filename myfile disk '/users/mydir/myfile';

The following FILENAME statement assigns a fileref of PRICES to the file /users/pat/cars. The FILE statement then refers to the file using the fileref:

filename prices '/users/pat/cars';
data current.list;
   file prices;
   ...PUT statements...
run;

See Concatenating Filenames for more information on using DISK files.

Debugging Code With DUMMY Devices

You can substitute the DUMMY device type for any of the other device types. This device type serves as a tool for debugging your SAS code without actually reading or writing to the device. After debugging is complete, replace the DUMMY device name with the proper device type, and your program will access the specified device type.

The FILENAME syntax for a DUMMY file is

FILENAME fileref DUMMY 'pathname'<options>;

Output to DUMMY devices is discarded.

Sending Output to PRINTER Devices

The PRINTER device type allows you to send output directly to a printer. The FILENAME syntax to direct a file to a PRINTER is

FILENAME fileref PRINTER '<printer> <printer-options>' <options>;

For example, this SAS program sends the output file to the BLDG3 printer:

filename myfile printer 'bldg3';

data test;
   file myfile;
   put 'This will appear in bldg3 .';
run;

See Using PRTFILE and PRINT with a Fileref and Using the PRINTTO Procedure for more information.

Using Temporary Files (TEMP Device Type)

The TEMP device type associates a fileref with a temporary file stored in the same directory as the WORK data library. (See WORK Data Library.) Using the TEMP device type enables you to create a file that lasts only as long as the SAS session.

The FILENAME syntax for a TEMP file is

FILENAME fileref TEMP <options>;

For example, this FILENAME statement associates TMP1 with a temporary file:

filename tmp1 temp;

Accessing TERMINAL Devices Directly

To access a terminal directly, use the TERMINAL device type. The FILENAME syntax to associate a file with a terminal is

FILENAME fileref TERMINAL <'terminal-pathname'> <options>;

The terminal-pathname must be a pathname of the special file associated with the terminal. Check with your system administrator for details. Enclose the name in quotes. If you omit the terminal pathname, the fileref is assigned to your terminal.

For example, this FILENAME statement associates the fileref HERE with your terminal:

filename here terminal;

The following FILENAME statement associates the fileref THATFILE with another terminal:

filename thatfile terminal '/dev/tty3';

Assigning Filerefs to Files on Other Systems (FTP and SOCKET access types)

You can access files on other systems in your network by using the SOCKET and FTP access methods. The forms of the FILENAME statement are

FILENAME fileref FTP 'external-file' <ftp-options>;

FILENAME fileref SOCKET 'external-file' <tcpip-options>;

FILENAME fileref SOCKET ':portno' SERVER <tcpip-options>;

These access methods are documented in SAS Language Reference: Dictionary. Under UNIX, the FTP access method supports an additional option:

MACH='machine': identifies which entry in the .netrc file should be used to get the username and password. Consult the UNIX man page for more information on the .netrc file. You cannot specify the MACH option together with the HOST option in the FILENAME statement.

The file that you want to transfer must be of type RECFM=U before you transfer it to UNIX.

CAUTION:: When you use the FTP access method to create a remote file, the UNIX permissions for that file are set to -rw-rw-rw-, which makes the file world-readable and world-writeable. See the man page for chmod for information on changing file permissions.

Chapter Contents
Previous
Next
Top of Page