UCBDEVN — Return EBCDIC device number for a UCB

Description

Use the UCBDEVN macro to obtain the printable EBCDIC format for the device number of a given unit control block (UCB). When issuing UCBDEVN, an unauthorized caller must pass a copy of the UCB unless one of the following is true:
  • The caller received the UCB address from an authorized program that can guarantee that the UCB is pinned or cannot be deleted by a dynamic configuration change.
  • 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 caller can obtain a copy of the UCB by using the UCBSCAN macro. See z/OS MVS Programming: Assembler Services Guide for information about accessing UCBs.

Before issuing UCBDEVN, authorized callers must pin the UCB 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.

If you are coding an authorized program that must pin the UCB, see z/OS MVS Programming: Authorized Assembler Services Guide for information about accessing UCBs.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state and any PSW key
Dispatchable unit mode: Task or SRB
Cross memory mode: Any PASN, any HASN, any SASN.
AMODE: 24- or 31-bit
ASC mode: Primary
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: No locks held
Control parameters: No requirement

Programming requirements

If you do not specify the UCBPTR parameter, you must include the IEFUCBOB mapping macro and establish addressability to the UCB common segment through a USING statement.

Restrictions

The caller of UCBDEVN cannot pass a copy of a UCB for a nonbase exposure of a multiple-exposure device.

When issuing UCBDEVN, the caller cannot pass a copy of an alias UCB of a parallel access volume.

UCBDEVN accepts above 16 megabyte UCBs, below 16 megabyte UCBs, and captured UCBs as input. To specify an above 16 megabyte UCB, the caller must run in AMODE 31. If the caller runs in AMODE 31 and passes a 24-bit UCB pointer, the pointer must have a clean high order byte.

Input register information

Before issuing the UCBDEVN macro, the caller must ensure that GPR 13 contains the address of an 18-word save area.

Output register information

When control returns to the caller, the GPRs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The UCBDEVN macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␣ One or more blanks must precede UCBDEVN.
   
UCBDEVN  
   
␣ One or more blanks must follow UCBDEVN.
   
DEVN=devnumber devnumber: RS-type address.
XDEVN=xdevn xdevn: Mutually exclusive with the DEVN keyword.
   
   ,UCBPTR=ucbptr ucbptr: RX-type address.
Note: If you omit this parameter, the system assumes that you have established addressability to the UCB common segment.
   
   ,NONBASE=NO Default: NO
   ,NONBASE=YES  
   

Parameters

The parameters are explained as follows:

DEVN=devnumber
Specifies the name of the fullword area in which the system returns the EBCDIC device number.
XDEVN=xdevn
Ten character field containing the EBCDIC form of the UCB name. Start of changeThe first byte is the length of the returned UCB name text. The remainder of the field contains the returned UCB name text, left-justified and padded with blanks.End of change The string that is returned is a logical device number composed of 4 or more hex digits.

XDEVN is mutually exclusive with the DEVN keyword.

,UCBPTR=ucbptr
Specifies a fullword containing the address of the UCB common segment, which contains the device number you need. If you omit this parameter, you must do the following:
  • Include the IEFUCBOB mapping macro in your program to map the UCB.
  • Establish addressability to the UCB common segment through a USING statement.
  • Place the address of the UCB common segment in the register specified in the USING statement.

If the UCB common segment is for a multiple exposure device, the system returns printable EBCDIC for the base exposure device number.

,NONBASE=NO
,NONBASE=YES
Specifies which device number the caller should receive for a specified alias UCB of a parallel access volume. NO specifies the base device number, and YES specifies the alias device number.

Return and reason codes

UCBDEVN does not return any return codes.

Example

Use the UCBDEVN macro to obtain the printable EBCDIC form of the device number for the UCB whose address is in UCBVAL. The system is to return the value in the fullword named WORD1. 
UCBDEVN DEVN=WORD1,UCBPTR=UCBVAL