IEA4APE — Allocate_Pause_Element

Description

Allocate_Pause_Element obtains a pause element token (PET), which uniquely identifies a pause element. The PET is used as input to the following services:

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:	For auth_level=IEA_UNAUTHORIZED: PASN=HASN=SASN For auth_level=IEA_AUTHORIZED: Any PASN, any HASN, any SASN
AMODE:	64-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	When supervisor state and PSW key 0: The local lock may be held. When problem state, or not PSW key 0: No locks may be held.
Control parameters:	Must be in the primary address space and addressable by the caller.

Programming requirements

Either link the object code of the calling program with the linkable stub routine (IEA4CSS from SYS1.CSSLIB), or load the calling program 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

When the calling program specifies auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only release another task in its home address space. All pause element tokens (PETs) used when auth_level=IEA_UNAUTHORIZED must have been obtained using an authorization level of IEA_UNAUTHORIZED.

Input register information

Before calling Allocate_Pause_Element, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register: Contents
1: Address of the parameter address list.
13: Address of a 144-byte register save area.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14: Used as work registers by the system
15: Return Code

When control returns to the caller, the ARs contain:

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
SYSSTATE AMODE64=YES
CALL IEA4APE	,(return_code ,auth_level ,pause_element_token)

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.

,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 that are defined in IEAASM or IEAC. The level needed is derived by adding the values of the required types together. The authorization type is required.

For example, the level to allocate authorized pause elements that are checkpoint- or 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 auth_level IEA_UNAUTHORIZED or IEA_AUTHORIZED can be used.
IEA_AUTHORIZED	1	When using the allocated pause element through other services, auth_level=IEA_AUTHORIZED will be 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 the pause element that you can use to synchronize the processing of a task.

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. If the auth_level indicates AUTHORIZED, locks other than the local lock are held. If the auth_level indicates UNAUTHORIZED, locks 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_PE_NOT_HOME	Meaning: Program error. The 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_XFER_TO_SELF	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_XFER_FAILED	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: Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM® Support Center.