Post_Deferred_UR_Exit (ATRPDUE, ATR4PDUE)

ATRPDUE is for AMODE(31) callers.
ATR4PDUE is for AMODE(64) callers and allows parameters in 64 bit addressable storage.

Several resource manager exit routines allow the resource manager to initiate asynchronous processing, then return to RRS with a return code that indicates a deferred response. The return codes that indicate a deferred response are:

    ATRX_LATER
    ATRX_LATER_CONTINUE

When the asynchronous processing completes, the resource manager calls the Post_Deferred_UR_Exit service to pass to RRS a return code that reflects the results of the asynchronous processing.

In response to the call, RRS issues a return code.

Environment

The requirements for the caller are:

Minimum authorization:

PKM allowing key 0-7, or supervisor state

Dispatchable unit mode:

Task or SRB

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (ATRPDUE)
64 bit (ATR4PDUE)

ASC mode:

Primary or access register (AR)

Interrupt status:

Enabled for I/O and external interrupts

Locks:

No locks held

Control parameters:

Control parameters must be in the primary address space and addressable by the caller.

Linkage:

Standard MVS™ linkage conventions are used.

Programming requirements

Either link edit your object code with the linkable stub routine ATRRCSS (31 bit) or ATRR4CSS (64 bit) from SYS1.CSSLIB, or LOAD and CALL the callable service. The high level language (HLL) definitions for the callable service are:

HLL definition	Description
ATRRASM	390 Assembler declarations
ATRRC	C/390 declarations

Restrictions

For the call, the UR must be in the same state as it was when the exit returned the deferred response code. The UR state cannot be in-reset, in-flight, or in-forget.

The exit routine's resource manager state must be either:

Restart, which means it has registered, set its exit routines with RRS, begun restart, and requested incomplete UR interests
Run, which means it has registered, set its exit routines with RRS, and completed restart

Input register information

Before issuing the call, the caller does not have to place any information into any register unless using it in register notation for the parameters, or using it as a base register.

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 a work register by the system
15: Return code

When control returns to the caller, the ARs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a call. If the system changes the contents of registers on which the caller depends, the caller must save them before calling the service, and restore them after the system returns control.

Performance implications

None.

Syntax

Write the call as shown in the syntax diagram. You must code the parameters in the CALL statement as shown.

CALL ATRPDUE

(return_code
,ur_interest_token
,exit_number
,completion_code)

CALL ATR4PDUE

(return_code
,ur_interest_token
,exit_number
,completion_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 Post_Deferred_UR_Exit service.

,ur_interest_token

Supplied parameter

Type: Character string
Character Set: No restriction
Length: 16 bytes

Specifies the UR interest token that uniquely represents an instance of the resource manager's interest in the particular UR. Your resource manager received the token on a call to: Express_UR_Interest, Retrieve_UR_Interest, or Retain_Interest.

,exit_number

Supplied parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

Specifies the exit number for the exit routine that has completed with the code in the completion_code parameter. Set_Exit_Information (CRGSEIF, CRGSEIF1,CRG4SEIF) lists the exit routines and their numbers, which are assigned by RRS.

,completion_code

Supplied parameter

Type: Integer
Character Set: N/A
Length: 4 bytes

Specifies the return code from the asynchronous exit routine that has now completed processing. The code can be any valid return code for the exit routine, except ATRX_LATER or ATRX_LATER_CONTINUE.

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'00090000' or X'00090001'. See z/OS MVS System Codes for the explanations and actions.

Return codes

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

Return Code in: Hexadecimal Equate Symbol	Meaning and action
0 ATR_OK	Meaning: Successful completion. Action: None.
10 ATR_OK_NO_CONTEXT	Meaning: The operation completed successfully. The UR state was in-completion or in-forget, and there was no associated context. Action: Continue normal processing.
103 ATR_INTERRUPT_STATUS_INV	Meaning: Program error. The resource manager is disabled; the interrupt status must be enabled for I/O and external interrupts. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
105 ATR_LOCKS_HELD	Meaning: Program error. The resource manager is holding one or more locks; no locks must be held. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
107 ATR_UNSUPPORTED_RELEASE	Meaning: Environmental error. The system release does not support this service. The system rejects the service call. Action: Remove the resource manager from the system, and install it on a system that supports RRS. Then rerun the resource manager.
109 ATR_ENVIRONMENT_INV	Meaning: Program error. The resource manager invoked the service from an SRB suspend exit or from an SRB that was ended abnormally by the PURGEDQ service. The system rejects the call to Post_Deferred_UR_Exit. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
370 ATR_URI_TOKEN_INV	Meaning: Program error. The UR interest token specified in the call is not for one of the currently valid interests. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
378 ATR_EXIT_NUMBER_INV	Meaning: Program error. The exit number specified in the call is not valid. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
379 ATR_COMP_CODE_INV	Meaning: Program error. The exit return code specified in the completion_code parameter in the call is not valid for the exit routine. The system rejects the service call. Action: Check the resource manager for a probable coding error. Check both the completion code and the exit number in the call. Correct the resource manager and rerun it.
381 ATR_LATER_INV	Meaning: Program error. The completion_code parameter specified in the call is `ATRX_LATER` or `ATRX_LATER_CONTINUE`. This value cannot be used for this call. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
701 ATR_RM_STATE_ERROR	Meaning: Program error. The resource manager associated with the UR interest token specified in the call is not in a valid state to issue the service call. The resource manager must be in restart or run state. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
702 ATR_RM_EXITS_UNSET	Meaning: Program error. RRS has unset the RRS exit routines for the resource manager. The system rejects the service call. Action: The resource manager must reset its RRS exits and begin restart processing with RRS.
740 ATR_POST_NOT_PENDING	Meaning: Program error. For the exit number and the interest specified in the call, RRS is not expecting a return code from the exit routine. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
F00 ATR_NOT_AVAILABLE	Meaning: RRS is not available. Action: The system rejects the service request. Retry the request later. Before retrying the request, the resource manager must reset its RRS exit routine information and begin restart processing with RRS.
F03 ATR_UR_RESOLVED_BY_ INSTALLATION	Meaning: Environmental error. The resource manager called the Post_Deferred_UR_Exit service to resolve a UR in an in-doubt state. However, the installation had already used panel input to resolve the UR. The system rejects the service call. Action: RRS processes the UR based on the installation input.
F06 ATR_WAS_NOT_AVAILABLE	Meaning: RRS was available to the resource manager, but went down and came back up again. A commit or backout operation may or may not have been in progress for the context under which the Post_Deferred_UR_Exit was done at the time of the RRS failure. A new unit of recovery can not be created until the current unit of recovery is completed. Action: The system rejects the service request. Restart your resource manager, making sure to reset the resource manager's exit routines with RRS. The resource manager must inform the application that one of the following actions must be taken to complete the current unit of recovery: If a commit or backout request was not active at the time of the RRS failure, a commit or backout must be requested before a new unit of recovery can begin. If a commit or backout request was active at the time of the RRS failure, the context must be ended, via the CTXENDC service, before a new unit of recovery can begin.
FFF ATR_UNEXPECTED_ERROR	Meaning: System error. The service that was called encountered an unexpected error. The system rejects the service call. Action: Search problem reporting databases for a fix for the problem. If no fix exists, contact the IBM® Support Center.

Example

In the pseudocode example, the exit routine issues a call to supply its return code.

⋮
EXIT_NUM = ATR_PREPARE_EXIT
URI_TOKEN = MY_URI_TOKEN
CCODE = ATRX_OK
CALL ATRPDUE(RC,URI_TOKEN,EXIT_NUM,CCODE)
IF RC ≠ ATR_OK THEN
    /* Handle error */
⋮