The GETDSAB macro returns a pointer to the data set association block (DSAB) associated with a DD name.
See z/OS MVS Programming: Authorized Assembler Services Guide for procedures that use the DSAB address returned by the GETDSAB macro to obtain the address of the TIOT entry and the UCB address.
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Problem state or supervisor state, and any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN=HASN=SASN |
AMODE: | 31-bit addressing mode |
ASC mode: | Primary |
Interrupt status: | Enabled for I/O and external interrupts |
Locks: | No locks held |
Control parameters: | Must be in the primary address space |
To use GETDSAB, the caller must include the DSAB mapping macro (IHADSAB), the CVT mapping macro (CVT), and the JESCT mapping macro (IEFJESCT).
The caller must provide or inherit serialization on the SYSZTIOT resource before calling the GETDSAB macro and while using the output addresses of the macro. The minimum required level of serialization is shared (SHR).
The GETDSAB service does not provide a recovery environment. Because the service runs in task mode, the system will use any recovery environment defined to the caller prior to invoking GETDSAB.
There are no restrictions or limitations for using this macro.
After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.
On input to the macro, register 13 must contain the address of an 18-word save area.
There are no performance implications related to GETDSAB.
The standard form of the GETDSAB macro follows.
Syntax | Description |
---|---|
name | name: Symbol. Begin name in column 1. |
␢ | One or more blanks must precede GETDSAB. |
GETDSAB | |
␢ | One or more blanks must follow GETDSAB. |
FIRST | |
NEXT | |
DCBPTR=dcb addr | dcb addr: RX-type address, or register (2) - (12). |
DDNAME=dd addr | dd addr: RX-type address, or register (2) - (12). This address specifies an 8-byte field which contains a DD name. |
,DSABPTR=dsab addr | dsab addr: RX-type address, or register (2) - (12). |
,TCBPTR=tcb addr | tcb addr: RX-type address, or register (2) - (12). Default: TCBPTR=0 |
,RETCODE=retcode addr | retcode addr: RX-type address, or register (2) - (12) of fullword output variable |
,RSNCODE=rsn addr | name: RX-type address, or register (2) - (12). |
,LOC=BELOW | Default = BELOW |
,LOC=ANY | |
The parameters are described as follows:
NEXT requests the pointer to the next DSAB in the DSAB chain, following the one pointed to by the initial value in DSABPTR.
DCBPTR=dcb addr specifies the name of a pointer that contains the address of a fullword field. The fullword points to the DCB associated with a DD name. The system retrieves the DSAB pointer associated with the DCB.
When DCBPTR points to an open DCB, DCBPTR and TCBPTR are mutually exclusive.
Do not use the DCBPTR option for a DCB in a DCB OPEN exit, DCB ABEND exit, data management ABEND installation exit or the DCB OPEN installation exit.
When DCBPTR points to a closed DCB, the system selects the DSAB chain associated with the TCB specified by TCBPTR parameter, or, if none is specified, by the current TCB.
DDNAME=dd addr specifies a DD name associated with a DSAB. The system puts the address of the DSAB associated with this DD name into the fullword field specified by the DSABPTR parameter. The DSAB selected is that associated with the TCB specified by the TCBPTR parameter, or, if none is specified, by the current TCB. The dd addr is an 8-character, left-justified field, with trailing blanks. The dd addr may not contain all blanks.
When used with the NEXT keyword, DSABPTR must contain the address of a DSAB that was previously obtained by invoking GETDSAB with FIRST, DCBPTR, or DDNAME. The system will replace this initial address with the address of the next DSAB in the DSAB chain.
When used with the keywords FIRST, DCBPTR, or DDNAME, DSABPTR is an output field only.
Upon output, DSABPTR contains the address of the specified DSAB if the return code is zero. If the return code is not zero, DSABPTR contains 0.
When DCBPTR points to an open DCB, DCBPTR and TCBPTR are mutually exclusive.
The default, TCBPTR=0, requests the current TCB.
LOC=BELOW, which is the default, searches only those DSABs residing below the 16 MB line
LOC=ANY searches both below and above the 16 MB line.
When control returns from GETDSAB, GPR 15 (and retcode addr, if you coded RETCODE) contains one of the following decimal return codes.
Decimal Return Code | Meaning |
---|---|
00 | Meaning: Successful completion |
04 | Meaning: Request failed. NEXT was specified when DSABPTR pointed to the last DSAB in the DSAB chain. |
08 | Meaning: Request failed. The specified DSAB was not found. |
12 | Meaning: Request failed. Input values were in error or in conflict. |
16 | Meaning: Request failed. The GETDSAB function is not currently installed on the system. Consult your system programmer. |
When control returns from GETDSAB, GPR 0 (and rsncode addr, if you coded RSNCODE) might contain one of the following decimal reason codes:
Decimal Return Code | Decimal Reason Code | Meaning |
---|---|---|
12 | 1200 | Request failed because of input error. The DDNAME specified or obtained was all blanks. |
12 | 1210 | Request failed because of input error. TCBPTR was specified when DCBPTR points to an open DCB. |
12 | 1220 | Request failed because of input error. The DSAB pointed to by DSABPTR is not valid. |
12 | 1230 | Request failed because of input error. The LOC=BELOW is requested, but the DSAB chain contains DSABs from both above and below the 16 MB line. Use LOC=ANY for this DSAB chain. |
MVC THEDD,=CL8'DD09'
GETDSAB DDNAME=THEDD,DSABPTR=MYDSAB
.
.
.
AUTO DSECT
THEDD DS CL8
MYDSAB DS AL4
In this example, the first invocation of GETDSAB will set MYDSAB to the address of the first DSAB in the DSAB chain. MYRC will contain the return code.
GETDSAB FIRST,DSABPTR=MYDSAB,RETCODE=MYRC
.
.
.
GETDSAB NEXT,DSABPTR=MYDSAB
.
.
.
AUTO DSECT
MYDSAB DS AL4
MYRC DS F
This technique can be used to get the DSAB for the first DD in a concatenation and then to step through the DSABs for all other DDs in the concatenation. It is the user's responsibility to determine when the DSAB for the last DD in the concatenation has been fetched, because a subsequent invocation of GETDSAB NEXT will simply return the next DSAB on the chain (if one exists), even if it is for a different DD statement.
GETDSAB DCBPTR=MYDCB,DSABPTR=MYDSAB,RSNCODE=MYRSN
.
.
.
AUTO DSECT
MYDSAB DS AL4
MYDCB DS AL4
MYRSN DS F
If DCBPTR points to an open DCB, DCBPTR and TCBPTR are mutually exclusive. The request will fail with return code 12. MYDSAB will contain 0.
GETDSAB DCBPTR=MYDCB,DSABPTR=MYDSAB,TCBPTR=MYTCB
.
.
.
AUTO DSECT
MYDSAB DS AL4
MYDCB DS AL4
MYTCB DS F