Set_Context_Data (CTXSDTA, CTX4SDTA)

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 */
⋮