Description

The IOSSPOF macro is used to check for I/O configuration redundancy of DASD devices or pairs of DASD devices. To do this IOSSPOF verifies that there are redundant hardware components such that given failure of a hardware component the availability of the device would be unaffected.

Environment

The requirements for the caller of IOSSPOF are:

Environmental factor	Requirement
Dispatchable unit mode:	Task mode.
Minimum authorization:	Problem state. Any PSW key.
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	31-bit or 64-bit If in AMODE 64, specify SYSSTATE AMODE64=YES before invoking this macro.
ASC mode:	Primary
Interrupt status:	The caller must be enabled for I/O and external interrupts.
Locks:	The caller may not hold any locks.
Control parameters:	Control parameters must be in the primary address space.

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the IOSSPOF macro, the caller does not have to place any information into any general purpose register (GPR) or access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0: Reason code if the return code is not 0. Otherwise, used as a work register by the system.
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

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.

Performance implications

None.

Syntax

The standard form of the IOSSPOF macro is written as follows:

Syntax	Description

`name`	`name`: symbol. Begin `name` in column 1.

␢	One or more blanks must precede IOSSPOF.

IOSSPOF

␢	One or more blanks must follow IOSSPOF.

[,xlabel]	An optional symbol, starting in column 1, that is the name on the IOSSPOF macro invocation. The name must conform to the rules for an ordinary assembler language symbol. DEFAULT: No name.

PERFORM_CHECK
,DEVN1=`xdevn1`	`xdevn1`: RS-type address or register (2) - (12).
[,SCHSET1=`xschset1`]	`xschset1`: RS-type address or register (2) - (12).
[,DSN1=`xdsn1`]	`xdsn1`: RS-type address or register (2) - (12).
[,DEVN2=`xdevn2`]	`xdevn2`: RS-type address or register (2) - (12).
[,SCHSET2=`xschset2`]	`xschset2`: RS-type address or register (2) - (12).
[,DSN2=`xdsn2`]	`xdsn2`: RS-type address or register (2) - (12).
,VOLSER1=`xvolser1`	`xvolser1`: RS-type address or register (2) - (12).
[,DSN1=`xdsn1`]	`xdsn1`: RS-type address or register (2) - (12).
[,VOLSER2=`xvolser2`]	`xvolser2`: RS-type address or register (2) - (12).
[,DSN2=`xdsn2`]	`xdsn2`: RS-type address or register (2) - (12).
,DEVLIST=`xdevlist`	`xdevlist`: RS-type address or register (2) - (12).
,DEVCOUNT=`xdevcount`	`xdevcount`: RS-type address or register (2) - (12).
[,DSNLIST=`xdsnlist`]	`xdsnlist`: RS-type address or register (2) - (12).
,VOLLIST=`xvollist`	`xvollist`: RS-type address or register (2) - (12).
,VOLCOUNT=`xvolcount`	`xvolcount`: RS-type address or register (2) - (12).
[,DSNLIST=`xdsnlist`]	`xdsnlist`: RS-type address or register (2) - (12).

[,SPOFAREA=`xspofarea`]	`xspofarea`: RS-type address or register (2) - (12).

[,HCMSG=NO]	Default: NO
[,HCMSG=YES]
[HANDLE=`xhandle`]	`xvolser2`: RS-type address or register (2) - (12).

[,WTO=NO]	Default: NO
[,WTO=YES]

[,IND_CHECKS=YES]	Default: YES
[,IND_CHECKS=NO]
[,IND_CHECKS=ONLY]

[,SWITCH_CHECKS=YES]	Default: YES
[,SWITCH_CHECKS=NO]

[,CU_CHECKS=YES]	Default: YES
[,CU_CHECKS=NO]


[,RETCODE=`retcode`]	`retcode`: RS-type address or register (2) - (12).
[,RSNCODE=`rsncode`]	`rsncode`: RS-type address or register (2) - (12).

[,PLISTVER=`plistver`\|IMPLIED_VERSION]	Default: IMPLIED_VERSION

[,MF=S]	Default: MF=S
[,MF=(L,`xmfctrl`,`xmfattr`, 0D)]
[,MF=(M,`xmfctrl`,COMPLETE\|NOCHECK)]
[,MF=(E,`xmfctrl`,COMPLETE\|NOCHECK)]

Parameters

The parameters are explained as follows:

,PERFORM_CHECK

Perform single point of failure checks. The following is a set of mutually exclusive keys. This set is required; only one key must be specified.

,DEVN1=xdevn1

Belongs to a set of mutually exclusive keys. It is the name (RS-type), or address in register (2)-(12), of a halfword input containing the device number of a device to check for single points of failure.

,SCHSET1=xschset1

This is the name (RS-type), or address in register (2)-(12), of an optional byte input that contains the subchannel set of the device associated with the device number in DEVN1.

Default: 0 (Subchannel set zero).

,DSN1=xdsn1

This is the name (RS-type), or address in register (2)-(12), of an optional 44-character input that contains a data set name or a description of the dataset associated with device specified in DEVN1. The keyword is only used for message generation.

Default: * No dataset will be displayed in any outputed messages.

,DEVN2=xdevn2

This is the name (RS-type), or address in register (2)-(12), of an optional halfword input that contains a device number of a device used to verify hardware isolation between the devices specified with DEVN1 and this device.

Default: * Pair checking will not be done.

,SCHSET2=xschset2: This is the name (RS-type), or address in register (2)-(12), of an optional byte input that contains the subchannel set of the device associated with the device number in DEVN2.
Default: 0 (Subchannel set zero).
,DSN2=xdsn2: This the name (RS-type), or address in register (2)-(12), of an optional 44-character input that contains a data set name or a description of the dataset associated with device specified in DEVN2. The keyword is only used for message generation.
Default: * No dataset will be displayed in any outputed messages.

,VOLSER1=xvolser1

Belongs to a set of mutually exclusive keys. It is the name (RS-type), or address in register (2)-(12), of a 6-character input that contains the VOLSER of the device to check for a single point of failure.

,DSN1=xdsn1

This is the name (RS-type), or address in register (2)-(12), of an optional 44-character input that contains a data set name associated with volume specified in VOLSER1. This keyword is only used for message generation.

Default: *

,VOLSER2=xvolser2

It is the name (RS-type), or address in register (2)-(12), of a 6-character input that contains a VOLSER of a volume used to verify hardware isolation between the volumes specified with VOLSER1 and this volume.

Default: *

,DSN2=xdsn2: This is the name (RS-type), or address in register (2)-(12), of an optional 44-character input that contains a data set name associated with volume specified in VOLSER2. This keyword is used for only message generation.
Default: *

,DEVLIST=xdevlist

It is the name (RS-type), or address in register (2)-(12), of a one-byte input that contains the address to an array of fullwords with byte 1 containing zero, byte 2 containing the subchannel set of the device and bytes containing the subchannel set of the device and bytes and 3 and 4 containing the device number of the device to be checked. For example, 0001DE61 represents a device in subchannel set one with a device number of DE61.

Note: Only individual device checks are performed when DEVLIST is specified.

,DEVCOUNT=xdevcount: This is the name (RS-type), or address in register (2)-(12), of a fullword input that contains the number of devices in the DEVLIST array.

End of group of keys.

,DSNLIST=xdsnlist

This is the name (RS-type), or address in register (2)-(12), of an optional 4-byte input that contains the address of an array of CL44 elements that contain the dataset names of the devices that correspond to the DEVLIST parameter. This keyword is used for message generation only.

Default: *

,VOLLIST=xvollist

This is the name (RS-type), or address in register (2)-(12), of a one-byte input that contains the address an array of CL6 elements containing the VOLSERs of devices to check for single points of failure.

,VOLCOUNT=xvolcount: This is the name (RS-type), or address in register (2)-(12), of a fullword input containing the number of devices in the VOLLIST array.

End of group of keys.

,DSNLIST=xdsnlist

This is the name (RS-type), or address in register (2)-(12), of an optional 4-byte input that contains the address of an array of CL44 elements containing the dataset names of the devices that correspond to the VOLLIST paramemter. This information is used for only message generation.

Default: *

This ends the of set of mutually exclusive required keywords.

,SPOFAREA=xspofarea

This is the name (RS-type), or address in register (2)-(12), of an optional 4-byte output that will contain the address that contains the data requested. The data is mapped by IOSDSPOF, and is only valid if the service ended with a 4 or 8 return code. The SPOFAREA is obtained by the service and must be released by the caller using the length and subpool specified in the SPOFAREA. The SPOFAREA may be returned in a subpool that is not associated with the issuing task and thus, the caller must not assume the storage is automatically released when the task ends. If the caller is in a PSW key other than key 0-7 when the IOSSPOF service is invoked, the caller must ensure the SPOFAREA storage is accessed while in a PSW key equal to the key of the calling task.

,HCMSG=NO|YES

This is an optional keyword input that specifies whether or not health checker messages should be issued automatically with this service. HCMSG=YES without a HANDLE is only valid when running under IBM Health Checker for z/OS.

Default: NO.

,HCMSG=NO: Indicates that health checker messages should not be issued.
,HCMSG=YES: Indicates that health checker messages should be issued through HZSFMSG. HCMSG is only valid when the IOSSPOF service is called from a Health Check running under control of the IBM Health Checker for z/OS.
Default: NO

,HANDLE=xhandle: This is the name (RS-type), or address in register (2)-(12), of an optional 16-character input that specifies a handle (token) that identifies the check. This handle is returned through the HANDLE parameter of the HZSADDCK macro for a REMOTE=YES check. HANDLE is required when the service is called from a remote check and is ignored when the service is called from a local check. If IBM Health Checker for z/OS is not running at the time of invocation, then a return code of X'10' with a reason code of '02' will be returned.
Default: * Health checker messages will be issued as a REMOTE=NO call.

,WTO=NO|YES

This is an optional keyword input that specifies whether or not WTOs of IOSPFxxxI messages will be issued for this service.

Default: NO.

,WTO=NO: Indicates that WTOs will not be issued for this service.
,WTO=YES: Indicates that WTOs will be issued for this service. The IOSPFxxxI messages will be issued with a ROUTCDE=11.

,IND_CHECKS=YES|NO|ONLY

This is an optional keyword input that specifies whether or not single points of failure for individual devices should be checked. For example, checks that are not comparing two devices for mutual single points of failure should be done. This keyword is ignored if a single device is specified. The specific device checks like the following are preformed if YES is specified.

Check to see if a device has only one path available.
Check to see if the paths of the device share internal hardware subchannel components.

Default: YES.

,IND_CHECKS=YES: Indicates that individual device checks should be made. That is, all checks should be made.
,IND_CHECKS=NO: Indicates that individual device checks should not be made or only pair checks should be made.
,IND_CHECKS=ONLY: Indicates that only individual device checks should be made or no pair checks should be made.

,SWITCH_CHECKS=YES|NO

This is an optional keyword input that specifies whether or not to check for switch related single points of failure. It applies to individual and pairs checks. The following specific device checks are performed if YES is specified:

Check if all online CHPIDs are connected to the same switch.
Check if all devices are connected to the same switch.

Default: YES.

,SWITCH_CHECKS=YES: Indicates that switch related checks should be made.
,SWITCH_CHECK=NO: Indicates that switch related checks should not be made.

,CU_CHECKS=YES|NO

This is an optional keyword input specifies whether or not to check for control unit related single points of failure. It applies to individual and pair checks. The following specific device checks are performed if YES is specified:

Check if all devices are in the same DASD logical subsystem (LSS).
Check if all devices are in the same physical control unit.
Check if all devices are sharing the same set of control unit interfaces.

This keyword is ignored if a single device is specified. That is, DEVN1 is specified without DEVN2 or VOLSER1 is specified without VOLSER2.

Default: YES.

,CU_CHECKS=YES: Indicates that control unit related checks should be made.
,CU_CHECKS=NO: Indicates that control unit related checks should not be made.

,RETCODE=retcode

The name (RS-type) of an optional fullword output variable, or register (2)-(12) or (15), into which the return code is to be copied from GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR15.

,RSNCODE=xrsncode

The name (RS-type) of an optional fullword output variable into which the reason code is to be copied from GPR 0. If you specify 0, 00, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0.

,PLISTVER=plistver | MAX | IMPLIED_VERSION

Is an optional byte input decimal value in the "1–1" range that specifies the macro version. PLISTVER is the only key allowed on the list form of MF and determines which parameter list is generated. Note that MAX may be specified instead of a number and will cause the parameter list to be of the largest size currently supported. This size may grow from release to release (thus possibly affecting the amount of storage needed by your program). If your program can tolerate this, IBM® recommends that you always specify MAX when creating the list form parameter list as this will ensure that the list form parameter list is always long enough to hold whatever parameters might be specified on the execute form.

Default: IMPLIED_VERSION. When PLISTVER is omitted, the default is the lowest version which allows all of the parameters specified on the invocation to be processed.

,MF=S|L|M|E

An optional keyword input that specifies the macro form.

Default: S.

,MF=S

Specify the standard form of the macro. The "S" form builds an inline parameter list and generates the macro invocation to transfer control to the service. Full checking for required macro keys is done along with supplying defaults for omitted optional parameters.

,MF=(L,xmfctrl,xmfattr, 0D)

Specifies the list form of the macro. The "L" form defines an storage area for the parameter list. Only the PLISTVER key can be specified on the invocation. All other macro parameters are flagged as errors. If PLISTVER is not specified, the original parameter list definition is used.

xmfctrl: A required input. It is the name of a storage area for the parameter list.
xmfattr: An optional 60-character input string that varies from 1 to 60 characters. Use it to force boundary alignment of the parameter list. Use only 0F or 0D. The default is 0D, which forces the parameter list to a doubleword boundary.

,MF=(M,xmfctrl,COMPLETE|NOCHECK)

Specifies the modify form of the macro. The "M" form generates code to put the parameters into the parameter list specified by xmfctrl.

xmfctrl

A required input. It is the name (RS-type), or address in register (1)-(12), of a storage area for the parameter list.

,COMPLETE|NOCHECK

An optional keyword input that specifies the degree of macro parameter syntax checking.

Default: COMPLETE.

,COMPLETE: Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK: Checking for required macro keys is not done or defaults are not supplied for omitted optional parameters.

,MF=(E,xmfctrl,COMPLETE|NOCHECK

Specifies the execute form of the macro. The "E" form generates code to put the parameters into the parameter list specified by xmfctrl and invoke the desired service.

xmfctrl

A required input. It is the name (RS-type), or address in register (1)-(12), of a storage area for the parameter list.

,[COMPLETE|NOCHECK]

An optional keyword input that specifies the degree of macro parameter syntax checking.

Default: COMPLETE.

,COMPLETE: Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
,NOCHECK: Checking for required macro keys is not done or defaults are not supplied for omitted optional parameters.

ABEND codes

None.

Return codes

Return codes, in hexadecimal, from the IOSSPOF macro are as follows:

Hexadecimal Return Code	Equate Symbol Meaning and Action
00	Equate Symbol: SPOF_RC_Ok Meaning: No single points of failure detected. Action: None.
04	Equate Symbol: SPOF_RC_SomeChecksFailed Meaning: The service couldn't perform all checks specified, but no single points of failure were detected. Action: Some checks may fail due to switch devices not being online at the time of the check. All switch devices must be online to determine if control unit interfaces are single point of failure free.
08	Equate Symbol: SPOF_RC_SPOFFound Meaning: Single points of failure were detected. Action: Refer to IOSPFxxxI message for action. Hex Reason Code Meaning/Action 00 Equate Symbol: SPOF_RSN_AllDevicesFound Meaning: While a single point of failure was discovered all devices were found. 01 Equate Symbol: SPOF_RSN_DeviceNotFound Meaning: Single points of failure were detected, and one or more of the devices specified are not found.
0C	Equate Symbol: SPOF_RC_ProgramError Meaning: Program error. Action: None. Hex Reason Code Meaning/Action 01 Equate Symbol: SPOF_RSN_InvalidParmListVers Meaning: It was discovered that the macro was invoked with an invalid parameter list. Action: Specify a valid parameter list version. 02 Equate Symbol: SPOF_RSN_InvalidCount Meaning: The number of devices specified via the DEVCOUNT parameter or volume serial numbers via the VOLCOUNT parameter is invalid. Action: Change DEVCOUNT or VOLCOUNT to be less than 65536 and greater than zero. 03 Equate Symbol: SPOF_RSN_ImproperModes Meaning: IOSSPOF was invoked in an improper mode. Action: See environment specification for what modes IOSSPOF can be invoked and only invoke in supported modes. 04 Equate Symbol: SPOF_RSN_ImproperDevlistEntry Meaning: A device in the device list did not match the format '000sdddd' where '000s' is the subchannel set and 'dddd' is the device number. Action: Adjust DEVLIST parameter to match the format. 05 Equate Symbol: SPOF_RSN_BadParmListAccess Meaning: Abend accessing parameter list. Action: Verify that the parameters can be accessed by invokers key.
10	Equate Symbol: SPOF_RC_EnvironError Meaning: Environmental error. Action: None. Hex Reason Code Meaning/Action 01 Equate Symbol: SPOF_RSN_IOSSPOFNotAvail Meaning: The IOSSPOF service is not available at this time. Action: Wait until the IOSAS address space is available. 02 Equate Symbol: SPOF_RSN_HlthChkerNotAvail Meaning: The Health Checker environment isn't available and is available if HCMSG=YES and HANDLE is specified. Action: Start the Health Checker if HCMSG=YES is required.
20	Equate Symbol: SPOF_RC_SystemError Meaning: System error. Action: None.

Return and reason codes

Macro IOSDSPOF provides equate symbols for the return and reason codes.

Hexadecimal Return Code	Hexadecimal Reason Code	Meaning
00	00	Always set.
04	00	Always set.
08	00	Single points of failure were detected, all devices are found.
08	01	Single points of failure were detected, and one or more of the devices specified are not found.
0C	01	Incorrect parameter list version.
0C	02	The number of devices specified through the DEVCOUNT parameter or volume serial numbers specified through the VOLCOUNT parameter is incorrect.
0C	03	The caller is in an improper mode when invoked.
0C	04	A device in the device list does not match the format '000sdddd' where '000s' is subchannel set and 'dddd' is the device number.
0C	05	Abend accessing parameter list.
10	01	The IOSSPOF service is not available at this time.
10	02	The Health Checker service is not available at this time.
20	00	Always set.