The configuration data record (CDR) information that IOSCDR retrieves is mapped by the mapping macro IHACDR.
The format of IHACDR is in z/OS MVS Data Areas, Vol 3 (IEFDORC-ISGYQCBP). For more information about the contents of CDRs and information about the contents of node descriptors (NDs), see ESA/390 Common I/O Device Commands.
The requirements for the caller are:
| Environmental factor | Requirement |
|---|---|
| Minimum Authorization: | For LINKAGE=LINK, supervisor state and any PSW
key. For LINKAGE=SYSTEM, any one or more of the following:
|
| 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. |
Include the IHACDR mapping macro.
The caller can have no enabled, unlocked task (EUT) FRRs established.
Note that, when you issue IOSCDR, the service pins the device so that the device's UCB and other related data structures are not dynamically deleted while IOSCDR is retrieving the data. When IOSCDR completes, it unpins the device.
Before issuing the IOSCDR 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 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.
None.
The standard form of the IOSCDR macro is written as follows:
| Syntax | Description |
|---|---|
| name | name: symbol. Begin name in column 1. |
| ␢ | One or more blanks must precede IOSCDR. |
| IOSCDR | |
| ␢ | One or more blanks must follow IOSCDR. |
| DEVN=device num | device num: RX-type address or address in register (2) - (12). |
| ,SCHSET=xschset | xschset: RX-type address or register (2) - (12). |
| ,CHPID=path id | path id: RX-type address or address in register (2) - (12). |
| ,CDRAREA=cdr area | cdr area: RX-type address or address in register (2) - (12). |
| ,CDRLEN=cdr length | cdr length: RX-type address or address in register (2) - (12). |
| ,CDRSIZE=cdr size | cdr size: RX-type address or address in register (2) - (12). |
| ,LINKAGE=SYSTEM | Default: LINK |
| ,LINKAGE=LINK | |
| ,NODE_DESCRIPTOR=node descriptor | Optional input. It is the name (RS-type), or address in register (2)-(12), of the 32 bytes of storage for one node descriptor to be returned by the service. The node descriptor is associated with the control unit that is attached to the specified path in the input mask. |
| ,READ=NOIO | |
| ,READ=IO | |
| ,READ=COND | |
| ,STATUS=status | status: RX-type address or address in register (2) - (12). |
| ,TIME=time | time: RX-type address or address in register (2) - (12). |
| ,IOCTOKEN=ioctoken addr | ioctoken addr: RX-type address or address in register (2) - (12). |
| ,WWPN=xwwpn | xwwpn: RX-type address or address in register (2) - (12). |
| ,RETCODE=return code | return code: RX-type address or address in register (2) - (12). |
| ,RSNCODE=reason code | reason code: RX-type address or address in register (2) - (12). |
| ,PLISTVER=IMPLIED_VERSION | |
| ,PLISTVER=MAX | |
| ,PLISTVER=parameter list version | |
The parameters are explained as follows:
| Bit | Status | Meaning |
|---|---|---|
| 0 | on |
CDR returned was read from the device. |
| 1 | on |
Specified CHPID was logically online to the device. |
| 2 | on |
Specified device was online. |
| 3 - 7 | — | Reserved for IBM® use. |
The time interval, whose address resides in virtual storage, is presented as zoned decimal digits in the form:
Note that the TIME parameter allows you to set an expiration time that is specific to IOSCDR. 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.
If you set the input IOCTOKEN (specified by ioctoken addr) to binary zeros, IOSCDR 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.
The default is IMPLIED_VERSION. When PLISTVER is omitted, the default is the lowest version that allows all of the parameters specified on the invocation to be processed.
Return and reason codes, in hexadecimal, from the IOSCDR macro are as follows:
| Hexadecimal Return Code | Hexadecimal Reason Code | Meaning and Action |
|---|---|---|
| 00 | None | Meaning: IOSCDR processing completed successfully.
IOSCDR successfully retrieved the CDR for the specified device and
path. Action: None |
| 04 | 04 | Meaning: IOSCDR cannot retrieve an entire
CDR because the CDR area specified was not large enough to receive
the CDR. Action: The size of the CDR area is determined by CDRLEN. If you do not know what length to specify on CDRLEN, use the optional CDRSIZE parameter. If you specified CDRSIZE, IOSCDR returns the size that CDRAREA needs to be. Retry the operation with a CDR area of the same length as the length returned on CDRSIZE for the failing operation. |
| 04 | 08 | Meaning: IOSCDR cannot retrieve the CDR
for the specified device and path. If you specified READ=IO, either
a subchannel error or an I/O error could be preventing IOSCDR from
retrieving the CDR. If you specified READ=NOIO, a subchannel error
could be preventing IOSCDR from retrieving the CDR. Action: Further investigation of the problem is required. The D M=DEV command may provide further diagnosis data. For example, a subchannel error may have occurred because the device is not available. Attempt to vary the path online to produce further diagnosis data. See ESCON® Error Recovery Concepts and Procedures in an MVS Environment for further problem diagnosis information. If the problem persists, contact your IBM service representative. |
| 04 | 0C | Meaning: IOSCDR cannot retrieve the CDR
for the specified device and path. I/O was attempted to the device,
but the time interval specified on the TIME parameter expired before
I/O completed. Action: Verify that the time interval was sufficiently long. Note that the system issues this return code only if the time expired before the device's MIH interval. To determine the MIH interval, use the 'D MIH' command or the MIHQUERY macro. |
| 04 | 10 | Meaning: IOSCDR cannot retrieve the CDR
for the specified device and path because MVS does
not have a last known CDR to return. Action: Use one of
the following methods to retrieve a CDR:
|
| 04 | 14 | Meaning: IOSCDR cannot retrieve the last
known CDR. IOSCDR did not attempt I/O. Action: A system problem exists that prevents any last known CDR from being retrieved. Retry the operation. If the problem persists, contact IBM Software Support. |
| 08 | 04 | Meaning: The specified device does not
support the channel control words (CCWs) used to obtain configuration
data records. Action: None |
| 08 | 08 | Meaning: IOSCDR cannot retrieve the CDR
because the device number specified on the DEVN parameter is not valid. Action: Verify your program to ensure that the correct device was passed and retry the operation. If the device number is valid, use the IOCTOKEN keyword to ensure that the device is not dynamically changed or deleted. |
| 08 | 0C | Meaning: IOSCDR cannot retrieve the CDR
because the channel path id on the CHPID parameter 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 | 10 | Meaning: IOSCDR cannot retrieve the CDR
because the time specified on the TIME keyword is not valid. Action: Ensure that the time specified contains valid zoned decimal digits that are in the proper range. |
| 08 | 14 | Meaning: An incorrect CDR length was specified
on the CDRLEN keyword. Action: Verify that CDRLEN is greater than 0 and does not exceed 65535 bytes, then retry the operation. |
| 08 | 20 | Meaning: IOSCDR cannot retrieve the CDR
because the I/O configuration token that is current when IOSCDR is
invoked does not match the token whose address is supplied as input
by IOCTOKEN. Note that 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: IOSCDR cannot retrieve the CDR
because the IOS address space is not yet available. Action: Retry the operation after the IOS address space is available (master scheduler initialization has completed). |
| 08 | 28 | Meaning: IOSCDR cannot establish an ESTAE. Action: Ensure that there is sufficient private area storage, then retry the operation. |
| 08 | 2Cx | Meaning: The value specified on the SCHSET
keyword is not valid. Action: Supply the correct value on the SCHSET keyword. |
| 0C | None | Meaning: An unexpected error occurred. Action: Record the return code and supply it to the appropriate IBM support personnel. |
Assume you want to retrieve a configuration data record (CDR) to determine if the manufacturer of a SYSRES volume is IBM.
*.....................................................................*
* 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 'IOSSCDRE - IOSCDR 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'IOSSCDRE'
DC CL8'&SYSDATE'
DC CL8'&SYSTIME'
TITLE 'IOSSCDRE - SCDRE 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_IOSCDR No, pre-MVS/SP Version 3 system
*
TM CVTOSLV1,CVTH5510 Running on version HBB5510?
BNO NO_IOSCDR No, pre-HBB5510 system. IOSCDR
* 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 it is 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.
*.....................................................................*
* *
* The program identifies an online channel path to the SYSRES *
* volume. *
* Issue the IOSCDR macro to request a configuration data *
* record (CDR) for the SYSRES volume whose binary number *
* you specify in the UCBCHAN field. IOSCDR returns the CDR *
* in a storage area called CDRSTOR, whose length you specify *
* on the CDRLEN parameter. *
* Specify the channel path ID (CHPID) of the online *
* path returned by the UCBINFO macro. Also specify *
* the IOSCDR READ=NOIO option to avoid performing *
* I/O operations to the SYSRES volume. The IOSCDR READ=NOIO *
* option will have a CDR to return if the device *
* supports the self-description channel control words (CCWs). *
* *
*.....................................................................* IOSCDR DEVN=UCBCHAN, X
CHPID=CHPID, X
READ=NOIO, X
CDRAREA=CDRSTOR, X
CDRLEN=CDRLEN, X
CDRSIZE=CDRSIZE, X
MF=(E,CDRLIST)
*.....................................................................*
* *
* Check for a zero return code, indicating that IOSCDR completed *
* successfully. If it was not successful, examine the return *
* and reason codes to determine the cause. *
* *
* Note: A large CDRAREA was specified for the purposes of this *
* example to reduce the possibility of the CDRAREA being *
* too small to contain the returned CDR. It *
* is expected that in practical applications of the IOSCDR *
* service, users will obtain the CDRAREA by issuing the *
* GETMAIN macro. If the IOSCDR macro indicates *
* through return and reason codes that the *
* area passed was too small, issue the FREEMAIN macro to *
* release the storage, and obtain a larger area. Reissue *
* the IOSCDR macro. IOSCDR indicates the minimum size *
* for the CDRAREA through the CDRSIZE keyword. *
* *
*.....................................................................*
LTR R15,R15 Test for 0 return code
BNZ EXIT_ERROR Exit if bad RC
*.....................................................................*
* *
* Scan the CDR, mapped by IHACDR, searching for the node element *
* descriptor (NED) for the SYSRES volume. The NEDTCU field *
* should indicate that this device is a control unit. *
* *
*.....................................................................*
LA R10,CDRSTOR Set up addressability to the
* CDRAREA.
USING NED,R10
SR R8,R8 Clear NED index register.
CDR_LOOP TM NEDFLAGS,CDRFNED Check if the record represents an
* NED.
BNO CDR_ITERATE If not, try next record.
CLI NEDTYPE,NEDTCU Check if the NED represents a
* control unit.
BNE CDR_ITERATE If not, try next record.
B CDR_EXIT CU NED found.
CDR_ITERATE LA R8,32(R8) Increment index register.
LA R10,32(R10) Increment to next record in CDR.
CL R8,CDRSIZE Make sure that there are more
* records.
BL CDR_LOOP Iterate loop.
B EXIT_ERROR No CU NED found. Exit program
*.....................................................................*
* *
* If the program finds the NED, check if IBM manufactured *
* the control unit by looking in the NEDMANUF field of the *
* returned CDR. Check if the control unit was manufactured *
* by IBM. Return a WTO to the user describing the result. *
* *
*.....................................................................*CDR_EXIT DS 0D
CLC NEDMANUF,=CL3'IBM' Check if built by IBM
BNE NOT_IBM
B IS_IBM
IS_IBM DS 0D
WTO 'IOSSCDRE-CONTROL UNIT FOR SYSRES WAS BUILT BY IBM', X
ROUTCDE=(11),DESC=(2)
B EXIT
NOT_IBM DS 0D
WTO 'IOSSCDRE-CONTROL UNIT FOR SYSRES WAS NOT BUILT BY IBM',X
ROUTCDE=(11),DESC=(2)
*
B EXIT
*.....................................................................*
* *
* Return a WTO to the user saying that the IOSCDR macro *
* is not available on the system executing this sample program. *
* *
*.....................................................................*
NO_IOSCDR DS 0H
WTO 'IOSSCDRE - IOSCDR SUPPORTED IN HBB5510 AND HIGHER', X
ROUTCDE=(11),DESC=(2)
B EXIT
*.....................................................................*
* *
* Return a WTO to the user saying that the IOSCDR macro *
* encountered an error during execution of this sample program *
* *
*.....................................................................*
EXIT_ERROR DS 0H
WTO 'IOSSCDRE - 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
*
*
*......................................................................*
* *
* Define constants *
* *
*......................................................................*
CDRLEN DC F'512'
*......................................................................*
* *
* DSECTs to map save areas and dynamic area *
* *
*......................................................................*
DYNSTART DS 0H
DYNAREA DSECT
* Save area
SAVE DS 18F
DS 0D Force doubleword alignment
SPACE 2*......................................................................*
* *
* Issue the list forms of macros since the 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_CDRSERV IOSCDR MF=(L,CDRLIST) List form of IOSCDR
CDRSERV_END DS 0D
CDRSTOR DS CL512 Storage for the CDRAREA
CDRSTOR_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 *
* *
*......................................................................*
CDRSIZE DS F Actual size of CDR
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 *
* *
*......................................................................*
IOSSCDRE CSECT
TITLE 'IOSSCDRE - DSECT MAPPINGS'
EJECT
CVT LIST=YES,DSECT=YES
*
UCB DSECT
IEFUCBOB
*
CDRAREA IHACDR DSECT=YES
*
PATHAREA IOSDPATH
END IOSSCDRE