FILENAME Function

Assigns or deassigns a fileref to an external file, directory, or output device.
Category: External Files
See: FILENAME Function: Windows in SAS Companion for Windows

FILENAME Function: UNIX in SAS Companion for UNIX Environments

FILENAME Function: z/OS in SAS Companion for z/OS

Syntax

Required Argument

fileref
specifies the fileref to assign to the external file. In a DATA step, fileref can be a character expression, a string enclosed in 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.
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.

Optional Arguments

file-name
is a character constant, variable, or expression that specifies the external file. Specifying a blank file-name deassigns a fileref that was assigned previously.
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 will be 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: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. For more information, see the SAS documentation for your operating environment.
dir-ref
specifies the fileref that was assigned to the directory or partitioned data set in which the external file resides.

Details

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 a null string for the file-name argument in FILENAME.
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.
Under some operating environments, you can also assign filerefs by using system commands. Depending on the operating environment, FILENAME might be unable to change or deassign filerefs that are assigned outside of SAS.

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));