The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: |
|
Dispatchable unit mode: |
|
Cross memory mode: |
|
AMODE: | 31-bit |
ASC mode: | Primary |
Interrupt status: | Enabled for I/O and external interrupts. |
Locks: |
|
Control parameters: | Must be in the primary address space and addressable by the caller. |
Either link the calling program's object code with the linkable stub routine (IEACSS from SYS1.CSSLIB) or have the calling program LOAD and then CALL the service. The high-level language (HLL) definitions for the callable service are:
HLL Definition | Description |
---|---|
IEAASM | 390 Assembler declarations |
IEAC | C/390 and C++/390 declarations |
Pause elements that are created with pause_element_auth_level=IEA_UNAUTHORIZED may only be used by callers in task mode and can only be released from a task in their home address space.
Allocate_Pause_Element cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the top, or first, job step task in the address space).
Key 1-15 or problem state callers must specify linkage as IEA_LINKAGE_SVC and pause_element_owner_stoken as binary zero.
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.
Syntax | Description |
---|---|
CALL IEAVAPE2 |
|
The parameters are explained as follows:
Contains the return code from the Allocate_Pause_Element service.
Represents one or more possible levels of the pause element being allocated. The calling program can use the constants defined in IEAASM or IEAC, as appropriate. The level desired results from adding the values of the required types together. The authorization type is not optional.
For instance, the level to allocate authorized pause elements that are checkpoint/restart tolerant is IEA_AUTHORIZED + IEA_CHECKPOINTOK, or 3.
IEAASM and IEAC defined constants | Value (hexadecimal) | Meaning |
---|---|---|
IEA_UNAUTHORIZED | 0 | When using the allocated pause element through other services, either pause_element_auth_level IEA_UNAUTHORIZED or IEA_AUTHORIZED can be used. |
IEA_AUTHORIZED | 1 | When using the allocated pause element through other services, pause_element_auth_level =IEA_AUTHORIZED is required. Caller must be both key 0 and supervisor state. |
IEAASM and IEAC defined constants | Value (hexadecimal) | Meaning |
---|---|---|
IEA_CHECKPOINTOK | 2 | The application can tolerate the pause elements' not being restored upon a restart after a checkpoint. |
Contains the pause element token that identifies a pause element which you can use to synchronize the processing of a task or SRB.
Allocation Service version: | Deallocation Rules |
---|---|
IEAVAPE | The PE will be deallocated by the system when
one of the following events occurs:
|
IEAVAPE2 | The PE will be deallocated by the system when
one of the following events occurs:
|
Specifies the release code which will be returned to a paused DU if the system deallocates the pause element while it is being used to pause a task or SRB, due to the CMRO task of its owning address space terminating.
Variable | Value (hexadecimal) | Meaning |
---|---|---|
IEA_LINKAGE_SVC | 0 | The Allocate_Pause_Element service routine will be invoked via an SVC linkage. This option can be used when in non-cross memory task mode, any key, and either problem state or supervisor state. |
IEA_LINKAGE_BRANCH | 1 | The Allocate_Pause_Element service routine will be invoked via a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode. |
None.
When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.
Return code in: Decimal (Hex) | Equate Symbol | Meaning and Action |
---|---|---|
00 (0) | IEA_SUCCESS | Meaning: Successful completion. Action: None. |
24 (18) | IEA_LOCK_HELD | Meaning: Program
error. One or more locks other than the local lock are held. The system
rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it. |
36 (24) | IEA_UNSUPPORTED_MVS_RELEASE | Meaning: Environmental error.
The system release does not support this service. The system rejects
the service call. Action: Run the program on a system that supports the service. |
40 (28) | IEA_INVALID_AUTHCODE | Meaning: Program error. The
pause_element_auth_level value specified in the call is not valid.
The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it. |
44 (2C) | IEA_INVALID_MODE | Meaning: Program error. The
calling program is not in primary ASC mode, which this service requires.
The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it. |
48 (30) | IEA_OUT_OF_STORAGE | Meaning: Environmental error.
The system could not obtain storage for a pause element. The system
rejects the service call. Action: Retry the request later. If the problem persists, consult your system programmer. |
56 (38) | IEA_NO_PETS_AVAILABLE | Meaning: There are no pause
element tokens available. Action: Retry the request later. |
4095 (FFF) | IEA_UNEXPECTED_ERROR | Meaning: This service routine
encountered an unexpected error. The system rejects this service
request. Action: Contact IBM® support. |
84 (54) | IEA_INVALID_LINKAGE | Meaning: Program error. The
linkage value specified is not valid. The system rejects the service
call Action: Check the calling program for a probable coding error. Correct the program and rerun it. |
88 (58) | IEA_INVALID_OWNER_STOKEN | Meaning: Program error. The
stoken specified for pause_element_owner_stoken is not valid. Action: Obtain the correct stoken of the target and reissue the call |
96 (60) | IEA_UNAUTH_NONZERO_OWNER_STOKEN | Meaning: Program error. A
key 8-15 problem state caller specified a nonzero value for pause_element_owner_stoken Action: Check the calliing program for a probable coding error. Correct the program and rerun it. |
100 (64) | IEA_INVALID_AUTHLVL_AUTHCODE | Meaning: The pause_element_auth_level
value specified in the call is not valid. The system rejects the service
call. Action: Check the calling program for a probable coding error. Correct the program and rerun it. |