- CTXSDTA is for AMODE(31) callers.
- CTX4SDTA is for AMODE(64) callers and allows parameters in 64
bit addressable storage.
A resource manager calls the Set_Context_Data service to save data
to be associated with a specific context and to identify it with a
specified key. This key can be used to identify the data in subsequent
calls to Set_Context_Data, or to the Retrieve_Context_Data service.
In response to the call, context services issues a return code.
Note: - The Set_Context_Data service can be used to change or delete the
data specified on a previous invocation of Set_Context_Data. The data
may be retrieved via the Retrieve_Context_Data service.
- The data set by calling Set_Context_Data can only be set by a
program running with a PKM of 0–7 or in supervisor state; however,
the data can be retrieved by any program.
Environment
The requirements for the resource
manager 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 (CTXSDTA)
64 bit (CTX4SDTA)
|
ASC mode: |
Primary or AR |
Interrupt status: |
Enabled for I/O and external interrupts |
Locks: |
Unlocked |
Control parameters: |
Control parameters must be in the
primary address space and addressable by the resource manager. |
Programming requirements
Either link edit
the resource manager's object code with the linkable stub routine
CTXCSS (31 bit) or CTX4CSS (64 bit) from SYS1.CSSLIB, or LOAD and
CALL the service. The high level language (HLL) definitions for the
callable service are:
HLL definition |
Description |
---|
CTXASM |
390 Assembler declarations |
CTXC |
C/390 declarations |
Restrictions
The caller must be in Task
mode when invoking Set_Context_Data for the current dispatchable unit's
context.
Input register information
Before issuing
the call, the resource manager 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 resource manager, 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 resource manager,
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 resource managers depend on register contents
remaining the same before and after issuing a call. If the system
changes the contents of registers on which the resource manager depends,
the resource manager 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 CTXSDTA
|
(return_code
,context_token
,context_key
,context_datalength
,context_data)
|
CALL CTX4SDTA
|
(return_code
,context_token
,context_key
,context_datalength
,context_data)
|
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 Set_Context_Data service.
- ,context_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
The context_token identifies the context with which the data
is to be associated. If a value of "binary zeros" is supplied in this
field, then the context will be the currently active context of this
dispatchable unit of work. A context token may be obtained via the
Begin_Context, Express_Context_Interest, or Retrieve_Current_Context_Token
services.
- ,context_key
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 32 bytes
The context_key is an identifier used to identify the data
to be saved, and by which the data can be changed or deleted by later
calls to Set_Context_Data, or retrieved by a call to Retrieve_Context_Data.
You
may code almost any key to identify data. However, a specific key,
CTX.OWNER_INFO.IBM, is reserved by IBM® to
return special data. You may not set context_key to CTX.OWNER_INFO.IBM
with the Set_Context_Data service.
- ,context_datalength
- Supplied
parameter
- Type: Integer
- Character Set: N/A
- Length: 4 bytes
The context_datalength is the length of the data specified
by the context_data keyword. The maximum value is 4096 bytes of data.
If a length of zero is specified, the previously saved data identified
by context_datakey will be deleted.
- ,context_data
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 1 to 4096 bytes
The context_data is the data to be saved. The contents of
this parameter are ignored if the context_datalength is 0.
ABEND codes
The call might result in an
abend X'AC7' with a reason code of either X'00200000' or X'00200001'.
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
CTX_OK
|
Meaning: Successful completion.
Action: None.
|
103
CTX_INTERRUPT_INV
|
Meaning: Program error. The
caller is disabled. The system rejects the service call. Action:
Check program logic for probable coding error. Correct the problem
and reissue service.
|
104
CTX_MODE_INV
|
Meaning: Program error. The
caller is not in task mode. The system rejects the service call. Action:
Check program logic for probable coding error. Correct the problem
and reissue service.
|
105
CTX_LOCKS_HELD
|
Meaning: Program error.
The resource manager is holding one or more locks; no locks may 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
CTX_UNSUPPORTED_RELEASE
|
Meaning: Environment error.
The release of MVS™ does not support
this service. The service stub has been linked on a system that does
not support the correct level of Context Services. Action:
Remove the resource manager from the system, and install it on a
system that supports the correct level of Context Services. Then rerun
the resource manager.
|
309
CTX_RESERVED_NAME
|
Meaning: Program error.
The value specified in context_key is reserved for Context Services.
The system rejects the service call. Action: Check the
resource manager for a probable coding error. Correct the resource
manager and rerun it.
|
361
CTX_CONTEXT_TOKEN_INV
|
Meaning: Program error.
The context interest 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.
|
36B
CTX_DATA_LENGTH_INV
|
Meaning: Program error.
The data 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.
|
36C
CTX_DATA_KEY_NOTFOUND
|
Meaning: Program error.
The data key value specified in the call is not found. The system
rejects the service call. This code is only returned when the specified
data length is 0. Action: Check the resource manager for
a probable coding error. Correct the resource manager and rerun it.
|
36E
CTX_STORAGE_UNAVAILABLE
|
Meaning: Environment error.
There is no storage available from the necessary subpool to save the
data. The system rejects the service call. Action: Determine
why the system ran out of subpool 247. Correct the problem and reissue
service.
|
FFF
CTX_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 associate data for the key
FRED with
the current context. Storage for the call has been allocated.
⋮
C_TOKEN = ''B;
DATA_KEY = 'FRED';
DATA_LEN = 6;
DATA = 'MYDATA';
CALL CTXSDTA(RC,C_TOKEN,DATA_KEY,DATA_LEN,DATA);
IF RC ¬= CTX_OK THEN
/* handle error situation */
⋮