Description

Description

z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
SA23-1375-00

Pinning a UCB ensures that the UCB cannot be deleted while a program is in the process of looking at a UCB. Programs that pin a UCB are also responsible for unpinning it once the UCB is no longer subject to processing.

Authorized programs that obtain UCB addresses, either through UCB services or other means, can use the UCBPIN macro to pin and unpin UCBs. Pinning and unpinning should be done any time a UCB is used, unless one of the following is true:

The caller is running in an environment where dynamic configuration changes cannot occur.
The caller can otherwise guarantee that the UCB will not be deleted. (The device is allocated.)

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or PKM keys 0-7. For LINKAGE=BRANCH, all of the following: Supervisor state with key 0 31-bit addressing mode Primary ASC mode Parameter list and any data areas it points to must be in fixed storage or, if the caller is disabled, in disabled reference (DREF) storage.
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN=SASN or PASN¬=HASN¬=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	No requirement
Control parameters:	Must be in the primary address space or be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL)

Programming requirements

If the program is in AR mode, issue the SYSSTATE ASCENV=AR macro before UCBPIN. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.

Restrictions

None.

Register information

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.

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: Reason code if GPR 15 contains a return code of 08; otherwise, used as a work register by the system
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Performance implications

None.

Syntax

The standard form of the UCBPIN macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede UCBPIN

UCBPIN

␢	One or more blanks must follow UCBPIN

PIN
UNPIN	Note: See the table following this diagram for valid parameter combinations.

,PTOKEN=`ptoken addr`	`ptoken addr`: RS-type address or register (2) - (12).

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

,TEXT=`text addr`	`text addr`: RX-type address

,LASTING

,IOCTOKEN=`ioctoken addr`	`ioctoken addr`: RX-type address or register (2) - (12).

,RETCODE=`retcode addr`	`retcode addr`: RX-type address or register (2) - (12).

,RSNCODE=`rsncode addr`	`rsncode addr`: RX-type address or register (2) - (12).

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

,TO=`xto`	`xto`: RS-type address or register (2) - (12).

,FROM=`xfrom`	`xfrom`: RS-type address or register (2) - (12).

,RETCODE=`retcode addr`	`retcode addr`: RX-type address or register (2) - (12).

,RSNCODE=`rsncode addr`	`rsncode addr`: RX-type address or register (2) - (12).

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

The following table shows how other parameters may be used with PIN and UNPIN.

Parameters	PIN	UNPIN
PTOKEN	required	required
UCBPTR	required	not valid
TEXT	required	not valid
LASTING	optional	not valid
IOCTOKEN	optional	not valid
LINKAGE	optional	optional
RETCODE	optional	optional
RSNCODE	optional	optional

Parameters	PIN	UNPIN
PTOKEN	required	required
UCBPTR	required	not valid
TEXT	required	not valid
LASTING	optional	not valid
IOCTOKEN	optional	not valid
LINKAGE	optional	optional
RETCODE	optional	optional
RSNCODE	optional	optional
TO	not valid	not valid
FROM	not valid	not valid

Parameters

The parameters are explained as follows:

PIN

UNPIN

Specifies whether the UCB is to be pinned or unpinned.

,PTOKEN=ptoken addr

Specifies the address of an 8-character field used to contain the pin token. For PIN requests, PTOKEN specifies an output field that receives the pin token for the UCB that is to be pinned. For UNPIN requests, PTOKEN specifies an input field that contains the pin token for the UCB that is to be unpinned; this token must match the one that was returned on the corresponding PIN request. UCBPIN will reset PTOKEN to binary zeros if the UNPIN function is successful.

,UCBPTR=ucbptr addr

Specifies the address of a pointer containing the address of the UCB common segment for the UCB that is to be pinned.

,TEXT=text addr

Specifies the address of a 58-character input field containing text that documents the reason for the PIN request. If the pin request remains outstanding during a request for a configuration change that would delete this UCB, the text specified by the TEXT parameter will be displayed in a message identifying the reason for a configuration change failure.

,LASTING

Specifies that the UCB will not be unpinned automatically by the system at the time of termination of the task or address space with which the pin is associated.

When you code LASTING, the system cannot dynamically delete the UCB until your program issues UCBPIN with the UNPIN parameter.

,IOCTOKEN=ioctoken addr

Specifies the address of a 48-character area that contains the MVS™ I/O configuration token that you supply to UCBPIN. You can obtain this token by issuing the IOCINFO macro, which is described in z/OS MVS Programming: Assembler Services Reference ABE-HSP. If the I/O configuration token that is current when UCBPIN is invoked does not match the token specified as input by ioctoken addr, the caller will be notified through a return code.

If the input IOCTOKEN (specified by ioctoken addr) is set to binary zeros, UCBPIN will set IOCTOKEN to the current I/O configuration token.

,RETCODE=retcode addr

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

,RSNCODE=rsncode addr

Specifies the fullword location where the system is to store the reason code. The reason code is also in GPR 0 if the return code is X'08'.

,LINKAGE=SYSTEM

,LINKAGE=BRANCH

Specifies the type of call that the system is to generate:

SYSTEM: Specifies a Program Call (PC)
BRANCH: Specifies a Branch entry

LINKAGE=BRANCH is intended for performance-sensitive programs.

Return and reason codes

When control returns from UCBPIN, GPR 15 (and retcode addr, if you coded RETCODE) contains one of the following return codes:

Table 1. Return Codes for the UCBPIN Macro
Hexadecimal Return Code	Meaning
00	Meaning: UCBPIN completed successfully. For PIN requests, the UCB has been pinned and the pin token has been returned in PTOKEN. For UNPIN requests, the UCB has been unpinned and PTOKEN has been reset to binary zeros.
08	Meaning: There is an error in the caller's parameters, as explained by the hexadecimal reason code that accompanies this return code. The reason code is in GPR 0 (and in `rsncode addr`, if you coded RSNCODE). Reason Code Meaning 01 An ALET in the parameter list is not valid; the caller might have inadvertently written over an area in the parameter list. 02 An error occurred in accessing the caller's parameter list. 03 The UCB address provided by the caller does not represent a valid UCB. 04 The PTOKEN supplied as input on an UNPIN request does not represent a valid pin token. 05 An error occurred in referencing the user-supplied work area for the IOCTOKEN. This reason code is valid only for callers using the IOCTOKEN keyword. 0A An error occurred in referencing the user-supplied work area for the pin reason text. This reason code is valid only for callers using the TEXT keyword.
0C	Meaning: The UCB definition is not consistent with the input configuration token, or a DDR has occurred. This return code is valid only for callers using the IOCTOKEN keyword.
20	Meaning: An unexpected error occurred.