Description
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.
- 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:
|
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.
- 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
- 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:
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).
|
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. |