IEAVAPE2 — Allocate_Pause_Element

The requirements for the caller are:

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:

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.

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. The home address space of the task or SRB which last used the PE terminates
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 The home address space of the task or SRB which last used the PE terminates.Note: A PE is considered as "being used to pause a task or SRB," when the PE is not Reset or Prereleased.

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

None.

When the service returns control to the resource manager, GPR 15 and return_code contain a hexadecimal return code.