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

FILENAME(fileref <,file-name> <,device-type> <,'host-options'> <,dir-ref> )

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