This document covers the following topics:
This section describes how to start Event Replicator Target Adapter in Windows and in UNIX.
To start Event Replicator Target Adapter in Windows:
Click on the option in the Programs/Software AG Event Replicator Target Adapter submenu found on the Windows Start menu.
This will set up your Event Replicator Target Adapter environment properly and start up Tomcat. A new console window is opened on the workstation in which you can review the Event Replicator Target Adapter startup messages.
If this the first time you have started the Event Replicator Target Adapter since it was installed and if you have not yet configured it, the following message appears on the console:
The Event Replicator Target Adapter needs to be configured. Run the Administration Tool. Read the documentation for details.
Be sure to follow these instructions prior to activating the Event Replicator Target Adapter or Event Replicator Target Adapter processing will not occur correctly. For information about configuring the Event Replicator Target Adapter, read Configuring the Messaging System for Event Replicator Target Adapter and Configuring the RDBMS Databases for Event Replicator Target Adapter.
Once the Event Replicator Target Adapter has been configured, the following message appears on the console:
Stop and restart the Event Replicator Target Adapter
to pick up configuration changes.
If Event Replicator Target Adapter has already been configured, stopped, and restarted, the following message appears on the console:
The Event Replicator Target Adapter is started and waiting replication data
To start Event Replicator Target Adapter in UNIX:
Verify that you have set up the environment for Software AG products by running sagenv.new, as described in the UNIX installation instructions, elsewhere in this section.
Enter startupart.sh at the UNIX
prompt.
This will set up your Event Replicator Target Adapter environment properly and start up Tomcat. A log file is set up in which you can review the Event Replicator Target Adapter startup messages.
Review the log file by typing the following commands:
cd $ARTDIR/$ARTVERS/logs tail -f sqlrep.log
Notes:
tail command
in order to see the most recent messages in the log. For complete information
about log file retention, read sqlrep.log Log File
Retention.
If this the first time you have started the Event Replicator Target Adapter since it was installed and if you have not yet configured it, the following message appears on the console:
The Event Replicator Target Adapter needs to be configured. Run the Administration Tool. Read the documentation for details.
Be sure to follow these instructions prior to activating the Event Replicator Target Adapter or Event Replicator Target Adapter processing will not occur correctly. For information about configuring the Event Replicator Target Adapter, read Configuring the Messaging System for Event Replicator Target Adapter and Configuring the RDBMS Databases for Event Replicator Target Adapter.
Once the Event Replicator Target Adapter has been configured, the following message appears on the console:
Stop and restart the Event Replicator Target Adapter
to pick up configuration changes.
If Event Replicator Target Adapter has already been configured, stopped, and restarted, the following message appears on the console:
The Event Replicator Target Adapter is started and waiting replication data
Once Event Replicator Target Adapter has been installed and configured and your relational database has been set up properly, you can activate Event Replicator Target Adapter processing.
To activate Event Replicator Target Adapter processing:
Verify that appropriate Event Replicator queue definitions have been set up for the messaging system (EntireX Communicator or MQSeries) you are using. For more information about maintaining queue definitions, read the documentation at one of the following links:
To maintain queue definitions using the Adabas Event Replicator Subsystem, read Maintaining Input Queue (IQUEUE) Definitions.
To maintain queue definitions using Event Replicator Administration, read Maintaining Input Queue (IQUEUE) Definitions.
Edit the subscription definitions that manage the replicated data you want applied to your relational database. For more information about maintaining subscription definitions, read the documentation at one of the following links:
To maintain subscription definitions using the Adabas Event Replicator Subsystem, read Maintaining Subscription Definitions.
To maintain subscription definitions using Event Replicator Administration, read Maintaining Subscription Definitions.
Verify that a global format buffer and field table have been generated for the subscription definition. To use Event Replicator Target Adapter, you must use generated global format buffers. For more information about generating a global format buffer and field table for a subscription, read the documentation at one of the following links:
To generate a global format buffer and field table using the Adabas Event Replicator Subsystem, read Generating a GFB.
To generate a global format buffer and field table using Event Replicator Administration, read Generating a GFB.
Note:
If you want to use UTF-8 character encoding, you must verify that
your GFB field lengths are increased as required to accommodate the character
set referenced by the code page you select and the data requested in the GFB.
You can increase these field lengths manually by editing the GFB itself or by
editing the Predict file or data definition module (DDM) used when the GFB is
generated.
Save the subscription definitions.
Edit the destination definitions used by the subscriptions you modified in the previous steps.
Verify that the destination class (DCLASS parameter) is specified as "SAGTARG" for each destination.
Optionally, specify keyword "NOSPRE" for the destination class parameter (DCLASSPARM parameter) if you do not want the subscription name to prefix the names of the tables produced by the Event Replicator Target Adapter. When "NOSPRE" is specified, the schema file name (Predict view name) alone is used for the table names; when "NOSPRE" is not specified, the subscription name prefixes the Predict view name in the table names.
For more information about specifying the destination class in a destination definition, read the documentation at one of the following links:
To modify the destination definition using DDKARTE statements, read DESTINATION Parameter.
To modify the destination definition using the Adabas Event Replicator Subsystem, read Adding Destination Definitions.
To modify the destination definition using Event Replicator Administration, read Adding Destination Definitions.
Save the destination definitions.
Stop and restart the Event Replicator Server or refresh the destination and subscription definitions, as described in RPLREFRESH Command.
Activate the destination definitions and the subscription definitions you modified in the previous steps. For more information, read one or more of the following sections:
To activate destination and subscription definitions using Adabas Online System (AOS), read Managing Replication Definitions from AOS.
To activate destination definitions using Event Replicator Administration, read Activating and Deactivating Destination Definitions.
To activate subscription definitions using Event Replicator Administration, read Activating and Deactivating Subscription Definitions.
If the subscription definitions are already activated, deactivate them first and then reactivate them to pick up the changes made in these steps.
Event Replicator Target Adapter processing is activated and replicated Adabas data will be transformed and applied to your RDBMS.
To deactivate Event Replicator Target Adapter processing:
Deactivate the subscription definitions that manage the replicated data you are transforming and applying to your relational database. For more information about deactivating subscription definitions, read the documentation at one of the following links:
To deactivate subscription definitions using Adabas Online System (AOS), read Managing Replication Definitions from AOS.
To deactivate subscription definitions using Event Replicator Administration, read Activating and Deactivating Subscription Definitions.
Event Replicator Target Adapter processing is deactivated.
This section describes how to shut down the Event Replicator Target Adapter in Windows and UNIX environments.
To shut down Event Replicator Target Adapter in Windows environments:
Click on the option in the Programs/Software AG Event Replicator Target Adapter submenu found on the Windows Start menu.
This will shut down your Event Replicator Target Adapter environment properly and shut down Tomcat. The Event Replicator Target Adapter console window is closed.
To shut down Event Replicator Target Adapter in UNIX environments:
Verify that you have set up the environment for Software AG products by running sagenv.new, as described in the UNIX installation instructions, elsewhere in this section.
Enter shutdownart.sh at the UNIX
prompt.
This will set up your Event Replicator Target Adapter environment properly and shut down Tomcat.
Using the Adabas Event Replicator Subsystem or Event Replicator Administration, you can manually submit requests to the Event Replicator Target Adapter that initiate an initial-state request to populate the relational database tables. For information on using the Adabas Event Replicator Subsystem to do this, read Populating the RDBMS Tables . For information on using Event Replicator Administration to do this, read Populating the RDBMS Tables .
Using the Adabas Event Replicator Subsystem or Event Replicator Administration, you can manually submit requests to the Event Replicator Target Adapter that delete the data in all relational database tables associated with the request, but leave the tables in place. This effectively clears the tables. For more information on using the Adabas Event Replicator Subsystem to do this, read Clearing (Refreshing) the RDBMS Table Data. For information on using Event Replicator Administration to do this, read Clearing (Refreshing) the RDBMS Table Data.
Using the Adabas Event Replicator Subsystem, you can manually submit requests to the Event Replicator Target Adapter that delete the data and remove the tables associated with the request from the relational database. For more information on using the Adabas Event Replicator Subsystem to do this, read Deleting (Dropping) RDBMS Tables . For information on using Event Replicator Administration to do this, read Deleting (Dropping) RDBMS Tables .
You can use the LOAD and UPDATE functions of the Adabas ADALOD utility to add and update data in the RDBMS tables. In both cases, you must specify RPLLOAD=YES when running the utility to ensure that the loaded data is automatically replicated.
The processing of ADALOD data for Event Replicator Target Adapter is the same as the processing of regularly replicated data for Event Replicator Target Adapter. In other words, the data that is loaded is processed by subscriptions; if a subscription is activated, includes a generated global format buffer field table for the Adabas file being loaded or updated, and includes an activated destination with a destination class type of "SAGTARG", the data is replicated and sent as an XML message to the Event Replicator Target Adapter for processing.
Before you decide to add data to the RDBMS tables using the ADALOD utility, consider the following potential problems:
All records processed by ADALOD and sent to the Event Replicator Target Adapter with action types of "Insert" are treated by the Event Replicator Target Adapter as if they were new records, unless the RESEND flag associated with the incoming data from Event Replicator for Adabas has been set to YES. If the RESEND flag is set to YES, checks are performed to determine whether a record already exists with the same primary key. If it does, the existing row is deleted and a new one is inserted for the new incoming data.
Note:
If, during Insert processing, the RESEND flag is set to NO and a
record with the same primary key as an existing record is found in the RDBMS
tables, Event Replicator Target Adapter processing will fail.
Performance problems can occur due to the massive numbers of records that might be sent if you use the ADALOD utility and the Event Replicator Target Adapter to add records to the RDBMS tables. A single subscription activated for Event Replicator Target Adapter processing can update multiple RDBMS tables simultaneously (depending on the number of pertinent SFILE definitions and the number of different generated global format buffer field tables that exist in the subscription). If multiple subscriptions are activated for Event Replicator Target Adapter processing, then, the amount of traffic on your system could be quite high.
To limit the number of ADALOD records replicated through the Event Replicator Target Adapter, you can deactivate some of the subscriptions, use transaction filter definitions, or elect not to drop an RDBMS table prior to the ADALOD utility run (in this case, all insert transaction will fail if the primary key already exists for that table).
This section covers the following topics:
All Event Replicator Target Adapter log files are stored in the logs subdirectory of your Event Replicator Target Adapter installation. The Event Replicator Target Adapter log file name is sqlrep.log, which contains all current log messages. If you have a problem, please keep this log file.
In addition, several other kinds of log files may be found at this location:
If you requested that EntireX Communicator or MQSeries tracing occur when you configured the messaging system for Event Replicator Target Adapter, the etb_trace.log file (for EntireX Communicator) or the mqs_trace.log file (for MQSeries) will be created at this location.
If you requested that all incoming Event Replicator messages be captured for debugging purposes when you configured the messaging system for Event Replicator Target Adapter, an etb_capture.log file (for EntireX Communicator) or an mqs_capture.log file (for MQSeries) will be created at this location.
When Event Replicator Target Adapter shuts down, the LAST_TRANS.log file is created. This file lists statistics about the Event Replicator Target Adapter session and about the last transaction processed during the session. The same information is also written to sqlrep.log.
On Windows systems, the sqlrep.log file can be reviewed using a text editor. On UNIX systems, it can be reviewed by running the sqlreplog.sh script. You can control the level of log messages written to the sqlrep.log file; read Setting Log Levels for more information.
Each time you start up the Event Replicator Target Adapter, a new sqlrep.log file is created. The previously-existing log file will be renamed sqlrep.log.1. All previous log files are also retained and renamed, so that the lowest numbered file is the most recent historical log file (the sqlrep.log file with no number is always the current log file). In other words, if an sqlrep.log and an sqlrep.log.1 file already exist when the Event Replicator Target Adapter is started, the following sequence of events occurs:
File sqlrep.log.1 is renamed to sqlrep.log.2.
File sqlrep.log is renamed to sqlrep.log.1.
A new sqlrep.log file is created for the new Event Replicator Target Adapter session.
When an sqlrep.log file reaches 10MB in size, it is renamed sqlrep.log.1, and all previous log files are retained and renamed as well, as described above.
A maximum of 99,999 log files can be retained. When this maximum is reached and a new sqlrep.log file is created, the sqlrep.log.99999 file is overwritten with data from the sqlrep.log.99998 log file.
When Event Replicator Target Adapter shuts down, the LAST_TRANS.log file is created. This file lists performance statistics about the Event Replicator Target Adapter session and about the last transaction processed during the session. The same information is also written to sqlrep.log.
The following is an example of the output you will find in the LAST_TRANS.log file.
Start Up Date : Wed May 10 10:44:20 EDT 2006 Shut Down Date : Wed May 10 10:47:53 EDT 2006 Source Message : 189 Source Message Length : 1746784 bytes Source Receiving Time : 25591 ms Source Commit/Rollback Time : 2952 ms Total Source Time : 28543 ms Source Percent Time : 16 % ART Translate/XML Time : 38841 ms ART Internal Processing Time : 48663 ms Total ART Time : 87504 ms ART Percent Time : 53 % Target RDBMS Transaction : 55 Target RDBMS Commands : 12168 Target RDBMS Transaction Time: 52796 ms Target RDBMS Percent Time : 31 % Total Processing Time : 168843 ms Idle Time : 44016 ms Target RDBMS Retry Time : 0 ms Total Time : 212859 ms Last Committed Transaction : REPTOR: Subs: SUB1 File: EMPLOYEES Committed: 2006/04/12-21:59:08.538683
When the Event Replicator Target Adapter is installed, all messages that display to the console are automatically written to the Windows or UNIX system event logs (as appropriate). You can control the level of log messages written to the Windows and UNIX event logs; read Setting Log Levels for more information.
You can set the log level of messages written to the sqlrep.log log file, the Windows and UNIX event logs, and to the console. Three log levels are available (listed in order of settings that result in the most logging to those resulting in the least logging):
| Log Level | Description |
|---|---|
| DEBUG | Only debugging, informational, warning, error,
and fatal messages are logged or displayed.
Note: |
| INFO | Only informational, warning, error, and fatal messages are logged or displayed. |
| ERROR | Only error and fatal messages are logged or displayed. |
To change the log level of messages sent to the console:
Edit the log4j.properties file. This file is located in the sqlrep\WEB-INF\classes directory wherever you installed Event Replicator Target Adapter.
Locate the line in the log4j.properties that reads:
log4j.appender.CONSOLEAppender.Threshold=loglevel
This line in the file controls the level of Event Replicator Target Adapter log messages sent to the console. By default, the log level is set to ERROR.
Change the log level as needed. Valid log level values are ERROR, INFO, and DEBUG, as described earlier in this section. For example, the following setting would display informational and error messages on the console.
log4j.appender.CONSOLEAppender.Threshold=INFO
Note:
Setting the log level to DEBUG can impact performance.
To change the log level of messages written to the
sqlrep.log file:
Edit the log4j.properties file. This file is located in the sqlrep\WEB-INF\classes directory wherever you installed Event Replicator Target Adapter.
Locate the line in the log4j.properties that reads:
log4j.appender.FILEAppender.Threshold=loglevel
This line in the file controls the level of Event Replicator Target Adapter log messages written to the sqlrep.log file. By default, the log level is set to ERROR.
Change the log level as needed. Valid log level values are ERROR, INFO, and DEBUG, as described earlier in this section. For example, the following setting would write all error, informational, and debugging Event Replicator Target Adapter messages to the sqlrep.log file.
log4j.appender.FILEAppender.Threshold=DEBUG
Note:
Setting the log level to DEBUG can impact performance.
To change the log level of messages written to the Windows or UNIX
system event logs:
Edit the log4j.properties file. This file is located in the sqlrep\WEB-INF\classes directory wherever you installed Event Replicator Target Adapter.
In Windows environments, locate the line in the log4j.properties that reads:
log4j.appender.NTAppender.Threshold=loglevel
This line in the file controls the level of Event Replicator Target Adapter log messages written to the Windows event log. By default, the log level is set to ERROR.
In UNIX environments, locate the line in the log4j.properties that reads:
log4j.appender.UNIXAppender.Threshold=loglevel
This line in the file controls the level of Event Replicator Target Adapter log messages written to the UNIX system event log. By default, the log level is set to ERROR.
Change the log level as needed. Valid log level values are ERROR, INFO, and DEBUG, as described earlier in this section. For example, the following setting would write all error, informational, and debugging Event Replicator Target Adapter messages to the Windows event log.
log4j.appender.NTAppender.Threshold=DEBUG
Note:
Setting the log level to DEBUG can impact performance.
This step pertains to UNIX systems only. If you are working on a Windows system, you can ignore this step.
In UNIX environments, an additional step must be taken that has system-wide implications. The UNIX syslog.conf file controls the level of logging for the entire UNIX system, so any log level settings set by the Event Replicator Target Adapter for the UNIX system event log (in the previous step) may be overridden by the syslog.conf settings. To fully change the log level settings, you must have your UNIX system administrator update the syslog.conf file as follows and restart the daemon:
| To set the log level to: | Update syslog.conf to include an entry for: |
|---|---|
| DEBUG | user.debug |
| INFO | user.info |
| ERROR | user.err |
The syslog.conf entries should direct these message levels to appropriate UNIX system directories. For complete information on updating the syslog.conf file, refer to your UNIX documentation.
