A policy is an XML definition that contains one or more policy rules. A policy rule
describes the action to be applied to a CICS system or an individual user task
when the specified condition is met. A policy is created in a CICS® Bundle project and you can define one or more policies in a CICS Bundle project. By packaging your policies in this way, you can deploy
your policies as a single entity to CICS, making it easier to
update and manage the policies in CICS.
Before you begin
To create and deploy a policy, you must have an existing CICS bundle project. For more information, see
Creating a CICS bundle project.
About this task
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 one or more policies
can apply to a CICS system or an individual user task.
Note: 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.
- Levels of scope for task rules
- Policies that define task rules can be deployed at the following levels of scope:
- Region level
- Rules apply to all user tasks running in the specified region.
- Platform level
- Rules apply to all user tasks for any CICS application
that is deployed on the specified platform.
- Application level
- Rules apply only to the users tasks for the specified application and not to other user tasks
that might run on the same platform.
For policies that define task rules that are deployed at the region or application level, you
can further restrict their scope to specific user tasks, by defining policy scopes. For more
information, see Defining policy scopes.
- Levels of scope for system rules
- Policies that define system rules can be deployed to the following levels of scope:
- Region level
- Rules apply to all tasks (system or user) in the specified region that make changes to system or
resource state.
- Platform level
- Rules apply to all tasks (system or user) in all regions of the specified platform that make
changes to system or resource state.
Policies that define system rules cannot be deployed at the application level.
Procedure
To create a policy in a CICS bundle project:
- Select the parent folder of a CICS bundle project from the Project Explorer view.
- Open the New Project wizard in either of the following ways:
- On the main menu for the workbench, click . Then expand the CICS Resources folder, select
Policy Definition, and click Next.
- Right-click the CICS bundle project, and then click .
- Create a policy that contains the policy rule:
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 the rule type you want to create.
- In the File Name field, enter the policy file name, for example
policy_rules.
- Click Finish. This opens the policy definition editor. For more information, see The policy definition editor.
- Optional: In the General Information section on the Overview tab, you can enter a
description in the Description field, a user tag in the User
Tag field, or both. A user tag is 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 policy
author, that is, anything that helps associate an event with the policy that requests the
event.
- Create a rule in the policy definition editor:
- On the Overview tab, click New.
- In the New Rule dialog, enter a rule name, select a rule type from the
list, and optionally enter a description for the rule.
- Click OK. This opens the Rules tab.
- 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 conditions.
Note: The earliest CICS release that supports a specific rule is displayed in the lower-right corner
of the Conditions section. Ensure that this is equal to or less than the CICS release to which this
policy will be deployed. For more information, see
Policy schema versioning.
- Select one action to take when the defined conditions are met:
- 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. Specify 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.
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 will be used.
- 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:
- For static data names:
- 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.
- For static data values:
-
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.
- For task rules only: Abend task. If you want CICS to terminate a running task when the specified threshold is
crossed, select the Abend task with abend code option. 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.
- Optional: Add more rules by following Steps 5 through 7.
- To save the policy, click .
To deploy a policy in the CICS bundle project:
Policies that define system rules can be deployed either to a stand-alone CICS region or with a CICS platform, but
they cannot be deployed with a CICS application. Policies
that define task rules can be deployed to a stand-alone CICS
region, with a CICS platform, or with a CICS application.
- Deploy the policy by using one of the following methods:
- To deploy the policy to a stand-alone CICS region:
- Export the CICS bundle project that defines the policy to
zFS. For more information about deploying CICS bundles to
zFS, see Deploying a CICS bundle.
- Define, install, and enable a CICS BUNDLE resource for
the CICS bundle. You can create and install a BUNDLE
definition by opening the Bundle Definitions view. For more information about bundle resources, see
BUNDLE resources in the CICS TS V5.4.0 product documentation.
- To deploy the policy to a platform, add the CICS bundle that contains the policy to a
platform:
- If the platform is not yet deployed, add the CICS bundle
that defines the policy to the platform definition as follows, so that it is deployed during the
platform deployment:
- Locate the platform bundle project in your workspace, expand the META-INF folder for the bundle
project, and double-click the bundles.xml file or the
platform.xml file. The platform descriptor editor opens. For more instructions
on using the platform descriptor editor, see The platform descriptor editor.
- Click Add in the CICS Bundles section on the
Overview tab.
- From the list of CICS bundles that are available in your
workspace, select the CICS bundle that defines the
policy.
- If the platform is active, follow these steps:
- Export the CICS bundle project to the platform home
directory on zFS. For more information, see Deploying a CICS bundle.
- Add the CICS bundle that defines the policy to the active platform, by using the ADDBUNDLE
operation dialog of the Cloud Explorer view. For more information, see Adding a CICS bundle to a platform.
- To deploy the policy with a CICS application, add the
CICS bundle that defines the policy to the application, as follows:
- Locate the application bundle project in your workspace, expand the META-INF folder for the
bundle project, and double-click the application.xml file or the
bundles.xml file. The application descriptor editor opens. For more
instructions on using the application descriptor editor, see The application descriptor editor.
- Click Add in the CICS Bundles section on the
Overview tab.
- From the list of CICS bundles that are available in your
workspace, select the CICS bundle that defines the
policy.
Results
A policy is created in the CICS bundle project and
deployed.