FILE Statement: z/OS

Specifies the current output file for PUT statements.
Valid in: In a DATA step
z/OS specifics: file-specification, type, host-options
See: FILE Statement in SAS Statements: Reference
Syntax
Details
Standard Host Options for the FILE Statement under z/OS
Host Options for Retrieving Information about Data Sets
VSAM Options for the FILE and INFILE Statements under z/OS
Host-Specific Options for UNIX System Services Files
See Also

Syntax

FILE file-specification <type> <ENCODING=encoding-value> <options> ;
FILE LOG | PRINT <options> ;

Required Argument

file-specification
identifies a file in one of the following forms:
fileref
specifies a fileref or the allocated ddname of the file. A fileref can consist of up to eight letters, numbers, national characters ($, @, and #), and underscores (_). The first character must be either a letter, a national character, or an underscore.
fileref(member)
specifies a member of a partitioned data set, where the PDS or PDSE is specified by the assigned fileref or allocated ddname.
If you specify a fileref that is not allocated, then SAS attempts to construct a data set name with the following three qualifiers:
  • the value of the SYSPREF= option (usually the user ID)
  • the specified fileref
  • DATA
If a file is found that has this constructed data set name, then SAS opens it and writes to it. If a file is not found, and the FILEPROMPT option is in effect, you will be asked if you want to create and catalog the file.
The value of the FILEEXT= system option can affect the way SAS interprets PDS and PDSE member names. For more information, see FILEEXT= System Option: z/OS.
'physical-filename'
specifies a physical file, which can be a sequential file, a member of partitioned data set (PDS), a member of an extended partitioned data set (PDSE), or a UNIX System Services file, using the following syntax:
  • a UNIX System Services file. For example: 
    '/u/userid/raw'
    or 
    'HFS:raw'
  • a fully qualified data set name. For example: 
    'myid.raw.datax'
  • a fully qualified data set name with a member in parentheses. For example: 
    'sas.raw.data(mem1)'
  • a partially qualified data set name with a period preceding it. For example: 
    '.raw.data'
  • a partially qualified data set name with a period preceding it and a member name in parentheses. For example: 
    '.raw.data(mem1)'
  • a temporary data set name. For example: 
    '&mytemp'
The value of the FILEEXT= system option can affect the way SAS interprets file specifications for PDS and PDSE files. For more information, see FILEEXT= System Option: z/OS.
For more information about partially qualified data set names, see Specifying Physical Files. For information about encodings for z/OS resources such as data set names and UFS paths, see Encoding for z/OS Resource Names.
LOG
directs output to the SAS log file.
PRINT
directs output to the SAS procedure output file.

Optional Arguments

type
specifies the type of file. When you omit type, the default is a standard external file. Nonstandard (host-specific) file types that you can specify for z/OS are
DLI
for IMS-DL/I databases. For information about IMS-DL/I options for the FILE statement, see SAS/ACCESS(R) 9.3 Interface to IMS: Reference.
HFS
for UNIX System Services files. For more information, see Accessing UNIX System Services Files.
MVS
for z/OS data sets.
PIPE
for pipelines in UNIX System Services. See Piping Data from SAS to a UNIX System Services Command.
VSAM
for VSAM files. See Accessing VSAM Data Sets.
ENCODING=encoding-value
specifies the encoding to use when writing to the output file. The value for ENCODING= indicates that the output file has a different encoding from the current session encoding. However, you can also specify the same encoding for the output file as the encoding of the current session. You must enclose the value in quotation marks if it contains a hyphen.
If you specify an encoding value different from the session encoding, SAS transcodes the data from the session encoding to the specified encoding when you write data to the output file. The default encoding is the session encoding, which is the value of the ENCODING= SAS system option.
For valid encoding values and more information about encoding, see “Encoding Values in SAS Language Elements” in the SAS National Language Support (NLS): Reference Guide.
options
are either portable or host-specific. For information about portable options that can be specified in the FILE statement, see the SAS Statements: Reference.
You can specify portable options and host options in any order. When you specify more than one option, separate the options with a blank space.
The host options that you can specify depend on what type of file you are accessing. See the following sections for details:

Details

Standard Host Options for the FILE Statement under z/OS

You can use the following options with all external files under z/OS:
BLKSIZE=value | BLK=value
specifies the block size of the file. Block size is discussed in more detail in DCB Option Descriptions and in Overview of DCB Attributes.
CLOSE=keyword
indicates how a tape volume is positioned at the end of the DATA step. Values for keyword are
REREAD positions the tape at the logical beginning of the data set.
LEAVE positions the tape at the logical end of the data set.
REWIND rewinds the tape to the physical beginning of the volume.
FREE dynamically deallocates the tape volume.
DISP is implied by the control language.
CSRC
specifies that you want to use the CSRCESRV services (available with z/OS) to compress data on output. For example: 
data _null_;
   file myfile csrc;
   put ... ;
run;
You cannot use this option with an external file that has a fixed-length record format.
DCB=fileref
specifies the fileref of an external file that was referenced in an earlier FILE or INFILE statement in the same DATA step. SAS uses that file's RECFM=, LRECL=, and BLKSIZE= information for the current file.
LINESIZE=width
works with LRECL to specify the maximum number of characters per line or record in print files, nonprint files, and the SAS log. Under z/OS, the range of acceptable values of LINESIZE= is 64 to 256. The default value of the LINESIZE= system option under z/OS is 132. This default applies only to print files (with carriage returns) or to the SAS log. For nonprint files (without carriage returns), the value of LRECL= is used in place of the default value for LINESIZE=.
LRECL=value
specifies the logical record length of the file. The specified value depends on the access method and the device type. For more information, see the discussion of LRECL= in DCB Option Descriptions and the IBM MVS JCL Reference.
MOD
writes the output lines following any existing lines in the file. This option overrides a disposition that was specified in JCL or under TSO. It is not valid if the specified file is a member of a partitioned data set (PDS).
NOPROMPT
specifies that if the file that you reference in the FILE statement is unavailable, a dialog box is not displayed, and an error is written to the SAS log.
OLD
writes the output lines at the beginning of the file, overwriting any existing data in the file. This option overrides a disposition that was specified in JCL or under TSO, and it is the default if no disposition is specified. Using OLD is necessary only if you used MOD for the file in an earlier FILE statement and you want to overwrite the file.
PRINT|NOPRINT
specifies whether carriage-control characters are placed in output files. Under z/OS, PRINT adds carriage-control characters to the beginning of all lines of output that are directed to print files and to the SAS log.
RECFM=record-format
specifies the record format of the file. Valid values are
F specifies fixed-length records, unblocked.
V specifies variable-length records, unblocked.
FB specifies fixed-length records, blocked.
VB specifies variable-length records, blocked.
U specifies undefined-length records, unblocked.
The following values can be appended to the RECFM values:
A specifies that the first byte of each record is an ANSI printer-control character.
S if appended to V, specifies that the file contains spanned records; if appended to F, specifies that the file contains standard blocks.
The following value stands alone; no other values can be appended:
N indicates that the file is in binary format. The file is processed as a stream of bytes with no record boundaries, which includes the default value of LRECL. This record format is specific to SAS.

Host Options for Retrieving Information about Data Sets

The following options are used in the FILE, FILENAME, and INFILE statements to retrieve information about a data set from the operating environment control blocks. SAS assigns values to the variables that are defined by these options when it opens the data set. It updates the values every time it opens a new data set in a concatenation. You can use these options with all standard external files under z/OS.
DEVTYPE=variable
defines a character variable (minimum length 24) that SAS sets to the device type. SAS obtains the device type by using the z/OS operating environment DEVTYPE macro. For more information, see the IBM documentation for your operating environment.
DSCB=variable
defines a character variable (minimum length 96) that SAS sets to the Data Set Control Block (DSCB) information from a non-VSAM data set. For more information, see the IBM documentation for your operating environment.
JFCB=variable
defines a character variable (minimum length 176) that SAS sets to the Job File Control Block (JFCB). For more information, see the IBM documentation for your operating environment.
UCBNAME=variable
defines a character variable (minimum length 3) that SAS sets to the unit name (device address), which is derived from information in the unit control block (UCB).
VOLUME=variable | VOLUMES=variable
defines a character variable (with a minimum length of six characters) that SAS sets to the tape VOLSER or the disk volume serial number. In the case of a multivolume file, the VOLUME= variable contains the concatenated volume serial numbers up to the length of the variable or the first 30 volumes, whichever is less. The value in the VOLUME= variable contains the volume serial number of the first data set in the concatenation when the file is opened. This serial number changes if you open a subsequent data set in the concatenation.

VSAM Options for the FILE and INFILE Statements under z/OS

You can use the following options for VSAM files in the FILE statement and in the INFILE statement. (Unless otherwise indicated, the option can be used in both.)
BACKWARD | BKWD
causes SAS to read the VSAM data set backwards (INFILE only).
BUFND=value
indicates how many data buffers to use for the VSAM data set.
BUFNI=value
indicates how many index buffers to use for the VSAM data set.
CONTROLINTERVAL | CTLINTV | CNV
indicates that you want to read physical VSAM control interval records rather than logical records. This option is typically used for diagnostic purposes (INFILE only).
ERASE=variable
defines a numeric SAS variable that you must set to 1 when you want to erase a VSAM record (INFILE only).
FEEDBACK=variable | FDBK=variable
defines a numeric variable that SAS sets to the VSAM logical error code. This option is similar to the _FDBK_ automatic variable. When SAS sets the FEEDBACK variable, you must reset it to 0 in order to continue.
GENKEY
causes SAS to use the KEY= variable as the leading portion of a record's key. VSAM retrieves the first record whose key matches the generic key (INFILE only).
KEY=variable | KEY=(variable1 variable2 . . . )
indicates that direct keyed access is being used to read records either from a KSDS or from an ESDS via an alternate index. Also, the variable contains the key value to be used in the retrieval of a record (input) or the writing of a record (output) (INFILE ONLY).
KEYGE
is used in conjunction with the KEY= option. KEYGE indicates that when KEY= is used in a retrieval request, SAS retrieves any record whose key is equal to or greater than the specified key. This option is useful when the exact key is not known (INFILE only).
KEYLEN=variable
specifies a numeric SAS variable that, when used with GENKEY, specifies the length of the key that is to be compared to the keys in the file.
KEYPOS=variable
indicates the numeric variable that SAS sets to the position of the VSAM key field. This option enables you to read keys without knowing the key position in advance. This variable is set to the column number (starting from 1).
NORLS | NRLS
specifies not to use record-level sharing (RLS) to open an RLS-eligible data set (INFILE only).
Note: This argument overrides the VSAMRLS system option.
PASSWD=value
gives the appropriate password for a VSAM data set that has password protection.
RBA=variable
specifies a numeric variable that you set to the relative byte address (RBA) of the data record that you want to read. The RBA= option indicates that addressed direct access is being used; it is appropriate for KSDS and ESDS. If you specify the CONTROLINTERVAL option, you can use the RBA= option to access control records in an RRDS (INFILE only). This variable is set to zero when a path is defined over an alternate index.
RC4STOP
stops the DATA step from executing if a return code greater than 4 is returned by the operating environment when the VSAM data set is opened.
RECORDS=variable
defines a numeric variable that SAS sets to the number of logical records in a VSAM data set that has been opened for input.
RECORG=record-organization
specifies the organization of records in a new VSAM data set. Use this option only if SMS is active. Valid values are
KS specifies a VSAM key-sequenced data set.
ES specifies a VSAM entry-sequenced data set.
RR specifies a VSAM relative-record data set.
LS specifies a VSAM linear-space data set.
RESET
indicates that the VSAM file is reset to empty (no records) when it is opened. This option applies only to loading a VSAM data set that has been marked REUSE. You cannot use this option if the data set contains an alternate index.
RLS
specifies that this data set should be opened in RLS mode. If the data set is not RLS-eligible, the specification will be ignored.
Note:Overrides the NOVSAMRLS system option.
RLSREAD=NRI | CR | CRE
specifies the read integrity level to be applied to this RLS data set.
Restriction:Valid only for the INFILE statement.
Note:Overrides any specification made with a DD statement or TSO ALLOC command.
RRN=variable
defines a numeric variable that you set to the relative record number (RRN) of the record that you want to read or write. This option indicates that keyed direct access is being used; it is appropriate for RRDS only.
SEQUENTIAL
specifies sequential VSAM record retrieval when either the RBA= (for an ESDS) or the RRN= option (for an RRDS) is specified (INFILE only).
SKIP
indicates skip-sequential processing of VSAM files. Skip-sequential processing finds the first record whose value is the same as the value specified by the KEY= option; records are read sequentially thereafter (INFILE only).
UPDATE=variable
defines a numeric SAS variable that indicates that not every record that it reads is to be updated. Use this option when you are updating records in a VSAM data set (INFILE only). When an INFILE and a FILE statement reference the same VSAM data set, records are retrieved for update by default.
In most cases when you retrieve a record for update, no user, including you, can access that particular record or any other records in the same control interval until you free the record by executing a PUT or an INPUT statement for the data set. The UPDATE= option avoids user lockout when only a few of many records read need to be updated. When you set the UPDATE= variable to a value of 1 before the INPUT statement, the record is retrieved for update. This value is the default if UPDATE= is not specified. If you set UPDATE=0 before the INPUT statement, the record is not retrieved for update.
VSMDBUG=nnnn
indicates that a message should be written to the SAS log that indicates the filename, function requested, return code, and reason code after each VSAM system request (for example, GET, POINT, PUT) until the number specified by nnnn is exceeded.
Note:The value of nnnn can be 1–9999.

Host-Specific Options for UNIX System Services Files

The following table shows which host-specific options are recognized by the FILENAME, FILE, and INFILE statements for UNIX System Services files and pipes. No other options are recognized, including such options specific to z/OS as DISP, CLOSE, and DCB. Descriptions of the options follow the table.
Host-Specific Options for UNIX System Services Files and Pipes
Option
FILENAME
FILE
INFILE
%INCLUDE
BLKSIZE=
X
X
X
X
BOM
X
X
BOMFILE
X
X
FILEDATA=
X
X
X
LRECL=
X
X
X
X
MOD
X
X
NOBOM
X
X
NOBOMFILE
X
X
OLD
X
X
RECFM=
X
X
X
X
TERMSTR=
X
X
X
BLKSIZE=
specifies the number of bytes that are physically read or written in an I/O operation. The default is 8K. The maximum is 1M.
BOMFILE
includes a Byte Order Mark when a UNICODE-encoded file is created.
Alias:BOM
FILEDATA=BINARY | TEXT
The FILEDATA= option specifies that the file being processed is expected to contain one of the following:
BINARY data without record separator character sequences.
TEXT data with records terminated by the EBCDIC newline character. The EBCDIC newline character is defined at code point x'15' and is typically represented as NL or \n.
Note: The FILEDATA= option is meant to be similar to the FILEDATA= parameter on the DD JCL statement, but is evaluated at run time by SAS. The JCL parameter is used by z/OS to set an attribute of the file when the file is created by the JCL
LRECL=value
specifies the maximum number of characters in a line (unless the file has been opened with RECFM=N). The default is 255. Lines longer than value are truncated. value must be between 1 and 16,777,215, inclusive.
MOD
appends the output lines to the file. This option has no effect on a pipe.
NOBOMFILE
specifies that a Byte Order Mark is not included when a UNICODE-encoded file is created.
Alias:NOBOM
OLD
replaces the previous contents of the file. This option is the default. It has no effect on a pipe.
RECFM=record-format
specifies the record format of the file. Valid values are
F specifies that all lines in the file have the length specified in the LRECL= option. In output files, lines that are shorter than the LRECL= value are padded on the right with blanks.
V | D specifies that the lines in the file are of variable length, ranging from one character to the number of characters specified by LRECL=. This option is the default.
P specifies that the file has variable-length records and is in print format.
N specifies that the file is in binary format. The file is treated as a byte stream. That is, line boundaries are not recognized.
TERMSTR=NONE | NL | CR | LF | CRLF | LFCR | CRNL
The TERMSTR= option specifies the type of record separator character sequences to use to terminate records in the file. TERMSTR= accepts the following parameters:
NONE Record terminators are not used. This parameter provides the same function as FILEDATA=BINARY.
NL The newline character (x'15') is used as the record terminator. This parameter provides the same function as FILEDATA=TEXT.
CR The carriage return character (x'0C') is used as the record terminator.
LF The line feed character (x'25') is used as the record terminator.
CRLF The sequence CR followed by LF is used as the record terminator.
LFCR The sequence LF followed by CR is used as the record terminator.
CRNL The sequence CR followed by NL is used as the record terminator.
All of the above specifications (x'15', x'0C', and x'25') assume that the files use an ENCODING= value whose short (12 byte) name is in the form open_ed-nnnn and whose long (32 byte) name contains (OpenEdition) (for example, open_ed-1047 or Western(OpenEdition)). These characters are automatically transcoded to or from the file's encoding if they are required by the ENCODING= or LOCALE= options.
The last occurrence of FILEDATA= or TERMSTR= takes precedence. Specification of one or the other of these options on a FILE or INFILE statement takes precedence over the specification in a related FILENAME statement. The full precedence order is as follows:
  1. Specification of FILEDATA= or TERMSTR= on a FILE or INFILE statement.
  2. Specification of FILEDATA= or TERMSTR= on a FILENAME statement.
  3. Specification of FILEDATA= on a DD JCL statement when the file was created by that DD statement
  4. Implied by the RECFM= option in effect for the file.
The RECFM= option in the FILENAME, FILE, and INFILE statement can imply the value assumed for the termination sequence. This implication is always overridden by the presence of a TERMSTR= or FILEDATA= option for the file. Here are the default values:
RECFM=V|D TERMSTR=NL is implied. (This option is the default.)
RECFM=F TERMSTR=NONE is implied.
RECFM=P TERMSTR=NL implied, along with other formatting control characters.
RECFM=N TERMSTR=NONE is implied.
Note: The FILEDATA= parameter on the DD JCL statement is used only by z/OS when the file is being created by that JCL statement. For existing files, the FILEDATA= parameter is ignored by z/OS, and SAS is informed of its value at file creation time. Therefore, SAS cannot detect a change in the JCL. However, SAS will honor the values of FILEDATA= or TERMSTR= that are specified in the FILENAME, INFILE, or FILE statements when you replace an existing file or read a file.
CAUTION:
The combination of RECFM= and TERMSTR= provides much flexibility for reading and writing many different file formats. It is possible to use these options in a way that can produce a file that might be difficult to process in the future. For example, a PRINT file can be created without record terminators, but this file would look strange when printed on a printer or viewed in an editor.
For more information about these options, see Writing to External Files and Using the FILE Statement to Specify Data Set Attributes.

See Also

SAS VSAM Processing for z/OS
Copyright © SAS Institute Inc. All rights reserved.