Retrieve_Context_Data (CTXRDTA, CTX4RDTA)

CTXRDTA is for AMODE(31) callers.
CTX4RDTA is for AMODE(64) callers and allows parameters in 64 bit addressable storage.

A resource manager calls the Retrieve_Context_Data service to retrieve the data associated with a particular context. The data must have previously been set by a call to Set_Context_Data. The resource manager specifies a key which identifies the data that is to be retrieved.

Environment

The requirements for the resource manager are:

Minimum authorization:

None

Dispatchable unit mode:

Task or SRB

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (CTXRDTA)
64 bit (CTX4RDTA)

ASC mode:

Primary or AR

Interrupt status:

Enabled for I/O and external interrupts

Locks:

Unlocked

Control parameters:

All parameters must be addressable by the caller and in the primary address space.

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 Retrieve_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 CTXRDTA

(return_code
,context_token
,context_key
,context_bufferlength
,context_datalength
,context_data_buffer)

CALL CTX4RDTA

(return_code
,context_token
,context_key
,context_bufferlength
,context_datalength
,context_data_buffer)

Parameters

The parameters are explained as follows:

return_code

Returned parameter

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

Provides the return code for the call.

,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 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 the identifier which was supplied on the earlier Set_Context_Data, and identifies the data which is to be retrieved.

If context_key is set to CTX.OWNER_INFO.IBM, the type and authorization of the context specified by the context_token will be returned in the context_data_buffer.

,context_bufferlength

Supplied parameter

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

The context_bufferlength is the length of the area specified by the context_data_buffer keyword for the return of the data. The minimum length is 1. If the length of the buffer is less than the length of the saved data, then only as much of the data will be returned as will fit in the buffer. In this case, the actual length of the data will be returned in the context_datalength keyword.

,context_datalength

Returned parameter

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

The context_datalength is the actual length of the data specified by the context_data_buffer keyword. A value of zero indicates that no data was returned. This value may be larger than context_bufferlength if the return code is CTX_PARTIAL_DATA.

,context_data_buffer

Returned parameter

Type: Character string
Character Set: No restriction
Length: 1 to 4096 bytes

The context_data_buffer is the area to which the saved data will be returned.

If context_key is set to CTX.OWNER_INFO.IBM, the following 6–word data string will be returned:

Word

Contents

0: The target work context is a DU native context.

1: The target work context is a privately managed context.

0: The target work context is owned by an authorized resource manager.

1: The target work context is owned by an unauthorized resource manager.

2–5

These words are reserved for future use. They contain random contents.

ABEND codes

The call might result in an abend X'AC7' with a reason code of either X'00210000' or X'00210001'. 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. Note: If there is no data associated with the specified key, the context datalength returned will be `0`. Action: None.
5 CTX_PARTIAL_DATA	Meaning: Program error. Partial data was returned. The buffer is not long enough to hold all of the data. The service completes successfully, but returns only partial data. The actual length of the data associated with the input context_key is returned in context_datalength. Action: Check program logic for probable coding error. Correct the problem and reissue service.
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 and specified 0 for context_token. 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: 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. The system rejects the service call. 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.
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.
36D CTX_BUFFER_LENGTH_INV	Meaning: Program error. The Buffer length specified via the CTXRDTA invocation is invalid. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
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 retrieve the data associated with the key FRED for the context associated with the current dispatchable unit.

⋮
C_TOKEN = ''B;
DATA_KEY = 'FRED';
DATA_LEN = 0;
BUFFER_LEN = 20;
DATA = '';
CALL CTXRDTA(RC,C_TOKEN,DATA_KEY,BUFFER_LEN,DATA_LEN,DATA);
IF RC ¬= CTX_OK THEN
    /* handle error situation */
⋮
IF DATA_LEN = 0 THEN
    /* handle no data associated with FRED */
⋮