Examples: Defining a policy that applies to specific user tasks in a single CICS region

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

1. 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.
2. After you have created a CICS bundle project, right-click the CICS bundle project in the Project Explorer view and click New > Policy Definition.

   

   The Create Policy Definition dialog opens.

   

   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.

3. On the Policy Overview tab, click the New button to the right of the Rules section to open the 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

4. Click OK to return to the Policy Definition editor. You are on the Rules tab by default.

   

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

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

Example 1: Defining a region scoped policy that applies to all user tasks has defined a policy that emits events when any task consumes more than 500 ms of CPU time, so you only need to confine its rule to the ORDR transaction.

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.

Procedure

1. Open the policy you created in Example 1: Defining a region scoped policy that applies to all user tasks, by double-clicking the policy file within the bundle in the Project Explorer view.
2. 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.
3. In the Condition section, specify Transaction ID equals ORDR.

   

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

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

   1. Right-click the CICS bundle project in the Project Explorer view and click New > Policy Definition.
   2. In the dialog, enter a name for the policy in the File name field and click Finish.
   3. 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.

   4. In the Condition section, define the threshold to be Elapse time greater than 2 Seconds.
   5. 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.

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

   1. Define ORDR as a transaction entry point.
      1. In the Project Explorer view, expand the CICS bundle project and META-INF folder.
      2. Open the CICS Bundle Manifest editor by double-clicking the cics.xml file.
      3. 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.

         

   2. Define a policy scope to associate the ORDR_elapsed_time policy with the entry point you defined.
      1. In the CICS Bundle Manifest editor, click the Policy Scopes tab.
      2. 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.

         

   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:

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

      1. Expand the CICS bundle project and META-INF folder.
      2. Open the CICS Bundle Manifest Editor by double-clicking the cics.xml file.
      3. 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.

   2. Define a policy scope to associate ORDR_elapsed_time policy with this entry point:
      1. In the CICS Bundle Manifest editor, click the Policy Scopes tab.
      2. 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.