Translate captured to actual address function

Syntax

The standard form of the IOSCAPU macro with the CAPTOACT option is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede IOSCAPU.

IOSCAPU

␢	One or more blanks must follow IOSCAPU.

CAPTOACT

,CAPTPTR=`captptr`	`captptr` :RS-type or address in register (2) - (12).
,UCBPTR=`ucbptr`	`ucbptr` :RS-type or address in register (2) - (12).

,ASID=CURRENT	Default: ASID=CURRENT
,ASID=`asid`	`asid` :RS-type or address in register (2) - (12).

,LINKAGE=SYSTEM	Default: LINKAGE=SYSTEM
,LINKAGE=BRANCH

,RETCODE=`retcode addr`	`retcode addr` : RS-type address or address in register (2) - (12) of fullword output variable.

,RSNCODE=`rsncode addr`	`rsncode addr` : RS-type address or address in register (2) - (12) of fullword output variable.

Parameters

The parameters are explained as follows:

CAPTOACT

Specifies that you want the actual UCB address for a captured UCB.

,CAPTPTR=captptr

Specifies the pointer to the address of the common segment of the captured UCB.

,UCBPTR=ucbptr

Specifies a pointer to contain the address of the actual UCB common segment.

,ASID=CURRENT

,ASID=asid

Specifies the address space in which the captured UCB was originally captured.

CURRENT: Specifies the address space of the program
asid: Specifies the name of another address space

,LINKAGE=SYSTEM

,LINKAGE=BRANCH

Specifies the type of call that should be generated:

SYSTEM: Specifies a program call (PC)
BRANCH: Specifies a branch entry

,RETCODE=retcode addr

Specifies the location where the system is to store the return code. The return code is also in GPR 15.

,RSNCODE=rsncode addr

Specifies the location where the system is to store the reason code. The reason code is also in GPR 0.

ABEND codes

IOSCAPU might abnormally end with abend code X'2C6'. See z/OS MVS System Codes for an explanation of abend code X'2C6'.

Return and reason codes

When the IOSCAPU macro returns control to your program, GPR 15 (and retcode if you coded RETCODE) contains the return code. If the return code is not 0, GPR0 (and rsncode if you coded RSNCODE) contains the reason code.

Table 1. Return and Reason Codes for the IOSCAPU CAPTOACT Macro
Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	None	Meaning: IOSCAPU completed successfully. Action: None.
04	0C	Meaning: Warning. The program requested the actual address of an actual UCB. Action: None required if the program always attempts to receive the actual UCB address for a UCB. Otherwise, check the address of the captured UCB. Correct the error and rerun the program.
08	04	Meaning: Program error. The program attempted to receive the actual UCB address for a captured UCB and the address space identifier specified for the captured UCB does not exist or the address space was swapped out. Action: Retry the request because the address space might have been swapped in. Also, check to see if your program correctly specified the address space of the captured UCB on the ASID parameter. Correct the error and rerun the program.
08	10	Meaning: Program error. The program attempted to use a UCB address that is not a valid UCB. Action: Check to see if your program correctly specified the UCB address on the CAPTPTR parameter. Correct the error and rerun the program.
20		Meaning: System error. This return code is for IBM® diagnostic purposes only. Most likely, the system could not obtain storage that it required. Action: Record the return code and supply it to the appropriate IBM support personnel.

Example

Receive the actual UCB address (in ACTUAL) of the captured UCB address specified by CAPTURED.

IOS_TRAN IOSCAPU CAPTOACT,                                             X

               UCBPTR=ACTUAL,                                          X

               CAPTPTR=CAPTURED,                                       X

               LINKAGE=BRANCH,                                         X

               MF=(E,CAPTLIST)