UCBINFO PATHINFO

Use the UCBINFO PATHINFO macro to obtain information about the device path and type of channel path associated with the device.

Syntax

The standard form of the PATHINFO option of the UCBINFO macro is written as follows:

Syntax Description
   
   name name: symbol. Begin name in column 1.
   
␢ One or more blanks must precede UCBINFO.
   
UCBINFO  
   
␢ One or more blanks must follow UCBINFO.
   
PATHINFO  
   
,PATHAREA=patharea addr patharea addr: RX-type address or register (2) - (12).
   
,DEVN=devn addr devn addr: RS-type address or register (2) - (12).
   
    ,SCHSET=schset addr schset addr RS-type address or register (2) - (12).
    ,SCHSET=0 Default: 0
   
   
    ,IOCTOKEN=ioctoken addr ioctoken addr: RX-type address or register (2) - (12).
   
    ,PLISTVER=IMPLIED_VERSION  
    ,PLISTVER=MAX Default: IMPLIED_VERSION
    ,PLISTVER=plistver plistver: 2
   
    ,RETCODE=retcode addr retcode addr: RX-type address or register (2) - (12).
   
    ,RSNCODE=rsncode addr rsncode addr: RX-type address or register (2) - (12).
   

Parameters

The parameters are explained as follows:

PATHINFO
Specifies that the system is to return information about the device path and type of channel path for the specified device.
,PATHAREA=patharea addr
Specifies the address of the required 256-byte output field into which the system is to return information about the device path and type of channel path for the specified device. This field is mapped by the mapping macro IOSDPATH.
,DEVN=devn addr
Specifies the address of a halfword that contains, in binary form, the device number of the device.
,SCHSET=schset addr
,SCHSET=0
Specifies the name (RS-type), or address in register (2)-(12), of an optional byte input that specifies a subchannel set for which the system is to return information about the device path and type of channel path. DEFAULT: 0.
,IOCTOKEN=ioctoken addr
Specifies the address of a 48-character storage area that contains the MVS I/O configuration token. The caller can obtain this token by issuing the IOCINFO macro. z/OS MVS Programming: Assembler Services Reference ABE-HSP If the I/O configuration token that is current when UCBINFO is invoked does not match the token whose address is supplied here, the system issues a return code to the caller.

If you set the input IOCTOKEN (specified by ioctoken addr) to binary zeros, UCBINFO sets IOCTOKEN to the current I/O configuration token.

,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:
  • IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
  • MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.

    If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.

  • 2, if you use the currently available parameters.
To code, specify in this input parameter one of the following:
  • IMPLIED_VERSION
  • MAX
  • A decimal value of 2
,RETCODE=retcode addr
Specifies the address of a fullword field into which the system copies the return code from GPR 15.
,RSNCODE=rsncode addr
Specifies the address of a fullword field into which the system copies the reason code from GPR 0.

Return and reason codes

When the UCBINFO PATHINFO macro returns control to your program, GPR 15 (or retcode addr, if you coded RETCODE) contains a return code, and GPR 0 (or rsncode addr, if you coded RSNCODE) contains a reason code.

Hexadecimal Return Code Hexadecimal Reason Code Meaning and Action
00 None Meaning: The PATHINFO function completed successfully.

Action: None.
04 None Meaning: Program error. No UCB exists for the device number specified in the DEVN parameter.

Action: Correct the device number and reissue the macro.
08 01 Meaning: Program error. A caller in AR mode specified an ALET that was not valid.

Action: Correct the ALET and reissue the macro.
08 02 Meaning: Program error. An error occurred when the system tried to access the caller's parameter list. This might be due to using a keyword that requires authorization but the caller was not authorized, that is the Supervisor state or PSW key 0 - 7.

Action: Ensure that you have met the environmental requirements for the macro, and reissue the macro.
08 03 Meaning: Program error. An unauthorized caller specified the UCBPTR parameter.

Action: Specify the DEVN parameter instead of the UCBPTR parameter to indicate the device for which the system is to obtain path information.

08 05 Meaning: Program error. An error occurred when the system referenced the caller-supplied area specified in the IOCTOKEN parameter. This reason code is valid only for callers using the IOCTOKEN parameter.

Action: Correct the IOCTOKEN parameter.
08 08 Meaning: Program error. An error occurred when the system attempted to reference the area specified by the PATHAREA parameter.

Action: Correct the address specified on the PATHAREA parameter and reissue the macro.
08 0B Meaning: The value specified on the SCHSET keyword is not valid.

Action: Enter a valid value.
0C None Meaning: Environmental error. The I/O configuration token supplied through the IOCTOKEN parameter is not current. This return code is valid only for callers using the IOCTOKEN parameter.

Action: Obtain the current I/O configuration token by issuing an IOCINFO macro or by setting the input IOCTOKEN parameter in the UCBINFO macro to zero.
18 04 Meaning: System error. The subchannel is in permanent error and cannot be accessed.

Action: Supply the return and reason codes to the appropriate IBM support personnel.
18 08 Meaning: Environmental error. The UCB is not connected to a subchannel.

Action: Verify that there is a device at the device number associated with the subchannel, and reissue the macro.
20 None Meaning: System error. An unexpected error occurred.

Action: Supply the return code to the appropriate IBM support personnel.

Example

To invoke UCBINFO to return device path and type of channel path information, code: 
         UCBINFO  PATHINFO,PATHAREA=INFOAREA,DEVN=DEVNUM,         X
         RETCODE=INFORTCD
         .
         .
         .

         DS  0D
INFOAREA DS  CL256
INFORTCD DS  F
DEVNUM   DS  H