Examples: Defining a policy that applies to specific user tasks in a single CICS region
These examples show different ways of restricting the scope of a CICS® policy containing task rules so that its rules are only applied to specific user tasks.
Example 1: Defining a region scoped policy that applies to all user tasks
When no policy scope or condition filter is specified, a policy that defines task rules and that
is deployed to a single CICS region applies to all user tasks
running in that region. The following procedure walks you through the steps to define a policy to
emit an event when any CICS user task consumes more than 500
milliseconds of CPU time.
Procedure
All policies are created in a CICS bundle project, so you
must first create a CICS bundle project. For details, see
Creating a CICS bundle project.
After you have created a CICS bundle project, right-click
the CICS bundle project in the Project
Explorer view and click New > Policy
Definition.
Enter a name for the policy (CICS_policy_example) in the
File name field and click Finish. This opens the
Policy Overview tab of the Policy Definition
editor.
On the Policy Overview tab, click the
New button to the right of the Rules section to open
the New Rule dialog.Figure 3. New Rule
dialog
Define the new rule as follows:
Field
Value
Name
event_if_more_than_500ms_of_CPU
Description (optional)
Emit a CICS event if a task consumes more than 500ms of
CPU
Rule type
Time
Click OK to return to the Policy Definition editor.
You are on the Rules tab by default.Figure 4. Rules
tab
In the Condition section, define the threshold as follows:
Select CPU time from the first drop-down box.
Specify 500 in the input field after greater
than.
Select milliseconds in the second drop-down box.
You can leave the Transaction ID and User ID filters as-is, because this policy is intended
to be region scoped.
In the Action section, define the action of the new rule as follows:
Select Emit an event.
Select EP Adapter from the drop-down box.
Enter CPUMON as the name of the EP adapter.
The EP adapter named here,
CPUMON, can be any of the supported types of EP Adapter. For example, it can 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, see
Event processing adapters in the CICS TS 6.1.0 product documentation.
Result
A new file CICS_policy_example.policy is added to the bundle project. That completes the definition of a policy that when deployed will apply to all CICS user tasks.
Example 2: Restricting the policy to certain user tasks using condition filters
Now, let's assume you want to restrict the policy to emit a CICS event only when a business critical transaction consumes more CPU than normal. Assume
that one of these transactions is ORDR, and the analysis of CICS monitoring SMF records concludes that on average this transaction consumes 400® ms of CPU. So allowing a 25% buffer, this means the policy
should emit an event if an ORDR transaction consumes more than 500 ms.
Because this policy contains only one rule, the easiest way of scoping the policy might be to
restrict the rule's scope using the Transaction ID or User ID filters provided as task rule
conditions. These filters take effect at the rule level so you can have rules of different scopes
within one policy if needed. When deployed to the region, the rule triggers an action only when the
threshold is met by tasks running under the specified transaction or user ID.
Note: The condition filters are supported in CICS TS 5.4 - 5.6 with APAR PH26145 and later releases. If your CICS is at an earlier version, consider using entry points and policy scopes.
In the Policy Definition editor that opens, double-click the
event_if_more_than_500ms_of_CPU rule you created. This opens the rule on the
Rules tab.
In the Condition section, specify Transaction ID equals ORDR.Figure 5. Condition of the
rule
Result
You now have a policy CICS_policy_example.policy. When deployed, the policy
will emit an event when any user task running under the ORDR transaction consumes more that 500 ms
of CPU time.
Example 3: Restricting a policy to specific user tasks using entry points and policy
scopes
It is also possible to scope a CICS policy to user tasks
running under a CICS transaction by defining application entry points and policy scopes for the policy. They are defined in a bundle
and apply to all rules contained in the specified policy. These features make it possible to be
specific to which tasks policies are applied, even when those tasks are not part of a CICS application. By exploiting these features, you can restrict
a policy to just those tasks that pass through a given entry point. CICS supports three types of entry point: PROGRAM, URIMAP, and TRANSACTION. This
example uses the TRANSACTION and PROGRAM entry points to show two different approaches. For web
service tasks, you might choose to use a URIMAP entry point instead.
In this example, a CICS threshold policy is defined to abend any user task running under the CICS Transaction ORDR when its elapsed time exceeds 2 seconds.
Procedure
Defining the elapsed time policy.
In this example, the policy will be defined in the same
bundle project so they can be deployed and managed together.
Right-click the CICS bundle project in the
Project Explorer view and click
New > Policy Definition.
In the dialog, enter a name for the policy in the File name field and
click Finish.
On the Policy Overview tab, click the
New button to the right of the Rules section to open
the New Rule dialog. Define the rule as follows:
Field
Value
Name
ORDR_elapsed_time
Description (optional)
Elapsed time policy for ORDR transaction
Rule type
Time
Click OK to open up the Rules tab of the Policy
Definition editor.
In the Condition section, define the threshold to be Elapse
time greater than 2
Seconds.
In the Action section, select Abend task with abend
code and specify a custom code ORDR to override the default
AMPB:
A new file ORDR_elapsed_time.policy will be added to your bundle
project. That completes the definition of the
policy.
As it stands, when this CICS bundle is deployed to a single CICS region that is not part of a CICSplex, the policy
will be applied to all CICS user tasks executing in that
region.
To further restrict the scope of the policy, proceed with either of the following approaches:
Option 1. Defining a TRANSACTION entry point
To restrict the policy to only instances of the ORDR transaction, you can:
Define ORDR as a transaction entry point.
Define a policy scope to restrict the effect of the policy ORDR_elpased_time to
all tasks that pass through this entry point.
Detailed steps are as follows:
Define ORDR as a transaction entry point.
In the Project Explorer view, expand the CICS bundle project and META-INF folder.
Open the CICS Bundle Manifest editor by double-clicking the
cics.xml file.
Click the Entry Points tab, and then click Add to
define an entry point, as follows:
Field
Value
Operation
ORDR_transaction_entry_point
Resource Type
Select TRANSACTION from the drop-down box
Resource Name
ORDR
The resource for an application entry
point does not have to be defined in the same CICS bundle as
the application entry point, but needs to be installed before the bundle is deployed.
Figure 6. Create Application Entry Point dialog
Define a policy scope to associate the ORDR_elapsed_time policy with the
entry point you defined.
In the CICS Bundle Manifest editor, click the Policy
Scopes tab.
Click the Add button and define the policy scope as follows:
Field
Value
Operation
ORDR_transaction_entry_point
Policy Name
ORDR_elpased_time
Note: Both Policy Name and
Operation are case sensitive attributes. Ensure the names match exactly those
defined previously. Otherwise your policy might fail to trigger.
Figure 7. Create Policy Scope dialog
Option 2. Defining a PROGRAM entry point
A PROGRAM entry point can be defined for any program that a given task invokes during its
lifetime. However, 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 you select the program to
define as an entry point, a TRANSACTION's initial program is an obvious choice. In many cases, this
might be an appropriate choice but bear in mind that:
The same initial program might be named on other transaction definitions.
The program might be invoked by another task via EXEC CICS LINK.
In both cases, this means a policy might end up being applied to tasks it was not
intended for, so a program invoked by the initial program might be a more appropriate choice.
However, if the initial program is only invoked via the transaction, you can safely use it as an
entry point program to scope a policy to a particular TRANSACTION. Otherwise, consider using the
TRANSACTION entry point or condition filter instead.
Follow the steps as follows:
Define a PROGRAM application entry point.
Assume that NEWORDER is the initial program of the
ORDR transaction, define it as a program entry point as follows:
Expand the CICS bundle project and META-INF folder.
Open the CICS Bundle Manifest Editor by double-clicking the
cics.xml file.
Click the Entry Points tab, and then click Add to
define an entry point, as follows:
Field
Value
Operation
new_order_ep
This can be any meaningful string up to 64 characters in length.
Resource Type
PROGRAM (default)
Resource Name
Set it to the name of the chosen entry point program, so in this case it's the initial
program of the ORDR transaction NEWORDR.
The resource for an application entry
point does not have to be defined in the same CICS bundle as
the application entry point, but needs to be installed before the bundle is deployed.
Define a policy scope to associate ORDR_elapsed_time policy with this entry point:
In the CICS Bundle Manifest editor, click the Policy
Scopes tab.
Click the Add button and define the policy scope as follows:
Field
Value
Operation
new_order_ep
Policy Name
ORDR_elapsed_time
Note: Both Policy Name and
Operation are case sensitive attributes. Ensure the names match exactly those
defined previously. Otherwise your policy might fail to trigger.
Tip: If you want to apply the same policy to multiple
transactions or programs, you can repeat the process above and define further entry points for those
transactions or programs, and policy scopes to associate the same policy with those entry
points.
Result
You now have a policy ORDR_elapsed_time. When deployed, the policy will abend any user task running under the CICS Transaction ORDR when its elapsed time exceeds 2 seconds.
What to do next
Deploy the CICS bundle and its policies. For details, see
Deploying a CICS bundle. If you're using policy entry points, the CICS BUNDLE resource must be set both ENABLED and AVAILABLE to
activate the policies because the CICS bundle defines
application entry points.
After deployment is complete, the following rules will be enforced in all CICS regions into which the bundle is deployed:
Any ORDR task that is consuming more than 500 ms will cause a CICS event to be emitted to the CPUMON EP adapter.
Any ORDR task with an elapsed time greater than 2 seconds will be abended.