- CTXRCID is for AMODE(31) callers.
- CTX4RCID is for AMODE(64) callers and allows parameters in 64
bit addressable storage.
A resource manager calls the Retrieve_Context_Interest_Data service
to retrieve the context interest data supplied by the resource manager
in:
- A call to the Express_Context_Interest service
- A call to the Set_Context_Interest_Data service
In response to the call, context services also returns a return
code.
A resource manager can express interest in a context multiple times.
The particular interest for this call is identified by the context
interest token your resource manager received from the Express_Context_Interest
service.
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 (CTXRCID)
64 bit (CTX4RCID)
|
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_Information 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 call as shown in the syntax
diagram. You must code the parameters in the CALL statement as shown.
CALL CTXRCID
|
(return_code
,context_interest_token
,context_interest_data)
|
CALL CTX4RCID
|
(return_code
,context_interest_token
,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 Retrieve_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
- Returned
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Receives the context interest data associated with this
context interest. The resource manager supplied the data on the most
recent call to the Express_Context_Interest or Set_Context_Interest_Data
service. If no earlier call has supplied context interest data, the
field contains hexadecimal zeros.
ABEND codes
The call might result in an
abend X'AC7' with a reason code of either X'00160000' or X'00160001'.
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_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.
|
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 context interest data.
Storage for the call parameters has been allocated.
⋮
CI_TOKEN = CONTEXT_INTEREST_TOKEN
CALL CTXRCID(RC,CI_TOKEN,CI_DATA)
IF RC = CTX_OK THEN
CONTEXT_I_DATA = CI_DATA
⋮