• Must specify ATR_UNPROTECTED_SETTING for the protection_level parameter.
• Cannot change any environmental settings established (by an authorized caller) with ATR_PROTECTED_SETTING for each element of the environment_protection parameter.
• Can change an address space scope setting only when that space is the primary address space (the stoken parameter is 0) and the setting is unprotected.
• Can change a context scope setting only when:
  • The context is current, the setting is unprotected, and the home address space scope setting is unprotected.
  • The context is not current, the setting is unprotected, the context is owned by a key 8–15 problem state work manager registered in the home address space, and the home address space scope setting is unprotected.

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

Register

Contents

0-1

Used as work registers by the system

2-13

Unchanged

14-15

Used as work registers by the system

return_code

Returned parameter

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

Contains the return code from the Set_Environment service.

,diag_area

Returned parameter

• Type: Character string
• Character Set: No restriction
• Length: 32 bytes

Contains diagnostic data from Set_Environment to help IBM® Service determine the cause of a Set_Environment failure. Be sure to log this data when recording any information about a Set_Environment failure.

,scope

Supplied parameter

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

Specifies the scope of the environmental setting value(s), either address space scope or context scope, as follows:

Constant in: Hexadecimal (Decimal) Equate Symbol	Description
1 (1) ATR_ADDRESS_SPACE_SCOPE	The environmental setting has address space scope for the address space represented by the token in the stoken parameter.
2 (2) ATR_CONTEXT_SCOPE	The environmental setting applies for the context represented by the token in the context_token parameter.

,context_token

Supplied parameter

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

Specifies the token of the context for which the resource manager is establishing context scope environment settings:

• 0: Binary zeros specify either:
  • The current context (when scope is ATR_CONTEXT_SCOPE)
  • No context (when scope is ATR_ADDRESS_SPACE_SCOPE)
  If scope is ATR_ADDRESS_SPACE_SCOPE, then context_token must be 0.
• token: Specifies a valid context token.

,stoken

Supplied parameter

• Type: Character string
• Character Set: No restriction
• Length: 8 bytes

Specifies the space token (stoken) of the address space for which the resource manager is establishing address space scope environment settings:

• 0: Binary zeros indicate the primary address space (required for unauthorized callers). If scope is ATR_CONTEXT_SCOPE, then stoken must be 0.
• token: Specifies a valid address space token.

Note: If an unauthorized caller in cross-memory mode specifies 0, the system rejects the call.

,element_count

Supplied parameter

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

Specifies the number of elements in the environment-setting array, which consists of the environment_id, environment_value, and environment_protection parameters.

The maximum number of elements is the number of possible environment settings (transaction mode and two-phase commit action) times the number of environment-setting parameters. The maximum number is 2.

,environment_id

Supplied parameter

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

Specifies one or more identifiers; each identifier supplies an environment attribute that is to be set. When you specify more than one identifier, you must define an array; element_count indicates the number of elements in the array. The positions of the identifiers in this array define the positions of the environment attributes in the environment-setting array. The scope parameter specifies the scope at which these settings are to apply. Specify each identifier as one of the following:

Identifier in: Hexadecimal (Decimal) Equate Symbol	Description
1 (1) ATR_TRAN_MODE_SETTING	The service is to set the transaction mode.
2 (2) ATR_NORM_CTX_END_SETTING	The service is to set the two-phase commit action RRS should take for in-flight URs when the associated context goes through normal end processing. Note: This setting does not apply to a cascaded (child) UR. The outcome of the entire syncpoint tree is determined by the environmental setting of only the top-level UR, not any of the child URs.

,environment_value

Supplied parameter

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

Supplies a value for each identifier on the environment_id parameter. When you specify more than one identifier, you must define an array, where element_count indicates the number of elements in the array. The positions of the identifiers in the environment_id array define the positions of the environment attributes in the environment_value array.

Specify the value for ATR_TRAN_MODE_SETTING as one of the following:

Value in: Hexadecimal (Decimal) Equate Symbol	Description
0 (0) ATR_NOT_SET	The transaction mode environment setting for this environment_id (address space or context) is to be removed. Setting this value makes it as if Set_Environment (for the environment_id specified) was never issued.
1 (1) ATR_GLOBAL_MODE	The transaction mode is set to global for the requested scope.
2 (2) ATR_LOCAL_MODE	The transaction mode is set to local for the requested scope.
3 (3) ATR_HYBRID_GLOBAL_MODE	The transaction mode is set to hybrid-global for the requested scope. This is the same as global mode, except it allows the resource manager to exhibit proprietary connection behavior.

Specify the value for ATR_NORM_CTX_END_SETTING as one of the following:

Value in: Hexadecimal (Decimal) Equate Symbol	Description
0 (0) ATR_NOT_SET	The environment setting at this environment_id (address space or context) is removed. Setting this value makes it as if Set_Environment (for the environment_id specified) was never issued.
1 (1) ATR_COMMIT_ACTION	RRS is to commit in-flight URs.
2 (2) ATR_ROLLBACK_ACTION	RRS is to roll back in-flight URs.

,environment_protection

Supplied parameter

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

Supplies a protection value for each identifier in the environment_id parameter. When you specify more than one identifier, you must define an array, where element_count indicates the number of elements in the array. The positions of the identifiers in the environment_id array define the positions of the environment attributes in the environment_protection array.

Only an authorized caller can set the protection value. By setting ATR_PROTECTED_SETTING, authorized callers can prevent unauthorized callers from changing the environmental settings. Specify each element as one of the following:

Value in: Hexadecimal (Decimal) Equate Symbol	Description
1 (1) ATR_UNPROTECTED_SETTING	An unauthorized caller can change the settings specified in the corresponding element in the environment_value array.
2 (2) ATR_PROTECTED_SETTING	Only an authorized caller can change the settings specified in the corresponding element in the environment_value array.

⋮
SCOPE = ATR_CONTEXT_SCOPE
C_TOKEN = MY_CONTEXT_TOKEN
A_TOKEN = 0
ELE_CNT = 1
ENV_SET_ID = ATR_NORM_CTX_END_SETTING
ENV_SET = ATR_COMMIT_ACTION
ENV_SET_PROT = ATR_PROTECTED_SETTING
CALL ATRSENV(RC,DIAG_DATA,SCOPE,C_TOKEN,A_TOKEN,ELE_CNT,
            ENV_SET_ID,ENV_SET,ENV_SET_PROT)
⋮