Begin_Context (CTXBEGC, CTX4BEGC)

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

A resource manager calls the Begin_Context service to create a privately-managed context. Begin_Context is intended for use in a program that manages work on behalf of another program or user. The program accepts the responsibility to manage the environment for the other program.

In response to the call, context services returns:

A return code.
The context token for the privately-managed context. You need this token for a call to the following services: End_Context, Express_Context_Interest, Express_UR_Interest, Retrieve_Interest_Count, or Switch_Context.

Contexts: 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. The two types of contexts are:

Native context
Privately-managed context

An application's task has a native context associated with it. A resource manager can use a call to the Begin_Context service to obtain a privately-managed context, then use a call to the Switch_Context service to associate the privately-managed context with a task. While the privately-managed context is associated with a task, interactions with the application are related to the privately-managed context.

Later, the resource manager can use a call to the Switch_Context service to disassociate the privately-managed context; subsequent interactions are related to the native context for the task.

Current context: The native context is the original current context for an application's task. A Begin_Context call obtains a privately-managed context, and a call to Switch_Context associates the privately-managed context with the application; the native context still exists but is not current. The privately-managed context is the current context. If a call to the Switch_Context service later disassociates the privately-managed context, the native context again becomes the current context.

Context token: The context token is a random value that is not preserved across restarts of the system, exit manager, or resource manager. Thus:

Do not use the context token as an identifier in log records.
Do not try to discern the contents of the token or create any dependencies on the contents.

Environment

The requirements for the resource manager are:

Minimum authorization:

None

Dispatchable unit mode:

Task or SRB

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31 bit (CTXBEGC)
64 bit (CTX4BEGC)

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

The resource manager's object code must be linked with the linkable stub routine CTXCSS (31 bit) or CTX4CSS (64 bit) from SYS1.CSSLIB. 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 resource manager 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.

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 must specify a resource manager token of a key 8–15 problem state resource manager which registered from the home address space.

If a PKM 8–15 problem state resource manager attempts to create a context and doing so will result in the PKM 8–15 problem state resource manager registered in the space owning more than 256 contexts per unauthorized resource manager, context services will request confirmation of the request from a system operator. If the operator allows the request, the PKM 8–15 problem state resource managers registered in the space will be able to create as many contexts as they want. If the operator does not allow the request, a context will not be returned.

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 CTXBEGC

(return_code
,resource_manager_token
,context_token)

CALL CTX4BEGC

(return_code
,resource_manager_token
,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 Begin_Context 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

Returned parameter

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

Receives the token for the privately-managed context that the resource manager is creating. The context token uniquely identifies the privately-managed context.

ABEND codes

The call might result in an abend X'AC7' with a reason code of either X'00110000' or X'00110001'. 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 context 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.
701 CTX_RM_STATE_ERROR	Meaning: Program error. The resource manager associated with the resource manager token 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.
756 CTX_AUTH_FAILURE	Meaning: Program error. The resource manager is PKM 8–15 problem state and specified a resource manager 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 calling program for a probable coding error. Correct the calling program and rerun it.
F00 CTX_MAX_CTXT_EXCEEDED	Meaning: Environment error. The resource manager is PKM 8–15 problem state and attempted to create more than the allowable number of active contexts. The system rejects the service call. Action: Either allow unauthorized resource managers to own additional contexts or change your program so less contexts are required.
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 create a private context. Storage for the call parameters has been allocated.

⋮
RM_TOKEN = REG_TOKEN
CALL CTXBEGC(RC,RM_TOKEN,C_TOKEN)
IF RC ≠ CTX_OK THEN
    /* handle error */
⋮