Creating a policy in a CICS bundle project

A policy is an XML definition that contains one or more policy rules that trigger an automated action when the specified condition is met. Policy rules can apply to a CICS® system or an individual user task. You can use CICS Explorer® to define policies in a CICS Bundle project, which allows you to maintain and deploy policies as a whole.

Before you begin

Before you create a policy, you must have an existing CICS bundle project. For more information, see Creating a CICS bundle project.

About this task

What rules can be defined within a policy?

CICS supports system and task rules. A system rule monitors and controls the overall health of a CICS system, and a task rule monitors and controls an individual user task. Each policy rule defines the conditions that must be met before an automated action is performed. Each policy can define one or more rules and multiple policies can apply to the same CICS system or one individual user task.

Taking policy scope into consideration when defining policy rules

When defining policies, it's useful to consider what scope you want to deploy the policies into. The following table shows policy scopes that are applicable to different rule types.

Table 1. Policy scope for different rule types
Policy scope Task rules System rules
Region level
(deployed into a CICS region)
 Yes.  1 

Rules apply to all user tasks running in the specified region.

 Yes.

Rules apply to all tasks (system or user) in the specified region that make changes to system or resource state.
Platform level
(deployed with a CICS platform)
 Yes.

Rules apply to all user tasks for any CICS application that is deployed on the specified platform.

 Yes.

Rules apply to all tasks (system or user) in all regions of the specified platform that make changes to system or resource state.
Application level
(deployed with a CICS application)
 Yes.  1 

Rules apply only to the users tasks for the specified application and not to other user tasks that might run on the same platform.

 NA.

Policies that define system rules cannot be deployed at the application level.
Notes:

Although system and task rules can be defined in the same policy, you must define the two types of rule in separate policies if you want to deploy any policy that defines task rules with a CICS application.

 1 : If a policy contains task rules that are deployed at the region or application level, you can further restrict its scope to specific user tasks by defining a policy scope or condition filters. For more information, see Restricting a task rule policy to specific user tasks in a single CICS region.

Procedure

  1. In the Project Explorer view, select the parent folder of a CICS bundle project.
  2. Open the New Project wizard in either of the following ways:
    • On the main menu for the workbench, click File > New > Other. Then expand the CICS Resources folder, select Policy Definition, and click Next.
    • Right-click the CICS bundle project, and then click New > Policy Definition.
  3. Create a policy to contain the policy rule:
    1. In the File Name field, enter the policy file name, for example policy_rules.
    2. Click Finish.
      This opens the policy definition editor. For more information, see The policy definition editor.
    Tip: To quickly create a policy rule from a CICS local file or transaction class resource, navigate to the corresponding resource view and right-click the resource for which you want to create a policy. Select Create Policy and then a rule type to be created.
  4. Optional: To help yourself identify the policy, you can update these fields in the General Information section on the Policy Overview tab:
    Field Description
    Description Description of the policy.
    User Tag A user defined 1-8 character identifier that is included in any event emitted for rules defined in a policy. It can be a version number, a department code, or initials of the policy author, that is, anything that helps associate an event with the policy that requests the event.
  5. Create a rule in the policy definition editor:
    1. On the Policy Overview tab, click New.
    2. In the New Rule dialog, enter a rule name, select a rule type from the list, and optionally enter a description for the rule.
      For detailed information about available rules, see Policy system rules and Policy task rules.
    3. Click OK. This opens the Rules tab.
  6. In the Conditions section on the Rules tab, define the conditions that trigger the automated action when they are met.
    System and task rules support different types of condition. For more information, see Policy rule conditions.
    Note: The earliest CICS release that supports a specific rule is displayed in the lower-right corner of the Conditions section. Ensure that it is equal to or less than the CICS release to which this policy will be deployed. For more information, see Policy schema versions.
  7. Select one action to take when the defined conditions are met:

    The for both rules icon 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.

    The for both rules iconEmit 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. For more instructions, see Choosing an EP adapter resource and Choosing an EP adapter set resource.
    Action tab on the Rules tab of the policy definition editor
    Optionally, to distinguish events emitted by policy rules of the same type, specify the event name as follows. If no event name is specified, a default one is used.
    Field Requirements
    Event name
    • 1 - 32 characters in length.
    • Acceptable characters are: 0-9 A-Z a-z _
    • Must start with an alphabetic character and cannot start with characters XML in any case.
    Optionally, to pass unchangeable data to the event consumer, associate static data items with the event by clicking Add. Any rule can contain a maximum of 479 static data items. Define each static data item as a name-value pair as follows.
    Field Requirements
    Name
    • 1 - 32 characters in length.
    • Acceptable characters are: 0-9 A-Z a-z _
    • Must start with an alphabetic character and cannot start with characters EPFE, MPFE, or XML in any case.
    • Must be unique within a rule.
    Value
    • 1 - 255 characters in length.
    • Acceptable characters are as follows, including embedded spaces:

      0-9 A-Z a-z `¬¦!"£$%^&*()_+-={}:@~;'#<>?,./|

    Note: If you specify the event action for a policy rule, you can export the event specifications as a schema or copybook for use elsewhere. Definitions of static data capture items are included in the exported file; and if an event name is specified, it is used as the prefix of the exported file name. For instructions, see Exporting event specifications from a policy.

    The task rules only icon 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.

    The system rules only icon 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.
  8. Optional: Add more rules by following Steps 5 through 7.
  9. To save the policy, click File > Save.
    You now have a basic policy ready to be deployed. If you defined task rules in the policy and want to add more customization, for example, to restrict the policy to specific user tasks, see Restricting a task rule policy to specific user tasks in a single CICS region. Otherwise, follow the steps as follows to deploy your policy as-is.

Results

A policy is created in the CICS bundle project.

What to do next

You can now deploy your new policy using CICS Explorer. For instructions, see Deploying a policy in a CICS bundle project.