SAS Component Language Dictionary

FILENAME

Assigns or deassigns a fileref for an external file, a directory, an output device, or a catalog entry

Category:

External File

Syntax
Details
Examples
	Example 1: Assigning a Fileref
	Example 2: Using a System-Generated Fileref
	Example 3: Making an External File Accessible to a Client
	Example 4: Assigning a Fileref for a Pipe File
See Also

Syntax

sysrc=FILENAME(fileref,filename<,device <,host-options<,dir-ref>>>);

sysrc

contains the return code for the operation:

0	successful
0	not successful

Type: Numeric

fileref

is the fileref to assign. A blank fileref ('') causes an error condition. If the fileref is an SCL character variable that has a blank value, a fileref will be generated for you.

Type: Character

filename

is the physical name of an external file.

Type: Character

device

is the type of device if the fileref points to something other than a physical file:

CATALOG

a catalog entry

DUMMY

output to the file is discarded

FTP

the file transfer protocol (FTP) access method

GTERM

graphics on the user's terminal

NAMEPIPE

a named pipe.

Note: Some operating systems do not support pipes. [cautionend]

PIPE

an unnamed pipe

Note: Some operating systems do not support pipes. [cautionend]

PLOTTER

an unbuffered graphics output device

PRINTER

a printer or printer spool file

SOCKET

the Transmission Control Protocol/Internet Protocol (TCP/IP) socket access method

TERMINAL

the user's terminal

TAPE

a tape drive

URL

the URL access method

Type: Character

host-options

are host-specific details such as file attributes and processing attributes. Host-options can also be used to specify device options. For example, they could include output destinations, and CATALOG, FTP, URL, TCPIP, and SOCKET options. For details about host and device options for the FILENAME statement, see SAS Language Reference: Dictionary and the SAS documentation for your operating environment.

Type: Character

dir-ref

is the fileref assigned to the directory or partitioned data set in which the external file resides.

Type: Character

Details

The name associated with the file or device is called a fileref (file reference name). Other SCL functions that manipulate external files and directories require that the files be identified by a fileref rather than by a physical filename. A system-generated fileref is not displayed in the FILENAME window.

The association between a fileref and a physical file lasts only for the duration of the current SAS session or until you use FILENAME to change or discontinue the association. If you specified the RECONN option when the fileref was assigned, then you must specify the CLEAR option to deassign the fileref. You can deassign other filerefs by specifying a null string for the filename argument.

For more information about the arguments that you can use with FILENAME, see SAS Language Reference: Dictionary and the SAS documentation for your operating environment.

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

Under some operating systems, you can also use system commands to assign filerefs. Depending on the operating system, FILENAME may be unable to change or de-assign filerefs that are assigned outside of a SAS session.

See the SAS documentation for your operating environment for information about the system-dependent options that you can specify for options. [cautionend]

Examples

Example 1: Assigning a Fileref

Assign the fileref MYFILE to an external file:

   /* Assign fileref MYFILE to the physical */
   /* filename stored in the variable FNAME   */
rc=filename('myfile',fname);
if (rc ne 0) then
   _msg_=sysmsg();

Example 2: Using a System-Generated Fileref

Assign a system-generated fileref, stored in the variable FNAME, to the file whose physical name is in the control FNAME:

fname=' ';
   /* Assign a system-generated fileref to the */
   /* filename stored in the variable FNAME      */
rc=filename(fname,fname);
if (rc) then
   _msg_=sysmsg();
else
   do;
      ...more SCL statements...
   end;
    /* De-assign the fileref */
rc=filename('myfile','');

Example 3: Making an External File Accessible to a Client

Assign a fileref to an external file:

rc=filename('sharedfl','\ABC\XYZ\AUTOEXEC.SAS);

Example 4: Assigning a Fileref for a Pipe File

Assign a fileref for a pipe file with the output from the UNIX command LS, which lists the files in the directory /u/myid:

rc=filename('myfile','ls /u/myid','pipe');