Application events

An application event is a type of business event that results from application program activity and contains application data.

You can specify that an event is emitted when your application issues any of the event enabled EXEC CICS® API commands or when an application program is initiated. The event enabled EXEC CICS commands are shown in Table 1. A limited set of CICS modules have also been event enabled so that you can capture events from, for example: file and temporary storage commands coming from Atom support; EXEC CICS LINK commands issued by the CICS-MQ bridge programs; commands from the CICS samples and the CECI transaction.

The capture specification defines the criteria for event emission by using filters, such as the transaction ID, program name, or EXEC CICS command option value. This capture specification can be further refined by filtering on the application data associated with the command. For example, you can specify that the COMMAREA field containing an order value must be greater than 10,000. The capture specification also defines the location of the data to be captured.

The location of the event in the application logic depends on how it is specified. If a CICS application contains two instances of the same EXEC CICS API command, and the filter specification does not distinguish between the two commands, an event is emitted when both commands are issued. If the same EXEC CICS API command occurs in two applications and there is no filter on the transaction ID or program name, an event is emitted when both applications run.

Capture points

You can capture events at program initiation (PGMINIT) and the following EXEC CICS API commands. Capture points that can be specified are shown in the following table:

Table 1. Application event capture points
Capture Point	Primary Predicate	Filter Predicate		Capture Data
Capture Point	Primary Predicate	Context	Event Option	Event option	Application Data
CONVERSE	None	Transaction Id Current Program User ID Response Code EIBAID EIBPOSN	None	FROM INTO-SET	None
DELETE FILE	FILE	Transaction Id Current Program User ID Response Code	FILE	FILE	RIDFLD
DELETEQ TD	QUEUE	Transaction Id Current Program User ID Response Code	QUEUE	QUEUE	None
DELETEQ TS	QNAME	Transaction Id Current Program User ID Response Code	QNAME	QNAME	None
INVOKE SERVICE	SERVICE	Transaction Id Current Program User ID Response Code	SERVICE OPERATION URI CHANNEL URIMAP	SERVICE OPERATION URI CHANNEL URIMAP	CHANNEL SCOPE
LINK PROGRAM	PROGRAM	Transaction Id Current Program User ID Response Code	PROGRAM CHANNEL	PROGRAM CHANNEL	COMMAREA CHANNEL
PROGRAM INIT	PROGRAM	Transaction Id User ID Response Code	PROGRAM CHANNEL	None	COMMAREA CHANNEL
PUT CONTAINER ^{#dfhep_applicationevents__PUT64-CONTAINER-note}	CONTAINER	Transaction Id Current Program User ID Response Code	CONTAINER CHANNEL	CONTAINER CHANNEL	FROM
PUT64 CONTAINER ^{#dfhep_applicationevents__PUT64-CONTAINER-note}	CONTAINER	Transaction Id Current Program User ID Response Code	CONTAINER CHANNEL	CONTAINER CHANNEL	FROM
READ	FILE	Transaction Id Current Program User ID Response Code	FILE UPDATE	FILE	RIDFLD INTO-SET
READNEXT	FILE	Transaction Id Current Program User ID Response Code	FILE UPDATE	FILE	RIDFLD INTO-SET
READPREV	FILE	Transaction Id Current Program User ID Response Code	FILE UPDATE	FILE	RIDFLD INTO-SET
READQ TD	QUEUE	Transaction Id Current Program User ID Response Code	QUEUE	QUEUE	INTO-SET
READQ TS	QNAME	Transaction Id Current Program User ID Response Code	QNAME	QNAME	INTO-SET
RECEIVE	None	Transaction Id Current Program User ID Response Code EIBAID EIBPOSN	NONE	NONE	INTO-SET
RECEIVE MAP	MAP	Transaction Id Current Program User ID Response Code EIBAID EIBPOSN	MAP MAPSET	MAP MAPSET	INTO-SET
RETRIEVE	None	Transaction Id Current Program User ID Response Code	NONE	NONE	INTO-SET
RETURN	None	Transaction Id Current Program User ID Response Code	TRANSID CHANNEL	TRANSID CHANNEL	COMMAREA CHANNEL
REWRITE	FILE	Transaction Id Current Program User ID Response Code	FILE	FILE	FROM
SEND	None	Transaction Id Current Program User ID Response Code	NONE	NONE	FROM
SEND MAP	MAP	Transaction Id Current Program User ID Response Code	MAP MAPSET ALARM	MAP MAPSET	FROM
SEND TEXT	None	Transaction Id Current Program User ID Response Code	ALARM	NONE	FROM
SIGNAL EVENT ^{#dfhep_applicationevents__SIGNAL-EVENT-note}	EVENT	Transaction Id Current Program User ID Response Code	EVENT FROMCHANNEL	EVENT FROMCHANNEL	FROM FROMCHANNEL
START	TRANSID	Transaction Id Current Program User ID Response Code	TRANSID CHANNEL	TRANSID CHANNEL	FROM CHANNEL
WEB READ `FORMFIELD` HTTPHEADER QUERYPARM	None	Transaction Id Current Program User ID Response Code	NONE	NONE	FORMFIELD INTO-SET VALUE
WEB READNEXT `FORMFIELD` HTTPHEADER QUERYPARM	None	Transaction Id Current Program User ID Response Code	NONE	NONE	FORMFIELD VALUE
WRITE FILE	FILE	Transaction Id Current Program User ID Response Code	FILE	FILE	RIDFLD FROM
WRITE OPERATOR	None	Transaction Id Current Program User ID Response Code	NONE	NONE	TEXT ³
WRITEQ TD	QUEUE	Transaction Id Current Program User ID Response Code	QUEUE	QUEUE	FROM
WRITEQ TS	QNAME	Transaction Id Current Program User ID Response Code	QNAME	QNAME	FROM
XCTL	PROGRAM	Transaction Id Current Program User ID Response Code	PROGRAM CHANNEL	PROGRAM CHANNEL	COMMAREA CHANNEL

All capture points define the same context capture items, PROGRAM, TRANSID, and USERID.

Note:

For the JCICS com.ibm.cics.server.Container class, the two put methods and the putString method can be captured with the PUT64 CONTAINER capture point.
The sole purpose of the SIGNAL EVENT API command is to provide data for an event. An event is only emitted if there is a matching capture specification enabled in the CICS system.
A length of 0 when specifying application data in the information sources tab means capture up to the end of the data area or container. This value is useful when you want to emit the contents of an EXEC CICS WRITE OPERATOR. For more information, see Information Sources tab in the CICS Explorer product documentation.

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.