The following topics provide information for troubleshooting and resolving the most commonly encountered problems you may encounter as you implement a replication solution.

The following table describes resources available to help you solve problems.

You must first diagnose a problem before you can fix it. The following checklist contains items to help you diagnose problems with DataExchange.

Continue reading for details about each checklist item.

Unpredictable results can occur if you set up multiple First Sites per replication network. Install only one First Site per replication network.

If you have activated databases that are located under C:\ProgramData\Actian\Zen\Replication, first deactivate them then delete the replication template with the Template Remover wizard. If you do not deactivate the database then remove the template, uninstall leaves the database files and the associated replication files. The remaining files do not cause any problems but you may prefer to reclaim physical storage by deleting them. You may delete the files manually if you want. Remember, also, to remove the DSN associated with the database.

Zen System Analyzer (PSA) is a diagnostic utility included with the Zen database engine. PSA can be used as a stand-alone diagnostic tool to help you troubleshoot network problems.

The Zen database engine must be running to perform replication.

The DataExchange replication engine must be running to perform replication. The engine will not run, for example, if a temporary license has expired.

Use the Zen License Administrator utility to determine if you have a permanent license installed for DataExchange or to see if a temporary license has expired. See the License Administrator topic in Zen User’s Guide.

DataExchange allows you to enable event logging. You may capture the activity of the DataExchange Monitoring Tools, DataExchange Manager, and DataExchange Replication Engine. Additionally, DataExchange keeps a messages log and an installation log.

All logs are text files and have a file extension of .log for the most current one saved. The files produce any mix of data: Information, Warning, Error, and Debugging. You can choose verbose (as opposed to terse) messages. Verbose messages contain the name of the program and a line number within the program to help you debug situations. Verbose applies only to the Debug logging level.

The DataExchange replication engine (DRE) records its operations in the file dre.log, located by default in C:\ProgramData\Actian\Zen\Replication\LogFiles. You can review replication activity in this log from ZenCC by right-clicking the Replication icon under the Databases branch and selecting Statistics and Log Views. You can also use a text editor to open the log file directly.

You can set a number of log file options in DataExchange Manager. You can change the default logging location. You can also change the default log size and the default number of files kept as history. For instructions, see DataExchange Manager Tasks.

If you set the maximum log size to zero, or no limit, the log will increase in size to whatever capacity the physical storage allows. We recommend that you do not set a maximum log size of zero except for troubleshooting. Even then, avoid using the no limit setting for an extended period (typically, more than four hours). The DRE log, for example, can grow rapidly depending on the type of logging being performed (such as Debug logging), the frequency of replication, and the number of sites replicating.

In the case of dre.log, when the log file reaches its maximum size, the file is reassigned to the next history file name. For example, when dre.log reaches its maximum size, it gets renamed to dre.LO1 and a new dre.log gets created. The dre.log file is then empty and starts acquiring data once more. When the maximum size is again reached, dre.LO1 gets renamed to dre.LO2, dre.log gets renamed to dre.LO1, and a new dre.log file is again empty and able to acquire data. The Maximum Logs to Keep setting determines the extent of the history retained: LO1, LO2, LO3, and so forth.

Other DataExchange components automatically start a new log file when the utility or service executes. Each time the utility is activated the associated filename.log file is copied to filename.LO1. The utility then begins logging in the now empty filename.log file. Again, the Maximum Logs to Keep setting controls retention.

The DataExchange Manager and DataExchange Monitoring Tools have a logging dialog that allows you to change the logging settings.

The following table describes the content of the various log files.

The following topics pertain to replicating data:

If you delete, disable, or modify a schedule, the other replication sites are not aware of this because replication does not take place. The notification agent on the other sites continues to contact the scheduling site. If the scheduling site is down or unreachable, the agent sends a failure alert. The alert is false because the schedule no longer applies.

To prevent such false alerts, manually initiate replication after you delete, disable, or modify a schedule. The replication ensures that the schedule changes get replicated. Alternatively, if your entire replication network no longer needs replication, deactivate all replication sites on the network.

This situation occurs if you change a schedule remotely. For example, you start DataExchange Manager on site B and use it to change the schedule on site A. The replication engine on site A will not use the new settings until you restart the engine. The notification agent, however, uses the new schedule without having to be restarted. The agent properly notifies of replication being off schedule.

To prevent this situation, do not update schedules remotely.

If your dynamically created tables are not being replicated, verify that the file matching patterns in the dCNF table are correct. DataExchange provides a utility, Dxdynpath, to help you verify file matching patterns. See dxdynpath.

Note that relative paths are relative to a home directory that contains data dictionary files (DDFs) recognized by DataExchange.

SQL triggers are a type of stored procedure that are automatically executed when data in a table is modified with an INSERT, UPDATE, or DELETE. (Stored procedures are SQL statements that are predefined and saved in the database dictionary.)

Replication updates the base table before updating the dependent tables. This sequence maintains the correct foreign key relationships. In the case of the sample database Tracker, for example, the Region table is updated before the Employee table.

For illustration, suppose you have a database with a base table A and a dependent table B (table B has a foreign key relationship to table A). You create a trigger that updates base table A when a new record is inserted into table B.

Partner site 1 inserts a new record into table B, causing the trigger to execute. Table A is updated on Partner Site 1. Then you replicate Partner Site 1 with your other sites.

On the other sites, replication updates table A, then inserts a new record into table B, causing the trigger in table B to execute and again attempt to update table A. This may not be the desired behavior because the replication engine has already updated the record in table A with changes made on Partner Site 1.

Definitive rules concerning triggers and replication cannot be given. In general, carefully consider each trigger that is part of a replicated database. Make certain that the trigger’s functionality and the behavior of replication are compatible to ensure the outcome you desire.

The template data prepared for replication during design is marked differently (with timestamps and other internal methods) than the data prepared during activation. The replication engine resolves the differences during replication. In a few cases, data conflicts may result between how you activate your First Site versus how you activate your Partner Sites.

For data files with 4096-byte page size, you are limited to 119 index segments per file. Because each indexed nullable column with true NULL support requires an index consisting of 2 segments, you cannot have more than 59 indexed nullable columns in a table (or indexed nullable true NULL fields in a Btrieve file). This limit is smaller for smaller page sizes.

Any file created with Zen, with file create mode set to 7.x, and TRUENULLCREATE set to the default value of On, has true null support. Files created using an earlier file format, or with PSQL 7, or with TRUENULLCREATE set to Off, do not have true null support and do not have this limitation.

See SQL Engine Reference for more information about TRUENULLCREATE.

Central to any replication solution is its ability to detect and resolve conflicts when they occur. The best method of handling conflicts is a preventative one: avoid conflicts by design. In addition to this, DataExchange includes a default last-in-wins policy. By maintaining time stamps in control tables and synchronizing clocks on replication sites, an accurate account of when records where inserted, updated, and deleted is kept. The replication engine is responsible for enforcing the conflict policy (and logging conflicts) as they occur.

In addition, DataExchange provides an interface with which you can define your own conflict resolution. You can design the appropriate conflict resolution for any set of business rules and provide the resolution through an event handler DLL. The DLL overrides or extends the functionality of the replication engine.

Data conflicts are divided into types by DataExchange. Each conflict is recorded in the log dre.log. You can read the log entries and determine what, if any, action needs to be taken. Messages similar to the following appear in the log. It contains the type of conflict, the key of the record involved, and how the conflict was resolved.

When a conflict occurs and a record must be overwritten, the newest record is always used. To alter this behavior, you can register your customized Event Handler DLL with the replication engine.

The log file of the site where the record was not updated will contain a message saying that the record at the partner Site was updated (as above). At the site where a record was overwritten, messages similar to the following show the data value that was updated as well as the new value (in this case the last name Yin was replaced by the last name Yan:

A Type I conflict occurs when a record has been updated at both sites since the last replication session. When this occurs the newer record is replicated and a log message similar to the following is generated:

Variations of this conflict type include the following possible scenarios and associated log messages:

Type V conflicts occur when there is an error with the starter data at each Site (the data that already exists in the database when your database application is activated).

If starter data exists at one Site and not at the other, the starter data is replicated to the other site. If the existing starter data is different, however, a type V conflict is logged and replication stops:

Conflicts between a record inserted or updated at one site and deleted at another site are treated as a Type VI conflict. During conflict processing, if all records are updated at one site (or the record was inserted) and the record is deleted at the other site, a type VIa conflict is logged and the most recent operation wins. If any records are not updated, then the delete operation must always win. This type VI conflict needs to be resolved in this way because there is insufficient information available to reinsert the entire record at the site where the record was deleted. The following describes the possible scenarios and the associated log messages:

Note that if conflicts were successfully resolved during a replication cycle, a message similar to the following appears in the replication log file:

The best way to avoid primary key conflicts is to design your source database with unique primary keys. If you are using an existing database for replication that does not have unique primary keys, you can designate primary keys with the Control Center.

A primary key conflict occurs when two rows have been inserted into two different activated databases that have the same primary key. Because each row could potentially have relevant data, the replication engine stops the replication and will not modify these rows.

You will see the following errors the dre.log file on the system that detects the primary key conflict. For this example, the primary key conflict has been detected on the Region table of the sample database Tracker.

All other systems that attempt to replicate with this system will fail with the Error:

Remedying a primary key conflict requires manual intervention. You must update the primary key of one of these conflicting rows to a new, unique value. Following that, you must start a replication session.

For instance, from the example above, the conflict occurred with primary key 8. So, on one of the databases involved you would update the primary key to 9, a unique key value for the table. Then you would replicate the two systems together.

Note that during this replication, the replication control tables are cleaned up to correct the primary key conflict, and the following is written to the dre.log file as a warning message. Its purpose is to let you know that the primary key conflict was successfully resolved.

So, what transpired in terms of data in the database? Here is the contents of the Region table throughout the process. First, a row with the same key is inserted onto each site.

We replicate and we get the primary key conflict, replication is stopped, no tables are updated.

Update one of the sites to a new unique value.

Replicate the new change.

Now both sites are replicated to a consistent copy and no data has been lost.

The notification agent is installed only if the machine contains the Zen Server product. If the notification agent is not sending email, check the following:

The SMTP mail server must also be functioning correctly. If required, verify that the SMTP mail server is sending and receiving email correctly. Reference the documentation supplied for your SMTP server software or check for testing procedures on vendor websites.