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 |
schset RS-type address or
register (2) - (12). |
,SCHSET=0 |
Default: 0 |
,UCBPTR=ucbptr |
ucbptr: RS-type
address. Note: Specify either DEVN or UCBPTR, but not both.
|
|
|
,IOCTOKEN=ioctoken addr |
ioctoken addr:
RX-type address or register (2) - (12). |
|
|
,LINKAGE=SYSTEM |
Default: SYSTEM |
,LINKAGE=BRANCH |
|
|
|
,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 UCB.
- ,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 UCB. 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
- ,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.
- ,UCBPTR=ucbptr
- Specifies the address of a fullword that contains the address
of the UCB common segment. The caller can obtain the address of the
UCB common segment by a UCBPTR parameter on a UCBLOOK macro.
- ,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, which is described in 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.
- ,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.
- ,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. Action: Ensure
that you have met the environmental requirements for the macro, and
reissue the macro.
|
08 |
03 |
Meaning: Program error. The UCB address provided by the caller does not
represent a valid UCB.
Action: Correct
the UCB address and reissue the macro.
|
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
|