The IOSPTHV macro enables authorized callers to validate the physical connectivity and availability of a channel path to a device. A path is considered available if an I/O operation can be initiated down a path, and the device can be selected. Validation does not guarantee that the device and path are error free. The IOSPTHV function depends on the availability of the IOS Address Space (IOSAS). IOSAS is started after Master Scheduler Initialization (MSI), and may be unavailable for periods of time during recovery. The issuer of the IOSPTHV macro must be able to handle the return/reason code indicating that the IOSAS is not active.
The requirements for the caller are:
| Environmental factor | Requirement |
|---|---|
| Minimum Authorization: | Supervisor state and any PSW key |
| Dispatchable unit mode: | Task |
| Cross memory mode: | PASN=HASN=SASN |
| AMODE: | 31-bit |
| ASC mode: | Primary |
| Interrupt status: | Enabled for I/O and external interrupts |
| Locks: | No locks held |
| Control parameters: | Control parameters must be in the primary address space |
None.
Do not have any enabled, unlocked task (EUT) FRRs established. If issued during IPL before the IOSAS (IOS address space) has initialized, MSI must have completed and WAIT=YES must be specified on the IOSPTHV macro.
If you attempt to validate a path to an active teleprocessing device (device types 2701, 2702, and 2703) or to an OSA or CTC device in use by VTAM with a long running I/O active, you will receive an error return and reason code.
Before issuing the IOSPTHV macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Some callers depend on register contents remaining the same before and after invoking 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.
None.
The standard form of the IOSPTHV macro is written as follows:
| Syntax | Description |
|---|---|
| name | name: symbol. Begin name in column 1. |
| ␢ | One or more blanks must precede IOSPTHV. |
| IOSPTHV | |
| ␢ | One or more blanks must follow IOSPTHV. |
| ,DEVN=device number | device number: RX-type address or address in register (2) - (12). |
| ,CHPID=path id | path id: RX-type address or address in register (2) - (12). |
| ,MSGBUF=msgbuf addr | msgbuf addr: RX-type address or address in register (2) - (12). |
| Default: none | |
| ,IOCTOKEN=ioctoken addr | ioctoken addr: RX-type address or address in register (2) - (12). |
| Default: none | |
| ,TIME=time | time: RX-type address or address in register (2) - (12). |
| Default: 5 seconds | |
| ,RETCODE=return code | return code: RX-type address or address in register (2) - (12). |
| ,RSNCODE=return code | reason code: RX-type address or address in register (2) - (12). |
| ,WAIT=NO | Default: NO |
| ,WAIT=YES | |
The parameters are explained as follows:
If you set the input IOCTOKEN to binary zeros, IOSPTHV sets IOCTOKEN to the current I/O configuration token.
For information about how you can use the configuration token to detect configuration changes, see z/OS MVS Programming: Authorized Assembler Services Guide.
WAIT=NO: Only process if the IOS address space has been initialized and not terminated.
WAIT=YES: Allows the request to wait for the IOSAS space to initialize as long as MSI has completed. Allows the request to wait for the IOS address space to reinitialize if terminated. The user of this keyword must ensure that no no resources are held that can cause the IOSAS not to initialize.
The time interval, whose address resides in virtual storage, is presented as zoned decimal digits of the form:
Note that the TIME parameter allows you to set an expiration time that is specific to IOSPTHV. The MIH interval, however, is used by other services associated with the device. Using the TIME parameter allows you to set an expiration time that is shorter than the MIH interval or the time that it takes the IOSPTHV macro to complete successfully.
Return codes, in hexadecimal, from the IOSPTHV macro are as follows:
| Hexadecimal Return Code | Hexadecimal Reason Code | Meaning and Action |
|---|---|---|
| 00 | None | Meaning: IOSPTHV processing completed successfully.
IOSPTHV successfully validated the specified path. The path is physically
available. Action: None |
| 04 | 04 | Meaning: IOSPTHV did not successfully validate
the specified path because the path was not physically available. Action: You need to investigate the problem further. Trying to vary the path online may produce further diagnosis data. |
| 04 | 08 | Meaning: User-specified time interval on
the TIME keyword expired before the I/O completed. Action: Verify that the time interval was long enough. Note that this return code is issued only if the time expired before the MIH interval. You can use the D MIH command or the MIHQUERY macro to determine the MIH interval for the device. |
| 08 | 04 | Meaning: IOSPTHV did not successfully validate
the specified path because the device number specified on the DEVN
keyword is not valid. Action: Ensure that you specified the device number correctly and retry the operation. Use the IOCTOKEN keyword to ensure that the UCB for that device number was not dynamically changed or deleted. |
| 08 | 08 | Meaning: IOSPTHV did not successfully validate
the specified path because the path specified on the CHPID keyword
is not valid. Action: Verify your program to ensure that the correct CHPID was passed and retry the operation. Use the IOCTOKEN keyword to ensure that the CHPID for the device was not dynamically changed or deleted. |
| 08 | 0C | Meaning: IOSPTHV did not successfully validate
the specified path because the time specified on the TIME keyword
was not valid. Action: Ensure that the time specified contains valid zoned decimal digits in the proper range. |
| 08 | 20 | Meaning: IOSPTHV did not successfully validate
the specified path because the UCB definition for the device represented
by the look-up argument (device number) has changed and is no longer
consistent with the UCB definition represented by the input I/O configuration
token. (This return code is only valid for callers using the IOCTOKEN
keyword.) Action: Ensure that the device number and CHPID are still valid and retry the operation passing a current IOCTOKEN. |
| 08 | 24 | Meaning: Processing cannot be performed
before the IOS address space (IOSAS) has initialized (unless MSI has
has completed and the WAIT=YES keyword was specified). Action: Retry the operation later in the IPL, after the IOSAS has been initialized, or after MSI by using the WAIT=YES keyword. |
| 08 | 28 | Meaning: IOSPTHV did not successfully validate
the specified path because an ESTAE environment could not be established. Action: Ensure that sufficient private area storage exists and retry the operation. |
| 0C | None | Meaning: An unexpected error occurred. Action: Record the return code and supply it to the appropriate IBM® support personnel. |
IOSSPTHV CSECT
IOSSPTHV AMODE 31 31-BIT ADDRESSING MODE
IOSSPTHV RMODE ANY Rmode any
SPACE 1
*.....................................................................*
* REGISTER ASSIGNMENTS *
*.....................................................................*
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6 Dynamic area register
UCBPTR7 EQU 7 UCB Pointer
R8 EQU 8
R9 EQU 9 Module base register
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13 Pointer to standard save area
R14 EQU 14
R15 EQU 15
SPACE 3
TITLE 'IOSSPTHV - IOSPTHV Sample Program'
*.....................................................................*
* *
* Standard Entry Linkage *
* *
*.....................................................................*
PRINT GEN
USING *,R9 Sets up base register
ENTRY STM R14,R12,12(R13) Save caller's registers
LR R9,R15 Establish module base register
MODESET KEY=ZERO,MODE=SUP
LA R0,DYNSIZE Load length of dynamic area
STORAGE OBTAIN,LENGTH=((R0)),SP=233 Gets dynamic area
LR R6,R1 Gets dynamic area address
USING DYNAREA,R6 Sets up dynamic area
ST R13,SAVE+4 Save caller's save area address
LA R15,SAVE Get this module's save area address
ST R15,8(R13) Save this modules save area address
* in caller's save area.
LR R13,R15 Set up addressability to this
* module's save area.
B MAINLINE
DC CL8'IOSSPTHV'
DC CL8'&SYSDATE'
DC CL8'&SYSTIME'
TITLE 'IOSSPTHV - SPTHV mainline '
*.....................................................................*
* *
* MAINLINE *
* *
*.....................................................................*
MAINLINE DS 0H
* L 10,X'10' Load CVT pointer
USING CVT,10
TM CVTDCB,CVTOSEXT Is the OSLEVEL extension present
BNO NO_IOSPTHV No, pre-MVS/SP Version 3 system
*
TM CVTOSLV1,CVTH5510 Running on version HBB5510?
BNO NO_IOSPTHV No, pre-HBB5510 system. IOSPTHV
* supported on HBB5510 and above
*.....................................................................*
* *
* Set up addressability to a storage area called UCBSTOR into which *
* the UCBSCAN macro will return the UCBs of devices it locates. *
* *
*.....................................................................*
LA UCBPTR7,UCBSTOR Get address of work area
USING UCB,UCBPTR7 Set up addressability
*
*.....................................................................*
* *
* Clear the UCBSCAN work area. *
* *
*.....................................................................*
LA R0,SCANWORK Set storage address
LA R1,100 Set storage length
SR R15,R15 Clear second operand
MVCL R0,R14 Clear the storage
*
*.....................................................................*
* *
* Loop through all DASD UCBs looking for the SYSRES volume. *
* *
* Note: There must be a SYSRES volume, and hence it will be found *
* in the scan loop which follows. *
* *
*.....................................................................*
SCANLOOP UCBSCAN COPY, X
WORKAREA=SCANWORK, X
UCBAREA=UCBSTOR, X
DEVCLASS=DASD, X
MF=(E,SCANLIST)
*.....................................................................*
* *
* If UCBSCAN returned a UCB, check whether the UCB represents *
* the SYSRES volume. If it isn't, continue checking more UCBs. If *
* the UCB represents the SYSRES device, end the loop. *
* *
*.....................................................................*
LTR R15,R15 Test return code
BNZ EXIT_ERROR Exit if non-zero
TM UCBSTAT,UCBSYSR Test if SYSRES volume
BZ SCANLOOP Keep looping if not*
*.....................................................................*
* *
* Issue the UCBINFO macro to obtain path-related information. *
* UCBINFO returns this information in a field called PATHSTOR, *
* mapped by IOSDPATH. *
* *
* Note- Since the device whose path information is sought is the *
* SYSRES device, an online path is certain to be found. *
* No loop counter is used. *
* *
*.....................................................................*
*
UCBINFO PATHINFO, X
DEVN=UCBCHAN, X
PATHAREA=PATHSTOR, X
MF=(E,INFOLIST)
*.....................................................................*
* *
* If UCBINFO cannot retrieve path-related information, that is, you *
* receive a non-zero return code, exit program. *
* *
*.....................................................................*
LTR R15,R15 Test for 0 return code
BNZ EXIT_ERROR Exit if bad RC
*.....................................................................*
* *
* Loop through the channel path ID array entries returned in *
* PATHSTOR to find the first online path. An online path *
* is represented by a flag in the array. *
* *
*.....................................................................*
LA R10,PATHSTOR Address of PATHINFO data
USING PATH,R10 Set up addressability to
* path information.
SR R8,R8 CHPID array index register.
CHPID_LOOP IC R11,PATHBITS(R8) Get flags from array entry.
STC R11,PATHSAVE Save entry
TM PATHSAVE,X'04' Test if the path is online
BO CHPID_EXIT If so, exit the loop
LA R8,L'PATHCHPIDARRAY(R8) Increment array index
B CHPID_LOOP
CHPID_EXIT LH R11,PATHCHPID(R8) Get the ID for the online
* channel path.
STC R11,CHPID Save the ID for the online
* channel path.
*.....................................................................*
* *
* Test the availability of the first online path to the SYSRES *
* volume by issuing the IOSPTHV macro. Supply the channel *
* path ID of the online path on the CHPID parameter. *
* *
* Note: Although the logical path mask (LPM) indicated that *
* the path was logically online to the device, it is *
* possible that the path is not operational. IOSPTHV *
* performs an I/O operation down the path to *
* determine if a non-operational condition exits. *
* *
*.....................................................................*
IOSPTHV DEVN=UCBCHAN, X
CHPID=CHPID, X
MF=(E,PTHVLIST)*.....................................................................*
* *
* A zero return code indicates an operational path to *
* the specified device. A non-zero return code indicates *
* a non-operational path. In the latter case, examine the *
* return and reason code to determine the cause. *
* *
*.....................................................................*
LTR R15,R15
BZ PATH_OK
B PATH_NOK
PATH_OK DS 0D
WTO 'IOSSPTHV-FIRST ONLINE PATH TO SYSRES VALIDATED', X
ROUTCDE=(11),DESC=(2)
B EXIT
PATH_NOK DS 0D
WTO 'IOSSPTHV-FIRST ONLINE PATH TO SYSRES NOT VALIDATED', X
ROUTCDE=(11),DESC=(2)
*
B EXIT
*.....................................................................*
* *
* Return a message to tell the user that the *
* IOSPTHV macro is not available on the system executing *
* this sample program. *
* *
*.....................................................................*
NO_IOSPTHV DS 0H
WTO 'IOSSPTHV - IOSPTHV SUPPORTED IN HBB5510 AND HIGHER', X
ROUTCDE=(11),DESC=(2)
B EXIT
*.....................................................................*
* *
* Return a message to the user alerting the user to an error *
* encountered during execution of this sample program. *
* *
*.....................................................................*
EXIT_ERROR DS 0H
WTO 'IOSSPTHV - THE SAMPLE ENCOUNTERED AN ERROR', X
ROUTCDE=(11),DESC=(2)
*.....................................................................*
* *
* Clean up and exit. *
* *
*.....................................................................*
EXIT DS 0H
L R13,SAVE+4 Reloads caller's save
* area addr into 11
LA R0,DYNSIZE Loads dynamic area size
STORAGE RELEASE,SP=233,ADDR=(R6),LENGTH=(R0)
MODESET KEY=NZERO,MODE=PROB
LM R14,R12,12(R13) Loads return regs
BR R14 Returns to caller
*
*
*......................................................................*
* *
* DSECTs to map save areas and dynamic area *
* *
*......................................................................*
DYNSTART DS 0H
DYNAREA DSECT
* Save areaSAVE DS 18F
DS 0D Force doubleword alignment
SPACE 2
*......................................................................*
* *
* List forms of macros. The list and execute forms of these macros *
* are used because this module is reentrant. *
* *
*......................................................................*
LIST_INFOSERV UCBINFO MF=(L,INFOLIST) List form of UCBINFO
INFOSERV_END DS 0D
PATHSTOR DS CL256 Storage for the PATHAREA
PATHSTOR_END DS 0D
LIST_PTHVSERV IOSPTHV MF=(L,PTHVLIST) List form of IOSPTHV
PTHVSERV_END DS 0D
LIST_SCANSERV UCBSCAN MF=(L,SCANLIST) List form of UCBSCAN
SCANSERV_END DS 0D
SCANWORK DS CL100 Scan work area
SCANWORK_END DS 0D
UCBSTOR DS CL48 UCB copy storage
UCBSTOR_END DS 0D
*......................................................................*
* *
* Work variables and data structures local to this module *
* *
*......................................................................*
CHPID DS C CHPID used for IOSCDR invocation
PATHSAVE DS C Work variable for CHPID array
* entries in the PATHAREA.
END_DYN DS 0D
DYNSIZE EQU *-DYNAREA Calculates Dynamic area
*
*......................................................................*
* *
* DSECTs *
* *
*......................................................................*
IOSSPTHV CSECT
TITLE 'IOSSPTHV - DSECT MAPPINGS'
EJECT
CVT LIST=YES,DSECT=YES
*
UCB DSECT
IEFUCBOB
*
PATHAREA IOSDPATH
END IOSSPTHV