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 may 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 |
Key 2-15 or problem state callers must specify linkage as IEA_LINKAGE_SVC.
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.
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 IEAVRPI2 |
|
The parameters are explained as follows:
Contains the return code from the Retrieve_Pause_Element_Information service.
Indicates the authorization level with which the pause element specified by the input PET was allocated. The following levels are supported:
| Variable | Value (hexadecimal) | Meaning |
|---|---|---|
| IEA_PET_UNAUTHORIZED | 0 | The pause element was allocated with pause_element_auth_level=IEA_UNAUTHORIZED. |
| IEA__PET_AUTHORIZED | 1 | The pause element was allocated with pause_element_auth_level=IEA_AUTHORIZED. |
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.
Specifies how the Retrieve_Pause_Element_Information service routine is to be invoked. The following options are supported:
| Variable | Value (hexadecimal) | Meaning |
|---|---|---|
| IEA_LINKAGE_SVC | 0 | The Retrieve_Pause_Element_Information service routine will be invoked by an SVC linkage. This option can be used when in non-cross memory task mode, in any key, and in either problem state or supervisor state. |
| IEA_LINKAGE_BRANCH | 1 | The Retrieve_Pause_Element_Information service routine will be invoked by a branch instruction. The caller must be in both key 0 and supervisor state. This option must be selected when in SRB mode. |
Specifies the stoken of the address space that currently owns the pause element specified by the input PET. The owner of a PE allocated by IEAVAPE2 is static and specified on the IAVEAPE2 call. The owner of a PE allocated by IEAVAPE is dynamic. See IEAVAPE — Allocate_Pause_Element for details.
If the value returned in state is IEA_PET_PAUSED, The stoken of the home address space of the task or SRB which is paused by the specified pause element. If the value in state is not IEA_PET_PAUSED, the information returned in this parameter is undefined.
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: 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. |
| 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. |
| 60 (3C) | IEA_AUTH_LEVEL_MISMATCH | Meaning: Program error.
The caller was in Problem state or key 8, but the pause element token
was allocated with pause_element_auth_level=IEA_AUTHORIZED. The system
rejects the service call. Action: Program error. The specified pause element token is not valid. The system rejects the service call. |
| 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. |
| 4095 (FFF) | IEA_UNEXPECTED_ERROR | Meaning: This service routine encountered
an unexpected error. The system rejects this service request. Action: Contact IBM support. |