Parameters

PRIMARY=n

Specifies one of the following:

• If MEASURE=TRK, the number of tracks to be allocated.
• If MEASURE=CYL, the number of cylinders to be allocated.
• If MEASURE=AVEBLK, the number of average data blocks in the data set, where n is a number in the range of 0-16,777,215 or 2 ^ 24-1.

When you specify TRK or CYL for a partitioned data set (PDS), the primary quantity includes the space for the directory. When you specify a block length for a PDS, the primary quantity does not include the directory space; the system assigns the directory space outside the primary space assignment.

One volume must have enough available space for the primary quantity. If you request a particular volume and it does not have enough space available for your request, the system ends the job step. Allow for track overflow when you compute track requirements.

SECONDARY=n

Specifies the number of additional tracks, cylinders, blocks, or records to be allocated, if more space is needed, where n is a number in the range 0-16,777,215 or 2 ^ 24-1. The system does not allocate additional space until it is needed.

If the requested volumes have no more space available, and if at least one volume is demountable, the system asks the operator to mount scratch (nonspecific) volumes until the secondary allocation is complete. If none of the volumes are demountable, the system abnormally ends the job step.

Note: Your program should not write with a disposition of DISP=SHR unless you take precautions to prevent other programs from being written at the same time.

DIRECTORY=n

Specifies the number of 256-byte records needed in the directory of a PDS, where n is a number in the range 0-8,388,607 or 2 ^ 23-1.

MEASURE=TRK|CYL|AVEBLK

Specifies the unit of measure of the space allocation as one of the following:

TRK

Requests that space be allocated in tracks.

CYL

Requests that space be allocated in cylinders.

AVEBLK

Requests that the system is to decide how many tracks to allocate based on the average block size. The size of the average block is specified using the BLKLNGTH parameter, and the number of blocks is specified using the PRIMARY parameter.

Note: When you change MEASURE to AVEBLK, BLKLNGTH and ROUND must also be specified on the same command.

BLKLNGTH=n

Specifies, in bytes, the average block length of the data, where n is a number in the range 0-65535 or 2 ^ 16-1.

Note: This parameter can be changed only when MEASURE=AVEBLK is specified.

ROUND=ROUND|NOROUND

Specifies whether (ROUND) or not (NOROUND) space allocated to the data set must be equal to an integral number of cylinders.

Note: This parameter can only be changed when MEASURE=AVEBLK is specified.

PRIM_ORG={CONTIG|MXIG|ALX|NONCONTIG}

Specifies the organization of the primary space allocation.

CONTIG

Requests that space allocated to the data set be contiguous. If CONTIG is specified on a dynamic allocation non-VIO request and contiguous space is not available, the request fails.

MXIG

Requests that space allocated to the data set meet the following requirements:

• The space is the largest area of available contiguous space on the volume.
• The space is equal to or greater than the value specified on the PRIMARY parameter.

Take care when coding this parameter. Large amounts of storage could be allocated, depending on how much free space is available at the time when the request is made. If you code this parameter, it is suggested that you also code the RLSE parameter to release any unused space.

MXIG is useful when you wish to dedicate as much space as possible on the volume to one data set, but is not useful as a system default.

Note: MXIG can also be specified in a job's JCL.

ALX

Requests that up to five of the largest separate areas of available contiguous space are to be allocated to the data set, and each area must be equal to or greater than the value specified on the PRIMARY parameter.

Take care when coding this parameter. Large amounts of storage could be allocated, depending on how much free space is available at the time when the request is made. If you code this parameter, it is suggested that you also code the RLSE parameter to release any unused space.

ALX is useful when you wish to dedicate as much space as possible on the volume to one data set and it does not have to be contiguous.

Note: ALX can also be specified in a job's JCL.

NONCONTIG

Specifies that non-contiguous space is acceptable.

RLSE=RLSE|NORLSE

Specifies whether (RLSE) or not (NORLSE) space allocated to an output data set, but not used, is to be released when the data set is closed, and the CLOSE macro does not specify TYPE=T. Unused space is released only if the data set is open for output and the last operation was a write.

NAME=group

Specifies the group of devices onto which data sets are placed, where group is a valid device group name. The installation must have assigned the name to the devices(s) during system initialization or IBM® must have assigned the name. This default applies only to dynamic requests.

UNITAFF={name|SYSTEMDEFAULT}

Specifies the installation default for the unit name on which the system is to place data sets when the following conditions are true:

• The data set for the referencing DD, namely, the DD that specifies UNIT=AFF, DISP=NEW or DISP=MOD (MOD treated as NEW), is not SMS-managed.
• The data set for the referenced DD, namely, the DD statement pointed to by the UNIT=AFF subparameter, is SMS-managed.
• The allocation is not part of a data set collection involving data set stacking.
• The system cannot obtain a unit name from the primary DD statement in the unit affinity chain.

When name is specified, the installation must have assigned the name to the device(s) during system initialization, or IBM must have assigned the name. When SYSTEMDEFAULT is specified, the tape generic that is highest in the device preference table is used. This generic must be available on every IODF used on the system between this IPL and the next IPL.

REDIRECTED_TAPE=DASD|TAPE

Allows the installation to specify whether unopened batch-allocated DASD data sets that were redirected from tape should be treated as DASD or TAPE.

Specifying REDIRECTED_TAPE(TAPE) causes unopened batch allocated data sets that have been redirected from TAPE to DASD to be deleted during final disposition processing. These unopened redirected data sets are deleted regardless of the disposition requested.

Specifying REDIRECTED_TAPE(DASD) causes unopened batch allocated data sets that have been redirected from TAPE to DASD to be processed according to the original disposition, as they would have been if they had been directed to DASD and not redirected to DASD from TAPE.

Note: Dynamic allocation of SMS DASD data sets that were redirected from TAPE continue to be treated as DASD during dynamic allocation.

SIZE=n

Specifies the size of the TIOT, where n is a number in the range 16-64 for each KB of space . (For example: 16 means 16KB).

The TIOT contains an entry for each DD statement. The size of the TIOT decides how many DDs are allowed per jobstep. See

z/OS MVS Initialization and Tuning Reference for examples on calculating the TIOT space required for a jobstep.

WAITALLOC=YES|NO

Specifies whether (YES) or not (NO) to cancel jobs that must wait to enqueue on a GDG absolute generation data set name, or a real data set name (when its corresponding alias data set name is specified on the JCL).

When YES is specified, and the enqueue request of a batch job cannot be satisfied, the system issues messages IEF861I, IEF863I and IEF458D. The job waits, holding any resources it might have acquired. The system operator can choose to cancel the job in response to message IEF458D, or allow the job to continue waiting until the enqueue becomes available. If the operator cancels the job, the system writes an informational message IEF330I to the job log.

When NO is specified, the system cancels the job, releases its resources, and issues message IEF211I.

Note:

1. Use with caution when specifying YES. Allowing jobs to wait for data set availability can cause deadlocks with other jobs in the system.
2. When you specify YES, the system does not allow the job to wait for a data set when both of the following conditions are true:
   1. This job plus one (or more) other jobs have the data set allocated as DISP=SHR.
   2. This job requests that its use of the data set be upgraded from DISP=SHR to DISP=OLD. The system ends this job and issues message IEF211I.
3. The WAITALLOC option applies only to batch allocation requests (that is, allocation requests specified in the job's JCL).

POLICY=WTOR|CANCEL|WAIT

Specifies the action to take. An installation exit can override the policy.

WTOR

The policy is to issue a message and let the operator make the decision about the allocation request.

CANCEL

The policy is to cancel a job that needs an unavailable volume. The system cancels the job, releases its resources, and issues message IEF251I.

WAIT

The policy is to let a job that needs an unavailable volume wait until the volume is available.

CAUTION: When WAIT is used as the default, deadlocks with other jobs in the system might arise for tape volumes.

POLICY=WTOR|WAITHOLD|WAITNOH|CANCEL

Specifies the action to take. An installation exit can override the policy.

WTOR

The policy is to issue a message and let the operator make the decision about the wait request.

WAITHOLD

The policy is for the system not to release any of the devices that have already been allocated to this job before it waits for the required units or volumes. The system issues message IEF289E.

Be aware that using the WAITHOLD policy might cause a deadlock situation, particularly when the device is being used by a job that is going to wait. The system does not release any non-sharable devices (namely, non-DASD) that have already been allocated to the job before it waits for required units and volumes. To avoid this problem, do not specify WAITHOLD.

When devices for a job are held during a wait, and a device that was eligible for allocation to the job becomes ineligible for allocation (because of its use by a system utility, for example), the job might fail because it does not have enough devices to complete successfully. See IEF700I in the job log identifies this failure. Refer to message IEF700I for information about how to respond to this failure.

Note: When you change POLICY to WAITHOLD, POLICYNW must also be specified on the same command.

WAITNOH

The policy is to let the job wait while it does not hold the obtained resources. The system releases those devices that have been allocated to this job, and issues message IEF289E.

Note: When you change POLICY to WAITNOH, MAXNWAIT and POLICYNW must also be specified on the same command.

CANCEL

The policy is to cancel the allocation request. If a TSO/E user issues the allocation request, the user receives an error message. If a batch job or started task issues the request, the system cancels the job or task, releases its resources, and issues message IEF251I.

MAXNWAIT=n

Specifies the number of WAITNOH decisions that can be made for the specific volume or unit allocation request before the default specified on the POLICYNW parameter takes effect, where n is a number in the range 1-255 or 2 ^ 8-1.

The WAITNOH decisions counted are those specified either through the default on the POLICY parameter or through an installation exit specified in the EXITxx parmlib member. "WAITNOH" decisions made by the operator are not included in the MAXNWAIT count.

Note: This parameter can be changed only when POLICY=WAITNOH is specified.

POLICYNW=CANCEL|WTOR

Specifies how the system handles the allocation request under the following circumstances:

• Either WAITHOLD or WAITNOH is specified on the POLICY parameter and the system does not allow the job to wait for resources.
• The maximum number of WAITNOH decisions (specified on the MAXNWAIT parameter) has been exceeded.

The system is to either cancel the allocation request (CANCEL) or issue a message (WTOR).

Note: This parameter can be changed only when POLICY=WAITNOH or POLICY=WAITHOLD is specified.

POLICY=WTOR|WAITHOLD|WAITNOH|CANCEL

Specifies the action to take. An installation exit can override the policy.

WTOR

The policy is to issue a message and let the operator make the decision about the needed device.

WAITHOLD

The policy is for the system not to release any of the devices that have already been allocated to this job before it waits for the required units or volumes. The system issues message IEF289E.

Be aware that using the WAITHOLD policy might cause a deadlock problem, particularly when the device is being used by a job that is going to wait. The system does not release any non-sharable devices (namely, non-DASD) that have already been allocated to the job before it waits for required units and volumes. To avoid this problem, do not specify WAITHOLD.

When devices for a job are held during a wait, and a device that was eligible for allocation to the job becomes ineligible for allocation (because of its use by a system utility, for example), the job might fail because it does not have enough devices to complete successfully. Message IEF700I in the job log identifies this failure. See message IEF700I for information about how to respond to this failure.

Note: When you change POLICY to WAITHOLD, POLICYNW must also be specified on the same command.

WAITNOH

The policy is to let the job wait while it does not hold the obtained resources. The system releases those devices that have been allocated to this job, and issues message IEF289E.

Note: When you change POLICY to WAITNOH, MAXNWAIT and POLICYNW option must also be specified on the same command.

CANCEL

The policy is to cancel the allocation request. If a TSO/E user issues the allocation request, the user receives an error message. If a batch job or started task issues the request, the system cancels the job or task, releases its resources, and issues message IEF251I.

MAXNWAIT=n

Specifies the number of WAITNOH decisions that can be made for the specific volume or unit allocation request before the default specified on the POLICYNW parameter takes effect, where n is a number in the range 1-255 or 2 ^ 8-1.

The WAITNOH decisions counted are those specified either through the default on the POLICY parameter or through an installation exit specified in the EXITxx parmlib member. WAITNOH decisions made by the operator are not included in the MAXNWAIT count.

Note: This parameter can be changed only when POLICY=WAITNOH is specified.

POLICYNW=CANCEL|WTOR

Specifies how the system handles the allocation request under the following circumstances:

• Either WAITHOLD or WAITNOH is specified on the POLICY parameter and the system does not allow the job to wait for resources (needed devices).
• The maximum number of WAITNOH decisions (specified on the MAXNWAIT parameter) has been exceeded.

The system is to either cancel the allocation request (CANCEL) or issue a message (WTOR).

Note: This parameter can be changed only when POLICY=WAITNOH or POLICY=WAITHOLD is specified.

• Catalog a new data set for which the user specified a disposition of CATLG.
• Catalog an old uncataloged data set for which the user specified a disposition of CATLG.
• Catalog an old cataloged data set again for which the volume list was extended, and for which the user specified a disposition of CATLG, KEEP or PASS.
• Roll an SMS-managed generation data set into the GDG base.

FAILJOB=YES|NO

Specifies whether (YES) or not (NO) the system is to end the job if a catalog error occurs.

When a job is ended by FAILJOB(YES), the action of ending is considered a post-execution error.

Note:

1. The setting of the condition code is not affected.
2. The job is NOT abnormally ended, unless the step that encountered the error had itself previously abnormally ended. Termination means that subsequent steps will not be taken.
3. The normal disposition for data sets is taken, unless the step that encountered the error had already abnormally ended, in which case the abnormal or conditional disposition is taken.

ERRORMSG=YES|NO

Specifies whether (YES) or not (NO) the system is to issue an error message to the operator if a catalog error occurs.

When YES is specified, the system issues message IEF377I. If FAILJOB=YES was also specified, the system ends the job, releases its resources, and issues message IEF378I.

Note: If any of the following conditions is true, the system writes the error message even when ERRORMSG=NO is specified:

• The user specifies MSGLEVEL=(,1) on the JCL JOB statement.
• The JES installation default sets the message level to MSGLEVEL=(,1).
• The job abnormally ends.

An AS Tape device that is connected and possibly used outside of this allocation's tape management scheme can be "stolen" for temporary use by allocation on a system outside this scheme. This causes the volume status for the device to change, unbeknownst to the allocation's scheme. In this case, if the volume has been premounted, or the volume is passed or retained, this allocation scheme can cause inadvertent read/write activity on a volume, and result in data loss or data integrity exposures.

If, for a given DD statement, MVS allocation selects an AS tape device, and the UCB for the device shows that any currently mounted volume is the required volume for the DD, the system can optionally cause volume verification when an OPEN is performed for that DD.

POLICY=YES|NO

Specifies whether the system is to perform volume verification of an apparently premounted, passed or retained AS tape device at open time.

YES

Volume verification is to be done by OPEN for Standard, ISO/ ANSI Version 1, or ISO/ANSI/FIPS Version 3 labeled tape volumes that are premounted, passed or retained on an AS tape device. Both volume serial and tape position are verified.

NO

No specific volume verification is to be done by OPEN for premounted, passed or retained volumes on an AS tape device. Select POLICY=NO option if it is certain that there is no exposure to the "stolen" AS device for premounted, passed or retained volumes as described in the previous scenarios. For example, specify POLICY=NO option if all systems within a sysplex are z/OS V1R2 or above, and tape devices that are defined as AS to systems within that sysplex are NOT shared with any systems, or sysplexes, outside of that sysplex.

IEFBR14_DELMIGDS=LEGACY|NORECALL

Specifies the policy on whether to recall a migrated data set when you use an IEFBR14 JCL program with DD DISP=(x,DELETE) to delete the data set. The recall is, in most cases, unnecessary, because the data set is being deleted anyway.

LEGACY

Indicates that the system is to recall HSM-migrated data sets before deletion.

NORECALL

Indicates that the system can delete (through HSM HDELETE processing) the data set without first recalling the data set to the primary storage.

TAPELIB_PREF=EQUAL|BYDEVICES

Specifies the policy on balancing non-specific tape library requests (for example, scratch tape requests) across multiple tape libraries.

EQUAL

Indicates that for non-specific tape library requests, all tape libraries must be treated as equal, and receive an equal share of the requests.

BYDEVICES

Indicates that non-specific tape library requests must be balanced across all tape libraries according to the number of tape devices in the tape library. Tape libraries with more tape devices receive more non-specific tape requests than libraries with fewer devices when all devices have the same attributes.

REMIND_INTV(xxx)

Specifies the number of seconds for how often the message IEF882E/IEF883E is displayed, letting an operator know of an outstanding IEF238D/IEF433D/IEF434D. This interval is a number in the range 10-999, indicating how many seconds between reminder messages, or 0 to disable them.

TEMPDSFORMAT=UNIQUE|INCLUDELABEL

Specifies how the system generates data set names for temporary data sets that include '&&label' as the specified data set name. This statement affects only the data sets that specify DSN=&&mydsn, but not the data sets that do not specify DSNAME at all.

UNIQUE

Indicates that when the system processes JCL that includes temporary data sets with DSN=&&LABEL, the generated data set name will be in the form "SYSyyddd.Thhmmss.RA000.jjobname.Rggnnnnn", which does not include the &&label specified in the JCL. All references to "&&mydsn" throughout the JCL correctly refer to the same data set. Using TEMPDSFORMAT=UNIQUE ensures that jobs with the same jobname running simultaneously do not create temporary data sets with the same names. See z/OS MVS JCL Reference for more information.

INCLUDELABEL

Indicates that when the system processes JCL that includes temporary data sets with DSN=&&LABEL, the generated data set name will include the &&label specified in the JCL. See z/OS MVS JCL Reference for more information.

Note: When this parameter is specified and the Job Entry Subsystem (JES) allows multiple jobs with the same job name to execute at the same time, jobs with the same name, executing simultaneously, might fail with a duplicate data set name error.

Restrictions: The SETALLOC SYSTEM,TEMPDSFORMAT= command only affects jobs and job steps that are initiated after the command completes. Jobs that were initiated and created the temporary data sets before the command completes continue to use the old setting.

VERIFY_UNCAT

Specifies the policy for handling UNCATLG requests in JCL and dynamic allocation when the data set information is not retrieved from the catalog.

FAIL

Fails the request. This option prevents a job from accidentally uncataloging a cataloged data set with the same name as the data set that is allocated. This is the default behavior.

TRACK

Allows the data set to be uncataloged, and tracks the request in the tracking facility. This option allows a job to uncatalog a cataloged data set with the same name as the data set that is allocated. The installation can use this option to find and correct existing JCL that have uncataloged data sets incorrectly.

Note: This option is provided for migration purposes. It might be removed from the system in the future.

The tracking facility must be active for UNCATLG requests to be tracked. Whenever a job attempts to uncatalog a data set for which the data set information was not retrieved from the catalog, the job will be tracked with the tracking information containing the string IEFALC 01, followed by the step name and DD name.

• For batch allocated DDs, the program name contains IEFIIC.
• For dynamically allocated DDs, the program name is the invoking program if it can be determined, or SVC-099 if it cannot be determined.

The track value field is unused, and will contain zeros.

Instances of the IEFALC 01 event should be corrected by the installation rather than reported to IBM. For more information about the tracking facility, see z/OS MVS Planning: Operations.

MSGTRACK

Allows the data set to be uncataloged, tracks the request in the tracking facility, and issues a message. This option allows a job to uncatalog a cataloged data set with the same name as the data set that is allocated. The installation can use this option to find and correct existing JCL that have uncataloged data sets incorrectly.

Note: This option is provided for migration purposes. It might be removed from the system in the future.

The tracking facility must be active for UNCATLG requests to be tracked. Whenever a job attempts to uncatalog a data set for which the data set information was not retrieved from the catalog, the job will be tracked with the tracking information containing the string IEFALC 01, followed by the step name and DD name.

• For batch allocated DDs, the program name contains IEFIIC.
• For dynamically allocated DDs, the program name is the invoking program if it can be determined, or SVC-099 if it cannot be determined.

The track value field is unused, and will contain zeros.

Instances of the IEFALC 01 event should be corrected by the installation rather than reported to IBM. For more information about the tracking facility, see z/OS MVS Planning: Operations.

In addition to tracking the event, message IEF384I is issued to indicate that the data set is uncataloged, but the volume information is not retrieved from the catalog. This message informs the submitter of the job that the JCL should be corrected. The message is only issued to the job log. For details about message IEF384I, see z/OS MVS System Messages, Vol 8 (IEF-IGD).

LOGTRACK

Allows the data set to be uncataloged, tracks the request in the tracking facility, and issues a message. This option allows a job to uncatalog a cataloged data set with the same name as the data set that is allocated. The installation can use this option to find and correct existing JCL that have uncataloged data set incorrectly.

Note: This option is provided for migration purposes. It might be removed from the system in the future.

The tracking facility must be active for UNCATLG requests to be tracked. Whenever a job attempts to uncatalog a data set for which the data set information was not retrieved from the catalog, the job will be tracked with the tracking information containing the string IEFALC 01, followed by the step name and DD name.

• For batch allocated DDs, the program name contains IEFIIC.
• For dynamically allocated DDs, the program name is the invoking program if it can be determined, or SVC-099 if it cannot be determined.

The track value field is unused, and will contain zeros.

Instances of the IEFALC 01 event should be corrected by the installation rather than reported to IBM. For more information about the tracking facility, see z/OS MVS Planning: Operations.

In addition to tracking the event, message IEF384I is issued to indicate that the data set is uncataloged, but the volume information is not retrieved from the catalog. This message informs the submitter of the job that the JCL should be corrected. The message is issued to the job log and as a hardcopy only WTO. For details about message IEF384I, see z/OS MVS System Messages, Vol 8 (IEF-IGD).

MEMDSENQMGMT

Specifies whether the MEMDSENQMGMT feature is available for exploitation by jobs and subsystems.

ENABLE

Allows jobs and subsystems to use memory-based data set ENQ management for dynamically allocated data sets. Memory-based data set ENQ management is faster than the other option, SWA-based data set ENQ management, for jobs that allocate a large number of data sets. In addition to the above parmlib setting, a job or subsystem that is to use the new management system must enable the feature using the IEFDDSRV macro, e.g. IEFDDSRV MODIFY TYPE=FEATURE,DSENQMGMT=MEMORY. Note that this feature makes the job or subsystem non-restartable through the checkpoint/restart interface.

DISABLE

Disables jobs and subsystems from using memory-based data set ENQ management for dynamically allocated data sets.

BATCH_RCLMIGDS

Specifies how migrated data sets will be recalled. When the BATCH_RCLMIGDS option is changed, future jobs and jobsteps will use the new option while processing batch allocation. As such, the command can enable or disable this feature for a running job as it starts its next job step.

SERIAL

Indicates the system will allow the CATALOG LOCATE function to recall data sets on its behalf, resulting in serial recall processing. SERIAL is the default value.

PARALLEL

Indicates the system will note which data sets are migrated and recall them in parallel, potentially reducing job execution time.

Default: SERIAL