An authorized program can use Retrieve_Pause_Element_Information to test the validity of a pause element passed by an unauthorized program. The authorized program can do this to ensure that it does not perform any operation, such as releasing the pause element, unless the unauthorized program is also able to perform the same operation.
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 addressing mode |
| ASC mode: | Primary mode |
| 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. |
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 |
None.
Before calling the Retrieve_Pause_Element_Information service, the caller does not need to place any information into any register, unless using it in register notation for the parameters, or using it as a base register.
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 IEAVRPI |
|
The parameters are explained as follows:
Contains the return code from the Retrieve_Pause_Element_Information service.
Indicates the caller's authorization level. The following levels are supported: IEAASM and IEAC define constants IEA_UNAUTHORIZED and IEA_AUTHORIZED, which can be used by the calling program.
| Variable | Value (hexadecimal) | Meaning |
|---|---|---|
| IEA_UNAUTHORIZED | 0 | The caller is not key 0 and supervisor state. |
| IEA_AUTHORIZED | 1 | The caller is both key 0 and supervisor state. |
A pause element token that identifies the pause element for which information will be returned. You obtain the PET from the Allocate_Pause_Element service.
The authorization level of the creator of the pause element specified by the input PET.
| IEAASM and IEAC defined constants | Value (hexadecimal) | Meaning |
|---|---|---|
| IEA_UNAUTHORIZED | 0 | The caller is not key 0 and supervisor state. |
| IEA_AUTHORIZED | 1 | The caller is not key 0 and supervisor state. |
| IEA_UNAUTHORIZED + IEA_CHECKPOINTOK | 2 | Unauthorized PET that can tolerate the pause elements' not being restored upon a restart after a checkpoint. |
| IEA_AUTHORIZED + IEA_CHECKPOINTOK | 3 | Authorized PET that can tolerate the pause elements' not being restored upon a restart after a checkpoint. |
The Stoken of the address space that currently owns the pause element specified by the input PET.
State Constant |
Meaning |
|---|---|
IEAV_PET_PRERELEASED |
The PE was released before any task or SRB was suspended on it, and no task or SRB has attempted to pause it. |
IEAV_PET_RESET |
The PE is not being used to make any task or SRB nondispatchable. If the PE is used in an attempt to pause the current task or SRB, the task or SRB will be made nondispatchable. |
IEAV_PET_RELEASED |
The task RB or SRB is currently dispatchable,
but control has not been returned to the task or SRB following a call
to the Pause or Transfer service. A call to the Release or Transfer service has released the task or SRB. In either case, control has not been returned to the caller of the Pause or Transfer service. The system has not transitioned the PE into the RESET state. |
IEAV_PET_PAUSED |
A task RB or SRB is currently nondispatchable. Its dispatchability is controlled by the PE. |
None.
When the service returns control to your program, GPR 15 contains one of the following return codes:
| Return code in: Decimal (Hex) | Equate symbol | Meaning and Action |
|---|---|---|
| 00 (00) | IEA_SUCCESS | Meaning: Successful completion. Action: None |
| 04 (04) | IEA_PE_TOKEN_BAD | Meaning: Program error. The specified
pause element token 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. |
| 08 (08) | IEA_PE_TOKEN_STALE | Meaning: The specified pause element token
is stale; that is, it was valid but has been used on the Pause or
Transfer service. This service requires the updated PET returned
on Pause or Transfer. Action: Check the calling program for a probable coding error. Correct the program and rerun it. |
| 24 (18) | IEA_LOCK_HELD | Meaning: Program error. The caller is
holding one or more locks; no locks must be 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. |
| 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. |
| 60 (3C) | IEA_AUTH_TOKEN | Meaning: Program error. The caller
specified an unauthorized auth_level type, but a pause element token
allocated with an authorized auth_level type was encountered. The
system rejects the service call. Action: Program error. The specified pause element token is not valid. The system rejects the service call. |
| 64 (40) | IEA_PE_NOT_HOME | Meaning: Program error. The caller
specified an unauthorized auth_level type, but a pause element token
for a pause element allocated to another address space was specified. Action: Check the calling program for a probable coding error. Correct the program and rerun it. |
| 4095 (FFF) | IEA_UNEXPECTED_ERROR | Meaning: This service routine encountered
an unexpected error. The system rejects this service request. Action: Contact IBM support. |