z/OS MVS Assembler Services Reference IAR-XCT

Chapter 44. IEA4PSE2 — Pause service

|

Description

Call IEA4PSE2 service to make the current task or SRB nondispatchable. After you pause a task or SRB, it remains nondispatchable until a release or transfer specifying the same PET is called. That is, the program issuing the pause does not receive control back until after the RELEASE or TRANSFER occurs. At that time, the returned release_code contains a value supplied by the associated release or transfer request.

If a release service specifying the same PET is called before pause, the system returns control immediately to the calling program, and the task or SRB 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

Minimum authorization:

Dispatchable unit mode:

Cross memory mode:

AMODE:

RMODE:

ASC mode:

Interrupt status:

Locks:

Control parameters:

Requirement

Problem state and any PSW key

Task

PASN=HASN=SASN

64-bit

Includes 64-bit

Primary mode

Enabled for I/O and external interrupts.

No locks held.

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

IEAASM

IEAC

Description

390 Assembler declarations

C/390 and C++/390 declarations

Restrictions

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.

Pause cannot be used by tasks that are higher in the task tree than the cross memory resource owning task (the top, or first, job step task in the address space).

© Copyright IBM Corp. 1988, 2017

321

IEA4PSE2 callable service

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

13

Address of the parameter address list.

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

14

15

Unchanged

Used as work registers by the system

Return code

When control returns to the caller, the access registers (ARs) contain:

Register

Contents

0-1

2-13

Used as work registers by the system

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

SYSSTATE AMODE64=YES

Description

CALL IEA4PSE2

,(return_code

,pause_element_token

,updated_pause_element_token

,release_code

,linkage)

Parameters

The parameters are explained as follows:

return_code

Returned parameter

322

z/OS MVS Assembler Services Reference IAR-XCT

IEA4PSE2 callable service

v Type: Integer v

Character Set: N/A v Length: 4 bytes

Contains the return code from the Pause service.

,pause_element_token

Supplied parameter v Type: Character string v Character Set: N/A v Length: 16 bytes

A pause element token that identifies the pause element being used to pause the current task or SRB. You 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 or SRB; use the new PET the next time when you make a Pause request using the same pause element.

,updated_pause_element_token

Returned parameter v Type: Character string v Character Set: N/A v Length: 16 bytes

A new pause element token that identifies the pause element originally identified by the PET specified in pause_element_token. This new PET must be used in place of the PET specified in pause_element_token on future calls to the Pause, Release, Transfer, or Deallocate_Pause_Element service.

,release_code

Returned parameter v Type: Character string v Character Set: N/A v Length: 3 bytes

The release code is specified by the issuer of the release service, which can release the task or SRB of the paused condition.

,linkage

Supplied parameter v Type: Integer v Character Set: N/A v Length: 4 bytes

Specifies how the Pause service routine is to be invoked. The following options are supported:

Variable

IEA_LINKAGE_SVC

Value (hexadecimal) Meaning

0 The Pause 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 either problem state or supervisor state.

Chapter 44. IEA4PSE2 — Pause service

323

IEA4PSE2 callable service

Variable

IEA_LINKAGE_BRANCH

Value (hexadecimal) Meaning

1 The Pause 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.

ABEND codes

Abend Code

AC7

Reason Code

001A0001

Description

This is an internal error.

Contact IBM support.

Return code in:

Decimal (Hex)

00 (00)

Return codes

When the service returns control to your program, GPR 15 contains one of the following return codes:

Equate symbol Meaning and Action

IEA_SUCCESS

04 (04)

08 (08)

12 (0C)

24 (18)

32 (20)

IEA_PE_TOKEN_BAD

IEA_PE_TOKEN_STALE

IEA_DUPLICATE_PAUSE

IEA_LOCK_HELD

IEA_PE_BAD_STATE

Meaning:

Successful completion.

Action:

None

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.

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.

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.

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.

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.

324

z/OS MVS Assembler Services Reference IAR-XCT

Return code in:

Decimal (Hex)

36 (24)

Equate symbol

IEA_UNSUPPORTED_MVS_RELEASE

44 (2C) IEA_INVALID_MODE

52 (34)

60 (3C)

IEA_ALREADY_SUSPENDED

IEA_AUTH_TOKEN

64 (40) IEA_PE_NOT_HOME

76 (4C) IEA_ABENDED_47B

80 (50) IEA_IN_SUSPEND_EXIT

4095 (FFF) IEA_UNEXPECTED_ERROR

IEA4PSE2 callable service

Meaning and Action

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.

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.

Meaning:

The pause element was already paused.

Action:

Check the calling program for a probable coding error and correct the program and rerun it.

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.

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.

Meaning:

After an SRB received ABEND 47B, it invoked IEA4PSE2. It is not valid to invoke IEA4PSE2 after receiving ABEND 47B.

Action:

Update the calling program to not invoke

IEA4PSE2 after ABEND 47B.

Meaning:

The suspend exit specified on SUSPEND with SPTOKEN of an SRB invoked IEA4PSE2. It is not valid to invoke IEA4PSE2 from a suspend exit.

Action:

Update the calling program to not invoke

IEA4PSE2 from a suspend exit.

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.

Chapter 44. IEA4PSE2 — Pause service

325

IEA4PSE2 callable service

326

z/OS MVS Assembler Services Reference IAR-XCT