z/OS MVS Programming: Resource Recovery
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


Change_Interest_Type (ATRSIT, ATR4SIT)

z/OS MVS Programming: Resource Recovery
SA23-1395-00

  • ATRSIT is for AMODE(31) callers.
  • ATR4SIT is for AMODE(64) callers and allows parameters in 64 bit addressable storage.

A resource manager calls the Change_Interest_Type service to change an interest in a unit of recovery (UR) from unprotected to protected. The resource manager can change the interest type until the UR enters the in-prepare state.

On the call, you also specify action for a resource manager failure and provide persistent interest data.

In response to the call, resource recovery services/MVS (RRS) returns:
  • A return code
  • A UR identifier (URID)
Action for Resource Manager Failure: On the Change_Interest_Type call, you can specify how RRS should process requests to commit the UR if your resource manager becomes:
  • Unregistered: Your resource manager is no longer registered as a resource manager. See Register_Resource_Manager (CRGGRM, CRG4GRM) for a description of how a resource manager can become unregistered.
  • Unset: Your resource manager's exit routines are no longer set with RRS.
RRS reacts to a resource manager failure as follows:
  • Standard processing: RRS backs out this UR, if the state of the UR is in-reset, in-flight, in-state-check, or in-prepare.

Persistent interest data: In the Change_Interest_Type call, your resource manager can provide persistent interest data for the protected interest. When hardening information for the interest in an RRS log, RRS records the persistent interest data. Because the data is hardened, it will be available if your resource manager restarts or if RRS restarts, forcing your resource manager to restart.

Your resource manager can also provide persistent interest data in a call to: Express_UR_Interest, Set_Persistent_Interest_Data, or Retain_Interest. Your resource manager can retrieve persistent interest data in a call to: Retrieve_UR_Interest or Retrieve_Interest_Data.

URID: Save the returned UR identifier (URID) with the information about the UR in your resource manager log. During restart processing after your resource manager, RRS, or the system fails, your resource manager obtains the URID for an incomplete UR from a Retrieve_UR_Interest call. Compare the URID from Retrieve_UR_Interest with the URIDs in your resource manager log to find the data for the incomplete UR.

Your resource manager can also obtain the URID from a call to: Express_UR_Interest, Retrieve_UR_Interest, Retrieve_UR_Data, or Retain_Interest.

Environment

The requirements for the caller are:

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

The UR state must be in-flight or in-state-check.

The state of the resource manager associated with the UR interest token specified in the call must be 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.

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 Change_Interest_Type 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 UR. Your resource manager received the token from the Express_Interest service or the Retain_Interest service.

,ur_identifier
Returned parameter
  • Type: Character string
  • Character Set: No restriction
  • Length: 16 bytes

Receives a UR identifier (URID) from the service. The URID uniquely identifies the UR.

,interest_type
Supplied parameter
  • Type: Integer
  • Character Set: N/A
  • Length: 4 bytes
Specifies the new type of interest the resource manager has in the UR. Specify the interest type as follows:

Constant in:
Hexadecimal
(Decimal)
Equate Symbol

 Description

1
(1)
ATR_PROTECTED

 Protected: The resource manager is now expressing a protected interest in the UR.
,failure_action
Supplied parameter
  • Type: Integer
  • Character Set: N/A
  • Length: 4 bytes
Specifies how RRS should process commit requests if your resource manager becomes unregistered or unset. Specify the failure action as follows:

Constant in:
Hexadecimal
(Decimal)
Equate Symbol

 Action

0
(0)
ATR_FAIL_STANDARD

 Standard processing
,persistent_interest_data_length
Supplied parameter
  • Type: Integer
  • Character Set: N/A
  • Length: 4 bytes

Specifies the length in bytes of the persistent interest data. The length can be 0 through 4096.

,persistent_interest_data
Supplied parameter
  • Type: Character string
  • Character Set: No restriction
  • Length: Specified in persistent_interest_data_length

The persistent interest data for your resource manager's interest in the UR. RRS records this data in an RRS log.

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'000F0000' or X'000F0001'. 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.

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.

370
ATR_URI_TOKEN_INV

 Meaning: Program error. The UR interest token specified in the call is not 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.

371
ATR_INTEREST_TYPE_INV

 Meaning: Program error. The interest_type value 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.

372
ATR_FAILURE_ACTION_INV

 Meaning: Program error. The failure_action value 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.

376
ATR_PERSISTENT_DATA_LEN_INV

 Meaning: Program error. The length specified in the persistent_interest_data_len parameter 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.

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 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.

731
ATR_UR_STATE_ERROR

 Meaning: Program error. The UR is not in a valid state for the service call. The UR state must be in-reset or in-flight. The system rejects the service call.

Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.

739
ATR_PROTECTED_INTEREST

 Meaning: Program error. The URI_TOKEN specified in the call represents an interest that is already protected. The system rejects the service call.

Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.

749
ATR_MAX_UR_LOG_DATA_EXCEEDED

 Meaning: Environmental error. This request will exceed the maximum amount of data that RRS can log for a UR. The system rejects the service call.

Action: Fail the client program request or back out the UR. Verify that the space set up for logging is adequate.

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.

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 Change_Interest_Type 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 resource manager issues a call to change one of its interests in a UR from unprotected to protected. 
⋮
URI_TOKEN = MY_URI_TOKEN
P_DATA_LEN = LENGTH(MY_P_DATA)
P_DATA = MY_P_DATA
INT_TYPE = ATR_PROTECTED
FAIL_ACT = ATR_FAIL_STANDARD
CALL ATRSIT(RC,URI_TOKEN,URID,INT_TYPE,FAIL_ACT,
            P_DATA_LEN,P_DATA)
IF RC ≠ ATR_OK THEN
   /* Handle error */
⋮
Parent topic: Callable resource recovery services

Go to the previous page Go to the next page

Notices | Terms of use | Support | Contact z/OS | zFavorites



Copyright IBM Corporation 1990, 2014