Release a captured UCB function

Syntax

The standard form of the IOSCAPU macro with the UCAPTUCB 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.

UCAPTUCB

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

,LASTING=NO	Default: LASTING=NO
,LASTING=YES

,CAPTCOM=NO	Default: CAPTCOM=NO
,CAPTCOM=YES

,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:

UCAPTUCB

Specifies that you want a captured UCB released.

,CAPTPTR=captptr

Specifies the address of the common segment of the captured UCB that you want released.

,CAPTCOM=NO

,CAPTCOM=YES

Specifies whether the above 16 megabyte UCB should be released from common storage.

NO: Release the UCB from private storage of the current address space
YES: Release the UCB from common storage.

,LASTING=NO

This is NOT a UCAPTUCB associated with a previous CAPTUCB (where LASTING=YES was specified).

,LASTING=YES

This is a UCAPTUCB associated with a previous CAPTUCB where LASTING=YES was specified).

Note: If, and only if, LASTING=YES is specified when capturing a UCB, LASTING=YES should be specified when releasing the same captured UCB.

,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 UCAPTUCB Macro
Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	None	Meaning: IOSCAPU completed successfully. Action: None.
04	08	Meaning: Warning. The program attempted to release an actual below 16 megabyte UCB. Action: None required if the program tries to release any input UCB. Otherwise, check the address of the captured UCB. Correct the error and rerun the program.
08	08	Meaning: Program error. The program attempted to release a captured UCB and the captured UCB does not exist in the address space. Action: Check to see if your program correctly specified the captured UCB address on the CAPTPTR 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 UCBPTR or CAPTPTR parameter. Correct the error and rerun the program.
08	18	Meaning: Warning. The program attempted to release an actual above 16 megabyte UCB. Action: None required if the program tries to release any input UCB. Otherwise, check the address of the captured UCB. 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

Release the captured UCB at the address specified by CAPTURED.

IOS_UNCA IOSCAPU UCAPTUCB,                                             X

               CAPTPTR=CAPTURED,                                       X

               LINKAGE=BRANCH,                                         X

               MF=(E,CAPTLIST)