Db2iDataQueue Listeners

 uses Db2iDataQueue listeners to subscribe to messages from data queues residing on IBM Db2 for i databases.
lac52
CA Live API Creator
 uses Db2iDataQueue listeners to subscribe to messages from data queues residing on IBM Db2 for i databases.
For more information about these data queues, see the IBM Knowledge Center.
The 
db2i
 sample API includes Db2iDataQueue listeners that demonstrate subscribing to messages from keyed and non-keyed data queues residing on Db2 for i databases.
For more information about this sample API, see GitHub.
In this article:
Verify the Prerequisites
Before you can create your Db2iDataQueue listener, you have verified the following prerequisites:
  • You have installed the JDBC driver for Db2 for i. 
    For more information about how to install the JDBC driver for Db2 for i, see IBM Db2 for i Data Source.
  • You have created a connection of type Db2iDataQueue.
    For more information about how to create a connection, see Manage Connections.
  • You know the hostname, port, exchange name, exchange type, and the data queue residing on the Db2 for i database to which you are connecting.
Create a Db2iDataQueue Listener
Follow these steps:
  1. With your API open, in the Create section, click 
    Listeners
    .
    If your API does not have existing listeners, the Welcome to Listeners and Connections page appears. If your API has existing listeners, they are listed on the Details tab.
  2. Complete one of the following options:
    • If you have not defined any listeners, on the Welcome to Listeners and Connections page, click 
      Create a Listener
      .
    • If you have defined at least one listener, on the Details tab, click 
      Add
      .
    The Add Listener window opens.
  3. Complete the following fields, and then click 
    Add
    :
    Listener name
    The name for your listener.
    Listener type
    The listener type defines the protocol that you want 
    CA Live API Creator
     to follow to establish a link to an external system to exchange information. Select
    Db2iDataQueue
    .
    The listener is added to the list of listeners. The Details tab is selected by default.
  4. Click the 
    Details
     tab, complete the following fields, and then click 
    Save
    :
    Connection
    The Db2iDataQueue connection that the Db2iDataQueue listener uses to connect to a data queue residing on a Db2 for i database.
    One server only
    (This option is for when you have configured 
    CA Live API Creator
     to run as a cluster.) Select this option if you want 
    CA Live API Creator
     to execute the listener code on a node in the cluster instead of on all nodes in the cluster. 
    CA Live API Creator
     records the node on which it executed the listener code in the listener log.
    All servers
    (This option is for when you have configured 
    CA Live API Creator
     to run as a cluster.) Select this option if you want 
    CA Live API Creator
     to execute the listener code on all nodes in the cluster. 
    Logging level
    Defines the level at which you want 
    CA Live API Creator
     to send messages to the logs for this Db2iDataQueue listener. You can write logs for your listener in the code editor at various levels, for example, 
    log.info("Foo")
     and 
    log.fine
    . The logging level determines whether 
    CA Live API Creator
     sends these messages to the listener logs.
    Active
    Indicates whether the Db2iDataQueue listener is active and can receive messages. Active listeners are in the "Running" status or the "Stopped" status. The status is based on the connections.
    Default:
     Cleared
  5. Configure and tailor your Db2iDataQueue listener using parameters by completing the following steps:
    1. Click the 
      Parameters
       tab.
      The required parameter for the Db2iDataQueue listener is listed by default. Db2iDataQueue listeners must listen to data queues residing on IBM Db2 for i databases.
      For more information about the Db2iDataQueue listener parameters, see the "Db2iDataQueue Listener Parameters" section.
    2. Complete the values for the parameter, and then click 
      Save Parameters
      . To add a parameter, click 
      Add Parameter
      .
  6. Click the 
    Code
     tab, enter the JavaScript code that 
    CA Live API Creator
     executes whenever the listener receives a message from a data queue to which it is subscribed, and then click 
    Save
    .
    You can use the following JavaScript objects inside the listener code:
    • The 
      listenerUtil
       object
      For information about this object, see The listenerUtil Object.
    • The 
      log
       object
      For information about this object, see The log Object.
    • The 
      JSON
       object. The standard JavaScript object for converting objects to and from JSON strings.
      You can view a list of the available methods that you can use in your JavaScript code using code completion.
    • The 
      payloadAsString
       object
    • The Camel 
      message
       object
    • The 
      headers
       object
    • The 
      outHeaders
       object
    • The 
      exchangeException
       object
    • The 
      properties
       object
    • The 
      exchange
       object
    • The 
      typeConverter
       object
    • The 
      camelContext
       object
    For more information about the 
    payloadAsString
     object, the Camel 
    message
     object, the 
    headers
     object, the 
    outHeaders
     object, the 
    exchangeException
     object, the 
    properties
     object, the 
    exchange
     object, the 
    typeConverter
     object, and the 
    camelContext
     object, see Apache Camel-Based Listener Object Reference.
  7. Click the 
    Details
     tab, select the 
    Active
     checkbox, and then click 
    Save
    .
Your Db2iDataQueue listener is created and is active.
Db2iDataQueue Listener Parameters
The Db2iDataQueue listener parameters are derived from the definition of the Apache Camel jt400 component. You can add the following listener parameters to a Db2iDataQueue listener:
Parameter Name
Parameter Description
keyed
Defines whether to use keyed or non-keyed data queues.
Default:
false
Values:
    • false
      : Use non-keyed data data queues.
    • true
      : Use keyed data data queues.
searchType
The search type for the data queue.
Default:
EQ
Values:
EQ
,
NE
,
LT
,
LE
,
GT
, or
GE
searchKey
Defines the search key for keyed data queues.
Default
:
null
For the complete list of the parameters that jt400 supports, see the Apache Camel documentation.
For more information about the data types for Db2iDataQueue listener parameters, see Connection and Listener Parameter Data Types.
Manage Db2iDataQueue Listeners
You can manage your Db2iDataQueue listeners by restarting them, by stopping them, by retrieving Db2iDataQueue connections, and by publishing messages to data queues residing on Db2 for i databases.
Update a Listener in Running Status
If the listener is in the "Running" status and you update it, you must restart it.
For more information about how to restart a running Db2iDataQueue listener, see the "Restart your Db2iDataQueue Listener" section.
Restart your Db2iDataQueue Listener
Restart listeners so that they can receive messages from data queues residing on the Db2 for i database.
If the listener is in the "Running" status and you update it, you must restart it.
Prerequisite:
  • You have changed the listener and you have saved those changes.
  • The listener is active (the 
    Active
     checkbox is selected) and can receive messages.
On the Details tab, click 
Restart
.
Stop your Db2iDataQueue Listener
You can stop your listener by clearing the 
Active
 field, and then clicking 
Save
.
Publish a Message to a Data Queue Residing on Db2 for i Databases
With a Db2iDataQueue connection, you can publish messages to data queues residing on Db2 for i databases by using the 
publishMessage()
 method in the JavaScript code for your functions or rules.
Prerequisite:
 You have created a Db2iDataQueue connection.
The 
db2i
 sample API includes example functions that demonstrate publishing messages to data queues residing on Db2 for i databases.
The following JavaScript objects include this method:
  • listenerUtil
    For more information about the 
    publishMessage()
     method that is included with this object, see The listenerUtil Object.
  • SysUtility
    For more information about the 
    publishMessage()
     method that is included with this object, see The SysUtility Object.
  • timerUtil
    For more information about the 
    publishMessage()
     method that is included with this object, see The timerUtil Object.
Run an API with Db2iDataQueue Listeners
Before you import an API into API Server or run 
CA Live API Creator
 pointing to an admin repository that includes APIs with Db2iDataQueue listeners, you must install the JDBC driver for Db2 for i and restart API Server.
For more information: