Chapter Contents

Previous

Next

FILENAME

Valid:	anywhere
OS/390 specifics:	fileref, device-type, physical-filename, host-options

fileref

identifies an external file. The fileref must conform to the rules for DDnames. That is, it can consist of one to eight letters, numbers, or the national characters $, @, and #. The first character must be either a letter or one of the national characters.

device-type

specifies a device type for the output. It can be one of the following:

CART

send the output to a tape cartridge.

DISK

sends the output to a disk drive.

DUMMY

specifies a null output device. This value is especially useful in testing situations. Any output that would normally be sent to the external file is dicarded.

HFS

specifies a UNIX System Services file.

MVS

specifies an MVS data set.

PIPE

specifies that SAS open a UNIX System Services pipeline for execution of UNIX System Services commands issued within the statement.

PLOTTER

sends the output to the default system plotter.

PRINTER

sends the output to the default system printer.

TAPE

sends the output to a tape drive.

TEMP

allocates a temporary data set.

TERMINAL

sends the output to your terminal.

You can specify device-type in two ways: either specify it between the fileref and the file specification in the FILENAME statement or use the standard file option UNIT= to specify it. (See Standard File Options for the FILENAME Statement.) If you specify device-type in both ways, the UNIT= option takes priority. If you do not specify a device type or UNIT value for a new file, SAS uses the current value of the SAS system option FILEDEV=.

file-specification or ('file-specification-1'... 'file-specification-n')

specifies an external file or a concatenation of external files. In a concatenation, each data set name must be enclosed in quotes, and the entire group of concatenated file specifications must also be enclosed in parentheses.

'physical-filename'

specifies a physical file, which can be a sequential data set, a member of partitioned data set (PDS), a member of an extended partitioned data set (PDSE), or a file in UNIX System Services. 'physical-filename' must be enclosed in quotes and must refer to one of the following:

• 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. For example:

  '.raw.data'

• a partially qualified data set name with a period preceding and a member name in parentheses. For example:

  '.raw.data(mem1)'

• for PDS members, a fully or partially qualified data set name with a wildcard name in parentheses. For example:

  '.raw.data(mem*)'

  '.raw.data(*mem1)'

  '.raw.data(*)'

• a temporary data set name. For example:

  '&mytemp'

• a UNIX System Services file:

  '/u/userid/raw'

  or

  'HFS:raw'

The value of the FILEEXT= system option can affect the way SAS interprets file specifications for PDS and PDSE files. See FILEEXT= for details.

The value of the FILESYSTEM= system option can also affect the way SAS interprets filenames. See FILESYSTEM= for details.

See Specifying Physical Files for more information about partially qualified data set names.

_ALL_

Can be specified to clear or list all currently allocated filerefs.

CLEAR

Can be specified to deallocate the specified fileref, or to deallocate all currently allocated filerefs.

LIST

Can be specified to list the fileref name and physical name, or to list information about all currently allocated filerefs.

host-options

are host-specific options that may be specified in the FILENAME statement. These options can be categorized into several groups. For details, see the following sections:

• Standard File Options for the FILENAME Statement

• DCB Attribute Options

• SYSOUT Data Set Options for the FILENAME Statement

• Subsystem Options for the FILENAME Statement

• Options That Specify SMS Keywords

• Host-Specific Options for UNIX System Services Files .

You can specify these options in any order following 'physical-filename '. When specifying more than one option, use a blank space to separate each option. Values for options may be specified with or without quotes. However, if a value contains one of the supported national characters ($, #, or @), the quotes are required.

Standard File Options for the FILENAME Statement

Standard file options provide information about a data set's disposition and physical attributes. The following standard options can be used with all external files under OS/390 except for files that are in the Hierarchical File System of UNIX System Services. (See Host-Specific Options for UNIX System Services Files .)

DISP=status | (status,<normal-termination-
disp>,<abnormal-termination-disp>)

specifies the status of the physical file at the beginning and ending of a job, as well as what to do if the job step terminates abnormally. If you are specifying only status, you can omit the parentheses.

status

specifies the status of the data set at the beginning of a job. Valid values are

NEW	a new data set is to be created.
OLD	the data set exists and is not to be shared.
SHR	the data set exists and may be shared.
MOD	if the data set exists, new records are to be added to the end; if the data set does not exist, a new data set is to be created. MOD cannot be specified for a partitioned data set.

The default is SHR.

Note:   You can also supply any of these values for status as a separate, individual keyword in the FILENAME statement rather than as a subparameter of the DISP= option.  

normal-termination-disp

specifies what to do with the data set if the job step that was using the data set terminates normally. Valid values are

DELETE	deletes the data set at the end of the step.
KEEP	keeps the data set.
CATLG	places the entry in the system catalog or user catalog.
UNCATLG	deletes the entry from the system catalog or user catalog.

For a new data set, the default is CATLG. For an existing data set, the default is KEEP.

abnormal-termination-disp

specifies what to do if the job step terminates abnormally. The default is to take the action that is specified or implied by normal-termination-disp. Valid values are

DELETE	indicates that the data set is to be deleted at the end of a job step.
KEEP	indicates that the data set is to be kept.
CATLG	indicates that the system should place an entry in the system or user catalog.
UNCATLG	indicates that the system is to delete the entry in the system or user catalog.

Here are some examples of the DISP parameter:

   DISP=SHR
   DISP=(NEW,CATLG)
   DISP=(OLD,UNCATLG,DELETE)

SPACE=(unit,(primary,secondary,directory),
RLSE,type,ROUND)

is the amount of disk space to be provided for a data set that is being created.

unit

may be any of the following:

TRK	specifies that the space is to be allocated in tracks.
CYL	specifies that the space is to be allocated in cylinders.
blklen	specifies that the space is to be allocated in blocks whose block length is blklen bytes. The system computes how many tracks are allocated.

primary

specifies how many tracks, cylinders, or blocks to allocate.

secondary

specifies how many additional tracks, cylinders, or blocks to allocate if more space is needed. The system does not allocate additional space until it is needed.

directory

specifies how many 256-byte directory blocks are needed for the directory of a partitioned data set.

RLSE

causes unused space that was allocated to an output data set to be released when the data set is closed. Unused space is released only if the data set is opened for output and if the last operation was a write operation.

type

can be any of the following:

CONTIG	means that the allocated space must be contiguous.
MXIG	means that the maximum contiguous space is required.
ALX	means that different areas of contiguous space are needed.

Note:   You can also specify MXIG or ALX as a separate, individual keyword on the FILENAME statement rather than as a subparameter of the SPACE= option.  

ROUND

specifies that the allocated space must be equal to an integral number of cylinders when the unit specified was a block length. If unit was specified as TRK or CYL, the system ignores ROUND.

Here are some examples of the SPACE parameter:

SPACE=(CYL,10) 
   or SPACE=(CYL,(10,,10),,CONTIG)
SPACE=(1024,(100,50,20),RLSE,MXIG,ROUND)

If SPACE is not specified, its values are taken from the SAS system options FILEUNIT=, FILESPPRI=, FILESPSEC=, and FILEDIRBLK=, in the following form:

SPACE=(FILEUNIT,(FILESPPRI,
  FILESPSEC,FILEDIRBLK))

The default specifications are as follows:

for partitioned data sets:

SPACE=(CYL,(1,1,6))

for sequential data sets:

SPACE=(CYL,(1,1))

See OS/390 JCL Reference by IBM for complete information about how to use the SPACE= option.

VOLSER=value | VOL=value | VOL=(value-1, ..., value-n)

specifies the disk or tape volume serial number or numbers. Up to 5 volume serial numbers can be specified.

If VOLSER= is not specified, its value is taken from the SAS system option FILEVOL=.

UNIT=value

can name one of several different devices. Some valid values follow. Ask your system administrator whether additional valid values have been defined at your site.

• CART

• DISK

• DUMMY

• PLOTTER

• PRINTER

• TAPE

• TERMINAL

The default for UNIT= is DISK.

LABEL=(subparameter-list)

enables you to specify the type and contents of the label of either a tape data set or a disk data set, as well as other information such as the retention period or expiration date for the data set. It is identical to the JCL LABEL= parameter. Here is a simple example:

label=(3,SL,,,EXPDT=1999/123)

This label specification indicates that the data set sequence number is 3, that it uses standard labels, and that it expires on the 123rd day of 1999. See OS/390 JCL Reference by IBM for complete information about how to use the LABEL= option, including which subparameters you can specify in subparameter-list.

NOMOUNT

specifies that the mount message is not to be issued for a volume that is not already online. The default action is to issue the mount message.

NOPROMPT

specifies that if the file that you reference in the FILENAME statement is unavailable, a requestor window is not displayed and an error message is written to the SAS log.

REUSE

indicates that the file that you reference in the FILENAME statement is to be freed and reallocated if it is currently in use. By default, SAS does not free and reallocate a file that is currently in use.

WAIT=n

controls how many minutes SAS waits if the file that you reference in the FILENAME statement is unavailable. SAS tries to reacquire the reserved data set every 15 seconds. The value n specifies a length of time in clock minutes.

DCB Attribute Options

The following section describes DCB options that can be used in the FILENAME statement. For additional information about DCB characteristics, see Overview of DCB Attributes.

DCB Option Descriptions

The following DCB options can be used in the FILENAME statement for all types of external files under OS/390, except for files that are stored in the directory structure of UNIX System Services. (For information about options that are available for UNIX System Services files, see Host-Specific Options for UNIX System Services Files .) These options correspond to the DCB parameters that you would specify in a JCL DD statement.

BLKSIZE=value

specifies the number of bytes in a block of records. A block is a group of records that SAS and the operating environment move as a unit when reading or writing an external file. The term also refers to the space allowed for each group of records. You seldom need to calculate block size when you write an external file because SAS automatically selects the block size.

The values of the FILEBLKSIZE(device-type)= system option contain, for each model of disk that is currently available, the block size that your installation considers best for external, nonprint data sets on that type of disk. Some installations may provide different FILEBLKSIZE default values for batch processing than they do for interactive processing. Therefore, to see the values for the FILEBLKSIZE(device-type)= option, run the OPTIONS procedure both in a batch job and in a SAS session under TSO.

For print data sets, which by default have variable-length records, SAS uses a default block size of 264, with one record per block.

You can use the OPT value of the FILEBLKSIZE(device-type)= option to tell SAS to calculate the optimal block size for nonprint files. (See FILEBLKSIZE(device-type)=.) Or you can calculate the block size yourself:

• To calculate a block size for fixed-length records, multiply the LRECL= value by the number of records you want to put into the block.

• For variable-length records, multiply the LRECL= value by the number of records per block and add 4 bytes.

In each case, if you are writing the data set to disk, compare the block size to the track size for the disk. A block cannot be longer than one track of the disk device on which it is stored, and the operating environment does not split a block between tracks. Make sure that the block size does not leave a large portion of the track unused. (If you are not sure, consult your computing center staff.) See Optimizing I/O for information about determining the optimal block size for your data.

The maximum block size for a data set on tape is 32,760.

BUFNO=value

specifies how many memory buffers to allocate for reading and writing. If BUFNO= is not specified, the default is BUFNO=5. See Optimizing I/O for information about determining the optimal BUFNO= value for your data.

DSORG=organization

The following types of organization can be specified:

• DA (direct access)

• PO (PDS, PDSE)

• PS (sequential).

The following types of organization, used to refer to physical files that contain location-dependent information, are also valid: DAU, POU, PSU.

You do not need to include the DSORG= value when you create an external file of type PS or PO. This is because the operating environment identifies a partitioned data set by the presence of a directory allocation in the SPACE= parameter. When you use a FILE statement to write data, SAS identifies a PDS or PDSE by the presence of a member name in the FILE statement. If no member name is present, SAS assumes that the data set is sequential.

LRECL=value

specifies the logical record length (that is, the number of bytes in a record). SAS defaults to the size that is needed (for either print or nonprint files) when a file is opened.

Logical record length is affected by the record format (see RECFM=). When the record format is fixed (indicated by an F as part of the RECFM= value), all records have the same length, and that length is the value of the LRECL= value.

When the record format is variable (indicated by a V as part of the RECFM= value), records may have different lengths, and each record contains 4 bytes of length information in addition to its other data. Therefore, you must specify an LRECL= value that is 4 bytes longer than the longest record you expect to write. If you do not know the length of the longest record to be put into a variable-format data set, choose a maximum value and add 4 to it to create an LRECL= value.

OPTCD=value

specifies the optional services to be performed by the operating environment. For example, specifying W requests a validity check for write operations on direct-access devices. For more information, see the appropriate IBM OS/390 JCL manual for your system.

Valid values are R, J, T, Z, A, Q, F, H, O, C, E, B, U, and W. You can specify more than one code by listing them with no blanks or commas between them (as with RECFM). A maximum of four characters is allowed.

RECFM=record-format

specifies the record format of the file. Valid values are

F	fixed length records, unblocked.
V	variable length records, unblocked.
FB	fixed length records, blocked.
VB	variable length records, blocked.
U	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.
M	specifies that the file is a machine control character file. SAS does not interpret machine-code control characters nor does it create them in output files. See OS/390 JCL Reference by IBM for more information.
S	specifies that the file contains spanned records (when appended to V), or that the file contains standard blocks (when appended to F).

The next format stands alone; no other values may be appended.

N	indicates that the file is in binary format. The file is treated as a byte stream; that is, line boundaries are not recognized. This record format is specific to the SAS System.

Overview of DCB Attributes

DCB attributes and options are relevant to INFILE and FILE statements as well as to the FILENAME statement. This section provides some background information about DCB characteristics.

DCB attributes are those data set characteristics that describe the organization and format of the data set records. If you do not specify these attributes, the SAS System uses default values for them. This section discusses how and under what circumstances these attributes are changed or default values are used.

The discussion focuses on the RECFM, LRECL, and BLKSIZE file attributes. For more information, see the appropriate data administration guide for your system.

Values for these attributes are kept in each of the following operating environment control blocks:

Data Set Control Block (DSCB)	is the description found in the VTOC of the disk device that the physical file resides on. These are the permanent characteristics of the data set. For tape devices, the data set label in the header of SL tapes contains this information.
Job File Control Block (JFCB)	maps a physical file on a device to a logical name (DDname). Contains information from a JCL DD statement, TSO ALLOCATE command, SAS FILENAME statement, or SAS FILENAME function. These attributes are either temporary (for the duration of the allocation) or new (to be made permanent).
Data Control Block (DCB)	describes the current state of an open data set. OS/390 and its access methods (BSAM for the SAS System) use the DCB to control how data is read or written. These attributes are temporary for input, but they become permanent for output.

For existing data sets, DCB attributes are almost always used unchanged from the DSCB. These attributes may be overridden by a DD statement or TSO ALLOCATE command or by SAS FILENAME, FILE, or INFILE options. If an option is specified in both places, the FILENAME, FILE, or INFILE option takes precedence.

When a data set is opened, OS/390 merges information from the DSCB (or data set label) and the JFCB to obtain the current DCB characteristics before entering the DCB open exit. SAS then merges its own information (FILENAME/FILE/INFILE statement options, data set device type, requested data set type, requested line size from LS=) and inspects the resulting DCB attributes. If the result is invalid for some reason, SAS terminates the open operation and issues an appropriate message. Attributes may be considered invalid for any of the following reasons:

• For RECFM=V, VB, BLKSIZE is not at least 4 bytes greater than LRECL.

• For RECFM=F, LRECL equals neither 0 nor BLKSIZE.

• For RECFM=FB, BLKSIZE is not a multiple of LRECL.

• BLKSIZE or LRECL is greater than the OS/390 maximum (32,760).

• LRECL is greater than BLKSIZE (except RECFM=VBS).

• RECFM is not consistent with the requested data set type.

• The requested data length cannot be contained in LRECL.

For any unspecified attributes, SAS takes default values that seem to fit existing attributes. This may cause unexpected combinations of attributes to be set, so be wary of specifying an incomplete set of attributes for a data set.

If no permanent attributes are present (as is possible with a new data set), and if none are given by FILENAME/FILE/INFILE options, then SAS uses default values that are based on the device type and data set type. The following table summarizes these default values.

Attribute		DISK	TAPE	PRINT/ SYSOUT	TERMINAL	DUMMY
RECFM		FB	FB	VBA	V	FB
LRECL		80	80	260	261	80
BLKSIZE		*	**	264	265	*
*The smaller of the SAS system option FILEBLKSIZE(device-type)= value and the output device maximum, rounded down to a multiple of the LRECL. **The smaller of the SAS system option FILEBLKSIZE(device-type)= value and 32,760, rounded down to a multiple of the LRECL.

If a line size (LS=) parameter is given, SAS uses this value to compute the LRECL, and the BLKSIZE is computed accordingly.

If permanent attributes are overridden on input, these values are used only for the duration of the INFILE processing; the permanent attributes of the data set are not changed. However, if attributes are overridden on output, the specified attributes become permanent for the data set, even if no records are physically written.

Options That Specify SMS Keywords

Several options that specify SMS (Storage Management Subsystem) keywords can be specified in the FILENAME or FILE statement when you create an external file. All of these options are ignored for existing data sets; they apply only when you are creating a data set. If you do not specify any of these options when you create an SMS data set, the system defaults are used. The default values are site-dependent; see your system administrator for details. For more information about SMS data sets, see OS/390 JCL Reference by IBM.

DATACLAS=data-class-name

specifies the data class for an SMS-managed data set. The name can have up to 8 characters. This option applies only to new data sets; it is ignored for existing data sets. The data class is predefined and controls the DCB attributes for a data set.

The implementation of the DATACLAS= option is compatible with the SMS DATACLAS= JCL parameter. For complete information about this parameter, see OS/390 JCL Reference. Ask your system administrator for the data-class names that are used at your site.

DSNTYPE=LIBRARY | PDS

specifies the data set name type.

LIBRARY	indicates that the data set is a PDSE.
PDS	indicates that the data set is a PDS.

DSNTPE= is valid only for SMS data sets, and is valid only when DSORG=PO.

LIKE=data-set-name

enables you to allocate an external file that has the same attributes as an existing file. See OS/390 JCL Reference for more information.

MGMTCLAS=management-class-name

specifies a management class for an SMS data set. The name can have up to 8 characters. This option applies only to new data sets; it is ignored for existing data sets. The management class is predefined and controls how your data set is managed, such as how often it is backed up and how it is migrated.

The implementation of the MGMTCLAS= option is compatible with the SMS MGMTCLAS= JCL parameter. For complete information about this parameter, see OS/390 JCL Reference. Ask your system administrator for the management class names that are used at your site.

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	VSAM key-sequenced data set
ES	VSAM entry-sequenced data set
RR	VSAM relative-record data set
LS	VSAM linear-space data set

STORCLAS=storage-class-name

specifies a storage class for an SMS data set. The name can have up to 8 characters. This option applies only to new data sets; it is ignored for existing data sets. The storage class is predefined and controls which device your SMS data set is stored on, such as disk or tape.

The implementation of the STORCLAS= option is compatible with the SMS STORCLAS= JCL parameter. For full details on this parameter, refer to OS/390 JCL Reference. See your system administrator for storage class names at your site.

SYSOUT Data Set Options for the FILENAME Statement

The following options apply to data sets that are sent to a system output device (usually a printer). The default value is usually the value that was specified by your site as the installation default. See Writing to Print Data Sets , as well as your IBM JCL reference, for more information about print data sets.

ALIGN

asks the operator to check the alignment of the printer forms before printing the data set.

BURST

tells the operator that the printed output is to go to a burster-trimmer-stacker machine, to be burst into separate sheets.

CHAR1=value

specifies a one- to four-character name for character-arrangement table #1 (used in conjunction with the 3800 Printing Subsystem).

CHAR2=value

specifies a one- to four-character name for character-arrangement table #2 (used in conjunction with the 3800 Printing Subsystem).

CHAR3=value

specifies a one- to four-character name for character-arrangement table #3 (used in conjunction with the 3800 Printing Subsystem).

CHAR4=value

specifies a one- to four-character name for character-arrangement table #4 (used in conjunction with the 3800 Printing Subsystem).

CLOSE

tells the operating environment to deallocate the data set when the DCB is closed.

COPIES=value

specifies how many copies of the SYSOUT data set to print. The default is COPIES=1.

DEST=dest-name

specifies a destination for the SYSOUT data set. If DEST is not defined, its value is taken from the SAS system option FILEDEST=.

FCB=fcb-image

specifies the forms control buffer image that JES should use to control the printing of the SYSOUT data set.

FLASH=value

specifies which forms overlay frame to use when printing the data set on a 3800 Printing Subsystem.

FLASHC=value

specifies the number of copies on which to print the forms overlay frame.

FOLD

requests that the print chain or print train for the universal character set be loaded in fold mode.

FORMDEF=member

identifies a member that contains statements that tell the Print Services Facility from IBM how to print the SYSOUT data set on a page-mode printer. This option has no effect on SAS forms.

FORMS=form-num

specifies the IBM form number. If FORMS= is not defined, its value is taken from the FILEFORMS= system option. This option has no effect on SAS forms.

HOLD

tells the system to hold the SYSOUT data set when it is deallocated until it is released by the system operator.

ID=dest-userid

specifies the user ID for the SYSOUT destination.

MODIFY=value

specifies a copy-modification module that tells JES how to print the SYSOUT data set on a 3800 Printing Subsystem.

MODIFYT=value

specifies which of the CHARn tables to use. For example, if value equals 1, then the character-arrangement table that is identified by the CHAR1= option is used.

OUTDES=value

specifies the output descriptor.

OUTLIM=value

specifies a limit for the number of logical records in the SYSOUT data set.

PAGEDEF=member

identifies a member that contains statements that tell the Print Services Facility how to format the page on a page-mode printer.

PGM=pgm-name

specifies the SYSOUT program name.

PRMODE=value

specifies which process mode is required for printing the SYSOUT data set.

SYSOUT=value

specifies the output class for the SYSOUT data set. If SYSOUT is not defined, its value is taken from the SAS system option FILESYSOUT=.

UCS=

specifies the universal character set.

UCSVER

tells the operator to visually verify that the character set image is for the correct print chain or print train. The character set image is displayed on the printer before the data set is printed.

VERIFY

tells the operator to verify that the image displayed on the printer is for the correct FCB image.

Subsystem Options for the FILENAME Statement

The following subsystem data set options are also available. For more information about subsystem data sets, see the appropriate IBM OS/390 JCL manual for your site.

SUBSYS=value

specifies the name of the subsystem (from 1 to 4 characters).

PARM1=value

specifies a subsystem parameter (up to 67 characters).

PARM2=value

specifies a subsystem parameter (up to 67 characters).

PARM3=value

specifies a subsystem parameter (up to 67 characters).

PARM4=value

specifies a subsystem parameter (up to 67 characters).

PARM5=value

specifies a subsystem parameter (up to 67 characters).

Options for UNIX System Services Files and Pipes

Several options can be specified in the FILENAME statement for files and pipes that are in the Hierarchical File System of UNIX System Services. For information about these options, see Accessing UNIX System Services Files .

See Also

• FILENAME

• SAS Language Reference: Dictionary

• OS/390 JCL Reference by IBM

Chapter Contents

Previous

Next

Top of Page

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