- What actions are supported by CICS system rules
- How to define your own action, by using a CICS transaction
- Examples of code and definitions
You can control the behavior of CICS during run time by defining policies. Policy rules – and these can be either system rules or task rules – tell CICS what action to take when a condition is met. System rules define an automated action to be performed when something of interest happens in a CICS system, such as a CICS resource changing state or a system threshold being crossed. CICS defines a set of actions that can be performed when a system rule is triggered. You can easily extend this set, just by coding a CICS transaction. This article shows you how.
This article focuses on writing customized actions for system rules, but you can use the same technique to write customized actions for task rules too.
Introducing system rules
System rules were introduced in CICS TS V5.4 in July 2018 and subsequently back-ported in October 2017 to CICS TS V5.1, V5.2, and V5.3 by APAR PI83667. System rules replace the system event support that was introduced in CICS TS V4.2 and deprecated in CICS TS V5.4. Initially, CICS provided a set of system rules that matched the support from system events and included rules to take an automated action when any of the following things happen:
- The state of a Db2 connection changes.
- The ENABLE or OPEN state of a file changes.
- A CICS (DFHxxxx) or CPSM (EYUxxxx) message is issued.
- The number of tasks in a TRANCLASS (transaction class) resource goes above or below a specific threshold.
- The number of active tasks in a TRANCLASS resource goes above or below a specific threshold.
- An unhandled transaction abend occurs.
- The number of active tasks in a CICS system goes above or below a specific threshold.
In July 2018, CICS TS V5.4 gained support for more system rules with APAR PI92806 in July 2018. This APAR added new system rules to take an automated action when:
- The ENABLE or AVAILABLE state of a CICS BUNDLE resource changes.
- The status of a MRO or IPIC CONNECTION resource changes.
- The ENABLE status of a PROGRAM resource changes.
All of these system rules supported just two automated actions:
- Issue a message.
- Emit a CICS event.
CICS TS V5.5 added another system rule. This system rule takes automated action when an EXEC CICS START request would cause the number of AIDs in a CICS system to exceed a given threshold. This new rule also supports a new action, in addition to the message and event actions that are supported by all system rules. You can have CICS reject the EXEC CICS START request with an INVREQ response so that application programmers can handle the condition. If the INVREQ response is not handled, the task abends with an AEIP abend.
This table shows which system rules are supported by each CICS TS V5 releases:
|Rule Type||CICS TS V5.1||CICS TS V5.2||CICS TS V5.3||CICS TS V5.4||CICS TS V5.5|
|BUNDLE AVAILABLE status||✔ with APAR PI92806||✔|
|BUNDLE ENABLE status||✔ with APAR PI92806||✔|
|Db2 connection status||✔ with APAR PI83667||✔ with APAR PI83667||✔ with APAR PI83667||✔||✔|
|File OPEN status||✔ with APAR PI83667||✔ with APAR PI83667||✔ with APAR PI83667||✔||✔|
|File ENABLE status||✔ with APAR PI83667||✔ with APAR PI83667||✔ with APAR PI83667||✔||✔|
|IPIC CONNECTION status||✔ with APAR PI92806||✔|
|Message||✔ with APAR PI83667||✔ with APAR PI83667||✔ with APAR PI83667||✔||✔|
|MRO CONNECTION status||✔ with APAR PI92806||✔|
|PROGRAM ENABLE status||✔ with APAR PI92806||✔|
|TRANCLASS tasks||✔ with APAR PI83667||✔ with APAR PI83667||✔ with APAR PI83667||✔||✔|
|Transaction abend||✔ with APAR PI83667||✔ with APAR PI83667||✔ with APAR PI83667||✔||✔|
|User tasks||✔ with APAR PI83667||✔ with APAR PI83667||✔ with APAR PI83667||✔||✔|
What about support for the old system events?
If you currently use system events, you can continue to do so even in CICS TS V5.5. However, no further enhancements to system events will be delivered in any future CICS release and support for system events might be withdrawn in a future release of CICS, so you should consider migrating to use policy system rules at the earliest opportunity.
Defining your own actions
As I’ve mentioned, all system rules support issuing a message or emitting an event. While reporting that something unusual has happened might be enough in many cases, what if you want to take a more decisive action? For example, what if you want to:
- Enable or disable a resource
- Acquire or release a connection
- Adjust the setting of the z/OS WLM health service
- Send an email alert
- Or …
It might not be immediately obvious how you can get to any of these actions through system rules but all of them are, in fact, possible. The trick is to exploit the power of the policy event action and involves just a little coding on your part. I’ll show you an example for a system rule, but you can use the same technique to write customized actions for task rules too.
How the CICS policy event action works
When you define a policy rule and you select the event action, you also have to supply the name of a CICS event processing (EP) adapter (or an EP adapter set, if you want the event to be processed by multiple EP adapters). CICS EP adapters are programs that format, then emit events from a CICS system. EP adapters format event data into a suitable output format and route the event, using a transport mechanism that makes it available to potential event consumers. See “Event processing adapters” in the CICS TS documentation for a description of all the supported transport mechanisms.
One of the EP adapters is the Transaction Start EP adapter. This starts a new CICS transaction when an event occurs – that is, when a system rules triggers. This is the mechanism that you can use to perform a customized action for a system rule, by coding a simple CICS transaction.
When such a transaction starts, it’s going to need some information about the system rule that was triggered. This information is contained in the data that was captured when the rule triggered and is made available to the started transaction in a series of CICS containers. If you defined system events, you had to choose which data to capture from a list of available data items for each event type. For example, for a FILE OPEN event, you chose from a list that includes the file name, the dataset name, the to- and from- open state, the file enable state, the transaction ID of the task that changed the state and the user ID under which that task was running.
System rules greatly simplify this configuration. You don’t have to choose which data to capture. Instead, all the data that relates to a given rule type is captured by CICS and it’s left to the event consumer to choose what it needs and to ignore the rest. Although this can mean that more data is captured and emitted than is actually required by the consumer of the event, most policy events are only a few hundred bytes. The simpler configuration of a policy event, compared to a system event, more than makes up for the few extra bytes being emitted. For details on the data emitted for each system rule type, refer to “Data captured for a policy event” in the CICS TS V5.5 Knowledge Center.
An example of how to set up a customized action
To show you how to exploit the system rule event action to perform a customized action, I’ll use the following simple example. Let’s assume that you want an IPIC connection to be automatically re-acquired if it is released. The rest of this article shows how you can do this by using the IPIC connection system rule with the event action, together with a simple CICS transaction.
Here’s what you’re going to need:
- A program to issue the required action: in our example, the CEMT SET IPCONN() ACQUIRED command. We call ours RACQIPIC.
- A CICS TRANSACTION for the Transaction Start EP adapter to start when the IPIC system rule triggers. We call this RAIC and configure it to name the program RACQIPIC.
- A CICS EP adapter with adapter type of “Transaction Start” which names RAIC as the transaction to start. We call this START_RAIC.
- A CICS policy defining a IPIC connection system rule, which defines the event action and names our EP adapter START_RAIC.
The rest of this article will show you how to define each of these artifacts.
1. Create a program to issue the required action
RACQIPIC is a simple program that needs to do four things:
- Check that CICS is active.
- Get the name of the IPCONN connection to be re-acquired.
- Issue the necessary EXEC CICS SET IPCONN() ACQUIRED command to re-acquire the IPCONN.
- Optionally, write an audit message to log that the re-acquire has been attempted.
The program can be written in C, COBOL, HLASM or PL/I. The program needs to issue a few EXEC CICS commands as shown below. To keep this example code simple, I haven’t shown any checking of the responses to the EXEC CICS commands but you’ll want to do that in your own code:
- As we only want to attempt the re-acquire if CICS is active and we certainly don’t want to do so if CICS has started to shutdown, first we inquire to see if CICS is active. This requires the following INQUIRE SYSTEM command:
EXEC CICS INQUIRE SYSTEM CICSSTATUS(cics-status) END-EXEC. if cics-status equal dfhvalue(active) then
- The name of the IPCONN that has been released is in the event data that is passed to a task that was started by a Transaction Start EP adapter in a series of containers. So, first we need to determine which container contains the information we need. You can find a list of all the containers that are created for a IPIC connection system rule event in Table 9 of “Data captured for a policy event” in the CICS TS V5.5 Knowledge Center. You can see from this that the IPCONN name is in the container “DFHEP.DATA.00017“. You can retrieve the contents of this container with a GET CONTAINER command as follows:
EXEC CICS GET CONTAINER('DFHEP.DATA.00017') SET(address of ipconn-name) FLENGTH(ipconn-length) END-EXEC.
- All that’s left to be done is to re-acquire the IPCONN. This requires the following SET IPCONN command:
EXEC CICS SET IPCONN(ipconn-name) ACQUIRED END-EXEC.
- Optionally, you might want to write an audit message to record the fact that the re-acquire has been performed. If the re-acquire fails, you might want to report that and/or retry the action after waiting for a while.
That’s all that’s needed in the RACQIPIC program. The complete program listing for the basic version of the required program is listed below.
Process cics('cobol3,sp') Process arith(extend) trunc(bin) list map xref rent Identification Division. Program-id. RACQIPIC. Environment division. Data division. ****************************************************************** Working-storage section. ****************************************************************** 01 Program-working-storage. 03 ipconn-length pic s9(8) comp. 03 Msg pic x(60). 03 Resp pic s9(8) comp. 03 Resp2 pic s9(8) comp. 03 cics-status pic s9(8) comp. ****************************************************************** Linkage section. ****************************************************************** 01 ipconn-name pic x(8). * Procedure division. ****************************************************************** Main-program section. ****************************************************************** EXEC CICS INQUIRE SYSTEM CICSSTATUS(cics-status) END-EXEC. * 1) If CICS is not active return immediately if cics-status NOT EQUAL dfhvalue(active) then EXEC CICS RETURN END-EXEC. EXEC CICS GET CONTAINER('DFHEP.DATA.00017') SET(ADDRESS OF ipconn-name) FLENGTH(ipconn-length) END-EXEC. * 2) Set IPCONN ACQUIRED EXEC CICS SET IPCONN(ipconn-name) ACQUIRED END-EXEC. * 3) Write audit message to TSQ move spaces to Msg string '***IPCONN ''' delimited by size ipconn-name delimited by spaces ''' has been re-acquired by RACQIPIC.' delimited by size into Msg. EXEC CICS WRITEQ TS QUEUE('RACQIPIC') FROM(Msg) LENGTH(60) END-EXEC. * * Return to caller EXEC CICS RETURN END-EXEC. * Main-program-exit. exit.
2. Define the policy
With the RACQIPIC program written, we can now start defining the policy and its related artifacts. First, we need to create a CICS bundle project to contain all the policy and EP adapter resource definitions. Please refer to “Creating a CICS bundle project” in the CICS Explorer V5.5 Knowledge Center for details on how to do this. For this article, I created a CICS bundle project called “reacquire_ipic_connections”.
Next we need to create the EP adapter resource definition. To do this:
- Right-click on the CICS bundle project that you just created and click New > Event Processing Adapter to open the New EP adapter wizard.
- In the File name field, enter “START_RAIC” as the name for the EP adapter and click Finish.
- In the EP Adapter Configuration editor, configure the adapter to start the RAIC transaction.
- Select the “Transaction Start” adapter from the list of Adapter types.
- In the Transaction ID field, enter the name of the transaction “RAIC“.
- In the EP Adapter Configuration editor, configure the adapter to start the RAIC transaction.
- To save the EP adapter definition, click File > Save.
Next we need to create the IPIC connection system rule. To do this:
- Right-click on the CICS bundle project and click New > Policy to open the Policy definition wizard.
- In the File name field, enter a name for the policy. This can be any name up to 64 characters. Let’s call it reacquire_ipic_connection and click Finish.
This opens up the Policy Definition editor. We now need to add a new rule to the policy:
- Click on the New button to add a rule.
- Enter a name for the rule in the Name field. Again, this is any name up to 64 characters. Let’s call our rule “reacquire_ipic_connection_on_release“.
- Click on IPIC connection status in the list of System rules.
- Click on the OK to open up the “Rules” tab of the Policy Definition editor.
- As it stands, this rule will trigger on ALL changes to the status of ALL IPIC connections. However, we only want the RAIC transaction to run when the IPCONN is released. So, using the drop-down list, choose “To connection status” and “RELEASED“. To restrict the rule to one particular IPCONN, we also enter “IPCONN1A” in the Connection Name field. We leave the operator to default to “equals” as that’s what we want, although we could pick “does not equal“, “starts with” or “does not start with” if we wish.
- Optionally, you can restrict the rule further by defining a user ID predicate. For example, if you do not want the rule to trigger if your senior system programmer called BILL releases the IPCONN, then you can do so by selecting the “does not equal” operator and entering BILL in the User ID field.
- By default, the rule action is “Issue a message“. Because we want to drive the RAIC transaction, we need to change this and select the “Emit an event” radio button. We then need to enter the EP Adapter name. If you know the name, you can just enter it in the text box to the right but to avoid getting it wrong (EP adapater names are case-sensitive), we’ll use the Choose button and pick “START_RAIC” from the list of EP adapters that are defined in the workspace.
- That completes the definition of the policy. To save the policy definition, click File > Save.
3. Define the other resources
In addition to the EP adapter and policy definitions, which must be defined in a CICS bundle project, you will also need to define the RAIC transaction, and, if you don’t use program auto-install, the RACQIPIC program. You could define these using RDO or BAS but, to keep all the definitions together in one place, consider adding these resource definitions to the same CICS bundle as the policy and EP adapter. See “Adding resources to a CICS bundle project” in the CICS Explorer V5.5 Knowledge Center for details of how to do this.
Deploy the policy
We need to deploy the policy CICS bundle project that we created above to the CICS regions where it’s needed and to create the resources from the bundle in the CICS region. You deploy a CICS bundle by exporting it directly to a z/OS® UNIX System Services (z/OS UNIX) file system from CICS Explorer, then install a BUNDLE resource to locate the bundle in zFS and dynamically create the resources defined in the bundle in the CICS region. See “Deploying a CICS bundle” in the CICS Explorer V5.5 Knowledge Center for details of how to do this.
After the BUNDLE resource is installed and enabled, as soon as the IPIC connection “IPCONN1A” is released, the policy will trigger and the RAIC transaction will be invoked to re-acquire the IPCONN. To verify the policy, use CEMT to set the IPCONN “IPCONN1A” released – but chances are that the policy will trigger so quickly that you won’t see the IPCONN change to the released state before the RAIC transaction re-acquires it.
CICS provides policies to allow you to set rules for the way that CICS behaves in response to defined system or task conditions. Policy system rules were introduced in CICS TS V5.4 and support was made available to previous releases of V5 through APARs. Further support was added in the latest release, CICS TS V5.5, and users of the now-deprecated system events are encouraged to move to system rules.
CICS supports a few actions for the system conditions but, with just a bit of coding, you can use one of these – the event action – to define your own actions. The same technique works for task rules as well as system rules. This article showed you how.
Find out more
For more information on CICS policies please see “CICS policies” in the CICS TS V5.5 documentation in IBM Knowledge Center.