IOSCHPD — IOS CHPID description service

Description

The IOSCHPD macro returns the acronym, description, attributes, and/or the Worldwide Port Name (WWPN) of a channel path (CHP) or channel path type.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem or Supervisor state and any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary or access register (AR).
Interrupt status:	Enabled or disabled for I/O and external interrupts.
Locks:	No locks may be held.
Control parameters:	Must be in the primary address space or be in an address/data space that is addressable through a public entry on the callers dispatchable unit access list (DU-AL).

Programming requirements

None.

Restrictions

The parameter list must be in the caller's primary address space or be addressable via the dispatchable unit access list.

The LINKAGE=BRANCH option is limited to callers which meet the following criteria:

supervisor state and key 0
31 bit addressing mode
primary ASC mode
the parameter list resides in fixed or DREF storage

Input register information

Before issuing the IOSCHPD 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.

Output register information

The contents of registers 14 through 1 are altered during processing.

When control returns to the caller, the GPRs contain:

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

When control returns to the caller, the ARs contain:

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

Performance implications

None.

Syntax

The IOSCHPD macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede IOSCHPD.

IOSCHPD

␢	One or more blanks must follow IOSCHPD.

CHPID=`chpid`	`chpid`: RS-type address or register (2) - (12).

,CHP_TYPE=`chp_type`	`chp_type`: RS-type address or register (2) - (12).
,CHP_PARM=`chp_parm`	`chp_type`: RS-type address or register (2) - (12).
,CHP_PARM=0	Default: 0

,ACRONYM=`acronym`	`acronym`: RS-type address or register (2) - (12).

,DESC=`desc`	`desc`: RS-type address or register (2) - (12).

,ATTR=`attr`	`attr`: RS-type address or register (2) - (12).

,WWPN=`wwpn`	`wwpn`: RS-type address or register (2) - (12).

,ND=`xnd`	`xnd`: Optional 32-character output.

,LINKAGE=SYSTEM	Default: LINKAGE=SYSTEM
,LINKAGE=BRANCH

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

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

,PLISTVER=IMPLIED_VERSION	Default: PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=1
,PLISTVER=2

,MF=S	Default: MF=S
,MF=(L,`list addr`)	`list addr`: RS-type address or register (1) - (12).
,MF=(L,`list addr,attr`)
,MF=(L,`list addr`,0D)
,MF=(E,`list addr`)
,MF=(E,`list addr`,COMPLETE)

Note: To use the IOSCHPD macro, you need to specify the following parameters:

Either CHPID or CHP_TYPE
One or more parameters among ACRONYM, DESC, ATTR, and WWPN.

Parameters

The parameters are explained as follows:

name

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

CHPID=chpid

A parameter which specifies the CHPID number for which to retrieve the attributes, acronym, description, and/or WWPN.

If the CHPID is defined as a managed channel path, the description and acronym returned will indicate that the channel path is managed. Otherwise, a non-managed description and acronym will be returned.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field.

CHP_TYPE=chp_type

A parameter which specifies the channel path type for which to retrieve the attributes, acronym, description, and/or WWPN. The channel path type can be obtained by invoking the UCBINFO PATHINFO macro and mapping the results with the IOSDPATH mapping macro. (The interface type is in the field called PathIntType).

To code: Specify the RS-type address, or address in register (2)-(12), of a one-byte field.

CHP_PARM=chp_parm

CHP_PARM=0

An optional input parameter, used only with CHP_TYPE=chp_type parameter, that specifies the channel path parameter. A value of 1 is the managed option and 0 (the default) is the non-managed option. If 1 is specified, and if the CHP type is managed, the description and acronym returned will indicate that the CHP type is managed.

To code: Specify the RS-type address, or address in register (2)-(12), of a one-byte field.

ATTR=attr

An optional parameter, used only with the CHPID parameter, that designates the output area that is to receive the CHPID attributes. The attributes are mapped by mapping macro IOSDCHPD.

To code: Specify the RS-type address, or address in register (2)-(12), of a one-byte field.

,ACRONYM=acronym

An optional parameter that designates the output area that is to receive the acronym.

To code: Specify the RS-type address, or address in register (2)-(12), of a 5-character field.

,DESC=desc

An optional parameter that designates the output area that is to receive the description.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field.

,WWPN=wwpn

An optional parameter, used only with the CHPID parameter, that designates the output area that is to receive the Worldwide Port Name (WWPN). (If the WWPN is not available, zeroes will be returned.)

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,ND=xnd

An optional parameter that designates the output area that is to receive the node descriptor for the channel. End of change

,LINKAGE=SYSTEM

,LINKAGE=BRANCH

An optional parameter that indicates whether a branch-entry linkage should be generated or a Program Call should be issued for the routine invocation. The default is LINKAGE=SYSTEM.

,LINKAGE=SYSTEM: requests Program Call invocation.
,LINKAGE=BRANCH: requests branch-entry invocation. The LINKAGE=BRANCH option is intended for performance-sensitive invokers or programs that require this function during NIP before a PC can be issued. See RESTRICTIONS for the restrictions on branch-entry invocation.

,RETCODE=retcode

An optional output parameter into which the return code is to be copied from GPR 15.

To code: Specify the RS-type address of a fullword field, or register (2)-(12).

,RSNCODE=rsncode

An optional output parameter into which the reason code is to be copied from GPR 0.

To code: Specify the RS-type address of a fullword field, or register (2)-(12).

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=1

,PLISTVER=2

An optional input parameter that 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, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.
1, which supports all parameters except those specifically referenced in higher versions.
2, which supports ATTR and WWPN, in addition to those from version 1.

To code: Specify one of the following:

IMPLIED_VERSION
MAX
A decimal value of 1 or 2

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

An optional input parameter that specifies the macro form.

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

,list addr: The name of a storage area to contain the parameters. For MF=S and MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr: An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE: Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

ABEND codes

None.

Return and reason codes

When the IOSCHPD macro returns control to your program:

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

The following table identifies the hexadecimal return and reason codes:

Table 1. Return and Reason Codes for the IOSCHPD Macro
Hexadecimal Return Code	Reason Codes, Meaning and Action
00	The acronym and/or description has been returned.
04	The acronym and/or description have not been returned (the acronym and description output areas have been set to zeroes). Reason Code Meaning 00 The system could not determine the CHP type from the input CHPID. 01 The input CHPID is not configured. 02 The CHP type obtained from the input CHPID is not valid. 03 The input CHP type is invalid. 04 The input CHP_PARM is invalid. 05 The managed option (1) was specified for the CHP_PARM, but the CHP type is one that does not support dynamic channel path management. The default acronym and/or description is returned.
08	Error in caller's parameters. Reason Code Meaning 01 The caller specified an invalid ALET. 02 An error occurred in accessing the caller's parameter list. 03 The ATTR= keyword can only be specified with CHPID=.
0C	Recovery was entered.
20	Recovery was entered.