Messaging System Integration

#### Search Results

Search

# Messaging System Integration

The messaging system (for example, IBM EntireX or WebSphere MQ) plays a key role in the operation of the Event Replicator for Adabas; however, administration and operation of the messaging system is outside the scope of the Event Replicator for Adabas.

This document describes guidelines to integrating these messaging systems with the Event Replicator for Adabas.

- Using WebSphere MQ as the Messaging System

- Using IBM EntireX as the Messaging System

## Using WebSphere MQ as the Messaging System

Note
If you are running on z/OS using IBM WebSphere MQ Series definitions for your Event Replicator DESTINATION or IQUEUE definitions, a S0D3 abend can occur if you run it as a started task and specify the parameter REUSASID=YES. This is a documented IBM WebSphere MQ Series issue.

To integrate the Event Replicator for Adabas with the WebSphere MQ messaging system:

1. The Adabas Event Replicator Server delivered code must first be linked with the latest WebSphere MQ interface modules on site. Essentially, the delivered ADAMQT module must be linked with the CSQBSTUB module which is the WebSphere MQ interface module. JCL such as the following should be used to create the required Event Replicator Server load module called ADAMQS.

       //LINK     EXEC PGM=IEWL,PARM='LIST,XREF,REUS,RENT'
       //SYSPRINT DD SYSOUT=*
       //SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(3,1))
       //ADALIB   DD DISP=SHR,DSN="ADABAS Event Replicator Server Load Library"
       //MQSLIB   DD DISP=SHR,DSN="WebSphere MQ SCSQLOAD Library"
       //SYSLMOD  DD DISP=SHR,DSN="User Load Library"
       //SYSLIN   DD *
        INCLUDE ADALIB(ADAMQT)
        INCLUDE MQSLIB(CSQBSTUB)
        ENTRY ADAMQS
        NAME  ADAMQS(R)
       /*

2. For each destination to be used by the Event Replicator for Adabas the user needs to ensure that the DMQQMGRNAME and DMQQNAME parameters identify correctly defined resources within the WebSphere MQ installation. You must also ensure that the Event Replicator for Adabas job or started task is defined to the security system to have access to the WebSphere MQ resources identified in this step.

   The DMQQMGRNAME parameter should identify the WebSphere MQ Subsystem to be used and DMQQNAME should identify a queue defined within that subsystem:

       ADARPD DESTINATION NAME=[destname]
       ADARPD DTYPE=MQSERIES
       ADARPD DMQQMGRNAME=CSQ1
       ADARPD DMQQNAME=SYSTEM.DEFAULT.LOCAL.QUEUE
       ADARPD DMQDYNQNAME=SOME.MEANINGFUL.NAME

   In the above example, the WebSphere MQ Subsystem name is CSQ1 and the queue to be used by the Event Replicator Server is SYSTEM.DEFAULT.LOCAL.QUEUE. If this actually defines a model queue, then DMQDYNQNAME should be specified to assign some name to the queue to be used by the Event Replicator for Adabas. Note that if the name contains special characters (such as periods), it should be enclosed in quotes as illustrated above. For complete information on the conventions that should be used when coding Event Replicator for Adabas parameters and subparameters, read Conventions.

3. The following table does not list all possible parameters used in defining local queues, merely those which may directly impact on the use of the queue by the Event Replicator for Adabas. For a complete guide to queue definition please consult your WebSphere MQ administrator or refer to the MQSC Command Reference Manual.

   WebSphere MQ Attribute | Impact on Adabas Replication Services Operation
   --- | ---
   PUT | Set to ENABLED if you want the Event Replicator Server to use the queue as an output queue.
   GET | Set to ENABLED if you want the Event Replicator Server to use the queue as an input queue.
   MAXDEPTH | Set this integer value to the number of messages the queue needs to contain.
   MAXMSGL | Set this integer value to the maximum expected message length to be handled by the queue.
   DEFPSIST | The default persistence parameter determines whether messages on the queue will be retained over a failure or outage of the queue manager. The Event Replicator Server requires that this parameter be set to Yes, to ensure that messages are not lost.
   SHARE | NOSHARE | If SHARE is set, more that one application may retrieve messages from the queue at a time. If NOSHARE is set only one application may retrieve messages from the queue at a time. Set according to the needs of your use of the Event Replicator Server.

   For further discussion of these attributes please refer to your WebSphere MQ System Administrator or the WebSphere MQ System Administration Guide.

4. Consult with your WebSphere MQ System Administrator to ensure that the above resources are correctly defined and that any dynamic queue names used adhere to the naming conventions in force at your installation.

## Using IBM EntireX as the Messaging System

For many of the tasks described in this section, you will need to communicate with the person responsible for IBM EntireX in your installation. The following gives details of what is required from an Event Replicator for Adabas perspective but for more details on any IBM EntireX issues referred to here, please refer to the IBM EntireX documentation. To enable the Event Replicator for Adabas to use IBM EntireX as a messaging system, IBM EntireX must be installed and available for use. This is the task of the person responsible for IBM EntireX in your installation.

1. The Event Replicator for Adabas requires IBM EntireX at a version as described in Messaging System (IBM EntireX or IBM WebSphere MQ) Requirements in the Installation documentation.

2. In order for Event Replicator for Adabas to communicate with IBM EntireX, the IBM EntireX interface module must be available to the Event Replicator Server address space. When a IBM EntireX queue of any nature is defined to Event Replicator for Adabas, the Event Replicator address space will attempt to load a module specified by the parameter ETBBROKERNAME. It is therefore necessary that you specify the IBM EntireX load library in the STEPLIB concatenation in the Event Replicator Server JCL. For more information refer to your IBM EntireX documentation.

   Note
   If you elect to use the BROKER module under z/OS, review the security considerations in the EntireX Broker documentation for administration of Broker stubs under z/OS.

   If you will be using an open systems version of IBM EntireX:

   - You must also have the z/OS Broker stub installed. This stub is included with Event Replicator for Adabas under the EXXxxx.MVSL0xx data set.

   - If you intend to use an open systems version of IBM EntireX with security turned on, you must use ACI version 8 or later. To use an older version of the IBM EntireX ACI, contact your Software AG support representative for assistance.

   Caution
   In high throughput situations, we recommend that you use IBM EntireX installed on z/OS.

   Use the following parameter to specify the name of the IBM EntireX interface module to be used by the Event Replicator Server:

       ADARPD ETBBROKERNAME=BROKER

   This parameter is described in ETBBROKERNAME (EntireX Broker Stub Program) Setting. This setting can also be specified in the Replicator system file using the Adabas Event Replicator Subsystem.

3. For each IBM EntireX destination to be used by the Event Replicator Server, the following destination parameters must be specified:

       ADARPD DESTINATION NAME=[destname]
       ADARPD  DTYPE=ETBROKER
       ADARPD  DETBBROKERID= [BrokerID]
       ADARPD  DETBSERVICECLASS=[classname]
       ADARPD  DETBSERVICENAME=[servicename]
       ADARPD  DETBSERVICE=[service]

   These parameters are described individually in Event Replicator Initialization Parameters. These settings can also be specified in the Replicator system file using the Adabas Event Replicator Subsystem.

4. For this destination to successfully be used with IBM EntireX, the ETBBROKERID setting must correctly identify an IBM EntireX Broker that is active in the system. This takes the standard format of an IBM EntireX Broker ID, a number of examples of which follow:

   Broker ID Example | Description
   --- | ---
   '10.128.200.202:18024:TCP' | The broker must be running on IP address 10.128.200.202 and listening on TCP/IP Port 18024.
   myhost:18025:TCP | The host on which the broker is running must be defined such that a `gethostbyname('myhost')` request will return the IP address of that host. The broker itself must be running on that host and listening on port 18025.
   ETB50500:SVC249:NET | The broker must be active as node 50500 on ADABAS Router SVC 249.

   Once the Broker can be resolved, the appropriate attribute definitions must be in place for the service that the Event Replicator Server will use. The following sample service definition illustrates what is required in order for the previous sample definition to work correctly:

       DEFAULTS=SERVICE
         CONV-LIMIT         = UNLIM
         CONV-NONACT        = 4M
         LONG-BUFFER-LIMIT  = UNLIM
         NOTIFY-EOC         = YES
         SERVER-NONACT      = 5M
         SHORT-BUFFER-LIMIT = UNLIM
         TRANSLATION        = NO
         MAX-UOWS           = 1000
         CLASS = [classname], SERVER = [servicename], SERVICE = [service]

   In addition, the following table documents the various attributes and parameters that can impact the operation of Event Replicator Server when using IBM EntireX as a messaging system. Software AG recommends that you review these parameters with the person in your installation responsible for IBM EntireX.

   ETB Broker Attribute | Impact on Adabas Replication Services Operation
   --- | ---
   AUTOLOGON | As the Event Replicator Server processing requires that messages are delivered as Units of Work, this must be set to ‘NO’
   CLIENT-NONACT | This should be set to as high a value as possible to prevent the ETB from timing out an Event Replicator Server due to lack of activity on a regular basis. The Event Replicator Server can recover from this time-out by logging on again, however, it could create an unacceptable overhead.
   DEFERRED | If this is set to ‘NO’, it will be necessary for the ETB Consumer that will receive data from the Event Replicator Server to be active before the Event Replicator Server is started. If this is set to ‘YES’, the Event Replicator Server may start submitting data to the ETB Consumer before it is active, however, due to the amounts of data, this should be used with care in the event that ETB experiences a resource shortage before the ETB Consumer starts accepting the data.
   MAX-MSG | This will determine how many SENDs will be required to output information on a given transaction to the broker. The Event Replicator Server logic will determine this during startup and use it to break up any messages that are longer than the maximum.
   MAX-UOWS | This must be set to a value that is at least equal to the number of subtasks the Event Replicator Server is running plus 1 for the main task. The Event Replicator Server logic uses Units of work to output data to broker and could theoretically get to a point where one unit of work is active on each task. If there are other users of the same ETB in the system that use Units of Work, this figure should be reviewed based on their requirements.
   NEW-UOW-MESSAGES | If this is set to ‘NO’, it will cause problems for the Event Replicator Server processing, as it will not be possible to set up new Units of Work.
   NUM-CLIENT | This must be calculated as follows: Number of Event Replicator Server subtasks + 1 for main task + Number of ETB Input Queues. This is the requirement for the Event Replicator Server alone. If other systems are using the broker in question, this must be added to the requirements of the other systems.
   PSTORE | If messages are intended to be persistent over ETB failure, this parameter must be set up along with the associated resources that are required for persistence. We strongly recommend that you use this feature.
   SECURITY | This must be set to NO as the Event Replicator Server logic does not present user IDs that may be authenticated to the Broker.
   UOW-MSGS | This must be set in association with the MAX-MSG parameters. The largest amount of data than can be replicated by the Event Replicator Server can be calculated by multiplying UOW-MSGS by MAX-MSG. Any transaction data above this length cannot be replicated.
   UWTIME | If Units of Work are to be persistent, this parameter should be reviewed.
   UWSTATP | The default 0 removes UOW status information once it has been received and committed by the consumer. Setting it to 1 or higher allows to keep this information for debugging purposes, but fills up Broker’s permanent store fairly quickly.

Note
A sample program is provided, in source form, of a Natural-written target application that communicates with Event Replicator for Adabas using IBM EntireX. You can use this Natural sample to build your own target application for Event Replicator for Adabas. The sample program is in the Event Replicator for Adabas SYSRPTR library and is named EXARFTA. It simply displays the data sent from the Event Replicator Server. You can run this program from Natural or edit it and follow the instructions in the program itself.

### On this page

- Using WebSphere MQ as the Messaging System
- Using IBM EntireX as the Messaging System