Specifying EP adapter and dispatcher information

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

  1. Click the Adapter tab in the CICS event binding editor to specify the EP adapter configuration to use for this event binding, the parameters for the EP adapter, and any advanced information. Start of changeYou can choose whether to use a predefined EPADAPTER resource, or the adapter defined in the Adapter section of the Adapter tab. For more information about a predefined EPADAPTER resource, see the Event processing (EP) adapter configuration editor topic. If you specify a predefined EPADAPTER resource, you must enter the name in the Name field.End of change
  2. 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).
    1. 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.
    2. Select the event specifications that you want to export.
    3. To export the event specifications, specify the directory in the To directory field.
    4. If you use a predefined EPADAPTER resource which is not found in your workspace you must select a Data Format as appropriate.
    5. 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.xsd and example2.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.xsd. You can use this schema file in the WebSphere Business Events Design Data tool to help define an event.
    • Start of changeIf 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.xsd and example2.xsd. You can import these schema files to IBM Business Monitor to help define an inbound event. End of change
    • Start of changeIf 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.xsd. You can use this schema file in the WebSphere Business Events Design Data tool to help define an inbound event. End of change
    • Start of changeIf 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.xsd and example2.xsd. You can import these schema files to any consumer that accepts the common base event format to help define an inbound event.End of change
    • 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.

  3. 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 queueStart of change in one of the XML formats: Common Base Event, Common Base Event REST, or WebSphere Business Events (WBE); or in a non-XML (CFE) formatEnd of change. 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.
    Start of changeFor 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.End of change
    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.
    Start of changeThe transaction start EP adapter does not support assured emission of events.End of change
    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.
    Start of changeFor 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.End of change
    WebSphere Message Queue
    Emits events to a WebSphere message queue either in an XML format for consumption by WebSphere Business Events, the Common Base Event format for IBM Business Monitor, or in a non-XML format.
    Start of changeFor assured event emission, event delivery is assured when the WebSphere MQ EP adapter is used in combination with persistent WebSphere message queues.End of change
    Start of changeHTTPEnd of change
    Start of changeEmits events to an HTTP 1.1 compliant server using HTTP POST in XML format for consumption by products such as WebSphere Business Events, and IBM Business Monitor.End of change
    Start of changeThe HTTP EP adapter does not support assured emission of transactional events.End of change
  4. 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.
      • Start of changeSpecify 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.
        End of change
    • 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.
    • Start of changeSpecify 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.
      End of change
    • 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 Business Events.
        Common Base Event (XML)
        Messages are put on the queue in the common base event format required by IBM Business Monitor.
    Start of change
    • 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 Business Events.
        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.
    End of change
  5. Optional: Specify any required advanced dispatcher options. These options are for advanced users, and they control the way in which 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.
    1. Start of changeSpecify 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.
      End of change
    2. 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: Start of changeThis option does not apply to synchronous emission mode.End of change
    3. Start of changeSpecify the transaction ID (not available for the CICS Transaction Start and Custom EP adapter types).End of change The EP adapter program runs using this transaction ID.

      Start of changeIf you do not specify a transaction ID, and you do not specify a user ID, the HTTP EP adapter is attached and run using the default transaction CEPH. All other EP adapters are linked to using the dispatcher transaction.End of change

      Note: Start of changeThis option does not apply to synchronous emission mode. End of change
    4. Specify the user ID. If you specify a user ID, the EP adapter transaction runs with this user ID. If you select Use context User ID, the EP adapter runs using the user ID that captured the event.
      If you specify a user ID, but you do not specify a transaction ID, the EP adapter runs using the default transaction for the EP adapter type:
      • The WebSphere MQ EP adapter uses the CEPQ transaction.
      • Start of changeThe HTTP EP adapter uses the CEPH transaction. End of change
      • The TS Queue EP adapter uses the CEPT transaction.
      Note: Start of changeThis option does not apply to synchronous emission mode.End of change
    5. 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.
    6. 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: Start of changeConsider 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. End of change

      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.
Parent topic: Tasks
Related concepts:
Event processing adapters
Related tasks:
Creating an event binding file