Replication Deployment
The following topics provide several tutorials to show how to deploy a database for replication:
All examples in the DataExchange documentation use a 64-bit Windows system with an installation location of C:\Program Files (x86)\Actian\Zen.
Deployment Process
Most users run the DataExchange Deployment Wizard to create and deploy a replication network. This wizard automatically takes care of most of the things needed for replication.
One way to learn the DataExchange replication deployment in deeper detail is to step through an example using the sample database Demodata that is included with Zen. The example concentrates on what to do. You can then learn about why you perform certain actions by reading Working with Your Database.
This topic illustrates a working example of preparing a database for real-time backup between two systems. It involves the use of the DataExchange utility DXdeploy and the manual copying of a file.
The typical deployment process has four steps:
1. Edit the XML deployment descriptor file used by the DXdeploy utility.
2. Run DXdeploy on the First Site, setting the XML descriptor file as a parameter.
3. Copy the replication-enabled files from the First Site to the Partner Site.
4. Run DXdeploy on the Partner Site, setting the same XML descriptor file used for the First Site.
An optional fifth step involves setting up a replication schedule with DataExchange Manager.
Tip... The deployment process described here can also be performed using DX Deployment Wizard, which provides a graphical user interface and partial automation of replication deployment. For more information, see Replication Deployment Using the DX Deployment Wizard.
Replication Deployment Using the DX Deployment Wizard
DataExchange Deployment Wizard is the simplest and quickest way to create and deploy a replication network. The wizard is used on both First and Partner sites and includes a means of creating a replication schedule.
You can open DX Deployment Wizard by selecting it from the Start menu or from Control Center by selecting DataExchange > Deployment Wizard. Before you use the wizard, be sure to follow the instructions under Administrator Rights for DataExchange users.
To get ready to use DX Deployment Wizard, first write down the following deployment attributes. As you run the wizard, you will enter these items at various points in the process.
• Project Name – this corresponds to a specific database. If your goal is to replicate a database named mydatabase, then you may want to call the project mydatabase project or something similar.
• Network Name – this refers to the name you have chosen to represent the grouping of replication sites that participate in replication.
• Release Name – this is similar to a version number for the design of the replication database.
• DSN – this specifies the data source name (DSN) to be associated with the data files deployed for replication. The DSN must be unique on each site.
• Directories and file names of data – this specifies the directories and data files to be included in the replication.
The wizard automates almost all of the steps that you must follow in using the DXdeploy utility on the command line. The wizard does require you to do one thing manually:
1. After you run the wizard on the First Site, look for the file projectname.dxb in C:\Program File(x86)\Actian\Zen\Replication\projects. If the project name is mydatabase, as in the example above, this file will be named mydatabase.dxb.
2. Copy the .dxb file to the Partner Site and place it in one of the data directories to be replicated.
3. When you run Deployment Wizard on the Partner Site, it prompts you to select the .dxb file as part of setting up Partner site replication.
For More Advanced Explanation
If you want to find out more about how DataExchange works, see the tutorial Replication Deployment Using DXdeploy with an XML Descriptor File. It steps through replication deployment from the command line using an XML file that contains all needed settings, including the deployment attributes mentioned above.
We expect only advanced users to routinely use the command line method with DataExchange, but it may be useful to those who want a more detailed understanding of the product.
Replication Deployment Using DXdeploy with an XML Descriptor File
This command line tutorial provides a more detailed understanding of the creation and deployment of replication networks in DataExchange. The tutorial uses the Demodata sample database as an example. Demodata is provided with Zen.
The steps presented here focus on what to do rather than why. Afterwards you can read about why how it works in the next topic, Working with Your Database. This topic includes an explanation of the structure and elements of the XML Deployment Descriptor File.
Working with the sample consists of two procedures, each with several tasks:
• Explanation of the XML Deployment Descriptor File
Since this deployment is only an example, it does not show how to set up a replication schedule.
Note: Zen contains security models for Btrieve applications. The example used here assumes that you deploy Demodata on sites with the Classic security model (the default model). If DefaultDB uses either Mixed or Database security, you must ensure that Demodata can be deployed. The easiest way to do this is to disable security by removing the password for DefaultDB on each site where security is set. To do so, in ZenCC right-click DefaultDB and select Properties. Click the Security tab, select the checkbox Disable database security, and click Apply. If you are not logged in to DefaultDB, provide the master password. Click OK. Remember to reenable security for DefaultDB after you complete the example deployment. If you want to retain security, see the tutorial Replicating a Database with Zen Security, which uses Demodata as an example.
Deploying Demodata for Replication
Before you work through this example, be sure you have already installed both a First Site and a Partner Site (backup site) as explained in Installing DataExchange with No Previous Installation.
Tip... So that you can restore Demodata to its original state after this deployment exercise, we recommend saving a copy of the database files before proceeding with this example.
Task 1: Edit the XML descriptor file
1. On the First Site machine, open the folder C:\Program Files (x86)\Actian\Zen\Replication\Docs.
2. Make a copy of the XML descriptor file EXPRESS.XML and rename the copy ExampleRTB.xml.
You may save the file to the location you choose on your First Site machine.
3. Open ExampleRTB.xml in a text editor.
This template file is explained under XML Deployment Descriptor File.
4. Set the machine name or IP address of your First Site. “Localhost” is not permitted as the machine name.
For example, if the name of your First Site is SiteA:
<First
ServerName="SiteA"
ServerName="SiteA"
5. Set the root directory path to the data files on the First Site.
For the First Site DataDirectory, change C:\MYDATA to C:\ProgramData\Actian\Zen\Demodata.
The configuration should now be something similar to the following:
<First
ServerName="SiteA"
DSN="DXDatabase"
DataDirectory="C:\ProgramData\Actian\Zen\Demodata">
ServerName="SiteA"
DSN="DXDatabase"
DataDirectory="C:\ProgramData\Actian\Zen\Demodata">
Because this is just an example, leave the DSN as DXDatabase.
6. Specify the paths to the data files that you want to replicate relative to the root directory in DataDirectory.
The Demodata data files use an .mkd extension, so keep the line <Include Path="*.mkd" />. You may include any extension used by Btrieve files in your Zen environment.
7. Delete the following lines because they do not apply to this example:
<Include Path="*.btr" />
<Include Path="*.dat" />
<Include Path="*.dat" />
Demodata has DDFs, so keep <Include Path="*.ddf" />. Typically, you will want to replicate DDFs. Note that the DSN created by DXdeploy does not use Demodata DDFs but rather uses its own in replication.
8. Set the machine name or IP address of your Partner Site.
Change remote.hostname to your site name or IP address. For example, if the Partner Site machine is SiteB:
<Partner
ServerName="SiteB"
ServerName="SiteB"
9. Set the absolute path to the root directory of the data files on the Partner Site.
For the Partner Site DataDirectory, change C:\MYDATA to C:\Demodata.
The information should now read something like the following:
<Partner
ServerName="SiteB"
DSN="DXDatabase"
DataDirectory="C:\Demodata" />
ServerName="SiteB"
DSN="DXDatabase"
DataDirectory="C:\Demodata" />
Note: The data directory on the Partner Site could be C:\ProgramData\Actian\Zen\Demodata if you want to overwrite the sample database. This example uses a different directory to preserve Demodata as installed by Zen.
10. Save and close the file ExampleRTB.xml.
Task 2: Run DXdeploy on the First Site
Open a command prompt on the First Site and run the following. The string is not case-sensitive.
dxdeploy /Site=First "C:\Program Files (x86)\Actian\Zen\Replication\Docs\ExampleRTB.xml"
As it runs, DXdeploy displays high-level status messages:
• Starting the CreateDSN action
• Starting the Design action
• Starting the Activate action
• Activation done, now synchronizing tables
The file dxdeploy.log in C:\ProgramData\Actian\Zen\Replication\LogFiles records more detail. To view its entries on-screen while DXdeploy runs, you can use the /LOGFILE= option. For example, dxdeploy /Site=First /LOGFILE= ExampleRTB.xml. A space follows the equal sign after LOGFILE=.
DXdeploy is finished when the command prompt reappears, having entered the following message in the log file:
Successfully completed all deployment actions.
Task 3: Verify deployment on the First Site (optional)
You can visually verify that deployment has succeeded.
1. Start ZenCC if it is not already running. (Select Zen Control Center & Documentation from the Start menu.)
The name of the First Site appears under the Engines branch.
2. Expand the First Site branch and its list of databases.
DXDatabase is listed as a database.
3. Expand the DXDatabase branch.
The letter A in the Replication node shows that the database is activated.
Task 4: Copy the Template to the Partner Site
After DXdeploy finishes on the First Site, do the following:
1. From the First Site, copy the file
C:\Program Files (x86)\Actian\Zen\Replication\Docs\ExampleRTB.xml
to the same folder on the Partner Site.
2. On the Partner Site, create the folder C:\Demodata.
3. From the First Site, copy the contents of the directory
C:\Program Files (x86)\Actian\Zen\Replication\Templates\DXDatabase
to C:\Demodata on the Partner Site.
Note: Demodata files reside in a relative location that can be wherever you choose on the Partner Site. Your application may require absolute paths to certain data files. See File Copying for details.
Task 5: Run DXdeploy on the Partner Site
Open a command prompt on the Partner Site and run the following. The string is not case-sensitive.
dxdeploy /Site=Partner "C:\Program Files (x86)\Actian\Zen\Replication\Docs\ExampleRTB.xml"
As it runs, DXdeploy displays high-level status messages:
• Starting the CreateDSN action
• Starting the Design action
• Starting the Activate action
• Activation done, now synchronizing tables
The file dxdeploy.log in C:\ProgramData\Actian\Zen\Replication\LogFiles records more detail. To view its entries on-screen while DXdeploy runs, you can use the /LOGFILE= option. For example,
dxdeploy /Site=Partner /LOGFILE= ExampleRTB.xml
A space follows the equal sign after LOGFILE=.
DXdeploy is complete when the command prompt reappears and when it enters the following message in the log file:
Successfully completed all deployment actions.
When DXdeploy runs on the Partner Site, it also performs an initial replication between the First Site and the Partner Site. The initial replication populates the data on the Partner Site so that it is the same as on the First Site.
You have now successfully deployed Demodata for replication.
XML Deployment Descriptor File
The XML deployment descriptor file is a text file in which you set information for the DXdeploy utility. For Real-Time Backup between two machines, you use the descriptor file EXPRESS.XML. This file is located in C:\Program Files (x86)\Actian\Zen\Replication\Docs. The contents of the file has the following elements and also includes comments not shown here to help document them.
<?xml version="1.0"?>
<DXDeployment>
<Configuration Project="DXProj" Network="DXNet" Release="1.0" Method="1-way">
<Sites>
<First
ServerName="this.hostname" DSN="DXDatabase" DataDirectory="C:\MYDATA">
<Files>
<Include Path="*.mkd" />
<Include Path="*.btr" />
<Include Path="*.dat" />
<Include Path="*.ddf" />
</Files>
</First>
<Partner
ServerName="remote.hostname" DSN="DXDatabase" DataDirectory="C:\MYDATA" />
</Sites>
</Configuration>
</DXDeployment>
<DXDeployment>
<Configuration Project="DXProj" Network="DXNet" Release="1.0" Method="1-way">
<Sites>
<First
ServerName="this.hostname" DSN="DXDatabase" DataDirectory="C:\MYDATA">
<Files>
<Include Path="*.mkd" />
<Include Path="*.btr" />
<Include Path="*.dat" />
<Include Path="*.ddf" />
</Files>
</First>
<Partner
ServerName="remote.hostname" DSN="DXDatabase" DataDirectory="C:\MYDATA" />
</Sites>
</Configuration>
</DXDeployment>
To use this XML file you must always edit it for your situation. The following table explains the elements in the file that may require editing. The default value for some of the attributes may be adequate. With the exception of Exclude Path, DXdeploy requires all of the attributes. DXdeploy is further discussed under dxdeploy.
XML Attribute | Discussion |
|---|---|
Project | A replication design requires names for the replication project, replication network, and project release. These names are of your own choosing to help you identify your replication setup. Project often corresponds to a specific database. If your goal is to replicate a database named mydb, then you may want to call the project mydb project or something similar that helps you remember which database is involved. Note that the three names – project, network, and release – are added to a replication system database used by the replication engine. The replication utilities also use these names to allow or disallow certain actions. For example, designed databases that differ only by release are allowed to replicate together so long as the project names and network names match. |
Network | The replication network is the grouping of replication sites that participate in replication. A name that helps you remember the grouping is very useful. For example, if machines A and B participate, you could name the network Sites A and B or something similar. You may use spaces in this string. |
Release | The release is like a version number for the design of the replication database. Your first design could be version 1, for instance. If you choose to change the design later, then you would create a version 2 and so forth. |
Method | Sets whether replication will be 1-way or 2-way. This setting should match what your license allows. For example, you cannot set 2-way replication with a Real-Time Backup Edition license. |
Include Path | Sets the files to deploy for replication. At least one Include Path attribute is required. The following properties apply to this attribute: • Relative paths are relative to DataDirectory listed in the <Sites> section of the XML file. • Absolute paths, if specified, must all start with the same drive letter, which must be the same drive letter specified by DataDirectory. • Paths must specify files individually or by wildcard. Wildcard characters “?” and “*” are allowed. • Subdirectories must be explicitly listed in the paths (DXdeploy does not automatically process subdirectories from a given root). • Multiple attribute lines are permitted. |
Exclude Path | Sets which files, among the included files, to exclude. The same properties apply as for Include Path. |
First Server name | Sets the machine name or IP address of the First Site. "Localhost" is not permitted. |
DSN | Sets the data source name (DSN) to be associated with the data files deployed for replication. The DSN must be unique on each site. |
DataDirectory | Sets the root path to which the Include Path and Exclude Path values are relative. DataDirectory must begin with a drive letter. DataDirectory in First Server name applies to the First Site. DataDirectory in Partner Server name applies to the Partner Site. |
Partner Server name | Sets the machine name or IP address of the Partner Site. "Localhost" is not permitted. |
Removing the Example Deployed Database
You do not need to keep the example deployed database. The following tasks explain how to remove it from the First Site and the Partner Site.
Task 1: Deactivate the example database on both sites
1. On the First Site machine, open a command prompt and run the following.
dxdeact dxdatabase
The example database on the First Site is now deactivated.
2. Repeat this step on the Partner Site.
Task 2: Run Template Remover on the First Site
1. On the First Site, do one of the following:
• Select DX Template Remover from the Start menu.
• In ZenCC, select DataExchange > Template Remover.
2. In the Template Remover Wizard welcome dialog, click Next.
3. In the templates pane, select LOCAL:DXDATABASE as the template to remove.
4. Select Remove DataExchange System Tables and click Yes in the warning message to continue.
5. Select Remove DSN and database name.
The wizard should now resemble the following:
6. Click Next.
The wizard removes the template and presents a summary.
7. Click Close.
Task 3: Delete files on the First Site
1. On the First Site, find the DX_projectname directory under C:\ProgramData\Actian\Zen\Demodata that was created during deployment.
DX_projectname is the name given to your replication project in the XML deployment file, in this case DXProj in the following line in ExampleRTB.xml:
<Configuration Project="DXProj" Network="DXNet" Release="1.0" Method="1-way">
2. Stop replication services as described under Starting and Stopping Replication. Replication must be stopped to do the next step as well.
3. Delete the DXDatabase folder under C:\Program Files (x86)\Actian\Zen\Replication\Templates.
Task 4: Delete the example database and files on the Partner Site
1. On the Partner Site, start ZenCC if it is not already running.
2. Make sure replication services are stopped as described under Starting and Stopping Replication. Deleting the Partner Site while replication is active can result in unwanted database behavior.
3. In the Databases list under Engines, right-click DXDatabase and select Delete. 
4. In the delete confirmation dialog, you have several options. 
5. Do one of the following:
• To keep the database you were replicating, select Yes, but only database name.
• To delete the database you were replicating, select Yes, database name and ddfs.
• Select No if you decide not to delete the database.
6. To complete removal of the deployed replication database on the Partner Site, delete the directory C:\Demodata. This was the directory created in Task 4: Copy the Template to the Partner Site. You may have to temporarily stop Zen services to delete the directory.
Task 5: Restore the database copy, if needed
1. Open the folder where you saved a copy of your data files before you copied the replication files from the First Site.
2. Move or copy the files back to the folder where your original database was located.
In this example, the location to which files are restored is C:\ProgramData\Actian\Zen\Demodata.
Working with Your Database
The Demodata example demonstrates the four required steps in the replication deployment process. This topic reviews that process and its components in more detail.
1. Edit the XML deployment descriptor file that is used by the DXdeploy utility.
2. Run DXdeploy on the First Site, setting the XML descriptor file as a parameter.
3. Copy the replication-enabled files from the First Site to the Partner Site.
4. Run DXdeploy on the Partner Site, setting the same XML descriptor file used for the First Site.
This topic discusses the process in more detail so that you can apply it to your own database. Before beginning the process, however, you need to determine which tables to replicate and ensure that they can be replicated.
Tip... When you work with the examples in this documentation, you should always make a copy of your database before performing the steps so that you can use it to restore the original database when you are done. Also, you do not need to keep the example deployed database. After each deployment, you can perform the steps associated with your deployment method to remove the replication files and templates and restore your database from the copy you made.
What to Do First
To deploy a database for replication, you need first to do the following:
• Decide which tables in which databases should be replicated.
• Ensure tables to be replicated contain system data and key.
Which Tables To Replicate
Determine which tables need to be replicated. Consider any situations in which tables created dynamically also need to be replicated. See Adding Dynamic Tables to an Activated Database.
You set the tables to be replicated in the XML deployment descriptor file. See XML Deployment Descriptor File.
System Data and Key
For Real-Time Backup replication, DataExchange requires that each table to be replicated has a unique system key. The replication control tables track changes by using the unique keys.
You may use the Zen utility Butil to determine whether a table contains system key and data. For example, to check table mytable.mkd located in c:\mydata, you would enter the following at a command prompt:
butil -stat c:\mydata\mytable.mkd
Among other information, the statistics output informs you about system data and key. If the output shows that System Data = Yes and SYSKEY Status = Present, then system data and key is present.
If the existing database does not have system keys, you must add system data and keys with the Zen Rebuild utility. See the Rebuild Utility topic in Advanced Operations Guide.
Zen Security with DataExchange
Zen provides security models for Btrieve applications. However, an activated database created by DXdeploy does not automatically use security, even if its source database does. You can manually configure security for the replication database. For an example of this using the Demodata sample database, see Replicating a Database with Zen Security.
DXdeploy Utility on First Site
After you edit the XML descriptor file, you run the DXdeploy utility on the First Site. The utility creates a template of the source data files. Hereafter, for ease of discussion, the source data files will be referred to collectively as the source database.
A template is a special type of database specifically for use with the replication tools. It contains various types of control tables used for replication. A template may also contain the data from the source database. DXdeploy creates a template without source data. (In step four of the deployment process, the source data gets replicated from the First Site to the Partner Site.)
You use a template to activate a database. Activation is the process of enabling a database for replication and establishing it as belonging to a site. DXdeploy also activates the source database on the First Site.
The following table explains where DXdeploy places the deployment files.
Activated Database | Template |
|---|---|
An activated database is placed in the folder DX_projectname, which is under the source database folder. For example, for source database C:\myfolder\mydb and project myproject, the activated database will be in C:\myfolder\mydb\DX_myproject. Your source database is not altered. | All templates are in C:\Program Files (x86)\Actian\Zen\Replication\Templates. For example, if your database is mydb and its DSN is mydbdsn, then the template resides in the following folders: • C:\Program Files (x86)\Actian\Zen\Replication\Templates\mydbdsn – Empty data files produced from source data files. These files are considered part of the template. Also in this folder is a copy of the XML descriptor file. • C:\Program Files (x86)\Actian\Zen\Replication\Templates\mydbdsn\DX_myproject – Other replication-enabled files, such as the control tables. |
Note: The activation process performed by DXdeploy may take a few minutes to several hours depending on the size and number of data tables. However, you may proceed with the next step, copying the template files to the Partner Site, as soon as DXdeploy finishes creating the template.
Check the screen for the message: “Starting the Activate action . . .” After it appears, copy the template files to the Partner Site. Typically, the template is created rapidly, even for a large number of data files.
File Copying
After DXdeploy creates the template on the First Site, manually copy the template to your Partner Site.
Example of What to Copy Where
DXdeploy creates template directories to show where to copy files to the Partner Site. For example, if the application DSN is mydbdsn with database name mydb and mydb uses four data files on your First Site:
• C:\myapp\data\table1.mkd
• C:\myapp\data\table2.mkd
• C:\myapp\data\other\table3.mkd
• C:\employees\accting\table4.mkd
Your edited XML descriptor file would resemble the following:
<First ServerName="SiteA" DSN="mydbdsn" DataDirectory="C:\myapp\data" >
<Files>
<Include Path="*.mkd" />
<Include Path="other\*.mkd" />
<Include Path="c:\employees\accting\table4.mkd"/>
<Files>
<Include Path="*.mkd" />
<Include Path="other\*.mkd" />
<Include Path="c:\employees\accting\table4.mkd"/>
The first and second Include Path statements are relative to DataDirectory. Assuming that table4.mkd is a bound table and must be located at C:\employees\accting, then it requires an absolute path.
Given this example, the following tables explain where on the Partner Site to copy the template files.
C:\Program Files (x86)\Actian\Zen\Replication\Templates\mydbdsn\mydb\DX_myproject | |
|---|---|
Contents | Where to Copy on Partner Site |
Empty data files table1.mkd, table2.mkd, and \other\table3.mkd. The edited XML descriptor file. DX_projectname directory: C:\Program Files (x86)\Actian\Zen\Replication\Templates\mydbdsn\mydb\DX_myproject | C:\myapp\data, same as on the First Site. But the only requirement is that the location match the partner data directory in the XML descriptor file. The XML descriptor file can go anywhere, but it may be simplest to copy it to the data directory. DX_myproject holds other replication-enabled files. Copy this it to the same location as on the First Site. |
C:\Program Files (x86)\Actian\Zen\Replication\Templates\mydbdsn\mydb\c_drive\employees\accting | |
|---|---|
Contents | Where to Copy on Partner Site |
Empty data file table4.mkd. | C:\employees\accting |
Note: If data files already exist on the Partner Site, overwrite them with the template data files.
DXdeploy Utility on Partner Site
After you use DXdeploy to activate the template on the First Site, copy the template to the Partner Site and use DXdeploy to activate it on that site by running DXdeploy with the XML deployment descriptor file used for the First Site. The template file is found in the database directory under C:\Program Files (x86)\Actian\Zen\Replication\Templates. In the example above, this is C:\Program Files (x86)\Actian\Zen\Replication\Templates\mydbdsn\mydb.
Caution! DXdeploy must finish activation on the First Site before you run it on the Partner Site. On the First Site, check on-screen for the message “Activation done, now synchronizing tables.” Once the message appears, you can then run DXdeploy on the Partner Site.
Replication Schedule
After DXdeploy finishes on the Partner Site, it performs an initial replication with the First Site. The initial replication between the sites fully populates the data tables on the Partner Site.
Following deployment, you may want to set up a replication schedule to keep Partner Site data current with First Site data. See Schedule Tasks for steps to set up a replication schedule.
Note: Replication works in either direction and is determined only by where you set the schedule. If the data changes that you want to back up occur on the First Site, then set the schedule on the First Site so that backups flow from the First Site to the Partner Site. If in your environment data changes occur instead on the Partner Site, then you must set the schedule there so that backups flow in the other direction, from the Partner Site to the First Site.
Disaster Recovery
If your First Site is catastrophically destroyed, you may restore your data from the Partner Site to a new First Site and reestablish your replication network. See Disaster Recovery.
Removing Databases Deployed with Designer
DataExchange Designer is a deprecated utility that was included with DataExchange before version 5.1. You may need to remove a database that was deployed with DataExchange Designer. Use the following tasks to complete the removal of a database deployed using DataExchange Designer.
Deactivate the Database on Both Sites
For this example, the value for DSN is Demodata.
1. Run DXdeact DSN at the First Site.
2. Run DXdeact DSN at the Partner Site.
Run Template Remover on the First Site
1. On the First Site, in the Start menu select Actian DataExchange 15 > DX Template Remover.
2. In the welcome dialog, click Next.
3. In the templates pane, when asked to choose a template to remove, click LOCAL:DSN. In this example, the value of DSN is DXDATABASE.
4. Select Remove DataExchange System Tables and click Yes to confirm that you wish to continue.
5. Select Remove DSN and database name and click Next.
6. After the wizard removes the template and presents a summary, click Close.
Delete Database and Files on the Partner Site
Before deleting a database or its files, you may need to stop replication. See Starting and Stopping Replication.
1. On the Partner Site machine, delete the contents of the folder to which you copied the replication replication files from the First Site.
2. If you need to use the Demodata sample database again, restore it in the next task.
Restore the Database Copy
1. Open the temporary folder to which you saved a copy of your data files before you copied the replication files from the First Site.
2. Move or copy the files back to the folder where your original database was located.
1-Way Deployment Using DXdeploy
This topic provides a step-by-step discussion on deploying a replication solution using the DXdeploy utility and the EXPRESS.XML descriptor template to create your XML descriptor file. This example can be used with either the Real-Time Backup or the Data Synchronization edition. It is similar to the tutorial Replication Deployment Using DXdeploy with an XML Descriptor File.
You need two machines for the example session. One machine must have DataExchange installed as a First Site. The other machine must have DataExchange installed as a Partner Site. Before you use DXdeploy, be sure to follow the instructions under Administrator Rights for DataExchange users.
This topic contains the following tasks:
Note: This topic covers only deployment and does not discuss setting up a replication schedule.
Before You Get Started
Before performing this task you must install DataExchange on First Site and a Partner Site.
Tip... So that you can restore your database to its original state after this deployment exercise, we recommend saving a copy of your database files before proceeding with this example.
To create your version of the XML descriptor file, first make note of the following items:
• Name or IP addresses for the two database servers
• Root path for the source data
• Directories and file names for the source data
• Root path for the replicated data
Caution! All applications using the database you are about to deploy must be shut down before using this deployment method.
Create the XML Descriptor File
To create the XML Descriptor file
1. On the First Site machine, open the folder C:\Program Files (x86)\Actian\Zen\Replication\Docs.
2. Make a copy of the XML descriptor file EXPRESS.XML and rename the copy EXP_1WAY.XML.
You may move the file to any location on your First Site machine. For this task we assume that you keep it in its original location. If EXPRESS.XML is no longer on your system, copy the text from the next step to recreate it.
3. Open EXP_1WAY.XML in a text editor.
This template file has the contents explained under XML Deployment Descriptor File.
4. For this example, we are replacing the contents of EXP_1WAY.XML with the following:
<?xml version="1.0"?>
<DXDeployment>
<Configuration Project="mydbproject" Network="sales dept net" Release="1.0" Method="1-way">
<Sites>
<First
ServerName="SiteA" DSN="SalesDB" DataDirectory="C:\CompanyData\SalesData">
<Files>
<Include Path="*.mkd" />
<Include Path="*.ddf" />
<Include Path="SalesReports\*" />
<Include Path="*SalesReports\Q1Rept.mkd" />
<Include Path="C:\Employee\SalesRep\sample.mkd" />
</Files>
</First>
<Partner
ServerName="SiteB" DSN="SalesDB" DataDirectory="C:CompanyData\SalesData" />
</Sites>
</Configuration>
</DXDeployment>
<DXDeployment>
<Configuration Project="mydbproject" Network="sales dept net" Release="1.0" Method="1-way">
<Sites>
<First
ServerName="SiteA" DSN="SalesDB" DataDirectory="C:\CompanyData\SalesData">
<Files>
<Include Path="*.mkd" />
<Include Path="*.ddf" />
<Include Path="SalesReports\*" />
<Include Path="*SalesReports\Q1Rept.mkd" />
<Include Path="C:\Employee\SalesRep\sample.mkd" />
</Files>
</First>
<Partner
ServerName="SiteB" DSN="SalesDB" DataDirectory="C:CompanyData\SalesData" />
</Sites>
</Configuration>
</DXDeployment>
Run DXdeploy on the First Site
To run DXdeploy on the First Site
1. On the First Site, open a command prompt and enter the following:
dxdeploy "C:\Program Files (x86)\Actian\Zen\Replication\Docs\EXP_1WAY.XML"
The command is not case-sensitive.
2. Press Enter.
As DXdeploy executes, high-level status messages display on the screen as it completes certain actions. For a successful deployment, the following messages appear:
• Starting the CreateDSN action
• Starting the Design action
• Starting the Activate action
• Activation done, now synchronizing tables
By default, detailed messages from DXdeploy are written to dxdeploy.log, not to the screen. This log is located in C:\ProgramData\Actian\Zen\Replication\LogFiles. If you want to view detailed messages on the screen while DXdeploy executes, use the /LOGFILE= option.
3. For example, you would enter the following:
dxdeploy /LOGFILE= "C:\Program Files (x86)\Actian\Zen\Replication\Docs\EXP_1WAY.XML"
DXdeploy is complete when the command prompt reappears. You may also check the DXdeploy log file to determine when DXdeploy finishes. The following message appears at the bottom of the log file: “Successfully completed all deployment actions.”
4. Optionally, start ZenCC if it is not already running. (Select Zen Control Center & Documentation from the Start menu.)
5. In Zen Explorer under Engines, open the SalesDB database branch. Notice that SalesDB is now listed as a database with the letter A shown on its Replication node to show that the database is activated.
Copy the Template to the Partner Site
To copy the template to the Partner Site
1. After DXdeploy finishes on the First Site, copy the SalesData directory from C:\Program Files (x86)\Actian\Zen\Replication\Templates\SalesDB to C:\CompanyData on your Partner Site.
Note: Note that the example used here contains data files in both relative and absolute locations. When copying your files, you must include absolute paths to data residing outside the DataDirectory location you specified. For information on where to copy your files, see File Copying in the Real-Time Backup replication example.
Tip... When using DXdeploy deployment, the template is a copy of the database files. These files are located in the directory C:\Program Files (x86)\Actian\Zen\Replication\Templates.
Run DXdeploy on the Partner Site
To run DXdeploy on the Partner Site
1. On the Partner Site, open a command prompt.
2. At the prompt, you would enter the following:
dxdeploy C:\CompanyData\SalesData\EXP_1WAY.XML
The command is not case-sensitive.
3. Press Enter.
DXdeploy provides high-level status messages on the screen as it completes certain actions. For a successful deployment, the following messages appear:
• Starting the CreateDSN action
• Starting the Design action
• Starting the Activate action
By default, detailed messages from DXdeploy are written to dxdeploy.log rather than to the screen. DXdeploy is complete when the command prompt reappears. You may also check the DXdeploy log file to determine when DXdeploy finishes. The following message appears at the bottom of the log file: “Successfully completed all deployment actions.”
When DXdeploy runs on the Partner Site, it performs an initial replication with the First Site. This replication populates data on the Partner Site so that it is the same as on the First Site.
Note: Depending on database size and connection bandwidth, initial replication can take from a few minutes to several hours.
Tip... For steps to remove the deployed database you just created, see Removing the Example Deployed Database.
2-Way Deployment Using DXdeploy
This topic discusses at a high level how to deploy a database for replication using the DXdeploy utility. It uses the sample database, TRACKER, as a working example. This sample database is provided with the Zen installation. This example can be used only with the Data Synchronization edition, since the Real-Time Backup edition supports only 1-way replication.
The example session requires two machines. One must have DataExchange installed as a First Site. The other must have DataExchange installed as a Partner Site. Before you use DXdeploy, be sure to follow the instructions under Administrator Rights for DataExchange users.
To step through the example, you will use the following tasks:
These steps omit setting up a replication schedule. Since the TRACKER deployment is only an example, setting up a regular replication schedule is unnecessary.
Before You Get Started
Before performing this task you must install DataExchange on a First Site and a Partner Site.
Tip... So that you can restore your database to its original state after this deployment exercise, we recommend saving a copy of your database files before proceeding with this example.
In order to complete the changes necessary to the XML descriptor file, we recommend that you make note of the following items:
• Name or IP addresses for the two database servers
• Root path for the source data
• Directories and file names for the source data
• Root path for the replicated data
Caution! All applications using the database you are about to deploy must be shut down before using this deployment method.
Create the XML Descriptor File
To create the XML Descriptor file
1. In the directory C:\Program Files\Actian\Zen\Replication\Docs\, make a copy of the XML descriptor file CUSTOM.XML and rename the copy CUST_2WAY.XML.
You may move the file to any location on your First Site machine. For this task we assume that you keep it in its original location. If CUSTOM.XML is no longer on your system, copy the text from the next step to recreate it.
2. Open CUST_2WAY.XML in a text editor.
This template file differs slightly from EXPRESS.XML as documented under XML Deployment Descriptor File. It has the following contents:
<?xml version="1.0"?>
<DXDeployment>
<Configuration Project="DXProj" Network="DXNet" Release="1.0" Method="1-way">
<Sites>
<First ServerName="this.hostname" DSN="DXDatabase" DataDirectory="C:\MYDATA">
<Files>
<Include Path="*.mkd" />
<Include Path="MoreData\dataFile.dat" />
<Exclude Path="DontNeed.dat" />
<Include Path="C:\OtherDir\*" />
<Exclude Path="C:\OtherDir\Temp*" />
<Include Path="*.ddf" />
</Files>
</First>
<Partner ServerName="remote.hostname" DSN="DXDatabase" DataDirectory="C:\MYDATA" />
</Sites>
</Configuration>
<Actions>
<CreateDSN />
<Design />
<Activate />
</Actions>
</DXDeployment>
<DXDeployment>
<Configuration Project="DXProj" Network="DXNet" Release="1.0" Method="1-way">
<Sites>
<First ServerName="this.hostname" DSN="DXDatabase" DataDirectory="C:\MYDATA">
<Files>
<Include Path="*.mkd" />
<Include Path="MoreData\dataFile.dat" />
<Exclude Path="DontNeed.dat" />
<Include Path="C:\OtherDir\*" />
<Exclude Path="C:\OtherDir\Temp*" />
<Include Path="*.ddf" />
</Files>
</First>
<Partner ServerName="remote.hostname" DSN="DXDatabase" DataDirectory="C:\MYDATA" />
</Sites>
</Configuration>
<Actions>
<CreateDSN />
<Design />
<Activate />
</Actions>
</DXDeployment>
3. For this example, we are replacing the contents of CUST_2WAY.XML with the following:
<?xml version="1.0"?>
<DXDeployment>
<Configuration Project="mydbproject" Network="admin dept net" Release="1.0" Method="2-way">
<Sites>
<First ServerName="SiteA" DSN="TrackerDB" DataDirectory="C:\ProgramData\Actian\Zen\Replication\Demodb">
<Files>
<Include Path="*.mkd" />
<Include Path="Misc\*.dat" />
<Include Path="Misc\misc_file3.dat" />
<Include Path="C:\Archive\*.dat" />
<Include Path="C:\Archive\History.dat" />
<Include Path="*.ddf" />
</Files>
</First>
<Partner ServerName="SiteB" DSN="TrackerDB" DataDirectory="C:\Program Files\Actian\Zen\Replication\Demodb" />
</Sites>
</Configuration>
<Actions>
<CreateDSN />
<Design />
<Activate />
</Actions>
</DXDeployment>
<DXDeployment>
<Configuration Project="mydbproject" Network="admin dept net" Release="1.0" Method="2-way">
<Sites>
<First ServerName="SiteA" DSN="TrackerDB" DataDirectory="C:\ProgramData\Actian\Zen\Replication\Demodb">
<Files>
<Include Path="*.mkd" />
<Include Path="Misc\*.dat" />
<Include Path="Misc\misc_file3.dat" />
<Include Path="C:\Archive\*.dat" />
<Include Path="C:\Archive\History.dat" />
<Include Path="*.ddf" />
</Files>
</First>
<Partner ServerName="SiteB" DSN="TrackerDB" DataDirectory="C:\Program Files\Actian\Zen\Replication\Demodb" />
</Sites>
</Configuration>
<Actions>
<CreateDSN />
<Design />
<Activate />
</Actions>
</DXDeployment>
Run DXdeploy on the First Site
To run DXdeploy on the First Site
1. On the First Site, open a command prompt and enter the following:
dxdeploy "C:\Program Files (x86)\Actian\Zen\Replication\Docs\CUST_2WAY.XML"
2. Press Enter.
DXdeploy provides high-level status messages on the screen as it completes certain actions. For a successful deployment, the following messages appear:
• Starting the CreateDSN action
• Starting the Design action
• Starting the Activate action
• Activation done, now synchronizing tables
By default, detailed messages from DXdeploy are written to dxdeploy.log, not to the screen. This log is located in C:\ProgramData\Actian\Zen\Replication\LogFiles. If you want to view detailed messages on the screen while DXdeploy executes, use the /LOGFILE= option. For example, dxdeploy /LOGFILE= CUST_2WAY.XML. A space character follows the equal sign.
DXdeploy is complete when the command prompt reappears. You may also check the DXdeploy log file to determine when DXdeploy finishes. The following message appears at the bottom of the log file: “Successfully completed all deployment actions.”
3. Optionally, open Control Center (ZenCC) and in Zen Explorer under Engines, open the TrackerDB branch. Notice that TrackerDB is now listed as a database with the letter A shown on its Replication node to show that the database is activated. 
Copy the Template to the Partner Site
To copy the template to the Partner Site
After DXdeploy finishes on the First Site, copy the DemoDB directory on the First Site from
C:\Program Files (x86)\Actian\Zen\Replication\Templates\TrackerDB
to the following directory on your Partner Site:
C:\Program Files (x86)\Actian\Zen\Replication
This example contains data files in both relative and absolute locations. When copying your files, you must include absolute paths to data residing outside the DataDirectory location you specified. For information on the copy locations, see File Copying.
Note: When using DXdeploy deployment, the template consists of a copy of the database files. These files are all located in C:\Program Files (x86)\Actian\Zen\Replication\Templates.
Run DXdeploy on the Partner Site
To run DXdeploy on the Partner Site
1. On the Partner Site, open a command prompt and run the following:
dxdeploy "C:\Program Files (x86)\Actian\Zen\Replication\DemoDB\CUST_2WAY.XML"
2. Press Enter.
DXdeploy provides high-level status messages on the screen as it completes certain actions. For a successful deployment, the following messages appear:
• Starting the CreateDSN action
• Starting the Design action
• Starting the Activate action
By default, detailed messages from DXdeploy are written to dxdeploy.log, not to the screen. DXdeploy is complete when the command prompt reappears. You may also check the DXdeploy log file to determine when DXdeploy finishes. The following message appears at the bottom of the log file: “Successfully completed all deployment actions.”
When DXdeploy runs on the Partner Site, it performs an initial replication with the First Site. This replication populates data on the Partner Site so that it is the same as on the First Site.
Note: Depending on database size and connection bandwidth, initial replication can take from a few minutes to several hours.
Tip... For steps to remove the deployed database you created, see Removing the Example Deployed Database.
Last modified date: 12/01/2023