FILENAME Statement: UNIX

Associates a SAS fileref with an external file or output device; disassociates a fileref and external file; lists attributes of external files.
Valid in: anywhere
UNIX specifics: device-type, external-file, host-options, and encoding-value
See: FILENAME Statement in SAS Statements: Reference
Syntax
Details
File Locking
Device Information in the FILENAME Statement
See Also

Syntax

FILENAME fileref <device-type> 'external-file' <ENCODING='encoding-value'>
<'host-options'> <LOCKINTERNAL= AUTO | SHARED> ;
FILENAME fileref device-type <'external-file'> <ENCODING='encoding-value'>
<'host-options'> <LOCKINTERNAL= AUTO | SHARED> ;
FILENAME fileref ('pathname-1' ... 'pathname-n') <ENCODING='encoding-value'>
<'host-options'> <LOCKINTERNAL= AUTO | SHARED> ;
FILENAME fileref directory-name <ENCODING='encoding-value'>
<LOCKINTERNAL= AUTO | SHARED> ;
FILENAME fileref <access-method> 'external-file' access-information;
FILENAME fileref CLEAR | _ALL_ CLEAR;
FILENAME fileref LIST | _ALL_ LIST;

Required Arguments

fileref
is the name by which you reference the file. Under UNIX, the value of fileref can be an environment variable.
Note: You cannot clear a fileref that is defined by an environment variable. Filerefs that are defined by an environment variable are assigned for the entire SAS session.
For more information, see Using Environment Variables to Assign Filerefs in UNIX Environments.
'external-file'
differs according to device type. Device Information in the FILENAME Statement shows the information appropriate to each device. Remember that UNIX filenames are case sensitive. For more information, see Specifying Pathnames in UNIX Environments.
Note: If a filename has leading blanks, then the blanks will be trimmed.

Optional Arguments

device-type
specifies a device for the output, such as a disk, terminal, printer, pipe, and so on. The device-type keyword must follow fileref and precede pathname. Device Information in the FILENAME Statement describes the valid device types. DISK is the default device type. If you are associating the fileref with a DISK file, then you do not need to specify the device type.
ENCODING='encoding-value'
specifies the encoding to use when reading from or writing to the external file. The value for ENCODING= indicates that the external file has a different encoding from the current session encoding.
When you read data from an external file, SAS transcodes the data from the specified encoding to the session encoding. When you write data to an external file, SAS transcodes the data from the session encoding to the specified encoding.
Note: The UPRINTER device type does not support the ENCODING option.
For valid encoding values, see Overview to SAS Language Elements That Use Encoding Values in SAS National Language Support (NLS): Reference Guide.
'host-options'
are specific to UNIX environments. These options can be any of the following:
BLKSIZE=
BLK=
specifies the number of bytes that are physically written or read in one I/O operation. The default is 8K. The maximum is 1G–1. If you specify RECFM=S370VBS, then you should specify BLKSIZE=32760 in order to avoid errors with records longer than 255 characters.
TERMSTR=
controls the end of line and record delimiters in files formatted by UNIX or the PC. This option enables the sharing of these formatted files between the two hosts. The following values for the TERMSTR= option are valid:
CR Carriage return. Use TERMSTR=CR to read files formatted by an Apple Macintosh.
CRLF Carriage return line feed. Use TERMSTR=CRLF to read files formatted by a PC.
LF Line feed. This parameter is used to read files formatted by UNIX. LF is the default.
If you are working on UNIX and reading a file that was created on a PC, specify TERMSTR=CRLF unless the file was created with the TERMSTR=LF option. If you are writing a file that will be read on a PC, specify TERMSTR=CRLF.
If you are working on a PC and reading a file that was created on UNIX, specify TERMSTR=LF unless the file was created with the TERMSTR=CRLF option.
If you are writing a file that will be read on UNIX, specify TERMSTR=LF.
LRECL=
specifies the logical record length. Its meaning depends on the record format in effect (RECFM). The default is 256. The maximum length is 1G.
  • If RECFM=F, then the value for the LRECL= option determines either the number of bytes to be read as one record or the length of each output record. The output record is truncated or padded with blanks to fit the specified size.
  • If RECFM=N, then the value for the LRECL= option must be at least 256.
  • If RECFM=V, then the value for the LRECL= option determines the maximum record length. Records that are longer than the specified length are divided into multiple records on output and truncated on input.
  • If RECFM=S370VBS, then you should specify LRECL=32760 in order to avoid errors with records longer than 255 characters.
MOD
indicates that data written to the file should be appended to the file.
NEW | OLD
specifies whether a new or existing file will be used for output. If you specify NEW, a new file is to be opened for output. If the file already exists, it is deleted and re-created. If you specify OLD, the previous contents of the file are replaced. NEW is the default.
RECFM=
specifies the record format. Values for the RECFM= option are the following:
D default format (same as variable).
F fixed format. That is, each record has the same length. Do not use RECFM=F for external files that contain carriage-control characters.
N binary format. The file consists of a stream of bytes with no record boundaries. N is not valid for the PIPE device type. If you do not specify the LRECL option, then by default SAS reads 256 bytes at a time from the file.
P print format. On output, SAS writes carriage-control characters.
V variable format. Each record ends with a newline character.
S370V variable S370 record format (V).
S370VB variable block S370 record format (VB).
S370VBS variable block with spanned records S370 record format (VBS). If you specify RECFM=S3270VBS, then you should specify BLKSIZE=32760 and LRECL=32760 in order to avoid errors with records longer than 255 characters.
The RECFM= option is used for both input and output.
LOCKINTERNAL=AUTO | SHARED
specifies the SAS system locking that is to be used for the files that are listed in a FILENAME statement. LOCKINTERNAL can have one of the following values:
AUTO
locks a file so that in a SAS session, if a user has Write access to a file, then no other users can have Read or Write access to the file. If a user has Read access to a file, no other user can have Write access to the file, but multiple users can have Read access.
SHARED
locks a file so that in a SAS session, two users do not have simultaneous Write access to the file. The file can be shared simultaneously by one user who has Write access and multiple users who have Read access.
Default:AUTO
UNBUF
tells SAS not to perform buffered Writes to the file on any subsequent FILE statement. This option applies especially when you are reading from or writing to a data collection device. As explained in SAS Statements: Reference, it also prevents buffered Reads on INFILE statements.
'pathname-1'...'pathname-n'
are pathnames for the files that you want to access with the same fileref. Use this form of the FILENAME statement when you want to concatenate filenames. Concatenation of filenames is available only for DISK files, so you do not have to specify the device-type. Separate the pathnames with either commas or blank spaces. Enclose each pathname in quotation marks. Character Substitutions in Pathnames shows character substitutions that you can use when specifying a pathname. If the fileref that you are defining is to be used for input, then you can also use wildcards as described in Using Wildcards in Pathnames (Input Only). Remember that UNIX filenames are case-sensitive.
directory-name
specifies the directory that contains the files that you want to access. For more information, see Assigning a Fileref to a Directory (Using Aggregate Syntax).
access-method
can be CATALOG, SOCKET, FTP, SFTP, or URL. Device Information in the FILENAME Statement describes the information expected by these access methods.
access-information
differs according to the access method. Device Information in the FILENAME Statement shows the information appropriate to each access method.
CLEAR
clears the specified fileref or, if you specify _ALL_, clears all filerefs that are currently defined.
Note: You cannot clear a fileref that is defined by an environment variable. Filerefs that are defined by environment variables are assigned for the entire SAS session.
_ALL_
refers to all filerefs currently defined. You can use this keyword when you are listing or clearing filerefs.
LIST
writes to the SAS log the pathname of the specified fileref or, if you specify _ALL_, lists the definition for all filerefs that are currently defined. Filerefs defined as environment variables appear only if you have already used those filerefs in a SAS statement. If you are using the Bourne shell or the Korn shell, SAS cannot determine the name of a pre-opened file, so it displays the following string instead of a filename: 
<File Descriptor number>
For more information, see Using Environment Variables to Assign Filerefs in UNIX Environments.

Details

File Locking

File locking of external files is controlled at the FILENAME statement level by the LOCKINTERNAL option. If you use the AUTO (default) value for LOCKINTERNAL, then SAS locks a file exclusively for one user who has Write access, or SAS locks a file non-exclusively for multiple users who have Read access. For example, if a file is opened in UPDATE or OUTPUT mode, then all other access from internal processes will be blocked. If a file is opened in INPUT mode, then multiple users can read the file, but UPDATE and OUTPUT functions are blocked.
If you use the SHARED value for LOCKINTERNAL, then SAS allows one user Write access to a file as well as allowing multiple users to read the file.

Device Information in the FILENAME Statement

The following table lists the relationship between device type or access method and the related external file.
Device Information in the FILENAME Statement
Device or Access Method
Function
External File
CATALOG
references a SAS catalog as an external file.
is a valid two-, three-, or four-part SAS catalog name followed by catalog options (if needed). See SAS Language Reference: Concepts for more information.
DISK
associates the fileref with a DISK file.
is either the pathname for a single file or, if you are concatenating filenames, a list of pathnames separated by spaces or commas and enclosed in parentheses. The level of specification depends on your location in the file system. Character Substitutions in Pathnames shows character substitutions that you can use when specifying a UNIX pathname.
DUMMY
associates a fileref with a null device.
None. DUMMY enables you to debug your application without reading from or writing to a device. Output to this device is discarded.
EMAIL
sends electronic mail to an address.
is an address and e-mail options. For more information, see Sending Electronic Mail Using the FILENAME Statement (EMAIL).
FTP
reads from or writes to a file from any computer on a network that is running an FTP server.
is the pathname of the external file on the remote computer followed by FTP options. See SAS Language Reference: Concepts, and Assigning Filerefs to Files on Other Systems (FTP, SFTP, and SOCKET Access Types) for more information.
If you are transferring a file to UNIX from the z/OS operating environment and you want to use either the S370V or S370VB format to access that file, then the file must be of type RECFM=U and BLKSIZE=32760 before you transfer it. If you FTP to a z/OS computer, only one member of a z/OS PDS can be written to at a time. If you need to write to multiple members at the same time, a z/OS PDSE or a UNIX System Services directory should be used.
PIPE
reads input from or writes output to a UNIX command.
is a UNIX command. For more information, see Printing and Routing Output.
PLOTTER
sends output to a plotter.
is a device name and plotter options. For more information, see Printing the Contents of a Window, and Using the PRINTTO Procedure in UNIX Environments.
PRINTER
sends output to a printer.
is a device name and printer option. For more information, see Printing the Contents of a Window, and Using the PRINTTO Procedure in UNIX Environments.
SFTP
reads from or writes to a file from any host computer that you can connect to on a network with an SSHD server running.
is the pathname of the external file on the remote computer, followed by SFTP options. For more information, see FILENAME Statement, SFTP Access Method in SAS Statements: Reference, and Assigning Filerefs to Files on Other Systems (FTP, SFTP, and SOCKET Access Types).
SOCKET
reads and writes information over a TCP/IP socket.
depends on whether the SAS application is a server application or a client application. In a client application, external-file is the name or IP address of the host and the TCP/IP port number to connect to, followed by any TCP/IP options. In a server application, external-file is the port number to create for listening, followed by the SERVER keyword, and then any TCP/IP options. See SAS Statements: Reference for more information.
TEMP
associates a fileref with an external file stored in the Work library.
None
TERMINAL
associates a fileref with a terminal.
is the pathname of a terminal.
UPRINTER
sends output to the default printer that was set up through the Printer Setup dialog box.
None
URL
enables you to use the URL of a file to access it remotely.
is the name of the file that you want to read from or write to on a URL server. The URL must be in one of these forms: 
http://hostname/file
http://hostname:portno/file
WebDAV
enables you to use WebDAV (Web Distributed Authoring and Versioning) to read from or write to a file from any host machine that you can connect to on a network with a WebDAV server running.
is the name of the file that you want to read from or write to a WebDAV server. The external file must be in one of these forms: 
http://hostname/path-to-the-file
https://hostname/path-to-the-file 
http://hostname:port/path-to-the-file
https://hostname:port/path-to-the-file

See Also

Using External Files and Devices
Printing and Routing Output
Copyright © SAS Institute Inc. All rights reserved.