Retrieve_Interest_Count (ATRREIC, ATR4REIC)

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

A resource manager calls the Retrieve_Interest_Count service to determine if RRS needs to coordinate the syncpoint for a unit of recovery (UR). If multiple interests are expressed in a UR, RRS must coordinate that UR's syncpoint. If only one interest is expressed in a UR, RRS may be able to allow coordination of the syncpoint by the resource manager expressing that interest. In response to the call, RRS returns:

A return code
An indication of whether or not RRS must coordinate the syncpoint
Note: The UR status may change after the call, which can affect whether or not RRS must coordinate the syncpoint.

If the UR is part of a UR family, interest_count_info will always return ATR_MULTIPLE_INTERESTS.

Environment

The requirements for the caller are:

Minimum authorization:

Supervisor state

Dispatchable unit mode:

Task or SRB

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (ATRREIC)
64 bit (ATR4REIC)

ASC mode:

Primary

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 (but the address of a save area is not required in GPR 13).

Programming requirements

The service does not perform any error checking or have any recovery. The caller should provide recovery to handle any unexpected errors.

This service is intended for use with URs in hybrid-global transaction mode. For URs in other transaction modes or when the transaction mode is unknown, call the Retrieve_Side_Information_Fast service.

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

None.

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

This service has a minimal path length.

Syntax

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

CALL ATRREIC

(return_code
,context_token
,coordinator_info)

CALL ATR4REIC

(return_code
,context_token
,coordinator_info)

Parameters

The parameters are explained as follows:

return_code

Returned parameter

Type: Integer
Length: 4 bytes

Contains the return code from the Retrieve_Interest_Count service.

,context_token

Supplied parameter

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

Specifies the context token associated with the UR. Do not specify a context token of 0.

Your resource manager received the token from:

The Begin_Context service for a privately managed context
The Express_UR_Interest service or Express_Context_Interest service for a native context

,coordinator_info

Received parameter

Type: Integer
Length: 4 bytes

Receives from the service an indicator of whether or not RRS must be the syncpoint coordinator. The indicator is one of the following:

Indicator in: Hexadecimal (Decimal) Equate Symbol	Description
1 (1) ATR_NO_MORE_THAN_ONE_INTEREST	Only one resource manager has expressed only one interest in the UR. That resource manager could coordinate the syncpoint of this UR itself, or allow RRS to coordinate the syncpoint.
2 (2) ATR_MULTIPLE_INTERESTS	One or more resource managers have expressed more than one interest in the UR. RRS must coordinate the syncpoint for this UR, because only RRS has all of the information needed to properly coordinate the syncpoint.

ABEND codes

None.

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

Example

In the pseudocode example, the resource manager issues a call to determine if RRS must coordinate the syncpoint for the UR. Storage for the call parameters has been allocated.

⋮
C_TOKEN = MY_C_TOKEN
CALL ATRREIC(RC,C_TOKEN,COORD_INFO)
IF RC = ATR_OK THEN
  CURRENT_COORD_INFO = COORD_INFO
⋮