Create_Cascaded_UR (ATRCCUR2, ATRCCUR3, ATR4CCUR)

A work manager calls the Create_Cascaded_UR service to create a UR that is associated with an existing UR. Typically, a work manager would do this when a single work request involves multiple work managers. The initial work manager would obtain the initial work context that represented the work request. When the work request moved from the execution environment of the original work manager into another work manager's environment, the latter work manager could obtain a new work context to represent the work request, allowing it to manipulate the work context as it needs. There are three versions of Create_Cascaded_UR, each with different parameters.

ATRCCUR2 is for AMODE(31) callers and is the basic version of the service.
ATRCCUR3 is for AMODE(31) callers and adds create options support.
ATR4CCUR is for AMODE(64) callers, allows parameters in 64 bit addressable storage, and adds create options support.

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

By using the Create_Cascaded_UR service to create a new UR for the new work context that is cascaded from the original UR, the second work manager ensures that the resources changed by the work request when it is running in its new execution environment are committed or backed out atomically along with those resources changed while the work request was running in other environments.

A work manager that creates a cascaded UR is responsible for informing RRS when the application running under the UR is application execution complete by calling the Set_Side_Information service specifying the ATR_APPL_COMPLETE information identifier.

Express_UR_Interest (ATREINT2, ATREINT4, ATREINT5 or ATR4EINT) can also be used to create a cascaded UR, if the creator also wants to express interest in the UR.

Multisystem cascaded transactions: When one work manager requests another work manager, residing on a different system, to become part of an existing work request, the requesting work manager is responsible for transferring all of the data needed by the new work manager, including the UR token representing the work request. The new work manager may then use the Create_Cascaded_UR service to create a new UR, associated with a new work context, to be cascaded from the received UR token.

As with normal (non-multisystem) cascaded transactions, a work manager that creates a multisystem cascaded transaction is responsible for informing RRS when the part of the application executing under a multisystem cascaded UR is complete by using the Set_Side_Information service to mark the UR as application-complete.

See Cascaded transactions for more information about cascaded transactions, including Multisystem cascaded transactions for more information about multisystem cascaded transactions.

Environment

The requirements for the caller are:

Minimum authorization:

None

Dispatchable unit mode:

Task or SRB

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (ATRCCUR2, ATRCCUR3)
64 bit (ATR4CCUR)

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:

MVS™ standard 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

For the call, the child UR state must be in-reset and the parent UR must be in-reset or in-flight.

The parent UR must not be in local transaction mode.

When the resource manager issues the call in SRB mode:

The call cannot specify a child_context_token of 0.
The call cannot specify a parent_UR_token of 0.

A caller that is PKM 8–15 problem state must specify a parent_UR_token for a UR that is associated with a DU native context associated with a task in the current home address space, or a private context owned by a PKM 8–15 problem state resource manager registered in the home address space.

A caller that is PKM 8–15 problem state must specify a child_context_token for a context that is either a DU native context associated with a task in the current home address space, or a private context owned by a PKM 8–15 problem state resource manager registered in the home address space.

Note: A call to the Retrieve_UR_Data service that does not specify ATR_EXTENDED_STATES for the states_option could cause a UR to go into an in-flight state. Once a UR has gone in-flight, it can no longer be made into a cascaded UR.

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 ATRCCUR2

(return_code
,parent_UR_token
,child_context_token
,child_UR_token
,child_UR_identifier)

CALL ATRCCUR3

(return_code
,parent_UR_token
,child_context_token
,child_UR_token
,child_UR_identifier
,create_options)

CALL ATR4CCUR

(return_code
,parent_UR_token
,child_context_token
,child_UR_token
,child_UR_identifier
,create_options)

Parameters

The parameters are explained as follows:

return_code

Returned parameter

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

Contains the return code from the Create_Cascaded_UR service.

,parent_UR_token

Supplied parameter

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

Specifies the token of the UR that is to be the parent of the UR specified by the child_context_token:

0: Binary zero specifies the current UR associated with the application's task active on the current system. Binary zero may be specified for either the parent_UR_token or the child_context_token, but not both.
token: The UR token of a particular UR. The UR token may be from another system in the same logging group.

Your resource manager may have received the parent_UR_token from the Retrieve_UR_Data service or from a work manager from another system. If the UR token was received from another system, RRS will associate the new child UR, which has a context specified by child_context_token, with the top-level UR of the cascaded UR family that resides on the system where the work request originated.

,child_context_token

Supplied parameter

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

Specifies the token of the context associated with the UR that is to be the child of the UR specified by the parent_UR_token:

0: Binary zero specifies the current UR associated with the application's task. Binary zero may be specified for either the parent_UR_token or the child_context_token, but not both.
token: The token of the context associated with a particular UR.

Your resource manager may have received the parent_UR_token from the Retrieve_UR_Data service.

,child_UR_token

Returned parameter

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

Receives the token that uniquely represents the new unit of recovery.

Note: UR tokens do not persist across restarts of the resource manager, RRS, or the system.

,child_UR_identifier

Returned parameter

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

Receives a UR identifier (URID) from the service. The URID uniquely identifies the UR.

Note: Unlike UR tokens, URIDs are persistent across restarts of the resource manager, RRS, and the system.

,create_options

Supplied parameter

Type: Bit string
Character Set: N/A
Length: 4bytes

On ATRCCUR3 calls, specifies various options that determine how RRS will process this interest. Each of the bits in create_options is either reserved or has a specific meaning. Each reserved bit must be specified as zero. Each other bit can be specified as either zero or one. The bit specifications are:

Bit Positions	Constant in: Hexadecimal Equate Symbol	Description
0–22	0	Reserved
23	00000000 ATR_DONT_END_ CONTEXT_MASK 00000100 ATR_END_ CONTEXT_MASK	Auto context termination A resource manager specifies zero when it does not want RRS to end the work context associated with the UR in which interest is being expressed when the UR completes. A resource manager specifies one when it wants RRS to end the work context associated with the UR in which interest is being expressed when the UR completes. Note: IBM® strongly recommends that one only be specified by the resource manager that owns the work context.
24–31	0	Reserved

ABEND codes

The call might result in an abend X'5C4' with a reason code of either X'001F0000' or X'001F0001'. 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 calling program is disabled; the interrupt status must be enabled for I/O and external interrupts. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the calling program and rerun it.
104 ATR_MODE_INV	Meaning: Program error. The calling program specified 0 in parent_UR_token or child_context_token, but the calling program is not in task mode. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the calling program and rerun it.
105 ATR_LOCKS_HELD	Meaning: Program error. The calling program is holding one or more locks; no locks must be held. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the calling program 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 is running a version of RRS that supports this service call. Then rerun the resource manager.
39A ATR_PARENT_UR_TOKEN_INV	Meaning: Program or environmental error. The UR token specified in the parent_UR_token parameter is not valid because one of the following is true: It was coded incorrectly The parent transaction failed The system it resided on failed The coordinator system failed The RRS running on that system failed The parent UR belongs to a system that is not in the same RRS logging group as this system If any of these conditions occurs, the system rejects the service call. Action: Check the calling program for a probable coding error. If it's a program error, correct the program and rerun it. If the work manager was creating a multisystem cascaded UR, the work manager must communicate the failure to the work manager originating the request. Installation action: Ensure that the originating work manager and this work manager are in the same RRS logging group.
39B ATR_CHILD_CONTEXT_TOKEN_INV	Meaning: Program error. The context token specified in the child_context_token parameter is not valid. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
39E ATR_PARENT_DU_TERMINATING	Meaning: Environmental error. The task associated with the UR represented by the parent_UR_token parameter is ending. The system rejects the service call. Action: None.
39F ATR_CHILD_DU_TERMINATING	Meaning: Environmental error. The task associated with the context specified by the child_context_token parameter is ending. The system rejects the service call. Action: None.
3A0 ATR_SAME_CURRENT_CONTEXT_INV	Meaning: Program error. The UR represented by the parent_UR_token and the UR associated with the context represented by the child_context_token are both 0. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3A1 ATR_SAME_PARENT_ CONTEXT_INV	Meaning: Program error. The UR represented by the parent_UR_token, which may have been specified with a 0, and the UR associated with the context represented by the child_context_token are the same UR. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3A2 ATR_SAME_CHILD_CONTEXT_INV	Meaning: Program error. The UR represented by the parent_UR_token and the UR associated with the context represented by the child_context_token, specified with a 0, are the same UR. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3A4 ATR_PARENT_AUTH_FAILURE	Meaning: Program error. The caller is PKM 8–15 problem state, but specified a parent_UR_token of a UR associated with a context which: Does not belong to a PKM 8–15 problem state resource manager registered in the home address space. Is not a native context in the home address space. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3A5 ATR_CHILD_AUTH_FAILURE	Meaning: Program error. The caller is PKM 8–15 problem state, but specified a child_context_token of a context which: Does not belong to a PKM 8–15 problem state resource manager registered in the home address space. Is not a native context in the home address space. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
3AD ATR_CREATE_OPTIONS_INV	Meaning: Program error. The create_options value specified on the call is not valid. Either reserved bits were nonzero or an unacceptable selection of options and parameters was specified. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
743 ATR_PARENT_UR_ STATE_ERROR	Meaning: Program error. The UR specified by the parent_UR_token is not in a valid state for the service call. The UR must be in an in-reset or in-flight state. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
744 ATR_CHILD_UR_STATE_ERROR	Meaning: Program error. The UR associated with the specified child_context_token is not in a valid state for the service call. The UR must be in an in-reset state. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the program and rerun it.
763 ATR_PARENT_LOCAL_TRAN_ MODE_INV	Meaning: Program error. The parent UR is in local transaction mode. The system rejects the service call. Action: Check the calling program for a probable coding error or an application environment configuration error. Correct the calling program 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 Create_Cascaded_UR 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 calling program attempts to create a parent-child relationship between the current unit of recovery and another unit of recovery that is to be the parent UR of the current UR. Storage for the call parameters has already been allocated.

⋮
PARENT_URTOKEN = TOPURTOKEN
CHILD_CTOKEN = 0
COPTS = ATR_DONT_END_CONTEXT_MASK
CALL ATRCCUR3(RC, PARENT_URTOKEN, CHILD_CTOKEN, CHILDURTOKEN, 
            CHILDURID, COPTS)
IF RC=0 THEN
    NEW_URTOKEN = CHILDURTOKEN
    NEW_URID = CHILDURID

⋮