IOSINFO — Obtain the subchannel number for a UCB

Description

The IOSINFO macro obtains the subchannel number for a specified unit control block (UCB). The macro returns the subsystem identification word (SID), which identifies the subchannel number of the UCB, in a user-specified location. The SID is a fullword value whose first halfword contains X‘0001’ and ending halfword contains the subchannel number.

Environment

The issuer of IOSINFO must be executing:
  • In 31-bit addressing mode
  • In either task mode or SRB mode
  • Locked or unlocked

Additionally, the issuing program must include the CVT and IHAPSA mapping macros. All addresses must be 31-bit addresses and the issuing program must pass a below 16 megabyte actual or captured UCB.

Input register information

Before entry to this macro, register 13 must contain the address of a standard 18-word save area.

Output register information

After the caller issues the macro, the macro might use some registers as work registers or might change the contents of some registers. When the macro 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 GPRs contain:
Register
Contents
0
Used as a work register by the macro
1
Contains the SID if the return code in register 15 is 0; otherwise, used as a work register by the macro.
2-13
Unchanged
14
Used as a work register by the macro
15
Return code

Syntax

The IOSINFO macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede IOSINFO.
   
IOSINFO  
   
␢ One or more blanks must follow IOSINFO.
   
FUNCTN=SUBCHNO  
   
,UCB=ucb addr ucb addr: A-type address or register (0) - (15).
   
,OUTPUT=output addr output addr: A-type address or register (0) - (14).
   
,RTNCODE=retcde addr retcde addr: A-type address or register (0) - (15).
   

Parameters

The parameters are explained as follows:

FUNCTN=SUBCHNO
Specifies that a subchannel number is to be obtained.
,UCB=ucb addr
Specifies the address of a fullword on a fullword boundary containing the address of a unit control block (UCB).
,OUTPUT=output addr
Specifies the address of a fullword on a fullword boundary that will contain the subsystem identification word (SID) upon completion.

The SID is a fullword value that identifies the subchannel. The first halfword is X‘0001’, and the last halfword contains the subchannel number.

The output address must reside in 31-bit addressable storage.

,RTNCODE=retcde addr
Specifies the location where the system is to store the return code. The return code is also in general purpose register (GPR) 15. The specified storage location must be a fullword on a fullword boundary.

The return code address must reside in 31-bit addressable storage.

Return codes

When control returns from IOSINFO, GPR 15 (and retcde addr, if you coded RTNCODE) contains one of the following return codes:

Hexadecimal Code Meaning
00 The address specified on the OUTPUT parameter contains the SID.*
04 The UCB was disassociated from the subchannel at the time of the IOSINFO service routine invocation.

* In some cases, the subchannel number in the SID might not be valid. Any disassociation of the UCB and the subchannel means the subchannel number in the SID is not valid. If the UCB is disassociated from the subchannel after the IOSINFO service routine invocation, no notification can be given.

Example 1

Obtain the subchannel number for a UCB whose address is in register 1. Specify the SID output to be placed in register 2 and the return code to be placed in register 3. 
IOSINFO  FUNCTN=SUBCHNO,UCB=(1),OUTPUT=(2),RTNCODE=(3)

Example 2

Obtain the subchannel number for a UCB whose address is in location ADDR. Specify the SID output to be placed in location ADDX and the return code to be placed in register 3. 
IOSINFO  FUNCTN=SUBCHNO,UCB=ADDR,OUTPUT=ADDX,RTNCODE=(3)

Example 3

Obtain the subchannel number for a UCB whose address is in register 2. Specify the SID output to be placed in register 3 and the return code to be placed in location ADDR. 
IOSINFO  FUNCTN=SUBCHNO,UCB=(2),OUTPUT=(3),RTNCODE=ADDR