The messaging system (for example, webMethods 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 webMethods EntireX as the Messaging System

---

Using WebSphere MQ as the Messaging System

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 webMethods EntireX as the Messaging System

For many of the tasks described in this section, you will need to communicate with the person responsible for webMethods 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 webMethods EntireX issues referred to here, please refer to the webMethods EntireX documentation. To enable the Event Replicator for Adabas to use webMethods EntireX as a messaging system, webMethods EntireX must be installed and available for use. This is the task of the person responsible for webMethods EntireX in your installation.

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

2. In order for Event Replicator for Adabas to communicate with webMethods EntireX, the webMethods EntireX interface module must be available to the Event Replicator Server address space. When a webMethods 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 webMethods EntireX load library in the STEPLIB concatenation in the Event Replicator Server JCL. For more information refer to your webMethods 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 webMethods 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 webMethods EntireX with security turned on, you must use ACI version 8 or later. To use an older version of the webMethods EntireX ACI, contact your Software AG support representative for assistance.

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

   Use the following parameter to specify the name of the webMethods 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 webMethods 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 webMethods EntireX, the ETBBROKERID setting must correctly identify an webMethods EntireX Broker that is active in the system. This takes the standard format of an webMethods 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 webMethods EntireX as a messaging system. Software AG recommends that you review these parameters with the person in your installation responsible for webMethods 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.