System events

A system event is a type of business event that results from system activity and contains system data. System events can include resource state changes, thresholds being crossed, or unusual system states or actions. Use system events to help you understand changes in the state of your system resources or system health.

Note:

CICS® TS 5.4 introduces support for system rules in CICS policies. Policy system rules provide equivalent or enhanced capability to system events and supersede system events. For more information, see Policy system rules.

Support for system events is deprecated; no further enhancements will be delivered in any future CICS releases. If you use system events, you can continue to do so in this release, and the following information provides details about the supported system events. However, support for system events might be withdrawn in a future release of CICS, so consider migrating to use policy system rules at the earliest opportunity.

You can be alerted to certain CICS system conditions by capturing events for those conditions. Receiving a notification for any changes to the state of system resources avoids the need to poll for changes after they happen; it also means that you can quickly respond to these system events.

Event processing supports the following system events:

DB2CONN connection status
FILE enable or disable status
FILE open or close status
MESSAGE
TASK threshold
TRANCLASS TASK threshold
Unhandled transaction abend

Capture points

The following table shows the capture points that are supported for system events.

Table 1. System event capture points
Capture point	Primary predicate	Filter Predicate Context	Filter Predicate Event Option	Capture Data Event Option	Description
DB2 CONNECTION STATUS	None	Transaction ID User ID	FROM_CONNECTST TO_CONNECTST	DB2ID DB2GROUPID DB2RELEASE FROM_CONNECTST TO_CONNECTST	You can capture an event whenever a DB2CONN connection status changes.¹
FILE ENABLE STATUS	FILE	Transaction ID User ID	FILE FROM_ENABLESTATUS TO_ENABLESTATUS OPENSTATUS	FILE DSNAME FROM_ENABLESTATUS TO_ENABLESTATUS OPENSTATUS	You can capture an event whenever a file ENABLESTATUS changes.¹
FILE OPEN STATUS	FILE	Transaction ID User ID	FILE FROM_OPENSTATUS TO_OPENSTATUS	FILE DSNAME FROM_OPENSTATUS TO_OPENSTATUS ENABLESTATUS	You can capture an event whenever a file OPENSTATUS changes.¹
MESSAGE	MESSAGE_ID	Transaction ID User ID	MESSAGE_ID INSERT1 to INSERT30²	MESSAGE_ID INSERT1 to INSERT30 MESSAGE_TEXT	You can capture an event whenever CICS emits a DFHxxnnnn ³ message or CICSPlex® SM emits a EYUxxnnnn message.
TASK THRESHOLD	None	None	PERCENT_MAXTASKS	FROM_TASKS TO_TASKS MAXTASKS PERCENT_MAXTASKS	You can capture an event whenever a task threshold is crossed. The threshold is chosen from predefined lists.⁶
TRANCLASS TASK THRESHOLD	TRANCLASS	None	TRANCLASS PERCENT_MAXACTIVE	TRANCLASS FROM_ACTIVE TO_ACTIVE MAXACTIVE PERCENT_MAXACTIVE	You can capture an event whenever a TRANCLASS task threshold is crossed. The threshold is chosen from predefined lists.⁶
TRANSACTION ABEND (Unhandled)	TRANSACTION	User ID	TRANSACTION ABCODE	TRANSACTION ABCODE	You can capture an event whenever a transaction encounters any unhandled abend.

Notes:

The change can occur either through explicit operator actions, EXEC CICS SET commands, or implicitly as a result of CICS internal processing.
You can choose up to 10 message insert filters. Ensure that you use an available insert, because the CICS event binding editor does not prevent you from defining a filter on an unavailable insert and does not flag the error. Instead, the result is a runtime exception trace, the predicate evaluates as false, and no event is emitted. For example, message DFHFC0200 has 7 inserts. If you define a filter on INSERT 8 through 30, no event is emitted. Message inserts are shown in the individual message topics (see CICS messages).
You cannot event enable any of the following messages:
- Any CICS initialization messages issued before event processing starts. Event processing is started just before phase 2 initialization PLT programs are run.
- Any CICS termination messages issued after event processing stops. Event processing is stopped after all shutdown PLT programs have run.
- Any messages sent to a CICS user, for example, messages issued by CICS supplied transactions such as CEMT and CEDA.
- Any messages issued by the EC or EP components, that is, all DFHECnnnn and DFHEPnnnn messages.
A MESSAGE system event is emitted regardless of whether or not a message is suppressed by either an XMEOUT global user exit program or the system initialization parameter MSGLVL=0.
No transaction abend system events are emitted for any transaction abends originating in any task running an event processing adapter program.
Task threshold values are chosen from predefined lists as follows:
- 60%, 70%, 80%, 90%, or 100% when the 'Goes Higher Than" operator is used.
- 50%, 60%, 70%, 80%, or 90%, when the 'Goes Lower Than" operator is used.

For more information about the capture points you can select, see Capture Point tab in the CICS Explorer product documentation and Information Sources tab in the CICS Explorer product documentation.

Task thresholds

You can use task threshold events to monitor both system and transaction class definition (TRANCLASS) task load by specifying that an event is to be emitted when the active task count crosses a threshold value.

Task thresholds are expressed as a percentage of the MXT system initialization parameter or the MAXACTIVE value of the TRANCLASS resource. For performance reasons, they are predefined. The possible task threshold values you can select are:

60%, 70%, 80%, 90%, and 100% when the Goes Higher Than operator is used.
50%, 60%, 70%, 80%, and 90% when the Goes Lower Than operator is used.

You can filter on:

A threshold to indicate how close the system is to the MXT value. You can define more than one event to indicate various degrees of health as the threshold gets closer to the limit you set for the MXT system initialization parameter.
A TRANCLASS resource and a threshold to indicate how close the TRANCLASS resource is to its MAXACTIVE value. You can define more than one event to indicate various degrees of health as the number of attached tasks gets closer to the MAXACTIVE limit you set for the TRANCLASS resource.

To avoid large numbers of events being emitted, events are emitted only when the number of active tasks crosses a new threshold boundary. For example, events are emitted during transaction attach when the number of active tasks exceeds a threshold and the previous goes higher than event was when the next lowest threshold was crossed. Events are emitted during transaction detach when the number of active tasks falls below a threshold and previously goes lower than event was when the next highest threshold was crossed. Figure 1 shows such examples.

An example line graph of the values of MAXTASKS over elapsed time. Points on the graph indicate where the value of MAXTASKS crosses a threshold boundary and creates an event emission opportunity. — Figure 1. Event emission opportunities

1 No events are emitted when the number of active tasks exceeds the 50% threshold. Events are emitted during transaction attach only when the number of active tasks crosses one of the 60%, 70%, 80%, 90%, or 100% thresholds. No events are emitted when the number of active tasks falls below the 50% threshold, because the number of active tasks has not been above the 60% threshold since the last goes below 50% event.

2 An event is emitted because the number of active tasks exceeds the 60% threshold for the first time since the previous goes above 50% event.

3 An event is emitted because the number of active tasks exceeds the 70% threshold for the first time since the previous goes above 60% event.

4 No events are emitted when the number of active tasks oscillates around the 70% threshold because the number of active tasks does not cross a threshold boundary to either exceed the 80% threshold or drop below the 60% threshold.

5 An event is emitted because the number of active tasks drops below the 60% threshold for the first time since the previous goes below 70% event.

6 A series of events are emitted when the number of active tasks progressively exceeds the 60%, 70%, 80%, 90%, and 100% thresholds.

Considerations:

Event emission is not enabled for a TRANCLASS when its MAXACTIVE value is set to less than 10.

TRANCLASS threshold events are not emitted for those transactions defined as not having a TRANCLASS, that is, those defined with TRANCLASS(DFHTCL00).

If you require an event to be emitted when the system or TRANCLASS crosses the 100% threshold, and you need that event emitted as quickly as possible, consider the dispatch characteristics of the EP adapter.

For the system 100% threshold, ensure that the EP adapter will be linked to. It is possible that an attached EP adapter task would be queued until the MAXTASK condition is cleared.
For the TRANCLASS 100% threshold, ensure that the TRANCLASS that causes the event is not used for the EP adapter.