Event emission
In this chapter, we describe event emission, including the different kinds of event processing (EP) adapters that emit events as different formats to different types of destination. The options to control event emission also are described, the EP adapter set is introduced, and exporting event specification is described.
This chapter includes the following topics:
3.1 Event processing adapters
EP adapters are programs that format and then emit events from a CICS system. An event binding needs an EP adapter to be specified for the event to be emitted by CICS.
The following EP adapters are provided by EP:
•TS queue EP adapter: Easy to set up for use within CICS, but has a limit of 32,767 entries in a TS queue.
•Transaction start EP adapter: Emits events to start CICS transaction.
•WebSphere MQ EP adapter: Uses a robust transport mechanism and provides a quick and easy way of emitting events out of CICS.
•HTTP EP adapter: Provides a quick and easy way of emitting events out of CICS.
•Custom EP adapter: If none of these adapters serve your purpose, you can provide a CICS program as EP adapter to format and emit the events.
If you want the event to be transactional and synchronous, WebSphere MQ and TS queue EP adapters are good choice because they can emit events in a recoverable way.
You can specify an EP adapter with a definition embedded in an event binding, or specify one which is predefined and thus is separate from the event binding. The advantage of specifying a predefined EP adapter is the EP adapter can be used in more than one event bindings. Predefined EP adapters can be included in an EP adapter set, which is described in 3.4, “EP adapter set” on page 60. Despite the name, a predefined EP adapter does not need to be defined when it is specified in the event binding or EP adapter set. However, it does need to be defined and installed before events can be emitted.
To view an EP adapter definition, open the catalog sample event binding in CICS Explorer and select the Adapter tab in the CICS event binding editor. The adapter pane is where you specify the EP adapter to emit events that are created by this event binding. You can specify the parameters for the EP adapter and any advanced information.
Select the type of EP adapter, then select options relevant to the EP adapter. Figure 3-1 shows the adapter configuration for the catalog sample event binding.
Figure 3-1 Adapter information for the catalog sample
Use the drop-down menu for the Adapter field to choose an EP adapter type. EP adapter types are described in 3.1.1, “TS Queue EP adapter” on page 52 through 3.1.5, “Custom EP adapter” on page 54. The event formats supported by each type of EP adapter are described in 3.1.6, “Data formats supported by EP adapters” on page 54.
You can export a description of your event as an XML schema or COBOL copy book. For more information, see 3.5, “Exporting event specifications” on page 62.
Optionally, you can set advanced dispatcher settings to control the behavior of EP adapter. For more information, see 3.2, “EP Adapter advanced options” on page 55.
3.1.1 TS Queue EP adapter
This EP adapter emits events to a named CICS temporary storage queue and can be used to perform the following tasks:
•Validate that the correct events are being captured with the correct data.
•Emit events to any consumer that reads from a TS queue.
This EP adapter is a good choice when events are implemented. You can use it for testing and debugging purposes because you can browse TS queues with the CICS-supplied CEBR transaction to check the payload. You can also refresh the view to check for new events in the queue.
However, TS Queues are limited to 32,767 entries or less. You might delete only the entire queue rather than individual entries within, so you need a strategy for clearing out events you processed.
Specify the following options for the TS queue EP adapter:
•The CICS queue name.
•The System ID if your target queue is remote.
•Select Use Auxiliary Temporary Storage if required and if the TS queue does not already exist.
•A data format for the event. For more information, see “Data formats supported by EP adapters” on page 54.
3.1.2 Transaction start EP adapter
This EP adapter emits events in the CICS container-based event (CCE) format to start a named CICS transaction that uses the event data. You can specify the CICS system that runs the transaction.
Specify the following options for the Transaction start EP adapter:
•The transaction ID of the CICS application that runs as a result of the events.
•Optionally, a transaction user ID or select Use Context User ID for the transaction to run under. If none of the IDs are specified, the started transaction runs under the CICS default user ID.
If you specify a transaction user ID, CICS checks that the installation user ID is authorized as a surrogate user of the transaction user ID when the adapter is installed.
3.1.3 WebSphere MQ EP adapter
This EP adapter emits events to a WebSphere MQ queue in an XML format for use by products that use the common event infrastructure and Common Base Event format, such as IBM Business Monitor, WebSphere Business Event format for IBM Operational Decision Manager, or in a non-XML character format.
Specify the following options for the WebSphere MQ Queue EP adapter:
•Specify the Queue Name of the WebSphere MQ queue on which events emitted by this event binding are placed. You must specify a queue name.
•Specify whether messages are persistent. Select one of the following values from the Persistent list.
 – No: Messages put on the queue by the adapter are nonpersistent.
 – Yes: Messages put on the queue by the adapter are persistent.
 – Queue default: Messages put on the queue inherit the default persistence of the named queue.
•Specify the message priority. You can select the queue default, or enter a value (0 - 9) in the Priority field for the WebSphere MQ message priority.
•Specify the expiry time. You can select Never Expire or enter a value for the WebSphere MQ message expiry in the Expiry Time field. This period is expressed in tenths of a second. A message can be discarded if it was not removed from the destination queue before this period elapses.
•Specify a data format for the event.
3.1.4 HTTP EP adapter
This EP adapter emits events to an HTTP 1.1-compliant server by using HTTP POST in XML format through the connection that is described in a URIMAP with USAGE(CLIENT). It can be used as a less robust alternative to WebSphere MQ.
Specify the following options:
•The URIMAP name that represents the connection to the HTTP server. You must specify this option.
•A data format for the event.
3.1.5 Custom EP adapter
A custom (user-written) EP adapter emits events in any format that you require. A custom EP adapter is a CICS program that you write to provide a combination of formatting and routing of an event that is not supported by the CICS-provided EP adapters. It must not carry out any other processing, such as usage of the event.
Specify the transaction ID for your user-written CICS application that formats, routes, and emits the event. You must specify a transaction ID.
Write the data to be passed to the Custom EP adapter. Your custom EP adapter receives this data that can be used to configure the custom EP adapter
3.1.6 Data formats supported by EP adapters
Table 3-1 lists the data formats that are supported by different types of EP adapters.
Table 3-1 Data formats supported by EP adapters
TS queue EP adapter
HTTP EP adapter
Transaction start EP adapter
WebSphere MQ EP adapter
•Common Base Event
•Common Base Event REST
•WebSphere Business Events
•CFE
•Common Base Event
•Common Base Event REST
•WebSphere Business Events
CCE
 
•Common Base Event
•WebSphere Business Events
•CFE
The following abbreviations of and terms for the event formats are used in Table 3-1:
•Common Base Event
Event data is the Common Base Event XML format that is required by IBM Business Monitor.
•Common Base Event REST format
Event data is the Common Base Event XML format without the Common Base Event envelope.
•WebSphere Base Event
Event data is the XML format that is required by WebSphere Business Events.
•CICS flattened event (CFE)
Event data is in a COBOL language structure.
•CICS container-based event (CCE)
Event data is placed in containers in a CICS channel named DFHEP.EVENT.
3.2 EP Adapter advanced options
Advanced dispatcher options are shown in Figure 3-2. These options are for advanced users and control the way in which the EP adapter is run in a CICS system. They are not required.
Figure 3-2 Advanced options for dispatcher
It is generally more efficient to allow CICS run the EP adapter under the dispatcher thread. However, you might need the EP adapter to be run as a separate transaction; for example, if you must run it under a particular user ID that has authority to write to the WebSphere MQ queue, or you want to control the number of concurrent EP adapter tasks by using the TRANCLASS settings. In these cases, you must specify the advanced options to achieve this goal. The following sections describe each of the options.
3.2.1 Emission mode
You can specify asynchronous (ASYNC) or synchronous (SYNC) to instruct CICS how events are emitted. This option does not apply to the Transaction start EP adapter.
With asynchronous event emission, the event is queued for asynchronous processing by an EP dispatcher thread, which is separate from the capturing transaction.
With synchronous event emission, event formatting and emission are completed within the unit of work of the capturing transaction. The EP adapter is part of the application task. “Dispatch priority”, “Transaction ID”, and “User ID” are not applicable to the synchronous event emission mode.
Synchronous event emission is not supported for system events. CICS TS V4.2 or higher is needed if you specify synchronous emission mode.
3.2.2 Dispatch priority
You can specify Normal or High priority to control dispatching of events. High priority events are emitted when they are available. Normal priority events are emitted when they are available, but after any outstanding high priority events. This option is subject to the Events are Transactional setting.
3.2.3 Transaction ID
Specify the Transaction ID, which is not available for a custom EP adapter. The EP adapter program runs under this transaction ID. This is optional.
3.2.4 User ID
Specify a user ID so that the EP adapter transaction runs with this user ID. If you select the Use context User ID option, the EP adapter runs with the user ID under which the event was captured.
For more information about the effect on the EP adapter with different combinations of Transaction ID and User ID, see the CICS Information Center at this website:
When you install a BUNDLE resource that includes an event binding for which you specified a user ID in the Adapter tab of the CICS event binding editor, CICS checks that the user ID performing the install operation is authorized as a surrogate user of the user ID that is specified in the CICS event binding editor. This check also applies to the CICS region user ID during group list install on a CICS cold or initial start.
3.2.5 Transactional events
Specify whether events are transactional under the following conditions:
•Select the Events are transactional option if you want CICS to emit captured events only if the unit of work (UOW) that is associated with the event completes successfully. The events are emitted when there is an internal sync point within the program, or when the program ends and reaches an implicit sync point.
If the transaction fails and backs out, the events are discarded.
•Do not select the Events are transactional option if you want CICS to process events that are associated with event binding in near-real time, regardless of whether the UOW commits.
You can assure the emission of an event by using an EP adapter with synchronous emission mode and the appropriate transaction mode. For example, WebSphere MQ EP adapter and TS queue EP adapter support synchronous and transactional event emission, while HTTP EP adapter and Transaction start EP adapter do not. For more information about the supported combinations of emission modes and transactional modes for EP adapters, see the CICS Information Center at this website:
System events cannot be transactional events.
3.3 Predefined EP adapters
You can define an EP adapter separately from the event binding. By separating the definition of EP adapter from event binding, it is easier to change the configuration details for how events are to be formatted and emitted. The person defines EP adapters might be different from the person who defines event bindings. You can also reuse predefined EP adapters in multiple event bindings and EP adapter sets that were introduced in 3.4, “EP adapter set” on page 60.
Complete the following steps to create an EP adapter definition:
1. Right-click a CICS bundle project, select New, and the select CICS Event Processing Adapter, as shown in Figure 3-3 on page 58.
The wizard that is used to create CICS EP Adapter configuration opens.
Figure 3-3 Creating an EP adapter
2. In the File name field, enter a name for the EP adapter and select Finish. The new EP adapter is opened for editing.
Separate EP adapters have the same options as when EP adapters are defined in an event binding. When the EP adapter definition is finished, you must install to CICS for it to emit events.
Figure 3-4 shows the event binding that uses a predefined EP adapter.
Figure 3-4 Event binding with separate EP adapter
Use either of the following methods to specify an EP adapter name:
•Enter an EP adapter name directly into the Name field of the Adapter tab.
•Click Choose, as shown in Figure 3-5. Use one of the following methods to specify the information:
 – Enter an EP adapter name.
 – Select an EP adapter from the workspace.
Figure 3-5 Choose an EP adapter in the workspace for event binding
 – If you have a CICS System Management connection, choose an installed EP adapter from the connected CICS, as shown in Figure 3-6 on page 60.
Figure 3-6 Choose an installed EP adapter for event binding
3.4 EP adapter set
If you want one event to be emitted to multiple users, use the EP adapter set as the adapter resource for the event binding. For example, you might want the events from the catalog sample event binding to be sent to a TS queue and an HTTP destination. In this case, you can define an EP adapter set that specifies the TS queue and HTTP EP adapters for the event binding instead of defining two event bindings with the same capture point.
An EP adapter set is an XML definition that contains one or more EP adapter names. By using an EP adapter set, you can format and emit events to multiple EP adapters. The definition and installation of EP adapter set is separate from those EP adapters whose names are contained in the EP adapter set. You must install and enable the EP adapter set and the EP adapters for the event to be emitted successfully to the EP adapters.
To create an EP adapter set definition, right-click a CICS bundle project as shown in Figure 3-3 on page 58 and choose CICS Event Processing Adapter Set, enter a name and then click Finish. The EP adapter set is opened for editing and you can add EP adapters to it.
Figure 3-7 shows an EP adapter set that contains two EP adapter names.
Figure 3-7 An EP adapter set definition
Specifying an EP adapter set in event binding is similar to specifying an EP adapter. Figure 3-8 on page 62 shows how to choose an EP adapter set in the CICS Explorer workspace.
Figure 3-8 Choose an EP adapter set for event binding
3.5 Exporting event specifications
You can export descriptions for one or more event specifications in an event binding as a schema or copy book for use elsewhere.
If your chosen EP adapter or the adapter that is contained in EP adapter set emits events in a non-XML data format, such as CFE, the exported file type is a COBOL copy book (.cpy) file. The file name is the event specification name.
If your chosen adapter or the adapter that is contained in the chosen EP adapter set emits events in an XML data format (such as Common Base Event, Common Base Event REST, or WebSphere Business Events), the exported file type is an XML schema definition (.xsd) file. The file name is the event specification name that is appended with Common Base Event, Common Base Event REST, or WebSphere Business Events.
Complete the following steps to export event schema or copy book:
1. Click Export Event Specifications. The Export Event Specifications window opens.
2. Select the event specifications that you want to export.
3. Specify in the To Directory field a directory to which to export the event specifications.
4. If the event binding specifies an EP adapter but the EP adapter definition is not in the local workspace, the Data Format option is shown. Select the data format for export, as shown in Figure 3-9.
Figure 3-9 Select data format for export when the EP adapter does not exist in CICS Explorer workspace
5. If the event binding specifies an EP adapter set but one or more EP adapters that are specified by the EP adapter set are not in the local workspace, you can select the data formats, as shown in Figure 3-10 on page 64.
Figure 3-10 Selecting data format for export
6. Click Export.
One or more files are created in the specified directory for each event specification. If the event binding uses an EP adapter or uses an EP adapter set that contains only one EP adapter, only one file is created. If the event binding uses an EP adapter set that contains multiple EP adapters, one file is created for each of the data types of the EP adapters.
For example, if the EP adapter uses the Common Base Event format and you select two event specifications called example1 and example2 for export, two XML schema files are created, example1_CBE.xsd and example2_CBE.xsd. You can import the schema file to IBM Business Monitor to help define an inbound event.
If the EP adapter uses the WebSphere Business Events (XML) format, two XML schema files are created, example1_WBE.xsd and example2_WBE.xsd. You can use the schema file in the WebSphere Business Events Design Data tool to help define an event.
If the EP adapter uses CFE format, two COBOL copy books are created, example1.cpy and example2.cpy. You can use these copy books to process data in your event consumer programs.
For the event specification called example1, the files example1_CBE.xsd, example1_WBE.xsd and example1.cpy are created, if you specify an EP adapter set that has EP adapters with all of the data formats that were described in this chapter.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset