IOSENQ — IOS ENQ service

Description

IOSENQ allows you to perform ENQs and DEQs on certain I/O Supervisor (IOS) resources. Currently, the following functions can be serialized:

Dynamic channel path management
Dynamic I/O processing

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state. Zero PSW key.
Dispatchable unit mode:	Task
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts.
Locks:	No locks may be held.
Control parameters:	Must be in the primary address space.

Programming requirements

The caller should include the IOSDENQ macro to get equate symbols for the return and reason codes.

Restrictions

The caller must not have functional recovery routines (FRRs) established.

The caller must not have a pending ENQ for the same resource managed by this service.

Input register information

Before issuing the IOSENQ 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 if GPR15 is not 0
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)

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 IOSENQ macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede IOSENQ.

IOSENQ

␢	One or more blanks must follow IOSENQ.

RESOURCE=DYNCHPID

,REQUEST=ENQ
,STATE=SHARED
,STATE=EXCLUSIVE
,COND=NO
,COND=YES
,WAITTIME=`waittime`	Required choice with REQUEST=ENQ,COND=YES.
,WAITTIME=SYSTEM_DEFINED	Default: SYSTEM_DEFINED.
,REQUEST=DEQ

,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

,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)

Parameters

The parameters are explained as follows:

name

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

RESOURCE=DYNCHPID

RESOURCE=NOT_SUPPORTED

A required input parameter. Indicates that this request will deal with the dynamic channel path management ENQ resource.

,REQUEST=ENQ

,REQUEST=DEQ

A required input parameter.

,REQUEST=ENQ

Indicates that the request is to perform an ENQ operation.

STATE=SHARED

STATE=EXCLUSIVE

A required input parameter if REQUEST=ENQ is specified.

STATE=SHARED: Indicates that the ENQ should be obtained in shared state.
STATE=EXCLUSIVE: Indicates that the ENQ should be obtained in exclusive state.

COND=NO

COND=YES

A required input parameter if REQUEST=ENQ is specified.

COND=NO: Indicates that this is not a conditional ENQ. Control will only be returned to the caller when the ENQ is held.
COND=YES: Indicates that this is a conditional ENQ. If the ENQ cannot be obtained within the given length of time, processing is ended, and a return code indicating this situation is provided to the caller.

,WAITTIME=waittime

,WAITTIME=SYSTEM_DEFINED

A required input parameter if REQUEST=ENQ,COND=YES is specified.

,WAITTIME=waittime: The name (RS-type), or address in register (2)-(12), of a fullword input that specifies the maximum time in hundredths of seconds that the system is to wait for the ENQ to be obtained. A value of 0, or omitting this parameter, results in the system using a pre-determined wait time. The value is treated as a 32-bit unsigned number.
,WAITTIME=SYSTEM_DEFINED: The pre-determined default time in hundredths of seconds that the system is to wait for the ENQ to be obtained.

,REQUEST=DEQ

Indicates that the request is to perform a DEQ operation. A warning return code will result if the ENQ is not held.

,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

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, if you use the currently available parameters.

To code: Specify one of the following:

IMPLIED_VERSION
MAX
A decimal value of 1

,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

The caller may get the following abend codes:

Table 1. ABEND Codes for the IOSENQ Macro
ABEND Code	Meaning and Action
0C4-4	Meaning: Your program was not in supervisor state with PSW key 0. Action: Call IOSENQ only when in supervisor state with PSW key 0.
B78-8	Meaning: Your program was in problem state with PSW key 8-15. Action: Call IOSENQ only when in supervisor state with PSW key 0.

Return and reason codes

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

When the IOSENQ 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) contains a reason code.

The following table identifies the hexadecimal return and reason codes:

Table 2. Return and Reason Codes for the IOSENQ Macro
Hexadecimal Return Code	Reason Codes, Meaning and Action
00	Equate Symbol: IOSENQRc_OK ENQ The ENQ is held. DEQ The DEQ is held.
04	Equate Symbol: IOSENQRc_Warn Reason Code Meaning/Action 01 Equate Symbol: IOSENQRsnEnqAlreadyHeld Meaning: For ENQ, this task already holds the ENQ. It could be held either in shared or exclusive state. Action: Avoid using the IOSENQ REQUEST=ENQ function when you already hold the requested ENQ. 02 Equate Symbol: IOSENQRsnEnqNotHeld Meaning: DEQ was requested but the caller did not have the ENQ. Action: None required.
08	Equate Symbol: IOSENQRc_InvParm Reason Code Meaning/Action 01 Equate Symbol: IOSENQRsnBadRequest Meaning: An incorrect request was specified. Action: Check for storage overlays. 02 Equate Symbol: IOSENQRsnBadResource Meaning: An incorrect resource was requested. Action: Check for storage overlays.
0C	Equate Symbol: IOSENQRc_Env Reason Code Meaning/Action 01 Equate Symbol: IOSENQRsnCouldNotGetENQ Meaning: On a conditional ENQ request, the ENQ could not be obtained within the specified time period. Action: Specify a longer time period, or request the ENQ unconditionally.