Copyright: Copyright © Synectics Software


Introduction
The InterBase replication manager:

Introduction

This application, IBRplManager, is the management tool for the InterBase replication server. Use this tool to define, alter and view the replication schemata that the replication server uses to establish what it needs to replicate, where the data should be sent to, and how often.

IBRplManager also provides utilities that allow you to handle conflicts in replicated data that the server could not resolve automatically, to schedule regular replications, to view replication statistics, and to view graphical representations of your schemata.

This help system explains how to use IBRplManager; for a discussion of replication techniques, consult the InterBase User's Guide.


Using the main window
Using the replication manager:

Using the main window

IBRplManager's main window allows you to:

Connect to a configuration database;

Register databases that are to provide or receive replicated data;

Define replication schemata.

The window's menu system provides these commands, and others that open windows for managing configuration databases and running IBReplicator's utilities (for manual conflict resolution, scheduling replications, viewing replication statistics, and viewing graphical representations of your replication schemata.

The main toolbar contains the configurations combo box and button, and buttons that control the format of the replications control panel.

The Databases tab allows you to work with the databases that are to be involved in replication.

The Replications tab allows you to define and maintain your replication schemata.

The status bar at the bottom of the window displays flyby hints which describe the control under the mouse pointer.

Note:

Many controls have tool tips that display their names when the mouse point is left over them for a moment.


Choosing a configuration
Using configurations:

Choosing a configuration

The configurations combo box in the main windows tool bar allows you to select a configuration database (if more than one are in use) and to connect to it.

When you select a configuration, you will be prompted for a logon password (which can be changed via the InterBase server responsible for the database). If you get the password wrong, choose the database from the combo box again, and you will be prompted once more.

Note:

If no configuration databases are known to this management tool, you will be prompted to create one when the application runs.

The default configuration database is shown in bold.

The configurations button beside the combo box opens the configurations window from which your configuration databases can be maintained.

See also:

Configuration databases, where the creation and maintainance of these databases is discussed.


Registering databases
Registering databases:

Overview

Before you define your replication schemata, you first need to inform IBReplicator of all the databases that are to be involved in your replication. This is done with the "Databases" tab on the main window. This tab allows you to:

Add a database to the list of registered databases

Edit a registered database's properties

Remove a database from the list of registered databases

Check your database properties by confirming that the database can, in fact, be connected to.

The treeview on the left of the tab sheet lists all the databases that are currently registered with IBReplicator.

The field editor to its right lists the parameters of the database currently selected in the treeview.

The database tool bar above the field editor presents the commands you'll need to maintain the list of registered databases.

The "Database" menu gives access to those same commands.

Note:

Registering a database with IBReplicator does not create that database; it merely informs the system of that database's existence and supplies it with the parameters it will need to connect to the database. Likewise, removing or unregistering the database does not destroy it; all that happens is that IBReplicator is no longer aware of that database and it cannot participate in any replications.

See also:

Database parameters;

Using the field editor.


Using the field editor
Using the replication manager:

Using the field editor

IBRplManager uses a "field editor" control to display and capture the parameters of registered databases and those of configuration databases as well.

To capture data, first place the editor in editing mode. You do this by running the "Add" or "Create" commands in the relevant menu. If you want to alter the values being displayed by the editor, run the "Edit" command, or double-click the editor.

Once the editor is in editing mode, you can move from property to property by using the Ctrl+Up, Ctrl+Down, Ctrl+Home, Ctrl+End and Enter keys.

When all the properties have their desired values, save your changes with the "Save" command in the relevant editor.

See also:

Configuration databases;

Database parameters.


Replication schemata
Replication schemata:

Overview

The "Replications" tab on the main window contains controls that allow you to define and maintain your replication schemata. You can:

Edit the defaults applied to each new schema;

Create, edit and delete schemata;

Identify the source database;

Identify the target database;

Identify the tables that contain data to be replicated;

Identify the primary key columns in those tables that are to be replicated;

Identify the columns and rows in those tables that are to be replicated.

The treeview on the left of the tab sheet displays the details of each schema in the current configuration database.

The control panel to the right displays the commands applicable to the treeview node that is currently selected.

The "Replication" menu gives access to these same commands.

Note:

Defining a replication schema involves identifying the databases which contain the data to be replicated, and which are to receive the replicated data; therefore, you need to register your databases with the system before you can define a replication schema.

See also:

Using the replication manager.


Schema defaults
Replication schemata:

The "Schema defaults" dialog

Each schema has various settings which you can customize to suit your needs. This is not always necessary, however, because the settings are automatically initialized to default values. You can view these settings in the "Schema defaults" dialog, which also allows you to provide default values of your own.

The dialog contains a tabbed notebook with two tabs:

The General tab controls whether replication happens at fixed intervals or in response to an InterBase event alerter in the source database, which conflict resolution strategy is applied, and whether database synchronization is enabled.

The Event logging tab controls which of the replication server's activities are logged, and whether they are logged to a file or to the server's windowed interface (IBReplicator.exe).

Note:

Changing the schema defaults does not change the settings of schemata that have already been defined; only newly defined schemata will have their settings initialized to the new values.


Schema defaults: General
Replication schemata:

The "Schema defaults" dialog: "General" tab

The "General" tab on the "Schema defaults" dialog allows you to view and edit certain settings that will be applied to each new replication schema that you define after setting their default values in the dialog.

Replication timing: The replications defined in a schema can occur at regular intervals (specified in seconds) or in response to an event fired by the source database. If you select replication in response to an event, provide the event alerter's name in the edit box.

Conflict resolution strategy: When the primary key of a row replicated from a source database conflicts with that of a row already in one of the target databases, IBReplicator provides three ways in which the problem can be overcome automatically:

1.	Priority based: When you register a database, you can give it a priority so that when conflicts occur, the database with the higher priority takes precedence. So, if the source database has the higher precedence, the target's row is over-written, but if the target has the higher priority, its row is preserved and the replicated row is discarded;

2.	Time-stamped: The more recent of the conflicting rows is preserved;

3.	Master-slave: The source database's row always replaces the conflicting row in the target.

Synchronization: IBReplicator allows you to synchronize two databases by emptying a target and filling it with data retrieved from a source database, or vice versa if Reverse synchronization is checked. If you need to synchronize databases, ensure that the Enabled check box is checked. Note that synchronization is used only under rare circumstances, such as populating a new, empty database, or one which has been restored from a backup; if a target database has simply been offline, there is no need to synchronize it as normal replication will catch up with the backlog.


Schema defaults: Event logging
Replication schemata:

The "Schema defaults": "Event logging" tab

The "Event logging" tab on the "Schema defaults" dialog allows you to control which of the replication server's activities are logged, and whether they are logged to a file (identified by you in the Log file edit box) or to a window in the replication server's windowed interface (IBReplicator.exe).


Database parameters
Registering databases:

Database parameters

The database field editor lists the properties of each registered database:

Descriptive name: A name for your convenience; it's value is unimportant to the replication system, so choose names that are self-explanatory and informative. You may include spaces and punctuation freely.

Server: The path and file name of the database being registered; Note that you can browse across a network for the server, but this will only help if you connect with NetBUI; if you connect with TCP/IP (as is usually done), you must supply the server name in TCP/IP syntax. for example, \\server\drive:\path\database.gdb.

Administrative user name: The user name that this management tool should use when connecting to the database to retrieve its table and column names. This is not the user name for the replication server to use as it moves data around; this is the "replication user name", and you provide it when you define a source or target database in a replication schema (which means that different schemata can have different user names).

Administrative password: Like the administrative user name, this password is used by this management tool; the replication server uses a "replication password" provided when databases are specified in a replication schema.

Administrative role: Like the administrative user name and password, this role is used by this management tool; the replication server uses a "replication role" provided when databases are specified in a replication schema.

SQL dialect: Informs IBReplicator on whether it can use the functionality implemented in InterBase 6 (such as the time-stamped date format, single vs. double quotes, etc.), or if it should confine itself to InterBase 5.5 functionality. The intermediate dialect causes InterBase to explain errors arising from dialect problems (these error messages can be automatically logged for later study).

Priority: This value is only meaningful when priority-based conflict resolution is in use. In this case, replication conflicts are resolved by ensuring that data from the database with the higher priority is preserved when conflicts arise.

CharSet: The character set in use by the database.

Time field: This value is only meaningful when time-stamped conflict resolution is in use. Your tables should all include a column with this name which will contain the date and time when each row was inserted or last updated; when you have provided this functionality, IBReplicator will ensure that the more recent row is preserved when conflicts arise.

Comments: This property is entirely for your convenience. Use it to document and explain each database you register.

IBReplicator can use the Windows 95/98/NT/2000 Remote access services to replicate across a dial-up connection. The following database parameters control how it does so:

RAS name: This is the name of the relevant entry in the Windows "Dial-up Networking" dialog.

RAS username: The username that the replicator should use when dialing out.

RAS password: The password that the replicator should use when dialing out.

Keep connection: Controls whether the replicator hangs up as soon as it is finished a replication, or retains the line until the replicator itself is shut down or a user terminates the RAS connection.


Schema properties
Replication schemata:

The "Schema properties" dialog

The "Schema properties" dialog is used when starting a new schema or editing an existing schema node in the replications treeview. Open it by:

Creating a new schema by selecting the "Defined replication schemata" node of the "Replications" treeview on the main window and double-clicking the "New schema" icon, or by running the "Replication|Schema|New" menu command;

Editing an existing schema by selecting its node in the "Replications" treeview on the main window and double-clicking the "Edit schema" icon, or by by running the "Replication|Schema|Edit" menu command.

The schema name is for your convenience; choose self-explanatory descriptive phrases (which may contain spaces and punctuation).

The synchronization group box controls whether the databases in the schema may be synchronized:

Use defaults: When checked, the synchronization settings specified in the "Schema defaults" dialog are used; when unchecked, the values of the "Enabled" and "Reversed" check boxes are used instead.

Enabled: When checked, the databases in the schema may be synchronized.

Reversed: When the databases are synchronized, the source database is updated to contain the exact data in the target database.

Note that synchronization is used only under rare circumstances, such as populating a new, empty database, or one which has been restored from a backup; if a target database has simply been offline, there is no need to synchronize it as normal replication will catch up with the backlog.

See also:

The "Schema defaults" dialog.


Source database properties
Source databases:

The "Source database" dialog

The "Source database" dialog is used when adding a source database to a schema, or when editing one that has been added already.

Open the dialog by:

Adding a source database to a schema which does not yet have one by selecting its "Source database" node in the "Replications" treeview and double-clicking the "Add source database" icon, or by running the "Replication|Source|Add" menu command;

Editing a source database by selecting its node in the "Replications" treeview and double-clicking the "Edit source database" icon, or by running the "Replication|Source|Edit" menu command.

The dialog contains a tabbed notebook with three tabs:

Use the controls on the Connection tab to provide the login parameters that the replication server should use when it connects to the database.

The Settings tab contains general replication properties.

The check boxes on the Event logging tab control which of its activities the replication server logs.

Note:

Many of these properties have their initial values set to the defaults specified for the schema to which the source database will be added. To change those default values, edit the "Default settings" for the schema.


Source database: Connection
Source databases:

The "Source database" dialog: "Connection" tab

The "Connection" tab on the "Source database" dialog is used to provide login parameters for the replication server to use when it connects to the database to retrieve the rows that are to be replicated..

Registered database: Select one of your registered databases as the source of data which will be replicated to target databases (which are identified with the "Target database" dialog).

Replication user name: The user name that IBReplicator should use when it connects to the database to retrieve the rows that are to be replicated.

Replication password: The password that IBReplicator should use when it connects to the database to retrieve the rows that are to be replicated.

Replication role: The role that IBReplicator should use when it connects to the database to retrieve the rows that are to be replicated.

See also:

Registering databases.


Source database: Settings
Source databases:

The "Source database" dialog: "Settings" tab

The "Settings" tab on the "Source database" dialog presents general settings that will affect replications from the source database identified on the "Connection" tab.

The Replication enabled check box allows you to prevent replication from occurring, for example, while the network is down for maintainance. If replication were enabled during a system failure, the result would be a log file filled with connection errors (in event logging has been turned on) and, perhaps, a need to synchronize databases that had been out of contact during the failure.

Conflict resolution strategy: When the primary key of a row replicated from a source database conflicts with that of a row already in one of the target databases, IBReplicator provides three ways in which the problem can be overcome automatically:

1.	Priority based: When you register a database, you can give it a priority so that when conflicts occur, the database with the higher priority takes precedence. So, if the source database has the higher precedence, the target's row is over-written, but if the target has the higher priority, its row is preserved and the replicated row is discarded;

2.	Time-stamped: The more recent of the conflicting rows is preserved;

3.	Master-slave: The source database's row always replaces the conflicting row in the target.

The conflict resolution strategy has a default value which you can change.

The separator character is used to separate the values in primary keys with multiple columns (which IBReplicator stores in text format). It is therefore necessary that this character not appear in those key values, even when they are strings. Provide the decimal ASCII code for one of the more improbable ASCII characters if the default of ASCII character 5 is likely to conflict with a legitimate value in any table's primary key.

The comments field is entirely for your own convenience. Use it for any form of documentation that is useful to you.

See also:

Schema defaults, where a default conflict resolution strategy can be specified.


Source database: Event logging
Source databases:

The "Source database" dialog: "Event logging" tab

The "Event logging" tab on the "Source database" dialog allows you to control which of the replication server's activities are logged, and whether they are logged to a file (identified by you in the Log file edit box) or to a window in the replication server's windowed interface (IBReplicator.exe).

See also:

Schema defaults, where default event logging can be specified.


Target database properties
Target databases:

The "Target database" dialog

The "Target database" dialog is used when adding a target database to a schema, or when editing one that has been added already.

Open the dialog by:

Adding a target database to a schema by selecting the "Target databases" node in the "Replications" treeview on the main window and double-clicking the "Add target database" icon, or by running the "Replication|Target|Add" menu command;

Editing one of a schema's target databases by selecting the target database's node in the "Replications" treeview and double-clicking the "Edit target database" icon, or by running the "Replication|Target|Edit" menu command.

The dialog contains a tabbed notebook with two tabs:

Use the controls on the Connection tab to provide the login parameters that the replication server should use when it connects to the database.

The Settings tab contains general replication properties.

Note:

Certain of these properties have their initial values set to the defaults specified for the schema to which the source database will be added. To change those default values, edit the "Default settings" for the schema.


Target database: Connection
Target databases:

The "Target database" dialog: "Connection" tab

The "Connection" tab on the "Target database" dialog is used to provide login parameters for the replication server to use when it connects to the database to retrieve the rows that are to be replicated..

Registered database: Select one of your registered databases to receive data which will be replicated from the schema's target database (which is identified with the "Source database" dialog).

Replication user name: The user name that IBReplicator should use when it connects to the database to retrieve the rows that are to be replicated. See the special user REPL for information on user names and bi-directional replication.

Replication password: The password that IBReplicator should use when it connects to the database to retrieve the rows that are to be replicated.

Replication role: The role that IBReplicator should use when it connects to the database to retrieve the rows that are to be replicated.

See also:

Registering databases.


Target database: Settings
Target databases:

The "Target database" dialog: "Settings" tab

The "Settings" tab on the "Target database" dialog presents general settings that will affect replications to the target database identified on the "Connection" tab.

Synchronization is a potentially destructive act because any data in the database being synchronized will be lost if those rows are not also in the database with which it is being synchronized. For this reason, you need to explicitly enable synchronizations with the Enabled check box. In general, a target database is synchronized with its source; to synchronize the source with a target, check the Reversed box.

Periodic commit. In general, IBReplicator commits changes once, after all the logged changes have been successfully replicated to the target database. However, if a network error occurs during replication, all changes will be rolled back, and IBReplicator will try again, which leads to the possibility that it will try and try again and never succeed. So, if the network connection is very unreliable, set the "periodic commit" field to a value greater than zero, and IBReplicator will perform a "commit retaining" after each group of that many rows has been successfully replicated. Note that using this option can damage transactional integrity, so you should only use it when absolutely necessary.

See also:

Schema properties.


Replicated tables and procedures
Replicated tables and procedures:

The "Replicated tables and procedures" dialog

When you have specified a schema's source database and one or more targets, you can start specifying which tables in the source database contain data to be replicated, and which target tables should receive data from which source tables. You do this by mapping targets to sources.

NOTE: You can automate this process by choosing to run Auto Generate Tables,Keys and Fields Dialog. This will automatically map all tables in the source database to tables of the same name in the target database.

Open the dialog by selecting a "Replicated tables and procedures" node in the main window's "Replications" treeview and double-clicking the "Replicated tables" icon, or by running the "Replication|Tables|Define" menu command.

Ensure that the "Tables" radio button is checked so that the target list box is showing table names, and then simply select a target table from the list of available tables in the list of target tables and drag it over the source table from which it will be receiving data.

It is also possible to replicate to a stored procedure in the target database. Check the "Stored procedures" radio button to see a list of the available stored procedures in the target database, and map the relevant one to a target database. The InterBase User's Guide explains why one might want to replicate to a stored procedure, and describes what you need to do with an example.

See also:

Using the mapping window.


Table mapping properties
Replicated tables and procedures:

The "Table properties" dialog

The "Table properties" dialog is opened by selecting a table-mapping's node in the main window's "Replications" treeview and double-clicking the "Table settings" icon, or by running the "Replication|Tables|Settings" menu command.

This dialog is most important for specifying a row-level replication condition. That is, when you want only certain rows in the table to be replicated, you can provide an SQL condition in the Row-level replication condition edit box; when the replication retrieves data from the source database, it will use that condition to select the rows to be replicated. The details are discussed in the InterBase User's Guide. To replicate all rows, simply leave the field blank.

The dialog also provides various other fields:

The Settings group:

The Time-field name is applicable when you are using the time-stamped conflict resolution strategy. Use the field to give the name of the column from which IBReplicator should retrieve each row's time stamp (typically, the time when the row was inserted or last updated) when resolving conflicts by preserving the most recent data.

To halt replication, uncheck the Replication enabled box; to start it, check the box.

To use the Monitor tool to study IBReplicator's performance, the Keep statistics check box must be checked.

The Synchronization group allows you to fine-tune the synchronization of the two tables::

When Use defaults is checked, IBReplicator uses the enabled and reverse synchronization values from the schema's properties.

Synchronization enabled allows the two tables in the mapping to be synchronized when it is checked, and prevents their synchronization when it is unchecked.

Reverse synchronization causes the source table to be updated to the target's rows when it is checked; unchecked, the target is synchronized with the source.

The Synchronization condition allows you to identify which rows in the table need to be synchronized with an SQL condition (see "Row level replication condition" above); if the field is left blank, all rows are synchronized.

The comments field is for your convenience: use it for any form of documentation that might be necessary.

See also:

Schema properties, where synchronization defaults for the table mapping are set.


Mapping primary keys
Replicated columns:

The "Primary keys" dialog

When you have mapped a table in the source database to the table in the target database that should receive its data, you next need to define the tables' primary keys.

To open the "Primary keys" dialog, select a "Key columns" node in the "Replication" treeview on the main window and double-click the "Define primary key" icon, or run the "Replication|Columns|Keys" menu command.

Define the mapped tables' primary keys by identifying the source table's primary key columns and the columns in the target table to which they correspond. Simply select a column from the list of columns in the target table on the right, and drag it over the column in the list of source columns.

Note:

If you have mapped a source table to a stored procedure in the target database, then the stored procedure will take care of updating the target, and this step is unnecessary.

See also:

The "Replicated tables and procedures" dialog

Using the mapping window.


Using the mapping window
Using the replication manager:

Using the mapping window

The mapping window is used to map source tables or stored procedures, key columns and data columns to their targets. The left panel lists available source objects (tables, procedures or columns), and the right one available targets.

To map a target to its source, simply drag the target over the relevant item in the list of sources. The window also supplies functionality to deal with special cases:

Double-clicking a target will map it to the source with the same name.

Selecting multiple targets and dragging them over the sources will map each selected target to the source with the same name.

To unmap a source-target pair, either double click the mapping in the source list, or drag it over the list of targets. Selecting multiple source-target pairs and dragging them over the list of targets will unmap all of them.

See also:

Replicated tables and stored procedures;

Mapping primary keys;

Replicated data columns.


Mapping data columns
Replicated columns:

The "Replicated data columns" dialog

When you have mapped a target table to its source and defined the primary key, you can identify the columns which contain data to be replicated, and map the columns in the target table to the columns in the source from which their data will come.

To open the "Replicated data columns" dialog, select a "Data columns" node in the "Replication" treeview on the main window and double-click the "Define data columns" icon, or run the "Replication|Columns|Data" menu command.

Simply select a column from the list of columns in the target table on the right, and drag it over the column in the list of source columns.

See also:

Using the mapping window.


Creating system objects

IBReplicator uses several tables, triggers etc. in the source database of a replication schema. You need to tell the system to create those object when:

a new schema has been completely defined

and

when an existing schema has been altered.

To create these, simply run the "Replication|Create system objects" command in the main window's menu system.

Note that you will be prompted to create these objects when you close down the replication manager, but only when you have made changes that necessitate it.


Maintaining configurations
Using configurations:

The "Configuration databases" window

IBReplicator stores your replication schemata in a configuration database. You may have multiple configuration databases, provided that both this management tool and the replication server can access them. It is never necessary to have multiple configuration databases because you can store innumerable replication schemata in each one. However, it might be convenient to divide your schemata between configuration databases.

NB: Current Schema No.

In many Replication environments, it is possible to have a Source Database referred to in more than one Configuration database. Each Configuration will cause 'System Objects' to be created in the Source Database, and these can start conflicting, unless precautions are taken.

Each schema that is created in a configuration database is referred to by a number internally, and this number is used in the naming of triggers etc when creating the System Objects. If the internal Schema Numbers are unique in each configuration Database, then no conflicts can occur.

When creating a new Configuration Database, ensure that the 'Current Schema No' value is set to a number which will prevent two configuration databases using the same numbers. e.g. Config1.gdb may start at 1, while Config2.gdb may start at 500.

Each new Schema within any Configuration Database will cause the internal Schema number to be incremented by one. (The current schema number is generated internally by a GENERATOR called REPLGEN.)  The majority of configuration databases will have fewer than 10 Schemas defined, so a simple rule of thumb would be to have each configuration database start at values separated by about 100.

This is only necessary if one or more Source Databases are included as a SOURCE in more than one Configuration database.

The configurations dialog allows you to:

Create a new configuration database;

Add an existing configuration to the ones that IBReplicator knows about;

Edit the connection parameters for an existing configuration;

Remove a configuration from IBReplicator's list without deleting the database so that it can be added again later;

Destroy a configuration by deleting it permanently.

Make a configuration into the default, which is the configuration that the replication server will connect to. At least one of your configurations must be made the default.

Open this dialog by clicking the configurations button beside the configurations combo box on the main window's tool bar, or by running the "File|Configurations" command.

For each configuration, you need to provide the logon parameters that IBReplicator should use:

The Descriptive name is for your convenience: choose self-explanatory descriptive names (which may include spaces and punctuation).

The Server name is the path and filename of the configuration database.

The User name is the user that IBReplicator should log on as.

The Current Schema No which is discussed at the top of this page.

When you make a configuration the default (or when you check your parameters with the "Test connection" command), you will be prompted for the password that IBReplicator should use when it connects to the configuration.

Note:

When you do have multiple configurations, you must choose one of them to be the default to which the replication server connects itself.

See also:

Choosing a configuration


Defining replications
Defining replications:

Overview

Configuring IBReplicator to replicate your data correctly involves several steps:

Choosing a configuration from the configurations combo box on the main window's tool bar;

Registering databases on the "Databases" tab of the main window;

Defining schema defaults (optional) by selecting the root node of the "Replications" treeview and double-clicking the "Edit default settings" icon, or by running the "Replication|Default settings" menu command;

Creating a replication schema by selecting the root node of the "Replications" treeview and double-clicking the "New schema" icon, or by running the "Replication|Schema|New" menu command;

Identifying the schema's source database by selecting a "Source database" node in the "Replications" treeview and double-clicking the "Add source database" icon, or by running the "Replication|Source|Add" command;

Choosing the schema's target database or databases by selecting a "Target databases" node in the "Replications" treeview and double-clicking the "Add target database" icon, or by running the "Replication|Target|Add" menu command;

Mapping source tables to their targets by selecting a "Replicated tables and procedures" node in the "Replications" treeview and double-clicking the "Replicated tables" icon, or by running the "Replication|Tables|Define" menu command;

Defining the mapped tables' primary keys by selecting a "Key columns" node in the "Replications" treeview and double-clicking the "Define primary key" icon, or by running the "Replication|Columns|Keys" menu command;

Mapping source columns to their targets by selecting a "Data columns" node in the "Replications" treeview and double-clicking the "Define data columns" icon, or by running the "Replications|Columns|Data" menu command.

Finally, and very importantly:

Whenever you have completely defined a replication schema, or altered a previously defined schema, you must create system objects.

See also:

Replication schemata.


Using the replication manager
Using the replication manager:

The main window, dialogs and specialized controls

The replication manager's main window opens when you run the application, IBRplManager.exe. This window gives access to all the application's functionality:

Choosing a configuration;

Registering databases involved in replication;

Maintaining replication schemata;

Administrative tools.

The replication manager is used to maintain data needed by the replication server, and most of that data is captured in dialog boxes. There are dialogs for:

Maintaining configurations;

Setting schema defaults;

Setting schema properties;

Choosing a source database;

Choosing a target database;

Mapping replicated tables and procedures;

Setting table mapping properties;

Defining primary keys;

Identifying data columns.

IBRplManager uses a "field editor" to capture database parameters, and a "mapping window" for connecting source tables, key columns and data columns to their targets. These specialized controls have topics in this help system explaining their usage:

Using the field editor;

Using the mapping window.


Replication tools
Replication tools:

Overview

IBRplManager supplies you with several utilities:

A manual conflict resolution tool for resolving conflicts that the replication server could not solve using the specified conflict resolution strategy (see Schema defaults and the Source database dialog);

A replication monitor which gives a live view of the replication server's activities;

A replication scheduler with which you can specify the frequency with which IBReplicator replicates.

A schema viewer which allows you to view and edit and graphical representation of your replication schemata.


Manual conflict resolution
Replication tools:

Manual conflict resolution

Use the conflict resolution tool to display conflicts which occurred in the replication process.

Select "Tools|Conflicts" from the main window's menu to open the  tool. Select a source database to display all conflicts that may have occurred when replicating from that database.

If any conflicts are present, three data grids will be displayed with records:

The top grid displays the records found in the manual log for that specific published database;

The grid in the middle display the record for the source table that was involved in the conflict;

The bottom grid displays the record for the target table that was involved in the conflict.

If any conflicts are displayed, use the buttons to resolve them:

Force Replication: IBReplicator will try to replicate the troublesome row during its next scheduled replication.

Force all Replication: IBReplicator will try to replicate all the troublesome rows during its next scheduled replication.

Manual correction: Select this option if you want to manually change the data in the source and target tables (only for experienced users);

Commit or Rollback Changes: These buttons are used when correcting manually; use commit to save your changes, or rollback to abandon them.

Delete record: Delete the selected conflict. Data in source and target tables will stay as they are.

Delete all records: Delete all the conflict. Data in source and target tables will stay as they are.

After a option is selected like Force Replication or Commit changes then the record in the manual log will be deleted and the conflict will not be displayed anymore - it has been resolved.


Replication monitor
Replication tools:

The replication monitor

The Replication monitor displays replication activity for one or more databases selected in its treeview.

To start the monitor, select "Tools|Monitor" from the main window's menu.

The graphs are updated as replication occurs; replication may be triggered by the scheduler (which instructs the replication server to replicate at regular intervals) or by manually replicating from the replication server.

Use the tool bar buttons or menu to select the replication data to graph.

Press the "Start" button to start graphing of replication types and the "Stop" button to stop the graphing process.

Features:

You can:

Graph only one type of replication statistic, or any combination of types;

Add or remove any graph or any combination of graphs while the monitor is busy displaying replication information;

Display statistics of graphs by selecting "View|Stats" from the menu. This will display total and last values of each replication type.

Reset the graph at any moment: all selected replication items will then be unselected.

Select other databases or tables in treeview at any moment while graphing of replication items.

Set error and conflict notification by selecting "View|Error/Conflict Notification". In this dialog you can set options such as display message when errors or conflicts occur or mail the designated person when an error or conflict occurs.


The replication scheduler
Replication tools:

The scheduler

To start the replication scheduler, select "Tools|Scheduler" from the main window's menu.

To define a schedule:

Frequency is the interval between automatic replications and may be set to once only, hourly, daily, week days, weekly, or monthly;

Schedule specifies the time when replication must occur.

You can also provide a log file ("Settings|Log file settings") and cause the server to beep whenever it replicates ("Settings|Beep when replicate").


The schema viewer
Replication tools:

The schema viewer

The schema viewer is a tool which allows you to visualize your schema quickly and easily. Open it by running the "Tools|Schema viewer" command in the main window's menu.

Arrange the database icons by dragging them over the image in the background. If you wish to save your layout, simply click on the "Save layout" icon. To restore the default layout (with the database icons arranged in a circle) simply click the "Reset" button.

You access information about each link between databases by right-clicking on the link.

Clicking on the "Options" icon opens the "Options" dialog. This dialog allows you to:

Choose the image you want in the background;

Choose the image the schema viewer should use to represent a database;

Choose the colors in which the links should be drawn;

There is also a "Use defaults" check box. which is used to restore system defaults.


Notifying the server
Replication tools:

Notifying the server

For convenience, IBRplManager gives access to some of the replication server's functionality; these commands are all accessed from the "Tools|Notify server" menu on the manager's main window.

These server commands are:

Reload params: Instructs the server to reload all its settings from the current configuration databases, presumably because the configuration has been altered and there is no need to shut the server down and restart it.

Replicate now: Instructs the server to replicate immediately, without waiting for its next scheduled replication. If you need only occasional replications, you need not schedule replications at all: simply use this command to replicate as necessary.

Synchronize now: Instructs the server to synchronize target tables with their sources, according to the synchronization settings provided in the configuration.


Auto Generate Tables, Keys and Fields

The "Auto Generate Tables, Keys and Fields" dialog.

In cases where the Source database structure and the Target database structure are identical, it is very easy to map all tables and fields in the source database with their counterparts in the target database.

Please note that the Replication Manager does not compare table and field names in the source and target databases, but assumes that all tables in the source database are present in the target database, and proceeds to set up mappings for these tables.

If a table has already been mapped or partially mapped to a table in the target database, then it will be ignored by this process.

This process produces a report which details any errors found, such as no Primary Key. You will need to sort out any errors manually, using the  Replicated Tables and Procedures dialog.

If you wish to map a view in the source database to a table/view in the target database, or a table/view to a Stored Procedure, then you need to use the manual process described in Replicated Tables and Procedures.


What is Bi-Directional Replication

Bi-Directional Replication is used when there are two databases, and each needs to send all changes to the other i.e. they are both source databases, and they are both target databases.

The concept is simple, but care needs to be taken to prevent changes from bouncing back and forth in a loop. See The Special User REPL for an explanation as to why this happens and how to prevent it, and then see Configuring Bi-Directional Replication for further instructions.

n-Way Replication is similar to BI-Directional replication, in that multiple databases are replicating to each other. However, things quickly get very complex. See n-Way Replication for information on how n-Way Replication can be configured.


The special user called REPL
The special user REPL

In a replication environment, any change to data in a replicated table gets moved from the source database to the target. In a bi-directional setup, this causes problems, because a change made to one database gets sent to the second database, and because it induces a change to the second database, the change gets sent straight back again, and so on, in a loop.

Fortunately, there is an easy way to get around this, and that is by using the special case user called REPL. This user is not created automatically, but must be created by the DBA, and sufficient privileges must be granted.

Any change made to a database by the user REPL will not get replicated to the target database.

When setting up each TARGET database in a bi-directional environment be sure to tell the Replication Server to log in as the user REPL. This is done in the "Target Database Dialog".

For more details on configuring Bi-Directional replication go to Configuring Bi-Directional Replication.

NOTE that in n-way replication, the use of the user REPL is of some use, but more work needs to be done to ensure correct replication. See n-Way Replication for more details.


n-Way Replication

n-Way Replication is replication between more than two databases, and can be set up in a number of ways.

In it's simplest form,  each database replicates from/to all others. In this case it is very similar to Bi-Directional Replication and can be set up in exactly the same way.

In more complex scenarios, more work needs to be done. Here is a description of a Hub-and-Spoke setup. In this case there is a central database which controls the replication, fetching data from each database, and forwarding the data to all of the others:

Figure 1: Example of Hub and Spoke Replication layout.

In this example, the New York database fetches data from Chicago, and then forwards it on to Atlanta and San Diego. Clearly, the data from Chicago cannot be written to the New York database using the Special User REPL otherwise it would stop there, and not be forwarded to Atlanta and San Diego. But, if the user REPL is not used, then the data will bounce straight back to Chicago.

In order to get around this we need to create a few new usernames, and use the 'Row Level Replication Condition' to prevent data from bouncing back to the originating database.

In the case of Chicago to New York, the Replication Server logs in as REPL_CHICAGO. In the reverse case (New York to Chicago), we log in as REPL, and have a Row Level Condition of ' USER <> REPL_CHICAGO'. This means that data will move from Chicago to New York, and from there onwards to Altanta and San Diego, but will not bounce back to Chicago. Other changes in New York will move to Chicago (amongst others) and stop there because of the use of the user REPL.

Here is a table of the UserNames and conditions required in the above scenario:

SOURCE	TARGET	USERNAME	CONDITION
Chicago	New York	REPL_CHICAGO
San Diego	New York	REPL_SANDIEGO
Altanta	New York	REPL_ATLANTA
New York	Chicago	REPL	USER <> 'REPL_CHICAGO'
New York	San Diego	REPL	USER <> 'REPL_SANDIEGO'
New York	Atlanta	REPL	USER <> 'REPL_ATLANTA'


Configuring Bi-Directional Replication

Setting up Bi-Directional replication is very straight forward:

First, add the two databases to the Databases Tab.

Next, add a new schema and set the first database as the source database, and the second database as the target database.  See The Special user REPL for important information on bi-directional replication.

After that, map the required tables and fields from the source to the target. Use the Replicated tables and procedures dialog or do it automatically with the Auto Generate Tables, Keys and Fields dialog.

Then execute the Create System Objects function on the source database.

That concludes the replication in one direction. To set up replication in the other direction, create a new schema as described above, but reverse the source and target databases.