|
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:
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
|
(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)
|
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
⋮
|