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