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


Retrieve_Interest_Data (ATRRID, ATR4RID)

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

  • ATRRID is for AMODE(31) callers.
  • ATR4RID is for AMODE(64) callers and allows parameters in 64 bit addressable storage.
A resource manager calls the Retrieve_Interest_Data service to retrieve data about an interest in a unit of recovery (UR). In response to the call, RRS returns:
  • A return code
  • The nonpersistent interest data
  • The length of the persistent interest data
  • The persistent interest data
  • The type of interest: unprotected, protected, or protected and logged
  • The type of expression of interest: new or restart
  • The role the resource manager is taking in the UR interest: participant, last-agent participant, distributed syncpoint resource manager (DSRM), or server distributed syncpoint manager (SDSRM)

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

For the call, the UR state cannot be in-reset.

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
  • Length: 4 bytes

Contains the return code from the Retrieve_Interest_Data service.

,ur_interest_token
Supplied parameter
  • Type: Character string
  • Character Set: No restriction
  • Length: 16 bytes

Specifies the UR interest token that identifies your resource manager's interest in the UR. Your resource manager received the token from one of the following services: Express_UR_Interest, Retrieve_UR_Interest, or Retain_Interest.

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

Receives from the service the nonpersistent interest data for your resource manager's interest in the UR. RRS does not record this data in nonvolatile storage.

Your resource manager provided the data in a call to one of the following services: Express_UR_Interest, Respond_to_Retrieved_Interest, or Retain_Interest.

,persistent_interest_buffer_length
Supplied parameter
  • Type: Integer
  • Length: 4 bytes

Specifies, in hexadecimal, the length of the buffer that your resource manager is supplying for the persistent interest data. The length in bytes can be X'0' - X'1000' (0 - 4096).

,persistent_interest_data_length
Returned parameter
  • Type: Integer
  • Length: 4 bytes

Receives from the service the actual length of the persistent interest data. The length ranges from X'0' - X'1000' (0-4096), where 0 indicates that there is no persistent interest data.

If the interest type is ATR_UNPROTECTED, then there is no persistent interest data.

,persistent_interest_data
Returned parameter
  • Type: Character string
  • Character Set: No restriction
  • Length: Specified in persistent_interest_buffer_length

Specifies a buffer that receives the persistent interest data for your resource manager's interest in the UR. If persistent_interest_data_length is 0, RRS ignores this parameter. Your resource manager provides this data in a call to one of the following services: Express_UR_Interest, Change_Interest_Type, Set_Persistent_Interest_Data, or Retain_Interest. Your resource manager can also retrieve persistent interest data from the Retrieve_UR_Interest service.

,interest_type
Returned parameter
  • Type: Integer
  • Length: 4 bytes
Receives from the service the interest type for the resource manager's interest in the UR. The interest type is indicated by one of the following:

Constant in:
Hexadecimal
(Decimal)
Equate Symbol

 Description

0
(0)
ATR_UNPROTECTED

 Unprotected: The resource manager expressed an unprotected interest in the UR.

1
(1)
ATR_PROTECTED

 Protected: The resource manager expressed a protected interest in the UR.

2
(2)
ATR_PROT_LOGGED

 Protected and logged: The resource manager expressed a protected interest in the UR and the interest is recorded in an RRS log.
,expression_of_interest_type
Returned parameter
  • Type: Integer
  • Length: 4 bytes
Receives from the service the expression of interest type, which indicates whether the UR is new or restart. The field contains one of the following:

Constant in:
Hexadecimal
(Decimal)
Equate Symbol

 Description

0
(0)
ATR_NORMAL_INTEREST

 Meaning: The expression of interest is a normal expression (that is, not a restart expression of interest).

1
(1)
ATR_RESTART_INTEREST

 Meaning: The expression of interest is a restart expression of interest (that is, an expression of interest returned by the Retrieve_UR_Interest service).
,role
Returned parameter
  • Type: Integer
  • Length: 4 bytes
Receives from the service the role of the resource manager in the UR interest identified in ur_interest_token. If your resource manager is not a participant, your resource manager specified its role through a Set_Syncpoint_Controls call. The role is indicated by one of the following:

Constant in:
Hexadecimal
(Decimal)
Equate Symbol

 Role

0
(0)
ATR_PARTICIPANT

 Participant

1
(1)
ATR_LAST_AGENT

 Last-agent participant

2
(2)
ATR_DSRM

 Distributed syncpoint resource manager

3
(3)
ATR_SDSRM

 Server distributed syncpoint resource manager

ABEND codes

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

5
ATR_PARTIAL_PERSISTENT_DATA

 Meaning: Program error. The persistent_interest_buffer_length value is less than the actual length of the persistent interest data.

The system accepts the service call. RRS puts in the buffer as many characters of the data as will fit, starting at the left.

Action: No action is required. If the result is not expected, check the resource manager for a probable coding error; correct the resource manager and rerun it.

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.

37D
ATR_PERSIS_DATA_BUF_LEN_INV

 Meaning: Program error. The length specified for the persistent interest buffer 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 state must be restart or run. 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: 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.

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 Retrieve_Interest_Data 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 obtain information about an interest in a UR. 
⋮
URI_TOKEN = MY_URI_TOKEN
PD_BUF_LEN = MY_PDATA_LEN
CALL ATRRID(RC,URI_TOKEN,NON_P_DATA,PD_BUF_LEN,PD_LEN,
     P_DATA,INT_TYPE,EI_TYPE,ROLE)
IF RC = ATR_OK THEN
  MY_P_DATA = P_DATA
  MY_INT_TYPE = INT_TYPE
  MY_ROLE = ROLE
⋮
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