IEAVAPE2 — Allocate_Pause_Element
Description
- Pause
- Release
- Transfer
- Deallocate_Pause_Element
Environment
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Problem state and any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN=HASN=SASN |
AMODE: | 31-bit |
ASC mode: | Primary |
Interrupt status: | Enabled for I/O and external interrupts |
Locks: | No locks held |
Control parameters: | Must be in the primary address space and addressable by the caller. |
Programming requirements
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 |
Restrictions
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.
Only 2040 unauthorized PETs may be allocated at any one time in an 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.
Input register information
- Register
- Contents
- 1
- Address of the parameter address list.
- 13
- Address of a 72-byte register save area.
Output register information
- Register
- Contents
- 0-1
- Used as work registers by the system
- 2-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- Return code
- 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
Syntax | Description |
---|---|
CALL IEAVAPE2 |
|
Parameters
The parameters are explained as follows:
- return_code
- Returned parameter
- Type: Integer
- Character Set: N/A
- Length: 4 bytes
Contains the return code from the Allocate_Pause_Element service.
- ,pause_element_auth_level
- Supplied parameter
- Type: Integer
- Character Set: N/A
- Length: 4 bytes
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.
The following levels are supported:Table 1. Authorization 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. Table 2. Checkpoint/Restart Toleration - only available when the CVTPAUS4 bit is set in the CVT. 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. Note: If the IEA_CHECKPOINTOK value is not added to the authorization value, checkpoints cannot be taken when an allocated pause element exists. - ,pause_element_token
- Returned parameter
- Type: Character string
- Character Set: N/A
- Length: 16 bytes
Contains the pause element token that identifies a pause element which you can use to synchronize the processing of a task or SRB.
- ,pause_element_owner_stoken
- Supplied parameter
- Type: Character string
- Character Set: N/A
- Length: 8 bytes
Specifies the space token (STOKEN) of the address space which is to be considered the owner of the Pause Element being allocated. Specify one of the following values:- Binary zero: indicate the system should make the current primary address space the owner of the Pause Element. This is the only value valid for key 8-15 problem state callers.
- A valid STOKEN, indicate the system should make the address space with the matching STOKEN the owner for the pause element.
When the CMRO task (the first job step task) of an address space terminates, the system will release and deallocate any pause elements owned by the CMRO task's home address space. The table below describes exactly when the system will release and/or deallocate a Pause Element:Allocation Service version: Deallocation Rules IEAVAPE The PE will be deallocated by the system when one of the following events occurs: - The PE was never used to pause a task or SRB and the CMRO task for the space which allocated it terminates.
- The PE is being used to pause a task or SRB which is asynchronously terminated via CALLRTM TYPE=ABTERM (for example, cancel or detach) or a PURGEDQ.
- The CMRO task of the home address space of the task or SRB which last used the PE terminates and the PE is not being used to pause an SRB.
IEAVAPE2 The PE will be deallocated by the system when one of the following events occurs: - The CMRO task of the address space specified by pause_element_owner_stoken terminates. If the PE is being used to pause a DU when the CMRO task terminates, the system will release the DU using the owner_termination_release_code before the PE is deallocated. Note that in this case, the UPET returned will be 16 bytes of binary zeros, an invalid value.
- The PE is being used to pause a task or SRB which is asynchronously terminated via CALLRTM TYPE=ABTERM (for example, cancel or detach) or a PURGEDQ.
- The PE is being used to pause a task or SRB when the home address space of the task or SRB is terminated
- The CMRO task of the home address space of the task or SRB which last used the PE terminates and the PE is not being used to pause an SRB
- ,owner_termination_release_code
- Supplied parameter
- Type: Character string
- Character Set: N/A
- Length: 3 bytes
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.
Note: If the system deallocates a PE due to its owner terminating while the PE was not being used to pause a task or SRB, future attempts to use the PE will fail with a return code indicating the PETOKEN was stale or the PE is in an invalid state. - linkage
- Supplied parameter
- Type: Integer
- Character Set: N/A
- Length: 4 bytes
Specifies how the Allocate_Pause_Element service routine is to be invoked. The following options are supported:Table 3. Linkage option 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.
ABEND codes
None.
Return codes
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. |