You specify information in your event binding that controls
how CICS® emits events produced
by the event binding.
About this task
You use dispatcher information to define what happens to
events created by this binding. You select the EP adapter to emit
events and then select options relevant to the EP adapter.
Procedure
- Click the Adapter tab in the CICS event binding editor and
select the Use an adapter defined here option
to specify the EP adapter configuration to use for this event binding,
the parameters for the EP adapter, and any advanced information.
You can also choose whether to use a predefined EPADAPTER
resource or EPADAPTERSET resource. For more information about a predefined
EPADAPTER resource, see Event processing (EP) adapter configuration editor
in the CICS TS 5.1 Information Center.
For more information about a predefined EPADAPTERSET resource, see Event processing (EP) adapter set editor in the
CICS TS 5.1 Information Center.
If you specify a predefined
EPADAPTER or EPADAPTERSET resource, you must enter the name in the Name field,
or click Choose to choose a resource. For more
information about choosing adapter resources, see Choosing an EP adapter resource in the CICS TS
5.1 Information Center and Choosing an EP adapter set resource in the CICS
TS 5.1 Information Center.
- Optional: You can export one or
more event specifications in this event binding.
To
export an event specification either enter the name of a predefined
EPADAPTER resource, or select an adapter of your choice:
- Use the TSQ EP adapter or the WebSphere® MQ
EP adapter
and choose the CFE format to emit events in a binary form, so a COBOL
copybook (.cpy) is provided.
- Use any other EP adapter and format to provide an XML schema definition
(.xsd).
- Click Export Event Specifications. If you are using an EPADAPTER resource and your workspace contains
more than one adapter with the same name you will be asked to choose
an adapter from a list. The Export Event Specifications window
is displayed.
- Select the event specifications that you want to export.
- To export the event specifications, specify the directory
in the To directory field.
- If you use a predefined EPADAPTER resource that is not
found in your workspace you must select a suitable value for the Data
Format field.
- Click Export.
A file is created in the specified directory for each
event specification that you selected. Here are some example specifications:
- If you specify the WebSphere MQ
EP adapter
and the Common Base Event format and select two event specifications
called example1 and example2, two XML schema files are created: example1_CBE.xsd and example2_CBE.xsd.
You can import these schema files to IBM® Business Monitor to
help define an inbound event.
- If you specify the WebSphere MQ
EP adapter
and the WebSphere Business
Events (XML) format and select an event specification called example1,
an XML schema file is created, example1_WBE.xsd.
You can use this schema file in the WebSphere Business Events Design Data tool
to help define an event.
- If you specify the HTTP EP adapter and the Common Base
Event REST format and select two event specifications called example1
and example2, two XML schema files are created: example1_CBER.xsd and example2_CBER.xsd. You can import these schema
files to IBM Business Monitor to
help define an inbound event.
- If you specify the HTTP EP adapter and the WebSphere Business Events (XML) format
and select an event specification called example1, an XML schema file
is created, example1_WBE.xsd. You can
use this schema file in the WebSphere Business
Events Design Data tool to help define an inbound event.
- If you specify the HTTP EP adapter and the Common Base
Event format and select two event specifications called example1 and
example2, two XML schema files are created: example1_CBE.xsd and example2_CBE.xsd. You can import these schema
files to any consumer that accepts the common base event format to
help define an inbound event.
- If you specify the TS Queue EP adapter and select two event specifications
called example1 and example2, two COBOL copybooks are created: example1.cpy and example2.cpy.
You can use these copybooks to process data in your own event consumer
programs.
Note that if you export an event specification, and then
export the same event specification again to the same directory, the
CICS event binding editor prompts
you to either overwrite the existing file or cancel the export operation.
- Choose the EP adapter type from the Adapter list. You can specify the following EP adapter types:
- TS Queue
- Emits events to a named CICS TS
queue in one of the XML formats: Common Base Event,
Common Base Event REST, or WebSphere Operational Decision Management (WBE);
or in a non-XML (CFE) format. Use this EP adapter to validate
that the correct events are being captured with the correct data,
and to emit events to any consumer that reads from a TS queue.
- For assured event emission, synchronous transactional
events need a recoverable TS queue; synchronous nontransactional events
need an unrecoverable queue. Whether TS queues are recoverable depends
on the settings of a matching TSMODEL; TS queues are recoverable only
when there is a matching TSMODEL. When you use the TS queue adapter
for synchronous transactional events, you cannot issue a DELETEQ
TS command for the event TS queue in the unit of work that
captures the event.
- Transaction Start
- Emits events to a named CICS transaction.
Data is passed to the transaction in a container-based event format.
You can specify the CICS system
to run the transaction. You can use an existing transaction, if the
event data is not required.
- The transaction start EP adapter does not support assured
emission of events.
- Custom (User Written)
- 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 supplied EP adapters. The custom EP adapter
must not carry out any other processing, such as consumption of the
event.
- For assured event emission, the custom EP adapter must
conform to the recoverability requirements of the event. Consult the
documentation for your custom EP adapter to see whether it supports
transactional or nontransactional synchronous events.
- WebSphere Message
Queue
- Emits events to a WebSphere message
queue either in an XML format for consumption by WebSphere Operational Decision Management,
the Common Base Event format for IBM Business Monitor,
or in a non-XML format.
- For assured event emission, event delivery is assured
when the WebSphere MQ
EP adapter is used in combination with persistent WebSphere message queues.
- HTTP
- Emits events to an HTTP 1.1 compliant server using HTTP POST in
XML format for consumption by products such as WebSphere Operational Decision Management,
and IBM Business Monitor.
- The HTTP EP adapter does not support assured emission
of transactional events.
- Specify the options for your chosen EP adapter type:
- Specify the following options for the TS Queue EP adapter:
- Specify the CICS queue
name. You must specify a queue name.
- If your target queue is remote, specify the system ID.
- Select Use Auxiliary Temporary Storage if
required.
- Specify a data format for the event. Select one of the
following values from the Data Format list:
- CICS Flattened Event (Binary)
- Event data is in a non-XML format.
- WebSphere Business Events (XML)
- Event data is in XML format.
- Common Base Event (XML)
- Event data is in XML format.
- Common Base Event REST (XML)
- Event data is in XML format.
- Specify the following options for the Transaction Start EP adapter:
- Specify the transaction ID of the CICS application
that runs as a result of the events. You must specify a transaction
ID.
- Specify a transaction user ID. The transaction that is started
by the transaction start EP adapter runs using this user ID.
- Specify the system ID, which is available only for the Transaction
EP adapter. The EP adapter transaction runs on the CICS system with this system ID.
- Specify the following options for a Custom (User Written)
EP adapter:
- Specify one of the following:
- If emission mode is asynchronous the transaction ID for your user-written CICS application that formats,
routes, and emits the event. You must specify a transaction ID for
asynchronous emission by the custom EP adapter.
- If emission mode is synchronous the name of your user-written CICS application program that formats,
routes, and emits the event. You must specify a program ID for synchronous
emission by the custom EP adapter.
- Write the data to be passed to the Custom EP adapter. Your Custom
EP adapter processes this data.
- Specify the following options for the WebSphere MQ 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 WebSphere MQ EP adapter
are nonpersistent.
- Yes
- Messages put on the queue by the WebSphere MQ EP adapter
are persistent.
- Queue Default
- Messages put on the queue inherit the default persistence of the
named queue.
- Specify the message priority. You can either select Queue
Default, or type a value in the Priority field,
for the WebSphere MQ message
priority, from 0 - 9.
- Specify the expiry time. You can either select Never
Expire or type a value for the WebSphere MQ message expiry in the Expiry
Time field. This time is expressed in tenths of a second.
A message becomes eligible to be discarded if it has not been removed
from the destination queue before this period elapses.
- Specify a data format for the event. Select one of the following
values from the Data Format list:
- CICS Flattened Event (Binary)
- Event data is in a non-XML format.
- WebSphere Business Events (XML)
- Messages are put on the queue in the XML format required by WebSphere Operational Decision Management.
- Common Base Event (XML)
- Messages are put on the queue in the common base event format
required by IBM Business Monitor.
- Specify the following options for the HTTP EP adapter:
- Specify a URIMAP. The name of a URIMAP resource that represents
the connection to the HTTP 1.1 compliant server.
- Specify a data format for the event. Select one of the following
values from the Data Format list:
- Common Base Event REST (XML)
- Events are sent to an HTTP 1.1 compliant server in the XML format
required by IBM Business Monitor.
- WebSphere Business Events (XML)
- Events are sent to an HTTP 1.1 compliant server in the XML format
required by WebSphere Operational Decision Management.
- Common Base Event (XML)
- Events are sent to an HTTP 1.1 compliant server in the common
base event format which is consumable by any product supporting the
Common Event Infrastructure.
- Optional: Specify any required
advanced dispatcher options. These options are for advanced
users, and they control how the EP adapter is run in a CICS system.
Note: It is generally more efficient
to let 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 need to 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.
- Specify the emission mode. You
can specify ASYNC or SYNC to
specify how events are emitted. Specify synchronous emission mode
for assured event emission. When the emission mode is synchronous,
the WebSphere MQ EP adapter
emits these events:
- Transactional events by using the MQPMO_SYNCPOINT option. WebSphere MQ messages can
be recovered in the unit of work for the capturing transaction.
- Non-transactional events by using the MQPMO_NO_SYNCPOINT option.
When the emission mode is asynchronous, the WebSphere MQ EP adapter emits events by
using the MQPMO_NO_SYNCPOINT option.
Notes: - For synchronous events (assured event emission), the event-capturing
application needs write authority to the event emission transport.
For asynchronous events, the EP adapter needs write authority.
- Specifying SYNC NONTRANS for the HTTP EP adapter turns the capturing
transaction into a web application that might have to be reconfigured
accordingly.
- Set the DTIMOUT attribute of the TRANSACTION definition for any
transaction that could potentially emit synchronous events through
the HTTP EP adapter.
- Specify the dispatch priority. You can specify Normal or High priority
to control how the event dispatcher processes events associated with
this event binding. High priority events are emitted as soon as
they are available based on the Events are Transactional setting.
Normal priority events are emitted as soon as they are available
based on the Events are Transactional setting
but after any outstanding high priority events.
Note: This
option does not apply to synchronous emission mode.
Specify the transaction ID and user ID. The adapter is initiated with the transaction ID and user ID
specified. The transaction ID is not relevant for the Custom EP adapter
type as it is set in the Adapter section instead. Depending on the
settings on transaction ID and user ID, EP dispatcher task either
starts or links to EP adapter program.Table 1. Transaction
ID and user ID for WebSphere MQ
EP adapter, TS Queue EP adapter, and Transaction Start EP adapterTransaction ID is specified |
User ID is specified |
Use Context user ID |
EP adapter is |
EP adapter runs using |
EP adapter transaction ID is |
x |
x |
|
Attached |
Specified user ID |
Specified transaction ID |
x |
|
x |
Attached |
Context user ID |
Specified transaction ID |
|
x |
|
Attached |
Specified user ID |
CEPQ for WebSphere MQ EP adapter
CEPT for TS Queue EP adapter
CEPS for Transaction Start EP adapter
|
|
|
x |
Attached |
Context user ID |
CEPQ for WebSphere MQ EP adapter
CEPT for TS Queue EP adapter
CEPS for Transaction Start EP adapter
|
x |
|
|
Attached |
CICS default
user ID |
Specified transaction ID |
|
|
|
Linked |
CICS region
user ID |
Not applicable |
If the WebSphere MQ
queue, TS queue, or the transaction that you want to start is remote,
see
for information
about the security settings.
Table 2. Transaction ID and
user ID for HTTP EP adapterTransaction ID is specified |
User ID is specified |
Use Context user ID |
EP adapter is |
EP adapter runs using |
EP Adapter transaction ID is |
x |
x |
|
Attached |
Specified user ID |
Specified transaction ID |
x |
|
x |
Attached |
Context user ID |
Specified transaction ID |
|
x |
|
Attached |
Specified user ID |
CEPH |
|
|
x |
Attached |
Context user ID |
CEPH |
x |
|
|
Attached |
CICS default
user ID |
Specified transaction ID |
|
|
|
Attached |
CICS default
user ID |
CEPH |
For the Custom (User-Written) EP adapter which has
a transaction ID and an asynchronous emission mode, EP dispatcher
task always attaches to this adapter, with the specified user ID,
or context user ID , or CICS default
user ID.
Note: These two options do not apply to synchronous emission
mode.

- Specify whether events are transactional. Select
the Events are Transactional check box if you
want CICS to capture events
only if the business unit of work (UOW) associated with the event
completes successfully.
Note: Consider carefully whether
events that are captured from unrecoverable actions should be specified
as transactional. For example, if you capture a transactional event
from a WEB SEND command and the unit of work is
then backed out, the event is backed out but the WEB SEND command
might have caused an HTTP message to be sent.
Clear the Events
are Transactional check box if you want CICS to process events associated with this
event binding outside a transaction. Events are emitted as they are
produced.
Results
The adapter and dispatcher information for your event binding
is now complete.