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.
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:
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) /*
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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
|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.|
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.|
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.|
A sample program is provided, in source form, of a Natural-written target application that communicates with Event Replicator for Adabas using webMethods 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.