- CTXENDC is for AMODE(31) callers.
- CTX4ENDC is for AMODE(64) callers and allows parameters in 64
bit addressable storage.
A resource manager calls the End_Context service to end a privately-managed
context or a dispatchable unit native context. A native context has
a fixed association with a single dispatchable unit.
When an application program ends processing, your resource manager
should call the End_Context service to end any context associated
with the application. RRS default actions are to commit on normal
context termination and backout on abnormal context termination.
In response to the call, the system issues a return code. After
the call, the context token associated with the ended context is no
longer valid.
Next current context: A call to the End_Context service ends
the context specified in the context_token parameter.
If the call specifies a privately-managed context, the native context
becomes the current context. If the call specifies a native context,
which is also the current context, a new native context becomes the
current context.
Ending a privately-managed context: If a call to the
End_Context service specifies a privately-managed context
not
associated with a unit of work, the system gives control to the
CONTEXT_SWITCH exit routines of all resource managers interested in
the context. If any CONTEXT_SWITCH exit routine disallows the context
end, the call does not end the context. However, CONTEXT_SWITCH exit
routines cannot stop the context end if one of the following is true:
- The address space of the resource manager that owns the privately-managed
context is terminating.
- The End_Context service forces the ending.
The End_Context service might fail because a CONTEXT_SWITCH exit
routine disallows ending the context. To override the decision when
there is no other way to resolve the problem, the privately-managed
context owner can force an end to the context by specifying a completion_type of
CTX_FORCED_END_OF_CONTEXT on the End_Context call.
After the CONTEXT_SWITCH exit routines have completed, if the privately-managed
context is still ending, the system invokes the END_CONTEXT exit routines
associated with the context.
Environment
The requirements for the resource
manager are:
| Minimum authorization: |
None |
| Dispatchable unit mode: |
Task |
| Cross memory mode: |
Any PASN, any HASN, any SASN |
| AMODE: |
31 bit (CTXENDC)
64 bit (CTX4ENDC)
|
| 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_Information service, specifying context services as the exit
manager.
When calling End_Context to end a native context:
- The context must be the current context.
- Your resource manager must be running under the work unit associated
with the native context.
When calling End_Context to end a privately-managed context
associated with the work unit:
- Your resource manager must be running under the work unit associated
with the privately-managed 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.
Resource
managers that are PKM 8–15 problem state must register using the Register_Resource_Manager
service from the home address space before invoking this service.
They can only end native contexts and privately managed contexts obtained
by a key 8–15 problem state resource manager that registered from
the home address space.
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 CTXENDC
|
(return_code
,context_token
,completion_type)
|
| CALL CTX4ENDC
|
(return_code
,context_token
,completion_type)
|
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 End_Context service.
- ,context_token
- Supplied
parameter
- Type: Character string
- Character Set: No restriction
- Length: 16 bytes
Specifies the token for the context that the resource manager
wants to end, as follows:
- 0: Binary zeros specify the current context associated with the
application's task or SRB.
- 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.
- ,completion_type
- Supplied
parameter
- Type: Integer
- Character Set: N/A
- Length: 4 bytes
Indicates the type of completion for the context. The value
is passed to the END_CONTEXT exit routine. Specify one of the following:
| Constant in:
Hexadecimal
(Decimal)
Equate Symbol
|
Resource manager specifies the completion_type because: |
|---|
| 0
(0)
CTX_NORMAL_TERMINATION
|
The context is ending normally. |
| 1
(1)
CTX_ABNORMAL_TERMINATION
|
The context is ending abnormally. |
| 3
(3)
CTX_FORCED_END_OF_CONTEXT
|
The context must be forced to end. A SWITCH_CONTEXT exit routine
cannot prevent the context from ending. |
ABEND codes
The call might result in an
abend X'AC7' with a reason code of either X'00140000' or X'00140001'.
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.
|
| 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 context services. Then rerun the resource manager.
|
| 360
CTX_COMPLETION_TYPE_INV
|
Meaning: Program error. The completion_type 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.
|
| 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.
|
| 363
CTX_OTHER_WU_NATIVE
|
Meaning: Program error. The native context specified
in the call is the native context of another unit of work. The system
rejects the service call. Action: Check the resource manager
for a probable coding error. Correct the resource manager and rerun
it.
|
| 366
CTX_PRIVATE_OTHER_WU
|
Meaning: Program error. The privately-managed context
specified in the call is the current context of another work unit.
The system rejects the service call. Action: Check the
resource manager for a probable coding error. Correct the resource
manager and rerun it.
|
| 369
CTX_SWITCH_EXIT_PREVENTED_
END
|
Meaning: Program error. A CONTEXT_SWITCH exit routine
returned a code that indicated the context should not be ended. The
system rejects the service call. Action: Check the resource
manager for a probable coding error. Correct the resource manager
and rerun it.
|
| 756
CTX_AUTH_FAILURE
|
Meaning: Program error. The resource manager is PKM
8–15 problem state and specified a context token that does not belong
to a PKM 8–15 problem state resource manager registered in the home
address space. 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 end a context. Storage for the call
parameters has been allocated.
⋮
COMPLETION_TYPE = CTX_NORMAL_TERMINATION
C_TOKEN = CONTEXT_1
CALL CTXENDC(RC,C_TOKEN,COMPETION_TYPE)
IF RC ≠ CTX_OK THEN
/* Handle error */
⋮
z/OS MVS Programming: Resource Recovery
Copyright IBM Corporation 1990, 2014