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.

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.

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

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.

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

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.

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.

Scenarios that do not support application context propagation

By default the initial and current application contexts are propagated from task to task. 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 program issues an EXEC CICS RUN TRANSID command 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 TRANSACTION resource is defined as an application entry point, the application context is set onto a task when any of the following conditions occur:
  • The TRANSACTION resource runs (the context is set before the nominated resource runs).
  • A program issues an EXEC CICS START command for the TRANSACTION 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 that is specified in the URIMAP resource. For the requests that are eligible to directly attach the transaction, the application context is set on the CICS transaction that is specified on the URIMAP resource. For more information, see Processing HTTP requests by using directly attached user transactions. 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 that is specified in the URIMAP resource. For the requests that are eligible to directly attach the transaction, the application context is set on the CICS transaction that is specified on the URIMAP resource. For more information, see Processing HTTP requests by using directly attached user transactions. The default transaction is the CPIH transaction.
Table 1. Task's application context data (ACD) settings when a transaction and its initial program are both defined as entry points (EP).
Transaction is defined as an application EP Initial program is defined as an application EP Initial program is public or private Initial ACD for task Current ACD for task
Yes Yes Not applicable Set by the transaction EP Set by the program EP
Yes No Public Set by the transaction EP Empty
Yes No Private Set by the transaction EP Same as initial ACD
No Yes Not applicable Set by the program EP Same as initial ACD
No No Not applicable Not set Not set
Table 2. Task's application context data (ACD) settings when a urimap and its alias transaction are both defined as entry points (EP).
Urimap is defined as an application EP Alias transaction is defined as an application EP Initial program is public or private Initial ACD for task Current ACD for task
Yes Yes Public Set by the transaction EP Empty
Yes Yes Private Set by the transaction EP Same as initial ACD
Yes No Public Set by the urimap EP Empty
Yes No Private Set by the urimap EP Same as initial ACD
No Yes Public Set by the transaction EP Empty
No Yes Private Set by the transaction EP Same as initial ACD
No No Not applicable Not set Not set
Note: The initial program of an alias transaction for a urimap cannot be set as an application entry point because its initial program starts DFH, which cannot be defined as an entry point. Therefore, all programs in this table are not defined as entry points.
Table 3. Task's application context data (ACD) settings when transactions are attached by EXEC CICS START or EXEC CICS RUN TRANSID.
Started transaction is defined as an application EP Initial program of started transaction is defined as an application EP Initial program is public or private Starting task has ACD set Initial ACD for task Current ACD for task
Yes Yes Not applicable Not applicable Set by the transaction EP Set by the program EP
Yes No Public Not applicable Set by the transaction EP Empty
Yes No Private Not applicable Set by the transaction EP Same as initial ACD
No Yes Not applicable Not applicable Set by the program EP Same as initial ACD
No No Not applicable Yes Inherits ACD from starting task Empty
No No Not applicable Not applicable Not set Not set
Table 4. Task's application context data (ACD) settings when a transaction is defined as DYNAMIC.
Transaction is defined as an application EP Starting task has ACD set ACD passed into routing program COMMAREA
Yes Yes Transaction's EP
Yes No Transaction's EP
No Yes Starting task's current ACD
No No No ACD

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.
  • The application context on a task is unchanged for either a COBOL program that makes a dynamic call to another program or a PL/I program that issues a FETCH and CALL to call another program (that is, if the EXEC CICS LINK call is bypassed).