This article describes how it is possible to define a CICS policy and deploy it into a CICS region such that the policies rules are only applied to specific CICS user tasks rather than all user tasks that run in that CICS region.
CICS TS V5.1 introduced the capability to define policies to monitor the resource utilisation of a user task, and to automatically respond when resource usage exceeds the thresholds you define. In this way, excessive resource usage and looping and runaway transactions can be detected and dealt with appropriately. While primarily designed to be deployed with CICS applications and platforms to monitor application tasks they can also be deployed to stand-alone CICS regions to monitor any CICS user task. By default polices deployed to a CICS region apply to all user tasks executing in that region. However deploying polices with such a wide scope may not be suitable in all cases. What if you have a requirement to apply policy to specific tasks rather than all tasks? This article walks you through the steps required to restrict a CICS region policy so that its rules are only applied to specific user tasks.
Policy support in CICS TS
CICS Transaction Server V5.1 introduced the capability to define policies to monitor:
- Number of SQL requests
- Number of EXEC CICS file control requests
- Number of EXEC CICS LINK requests
- Number and size of EXEC CICS GETMAIN requests
- CPU time consumed by a task
CICS Transaction Server V5.2 built on this support to add further polices to monitor
- Number of EXEC CICS START requests
- Number of EXEC CICS SYNCPOINT requests
- Number of EXEC CICS transient data requests
- Number and size of EXEC CICS temporary storage requests
- Elapsed time of a task
A CICS policy is defined in a CICS bundle project and each bundle can define one or more policies. Once defined the bundle can then be deployed to a CICS region in one of three ways:
- Add the CICS bundle to a CICS platform. The bundle is deployed with the platform and any policy rules scoped so they apply to any application tasks running on that platform
- Add it to a CICS application or application binding. The bundle is then deployed with the CICS application and any policy rules scoped so they apply only to that particular application's tasks.
- Export the bundle to zFS, and then define, install and enable a CICS BUNDLE resource for the CICS bundle project in a CICS region. In this case any policy rules apply to ALL user tasks running in the CICS region.
This article concentrates on the last of these methods of deployment and shows you how to define a policy such that its rules are only applied to specific user tasks. To find out more information on how to deploy CICS policy with CICS platform and application please refer to "Working with platforms, applications, and policies" in the CICS TS 5.2 Knowledge Center.
For the purpose of this article lets assume we want to enforce the following rules in a CICS region:
- Abend any CICS task that consumes more than 1 second of CPU.
- Emit a CICS event if any of my business critical transactions consume more than 25% of their average CPU consumption.
Defining a region scoped policy
So first lets define a policy to abend any task using more than 1 second of CPU. All policies are created in a CICS bundle project using CICS Explorer. For details of how to create a CICS bundle project please refer to "Creating a CICS bundle project" in in the CICS TS 5.2 Knowledge Center.
Once you have created a CICS bundle project, right click on the bundle project in the Project Explorer view and select New->Policy Definition. The policy is then defined as follows:
Click Finish and a new file "region_CPU_policy.policy" will be added to your bundle project. That completes the definition of a policy that once deployed will apply to all CICS user tasks.
For a more detailed description of how to define a policy in a CICS bundle project please refer to "Creating a policy in a CICS Bundle project" in the CICS TS 5.2 Knowledge Center.
Restricting the scope of a policy
Next we need to define the policy to emit a CICS event if any business critical transaction consumes more CPU than normal. Let's assume one of these transactions is ORDR and we know from the analysis of CICS monitoring SMF records that on average this transaction consumes 400ms of CPU. So allowing a 25% buffer this means we need emit an event if an ORDR transaction consumes more than 500ms.
So first we define a policy to emit an event if a task consumes more than 500ms of CPU. This second policy can either be defined in the same CICS bundle project or a separate one; the choice is yours on how you manage your different policies. In this case we will define the second the policy in the same bundle project so they can be deployed and managed together. So again right click on the bundle project in the Project Explorer view and select New->Policy Definition. The second policy is then defined as follows:
The EP Adapter named here; CPUMON; could be any of the supported types of EP Adapter. For example it could be a simple custom adapter that writes a message to an operator console or a HTTP adapter that routes the event to an event processing product such as IBM Business Monitor to update an operations dashboard. For details on the different types of EP adapter available please refer to "Event processing adapters" in the in the CICS TS 5.2 Knowledge Center.
So far this policy looks no different to the first policy. In fact as it stands if we deploy this policy it will trigger an event if ANY task, including ORDR tasks, uses more than 500ms of CPU which is not what we want; we need to restrict its scope to just ORDR tasks. To do this we exploit two of the new features added in CICS TS 5.1 for CICS application and platform support; namely application entry points and policy scopes. These features enable us to be much more specific about which tasks policies are applied to even when those tasks are not part of a CICS application and by exploiting these features we can restrict a policy to just those tasks that pass through a given entry point. CICS currently supports 2 types of entry point; PROGRAM and URIMAP (CICS TS 5.2 only). You can use either type of entry point to help restrict which tasks a policy is applied to. For web service tasks you might chose to use a URIMAP entry point instead but in this case we will use a PROGRAM entry point.
A program entry point can be defined for ANY program that a given task invokes during its lifetime but please be aware that the set of policy rules applied to a task is based on the FIRST entry point a task passes through during its lifetime; if a task passes through a second entry point program no policy rules associated with the second entry point are applied to the task and the original policy rules all still apply to the task. When selecting the program to define as an entry point a TRANSACTION's initial program is an obvious choice. In many cases this may be an appropriate choice but please bear in mind that:
- the same initial program may be named on other transaction definitions
- the program may be invoked by another task via EXEC CICS LINK.
In both cases this could mean a policy may end up being applied to tasks it was not intended for so a program invoked by the initial program may be a more appropriate choice. However if the initial program is only invoked via the transaction it is the perfect choice to use as an entry point program to scope a policy to a particular TRANSACTION.
So if we assume that NEWORDER is the initial program of the ORDR TRANSACTION we define it at a program entry point as follows:
- First open up the CICS Bundle Manifest Editor. To do this double click on the cics.xml file in the CICS bundle projects META-INF folder
- Next select the "Entry Points" tab in the CICS Bundle Manifest Editor, and then
- Press the "Add" button and define the entry point as follows;
i) Set Operation to "new_order_ep". This can be any meaningful string up to 64 characters in length.
ii) Let the Resource Type default to PROGRAM. If you are going to deploy the resulting CICS bundle project to a CICS TS 5.2 region you could chose to define a URIMAP entry point here by selecting it from the list of valid "Resource Type".
iii) Set Resource name. We will set this to the name of the chosen entry point program so in this case its the initial program of the ORDR transaction "NEWORDER".
That's defined the set of tasks we are interested in to be those that pass through the entry point program NEWORDER, next we need to associate critical_task_CPU_policy we defined above with this entry point. To do so we define a Policy Scope. Again this is defined using the CICS manifest editor as follows:
- Select the "Policy Scopes" tab in the CICS Bundle Manifest editor, and then
- Press the "Add" button and define the Policy Scope as follows:
i) Set Operation to the value specified when defining the entry point previously, i.e "new_order_ep".
ii) Set Policy Name to the name of the policy we defined earlier, i.e "critical_task_CPU_policy".
Debug tip: Both Policy Name and Operation are case sensitive attributes. If your policy fails to trigger then the first thing to check is that these 2 names match exactly with the names specified when creating the policy and the entry point.
What if I want to apply the same policy to multiple transactions ?
That's easy. You can just repeat the process above and define further entry points for those transactions and policy scopes to associate the same policy with those entry points.
Deploying the CICS bundle and its policies
For details of how to deploy these polices to a CICS region please refer to "Deploying the policies to a single CICS region" in the CICS TS 5.2 Knowledge Center. As the CICS bundle defines application entry points the CICS BUNDLE resource must be set both ENABLED and AVAILABLE to activate the policies. After deployment is complete the following rules will be enforced in all CICS regions into which the bundle is deployed:
- Any ORDR task's consuming more than 500ms will cause a CICS event to be emitted to the CPUMON EP adapter.
- Any task, including ORDR tasks, consuming more than 1 second of CPU will be abended,
In this article you have seen how you can use functionality that's been available since CICS TS 5.1 to restrict the affect of CICS policy deployed to a CICS region such that its rules are only enforced on specific user tasks. Thanks for reading and I hope you found the information above useful. If you have any questions please leave a comment below and I will get back to you.