IEA4PSE — Pause service

Description

Call IEA4PSE service to make the current task nondispatchable. After you pause a task, it remains nondispatchable until a release service specifying the same PET is called. That is, the program issuing the pause does not receive control back until after the release occurs.

If a release service specifying the same PET is called before pause, the system returns control immediately to the calling program, and the task is not paused.

When you use pause, it returns an updated PET. Use this updated PET to either deallocate or reuse the PE.

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 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 is running auth_level=IEA_UNAUTHORIZED, the caller must be in task mode and can only pause 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 Pause service, 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 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 IEA4PSE

 ,(return_code
,auth_level
,pause_element_token
,updated_pause_element_token
,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 code from the Pause service.

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

Indicates the maximum level that the specified pause element was allocated with. IEAASM and IEAC define constants IEA_UNAUTHORIZED and IEA_AUTHORIZED, which the calling program can use. The following levels are supported:

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

A pause element token that identifies the pause element being used to pause the current task. You can obtain the PET from the Allocate_Pause_Element service.

When you use a PET in a call to the pause service, you cannot reuse the PET on a second call to pause or on a call to transfer. The pause service returns a new PET in updated_pause_element_token. The new PET now identifies the pause element used to pause the task; use the new PET the next time when you make a pause request using the same pause element.

,updated_pause_element_token
Returned parameter
  • Type: Character string
  • Character Set: N/A
  • Length: 16 bytes

A new pause element token that identifies the pause element originally identified by the PET specified in pause_element_token, which cannot be reused after a successful call to Pause.

,release_code
Returned parameter
  • Type: Character string
  • Character Set: N/A
  • Length: 3 bytes

The release code, specified by the issuer of the Release service. A Release that specified this code released the task from its paused condition.

ABEND codes

Abend Code Reason Code Description
AC7 001A0001 This is an internal error. Contact IBM® support.

Return codes

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

Action: Check the calling program for a probable coding error. Correct the program and rerun it.
12 (0C)

IEA_DUPLICATE_PAUSE

 Meaning: The work unit has already been paused using the specified pause element token. The system rejects the service call.

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.
32 (20)

IEA_PE_BAD_STATE

 Meaning: Program error. The pause element associated with the pause element token specified in the call is not in a valid state. The system rejects the service call.

Action: Check the calling program for a probable coding error, such as attempting to perform a Pause or Transfer using a pause element token that has already been used to Pause or Transfer by another unit of work. 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.
52 (34)

IEA_ALREADY_SUSPENDED

 Meaning: The pause element was already paused.

Action: Check the calling program for a probable coding error and 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: Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM Support Center.