Application context

An application context is a set of data that identifies tasks that are running in the context of your application and platform. CICS® adds an application context to each task at the point the application is entered. You can use the information to measure resource consumption by applications (or by particular routes into applications), to use policy-based management for applications, and to relate tasks to specific applications to help with problem diagnosis.

A task may pass through one or more applications as it executes. Each task can have up to two application contexts associated with it at any time:

The initial application context of a task is used for monitoring and measuring how much resource an application or a particular application operation is using across CICS regions and multiple tasks. The initial application context can be used when applying a policy to tasks that are part of an application, to define threshold conditions to manage the behavior of the tasks. The initial application context can be inherited from an invoking task, or set when the task first passes through an application entry point.
The current application context of a task is used for loading private libraries and WLM user exits. The current application context can be queried using XPI, SPI, and API calls. The current application context changes each time the task passes through an application entry point.

The initial or current application context can be used with the transaction tracking capability in the CICS Explorer® to quickly identify and diagnose application-related problems. Both the initial and the current application contexts are propagated from task to task. End of change

Start of change To create an application context, a CICS resource must be declared as an application entry point for an application that is deployed on a platform. PROGRAM and URIMAP resources can be declared as application entry points. PROGRAM entry points must be called by using an EXEC CICS LINK command. For more information about application entry points, see Application entry points. End of change

Note: Using the EXEC CICS XCTL command or COBOL call (whether static or dynamic) to create an application context is not supported.

Start of change When a task that does not have an application context calls a resource that is declared as an application entry point, CICS creates an application context that becomes the initial application context associated with the task. This application context is also associated with any subsequent programs that the task calls and tasks that it starts. If a task already has an application context, the new application context becomes the current application context for the task. The task's initial application context continues to be used for monitoring and scoping of policies. End of change

The application context contains the following data:

Application name
Major version number for the application
Minor version number for the application
Micro version number for the application
Platform name for the platform where the application is deployed
Operation name for the application entry point

Start of change You can specify the application context to browse private resources by using the EXEC CICS INQUIRE system programming command. By default, CICS searches for the private and public resources that are available to the program where the EXEC CICS INQUIRE command is issued. You can specify a different application context to browse the private and public resources that are available for another application. When you use the application context for browsing the resources that are used by an application, you do not specify the operation name. End of change

Start of change Application context data is passed in the DFHDYPDS parameter list and the EYURWCOM parameter list, and can be used in custom dynamic routing algorithms. For more information about dynamic routing, see Dynamic routing with CICSPlex® SM. End of change

Scenarios that do not support application context propagation

Start of change By default the initial and current application contexts are propagated from task to task. End of change However, some CICS commands, interfaces, connection types, and other processes do not support application context propagation between tasks.

The following scenarios do not support application context propagation:

A task is attached by a START command that specifies the TERMID option.
A task is attached by a DTP or CPIC request.
A task is attached over an APPC connection.
A task is attached using the transaction start EP adapter.
A task is attached by the JVM server when a ThreadExecutor service creates a new thread.
A web service pipeline handler transaction is routed over an MRO connection.
An outbound HTTP request is made to CICS using CICS Web support.
A task is created using a URIMAP resource as an application entry point for Liberty that calls CICSExecutorService to start a thread in a Java™ program.

Viewing the current application context

To view the current application context, you can:

Use the CICS Explorer Task Association view.
Use the EXEC CICS INQUIRE ASSOCIATION command.
Use the EXEC CICS ASSIGN command.
Query the current application context from within a global user exit using the monitoring XPI function INQUIRE_APP_CONTEXT.
Query the current application context using the JCICS Task.getApplicationContext() method.

Conditions when an application context is set onto a task

When a PROGRAM resource is defined as an application entry point, the application context is set onto a task when any of the following conditions occur:

A CICS transaction that specifies the name of the PROGRAM resource runs (the context is set before the nominated resource runs).
A program issues an EXEC CICS LINK command to the PROGRAM resource.
A program issues an EXEC CICS INVOKE APPLICATION command naming an operation which equates to the PROGRAM resource.
A Java program issues a Program.link() command to the PROGRAM resource.
A java program issues an Application.invoke() command naming an operation which equates to the PROGRAM resource.

When a URIMAP resource is defined as an application entry point, the application context is set onto tasks as follows:

If the HTTP/HTTPS request URL matches a URIMAP resource with USAGE(JVMSERVER), the application context is set on the task that runs the CICS transaction specified in the URIMAP resource.
If the HTTP/HTTPS request URL matches a URIMAP resource with USAGE(SERVER) and a static response is to be provided, the application context is set on the CWXN task. A static response is provided by specifying the HFSFILE or TEMPLATENAME values.
If the HTTP/HTTPS request URL matches a URIMAP resource with USAGE(SERVER) and a static response is not to be provided, the application context is set on the CWXN task and this application context is also propagated to the task that runs the CICS transaction specified in the URIMAP resource. The default alias transaction is the CWBA transaction.
If the HTTP/HTTPS request URL matches a URIMAP resource with USAGE(PIPELINE), the application context is set on the CWXN task and also propagated to the task that runs the CICS transaction specified in the URIMAP resource. The default alias transaction is the CPIH transaction.

Restrictions

The application context is set on a task for a program defined as an application entry point, only if that program runs locally. If the program runs remotely, the request is passed to the remote CICS region, and it is on the remote CICS region that the context is set, if the resource is also flagged as an application entry point on that CICS region.
Context is not set on a task, for a COBOL program that makes a dynamic call to another program (that is, if the EXEC CICS LINK call is bypassed).