IOSZHPF — zHPF channel program capabilities service

Description

The IOSZHPF macro provides information about the zHPF capabilities of a device from the operating system, processor, channel, and device point of view. The information returned is mapped by IOSDZHPF and reflects the minimum capability of all of the online channels for a device. For example, if a device has two online channels and one channel supports a new function and the other does not, that function will not be reported.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem or supervisor state. Any PSW key.
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN=SASN
AMODE:	31- bit
ASC mode:	Primary
Interrupt status:	Enabled or disabled for I/O and external interrupts.
Locks:	The caller may hold locks, but is not required to hold any.
Control parameters:	If the caller is disabled, the parameter list must reside in fixed or disabled reference (DREF) storage.

Programming requirements

Users of this macro must make sure that the UCB will not be deleted. The application must pin the UCB, or make sure that the environment it is executing in, will not allow the UCB to be deleted.

This service will not have any recovery. The user must supply recovery to handle any unexpected errors.

Restrictions

None.

Input register information

Before issuing the IOSZHPF macro, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register: Contents
13: Address of a 144 byte save area

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: Reason code
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

Performance implications

None.

Syntax

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

Syntax	Description

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

␢	One or more blanks must precede IOSZHPF.

IOSZHPF

␢	One or more blanks must follow IOSZHPF.

INFOAREA=`infoarea`	`infoarea`: RX-type address or register (2) - (12).

,UCBPTR=`ucbptr`	`ucbptr`: RX-type address or register (2) - (12).

,DEVINFO=NO	Default: NO
,DEVINFO=YES

,LINKAGE=BRANCH

,RETCODE=`xretcode`	`xretcode`: RX-type address or register (2) - (12).

,RSNCODE=`xrsncode`	`xrsncode`: RX-type address or register (2) - (12).

,PLISTVER={`xplistver` \| MAX \| IMPLIED_VERSION}	Default: PLISTVER=IMPLIED_VERSION

Parameters

The parameters are explained as follows:

name

An optional symbol, starting in column 1, that is the name on the IOSZHPF macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

INFOAREA=infoarea

The name (RS-type), or address in register (2)-(12), of a required 32 character input into which IOSZHPF is to return the zHPF channel program information. This area is mapped by IOSDZHPF.

,UCBPTR=ucbptr

The name (RS-type), or address in register (2)-(12), of a required 4 byte input that contains the address of the UCB (common segment address mapped by IEFUCBOB) whose zHPF information is to be obtained.

,DEVINFO=NO

,DEVINFO=YES

Specifies whether the device-related zHPF capabilities should be returned.

NO: The device-related zHPF capabilities should not be returned. NO is the default.
YES: The device-related zHPF capabilities should be returned.

,LINKAGE=BRANCH

An optional keyword input that indicates that branch-entry linkage should be issued for the routine invocation.

,RETCODE=xretcode

The name (RS-type), or register (2)-(12), of an optional fullword output into which the return code is to be copied from GPR 15.

,RSNCODE=xrsncode

The name (RS-type), or register (2)-(12), of an optional fullword output into which the reason code is to be copied from GPR 0.

,PLISTVER=xplistver | MAX | IMPLIED_VERSION

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.

ABEND codes

None.

Return and reason codes

When the IOSZHPF macro returns control to your program:

GPR 15 (and xretcode when you code RETCODE) contains a return code.
When the value in GPR 15 is not zero, GPR 0 (and xrsncode when you code RSNCODE) contains a reason code.

The following table identifies the hexadecimal return and reason codes:

Return Code	Meaning
00	Successful completion
04	Warning Reason Code Meaning 01 zHPF is disabled for the device.
08	Program error Reason Code Meaning 01 The UCB address provided by the caller does not represent a valid UCB.