IEA4RLS — Release

Description

Call IEA4RLS service to remove a task that has been paused, or to keep a task from being paused. Although a pause element can be used multiple times to pause a task, a pause element token can be used to successfully pause and release a task only once. Each time a pause element is used, the system generates a new PET to identify the pause element. The system returns the new updated PET on calls to the pause and transfer services.

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:

PASN=HASN=SASN

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.

Programming requirements

Either link the calling program's object code 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 the Release service, the caller must ensure that the following general purpose (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 general purpose registers (GPRs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14
Used as a work register by the system
15
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as a work register 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 IEA4RLS

 
,(return_code
,auth_level
,target_du_pause_element_token
,target_du_release_code)
 

Parameters

The parameters are explained as follows:

return_code
Returned parameter
  • Type: Integer
  • Character Set: N/A
  • Length: 4 bytes

Contains the return from the Release service.

,auth_level
Supplied Parameter
  • Type: Integer
  • Character Set: N/A
  • Length: 4 bytes

Indicates the maximum authorization level that the specified pause element was allocated with. The calling program can use constant IEA_UNAUTHORIZED defined by IEAASM and IEAC. The following levels are supported:

Variable Value (HEX) Meaning
IEA_UNAUTHORIZED 0 The pause element being released must have been allocated with auth_level=IEA_UNAUTHORIZED.
,target_du_pause_element_token
Supplied parameter
  • Type: Character string
  • Character Set: N/A
  • Length: 16 bytes

Contains the pause element token that identifies the pause element used to pause the task. If the PET identifies a pause element that has not been paused, the task is paused. However, the value specified in target_du_release_code is returned to the caller of pause.

,target_du_release_code
Supplied parameter
  • Type: Character string
  • Character Set: N/A
  • Length: 3 bytes

Contains the release code returned to the caller of pause or transfer service that used or will use the same PET to pause a task. If your program is not using this code for communication, set this field to zero.

ABEND codes

None.

Return codes

When the service returns control to the resource manager, GPR 15 and the return_code parameter contain a hexadecimal return code.

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: 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 be returned on Pause or Transfer.

Action: Check the calling program for a probable coding error. Correct the program and rerun it.

16 (10)

IEA_SLEEP_DISRUPTED

Meaning: RTM has ended the task; no release is necessary.

Action: None.

20 (14)

IEA_SPACE_TERMINATING

Meaning: The address space that contains the task is terminating; no release is necessary.

Action: None.

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.

32 (20)

IEA_PE_BAD_STATE

Meaning: Program error. The pause element associated with the pause element token specified is not valid or has already been prereleased.

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 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 specified auth_level=UNAUTHORIZED, but the pause element token was allocated with auth_level=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 caller specified auth_level=UNAUTHORIZED, but the pause element token was for a pause element allocated to another address.

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.