The policy definition editor

Use the policy definition editor to create or edit system and task rules in a policy.

The policy definition editor opens automatically after you create a policy. To open the editor at a later time, go to the Project Explorer view, open the project, and double-click any of the .policy files. Alternatively, right-click a .policy file, click Open With, and then select Policy Definition editor. If you do not have a versioned backup system that enables you to revert to a previous version of the project, instead of editing the existing project directly, you can copy it to another project and edit the new copy.

Errors and warnings during the editing process are displayed in the main editor window. You can find saved errors in the Problems view.

To reverse one or more of your changes before you save them, use the Undo function. On the workbench menu, click Edit > Undo, or press Ctrl+Z (cmd+Z for macOS).

To reverse changes made by the Undo function before you save them, use the Redo function. On the workbench menu, click Edit > Redo, or press Ctrl+Y (cmd+Y for macOS).

To save your changes, click the Save icon The save icon, or press Ctrl+S (cmd+S for macOS). If you attempt to close the editor without saving the changes, a dialog is displayed asking whether you want to save your changes or close without saving.

The policy definition editor has two tabs: Overview and Rules. It also provides a New Rule dialog for rule creation and a Copy Existing Rule dialog for rule duplication.

Overview tab in the policy definition editor

Policy Overview tab

The Policy Overview tab in the policy definition editor summarizes information that applies to the whole policy, such as the policy name, description, and the rules defined in the policy. It contains the following sections:
General Information
The name, description, and user tag for the policy are displayed. The description and user tag are optional and can be edited.
Actions
Contain a list of actions you can perform against the policy in the editor.
Rules
Displays a table of created rules with their rule descriptions. The minimum CICS® release that is required for each rule defined in the policy is also displayed. In the lower-right corner of this section, the minimum CICS release that is required to provide necessary runtime support for all the rules defined in the policy is also displayed.
You can perform the following actions in this section:
  • Editing a rule in either of the following ways:
    • Selecting a rule in the table and then clicking either the Name or the Description column to edit its value directly in the table.
    • Double-clicking a rule in the table to edit it in the Rules tab.
  • Adding a rule by clicking the New button in this section. This opens the New Rule dialog.
  • Duplicating a rule by selecting a rule in the table and then clicking the Copy button in this section. This opens the Copy Existing Rule dialog.
  • Deleting a rule by selecting a rule in the table and then clicking the Delete button in this section.

Rules tab

The Rules tab in the policy definition editor shows detailed information about the selected rule. On this tab, you can define the condition for each rule, and specify an action to be taken when the defined condition is met.
The Rules tab in the policy definition editor
The Rules tab contains the following sections:
Rules
Displays rules that are created in the editor. When you select a rule from this section, its detailed information is displayed in the other sections on the tab.

Click the add rule icon icon in the top right of this section to create a new rule, the copy rule icon icon to create a copy of the selected rule, or the delete rule icon icon to delete the selected rule.

General Information
Displays the rule type and description of the selected rule. You can edit its description in the Description field.
Condition
Displays the condition that is defined for the selected rule. Use this section to set the condition that triggers the requested action when it is met.

Based on the rule type, different kinds of condition are supported. As a result, the content in the Condition section changes depending on the rule type. For more information on what conditions are available for different rule types, see Policy conditions.

When you set a threshold for a task rule, it is recommended that you determine the threshold value by using CICS monitoring data or reports from a tool such as CICS PA. For more information, see Policies and CICS Performance Analyzer.

Action
Displays the action that is defined for the selected rule. Use this section to define the action to be taken when the specified condition is met. You can choose one of the following actions based on the rule type. To set more than one action, you can duplicate your rule and define another action for the new rule.
For all rule types:
  • Issue a message. CICS issues a message to the CICS log when the specified condition is met. For task rules, either DFHMP3001 or DFHMP3007 is issued. For system rules, either DFHMP3009 or DFHMP3010 is issued.
  • Emit an event. Specifies an event processing (EP) adapter or an EP adapter set for CICS to emit an event either to a single EP adapter or to all adapters in an EP adapter set. EP adapters format the event data into a suitable output format, and route the event to the defined event consumers. You can optionally specify static data to be associated with the event and an event name. For instructions about defining the event action for a policy rule, see Creating a policy in a CICS bundle project.
    Tip: For a policy rule with the event action specified, you can export the event specifications as a schema or copybook for use elsewhere. For instructions, see Exporting event specifications from a policy.
For system rules only:
  • Set z/OS WLM open status to. Sets the z/OS® WLM health open status of the CICS region. This rule action, when triggered, results in increasing or decreasing the region's WLM health value according to the adjustment percentage and time interval that are effective at CICS run time. If the WLMHEALTH time interval needs to be modified, use the Set interval to option provided. CICS also issues a message (DFHMP3015 or DFHMP3016) to the CICS log when the z/OS WLM open status is modified by the policy rule.
    No change to interval
    This is the default. The region's WLMHEALTH time interval at run time is to remain unchanged.
    Set interval to
    Select this option if you want to modify the region's WLMHEALTH time interval. Specify a new value in the range 1 - 600, in seconds, in the field next to the option. When the rule is triggered, the region's WLMHEALTH time interval is set to this value as part of the set z/OS WLM health open status action.
For task rules only:
  • Abend task. CICS terminates the running task when the specified threshold is crossed. CICS also issues a message (DFHMP3002 or DFHMP3008) to the CICS log when a task is terminated. The default abend code is AMPB but you can overtype this to specify another code for the task abend.

For more information about supported policy actions, see Policy actions.

New Rule dialog

Use the New Rule dialog to create a new rule in the policy. To open this dialog, you can either click New on the Policy Overview tab, or click the add rule icon icon in the upper right of the Rules section on the Rules tab.

The New Rule dialog in the policy definition editor
In the New Rule dialog, you must specify a rule type name; you can also specify a description for your rule. The dialog lists all the rule types you can define by using the policy definition editor. Two types of rule are supported:
System rules
Define the action to be taken when something of interest happens in a CICS system, such as a resource state change, a threshold being crossed, or an unusual system state or action. Policies that define system rules can be deployed either to a single CICS region or with a CICS platform. They cannot be deployed with a CICS application.
Task rules
Define the action to be taken when a CICS user task crosses a threshold, such as consuming too much CPU, allocating too much storage, or issuing too many requests to IBM® MQ. Policies that define task rules can be deployed to a single CICS region, with a CICS platform, or with a CICS application.

When you select a rule type, a description of that rule type is displayed. For more information about each rule type, see Policy task rules and Policy system rules.

Copy Existing Rule dialog

The Copy Existing Rule dialog allows you to duplicate an existing rule and make alterations to the copy.

To open this dialog, you can either click Copy on the Policy Overview tab, or click the copy rule icon icon in the top right of the Rules section on the Rules tab.
The Copy Existing Rule dialog

In the dialog, the name for the new rule and its description are prefilled for you. You can either use these values or overtype them to supply new values.