 |
The resource manager calls the Set_Work_Identifier service to set
the current or next unit of work identifier (UWID) for a unit of recovery
(UR). In response to the call, RRS returns a return code. There
are three versions of Set_Work_Identifier, each with different parameters. - ATRSWID is for AMODE(31) callers and is the basic version of the
service. It must be called specifying a UR interest token.
- ATRSWID2 is for AMODE(31) callers and can be called specifying
either a UR token or a UR interest token.
- ATR4SWID 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.Table 1 describes the UWIDs that this
service can set. Your resource manager can use the call to set a UWID
only if one does not already exist for the UR; the UWID must be null
before the call. Table 1. Setting
Unit of Work Identifiers| Unit of Work Identifier (UWID) |
Format |
Current UWID can be set |
Next UWID can be set |
|---|
| 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
|
Yes |
Yes |
| Enterprise Identifier (EID) |
tidgtid
- tid
- 4-byte transaction identifier (TID)
- gtid
- 8-40 byte global transaction identifier (GTID)
|
Yes |
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. |
Yes |
No |
The XID for a unit of recovery can also be set with the Express_UR_Interest
service.
The next LUWID is used for the next UR, unless ATR_BREAK_TREE was
set in the UR's side information by a Set_Side_Information call.
All of the URs in a cascaded UR family will have the same GTRID
component in their XID.
Environment The requirements for the caller
are:
| Minimum authorization: |
PKM allowing key 0-7, or supervisor
state |
| Dispatchable unit mode: |
Task or SRB |
| Cross memory mode: |
Any PASN, any HASN, any SASN |
| AMODE: |
31 bit (ATRSWID, ATRSWID2)
64 bit (ATR4SWID)
|
| 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 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 state of the resource
manager associated with the specified UR interest token must be run,
which means it has registered, set its exit routines with RRS, and
completed restart.
You cannot set a global work identifier
for a UR in local transaction mode.
For the specified interest
in the UR, your resource manager cannot call the Set_Work_Identifier
service if any of the following are true: - A resource manager's exit routine returns ATRX_LATER_CONTINUE
- The UR state is in_completion.
- For a server distributed syncpoint manager (SDSRM), the UR state
is in_forget.
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 ATRSWID
|
(return_code
,ur_interest_token
,set_option
,uwid_type
,uwid_len
,uwid_data)
|
| CALL ATRSWID2
|
(return_code
,ur_or_uri_token
,set_option
,uwid_type
,uwid_len
,uwid_data)
|
| CALL ATR4SWID
|
(return_code
,ur_or_uri_token
,set_option
,uwid_type
,uwid_len
,uwid_data)
|
Parameters The parameters are explained
as follows: - return_code
- Returned parameter
- Type: Integer
- Length: 4 bytes
Contains the return code from the Set_Work_Identifier service.
- ,ur_interest_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
For ATRSWID callers, specifies a token that uniquely identifies
your resource manager's interest in the UR whose data you want to
set. Your resource manager received the token from one of the following
services: Express_UR_Interest, Retain_Interest.
- ,ur_or_uri_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
For ATRSWID2 callers, specifies a token that uniquely identifies
either the UR, or your resource manager's interest in the UR, whose
data you want to set: - 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. 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.
- ,set_option
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
Identifies the UWID to be set. Specify one of the following:
| Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
UWID to be set |
|---|
| 0
(0)
ATR_CURRENT
|
Current UWID: RRS is to set
the current UWID for this UR. |
| 1
(1)
ATR_NEXT
|
Next UWID: RRS is to set
the next UWID for this UR. The next UWID cannot be an EID or XID.
|
- ,uwid_type
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
Specifies the type of the UWID you want to set. 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_len
- Supplied
parameter
- Type: Integer
- Length: 4 bytes
Specifies the length of the UWID your resource manager wants
to set. The length of the UWID depends on its type. Specify the actual
length of the UWID between the following upper and lower limits: | 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_data
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: Specified in uwid_len parameter
Specifies the contents of the UWID your resource manager
wants to set.
The format of the UWID 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'00140000' or X'00140001'.
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 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.
|
| 377
ATR_UWID_LEN_INV
|
Meaning: Program error. The
UWID length 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.
|
| 37F
ATR_SET_OPTION_INV
|
Meaning: Program error. The set_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.
|
| 380
ATR_UWID_TYPE_INV
|
Meaning: Program error. The uwid_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.
|
| 393
ATR_LUWID_DATA_INV
|
Meaning: Program error. The
LUWID specified in uwid_data is not valid.
The first byte of this data must contain a valid length of an LU name
(a value from 1 to 17). The system rejects the service call. Action:
Check the resource manager for a probable coding error. Correct
the resource manager and rerun it.
|
| 397
ATR_XID_DATA_INV
|
Meaning: Program error. The
computed length of the XID does not match the specified length passed
via the uwid_len parameter. 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.
|
| 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 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.
|
| 735
ATR_UWID_ALREADY_SET
|
Meaning: The UR already has
a UWID. The system rejects the service call. It is possible that
another program in the system previously set the UWID.
Action:
Check the resource manager for a probable coding error. Correct
the resource manager and rerun it.
|
| 73C
ATR_AFTER_NEW_UR
|
Meaning: Program error. The
application is already running under a new UR. The system rejects
the service call. Action: Check the resource manager for
a probable coding error. Correct the resource manager and rerun it.
|
| 74E
ATR_SET_NEXT_EID_INV
|
Meaning: Program error. The
resource manager tried to set the next Enterprise identifier, but
the requested function is not available. The system rejects the service
call. Action: Check the resource manager for a probable
coding error. Correct the resource manager and rerun it.
|
| 752
ATR_SET_NEXT_XID_INV
|
Meaning: Program error. The
next XID cannot be set. The system rejects the service call. Action:
Check the resource manager for a probable coding error. Correct
the resource manager and rerun it.
|
| 764
ATR_LOCAL_TRAN_MODE_INV
|
Meaning: Program error. The current UR is in local
transaction mode. This service is valid only for a UR in global 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
Set_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 set a UWID. ⋮
URI_TOKEN = UR_INTEREST_TOKEN
SET_OPT = ATR_CURRENT
UWID_TYPE = ATR_LUWID
LUWID_LEN = 26
LUWID = LUWID_1
CALL ATRSWID2(RC,URI_TOKEN,SET_OPT,UWID_TYPE,LUWID_LEN,LUWID)
IF RC ≠ ATR_OK THEN
/* Handle error */
⋮
|
z/OS MVS Programming: Resource Recovery
Copyright IBM Corporation 1990, 2014