Chapter Contents

Previous

Next
FILENAME

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
[ne]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. Specifying a blank filename deassigns one that was previously assigned.

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

PIPE
an unnamed pipe

Note:    Some host 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. You can de-assign filerefs by specifying a null string for the filename argument in FILENAME.

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 host operating system 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');

See Also

FEXIST

FILEEXIST

FILEREF

PATHNAME


Chapter Contents

Previous

Next

Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.