Application context

An application context is a set of data that identifies tasks that are running in the context of your application and platform. When an application is accessed through its application entry points, the CICS® regions generate application context data for the tasks related to the application. This task application context is available in the performance records that the CICS monitoring facility writes to SMF and includes data fields about the platform, the application, the application version and the operation. 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 can 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
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
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.
Both the initial or current application context can be used with the transaction tracking capability in CICS Explorer® to quickly identify and diagnose application-related problems. Both the initial and the current application contexts are propagated from task to task.

Creating an application context

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

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.

When application context isn't propagated

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.

Conditions for setting application context on to a task

PROGRAM resource
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.
Note:
  • 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).
TRANSACTION 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.
URIMAP 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. Application context data (ACD) settings of a task when a transaction and its initial program are both defined as entry points (EP).
Transaction is defined as an application entry point Initial program is defined as an application entry point Initial program is public or private Initial ACD for task Current ACD for task
Yes Yes Not applicable Set by the transaction entry point Set by the program entry point
Yes No Public Set by the transaction entry point Empty
Yes No Private Set by the transaction entry point Same as initial ACD
No Yes Not applicable Set by the program entry point Same as initial ACD
No No Not applicable Not set Not set
Table 2. Application context data (ACD) settings of a task when a URIMAP and its alias transaction are both defined as entry points (EP).
URIMAP is defined as an application entry point Alias transaction is defined as an application entry point Initial program is public or private Initial ACD for task Current ACD for task
Yes Yes Public Set by the transaction entry point Empty
Yes Yes Private Set by the transaction entry point Same as initial ACD
Yes No Public Set by the URIMAP entry point Empty
Yes No Private Set by the URIMAP entry point Same as initial ACD
No Yes Public Set by the TRANSACTION entry point Empty
No Yes Private Set by the TRANSACTION entry point 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 with DFH, which cannot be defined as an entry point. Therefore, all programs in Table 2 are not defined as entry points.
Table 3. Application context data (ACD) settings of a task when transactions are attached by EXEC CICS START or EXEC CICS RUN TRANSID.
Started transaction is defined as an application entry point Initial program of started transaction is defined as an application entry point 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 entry point Set by the PROGRAM entry point
Yes No Public Not applicable Set by the TRANSACTION entry point Empty
Yes No Private Not applicable Set by the TRANSACTION entry point Same as initial ACD
No Yes Not applicable Not applicable Set by the PROGRAM entry point 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. Application context data (ACD) settings of a task when a transaction is defined as DYNAMIC.
Transaction is defined as an APPLICATION entry point Starting task has ACD set ACD passed into routing program COMMAREA
Yes Yes Transaction's entry point
Yes No Transaction's entry point
No Yes Starting task's current ACD
No No No ACD