Policy system rules support, first introduced in CICS TS 5.4 and subsequently back-ported to earlier CICS TS V5 releases by APAR PI83667, provides equivalent function to that provided by CICS system events but with much simpler configuration. This article aims to demonstrate just how easy it is to configure a system rule.
In CICS TS 4.2 we introduced support for system events. This helps you understand and manage the health and availability of your CICS system by emitting events that notify you when system health or system resource state changes. In CICS TS 5.1 we introduced support for CICS policy task threshold rules. This helps you identify excessive resource usage by individual user tasks and to automatically respond when that resource usage exceeds a threshold you define. The automated actions that can be configured for policies are: to issue a CICS message, emit an event or abend the user task. This resulted in two methods of performing broadly similar tasks. These two functions have now been brought together under Policy with the introduction of support for policy system rules.
Policy system rules
CICS TS 5.4 (or earlier CICS TS V5 releases with APAR PI83667 applied) includes support for seven types of system rules to help you monitor overall system health. They define the action to be taken when:
- the status of a DB2 connection changes from or to a specific state (DB2 connection status rule)
- the open status of a CICS FILE changes from or to a specific open state (File open status rule)
- the enable status of a CICS FILE changes from or to a specific enablement state (File enable status rule)
- CICS issues a DFHxxnnnn message or when CICSPlex® SM issues an EYUxxnnnn message (Message rule)
- the number of active tasks in a CICS transaction class goes above or below a percentage of a transaction class’s MAXACTIVE value (Transaction class tasks rule)
- a transaction encounters an unhandled abend (Transaction abends rule)
- the number of active tasks in a CICS system goes above or below a percentage of the MXT value (User tasks rule)
System rules provide functional equivalence and map one to one to the system events supported in CICS TS 5.3, but with much simpler configuration and they support two possible actions: issue a CICS message or emit a CICS event. A CICS message may be sufficient for your needs and system rules with this action are simple to adopt, avoiding the complexity that comes with supporting an event consumer. The CICS message could also be used with your existing automation products to trigger further automated actions. However, if you wish to perform further analysis on the ‘event’ using tools such as IBM Decision Manager or IBM Operational Decision Manager, or if you wish to start a CICS task to perform some automated action then the event action will be required.
While system events can still be defined and installed in CICS TS 5.4, support for system events is now deprecated and may be removed in a future release of CICS TS. Support for application events is unaffected and remains strategic.
All system rules are defined using the policy definition editor introduced in CICS Explorer 5.4 which replaces the original policy definition wizard. This new editor supports the creation, modification and deletion of both system rules and task rules (formerly referred to as task threshold rules) and can be used to modify any policy created using old policy definition wizard supplied with older versions of CICS Explorer. For further information see The policy definition editor in the IBM Knowledge Center.
In January 2018 a further APAR, PI88500, was shipped on CICS TS 5.1, 5.2, 5.3 and 5.4 to further enhance CICS Policy support to allow items of static data to be emitted with any policy events and for the policy events themselves to have user-defined names. CICS Explorer 188.8.131.52 provides the necessary enhancements to the Policy Definition Editor to allow you to define any static data items and an event name when defining your policy rules.
A simple example …
So let’s see just how simple it is to define a system rule by way of an example. Let’s say you wish to receive a notification when the number of active tasks in your CICS regions goes above 90% of your MXT value. To do this proceed as follows:
First create a CICS bundle project. All policies are defined 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 the IBM Knowledge Center.
Once you have created a CICS bundle project, right click on the bundle project in the Project Explorer view of CICS Explorer and select New>Policy Definition to open the Create Policy Definition wizard as follows:
Enter a name for the policy in the File name field and click Finish. This opens the policy definition editor in the Overview tab as follows:
Here you can optionally supply a description for the policy rules, and the value for the user tag. The user tag is included in the emitted event data when rules specify the event action. Here I have just used my initials.
Next we need to define the policy rule to issue a message when the number of tasks in the CICS region goes above 90% of the MXT value. To do this click on the New button to the right of the screen to open the New Rule dialogue as follows:
Enter a name for the rule together with an optional description. Then select the rule type from the list of supported rule types in the left-hand column. As we are defining a rule for when we go above 90% of MXT, select User tasks. As you do so a brief description of that rule type will be displayed on the right of the dialogue box. Press OK to open up the Rules tab of the policy definition editor:
Next define the condition which will trigger the automated action and the action to be taken when it is triggered. In this case there is only one condition that can be defined, Percentage of MXT, so to define the required condition for the rule being defined:
- select Goes higher than from the first drop-down box, and
- select 90% from the second drop-down box.
The action defaults to Issue a message so we can leave that as-is. That completes the definition of the required system rule to issue a message when the number of active task in a CICS region goes above 90% of the MXT value.
If the event action had been chosen instead of message then the action would be configured by:
- Selecting the Emit an event to radio button,
- Choosing EP Adapter or EP Adapter set from the drop-down box, and
- Entering the name of the EP adapter or EP adapter set in the box
That’s it! With the equivalent system event you have to choose which data to capture in the emitted event from a list that includes the from task count, the to task count the MXT value and the threshold defined. Whereas a policy system rule is much simpler to use because the events are pre-configured to contain all this information in the emitted events.
To deploy this policy to a CICS region you need to first export the CICS bundle project to zFS and then define, install and enable a CICS BUNDLE resource which refers to it. For details of how to do this see Deploying the policies to a single CICS region in the IBM Knowledge Center. Once that’s done, whenever the number of active tasks in your CICS region goes above 90% of MXT the following CICS message will be sent to the CMPO destination which by default is re-directed to CSSL:
DFHMP3009 07/05/2017 11:39:27 IYK2Z3B1 Task 00252 (STRT) has triggered a taskThreshold system rule goes_above_90_percent_of_MXT FROM=90, TO=91) defined by policy mySystemRules in bundle CICSDEV_system_rule.
In this case the CICS region has the MXT value set to 100 so the policy triggers when the 91st task is attached.
System rules are a re-implementation of system events as CICS policy with much simpler configuration and a choice of actions. For more details about defining and using CICS policy, see CICS Policies in the IBM Knowledge Center.