Retrieve_Work_Identifier (ATRRWID, ATRRWID2, ATR4RWID)

The resource manager calls the Retrieve_Work_Identifier service to retrieve a work identifier related to a unit of recovery (UR). In response to the call, RRS returns:

A return code
The actual length of the unit of work identifier (UWID)
The UWID

There are three versions of Retrieve_Work_Identifier, each with different parameters.

ATRRWID is for AMODE(31) callers and is the basic version of the service. It must be called specifying a UR interest token.
ATRRWID2 is for AMODE(31) callers and can be called specifying either a UR token or a UR interest token.
ATR4RWID is for AMODE(64) callers, allows parameters in 64 bit addressable storage, and can be called specifying either a UR token or a UR interest token.

Code your resource manager to call the version that includes the support you need.

Only global URs can have work identifiers. Global work identifiers are not assigned to URs that are in local transaction mode. If you call Retrieve_Work_Identifier and specify a UR that is in local transaction mode, no work identifier is returned.

Your resource manager can request the current or next UWID for this UR. Table 1 describes the UWIDs that can be requested.

Table 1. Unit of Work Identifiers
Unit of Work Identifier (UWID)	Format	Generate option is allowed or required	Next UWID is available
LU 6.2 logical unit of work identifier (LUWID)	`netid.luname.instnum.seqnum` netid.luname 1-17 character identifier of the network and LU, preceded by a 1-byte fixed length field instnum 6-byte fixed TP instance seqnum 2-byte fixed sequence number	Allowed only for authorized callers.	Yes
Enterprise Identifier (EID)	`tidgtid` tid 4-byte transaction identifier (TID) gtid 8-40 byte global transaction identifier (GTID)	Not allowed	No
X/Open Identifier (XID)	`FormatIDGtrid_lengthBqual_lengthID` FormatID 4-byte fixed format ID Gtrid_length 4-byte fixed GTRID length Bqual_length 4-byte fixed BQUAL length ID 128-byte character XID The GTRID length and BQUAL length define the length of the first and second subsection of the ID. The GTRID must have a length of at least 1 byte, however the BQUAL can have a length of 0. The length of the entire XID cannot exceed 140 bytes.	Required RRS automatically generates an XID whenever a request for an XID is made by an authorized caller against a UR which does not already have one.	No

If the requested LUWID or XID has not been set by a call to Set_Work_Identifier or generated by RRS, you can use Retrieve_Work_Identifier to generate the LUWID or XID. The service, however, cannot generate EIDs. This service will not generate LUWID or XID if invoked by an unauthorized caller.

An XID can be set for a UR by a call to Set_Work_Identifier or by a call to Express_UR_Interest. An XID is generated by RRS for a UR that does not already have an XID when it is first requested, or when the UR becomes part of a cascaded UR family. All of the URs in a cascaded UR family will have the same FormatID and GTRID components in their XID. No generation of work identifiers will be performed for unauthorized callers.

All of the URs in a cascaded UR family will have the same FormatID and GTRID components in their XID.

Environment

The requirements for the caller are:

Minimum authorization:

PKM allowing key 0-7, or supervisor state
None if retrieval of current work identifier is requested;
in this case no generation of work identifiers will be
performed.

Dispatchable unit mode:

Task or SRB

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (ATRRWID, ATRRWID2)
64 bit (ATR4RWID)

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:

Uses standard MVS™ linkage conventions

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 resource manager associated with the specified UR interest token must be in restart state or in run state.

The UR transaction mode cannot be local.

Note: The LUWID of a UR created by calling the Retain_Interest service is not available until the UR for which Retain_Interest was called has reached in_completion state. At that time, you can call Retrieve_Work_Identifier to retrieve the LUWID by specifying the current LUWID and the new_ur_interest_token returned on the call to Retain_Interest.

You cannot call this service to generate an LU 6.2 logical unit identifier (LUWID) when any of the following are true:

The resource manager returned the ATRX_LATER_CONTINUE return code from an exit routine for this expression of interest.
The UR state is in_completion.
The caller is not authorized.

When the resource manager issues the call in SRB mode, the call must not specify binary zero for ur_interest_token or ur_or_uri_token.

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 appropriate call as shown in the syntax diagrams. You must code the parameters in the CALL statement as shown.

CALL ATRRWID

(return_code
,ur_interest_token
,retrieve_option
,generate_option
,uwid_type
,uwid_buffer_len
,uwid_len
,uwid_data_buffer)

CALL ATRRWID2

(return_code
,ur_or_uri_token
,retrieve_option
,generate_option
,uwid_type
,uwid_buffer_len
,uwid_len
,uwid_data_buffer)

CALL ATR4RWID

(return_code
,ur_or_uri_token
,retrieve_option
,generate_option
,uwid_type
,uwid_buffer_len
,uwid_len
,uwid_data_buffer)

Parameters

The parameters are explained as follows:

return_code

Returned parameter

Type: Integer
Length: 4 bytes

Contains the return code from the Retrieve_Work_Identifier service.

,ur_interest_token

Supplied parameter

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

For ATRRWID callers, specifies a token that uniquely identifies your resource manager's interest in the UR whose data you want to retrieve. Your resource manager received the token from one of the following services: Express_UR_Interest, Retrieve_UR_Interest, Retain_Interest.

,ur_or_uri_token

Supplied parameter

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

For ATRRWID2 callers, specifies a token that uniquely identifies either the UR, or your resource manager's interest in the UR, whose data you want to retrieve:

0: Binary zero specifies the current UR associated with the application task.
UR token: The token for the UR.
UR interest token: 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_Interest_Data, Retain_Interest, Create_Cascaded_UR, or Retrieve_UR_Data.

You must specify a URITOKEN when you specify ATR_GENERATE on generate_option and ATR_LUWID on uwid_type.

Because you may pass two different types of tokens through this parameter, passing an invalid token can generate either a ATR_URI_TOKEN_INV or a ATR_UR_TOKEN_INV return code. For example, passing an invalid UR token might result in an ATR_URI_TOKEN_INV return code. Even though a UR token was passed, if it is invalid, then RRS may not understand what sort of token it was supposed to be. For this reason, IBM® recommends callers check both return codes, even when they know what type of token they intend to pass.

,retrieve_option

Supplied parameter

Type: Integer
Length: 4 bytes

Indicates whether you want to retrieve the current UWID or the next UWID. Unauthorized callers must specify the ATR_CURRENT retrieve option.

Constant in: Hexadecimal (Decimal) Equate Symbol	UWID to be retrieved
0 (0) ATR_CURRENT	Current UWID: RRS is to retrieve the current UWID for this UR.
1 (1) ATR_NEXT	Next UWID: RRS is to retrieve the next UWID for this UR. Note: You can validly specify ATR_NEXT only when uwid_type is ATR_LUWID.

,generate_option

Supplied parameter

Type: Integer
Length: 4 bytes

Specifies the action RRS is to take if a UWID has not been set by a call to the Set_Work_Identifier service or generated by RRS. Specify one of the following:

Constant in: Hexadecimal (Decimal) Equate Symbol	RRS's action
0 (0) ATR_DO_NOT_GENERATE	Do not generate: RRS is not to generate a new UWID.
1 (1) ATR_GENERATE	Generate: RRS is to generate a new UWID if the identifier has not yet been set or generated.

You must specify ATR_GENERATE when uwid_type is ATR_XID. You must
specify ATR_DO_NOT_GENERATE when uwid_type is ATR_EID. You may
specify either ATR_GENERATE or ATR_DO_NOT_GENERATE when uwid_
type is ATR_LUWID. Unauthorized callers must specify the
ATR_DO_NOT_GENERATE option.

You can specify ATR_GENERATE to generate the current LUWID or the next LUWID.

RRS will generate the current LUWID only when all of the following are true:

You specified ATR_CURRENT on retrieve_option,
The call to the Set_Exit_Information service for RRS specified an LU name in variable_data_1.

RRS will generate the next LUWID only when the following are true:

You specified ATR_CURRENT on retrieve_option,
At least one of the following is true:
- Your resource manager's call to the Set_Exit_Information service for RRS specified an LU name in variable_data_1.
- The current LUWID has already been set or generated.

,uwid_type

Supplied parameter

Type: Integer
Length: 4 bytes

Specifies the type of the UWID you want to retrieve. Specify one of the following:

Constant in: Hexadecimal (Decimal) Equate Symbol	UWID type
0 (0) ATR_LUWID	An LU 6.2 logical unit of work identifier (LUWID)
1 (1) ATR_EID	An Enterprise identifier (EID)
2 (2) ATR_XID	An X/Open transaction identifier (XID)

,uwid_buffer_len

Supplied parameter

Type: Integer
Length: 4 bytes

Specifies the length of the buffer that your resource manager supplies for the UWID. The recommended length of the buffer is the maximum length for the UWID you are retrieving. Specify one of the following:

Maximum Length in: Hexadecimal (Decimal) Equate Symbol	UWID type
A (10) ATR_MIN_LUWID_LENGTH	The minimum length of a LU 6.2 LUWID
1A (26) ATR_MAX_LUWID_LENGTH	The maximum length of a LU 6.2 LUWID
C (12) ATR_MIN_EID_LENGTH	The minimum length of an Enterprise identifier
2C (44) ATR_MAX_EID_LENGTH	The maximum length of an Enterprise identifier
D (13) ATR_MIN_XID_LENGTH	The minimum length of an X/Open identifier
8C (140) ATR_MAX_XID_LENGTH	The maximum length of an X/Open identifier

,uwid_len

Returned parameter

Type: Integer
Length: 4 bytes

Receives the actual hexadecimal length of the UWID from the service.

,uwid_data_buffer

Returned parameter

Type: Character string
Character Set: No restriction
Length: Specified in uwid_buffer_len

Specifies a buffer that receives the UWID from the service. The uwid_buffer_len parameter specifies the length of the buffer. The UWID length is from 10 to 140 bytes.

The format of the UWID returned depends on the UWID type. A LUWID has the following format:

     netid.luname.instnum.seqnum

The fields are as follows:

netid.luname: 1-17 character identifier of the network and LU, preceded by a 1-byte length field
instnum: 6-byte TP instance
seqnum: 2-byte sequence number

An EID has the following format:

     tidgtid

The fields are as follows:

tid: 4-byte transaction identifier (TID)
gtid: 8-40 byte global transaction identifier (GTID)

For XID, the uwid_data_buffer contains the 4–byte address of the buffer to contain the retrieved XID. An XID has the following format:

FormatIDGtrid_lengthBqual_lengthID

The fields are as follows:

FormatID: 4-byte fixed format ID
Gtrid_length: 4-byte fixed Gtrid length
Bqual_length: 4-byte fixed Bqual length
ID: 128-byte character XID

The 1–128 byte ID field has the following format:

Gtrid: 1–64 byte Gtrid
Bqual: 0–64 byte Bqual

The length of the entire XID cannot exceed 140 bytes.

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'000E0000' or X'000E0001'. 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.
7 ATR_REQUESTED_WID_UNAVAILABLE	Meaning: Program processing. The requested UWID has not been set by a call to the Set_Work_Identifier service or been generated by RRS. The generate_option parameter specified that a new UWID should not be generated. The system accepts the call. Action: If this result is expected, no action is needed. If this result is not expected, check the resource manager for a probable coding error; correct the resource manager and rerun it.
A ATR_PARTIAL_UWID_DATA	Meaning: Program error. The uwid_buffer_len value specified in the call is less than the actual length of the UWID. The system accepts the service call. RRS puts in the buffer as many characters of the data as will fit, starting at the left, and returns the actual length in uwid_len. 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 does not identify one of the currently valid interests. If the specified token is not a valid UR or URI token, RRS may return this return code even if the resource manager was attempting to specify a UR token. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
37E ATR_RETRIEVE_OPTION_INV	Meaning: Program error. The retrieve option 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.
380 ATR_UWID_TYPE_INV	Meaning: Program error. The specified uwid_type 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.
382 ATR_UWID_BUF_LEN_INV	Meaning: Program error. The length specified for the UWID data 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.
388 ATR_GENERATE_OPTION_INV	Meaning: Program error. The generate_option 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.
3A3 ATR_UR_TOKEN_INV	Meaning: Program error. The UR token specified in the call does not identify a valid UR. If the specified token is not a valid UR or URI token, RRS may return this return code even if the resource manager was attempting to specify a URI token. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
3B4 (948) ATR_AUTH_FAILURE_RETRIEVE_OPTION	Meaning: The caller, which is PKM 8-15 problem state, specified a retrieve_option not equal to ATR_CURRNET. Only ATR_CURRENT can be specified when the caller is PKM 8-15 problem state. To use other retrieve_option's the caller must be PKM allowing key 0-7, or supervisor state. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3B5 (949) ATR_AUTH_FAILURE_GENERATE_ OPTION	Meaning: The caller, which is PKM 8-15 problem state, specified a generate_option not equal to ATR_DO_NOT_GENERATE. Only ATR_DO_NOT_GENERATE can be specified when the caller is PKM 8-15 problem state. To use other retrieve_option's the caller must be PKM allowing key 0-7, or supervisor state. Action: Check the calling program for a probable coding error. Correct the program 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 state or 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: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
73C ATR_AFTER_NEW_UR	Meaning: The resource manager has previously returned the ATRX_LATER_CONTINUE return code from an exit routine for this expression of interest. You cannot generate an LUWID after that point for this expression of interest. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
73F ATR_LUWID_NOT_AVAILABLE	Meaning: Environmental error. The current LUWID for the UR specified in the call is not available. The LUWID created for a UR by a Retain_Interest call is not available until the previous UR has reached a complete state. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
748 ATR_GEN_NOT_ALLOWED_NO_LUNAME	Meaning: The resource manager did not specify an LU prefix on a Set_Exit_Information call, so the resource manager cannot tell RRS to generate a LUWID. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
74D ATR_GEN_NOT_ALLOWED_EID	Meaning: The request to generate an Enterprise identifier 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.
751 ATR_GEN_REQUIRED_XID	Meaning: Program error. The request to not generate an XID 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.
753 ATR_GEN_NOT_ALLOWED_ NO_URI_TOKEN	Meaning: Program error. The request to generate a LUWID is not valid, because a URI token was not specified. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
754 ATR_RETRIEVE_NEXT_EID_INV	Meaning: Program error. The request to retrieve the next Enterprise identifier 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.
755 ATR_RETRIEVE_NEXT_XID_INV	Meaning: Program error. Retrieval of XID for the next Unit of Recovery 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.
765 ATR_GEN_LUWID_NOT _ALLOWED_LOCAL	Meaning: Program error. The request to generate a LUWID is not valid for a UR in local transaction mode. The system rejects the service call. Action: Check the calling program for a probable coding error. If the caller is a resource manager, it should not unset its exits with RRS.
767 ATR_GEN_XID_NOT _ALLOWED_LOCAL	Meaning: Program error. The request to generate an XID is not valid for a UR in local transaction mode. The system rejects the service call. Action: Check the calling program for a probable coding error. If the caller is a resource manager, it should not unset its exits with RRS.
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_Work_Identifier 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 retrieve the current LU 6.2 LUWID. If a UWID is not available, RRS will generate one.

⋮
URI_TOKEN = UR_INTEREST_TOKEN
RET_OPT = ATR_CURRENT
GEN_OPT = ATR_GENERATE
UWID_TYPE = ATR_LUWID
BUF_LEN = ATR_MAX_LUWID_LENGTH
CALL ATRRWID2(RC,URI_TOKEN,RET_OPT,GEN_OPT,UWID_TYPE,
     BUF_LEN,LUWID_LEN,LUWID)
IF RC ≠ ATR_OK THEN
  /* Handle error */
⋮