IEA4APE2 — Allocate_Pause_Element

The requirements for the caller 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).

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_token

Returned parameter

• Type: Character string
• Character Set: N/A
• Length: 16 bytes

Contains the pause element token that identifies a pause element that 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
IEA4APE	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
IEA4APE2	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 1. 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 the return_code parameter contain a hexadecimal return code.