FILENAME Function

Assigns or deassigns a fileref to an external file, directory, or output device.

Category:	External Files
Restrictions:	If the SAS session in which you are specifying the FILENAME function is in a locked-down state, and the pathname specified in the function has not been added to the lockdown path list, then the function fails and a file access error related to the locked-down data is not generated in the SAS log unless you specify the SYSMSG function.
Restrictions:	This function is not valid on the CAS server.
Note:	You can assign a fileref by using a File Shortcut in the Navigation pane, the FILENAME statement, the FILENAME function, or you can use a Windows environment variable to point to the file.

Table of Contents

Example 1: Assigning a Fileref to an External File

Example 2: Assigning a System-Generated Fileref

Example 3: Assigning a Fileref to a Pipe File

Syntax

FILENAME(fileref, filename <,device-type> <, 'host-options'>
<, directory-reference>);

Required Arguments

fileref

specifies the fileref to assign to the external file. In a DATA step, fileref can be a character expression, a string enclosed in single quotation marks that specifies the fileref, or a DATA step variable whose value contains the fileref. In a macro (for example, in the %SYSFUNC function), fileref is the name of a macro variable (without an ampersand) whose value contains the fileref to assign to the external file. If the function is used within a DATA step, the fileref must be enclosed in single quotation marks. If the function is used in macro code, the fileref must not be enclosed in quotation marks.

Requirement	If fileref is a DATA step variable, its length must be no longer than eight characters.
Tip	If a fileref is a DATA step character variable with a blank value and a maximum length of eight characters, or if a macro variable named in fileref has a null value, then a fileref is generated and assigned to the character variable or macro variable, respectively.

filename

is a character constant, variable, or expression that specifies the external file.

Tip	You can deassign a fileref that was previously assigned by passing a blank value for the filename argument.

Optional Arguments

device-type

is a character constant, variable, or expression that 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.

Alias	BASE
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 is receiving 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 that are manipulated by the TEMP device can have the same attributes and behave identically to DISK files.

TERMINAL

specifies the user's personal computer.

UPRINTER

specifies a Universal Printing printer definition name.

Operating Environment Information: The FILENAME function also supports operating-environment specific devices. For more information, see the SAS documentation for your operating environment.

'host-options'

specifies host-specific details such as file attributes and processing attributes.

directory-reference

specifies the fileref that was assigned to the directory or partitioned data set in which the external file resides.

Details

You can create a fileref with the FILENAME function and FILENAME statement.

FILENAME returns 0 if the operation was successful; ≠0 if it was not successful. The name that is associated with the file or device is called a fileref (file reference name). Other system functions that manipulate external files and directories require that the files be identified by fileref rather than by physical filename. The association between a fileref and a physical file lasts only for the duration of the current SAS session or until you change or discontinue the association by using FILENAME.

You can deassign filerefs by specifying one argument in the FILENAME function, or by passing a blank value for the filename argument.

Operating Environment Information: The term directory in this description refers to an aggregate grouping of files that are managed by the operating environment. Different operating environments identify these groupings with different names, such as directory, subdirectory, folder, MACLIB, or partitioned data set. For details, see the SAS documentation for your operating environment.

Examples

Example 1: Assigning a Fileref to an External File

This example assigns the fileref MYFILE to an external file. Next, it deassigns the fileref. Note that in a macro statement that you do not enclose character strings in quotation marks.

%let filrf=myfile;
%let rc=%sysfunc(filename(filrf, physical-filename));
%if &rc ne 0 %then
   %put %sysfunc(sysmsg());
%let rc=%sysfunc(filename(filrf));

Example 2: Assigning a System-Generated Fileref

This example assigns a system-generated fileref to an external file. The fileref is stored in the variable FNAME. Note that in a macro statement that you do not enclose character strings in quotation marks.

%let rc=%sysfunc(filename(fname, physical-filename));
%if &rc %then
   %put %sysfunc(sysmsg());
%else
   %do;
      ... more macro statements ...
   %end;

Example 3: Assigning a Fileref to a Pipe File

This example assigns the fileref MYPIPE to a pipe file with the output from the UNIX command LS, which lists the files in the directory /u/myid. Note that in a macro statement that you do not enclose character strings in quotation marks.

%let filrf=mypipe;
%let rc=%sysfunc(filename(filrf, %str(ls /u/myid), pipe));

FILENAME Function

Syntax

Required Arguments

fileref

filename

Optional Arguments

device-type

DISK

DUMMY

GTERM

PIPE

PLOTTER

PRINTER

TAPE

TEMP

TERMINAL

UPRINTER

'host-options'

directory-reference

Details

Examples

Example 1: Assigning a Fileref to an External File

Example 2: Assigning a System-Generated Fileref

Example 3: Assigning a Fileref to a Pipe File

See Also