Capturing application and system events
This chapter describes how CICS supports event processing and introduces the CICS Explorer editors that are used to define and deploy events.
The event binding editor is detailed to create an event specification, capture points, filters, information sources, and finally determines which EP adapter is to emit the event.
The CICS Explorer provides a set of example event bindings that are based on the CICS Catalog sample. One of these event bindings is used for illustration.
Finally, we describe how to use the CICS Explorer to deploy the event binding within a CICS bundle onto zFS.
This chapter includes the following topics:
2.1 How CICS supports event processing
CICS provides a flexible solution to capture application and system events, with options for filtering, enriching, and formatting the event, and emitting the event to one or more consumers. The events are typically used by event processing engines, business dashboards, monitoring tools, or CICS transactions, as shown in Figure 2-1.
Figure 2-1 CICS and event processing overview
The CICS Explorer is used to create required resources and deploy them to CICS.
At a minimum, an event specification and an EP adapter specification are required. The event specification describes the information to be emitted, the point to capture the event, and the filters that are required to precisely capture only events of interest. The EP adapter specification describes which EP adapter should emit the event, how the data should be formatted, and advanced options such as priority and transactionally. If you require one event to be emitted to multiple EP adapters, you can also specify an EP adapter set specification.
It is recommended to create the event specification by using the CICS Explorer event binding editor and the EP adapter specifications by using the EP adapter editor. These specifications are created within a CICS bundle project, which can be exported as a CICS bundle onto the z/OS UNIX File System (zFS) and installed in CICS by using a CICS BUNDLE resource.
When CICS applications are run, many potential capture points occur. Possible capture points include when a program is initialized and when it runs one of the event-enabled CICS commands, such as REWRITE, LINK, and RECEIVE. These are referred to as application events. Applications can also declare capture points by using the SIGNAL EVENT command.
CICS also provides capture points for system activity, such as when the state of a DB2 connection changes, and when a workload reaches a percentage of a transaction class. These are referred to as system events.
For each EXEC CICS API that can be included as a capture point, CICS evaluates the event specifications that are installed and enabled. If there is a match, CICS captures the required information and enriches it with information about the application and system, and queues it for later processing. The application then continues without being aware the event was even captured.
Application events can be marked as transactional, in which case they are kept on the queue of captured events until the transaction within which the event was captured is successfully committed. Conversely, if the transaction is rolled back, the event is removed and not emitted.
A separate process takes events from the queue according to whether they have a normal or high priority order and routes them to the adapter that is specified in the event EP adapter specification. Each EP adapter formats the information to be included in the event (for example, into XML), and emits the event. This is referred to as asynchronous event processing.
CICS also supports synchronous event processing for application events where the EP adapter is called in-line when the event is captured from the application. This is useful if you want the application to be aware of errors when emitting events.
After an event is emitted, the event consumer (such as IBM Operation Decision Manager or IBM Business Monitor) typically update a dashboard or correlate it with other events and take some business action.
2.2 CICS Explorer
The CICS Explorer provides the following features to support event processing:
•A set of the following resource wizards and editors:
– CICS Bundle Project
– CICS Event Binding
– CICS Event Processing Adapter
– CICS Event Processing Adapter Set
– Policy Definition
•A wizard to export CICS bundle projects to zFS.
•A facility to search event bindings in CICS bundle projects within the local workspace, or those installed into CICS systems.
•A set of the following CICS Operations views, including:
– Event Processing
– Event Bindings
– EP Adapters
– EP Adapter Sets
– Bundles
– Bundle Parts
•CICS SM definition views to create and manage BUNDLE resources.
The latest version of the CICS Explorer can be downloaded and installed from this website:
2.2.1 CICS bundles
A CICS bundle is a collection of bundle parts, artifacts, references, and a manifest. Bundles can include version information and declare dependencies on other resources outside the bundle. Together, these make it easier to package, deploy, and manage applications, and enable CICS to identify problems and take corrective actions.
Complete the following steps to create a CICS bundle:
1. Start the CICS Explorer.
2. Switch to the Resource perspective by using the button as shown in Figure 2-2. Alternatively, select Window → Open Perspective → Other → Resource → OK.
Figure 2-2 CICS Explorer Resource Perspective
3. Create a CICS Bundle project by using the icon that is shown in Figure 2-3. Alternatively, select File → New Wizards → Other → CICS Resources → CICS Bundle Project.
Figure 2-3 Creating a CICS Bundle project
4. Enter the project name CatalogSample.
5. Select Finish.
You are now ready to create event bindings, EP adapters, EP adapter sets, and policies in the CICS bundle.
2.3 Event binding editor
An event binding is an XML document that defines one or more events to CICS and consists of the following components, as shown in Figure 2-4:
•Event specifications
•Capture specifications
•An EP adapter specification, or a reference to an externally defined EP adapter or an EP adapter set
Figure 2-4 Event binding components
Complete the following steps to create the catalog example event binding:
1. Select the CatalogSample project.
2. Select File → New Wizards → Other → Examples → CICS Catalog Manager REWRITE event, as shown in Figure 2-5 on page 29.
Figure 2-5 Generating a CICS Catalog Manager REWRITE event
3. Select Next.
4. Enter the file name CatalogSample, then select Finish.
The example is created and the event binding editor is started.
2.3.1 Event Binding tab
The event binding tab is divided into the following sections, as shown in Figure 2-6 on page 30:
•General Information: This section includes a description of the event in high-level business terms and a usertag to describe a version number.
•Event Specifications: This section lists the event specifications that are included in this event binding and provides controls to create, edit, remove, and copy specifications.
Figure 2-6 Catalog sample event binding
To display the Specifications tab, select the Catalog_stock_status_check event specification, then Edit Details.
2.3.2 Specifications tab
Each event specification includes one or more capture specifications and a set of the business information items to be emitted, as shown in Figure 2-7.
Figure 2-7 Event Specification components
Figure 2-8 on page 32 shows the event specification for the catalog sample, which is divided into the following sections:
•General: This section includes a description of the event specification.
•Emitted Business Information: This section lists the items to be included in the event, in the order they are to be included. Each item includes a data type, length, and numeric precision. As shown in Figure 2-8 on page 32, the emitted items include Program_name, Item_ref, Item_description, in_stock, and on_order.
•Capture Specifications: This section includes a button that is used to add new capture specifications. Alternatively, you can right-click the event specification in the tree on the left side and select Add a Capture Specification in the menu.
•Automatic Capture Specification: The use of automatic capture specifications is described in 2.4, “Explicit events by using SIGNAL EVENT” on page 42.
Figure 2-8 Catalog sample event specification
2.3.3 Capture Point tab
A capture specification defines the place in CICS where a particular event can be captured. It consists of a capture point, filter predicates, and information sources for the data to be captured from, as shown in Figure 2-9.
Figure 2-9 Components of a capture specification
If there is more than one place in the application where the event occurs, you can add a capture specification for each scenario. For example, a stock application can provide an entry point for orders to be placed via a web service and another for mobile applications. The capture points and data formats are likely to be different; therefore, two capture specifications are needed.
Capture point
A capture point is an event-enabled CICS command that is run by an application or a stage in CICS processing that was event-enabled. Table 2-1 lists application-related capture points.
Table 2-1 Application capture points
|
CONVERSE1
|
DELETE FILE
|
DELETEQ TD
|
DELETEQ TS
|
|
INVOKE SERVICE a
|
LINK PROGRAMa
|
PROGRAM INIT2
|
PUT CONTAINER
|
|
READ
|
READNEXT
|
READPREV
|
READQ TD
|
|
READQ TS
|
RECEIVE
|
RECEIVE MAP
|
RETRIEVE
|
|
RETURNb
|
REWRITE
|
SEND
|
SEND MAP
|
|
SEND TEXT
|
SIGNAL EVENT
|
START
|
WEB READ
|
|
WEB READNEXT
|
WRITE FILE
|
WRITE OPERATOR
|
WRITEQ TD
|
|
WRITEQ TS
|
XCTLb
|
|
|
1 CONVERSE, INVOKE SERVICE, and LINK PROGRAM capture points can be evaluated before or after the command runs.
2 PROGRAM INIT, RETURN, and XCTL capture points are evaluated before the CICS command runs.
2 For more information about cross-reference of capture points and their corresponding filter predicates and information items, see Appendix , “CICS application capture points” on page 240.
2 Capture points are evaluated after the CICS command runs, except where noted.
Table 2-2 System capture points
|
DB2 CONNECTION STATUS
|
FILE ENABLE STATUS
|
FILE OPEN STATUS
|
|
MESSAGE
|
TRANSACTION ABEND
|
TASK THRESHOLD
|
|
TRANSCLASS THRESHOLD
|
|
|
Select the Check_stock_status_on_rewrite capture point from the tree in Figure 2-8 on page 32 to see the catalog sample capture point, as shown in Figure 2-10 on page 35. The capture point for this sample event is REWRITE.
Figure 2-10 Catalog sample REWRITE capture point
2.3.4 Filtering tab
A predicate is an expression that is used as part of a filter, which consists of a data item, an operator such as Equals or Starts With, and optionally a value. A predicate is evaluated against data values on the capture point command or context data.
A filter is a set of predicates. If the predicates in the filter all evaluate to true, CICS captures the event. Conversely, if any predicates evaluate to false, CICS does not continue to evaluate the remaining predicates and the event is not captured.
Select the Filtering tab to show the catalog sample filter predicates, as shown in Figure 2-11.
Figure 2-11 Catalog sample filtering
The Filtering tab is divided into the following sections:
•Context: These predicates enable filtering that is based on transaction ID, current program, user ID, and the CICS command response code. The last of these are relevant only for capture points that are evaluated after the command has run.
•Event Options: These predicates are different for each capture point. For the REWRITE command capture point that is used here, the predicate is for the file name.
•Application Data: These predicates are different depending on the capture point. For the REWRITE command capture point, you can define multiple predicates for the data that is passed by the program on the FROM option when it issued the REWRITE command.
Getting the right combinations of predicates in the filter is important to ensure that the required events always are captured and, for efficiency, unwanted events are not captured.
|
Tip: If you need a combination of predicates that is too complex or not possible to express by using the editor, you must modify the application to perform those tests and when true issue the SIGNAL EVENT command. The SIGNAL EVENT capture point then can be used.
|
2.3.5 Information Sources tab
Complete the following steps if you want the event to contain specific data:
1. Add business information items to the event specification in the order you want them emitted.
2. Define an information source for each item of business information in the capture specifications for the event.
Figure 2-12 on page 38 shows information sources for the catalog sample.
Figure 2-12 Catalog sample information sources
3. In the Information Sources section, select the Item_description item, then click Edit. Figure 2-13 on page 39 shows the information source editor.
Figure 2-13 Editing an information source
The content of this editor is relevant to the capture point; in this case, the REWRITE application capture point.
The available data is divided into the following areas:
– Context
These are provided by CICS, and for application capture points including USERID, PROGRAM, and TRANSID.
– Event options
These are provided by the application on the application command.
– Application data
These are provided by the application on the application command options. You must provide extra information, such as the container name, type, offset, length, numeric precision, and code page.
If you have an application language structure that defines the necessary fields (such as a COBOL copy book), use the Select from imported language structure button to import and select the field.
– Static data
This is a way of providing data that is to be statically included each time the event is emitted, and is not based on the value of any data at run time.
This is provided in the Static Data field on the right side of the GUI.
|
Tip: If you need the event to contain information that is not supplied by an existing capture point, you must modify the application to issue the SIGNAL EVENT command and supply the data in the FROMCHANNEL or FROM options. The SIGNAL EVENT capture point can then be used.
|
4. Select OK.
5. Select the Adapter tab.
2.3.6 Adapter tab
The Adapter tab is used to specify which EP adapter or EP adapter set should be used to emit the event, or to define the EP adapter specification within the event binding.
The tab is divided into the following sections:
•Resource: This section is used to select if the event should be emitted by using the EP adapter specification that is defined in an EPADAPTER resource, an EPADAPTERSET resource, or defined in the Adapters section.
Use the Export Event Specification button to create two files that define the data in the emitted event: as an XML scheme in a .xsd file, and as COBOL copy book in a .cpy file. Only one of these files is required, depending on the Data Format option that is selected in the EP adapter specification.
•Adapters: This section is used to select the EP adapter to be used to emit the event with configuration that is appropriate for that adapter. For example, the TS Queue adapter requires the queue name, queue system identifier if the queue is remote, if the queue should use auxiliary storage, and the data format. For more information, see Chapter 3, “Event emission” on page 49.
•Advanced Options: This section is used to select the emission mode, dispatch priority, transaction ID, user ID, and if events are to be transactional. For more information, see Chapter 3, “Event emission” on page 49.
|
Tip: It is recommended to use an EPADAPTER or EPADAPTERSET resource because it is likely that several event specifications can use the same EP adapter specification. Also, any changes to the EP adapter specification do not require event bindings to be modified.
|
Figure 2-14 EP adapter information for the catalog sample
2.4 Explicit events by using SIGNAL EVENT
In addition to capture points for commands that are already in use in your applications, CICS enables applications to identify specific capture points by using the SIGNAL EVENT command.
The format of the command is shown in Example 2-1.
Example 2-1 SIGNAL EVENT command format
>>-SIGNAL EVENT(data-value)--+--------------------------------------------+-><
+-FROMCHANNEL(data-value)--------------------+
'-FROM(data-area)-+------------------------+-'
'-FROMLENGTH(data-value)-'
The command includes the following elements:
•Event(data-value) specifies the event name
•FROMCHANNEL specifies the name of a channel that has containers from which event information can be captured
•FROM provides a storage area from which event information can be captured
SIGNAL EVENT works in the same way as other capture point in CICS in that an event specification and capture point are required. However, the following differences are notable:
•You can explicitly choose where in the application logic the capture point occurs, rather than relying on the use of an existing command.
This ability is useful where there is no suitable existing command that is event-enabled (such as an SQL command) or complex logic is required to establish if the event is of interest that cannot be expressed by using the event binding editor.
•You provide a name for this capture point.
This function can make it easier to capture events without requiring the user of the event binding editor to have a deep knowledge of the application code. In particular, this might be the case if the application is provided by an IBM Business Partner and the application source is not available.
Capture points can filter on this name with operators Equals or Begins With.
•You can assemble the data you want to make available from diverse sources (such as DB2 tables) that are not available on event-enabled commands.
A capture specification for this SIGNAL EVENT can capture information sources from this data to build the event payload.
Although SIGNAL EVENT requires the application to be changed, if a good selection of data is included on the command, this change must be made only once. After that change is made, an event specification can be used to determine whether the event is enabled and what data is emitted.
2.4.1 Automatic Capture Specification for SIGNAL EVENT
If you use the SIGNAL EVENT command that uses FROMCHANNEL and put the data into containers, you can use the editor to create a capture specification for the event automatically.
Complete the following steps to add an automatic capture specification by using the event binding editor:
1. Add a new event specification with a name that matches the EVENT predicate.
2. Add the business data you want to capture with the names of the containers you are passing on the FROMCHANNEL.
The editor creates a capture specification for a SIGNAL EVENT capture point with the filter predicate as shown in the following example:
EVENT Equals <name of event specification>
It also adds information sources for each business data and includes the following parameters:
•The information is in a container with the name of the business data that is passed on the FROMCHANNEL.
•The data is at offset 0 in the container.
•The length is the same as the length of the business data.
Figure 2-15 shows an event specification to be used with SIGNAL event.
Figure 2-15 Event specification for a SIGNAL EVENT
Figure 2-16 on page 45 shows an automatically-generated capture specification.
Figure 2-16 Automatically generated capture specification
Figure 2-17 shows the automatically-generated information sources in the capture specification.
Figure 2-17 Automatically generated information sources
2.5 Deploying a CICS bundle to zFS
The CICS Explorer provides an export wizard to deploy a CICS bundle project to a zFS directory, which is ready for it to be installed into CICS by using a BUNDLE resource.
Complete the following steps to deploy a CICS bundle to zFS:
1. To start the export wizard, right-click the CICS bundle project and select Export Bundle Project to z/OS UNIX File System, as shown in Figure 2-18.
Figure 2-18 Selecting the export panel
2. Select Export to a specific location in the file system → Next and complete the information in the Export Bundle panel to provide the bundle project name, connection, and directory details.
It is advisable to select the Clear existing contents of Bundle directory option if the directory already exists to remove any pre-existing files, as shown in Figure 2-19.
It is advisable to select the Clear existing contents of Bundle directory option if the directory already exists to remove any pre-existing files, as shown in Figure 2-19.
Figure 2-19 Export bundle panel
3. Select Finish. The CICS bundle project is exported.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.