Allocating a Data Set by Dsname (Entry Code X’08’)
Build the DAIR parameter block shown in Table 1 to request that DAIR allocate a data set. Use the IKJDAP08 mapping macro, which is provided in SYS1.MACLIB, to map this DAIR parameter block. The exact action taken by DAIR depends upon the presence of the optional fields and the setting of bits in the control byte.
If the data set is new and you specify DSNAME, (NEW, CATLG) the data set is cataloged upon successful allocation. This is the only time a data set will be cataloged at allocation time. If the catalog attempt is unsuccessful, the data set is freed. If the proper indices are not present, the indices are built.
To allocate a utility data set use DAIR code X'08' and use a dsname of the form &name. If the &name is already allocated, that data set is used. If the &name is not found, a new data set is allocated.
To supply DCB information, provide the name of an attribute list that has been defined previously by a X'34' entry into DAIR.
When setting disposition in a parameter list, only one bit should be on.
For partitioned data sets, specifying the data set name and the member name for DAIR entry code X'08' causes the data set to be allocated, but no check is done to see if the member exists.
- Allocate the data set with the member name using DAIR entry code X'08'.
- Open the data set with DSORG=PO, MACRF=R.
- Issue BLDL for the member. (The BLDL return code will indicate whether the member is there or not.)
- Close the data set.
- If BLDL indicates that the member does not exist, deallocate the data set using ddname and DAIR entry code X'18'.
The DAIR parameter block required for entry code X'08' has the format shown in Table 1.
| Number of bytes | Field name | Contents or meaning |
|---|---|---|
| 2 | DA08CD | Entry code X'0008' |
| 2 | DA08FLG | A flag field set by DAIR before returning to the
calling routine. The flags have the following meaning: Byte 1:
Byte 2: Reserved. Set to zero. |
| 2 | DA08DARC | This field contains the error code, if any, returned from the dynamic allocation routines. (See Reason Codes from Dynamic Allocation.) |
| 2 | DA08CTRC | This field contains the error code, if any, returned from catalog management routines. (See Return Codes from DAIR.) |
| 4 | DA08PDSN | Place in this field the address of the dsname
buffer. The dsname buffer is a 46-byte field with the following format: The first two bytes contain the length, in bytes, of the dsname; the next 44 bytes contain the dsname, left justified and padded to the right with blanks. If this field (DA08PDSN) is zero, the system generates a data set name unless bit 5 in DA08CTL is on, in which case a DUMMY data set is allocated. The system also generates a name if the DA08PDSN field points to a dsname buffer which has a length of 44, is initialized to blanks, and bit 5 in DA08CTL is off. |
| 8 | DA08DDN | This field contains the ddname for the data set. If a specific ddname is not required, fill this field with eight blanks; DAIR will place in this field the ddname to which the data set is allocated. |
| 8 | DA08UNIT | |
| 8 | DA08SER | Serial number desired. Only the first six bytes are significant. If the serial number is less than six bytes, it must be padded to the right with blanks. If the serial number is omitted, the entire field must contain blanks. In this case the following is done: if the data set is a new data set, the system determines the volume to be used for the data set based on the unit information. If the data set already exists, volume and unit information are obtained from the catalog. If the information is not found in the catalog, the allocation request is denied. |
| 4 | DA08BLK | This is a 4-byte field used as follows: if the data set is a new data set and bit 0 in DA08CTL is off and bit 1 in DA08CTL is on, this field is used with DA08PQTY to determine the amount of direct access space to be allocated for the data set. If bit 6 of DA08CTL is off, the field is also used as DCB blocksize specification. The value for blocksize must be placed in the two low-order bytes, and the high-order bytes must be zero. |
| 4 | DA08PQTY | Primary space quantity desired. The high-order byte must be set to zero and the three low-order bytes should contain the space quantity required. If the quantity is omitted, the entire field must be set to zero. In the case of new direct access data sets, primary and secondary space and type of space are defaulted. Directory quantity is used if specified in DA08DQTY. |
| 4 | DA08SQTY | Secondary space quantity desired. The high-order byte must be set to zero; the three low-order bytes should contain the secondary space quantity required. If the quantity is omitted, the entire field must be set to zero. |
| 4 | DA08DQTY | Directory quantity required. The high-order byte must be set to zero; the three low-order bytes contain the number of directory blocks desired. If the quantity is omitted, the entire field must be set to zero. |
| 8 | DA08MNM | Contains a member name of a partitioned data set. If the name has less than eight characters, pad it to the right with blanks. If the name is omitted, the entire field must contain blanks. |
| 8 | DA08PSWD | Contains the password for the data set. If the password has less than eight characters, pad it to the right with blanks. If the password is omitted, the entire field must contain blanks. |
| 1 | DA08DSP1 | Flag byte. Set the following bits to indicate
the status of the data set:
If this byte is zero, OLD is assumed. NEW or MOD is required if dsname is omitted. |
| 1 | DA08DPS2 | Flag byte. Set the following bits to indicate
the normal disposition of the data set:
If this byte is zero, it is defaulted as follows: if DA08DSP1 is NEW, DELETE is used; otherwise, KEEP is used. |
| 1 | DA08DPS3 | Flag byte. Set the following bits to indicate
the abnormal disposition of the data set:
If this byte is zero, DA08DPS2 will be used. |
| 1 | DA08CTL | Flag byte. These flags indicate to the DAIR service
routine what operations are to be performed:
|
| 3 | Reserved. Set these bytes to zero. | |
| 1 | DA08DSO | A flag field. These flags are set by the DAIR
service routine; they describe the organization of the data set to
the calling routine.
|
| 8 | DA08ALN | Attribute list name, or a ddname from which DCB attributes should be copied (as in a JCL DCB reference). If the name is less than 8 characters, it should be padded to the right with blanks. |
After attempting the requested function, DAIR returns, in register 15, one of the following codes: 0, 4, 8, 12, 16, 20, 28, 32, 44, or 52. See Return Codes from DAIR for return code meanings.