Post-Installation Replication Implementation Steps (All Platforms)

Once the Event Replicator for Adabas has been installed, replication can be implemented and started. How replication is implemented varies greatly by site and situation, but this document describes some general implementation steps.


Step 1. Supply Event Replicator Definitions

Replication definitions are used to customize the replication process. These definitions are specified in initialization parameters read from DDKARTE in the Event Replicator Server startup job or in the Replicator system file.

Once the Event Replicator for Adabas in installed, its replication processing is driven by definitions you specify. These definitions are described in the following table in order of importance to replication (required definitions are listed first).

Note:
You can run Event Replicator for Adabas in verify (test) mode, by turning on verification in the VERIFYMODE replication definition. This is useful if you want to test the definitions you have specified before you start using Event Replicator for Adabas in production mode. For more information, read Running in Verify Mode.

Definition Type Defines How many definitions are required?
destination The destination of the replicated data. Destination definitions can be created for Adabas, File, webMethods EntireX, WebSphere MQ, and Null destinations.

To maintain destination definitions using DDKARTE statements of the Event Replicator Server startup job, read Destination Parameter. To maintain destination definitions using the Adabas Event Replicator Subsystem, read Maintaining Destination Definitions.

Required.

At least one destination definition is required for data replication to occur. Create one definition for every Event Replicator for Adabas destination you intend to use.

subscription A set of specifications to be applied to the replication of the data. These include (but are not limited to):
  • the identification of the Adabas files that should be replicated and how they should be replicated (SFILE definitions that should be processed as part of the subscription)

  • architecture key, output alpha and wide-character keys that should be used

  • the name of the resend buffer definition that should be used for replication, if any

  • various settings relating to the availability of the subscription in specific circumstances

Subscription definitions identify SFILE definitions and resend buffer definitions that should be used. At least one SFILE definition is required.

To maintain subscription definitions using DDKARTE statements of the Event Replicator Server startup job, read SUBSCRIPTION Parameter. To maintain subscription definitions using the Adabas Event Replicator Subsystem, read Maintaining Subscription Definitions.

Required.

At least one subscription definition is required for data replication to occur.

SFILE An Adabas file to be replicated and the replication processing that should occur for that file. SFILE definitions are sometimes referred to as subscription file definitions and are referenced by subscription definitions.

An SFILE definition identifies (among other things):

  • the Adabas database ID and file number that should be replicated

  • the transaction filter definitions that should be used to filter the data in the Adabas file during replication (if any)

  • the subscription user exit that should be processed during replication (if any)

  • whether insert, delete, and update transactions should be replicated

  • the file’s alpha character encoding, if any

  • the GFB definitions that should be used for replication, if any, or the specific format buffer definitions that should be used instead.

To maintain SFILE definitions using DDKARTE statements of the Event Replicator Server startup job, read SUBSCRIPTION Parameter. To maintain SFILE definitions using the Adabas Event Replicator Subsystem, read Maintaining SFILE Definitions.

Required.

At least one SFILE definition is required for data replication to occur.

initial-state An initial-state request for data from the target application. Initial-state definitions identify the subscription, destination, and specific Adabas files to use in an Event Replicator for Adabas initial-state run.

To maintain initial-state definitions using DDKARTE statements of the Event Replicator Server startup job, read INITIALSTATE Parameter. To maintain initial-state definitions using the Adabas Event Replicator Subsystem, read Maintaining Initial-State Definitions.

Not required.

If you want initial-state data produced in an Event Replicator for Adabas run, only one initial-state definition is required. Otherwise, no initial-state data definition is required.

IQUEUE The input queue on which Event Replicator for Adabas should listen for requests from webMethods EntireX and WebSphere MQ targets.

To maintain IQUEUE definitions using DDKARTE statements of the Event Replicator Server startup job, read IQUEUE Parameter. To maintain IQUEUE definitions using the Adabas Event Replicator Subsystem, read Maintaining Input Queue (IQUEUE) Definitions.

Not required.

At least one IQUEUE definition is required for every EntireX Communicator or WebSphere MQ target you intend to use. If webMethods EntireX or WebSphere MQ are not used, no IQUEUE definition is required.

GFB

A global format buffer (GFB) definition stored separately for use in SFILE definitions. You can specify GFBs manually or generate them using Predict file definitions. When you generate them, a field table is also generated.

While a format buffer specification is required in a subscription's SFILE definition, a stored GFB definition does not need to be used. The SFILE definition could simply include the format buffer specifications it needs.

To maintain GFB definitions using DDKARTE statements of the Event Replicator Server startup job, read GFORMAT Parameter. To maintain GFB definitions using the Adabas Event Replicator Subsystem, read Maintaining GFB Definitions.

Not required.

No GFB definition is required. If a global format buffer is needed, at least one GFB definition is required.

resend buffer A resend buffer that can be used by any subscription to expedite the retransmission of a transaction.

To maintain resend buffer definitions using DDKARTE statements of the Event Replicator Server startup job, read RESENDBUFFER Parameter. To maintain resend buffer definitions using the Adabas Event Replicator Subsystem, read Maintaining Resend Buffer Definitions.

Not required.

No resend buffer definition is required. If you elect to retransmit a transaction, at least one resend buffer definition is required.

transaction filter A filter definition that can be used to filter the records used for replication based on the values of fields in those records.

To maintain transaction filter definitions using DDKARTE statements of the Event Replicator Server startup job, read FILTER Parameter. To maintain transaction filter definitions using the Adabas Event Replicator Subsystem, read Maintaining Transaction Filter Definitions.

Not required.

No transaction filter definition is required. If you want to use a transaction filter to filter records used in replication, at least one transaction filter definition is required.

The applicable definitions and the sequence in which they should be set up varies, depending on the destination. Five destinations are supported in the Event Replicator for Adabas: Adabas, webMethods EntireX, IBM WebSphere MQ, File, and Null. The following table describes each of these destination types and lists the definitions that apply to the destination in the order in which they should be defined.

Destination Type Description Definition List and Order of Creation
Adabas Data is replicated to one or more Adabas files.
  1. destination definitions, as necessary (referenced by subscription definitions)

  2. global format buffer definitions, if needed (can be referenced by the SFILE definitions)

  3. subscription definition, including at least one SFILE definition

  4. one or more SFILE definitions (included in the subscription definition)

  5. initial-state definition

webMethods EntireX Replicated data is written to an output queue via webMethods EntireX.
  1. destination definitions, as necessary (referenced by subscription definitions)

  2. IQUEUE definition

  3. global format buffer definitions, if needed (can be referenced by the SFILE definitions)

  4. subscription definition, including at least one SFILE definition

  5. one or more SFILE definitions (included in the subscription definition)

  6. initial-state definition

File Replicated data is written to the CLOG, using TLOG URBLTDOD records.
  1. destination definitions, as necessary (referenced by subscription definitions)

  2. global format buffer definitions, if needed (can be referenced by the SFILE definitions)

  3. subscription definition, including at least one SFILE definition

  4. one or more SFILE definitions (included in the subscription definition)

  5. initial-state definition

WebSphere MQ Replicated data is written to an output queue via IBM WebSphere MQ.
  1. destination definitions, as necessary (referenced by subscription definitions)

  2. IQUEUE definition

  3. global format buffer definitions, if needed (can be referenced by the SFILE definitions)

  4. subscription definition, including at least one SFILE definition

  5. one or more SFILE definitions (included in the subscription definition)

  6. initial-state definition

Null Data replication is tested without actually sending the data to a destination.
  1. destination definitions, as necessary (referenced by subscription definitions)

  2. global format buffer definitions, if needed (can be referenced by the SFILE definitions)

  3. subscription definition, including at least one SFILE definition

  4. one or more SFILE definitions (included in the subscription definition)

  5. initial-state definition

Step 2. Customize the Event Replicator Server Startup JCL

Once the replication definitions have been defined for your Event Replicator Server, customize the startup JCL to identify where the replication definitions should be found for the Event Replicator Server run.

  1. Change the setting for the ADARUN parameter RPLPARMS to "BOTH", "FILE", or "PARMS". The RPLPARMS parameter identifies where the replication definitions (initialization parameters) should be read from:

    • If you have specified and intend to maintain your replication definitions solely in DDKARTE statements of the Event Replicator Server startup job, specify the value of RPLPARMS as "PARMS".

    • If you have specified and intend to maintain your replication definitions solely in a Replicator system file associated with this Event Replicator Server, specify the value of RPLPARMS as "FILE".

    • If you have specified and intend to maintain your replication definitions in both DDKARTE statements of the Event Replicator Server startup job and a Replicator system file associated with the Event Replicator Server, specify the value of RPLPARMS as "BOTH".

      Note:
      In this case, the DDKARTE statements in the Event Replicator Server startup job are read after the definitions in the Replicator system file. Therefore the DDKARTE initialization parameter settings will override any replication definitions in the Replicator system file.

    Read Adabas Initialization (ADARUN) Parameters for further details.

  2. If one or more WebSphere MQ queues will be used by the Event Replicator Server, ensure all load libraries in the Event Replicator Server STEPLIB or JOBLIB concatenation are APF-authorized.

  3. If tracing is enabled for a destination class or user exit (using the TRACE keyword parameter of the DCLASSPARM parameter), be sure to include the following JCL statement in the startup JCL of the Event Replicator Server:

    //DDTRACE1 DD   SYSOUT=X

    For more information about the DCLASSPARM parameter, which is valid only for webMethods EntireX or WebSphere MQ destinations, read DCLASSPARM.

  4. If you choose to automate Replay Utility (ADARPL) processing by the Event Replicator Server for specific subscriptions, you need to add the DDJCLIN and DDJCLOUT JCL statements in the Event Replicator Server startup JCL. For complete information on the Event Replicator Server startup JCL updates required for automated ADARPL processing, read Automating Replay Processing.

Step 3. (Optional) Modify the Sample Subscription User Exit

If appropriate, modify the sample subscription user exit located in the ARFvrs.SRCE library and assemble. Ensure the subscription user exits are in the Event Replicator Server job STEPLIB concatenation. See ARFvrs.JOBS (z/OS), ARFvrs.LIBR (z/VSE), or ARFvrs.SRC (BS2000) for sample job ASMUSERX that can be used to assemble the subscription user exit. Refer to the section entitled Using the Event Replicator Server Subscription User Exit for detailed information on using the exit.

Once the user exit is modified and assembled, it can be called during replication runs. For each combination of subscription and file, the user exit to be called can be specified using the SFSEXIT initialization parameter (file-related parameter of the subscription) in the Event Replicator Server startup job.

Step 4. Restart the Event Replicator Server

Stop and restart the Event Replicator Server to pick up the replication definitions and any subscription user exit specifications you have added.

Note:
If you use a Replicator system file to store your replication definitions, you can use the RPLREFRESH command to refresh resource definitions in your Event Replicator Server configuration while the Event Replicator Server is running. For more information, read RPLREFRESH Command.

Step 5. Modify the JCL for the Adabas Database and Restart It

Add the ADARUN parameter REPLICATION=YES to the Adabas nucleus job containing the files available for replication. Add the LRPL parameter for setting the size of the Adabas nucleus replication pool. The replication pool in the Adabas nucleus does not necessarily need to be the same size as the replication pool in the Event Replicator Server. For performance, Software AG recommends setting LRPL to a relatively large value (e.g. LRPL=30M). For more information about these parameters, read Pertinent ADARUN Parameters.

For BS2000 installations, if the database is an Adabas version 8 database, set the ADARUN SUBMPSZ parameter large enough to accommodate the LRPL parameter above. Be sure also to add the ARFvrs.MOD library to the BLSLIB or to the Adabas nucleus to be replicated.

When all modifications have been made, restart the Adabas database.

Step 6. Start Replication Processing

Start replication processing in any of the following ways, as needed for your organization: