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: |
|
Dispatchable unit mode: |
|
Cross memory mode: |
|
AMODE: | 64-bit |
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 object code of 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 |
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.
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 |
---|---|
SYSSTATE AMODE64=YES | |
CALL IEA4RPI2 |
|
The parameters are explained as follows:
Contains the return code from the Retrieve_Pause_Element_Information service.
A pause element token that identifies the pause element for which information will be returned. You can obtain the PET from the Allocate_Pause_Element service.
The calling program can use the constants defined in IEAASM or IEAC, as appropriate. Add the specified values together to achieve the desired results. For example, to specify linkage branch and untrusted PET, specify IEA_LINKAGE_BRANCH + IEA_UNTRUSTED_PET.
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. |
Variable | Value (hexadecimal) | Meaning |
---|---|---|
IEA_UNTRUSTED_PET | 2 | The Retrieve_Pause_Element_Information service routine is to validate that the input PET is allowed to be used by an unauthorized program. An authorized program should use this if it is validating a PET provided to it by an unauthorized caller. |
The Stoken of the address space that currently owns the pause element specified by the input PET.
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.
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. |
State Constant |
Meaning |
---|---|
IEA4_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. |
IEA4_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. |
IEA4_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 transited the PE into the RESET state. |
IEA4_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. |
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_TOKEN | Meaning:Program error.
The caller was in Problem state or key 8, or specified IEA_UNTRUSTED_PET,
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. |
64 (40) | IEA_PE_NOT_HOME | Meaning: Program error.
The pause element token was for a pause element allocated with pause_element_auth_level=IEA_UNAUTHORIZED
to another address space. 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: Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM® Support Center. |