 |
- ATRRENV is for AMODE(31) callers.
- ATR4RENV is for AMODE(64) callers and allows parameters in 64
bit addressable storage.
A work manager calls the Retrieve_Environment service to retrieve
the environment settings at the address space level, at the context
level, or at the default level. The settings retrieved have either
been set via the Set_Environment service, or defaulted to. RRS need
not be available when the service is called.
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 (ATRRENV)
64 bit (ATR4RENV)
|
| 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 SRB mode callers cannot specify
a context token of 0 when trying to retrieve environment settings
at the context scope (ATR_CONTEXT_SCOPE).
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 call as shown in the syntax
diagram. You must code the parameters in the CALL statement as shown.
| CALL ATRRENV
|
(return_code
,diag_area
,scope
,context_token
,stoken
,element_count
,environment_id
,environment_value
,environment_protection)
|
| CALL ATR4RENV
|
(return_code
,diag_area
,scope
,context_token
,stoken
,element_count
,environment_id
,environment_value
,environment_protection)
|
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 Retrieve_Environment service.
- ,diag_area
- Returned
parameter
- Type: Character string
- Character Set: No restriction
- Length: 32 bytes
Contains diagnostic data from Retrieve_Environment to help IBM® Service determine the cause
of a Retrieve_Environment failure. Be sure to log this data when recording
any information about a Retrieve_Environment failure.
- ,scope
- Supplied
parameter
- Type: Integer
- Character Set: N/A
- Length: 4 bytes
Specifies the scope at which you want to receive environment
setting value(s), either address space level, context level, or at
the default level, as follows: | Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
Description |
|---|
| 1
(1)
ATR_ADDRESS_SPACE_SCOPE
|
Retrieve the environmental setting for each element in the environment_id array
at the address space level. |
| 2
(2)
ATR_CONTEXT_SCOPE
|
Retrieve the environmental setting for each element in the environment_id array
at the context level for the context represented by the context_token parameter. |
| 3
(3)
ATR_DEFAULT_SCOPE
|
Retrieve the environmental setting for each element in the environment_id array
at the level that RRS will use for the UR associated with the work
context represented by 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 retrieving context scope environment settings: - 0: Binary zero specifies either:
- The current context (when scope is ATR_CONTEXT_SCOPE
or ATR_DEFAULT_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 retrieving address space scope environment
settings: - 0: Binary zeros indicate the primary address space. If scope is
ATR_CONTEXT_SCOPE or ATR_DEFAULT_SCOPE, then stoken must
be 0.
- token: Specifies a valid address space token.
- ,element_count
- Supplied
parameter
- Type: Integer
- Character Set: N/A
- Length: 4 bytes
Specifies the number of elements in the environment-retrieving
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-retrieving 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 attribute of the environment settings to be retrieved. 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 settings to
be returned in the environment_id 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
|
Retrieve the environmental setting for transaction mode. If scope is
ATR_DEFAULT_SCOPE and no call was made to Set_Environment to set the
transaction mode, RRS returns ATR_HYBRID_GLOBAL_MODE.
If scope is
ATR_ADDRESS_SPACE_SCOPE or ATR_CONTEXT_SCOPE, RRS returns the value
of the address space or context as specified on the last applicable
call to Set_Environment for the specified address space or context.
If the specified environment has not been set, RRS returns ATR_ENVIRONMENT_NOT_SET.
|
| 2
(2)
ATR_NORM_CTX_END_SETTING
|
Retrieve the environmental setting for the two-phase commit
action RRS is to take for in-flight URs when their associated
context goes through normal end processing. If scope is
ATR_DEFAULT_SCOPE and no call was made to Set_Environment to set the
normal transaction context end setting, RRS returns ATR_COMMIT_ACTION.
If scope is
ATR_ADDRESS_SPACE_SCOPE or ATR_CONTEXT_SCOPE, RRS returns the value
of the address space or context as specified on the last applicable
call to Set_Environment for the specified address space or context.
If the specified environment has not been set, RRS returns ATR_ENVIRONMENT_NOT_SET.
|
- ,environment_value
- Returned
parameter
- Type: Integer
- Character Set: N/A
- Length: 4 bytes
Returns 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.
The
value returned for ATR_TRAN_MODE_SETTING is 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) has not been set. (This setting is not valid when scope is
ATR_DEFAULT_SCOPE.) |
| 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. |
The value returned for ATR_NORM_CTX_END_SETTING is
one of the following: | Value in:
Hexadecimal
(Decimal)
Equate Symbol
|
Description |
|---|
| 0
(0)
ATR_NOT_SET
|
The two-phase commit setting at the scope specified by environment_id (address
space or context) has not been set. If the two-phase commit environment
is not set, RRS will commit the UR on normal task termination. |
| 1
(1)
ATR_COMMIT_ACTION
|
The action RRS will take is to commit the UR. |
| 2
(2)
ATR_ROLLBACK_ACTION
|
The action RRS will take is to roll back the UR. |
- ,environment_protection
- Returned
parameter
- Type: Integer
- Character Set: N/A
- Length: 4 bytes
Returns 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 corresponding protection values in the environment_protection array.
The
value returned is one of the following: | Value in:
Hexadecimal
(Decimal)
Equate Symbol
|
Description |
|---|
| 1
(1)
ATR_UNPROTECTED_SETTING
|
The setting can be changed by an unauthorized caller. |
| 2
(2)
ATR_PROTECTED_SETTING
|
The setting can be changed only by an authorized caller. |
ABEND codes The call might result in an
abend X'5C4' with a reason code of either X'00270000' or X'00270001'.
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.
|
| 104
ATR_MODE_INV
|
Meaning: Program error. The calling program is not
in task mode, specified a zero context token, and requested the retrieval
of environment settings at a scope of ATR_CONTEXT_SCOPE. 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 application is holding
one or more locks; no locks must be held. The system rejects the service
call. Action: Check the application 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 is running a version of RRS that supports this service
call. Then rerun the resource manager.
|
| 361
ATR_CONTEXT_TOKEN_INV
|
Meaning: Program error. The context token 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.
|
| 362
ATR_STOKEN_INV
|
Meaning: Program error. The address space token 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.
|
| 364
ATR_ENV_SETTING_ID_INV
|
Meaning: Program error. A value in the environment_id parameter
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.
|
| 366
ATR_SCOPE_INV
|
Meaning: Program error. The scope 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.
|
| 392
ATR_ELEMENT_COUNT_INV
|
Meaning: Program error. The element count value 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.
|
| 802
ATR_STOKEN_NOT_ZERO
|
Meaning: Program error. The stoken parameter was incorrectly
specified. The stoken is not zero, but the caller specified ATR_CONTEXT_SCOPE
or ATR_DEFAULT_SCOPE on the scope parameter. The system rejects the
service call. Action: Check the resource manager for a
probable coding error. Correct the resource manager and rerun it.
|
| 803
ATR_CTOKEN_NOT_ZERO
|
Meaning: Program error. The context token parameter
was incorrectly specified. The caller specified ATR_ADDRESS_SPACE_SCOPE
on the scope parameter and a non-zero value on the context token parameter.
The system rejects the service call. Action: Check the
resource manager for a probable coding error. Correct the resource
manager and rerun it.
|
| 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
work manager issues a call to retrieve environmental settings at the
context level. ⋮
SCOPE = ATR_CONTEXT_SCOPE
C_TOKEN = MY_CONTEXT_TOKEN
A_TOKEN = 0
ELE_CNT = 1
ENV_SET_ID = ATR_NORM_CTX_END_SETTING
CALL ATRRENV(RC,DIAG_DATA,SCOPE,C_TOKEN,A_TOKEN,ELE_CNT,
ENV_SET_ID,ENV_SET,ENV_SET_PROT)
⋮
|
z/OS MVS Programming: Resource Recovery
Copyright IBM Corporation 1990, 2014