Set_Context_Interest_Data (CTXSCID, CTXSCID2, CTX4SCID)

A resource manager calls the Set_Context_Interest_Data service to provide or change context interest data. The system passes the current context interest data to the resource manager's exit routines associated with the context interest. Your resource manager can issue:

A call to the Set_Context_Interest_Data service to specify the data, if it is not specified in a call to the Express_Context_Interest service
One or more calls to the Set_Context_Interest_Data service to change this data
A call to the Retrieve_Context_Interest_Data service to retrieve the data

There are three versions of Set_Context_Interest_Data, each with different parameters.

CTXSCID is for AMODE(31) callers and is the basic version of the service.
CTXSCID2 is for AMODE(31) callers and adds current context interest data support.
CTX4SCID is for AMODE(64) callers, allows parameters in 64 bit addressable storage, and adds current context interest data support.

Code your resource manager to call the version that includes the support you need.

For CTXSCID2 and CTX4SCID callers, to enable serialized update of the context interest data, you must provide the expected current value of the context interest data when you make the call to Set_Context_Interest_Data. If the provided data does not match the real data, the set request will fail and the actual current data will be returned.

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 (CTXSCID, CTXSCID2)
64 bit (CTX4SCID)

ASC mode:

Primary or 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 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

To call the service, the resource manager associated with the context interest token specified in the call must be in set state, which means it has registered and called the set exit routine service, specifying context services as the exit manager.

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 appropriate call as shown in the syntax diagrams. You must code the parameters in the CALL statement as shown.

CALL CTXSCID

(return_code
,context_interest_token
,context_interest_data)

CALL CTXSCID2

(return_code
,context_interest_token
,context_interest_data
,current_context_interest_data)

CALL CTX4SCID

(return_code
,context_interest_token
,context_interest_data
,current_context_interest_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_Interest_Data service.

,context_interest_token

Supplied parameter

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

Specifies the context interest token that identifies your resource manager's interest in the context. Your resource manager received the token from the Express_Context_Interest service.

,context_interest_data

Supplied parameter

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

Specifies the context interest data the system is to associate with this context interest. The Express_Context_Interest service can also specify this data. If context interest data already exists, the system replaces it with the context interest data you supply.

,current_context_interest_data

Supplied and returned parameter

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

For CTXSCID2 callers, specifies the current context interest data the system is to compare with context interest data. As part of a compare and swap, if current_context_interest_data matches the context interest data, then the context interest data is set to context_interest_data. Otherwise, current_context_interest_data returns the context interest data.

ABEND codes

The call might result in an abend X'AC7' with a reason code of either X'00170000' or X'00170001'. 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.
8 CTX_CUR_CI_DATA_MISMATCH	Meaning: Program error. The context interest data parameter no longer contains the value that was passed on input to Set_Context_Interest_Data. The system rejects the service call. Action: Check the resource manager for a probable coding error. Correct the resource manager and rerun it.
103 CTX_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.
105 CTX_LOCKS_HELD	Meaning: Program error. The resource manager is holding one or more locks; no locks must 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: 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 supports registration services. Then rerun the resource manager.
365 CTX_CI_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.
701 CTX_RM_STATE_ERROR	Meaning: Program error. The resource manager associated with the context specified in the call is not in a valid state to issue the service call. The resource manager must be in set state. 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 retrieves the current context interest data value for an interest identified by context_interest_token and updates that value to new_ci_data. Storage for the call parameters has already been allocated.

⋮
DONE = FALSE
CI_TOKEN = CONTEXT_INTEREST_TOKEN
/* RETRIEVE CURRENT VERSION OF CI_DATA */
CALL CTXRCID(RC,CI_TOKEN,CURRENT_CI_DATA)
/* BUILD NEW DATA */
DO WHILE(¬DONE)
      CI_DATA = NEW_CI_DATA
      /* UPDATE CI_DATA IF IT HAS NOT CHANGED SINCE LAST TIME I LOOKED */
      CALL CTXSCID2(RC,CI_TOKEN,CI_DATA,CURRENT_CI_DATA)
      IF RC ¬= CTX_CUR_CI_DATA_MISMATCH THEN
            DONE = TRUE
END DO
⋮