Switch_Context (CTXSWCH, CTX4SWCH)

CTXSWCH is for AMODE(31) callers.
CTX4SWCH is for AMODE(64) callers and allows parameters in 64 bit addressable storage.

A resource manager calls the Switch_Context service to switch the context associated with the application's task to another context. In response to the call, the system returns a return code.

A context can be associated with only one task at a time. A context represents the resources for a work request; a context consists of the application program requesting the work and the protected resources involved in the work.

A native context exists when an application requests work. A resource manager can associate a privately-managed context with an application by calling the Switch_Context service.

Possible context switches: A call to the Switch_Context service can switch the context for the current task:

From one privately-managed context to another privately managed context
From the native context to a privately-managed context
From a privately-managed context to the native context

The call cannot be used to switch from one native context to another.

Results of context switches: The results of using the call to associate the current application's task with a different context depend on the type of the previously current context:

If the previously current context was a native context, it will still be associated with the task, but it will no longer be the current context.
If the previously current context was a privately-managed context, it will be disassociated from the task. If the call specifies a new privately-managed context, the new context becomes the current context. Otherwise, the native context becomes the current context for the task.

When it processes the Switch_Context service, the system invokes each CONTEXT_SWITCH exit routine set by a resource manager with an interest in the context. Any CONTEXT_SWITCH exit routine can disallow the context switch.

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 (CTXSWCH)
64 bit (CTX4SWCH)

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.

The context to be associated with the current application's task must not be already associated with another task.

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 switch contexts obtained by a key 8–15 problem state resource manager which registered from the home address space.

Note: A PKM 8–15 problem state resource manager can switch to and from the native context.

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 CTXSWCH

(return_code
,context_token
,disassociated_context_token)

CALL CTX4SWCH

(return_code
,context_token
,disassociated_context_token)

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

,context_token

Supplied parameter

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

Specifies the token for the context to be associated with the current application's task:

0: Binary zeros specify the native context. The call switches the task from a privately-managed context to the native context.
token: Specifies the context token of a privately-managed context. The call switches the task from its current context to the specified privately-managed context. The current context can be a privately-managed context or a native context.

,disassociated_context_token

Returned parameter

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

Specifies the token for the privately-managed context that was disassociated by the switch.

0: Binary zeros, if the previous current context was the native context.
token: The disassociated context token. It identifies the privately-managed context that has been disassociated from the current task.

ABEND codes

The call might result in an abend X'AC7' with a reason code of either X'00150000' or X'00150001'. 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 registration services. Then rerun the resource manager.
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.
362 CTX_PRIVATE_CURRENT	Meaning: Program error. The privately-managed context specified in the context_token parameter in the call is already the current context. 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 context specified in the context_token parameter in the call is the native context for another task or SRB. 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.
368 CTX_CURRENT_WU_NATIVE	Meaning: Program error. The context specified in the context_token parameter in the call is the native context and is already the current context. 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 task or SRB associated with or to be associated with the context specified in the context_token parameter in the call is terminating. The system rejects the service call. Action: None.
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.
800 CTX_DISALLOW_SWITCH	Meaning: Program error. A CONTEXT_SWITCH exit routine disallowed the context switch requested in the call. The system rejects the service call. Action: Check the resource manager for a probable coding or environmental error. Correct the resource manager and rerun it.
801 CTX_DISALLOW_SWITCH_WU	Meaning: Program error. A CONTEXT_SWITCH exit routine disallowed the context switch requested in the call because the calling resource manager is running under the wrong work unit. The system rejects the service call. Action: Check the resource manager for a probable coding or environmental 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 switch an application's task or SRB to another context. Storage for the call parameters has been allocated.

⋮
C_TOKEN = CONTEXT_1
CALL CTXSWCH(RC,C_TOKEN,DISASSOC_C_TOKEN)
IF RC ≠ CTX_OK THEN
⋮