Retrieve_Side_Information_Fast (ATRRUSF, ATRRUSF1, ATR4RUSF)

The resource manager calls the Retrieve_Side_Information_Fast service to retrieve the current settings of RRS-related environment attributes for the UR associated with the specified context. There are three versions of Retrieve_Side_Information_Fast:

ATRRUSF is for AMODE(31) callers and is the basic version of this service.
ATRRUSF1 is for AMODE(31) callers and adds support for work managers that need interest count data, even if an event has occurred that requires RRS to coordinate the syncpoint.
ATR4RUSF is for AMODE(64) callers, allows parameters in 64 bit addressable storage, and adds support for work managers that need interest count data, even if an event has occurred that requires RRS to coordinate the syncpoint.

This service returns information about:

The mode of a UR
Who can or must coordinate a UR
How many interests exist for a UR (The interest count is only available with ATRRUSF1 and ATR4RUSF. This information is optional, and is returned only when the caller specifically requests it.)

If a condition has occurred that requires RRS to coordinate the syncpoint, such as setting an XID or a post-syncpoint PET, then RRS must coordinate the resources, even if no resource manager has expressed an interest in the UR.

Environment

The requirements for the caller are:

Minimum authorization:

Any

Dispatchable unit mode:

Task or SRB

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (ATRRUSF, ATRRUSF1)
64 bit (ATR4RUSF)

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

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

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

The 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 ATRRUSF

(return_code
,context_token
,environment_info)

CALL ATRRUSF1

(return_code
,context_token
,environment_info
,side_information_options)

CALL ATR4RUSF

(return_code
,context_token
,environment_info
,side_information_options)

Parameters

The parameters are explained as follows:

return_code

Returned parameter

Type: Integer
Length: 4 bytes

Contains the return code from the Retrieve_Side_Information_Fast 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 context token from Retrieve_Current_Context, Begin_Context for a privately managed context, or Express_UR_Interest or Express_Context_Interest for a native context.

,side_information_options

Supplied parameter

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

Valid on ATRRUSF1 and ATR4RUSF only. Specifies one or more options to request the type of information to be returned by RRS. Any undefined bits are reserved and set to zero. You must ignore the reserved bits.

The parameter will have one or more bits turned on that can be referenced by the following mask:

Mask in: Hexadecimal Equate Symbol	Description
00000001 ATR_INTEREST_COUNT_MASK	A resource manager specifies this mask to request RRS to return the interest count information for the UR associated with the specified context. The interest count information ATRRUSF1/ATR4RUSF returns is valid only for a UR that is in-flight. You must not use the interest count information ATRRUSF1/ATR4RUSF returns if the UR is in any other state.
00000002 ATR_CASCADED_TRANSACTION_MASK	A resource manager specifies this mask to request RRS to return the cascaded transaction information for the UR that is associated with the specified context. This is for ATRRUSF1/ATR4RUSF callers on systems where the ATRPre_PrepareExitSupport flag is on in ATRRINST.

,environment_info

Returned parameter

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

Receives UR environment information. Any undefined bits are reserved and set to zero. You must ignore the reserved bits.

The parameter will have one or more bits turned on that can be referenced by the following masks:

Mask in: Hexadecimal Equate Symbol	Description
00000001 ATR_NO_INTERESTS_MASK	There are no interests in the current UR. There are no protected resources to commit. Only one of the following indicators is set for a given UR at any given time: ATR_NO_INTERESTS_MASK ATR_RM_COORD_OK_MASK ATR_RRS_MUST_COORD_MASK Note: This bit is never set if ATR_LOCAL_MODE_MASK is on.
00000002 ATR_RM_COORD_OK_MASK	The UR has one or more expressions of interest by the same resource manager. The resource manager that owns the expression (or expressions) of interest can coordinate its own resources. Note: Do not confuse this condition with local transaction mode. Generally, when the resource manager decides to bypass RRS calls, the UR is in global transaction mode and will remain in in-flight state and global transaction mode. Only one of the following indicators is set for a given UR at any given time: ATR_NO_INTERESTS_MASK ATR_RM_COORD_OK_MASK ATR_RRS_MUST_COORD_MASK
00000004 ATR_RRS_MUST_COORD_MASK	One of the following conditions have occurred that require RRS to coordinate the syncpoint: Multiple resource managers have expressed interest in the UR A resource manager has set an XID for the UR A work manager has set a post syncpoint PET to be associated with the UR so it can know when the transaction completes The UR of interest is a child UR If any of the above occurs, RRS must coordinate the syncpoint for this UR, because only RRS has all the information needed to properly coordinate the syncpoint. Only one of the following indicators is set for a given UR at any given time: ATR_NO_INTERESTS_MASK ATR_RM_COORD_OK_MASK ATR_RRS_MUST_COORD_MASK
00000010 ATR_ZERO_INTEREST_COUNT_MASK	There are no interests in the current UR. This information is returned if the caller specifies the ATR_ZERO_INTEREST_COUNT_MASK in the side_information_options. For information regarding who can and must coordinate the syncpoint for the UR, check the ATR_NO_INTEREST_MASK, ATR_RM_COORD_OK_MASK, and ATR_RRS_MUST_COORD_MASK. Only one of the following interest count indicators is set for a given UR at any given time: ATR_ZERO_INTEREST_COUNT_MASK ATR_ONE_INTEREST_COUNT_MASK ATR_MULTIPLE_INTEREST_ COUNT_MASK
00000020 ATR_ONE_INTEREST_COUNT_MASK	Only one resource manager has expressed only one interest in the UR. This information is returned if the caller specifies the ATR_INTEREST_COUNT_MASK in the side_information_options. For information regarding who can and must coordinate the syncpoint for the UR, check the ATR_NO_INTEREST_MASK, ATR_RM_COORD_OK_MASK, and ATR_RRS_MUST_COORD_MASK. Only one of the following interest count indicators is set for a given UR at any given time: ATR_ZERO_INTEREST_COUNT_MASK ATR_ONE_INTEREST_COUNT_MASK ATR_MULTIPLE_INTEREST_ COUNT_MASK
00000040 ATR_MULTIPLE_INTEREST_ COUNT_MASK	There are two or more interests in the UR; either one resource manager has multiple interests, or multiple resource managers have one or more interests. This information is returned if the caller specifies the ATR_INTEREST_COUNT_MASK in the side_information_options. For information regarding who can and must coordinate the syncpoint for the UR, check the ATR_NO_INTEREST_MASK, ATR_RM_COORD_OK_MASK, and ATR_RRS_MUST_COORD_MASK. Only one of the following interest count indicators is set for a given UR at any given time: ATR_ZERO_INTEREST_COUNT_MASK ATR_ONE_INTEREST_COUNT_MASK ATR_MULTIPLE_INTEREST_ COUNT_MASK
00000100 ATR_UR_STATE_IN_RESET_MASK	When set, the UR state is in-reset. No other indicators will be set when this indicator is returned.
00000200 ATR_UR_CASCADED_MASK	This is for ATRRUSF1/ATR4RUSF callers. When set, the UR is a cascaded UR, regardless if the UR is a parent or a child UR, or if the transaction is locally or sysplex cascaded. If this bit is set, the ATR_RRS_MUST_COORD_MASK indicator is also set to indicate that RRS must coordinate the syncpoint. This information is returned if the caller specifies the ATR_CASCADED_TRANSACTION_MASK in the side_information_options.
00010000 ATR_GLOBAL_MODE_MASK	The UR transaction mode is global, and the UR state is beyond in-reset. This setting is valid only when ATR_UR_STATE_IN_RESET_MASK is not set because the transaction mode for the UR has not yet been determined. Only one of the following indicators is set for a given UR: ATR_GLOBAL_MODE_MASK ATR_LOCAL_MODE_MASK ATR_HYBRID_GLOBAL_MASK
00020000 ATR_LOCAL_MODE_MASK	The UR transaction mode is local, and the UR state is beyond in-reset. No interest information will be returned when this bit is on, since RRS assumes that the resource manager is always the coordinator for a local transaction. When this indicator is set, no other indicators are set.
00040000 ATR_HYBRID_GLOBAL_MASK	The UR transaction mode is hybrid-global, and the UR state is beyond in-reset. RRS considers the UR to be a global transaction; however, resource managers may exhibit proprietary transactional behaviors. This setting is valid only when ATR_UR_STATE_IN_RESET_MASK is not set because the transaction mode for the UR has not yet been determined. Only one of the following indicators is set for a given UR: ATR_GLOBAL_MODE_MASK ATR_LOCAL_MODE_MASK ATR_HYBRID_GLOBAL_MASK

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 this level of RRS. Rerun the resource manager.
3AF ATR_SIDE_INFORMATION_OPTIONS_INV	Meaning: Program error. The side_information_options value specified on the call is invalid. Either reserved bits were nonzero, or an unacceptable selection of options was specified. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
F00 ATR_NOT_AVAILABLE	Meaning: RRS is not available. Action: The system rejects the service request. Retry the request later after RRS has been restarted.

Example

In the pseudocode example, the resource manager issues a call to request side information for the UR associated with a specific context. Storage for the call parameters has been allocated.

⋮
CTX_TOKEN = MY_CONTEXT_TOKEN
CALL ATRRUSF(RC,CTX_TOKEN,ENV_INFO)
IF RC = ATR_OK THEN
  CURRENT_ENV_INFO = ENV_INFO
  LOCAL_MODE = CURRENT_ENV_INFO && ATR_LOCAL_MODE_MASK
⋮