Express_Context_Interest (CTXEINT, CTXEINT1, CTX4EINT)

A resource manager calls the Express_Context_Interest service to express an interest in a privately-managed context or a dispatchable unit native context. A native context has a fixed association with a single dispatchable unit. There are three versions of Express_Context_Interest, each with different parameters.

CTXEINT is for AMODE(31) callers and is the basic version of the service.
CTXEINT1 is for AMODE(31) callers and adds work manager name support.
CTX4EINTis for AMODE(64) callers, allows parameters in 64 bit addressable storage, and includes work manager name support.

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

In response to the call, context services returns:

A return code.
The context token of the current context, if requested.
The context interest token. You need the context interest token for calls to the following services: Delete_Context_Interest, Retrieve_Context_Interest_Data, or Set_Context_Interest_Data.
For CTXEINT1 and CTX4EINT callers, the work manager name of the resource manager that owns the context associated with the expression of interest.

If your resource manager already has an interest in the context, a call to the Express_Context_Interest service can do one of the following, depending on the multiple_interest_option parameter you supply:

Return the context interest token and the context interest data for the existing interest
If your resource manager already has several interests in a context, there is no way to predict which one the service will return.
Create a new interest in the context and provide a new context interest token for the new interest

Expressing interest: Expressing interest in a context tells the system to invoke your resource manager's exit routines for this context interest. A resource manager can express interest in any context in any address space. A resource manager can make the call multiple times to create multiple context interests.

Expressing interest in a context has no connection with expressing interest in a unit of recovery (UR).

Context interest data: In the call, your resource manager provides context interest data. The system passes this data to your resource manager's exit routines invoked for this context interest. This data can contain an anchor for the resource manager's data structures for the context. Your resource manager can issue:

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

Context end: The context abnormally ends if the application program abnormally ends processing or if the application's address space abnormally ends. Other conditions that can abnormally end a context are:

The End_Context service specifies an abnormal condition.
The owner of a disassociated privately-managed context ends.

Depending on how the context ends and on the memterm_option parameter in the Express_Context_Interest call, the system might give control to your resource manager's END_CONTEXT exit routine.

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 (CTXEINT, CTXEINT1)
64 bit (CTX4EINT)

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 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. must be in run state.

When the resource manager issues the call in SRB mode, the call cannot specify a context_token of 0, indicating the current context.

If you are coding an RRS exit routine, do not call this service to process the context associated with the UR passed to the exit routine in the ur_interest_token parameter.

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 CTXEINT

(return_code
,resource_manager_token
,context_token
,memterm_option
,context_interest_data
,current_context_token
,context_interest_token
,returned_context_interest_data
,multiple_interest_option)

CALL CTXEINT1

(return_code
,resource_manager_token
,context_token
,memterm_option
,context_interest_data
,current_context_token
,context_interest_token
,returned_context_interest_data
,multiple_interest_option
,work_manager_name)

CALL CTX4EINT

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 Express_Context_Interest service.

,resource_manager_token

Supplied parameter

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

Specifies the resource manager token that identifies the resource manager. Your resource manager received the token from the Register_Resource_Manager service.

,context_token

Supplied parameter

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

Specifies the token for the context in which the resource manager is expressing an interest, as follows:

0: Binary zeros specify the current context associated with the application's task.
token: The context token of a privately-managed context.

For a privately-managed context, your resource manager received the context_token from the Begin_Context service.

,memterm_option

Supplied parameter

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

Indicates whether or not the resource manager's END_CONTEXT exit routine should receive control if the context abnormally ends. Specify one of the following:

Constant in: Hexadecimal (Decimal) Equate Symbol	Description
0 (0) CTX_ALL_TERMINATIONS	All endings: The END_CONTEXT exit routine receives control at all endings, including memory termination.
1 (1) CTX_NOT_MEMTERM	All endings, except memory termination: The END_CONTEXT exit routine receives control at all endings except memory termination.

,context_interest_data

Supplied parameter

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

Specifies the context interest data that the system is to associate with this context interest. The Retrieve_Context_Interest_Data service can retrieve the context interest data.

,current_context_token

Returned parameter

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

Receives the following from the service:

The token of the current context, if the call specifies zeros in the context_token parameter. The token is a 16-byte character string.
Undefined, if context_token specifies a token.

,context_interest_token

Returned parameter

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

Receives the context interest token from the service. The context interest token uniquely identifies your resource manager's interest in the context. If you specified CTX_CONDITIONAL on multiple_interest_option, the context interest token represents an existing interest, if there is one. Otherwise, the context interest token represents the newly created interest.

,returned_context_interest_data

Returned parameter

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

If multiple_interest_option specified CTX_CONDITIONAL and the return code from the service is CTX_RM_ALREADY_HAS_INTEREST, this field receives the context interest data from the service. The data comes from an already existing interest that the resource manager has in the context. If the resource manager does not have an existing interest, the service returns binary zeros.

Otherwise, this field is undefined.

,multiple_interest_option

Supplied parameter

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

Indicates whether or not the service is to create a new interest when the resource manager already has an interest in the context. Specify one of the following:

Constant in: Hexadecimal (Decimal) Equate Symbol	Description
0 (0) CTX_UNCONDITIONAL	Unconditional: The service should create a new interest, even when the resource manager already has an interest in the context.
1 (1) CTX_CONDITIONAL	Conditional: The service should not create a new interest when the resource manager already has an interest in the context.

When you specify CTX_CONDITIONAL and the resource manager has an existing interest in the specified context, the values in memterm_option and context_interest_data are ignored.

,work_manager_name

Returned parameter

Type: Character string
Character Set: See Note
Length: 32 bytes

For CTXEINT1 callers, this field receives the work manager name from the service. The work manager name is the 32–byte name of the resource manager that owns the privately-managed context this expression of interest pertains to. If the expression of interest is for a dispatchable unit native context, the work manager name returned is a concatenation of the following strings:

SystemName
Period (.)
JobName
Period (.)
ASID (4 bytes readable hexadecimal)
Blanks (padded to 32 bytes)

Note: The work manager name can consist of the following printable characters:

Alphanumeric characters: A–Z and 0–9
National characters: $ (X'5B'), # (X'7B'), and @ (X'7C')
The period (.)
The underscore (_)
The trailing blank characters needed to fill the 32–byte field

ABEND codes

The call might result in an abend X'AC7' with a reason code of either X'00130000' or X'00130001'. 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_RM_ALREADY_HAS_INTEREST	Meaning: The resource manager already has an expression of interest in this context. The system returns the context_interest_token and returned_context_interest_data for an existing expression of interest in the context by the resource manager. Action: Process the returned information.
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.
104 CTX_MODE_INV	Meaning: Program error. The calling program is not in task mode, which is the required mode. The system rejects the service call. Action: Check the calling program for a probable coding error. Correct the calling program 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.
301 CTX_RM_TOKEN_INV	Meaning: Program error. The resource manager 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.
361 CTX_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.
364 CTX_MEMTERM_INV	Meaning: Program error. The memterm_option value 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.
367 CTX_MULTIPLE_INTEREST_ OPTION_INV	Meaning: Program error. The multiple_interest_option value 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.
36A CTX_DU_TERMINATING	Meaning: Environmental error. The application's task or SRB associated with the specified context is abnormally ending. The system rejects the service call. Action: None.
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 issues a call to express an interest in a context. Storage for the call parameters has been allocated.

⋮
RM_TOKEN = REG_TOKEN
C_TOKEN = CONTEXT_1
MEMTERM_OPT = CTX_ALL_TERMINATIONS
CI_DATA = CONTEXT_1_DATA
CALL CTXEINT1(RC,RM_TOKEN,C_TOKEN,MEMTERM_OPT,CI_DATA,
            CUR_C_TOKEN,CI_TOKEN,
            RETURNED_CONTEXT_INTEREST_DATA,
            MULTIPLE_INTEREST_OPTION,
            WORK_MANAGER_NAME)
IF RC = CTX_OK THEN
  DO
   CONTEXT_INTEREST_TOKEN = CI_TOKEN
   MYWMNAME=WORK_MANAGER_NAME
  END DO
⋮