ALLOCATE command operands

DATASET(dsname | *) | DSNAME(dsname | *)

specifies the name or a list of names of the data sets that are to be allocated. If a list of data set names is entered, ALLOCATE allocates and concatenates non-VSAM data sets. The data set name must include the descriptive (rightmost) qualifier and can contain a member name in parentheses.

If you specify a password, you are not prompted for it when you open a non-VSAM data set.

If you want to allocate a file to the terminal for input or output, only the following operands are processed:

ALLOCATE DA(*) FILE, DDNAME, BLOCK, BLKSIZE, USING

If you allocate more than one data set to your terminal, the block size and other data set characteristics, which default on the first usage, are also used for all other data sets. This happens for input or output. Use the ATTRIB command and the USING operand of ALLOCATE to control the data set characteristics.

Data sets residing on the same physical tape volume cannot be allocated concurrently.
The following items should be noted when using the concatenate function:
- The data sets specified in the list must be cataloged. You can use the CATALOG operand of either the ALLOCATE or FREE commands to catalog a data set.
- The maximum number of sequential data sets or partitioned members that you can concatenate is 255. The maximum in a partitioned concatenation is 255 PDS extents, PDSEs, or z/OS® UNIX directories. For more information about the maximum number of partitioned data sets that you can concatenate, see z/OS DFSMS Using Data Sets. The data sets to be concatenated must all have the same record format (RECFM). If you omit the BLKSIZE operand from the concatenation statement, the system uses the block size of the first data set. If the data sets have different block sizes, you must specify the data set with the largest block size first. In most situations, the access method automatically handles block size differences. For more information, see z/OS DFSMS Using Data Sets.
- The data set group is concatenated. You must free it to deconcatenate it. The file name specified for the FILE or DDNAME operand on the ALLOCATE command must be the same as that specified for the FILE or DDNAME operand on the FREE command.
- The system ignores all operands except for DATASET/DSNAME, FILE/DDNAME, and status operands. The following DCB attribute operands are allowed when concatenating data sets:
```
BLKSIZE   INPUT     EROPT     BUFOFF   USING
BUFL      OUTPUT    BFTEK     DEN
BUFNO     BFALN     DIAGNS    TRTCH
NCP       OPTCD     LIMCT     KEYLEN
```
To allocate a member of a generation data group, specify the fully-qualified data set name, including the generation number.
The ALLOCATE command verifies the existence of a data set on the specified volume(s) only when the VOLUME operand is also specified.
When you invoke ALLOCATE to perform dsname dynamic allocation, an "allocation environment" already exists for your request. It consists of the allocation requests, made through your JCL or internal dynamic allocation, that have not yet been deallocated. These resources are considered to be existing allocations, and are considered first in the attempt to fill your ALLOCATE requests.
If possible, ALLOCATE will use an existing allocation to satisfy your dsname allocation request. Although some parameters can be changed if necessary, the request and the existing allocation must match according to several criteria before the allocation can be selected to satisfy your request.

For more information about this criteria and using an existing allocation, see z/OS MVS Programming: Authorized Assembler Services Guide.

DUMMY

specifies that no devices or external storage space are to be allocated to the data set, and no disposition processing is to be performed on the data set. Entering the DUMMY operand has the same effect as specifying NULLFILE as the data set name on the DATASET or DSNAME operand.

If you want to allocate a DUMMY data set, only the following operands are processed:

ALLOCATE DUMMY, FILE, DDNAME, BLOCK, BLKSIZE, USING

The following operands are not valid when you specify a DUMMY data set:

COPIES, DEST

FILE(name) | DDNAME(name)

specifies the name to be associated with the data set. It can contain up to eight characters. (This name corresponds to the name on the data definition (DD) statement in job control language and must match the ddname in the data control block (DCB) that is associated with the data set.) For PL/I, this name is the file name in a DECLARE statement and has the form DCL file name FILE; for example, DCL MASTER FILE. For COBOL, this name is the external name used in the ASSIGN TO clause. For FORTRAN, this name is the data set reference number that identifies a data set and has the form FTxxFyyy, for instance, FT06F002.

If you omit this operand, the system assigns an available file name (ddname) from a data definition statement in the procedure that is invoked when you enter the LOGON command.

Do not use special ddnames unless you want to use the facilities those names represent to the system.

For more information about the special ddnames SYSMDUMP, SYSUDUMP, SYSCHK, SYSCKEOV, and SYSABEND see z/OS MVS JCL Reference.

For more information about the special ddnames JOBCAT, JOBLIB, STEPCAT, and STEPLIB see z/OS MVS JCL Reference.

OLD | SHR | MOD | NEW | SYSOUT(class)

OLD

indicates the data set currently exists and you require exclusive use of the data set. The data set should be cataloged. If it is not, you must specify the VOLUME operand. OLD data sets are retained by the system when you free them from allocation. The DATASET or DSNAME operand is required.

SHR

indicates the data set currently exists, but you do not require exclusive use of the data set. Others can use it concurrently. ALLOCATE assumes the data set is cataloged if the VOLUME operand is not entered. SHR data sets are retained by the system when you free them. The DATASET or DSNAME operand is required.

MOD

indicates you want to append data to the end of the sequential data set. Do not catalog the data set or specify VOLUME=SER when you use DISP=MOD to create a new data set. After creation, the system changes the disposition of the data set to NEW. If the data set does not exist, a new data set is created and the disposition is changed to NEW. MOD data sets are retained by the system when you free them. The DATASET or DSNAME operand is required.

NEW

(non-VSAM only, unless SMS is running) indicates the data set does not exist and it is to be created. For new partitioned data sets, you must specify the DIR operand unless its data class provides a default value for it. For more information, see z/OS DFSMSdfp Storage Administration. If you specify a data set name, a NEW data set is kept and cataloged. If you do not specify a data set name, it is deleted when you free it or log off.

SMS will only manage data sets that were allocated with a disposition of NEW while SMS was active.

SYSOUT[(class)]

indicates the data set is to be a system output data set. An optional subfield can be defined giving the output class of the data set. Output data is initially directed to the job entry subsystem (JES) and can later be transcribed to a final output device. The final output device is associated with output class by the installation. After transcription by the job entry subsystem, SYSOUT data sets are deleted.

The system generates names for SYSOUT data sets; therefore, you should not specify a data set name when you allocate a SYSOUT data set. If you do, the system ignores it.

You can specify the OUTDES operand of the ALLOCATE command or the PRINTDS command to supply the name or names of the output descriptors that were created by the OUTPUT JCL statements in the LOGON procedure. Specifying OUTDES eliminates the need to supply information related to the printer or the type of printing to be done. For more information about establishing OUTPUT JCL statements in the LOGON procedure, see z/OS TSO/E Customization.

If you do not specify an output class value, the ALLOCATE command uses the default output class, which was determined during logon for your user ID. If no default class was set for your user ID, JES assigns an output class according to its assignment procedures, using any referenced or default output descriptors.

For information about how a sysout class is chosen, especially when an output descriptor is specified, see Determining the SYSOUT class.

If you want to allocate a SYSOUT data set, the following operands are used exclusively with SYSOUT:

ALLOCATE DDNAME, SYSOUT, DEST, HOLD, NOHOLD, COPIES, BURST/NOBURST,
CHARS, FLASH, MODIFY, FCB, FORMS, OUTDES, UCS, WRITER, SPIN, SEGMENT

If you do not specify OLD, SHR, MOD, NEW, or SYSOUT, a default value is assigned or a value is prompted for, depending on the other operands specified:

If the LIKE operand or any space operands (SPACE, DIR, BLOCK, BLKSIZE, AVBLOCK, TRACKS, or CYLINDERS) are specified, then the status defaults to NEW.
If the COPIES operand is specified, then the status defaults to SYSOUT.
If the DATASET/DSNAME operand is entered without the LIKE operand or any space operands, then the status defaults to OLD.
If the LIKE operand, the DATASET/DSNAME operand, and the space operands are all omitted, you are prompted to enter a status value.

VOLUME(serial_list)

specifies the serial number(s) of an eligible direct access volume(s) on which a new data set is to reside or on which an old data set is located. If you specify VOLUME for an old data set, the data set must be on the specified volume(s) for allocation to take place. If you do not specify VOLUME, new data sets are allocated to any eligible direct access volume. Eligibility is determined by the UNIT information in your procedure entry in the user attribute data set (UADS). You can specify up to 255 volume serial numbers.

With SMS, the VOLUME operand is not suggested. The system determines the UNIT and VOLUME from the storage class (STORCLAS operand) associated with the data set. If SMS does not manage the data set and you want to allocate a data set to a specific volume, explicitly specify VOLUME.

DATACLAS(data_class_name)

if SMS is active, specifies the name, 1 to 8 characters, of the data class for the data set. The data set does not have to be managed by SMS.

Using the DATACLAS operand to define the data class makes specifying all the attributes for a data set unnecessary. For example, the storage administrator might provide RECFM, LRECL, RECORG, KEYLEN, and KEYOFF as part of the data class definition. However, you can override the DATACLAS operand by explicitly specifying the appropriate operands on the ALLOCATE command. If you specify DATACLAS for an existing data set, SMS ignores it.

The data class defines the following data set allocation attributes:

Data set organization (record organization or record format):
- Record organization (RECORG)
- Record format (RECFM)
Record length (LRECL)
Key length (KEYLEN)
Key offset (KEYOFF)
Space allocation
- AVGREC
- SPACE
Expiration date (EXPDT) or retention period (RETPD)
Volume number (VOLUME)
For VSAM data sets, the following:
- IMBED or REPLACE
- CISIZE
- FREESPACE
- SHAREOPTIONS

Note: Without SMS, the system syntax checks and then ignores the DATACLAS operand.

MGMTCLAS(management_class_name)

with an SMS-managed data set, specifies the name, 1 to 8 characters, of the management class for a new data set. When possible, do not specify MGMTCLAS. Instead, use the default your storage administrator provides through the ACS routines.

After the data set is allocated, attributes in the management class control the following:

The migration of the data set, which includes migration from primary storage to Data Facility Storage Management Subsystem Hierarchical Storage Manager (DFSMShsm) owned storage to archival storage.
The backup of the data set, which includes frequency of backup, number of versions, and retention criteria for backup versions.

Note: Without SMS, the system syntax checks and then ignores the MGMTCLAS operand.

STORCLAS(storage_class_name)

with SMS, specifies the name, 1 to 8 characters, of the storage class. If you have no specific storage class requirements, do not specify STORCLAS. Instead, use the default your storage administrator provides through the ACS routines.

The storage class replaces the storage attributes that are specified on the UNIT and VOLUME operand for non-SMS-managed data sets.

An "SMS-managed data set" is defined as a data set that has a storage class assigned. A storage class is assigned when the installation-written ACS routine selects a storage class for the new data set.

Note: Without SMS, the system syntax checks and then ignores the STORCLAS operand.

SPACE(quantity,increment)

specifies the amount of space to be allocated when creating or extending a DASD data set.

quantity: specifies the number of units of space to be allocated initially when creating or extending a DASD data set.
increment: specifies the number of units of space to be added to the data set each time the previously allocated space has been filled. You must specify the primary quantity along with the increment value.

SPACE can be specified for SYSOUT, NEW, and MOD data sets. The SPACE parameter has no effect if SYSOUT is coded also.

If you omit this operand, the system uses the first of the following sources that provides values:

Your installation might change the value for SPACE or set a default by using the IEFDB401 exit routine. See z/OS MVS Installation Exits.
A data class can specify space values. You can specify a data class name with the DATACLAS keyword or SMS can provide one. The data set does not have to be SMS-managed. In addition your storage administrator can use SMS to override the data class name that you code.
Your installation might have set a default for SPACE using the ALLOCxx PARMLIB member. See z/OS MVS™ Initialization and Tuning Reference.
If none of the above sources provides a value for SPACE, the IBM-supplied default is SPACE(4,24) AVBLOCK(8192).

With SMS, the system does not prompt you for the space. To have the system obtain the amount of space, specify both the AVGREC and AVBLOCK operand.

Specifying AVGREC requires you to also specify an average record length. You can use the AVBLOCK keyword. If you do not specify BLOCK or BLKSIZE, the system determines the optimized value.

When you specify SPACE, you must specify a unit of space. To indicate the unit of space for allocation, you must specify one of the following:

BLOCK(value)
BLKSIZE(value)
AVBLOCK(value)
TRACKS
CYLINDERS

The amount of space requested is determined as follows:

BLOCK(value) or BLKSIZE(value): Multiply the value of the BLOCK/BLKSIZE operand by the quantity value of the SPACE operand. With SMS, if you do not specify BLKSIZE, the system determines an optimum DCB block size for the new data set.
AVBLOCK(value): Multiply the value of the AVBLOCK operand by the quantity value of the SPACE operand. The AVBLOCK is the average logical record length and should be coded with the AVGREC(U, K, or M) operand.
TRACKS: The quantity value of the SPACE operand is the number of tracks you are requesting.
CYLINDERS: The quantity value of the SPACE operand is the number of cylinders you are requesting.

See the preceding information concerning the AVGREC operand about how the amount of space is determined for each of these keywords.

BLOCK(value)

specifies the average length of the blocks written to the data set. The maximum block value used to determine space to be allocated is 65,535. The block value is the unit of space used by the SPACE operand. A track or a cylinder on one device can represent a different amount of storage (number of bytes) than a track or a cylinder on another device. The unit of space value is determined in one of the following ways:

From the default value, which is SPACE (4,24) AVBLOCK (8192), when no space operands (that is, SPACE, BLOCK, TRACKS, AVBLOCK, or CYLINDERS) are specified.
From the BLOCK operand, if specified.
From the model data set, if the LIKE operand is specified and BLOCK, TRACKS, AVBLOCK, or CYLINDERS are not specified on ALLOCATE. This is true only when SMS is inactive. When SMS is active, LIKE does not retrieve the unit of space(CYL/TRK/BLK) from the model data set.
From the BLKSIZE operand, if BLOCK is not specified.

Note that the default value for space is installation dependent. Your installation might have changed the default value.

If you do not specify BLKSIZE, the system attempts to determine an optimum DCB block size for the new data set.

AVBLOCK(value)

specifies the average length (in bytes) of the records that are written to the data set. This parameter only has an effect if SPACE is specified.

With SMS, to allocate space in a quantity of records instead of blocks, tracks, or cylinders, use both the AVBLOCK and AVGREC operands. Do not code the BLOCK, TRACKS, or CYLINDERS operands.

TRACKS

specifies the unit of space is to be a track. This parameter only has an effect if SPACE is specified.

With SMS, if you do not want to explicitly specify TRACKS, specify both the AVGREC and AVBLOCK operands instead of the TRACKS operand.

CYLINDERS

specifies the unit of space is to be a cylinder. This parameter only has an effect if SPACE is specified.

With SMS, if you do not want to explicitly specify CYLINDERS, specify both the AVGREC and AVBLOCK operands instead of the CYLINDERS operand.

AVGREC(U | K | M)

together with AVBLOCK in SMS, determines the size of the average record length. This parameter only has an effect if SPACE is specified. Following are the values for AVGREC:

U: Use the primary and secondary space quantities specified on the SPACE operand.
K: Multiply primary space quantity and secondary space quantity specified on the SPACE operand by 1024 (1 K).
M: Multiply primary space quantity and secondary space quantity specified on the SPACE operand by 1,048,576 (1 M).

For example, if you want to allocate 12 mega units of space, you can specify SPACE(12) AVGREC(M), which results in 12 * 1,048,576 = 12,582,912.

To get a secondary space quantity, you need to specify SPACE(12,1) AVGREC(M). This specification provides 12 mega units of primary space and 1 mega unit of secondary space. The unit of space is determined by either BLOCK, BLKSIZE, or AVBLOCK.

If AVGREC(K), AVBLOCK(128), and SPACE(5,2) are specified, the average record length is 128, the primary quantity of records is 5K, and the second quantity of records is 2K.

BLKSIZE(blocksize)

specifies the block size for the data set. The maximum allowable decimal value for block size recorded in the DCB is 32,760.

With DASD, labeled tape or spooled data set, or a TSO terminal, if you do not specify BLKSIZE, the system determines the optimum block size for the new data set unless you have undefined length records. For more information see z/OS DFSMS Using Data Sets.

The DCB block size is determined in one of the following ways:

If USING is specified, from the attribute list. You cannot use the BLKSIZE operand on ALLOCATE for the block size.
If you specify BLKSIZE on ALLOCATE, from the BLKSIZE operand.
If LIKE is specified and BLKSIZE is not specified on ALLOCATE, from the model data set.
With SMS, BLKSIZE is not copied from the model data set. Without SMS, BLKSIZE is copied from the model data set.
If neither USING, BLKSIZE, nor LIKE is specified, from the BLOCK operand.

The block size that you specify to be recorded in the data control block (DCB) must be consistent with the requirements of the RECFM operand:

RECFM(F) – the block size must be equal to the logical record length.
RECFM(F,B) – the block size must be an integral multiple of the logical record length.
RECFM(V) – the block size must be equal to or greater than the largest block in the data set. (Note: For unblocked variable-length records, the size of the largest block must allow space for the four-byte block descriptor word in addition to the largest logical record length. The logical record length must allow space for a four-byte record descriptor word.)
RECFM(V,B) – the block size must be equal to or greater than the largest block in the data set. For block variable-length records, the size of the largest block must allow space for the four-byte block descriptor word in addition to the sum of the logical record lengths that will go into the block. Each logical record length must allow space for a four-byte record descriptor word. Because the number of logical records can vary, you must estimate the optimum block size and the average number of records for each block based on your knowledge of the application that requires the I/O.
RECFM(U) – for files allocated to the TSO/E terminal with RECFM(U) and BLKSIZE(80), one character is truncated from the line. That character (the last byte) is reserved for an attribute character.
Specify BLKSIZE with the ALLOCATE command when using the LIKE operand, because optimal BLKSIZE is not determined by the system for a RECFM(U) data set.

The operands BLOCK, BLKSIZE, AVBLOCK, TRACKS, and CYLINDERS can be specified for SYSOUT, NEW, or MOD data sets. The operands BLOCK or BLKSIZE can also be specified for dummy or terminal data sets.

DIR(integer)

specifies the number of 256 byte records that are to be allocated for the directory of a new partitioned data set. This operand must be specified if you are allocating a new partitioned data set. Generally it is not useful for a PDSE.

ALTFILE(name)

specifies the name associated with the SYSIN subsystem data set that is to be allocated. It can contain up to 8 characters. This operand is used primarily in the background.

DEST({destination | destination.user_id})

specifies a specific remote workstation or a user at a specific remote workstation to which SYSOUT data sets are directed upon deallocation. Specify 1 to 8 characters for either the destination or the user ID.

REUSE

specifies the file name being allocated is to be freed and reallocated if it is currently in use.

When you allocate a data set with file name or ddname, give it a disposition of SHR or OLD. You cannot use the REUSE operand to reallocate a file from a disposition of OLD to a disposition of SHR. However, you can first free the file with a disposition of OLD, then reallocate it with a disposition of SHR.

HOLD | NOHOLD

HOLD: specifies the data set is to be placed on a HOLD queue upon deallocation.
NOHOLD: specifies processing of the output should be determined by the HOLD/NOHOLD specification associated with the particular SYSOUT class specified. However, the specification associated with the SYSOUT class can be overridden by using the NOHOLD operand on the FREE command.

UNIT(type)

specifies the type of the unit to which a file or data set is to be allocated. You can specify an installation-defined group name, a generic device type, or a specific device number.

This distinguishes numeric-only device numbers from generic device types that contain only four-character numerics.

If volume information is not supplied (volume and unit information is retrieved from a catalog), the unit type that is coded overrides the unit type from the catalog.

If the data set is managed by SMS, the UNIT operand is not suggested. The system determines the UNIT and VOLUME from the storage class associated with the data set. If the storage administrator has set up a default unit type under SMS regardless of whether the data set is SMS-managed, you do not have to specify UNIT.

Without SMS, if you do not specify UNIT, the default UNIT is obtained from the user attribute data set (SYS1.UADS) or the security system being used (if SYS1.UADS is not being used).

The default specification for the UNIT operand relates to the LOGON procedure selected in the foreground. If the ALLOCATE command is to be executed in the background, and the UNIT operand is not specified, the default operand value is not obtained from the user attribute data set (SYS1.UADS) or the security system. See the z/OS TSO/E User's Guide, for a description of command processing differences when executing foreground commands from a background job.

UCOUNT(count)

specifies the maximum number of devices to be allocated, where count is a value from 1-59.

PARALLEL

specifies one device is to be mounted for each volume specified on the VOLUME operand or in the catalog. This is meaningful only for magnetic tape.

LABEL(type)

specifies the kind of label processing to be done. Type can be one of the following: SL, SUL, AL, AUL, NSL, NL, LTM, or BLP. These types correspond to the JCL label-type values.

ACCODE(access_code)

specifies or changes the accessibility code for an ISO/ANSI labeled output tape data set. The purpose of the code is to protect the ANSI data set from unauthorized use. Up to 8 characters (A-Z) are permitted in the access code, but only the first character is validated by ANSI. The first character must be an uppercase alphabetic character. An installation exit routine validates it. That routine is described in z/OS MVS Installation Exits.

POSITION(sequence_no.)

specifies the relative position (1- 65535) of the data set on a multiple data set tape. The sequence number corresponds to the data set sequence number field of the label operand in JCL.

MAXVOL(count)

specifies the maximum number of volumes that the data set can reside upon. For DASD, the maximum value is 59. For magnetic tapes, the maximum value is 255. This number corresponds to the count field on the VOLUME operand in JCL.

PRIVATE

specifies the private volume use attribute be assigned to a volume that is not reserved or permanently in resident. This operand corresponds to the PRIVATE keyword of the VOLUME operand in JCL.

If VOLUME and PRIVATE operands are not specified and the value specified for MAXVOL exceeds the value specified for UCOUNT, the system does not demount any volumes when all of the mounted volumes have been used, causing abnormal termination of your job. If PRIVATE is specified, the system demounts one of the volumes and mounts another volume in its place so that processing can continue.

VSEQ(vol_seq_no.)

specifies at which volume (1-255) of a multi-volume data set processing is to begin. This operand corresponds to the volume sequence number on the VOLUME operand in JCL.

LIKE(model_dsname)

specifies the name of an existing model data set whose attributes are to be used as the attributes of the new data set being allocated. This data set must be cataloged and must reside on a direct access device. The volume must be mounted when you issue the ALLOCATE command.

If SMS is active in the system, ALLOCATE assigns attributes to a new data set by copying all of the following attributes from the model data set:

Primary space quantity (SPACE)
Secondary space quantity (SPACE)
Space unit (BLOCK, AVBLOCK, TRACKS, CYLINDERS)
AVGREC unit (KB, megabyte)
Directory space quantity (DIR)
Data set organization:
- RECORG for a VSAM data set
- DSORG for a non-VSAM data set
Logical record length (LRECL)
Key length (KEYLEN)
Record format (RECFM)
Key offset (KEYOFF)
Data set type (DSNTYPE)
Extended attribute status (EATTR)

Note, however, that if SMS is active, the following attributes are not copied:

Optional services code (OPTCD) - for ISAM data sets only
Block size (BLKSIZE)
Volume sequence number (VSEQ)
Data set expiration date (EXPDT)

You can use the LIKE operand even if none of your existing data sets have the exact attribute values you want to use for a new data set. You can override attributes copied from a model data set by specifying the LIKE operand and the operands corresponding to the attributes you want to override on the ALLOCATE command.

The following items should be considered when using the LIKE operand:

NEW is the only valid data set status that can be specified with the LIKE operand.
The LIKE operand must be specified with the DATASET operand.
Only one data set name can be specified on the DATASET/DSNAME operand.
With SMS, block size is not copied from the model data set. If you do not specify the block size, the system determines the optimal block size for the data set, unless the data set has RECFM(U).
The attributes copied from the model data set override attributes from the data class.
If the new data set to be allocated is specified with a member name, indicating a partitioned data set (PDS), then you are prompted for directory blocks unless that quantity is explicitly specified on the ALLOCATE command or defaulted from the LIKE data set.
If the new data set name is specified with a member name, but the model data set is sequential and you have not explicitly specified the quantity for directory blocks, then you are prompted for directory blocks.
If you specify the directory value as zero and the model data set is a partitioned data set, then the new data set is allocated as a sequential data set.
Unless you explicitly code the SPACE operand for the new data set, the system determines the space to be allocated for the new data set by adding up the space allocated in the first three extents of the model data set. Therefore, the space allocated for the new data set will generally not match the space that was specified for the model data set. Also, the system allocates the space for the new data set in tracks.
Without SMS, the DSNTYPE keyword must be specified in order to allocate a PDSE data set.

USING(attr_list_name)

specifies the name of a list of attributes that you want to have assigned to the data set you are allocating. The attributes in the list correspond to, and are used for, data control block (DCB) operands. (Note to users familiar with batch processing: These DCB operands are the same as those normally specified by using JCL and data management macro instructions.)

An attribute list must be stored in the system before you use this operand. You can build and name an attribute list by using the ATTRIB command. The ATTRIB command allocates a file with the name being the (attr_list_name) specified in the ATTRIB command. The name that you specify for the list when you use the ATTRIB command is the name that you must specify for this USING(attr_list_name) operand.

USING, LIKE, and REFDD are mutually exclusive.

Note: You cannot specify the DCB operands (operands that are also on the ATTRIB command) with the USING operand.

REFDD(file_name)

if SMS is active, specifies the ddname of an existing data set whose attributes are copied to the new data set. The following attributes are copied to the new data set:

Data set organization (record organization or record format):
- Record organization (RECORG)
- Record format (RECFM)
Directory space quantity (DIR)
Record length (LRECL)
Key length (KEYLEN)
Key offset (KEYOFF)
Space allocation:
- AVGREC
- SPACE
- TRACK, CYLINDER, BLOCK

When you allocate a data set with REFDD, specify a disposition of NEW. For example,

alloc da('user1.my.text') fi(dd1) shr reu
alloc f(dd2) da('user2.your.data') new refdd(dd1)

USER1.MY.TEXT is an existing and cataloged data set. Note that the block size (BLKSIZE) is not copied to the new data set USER2.YOUR.DATA.

The retention period (RETPD) or expiration date (EXPDT) is not copied to the new data set.

The LIKE, REFDD, and USING operands are mutually exclusive.

Note: Without SMS, the system syntax checks and ignores the REFDD operand.

SECMODEL(profile_name[,GENERIC])

specifies the name of an existing RACF® data set profile, the attributes of which will be copied to the discrete profile. Use SECMODEL when you want a different RACF data set profile than the default profile selected by RACF, or when there is no default profile. The model profile can be one of the following profiles:

RACF model profile
RACF discrete data set profile
RACF generic data set profile

GENERIC identifies that the profile name is a generic data set profile. For example, if you want to create a generic data set profile, specify SECMODEL(profile_name,GENERIC).

The following information from the RACF data set profile is copied to the discrete data set profile of the new data set:

OWNER indicates the user or group assigned as the owner of the data set profile.
ID indicates the access list of users or groups authorized to access the data set.
UACC indicates the universal access authority associated with the data set.
AUDIT/GLOBALAUDIT indicates which access attempts are logged.
ERASE indicates that the data set is to be erased when it is deleted (scratched).
LEVEL indicates the installation-defined level indicator.
DATA indicates installation-defined information.
WARNING indicates that an unauthorized access causes RACF to issue a warning message, but allows access to the data set.
SECLEVEL indicates the name of an installation-defined security level.

Note: Without SMS, the system syntax checks and ignores the SECMODEL operand.

For more information about RACF, see z/OS Security Server RACF Command Language Reference.

RELEASE

specifies unused space is to be deleted when the data set is closed.

If you use RELEASE for a new data set with the BLOCK or BLKSIZE operand, then you must also use the SPACE operand.

ROUND

specifies the allocated space be equal to one or more cylinders. This operand should be specified only when space is requested in units of blocks. This operand corresponds to the ROUND operand on the SPACE parameter in JCL.

KEEP | DELETE | CATALOG | UNCATALOG

KEEP ¹: specifies the data set is to be retained by the system after it is freed. If the data set is SMS-managed, KEEP has the same effect as CATALOG.
DELETE ¹: specifies the data set is to be deleted after it is freed. If the data set is SMS-managed, DELETE also forces UNCATALOG.
CATALOG ¹: specifies the data set is to be retained by the system in a catalog after it is freed.
UNCATALOG ¹: specifies the data set is to be removed from the catalog after it is freed. If the data set is not SMS-managed and you do not want the system to retain the data set, you must also specify the DELETE operand.

BUFL(buffer_length)

specifies the length, in bytes, of each buffer in the buffer pool. Substitute a decimal number for buffer_length. The number must not exceed 32,760.

If you omit this operand and the system acquires buffers automatically, the BLKSIZE and KEYLEN operands are used to supply the information needed to establish buffer length.

BUFNO(number_of_buffers)

specifies the number of buffers to be assigned for data control blocks. Substitute a decimal number for number_of_buffers. The number must never exceed 255, and you can be limited to a smaller number of buffers depending on the amount of available virtual storage. The following table shows the condition that requires you to include this operand.

When you use one of the following methods of obtaining the buffer pool, then:

(1) BUILD macro instruction

(1) You must specify BUFNO.

(2) GETPOOL macro instruction

(2) The system uses the number that you specify for GETPOOL.

(3) Automatically with BPAM or BSAM

(3) You must specify BUFNO if the program was designed to use buffers obtained during OPEN.

(4) Automatically with QSAM

(4) You may omit BUFNO and accept the system default, which is five or one, except with an extended format data set. For more information see z/OS DFSMS Using Data Sets.

LRECL({logical_record_length | X | nnnnnK})

specifies the length, in bytes, of the largest logical record in the data set. You must specify this operand for data sets that consist of either fixed-length or variable-length records.

If SMS is active, you can use the DATACLAS operand in place of LRECL to specify the logical record length. If you specify LRECL, the system determines the block size.

The logical record length must be consistent with the requirements of the RECFM operand and must not exceed the block size (BLKSIZE operand) except for variable-length spanned records. If you specify:

RECFM(V) or RECFM(V B), then the logical record length is the sum of the length of the actual data field plus four bytes for a record descriptor word.
RECFM(F) or RECFM(F B), then the logical record length is the length of the actual data fields.
RECFM(U), then you should omit the LRECL operand.

LRECL(nnnnnK) allows users of ISO/ANSI extended logical records and QSAM locate mode users to specify a K multiplier on the LRECL operand. nnnnn can be a number within 1-16,384. The K indicates that the value is multiplied by one thousand and twenty-four (1024).

For variable-length spanned records (VS or VBS) processed by QSAM (locate mode) or BSAM, specify LRECL (X) when the logical record exceeds 32756 bytes.

NCP(number_of_channel_programs)

specifies the maximum number of READ or WRITE macro instructions allowed before a CHECK or WAIT macro instruction is issued. The maximum number must not exceed 255 and must be less than 255 if the address space does not have enough virtual storage. If you are using chained scheduling, you must specify an NCP value greater than 1. If you omit the NCP operand, the default value is 1.

INPUT

specifies a BSAM data set opened for INOUT or a BDAM data set opened for UPDAT is to be processed for input only. This operand overrides the INOUT (BSAM) option or UPDAT (BDAM) option in the OPEN macro instruction to INPUT. This is useful if you only have READ access authority to the data set.

OUTPUT

specifies a BSAM data set opened for OUTIN or OUTINX is to be processed for output only. This operand overrides the OUTIN option in the OPEN macro instruction to OUTPUT or the OUTINX option in the OPEN macro instruction to EXTEND.

EXPDT(year_day)

specifies the data set expiration date. Specify the year and day in one of two forms:

yyddd, where yy is the last two-digit number for the year and ddd is the three-digit number for the day of the year. The maximum value for the year is 99 (for 2099). The minimum value for the day is 000 and the maximum value is 366.
yyyy/ddd, where yyyy is the four-digit number for the year and ddd is the three-digit number for the day of the year. The slash is required. The maximum value for the year is 2155. The minimum value for the day is 000 and the maximum value is 366.

EXPDT is mutually exclusive with RETPD.

If SMS is active, the expiration date might have been defined by the DATACLAS operand.

RETPD(number_of_days)

specifies the data set retention period in days. The value can be a five-digit decimal number with a current maximum value of 93000.

RETPD is mutually exclusive with EXPDT.

BFALN({F | D})

specifies the boundary alignment of each buffer as follows:

F: Each buffer starts on a fullword boundary that might not be a doubleword boundary.
D: Each buffer starts on a doubleword boundary.

If you do not specify this operand, the system defaults to a doubleword boundary.

OPTCD(A, B, C, E, F, H, J, Q, R, T, W, and Z or all)

specifies the following optional services that you want the system to perform. For a detailed discussion of these services, see the OPTCD subparameter of the DCB parameter in z/OS MVS JCL Reference and z/OS DFSMS Macro Instructions for Data Sets.

A: specifies the actual device addresses be presented in READ and WRITE macro instructions.
B: specifies the end-of-file (EOF) recognition be disregarded for tapes.
C: specifies the use of chained scheduling.
E: requests an extended search for block or available space.
F: specifies feedback from a READ or WRITE macro instruction should return the device address in the form it is presented to the control program.
H: requests the system to check for and bypass embedded VSE checkpoint records on tape.
J: specifies the character after the carriage control character is the table reference character for that line. The table reference character tells TSO/E which character arrangement table to select when printing the line.
Q: requests the system to translate a magnetic tape from ASCII to EBCDIC or from EBCDIC to ASCII.
R: requests the use of relative block addressing.
T: requests the use of the user totaling facility.
W: requests the system to perform a validity check when data is written on a direct access device.
Z: requests the control program to shorten its normal error recovery procedure for input on magnetic tape.

You can request any or all of the services by combining the values for this operand. You can combine the characters in any sequence, being sure to separate them with blanks or commas.

EROPT({ACC | SKP | ABE})

specifies the option you want to execute if an error occurs when a record is read or written. The options are:

ACC: to accept the block of records in which the error was found.
SKP: to skip the block of records in which the error was found.
ABE: to end the task abnormally.

BFTEK({S | E | A | R})

specifies the type of buffering that you want the system to use. The types that you can specify are:

S: Simple buffering
E: Exchange buffering
A: Automatic record area buffering
R: Record buffering.

RECFM(A, B, D, F, M, S, T, U, and/or V)

specifies the format and characteristics of the records in the data set. The format and characteristics must be completely described by one source only. If they are not available from any source, the default is an undefined-length record. For a discussion of the formats and characteristics of the RECFM subparameter of the DCB parameter, see z/OS MVS JCL Reference.

Use the following values with the RECFM operand:

A: indicates the record contains ASCII printer control characters.
B: indicates the records are blocked.
D: indicates variable-length ASCII records.
F: indicates the records are of fixed-length.
M: indicates the records contain machine code control characters.
S: indicates, for fixed-length records, the records are written as standard blocks (there must be no truncated blocks or unfilled tracks except for the last block or track). For variable-length records, a record might span more than one block. Exchange buffering, BFTEK(E), must not be used.
T: indicates the records can be written onto overflow tracks, if required. Exchange buffering, BFTEK(E), or chained scheduling, OPTCD(C), cannot be used.
U: indicates the records are of undefined-length.
V: indicates the records are of variable-length.

You can specify one or more values for this operand; at least one is required. If you use more than one value, you must separate each value with a comma or a space.

With SMS, the record format for a new data set might have been defined by the DATACLAS operand.

RECFM is mutually exclusive with RECORG.

DIAGNS(TRACE)

specifies the Open/Close/EOV trace option that gives a module-by-module trace of the Open/Close/EOV work area and your DCB.

LIMCT(search_number)

specifies the number of blocks or tracks to be searched for a block or available space. The number must not exceed 32,760.

BUFOFF({block_prefix_length | L})

specifies the buffer offset. The block prefix length must not exceed 99. L specifies the block prefix field is four bytes long and contains the block length.

DSORG({DA | DAU | PO | POU | PS | PSU})

specifies the data set organization as follows:

DA: Direct access
DAU: Direct access unmovable
PO: Partitioned organization
POU: Partitioned organization unmovable
PS: Physical sequential
PSU: Physical sequential unmovable

When you allocate a new data set and you do not specify the DSORG operand, DSORG defaults to partitioned organization (PO) if you specify a non-zero value for the DIR operand. If you do not specify a value in the DIR operand, the system assumes you want a physical sequential (PS) data set. Note that the system does not store this default DSORG information into the data set until a program opens and writes to the data set. For more information about data set organization, see z/OS MVS Programming: Authorized Assembler Services Guide.

DEN({0 | 1 | 2 | 3 | 4})

specifies the magnetic tape density as follows:

0: 200 bpi/7 track
1: 556 bpi/7 track
2: 800 bpi/7 and 9 track
3: 1600 bpi/9 track
4: 6250 bpi/9 track (IBM® 3420 Models 4, 6, and 8, or equivalent)

TRTCH({C | E | T | ET}, {COMP | NOCOMP})

specifies the recording technique for 7 or 18 track tape as follows:

C: Data conversion with odd parity (the default) and no translation (the default).
E: Even parity with no translation (the default) and no conversion (the default).
T: Odd parity (the default) and no conversion (the default). BCD to EBCDIC translation when reading and EBCDIC to BCD translation when writing.
ET: Even parity, and no conversion (the default). BCD to EBCDIC translation when reading and EBCDIC to BCD translation when writing.
COMP| NOCOMP: specifies whether data sets are to be compressed with IDRC to save space in tape.

This operand is mutually exclusive with KEYLEN.

KEYLEN(bytes)

specifies the length in bytes of each of the keys used to locate blocks of records in the data set when the data set resides on a direct access device. The key length must not exceed 255 bytes for a record organization of physical sequential (PS) or partitioned (PO).

If an existing data set has standard labels, you can omit this operand and let the system retrieve the key length from the standard label. If a key length is not supplied by any source before you issue an OPEN macro instruction, a length of zero (no keys) is assumed. This operand is mutually exclusive with TRTCH.

If SMS is active, the key length might have been defined by the DATACLAS operand. If you want to override it, explicitly specify KEYLEN. The number of bytes is as follows:

1 to 255 for a record organization of key-sequenced (RECORG(KS)).
0 to 255 for a record organization of physical sequential (PS) or partitioned (PO).

KEYOFF(offset)

if SMS is active, specifies the key position (offset) of the first byte of the key in each record. If you want to specify key offset or override the key offset defined in the data class (DATACLAS) of the data set, use KEYOFF. Specify KEYOFF only for a VSAM key-sequenced data set (RECORG(KS)).

Note: Without SMS, the system syntax checks and then ignores the KEYOFF operand.

RECORG({ES | KS | LS | RR})

if SMS is active, specifies the organization of the records in a new VSAM data set. If you want to override the record organization defined in the data class (DATACLAS) of the data set, use RECORG. The types that you can specify are:

ES: specifies a VSAM entry-sequenced data set.
KS: specifies a VSAM key-sequenced data set.
LS: specifies a VSAM linear space data set.
RR: specifies a VSAM relative record data set.

If you are using DATACLAS in place of RECORG, explicitly specify valid LRECL and KEYLEN values for a VSAM key-sequenced data set (RECORG(KS)).

If you do not specify RECORG, SMS assumes a physical sequential (PS) or partitioned (PO) data set.

RECORG is mutually exclusive with RECFM.

Note: Without SMS, the system syntax checks and then ignores the RECORG operand.

PROTECT

specifies the DASD data set or the first data set on a tape volume is to be RACF protected.

For a new permanent DASD data set, the specified status must be NEW or MOD, treated as NEW, and the disposition must be either KEEP, CATALOG, or UNCATALOG. With SMS, SECMODEL overrides PROTECT.
For a tape volume, the tape must have an SL, SUL, AL, AUL, or NSL label. The file sequence number and volume sequence number must be one (except for NSL), and PRIVATE must be assigned as the tape volume use attribute.

The PROTECT operand is not valid if a data set name is not specified or if the FCB operand or status other than NEW or MOD is specified.

COPIES((number)[,group_value])

specifies the total number of copies of the data set to be printed, with an optional specification on the IBM 3800 printer as to how those copies can be grouped. Number is a required operand. The number of copies which can be requested is subject to an installation limit. You can specify up to 8 group values. For more information, see z/OS MVS JCL Reference.

Do not specify the COPIES operand with the DATASET operand.
SYSOUT is the only valid data set status that you can specify with the COPIES operand.

BURST | NOBURST

specifies a request for the burster-trimmer-stacker on IBM 3800 or 3900 output. SYSOUT is the only valid data set status that you can specify with the BURST operand.

CHARS(table_name)

specifies a request for name or names of character arrangement tables (fonts) for printing a data set with the IBM 3800 or 3900 printer. You can specify up to 4 table names. The choice of fonts available is determined by your installation at system generation time. SYSOUT is the only valid data set status that you can specify with the CHARS operand.

FLASH(overlay_name[,copies])

specifies the name of a forms overlay, which can be used by the IBM 3800 or 3900 Printing Subsystem. The overlay is "flashed" on a form or other printed information over each page of output. The forms overlay_name must be 1 to 4 alphabetic, numeric, or special characters (#, $, or @). Optionally, you can specify the number of copies on which the overlay is to be printed. The count can range from 0 to 255. To flash no copies, specify a count of zero. SYSOUT is the only valid data set status that you can specify with the FLASH operand.

MODIFY(module_name[:trc])

specifies the name of a copy modification module, which is loaded into the IBM 3800 or 3900 Printing Subsystem. This module contains predefined data such as legends, column headers, or blanks, and specifies where and on which copies the data is to be printed. The IEBIMAGE utiliy program is used to define and store the module in SYS1.IMAGELIB. The module_name can contain 1 to 4 alphanumeric or special characters (#, $, or @.)

MODIFY is used with FLASH so that individual pages can be tailored with the MODIFY operand from the basic form of pages created by the FLASH operand.

The table reference character (trc ) corresponds to the character set(s) specified on the CHARS operand. Values are 0 for the first table-name, 1 for the second, 2 for the third, or 3 for the fourth. If trc is not specified, a default character set is used. If trc is used, CHARS must also be specified.

SYSOUT is the only valid data set status that you can specify with the MODIFY operand.

FCB(image_id[ | VERIFY | ALIGN])

specifies a forms control buffer (FCB) that is used to store vertical formatting information for printing, each position corresponding to a line on the form. The buffer determines the operations of the printer. It specifies the forms control image to be used to print an output data set on an IBM 3800 printer or 3211 printer. The FCB also specifies the data protection image to be used for the IBM 3525 card punch. The FCB operand is ignored for SYSOUT data sets on the 3525 card punch.

For further information about the forms control buffer, see z/OS DFSMSdfp Advanced Services, Programming Support for the IBM 3505 Card Reader and IBM 3525 Card Punch or IBM 3800 Printing Subsystem Programmer's Guide.

image_id

specifies 1-to-4 alphanumeric or the special characters #, $, or @ that identify the image to be loaded into the forms control buffer (FCB).

For a 3211 printer, IBM provides two standard FCB images, STD1 and STD2. STD1 specifies that 6 lines per inch are to be printed on an 8.5 inch form. STD2 specifies that 6 lines per inch are to be printed on a 11 inch form.
For a 3800 Printing Subsystem, IBM provides another standard FCB image, STD3, which specifies output of 80 lines per page at 8 lines per inch on 11 inch long paper.

STD1 and STD2 (standard FCB images) should not be used as image_ids for the SYSOUT data set unless established by your installation at system generation time.

If the image_id information is incorrectly coded, the default for the 3211 printer is the image currently in the buffer. If there is no image in the buffer, the operator is requested to specify an image. For the 3800 printer, the machine default is 6 lines per inch for any size form that is on the printer.

ALIGN

specifies the operator should check the alignment of the printer forms before the data set is printed. The ALIGN subparameter is ignored for SYSOUT data sets and is not used by the 3800 printer.

VERIFY

specifies the operator should verify that the image displayed on the printer is the desired one. The VERIFY subparameter is ignored for SYSOUT data sets.

FORMS(forms_name)

specifies the name of the form on which the output from the SYSOUT data set is to be printed. Specify 1-to-4 alphanumeric or the special characters #, $, or @ for the forms name. SYSOUT is the only valid data set status that you can specify with the FORMS operand.

OUTDES(output_descriptor_name{,…})

specifies a list of installation-defined output descriptors that were created by OUTPUT JCL statements in the LOGON procedure or by the TSO/E OUTDES command. Specifying the OUTDES operand eliminates the need to supply information related to the printer or the type of printing to be done.

You can specify up to 128 output descriptors associated with the SYSOUT data set. Specify 1-to-8 alphanumeric characters for the output descriptor name. The first character must be alphabetic or one of the special characters #, $, or @. SYSOUT is the only valid data set status that you can specify with the OUTDES operand.

For information about how to create output descriptors using OUTPUT JCL statements in the LOGON procedure, see z/OS TSO/E Customization. See OUTDES command for information about using the TSO/E OUTDES command to dynamically create output descriptors.

SPIN(UNALLOC | NO)

specifies when the system should make the SYSOUT data set available for printing.

UNALLOC: specifies that the system should make the SYSOUT data set available for printing immediately after deallocation.
NO: specifies that the system should make the SYSOUT data set available for printing when you log off or at the end of the batch job.

If the SPIN keyword is not specified, ALLOCATE assumes SPIN=UNALLOC.

When the SPIN keyword is specified, you must also specify UNALLOC or NO. If you specify a parameter that is not UNALLOC or NO, or the parameter is missing, ALLOCATE will prompt you to specify the parameter.

The SPIN keyword specified on the FREE command overrides the SPIN keyword specified on the ALLOCATE command.

If the SEGMENT keyword is specified on the ALLOCATE command, the system prints the SYSOUT data set regardless of the SPIN specification on either the ALLOCATE command or FREE command.

SEGMENT(page_count)

specifies the number of pages written to the SYSOUT data set before spinoff processing begins. SEGMENT can be a number, 1-99999. You can use SEGMENT to allow part of a job's output to be printed while the job is still running, or to allow multiple segments of a job's output to print simultaneously on multiple printers. See z/OS MVS JCL Reference, for more information about the SEGMENT keyword.

DSNTYPE(LIBRARY{,1|,2}| PDS | HFS | PIPE |LARGE | BASIC | EXTREQ | EXTPREF)

specifies the type of data set to be allocated.

LIBRARY: specifies a partitioned data set extended (PDSE). LIBRARY uses the PDSE_VERSION parameter in IGDSMSxx or its default to determine which version of PDSE to allocate.
LIBRARY,1: Specifies a version 1 partitioned data set extended (PDSE).
LIBRARY,2: Specifies a version 2 partitioned data set extended (PDSE). Version 2 offers more efficient directory usage.
PDS: specifies a partitioned data set (PDS).
HFS: specifies a UNIX file system. For better performance, do not use this type of data set. Instead, define a VSAM linear data set and define a z/OS file system (zFS) in it.
PIPE: specifies a first-in first-out (FIFO) special file, which is also called a named pipe. If you specify PIPE, you must also specify PATH and not specify DATASET or DSNAME.
LARGE: specifies a large format sequential data set. It can have a size greater than 65535 tracks on a single volume.
BASIC: specifies a basic format sequential data set. It is limited to no more than 65535 tracks per volume, which is about 3.6 GB.
EXTREQ: specifies that the data set must be extended format. It can be sequential or VSAM. It can be striped, compressed format or neither.
EXTPREF: specifies that the data set should be allocated as extended format, if possible. If not possible, allocate the data set as basic format.

If you omit DSNTYPE, the type of data set is determined by other data set attributes, the data class for the data set, or an installation default.

UCS(universal_character_set_name)

specifies the universal character set name or font name to be used when printing SYSOUT data sets. The UCS name can contain up to 4 alphanumeric characters. If you do not specify the CHARS operand, the system uses the UCS operand as the default. SYSOUT is the only valid data set status that you can specify with the UCS operand unless the UNIT operand specified a directly allocated printer, not a JES-printer.

WRITER(external_writer_name)

specifies a name for use in processing or selecting a SYSOUT data set. If you specify the external writer name, the system uses it instead of JES2 or JES3. The writer name can contain 1 to 8 alphanumeric or special characters #, $, or @. SYSOUT is the only valid data set status that you can specify with the WRITER operand.

A common use of this parameter is to specify the name of an external writer routine to be used to pass JCL to JES2/JES3. For example:

WRITER(INTRDR)

PATH(pathname)

identifies a UNIX file.

A pathname consists of the names of the directories from the root to the file being identified, and the name of the file. The form is /name1/name2/…/namen.

A pathname begins with a slash (/). The system treats any consecutive slashes like a single slash. The pathname can be 2 to 250 characters, including the initial slash.

Value for a pathname consists of printable characters from X'40' to X'FE'. A filename can contain characters outside this range but these characters cannot be specified in the JCL. Enclose the pathname in apostrophes if it contains any character other than the following characters:

Uppercase letters                Numbers
Special characters (#,$, or @)   Slash (/)
Asterisk (*)                     Plus (+)
Hyphen (-)                       Period (.)
Ampersand (&)

A pathname is case sensitive. Thus, '/usr/joe' and /usr/JOE define two different files.

If you specify either OCREAT alone, or OCREAT and OEXCL, on the PATHOPTS operand and if the file does not exist, MVS performs an open() function. The options from PATHOPTS, the pathname from the PATH operand, and the options from PATHMODE (if specified) are used in the open(). MVS uses the close() function to close the file before the application program receives control.

For status group options other than OCREAT and OEXCL, the description in this book assumes that the application or OPEN macro passes the operands to the open() function without modification. That is, this application uses dynamic allocation information retrieval (the DYNALLOC macro) to retrieve the subparameters specified for PATHOPTS and passes the subparameters to the open() function or the OPEN macro does the equivalent. The application program can ignore or modify the information specified in the JCL or on the ALLOCATE command.

When the PATH operand is specified on the ALLOCATE command, you can specify only the following operands:

BLKSIZE
BUFNO
DSNTYPE
DUMMY
FILEDATA
LRECL
NCP
PATHDISP
PATHMODE
PATHOPTS
RECFM
REUSE
TERM

Note: Allocation verifies the validity of the pathname. However, there is no ENQ or locking of the pathname, so it is possible to modify a pathname component, even in an asynchronous process. Doing this may cause errors in OPEN or unexpected results with no errors reported.

Note: For programs that use a statements with the PATH keyword, do one of the following tasks:

Use dynamic allocation information retrieval to obtain the information specified for PATH, PATHOPTS and PATHMODE, and pass it to the open() callable service. See z/OS UNIX System Services Programming: Assembler Callable Services Reference, for details for using open().
Use the C/370™ fopen(//dd: ) function. fopen() handles the differences between DD statements with PATH and DSN specified. See z/OS XL C/C++ Runtime Library Referencefor details on using fopen().
Use the OPEN macro for BSAM, QSAM or VSAM as described in z/OS DFSMS Using Data Sets.

PATHDISP([normal_disposition] [, abnormal_disposition])

specifies the disposition of a UNIX file upon normal and abnormal (conditional) TSO/E session termination.

normal_disposition

indicates the disposition of the UNIX file upon normal TSO/E session termination. Valid values are:

KEEP: specifies that the file should be kept.
DELETE: specifies that the file should be deleted.

abnormal_disposition

indicates the disposition of the UNIX System Services file upon abnormal (conditional) TSO/E session termination. Valid values are:

KEEP: specifies that the file should be kept.
DELETE: specifies that the file should be deleted.

PATHMODE(file_access_attribute)

specifies the file access attributes when the PATHOPTS operand also specifies OCREAT.

If you specify either OCREAT alone, or OCREAT and OEXCL, on the PATHOPTS operand, and if the file does not exist, then MVS performs an open() function. The options from PATHOPTS, the pathname from the PATH operand, and the options from PATHMODE (if specified) are used in the open(). MVS uses the close() function to close the file before the application program receives control.

For status group options other than OCREAT and OEXCL, the description in this book assumes that the application or OPEN macro passes the operands to the open() function without modification. That is, this application or OPEN macro uses dynamic allocation information retrieval (the DYNALLOC macro) to retrieve the subparameters specified for PATHOPTS and passes the subparameters to the open() function. The application program can ignore or modify the information specified in the JCL or on the ALLOCATE command.

You can specify up to 14 file access attributes; separate each with a comma. The system treats duplicate specifications as a single specification.

Subparameter Definition:

SIRUSR: specifies permission for the file owner to read the file.
SIWUSR: specifies permission for the file owner to write the file.
SIXUSR: specifies permission for the file owner to search, if the file is a directory, or to execute, for any other file.
SIRWXU: specifies permission for the file owner to read, write, and search, if the file is a directory, or to read, write, and execute, for any other file.
This value is the bit inclusive OR of SIRUSR, SIWUSR, and SIXUSR.
SIRGRP: specifies permission for users in the file group class to read the file.
SIWGRP: specifies permission for users in the file group class to write the file.
SIXGRP: specifies permission for users in the file group class to search, if the file is a directory, or to execute, for any other file.
SIRWXG: specifies permission for users in the file group class to read, write, and search, if the file is a directory, or to read, write, and execute, for any other file.
This value is the bit inclusive OR of SIRGRP, SIWGRP, and SIXGRP.
SIROTH: specifies permission for the users in the file other class to read the file.
SIWOTH: specifies permission for users in the file other class to write the file.
SIXOTH: specifies permission for users in the file other class to search, if the file is a directory, or to execute, for any other file.
SIRWXO: specifies permission for users in the file other class to read, write, and search, if the file is a directory, or to read, write, and execute, for any other file.
This value is the bit inclusive OR of SIROTH, SIWOTH, and SIXOTH.
SISUID: specifies that the system set the user ID of the process to be the same as the user ID of the file owner when the file is run as a program.
SISGID: specifies that the system set the group ID of the process to be the same as the group ID of the file owner when the file is run as a program. The group ID is taken from the directory in which the file resides.

When creating a new UNIX file, if you do not code a PATHMODE operand on a DD statement with a PATH operand, the system sets the permissions to zero, which prevents access by all users. If the UNIX file already exists, PATHMODE is checked for syntax but ignored. The permission bits are left as they are set.

PATHOPTS(file_options)

specifies the file access and status used when accessing a file specified on the PATH operand. You can specify up to 7 file options; separate each with a comma. The system treats duplicate specifications as a single specification.

Access Group:        Status Group:
------------         ------------
(choose only 1)      (choose up to 6)
ORDONLY              OAPPEND
OWRONLY              OCREAT
ORDWR                OEXCL
                     ONOCTTY
                     ONONBLOCK
                     OTRUNC

Note: If you specify more than one Access Group, the system ignores them and uses ORDWR.

For status group options other than OCREAT and OEXCL, the description in this book assumes that the application or OPEN macro passes the operands to the open() function without modification. That is, this application or OPEN macro uses dynamic allocation information retrieval (the DYNALLOC macro) to retrieve the subparameters specified for PATHOPTS and passes the subparameters to the open() function. The application program can ignore or modify the information specified in the JCL or on the ALLOCATE command.

Sub-parameter definition:

ORDONLY

specifies this access group so that the program can open the file for reading.

OWRONLY

specifies that the program can open the file for writing.

ORDWR

specifies that the program can open the file for reading and writing. Do not use this option for a FIFO special file.

OAPPEND

specifies that the system sets the file offset to the end of the file before each write, so that data is written at the end of the existing file.

OCREAT

specifies that the system is to create the file. If the file already exists, the operation fails if OEXCL is specified, and opens the existing file if OEXCL is not specified.

OEXCL

specifies that, if the file does not exist, the system is to create it. If the file already exists, open() fails. Note that the system ignores OEXCL if OCREAT is not also specified.

ONOCTTY

specifies that, if the PATH operand identifies a terminal device, open() does not also make the terminal device the controlling terminal of the process and the session.

ONONBLOCK

specifies the following, depending on the type of file:

For a FIFO special file with ORDONLY option set:
ONONBLOCK specifies read-only opening of the file. If ONONBLOCK is not specified, the read-only open() blocks until a process opens the file for writing.
For a FIFO special file with OWRONLY option set:
ONONBLOCK specifies that the system immediately process a request for a write-only open() of the file, if a process has already opened the file for reading. If the file is not open for reading, the system returns an error. If ONONBLOCK is not specified, the write-only open() blocks until a process opens the file for reading.
For a character special file that supports a nonblocking open():
ONONBLOCK specifies that the system immediately returns if it cannot open a file because the device is not ready or available. If ONONBLOCK is not specified, the open() blocks until the device is ready or available.

Specifications of ONONBLOCK has no effect on other file types.

OSYNC

specifies that the system is to move data from buffer storage to permanent storage before returning control from a callable service that performs a write.

OTRUNC

specifies that the system is to truncate the file to zero length if all of the following conditions are true:

The file specified on the PATH operand exists.
The file is a regular file.
The file successfully opened with ORDWR or OWRONLY.

The system does not change the mode and owner. OTRUNC has no effect on FIFO special files or directories.

FILEDATA(BINARY | TEXT | RECORD)

controls the data conversion method, performed by the network file system client, when accessing network files on a different system. For information of using UNIX file system such as NFS, see z/OS DFSMS Using Data Sets. The other system might be OS/390®, AIX®, or certain other kinds of systems. The FILEDATA keyword is used to describe the content type of a z/OS UNIX file so that the system can determine how to process the file.

BINARY

specifies that the file described by the DD statement is a byte-stream file and does not contain record delimiters. The access method does not insert or delete record delimiters.

If you do not code the FILEDATA operand, the system assigns a default value of BINARY to the UNIX file.

TEXT

specifies that the file described by the DD statement contains records delimited by the EBCDIC newline character (x'15').

See the appropriate DFSMS/MVS publications for more details about the Network File System client and its conversion methods.

You need to code the PATH operand together with the FILEDATA operand.

You can code the FILEDATA operand together with the following ALLOCATE operands: BLKSIZE, BUFNO, DSNTYPE, DUMMY, LRECL, NCP, PATHDISP, PATHMODE, PATHOPTS, RECFM.

RECORD

Indicates that the data consists of records with prefixes. The record prefix contains the length of the record that follows. On output, the access method inserts a record prefix at the beginning of each record. On input, the access method uses the record prefix to determine the length of each record. The access method does not return the prefix as part of the record. Code FILEDATA(RECORD) when you cannot code FILEDATA(TEXT) because your data might contain bytes that are considered delimiters.

Note: The record prefix for FILEDATA(RECORD) is mapped by the IGGRPFX macro. This is different from the record descriptor word (RDW) that is in z/OS physical sequential format-V data sets.

RLS(NRI | CR)

specifies the level of record sharing, or sharing protocol, for a VSAM data set in a sysplex. See z/OS DFSMS Using Data Sets, for a description of sharing protocols and to determine whether your application can run in a sharing environment without modification.

NRI: specifies no read integrity (NRI). An application can read uncommitted changes to a data set made by another application.
CR: specifies consistent read (CR). An application can read only committed changes to a data set made by another application. An application might require changes if it attempts to read changes to a data set that was allocated with a specification of CR.

Do not use any of the following ALLOCATE operands with RLS: BURST, CHARS, COPIES, DDNAME, DSNTYPE, FLASH, MODIFY, OUTPUT, PATH, PATHOPTS, PATHMODE, PATHDISP, SEGMENT, SPIN, SYSOUT, UCS.

EATTR(NO | OPT)

specifies whether the data set can support extended attributes (format 8 and 9 DSCBs) or not. To create such data sets, you can include extended address volumes (EAVs) in specific storage groups or specify an EAV on the request or direct the Allocation to an esoteric containing EAV devices.

By definition, a data set with extended attributes can reside in the extended address space (EAS) on an extended address volume (EAV). This parameter can be specified for non-VSAM data sets and for VSAM data sets. If EATTR is not specified, VSAM data sets can have format 8 and 9 DSCBs by default, while non-VSAM data sets can not.

The EATTR value has no affect for DISP OLD processing, even for programs that might open a data set for OUTPUT, INOUT, or OUTIN processing. The value on the EATTR parameter is used for requests when the data set is newly created.

NO: specifies that no extended attributes are available. The data set cannot have extended attributes (format 8 and 9 DSCBs) or reside in EAS.
OPT: specifies that extended attributes are optional. The data set can have extended attributes and reside in EAS.