Allocates an existing cataloged data set.
&CONTROL SHRVARS=($DS)
EXEC $DSCALL OPT=ALLOC
DSN=dataset_name
[ DD=DD_name ]
[ DISP= { KEEP | DELETE } [, { KEEP | DELETE } ] ]
[ MIGRATE= { YES | NO } ]
[ MOUNT= { NO | YES } ]
[ STAT= { OLD | MOD | SHR } ]
[ INFO= { YES | WAIT | NOWAIT | NO } ]
This call is used to allocate an existing cataloged data set to your product region. The data set remains allocated to your product region until it is explicitly deallocated, or your product region terminates.
Operands:
Specifies that a data set is to be allocated.
Specifies the data set name to allocate.
Specifies the ddname for the allocation. If this operand is omitted, a ddname is generated by the operating system.
Specifies the Normal and Conditional Disposition of the data set. The disposition relates to the normal or conditional termination of your product region, not of the requesting NCL process. If KEEP is specified, the data set remains cataloged. If DELETE is specified, the data set is uncataloged and deleted.
Specifies whether to allocate a data set if it has been migrated. If MIGRATE=NO is specified, Dataset Services checks that the data set has been migrated (for example, by DFHSM). If the data set has been migrated, Dataset Services rejects the allocation request. If MIGRATE=YES is specified, Dataset Services issues the allocation request without checking that the data set has been migrated.
Specifies whether a volume mount is allowed. If MOUNT=NO is specified, and an allocation request requires a volume which is off-line, the allocation request fails. If MOUNT=YES is specified and an allocation request requires a volume which is off-line, a MOUNT request for the volume is issued.
Specifies the data set status.
Allocation information is obtained by using the Dynamic Allocation (SVC 99) services, which require the SYSZTIOT system resource, which may not be available. The INFO= parameter specifies whether allocation information is required and, if so, the action required when SYSZTIOT is not available:
Indicates that information is required. If the SYSZTIOT resource is not immediately available, then $DSCALL retries the allocation information request up to five times at two-second intervals. This is the default.
Also indicates that information is required. If the SYSZTIOT resource is not immediately available, then $DSCALL retries the allocation information request at two-second intervals until the information is available.
Also indicates that information is required. If the SYSZTIOT resource is not immediately available, then $DSCALL does not retry.
Indicates that allocation information is not required.
If allocation information is requested (INFO=YES, INFO=WAIT, or INFO=NOWAIT), then the information is returned as described in the Return Variables section below. If allocation information is not requested (INFO=NO) or the SYSZTIOT resource is not available after any retries (INFO=YES or INFO=NOWAIT), then the return variables are undefined.
Return Codes:
|
$DSRC |
$DSFDBK |
Meaning |
|---|---|---|
|
0 |
0 |
Data set was allocated; allocation details available in &$DS* variables as described below. |
|
0 |
non-zero |
Data set was allocated; however, allocation details are incomplete. |
|
4 |
non-zero |
Data set was not allocated. |
|
8 |
non-zero |
A Dataset Services Interface error has occurred and the function is incomplete. This is typically an application program specification error. The error is indicated in &SYSMSG with message number DSnnnn. |
Note: For more information about &SYSMSG, &$DSRC, and &$DSFDBK, see Return Codes and Feedback Codes.
Return Variables:
Status of data set; values are OLD, MOD, or SHR
Full data set name with member name omitted, and true name if an alias was entered
Member name if a member of a PDS
Data set organization; values are PS, PO, PSU, POU, CX, CQ, MQ, GS, TX, TQ, TR, and VS
First volume
Unit name for the volume
Record format; values are F,FB, FS, FBS, FA, FBA, FSA, FBSA, FM, FBM, FSM, FBSM, V, VB, VS, VBS, VBSA, VM, VBM, VSM, VBSM, U, UA, UM
Record length
Actual usable record length. If the record format is variable length, then the value is record length minus 4. In all other cases the value is the same as record length.
Block size
DDname from the allocation, as supplied or as generated by the operating system
SMS storage class if SMS is active for this data set
SMS management class if SMS is active for this data set
SMS data class if SMS is active for this data set
DYNALLOC error code
DYNALLOC information code
Examples: OPT=ALLOC
EXEC $DSCALL OPT=ALLOC DSN=CUSTOMER.DATA STAT=SHR
Notes:
Only cataloged data sets are supported. Unit and volume parameters are not supported by this function.
If the data set has been migrated, the allocation may be delayed if a tape mount is required to recover the migrated data set.
Allocation of a data set uses the Dynamic Allocation (SVC 99) services, which require the SYSZTIOT system resource. An unconditional SVC 99 is used at first. This causes the allocation function to wait if SYSZTIOT is unavailable.
If allocation fails, then &$DSRC is set to 4 and specific information is made available in &$DSFDBK, &$DSDYNEC, &$DSDYNIC, and &SYSMSG.
If the data set is allocated, then &$DSRC is always set to zero. If allocation information was requested (INFO=YES, INFO=WAIT, or INFO=NOWAIT), then a conditional SVC 99 is used to obtain the allocation information which is returned in the &$DS* variables. If the information is available in the return variables, then &$DSFDBK is also set to zero. If INFO=YES or INFO=NOWAIT was specified, then failure of the allocation information request due to SYSZTIOT being unavailable is indicated by the following:
&$DSFDBK = 5
&$DSDYNEC = 0254