• between an HFSQL database and an Oracle database.
• between HFSQL Classic or HFSQL Client/Server databases.
• etc.

• .rpm file: file used to describe a master database and the databases subscribed to it. Contains the name of the ".syn" file for each subscriber. This file is a text file. It is created and stored on the computer that will be used to connect to the master database.
• .rpl file: file describing a subscriber base. A "rpl" file is created for each subscriber database. This file is found on the subscriber computer. Contains the subscriber's ".syn" file name. This file is a text file. It is created on the master computer then transferred to the subscriber computer.
• .rpa file log file containing replication information. This file is exchanged between the master database and the subscriber database. This file is created by HCreateMovableReplica, and it is read and deleted by HSynchronizeReplica. The content is incremental: if two HCreateMovableReplica in the same direction are executed in succession, the second file will contain the equivalent of the first, with the addition of recent modifications. If a ".rpa" is "lost", simply redo it: it will contain all the modifications. If several "rpa" files are present on the subscriber, simply execute the last one.. This file is in binary format.
• .syn file: file containing information on the status of the remote base. This file is used to optimize the size of the synchronization files. This file is found on the master computer and on each subscriber computer. This file is in binary format.

Operating mode of replication

Database structure

Step 1: Installation on the master site

1. To enable universal replication, simply use HSetReplication with the rplReplicationUniversal constant.
   

   HSetReplication(rplReplicationUniversal)

   
   This function is used to disable the standard replication mode (if it was enabled) and to enable universal replication.
2. Creating the base directory of data (optional)
   You have the ability to create a directory that will receive the database files. This directory will be shared on the server of the master site in order for the users to access the data.
   

   // Create the data directory
   fMakeDir(gsMasterDirectory)
   // Connect to this location
   HOpenConnection(MasterConnection)
   HChangeConnection(CLIENT, MasterConnection)

3. Creating the data files of the application (optional)
   If the data files do not exist, you have the ability to create empty data files (HCreation). This data will be handled by the users of the master site.
4. Creating the master replica
   To declare the master database, all you have to do is use HCreateMasterReplica.
   

   HCreateMasterReplica(gsMasterDirectory)

   
   This line of code creates the file "ReplicaMaster.rpm" on disk.. Then, all you have to do is write the subscribers into this file.

Step 2: Preparing subscriber site data

1. Creation of an data home directory (optional)
   You have the ability to create a directory that will receive the database files.
2. Creating the subscriber replica
   To create a new subscriber, use HCreateSubscriberReplica. This function creates a subscriber ("rpl" file) with the specified name. This functions also returns a subscriber number.
   As soon as it is created, the subscriber is ready to receive the data from the master replica that was used to initialize it. This first synchronization is used to make sure that the content of the subscriber identical to the content of the master.
   

   // Create the subscriber replica
   HCreateSubscriberReplica(gsMasterDirectory, gsSubscriberDirectory, ...
   		"Subscriber1", 0, "Customer" + TAB + "DATETIMEID")

   
   In this example, the "DATETIMEID" item corresponds to a "DateTime" item that must be available to the database (for a database not in HFSQL Classic or Client/Server format). This item will have to be updated by the application when modifying or adding a record. If the databases use different time zones, we recommend that you use a universal format (GMT date and time for example).
   This item is not required for an HFSQL Classic or Client/Server database.
   Note: A parameter in function HCreateSubscriberReplica is used to specify whether automatic data modification is to be taken into account.. For more details, see Remarks.

• Code of the trigger:
  

  TriggerResult is boolean
  TriggerResult = HDescribeTrigger("*", "HADD,HMODIFY,HDELETE,HCROSS,HWRITE", ...
  		"AddDateTime",hTriggerBefore)
  IF TriggerResult = False THEN Error(HErrorInfo())

• Procedure called by the trigger:
  

  PROCEDURE AddDateTime()
  TestReplic.Itm_DateTime = DateSys()+TimeSys()

Step 3: Installation on the subscriber site

1. When the data is "prepared" for the subscriber site (".rpl", ".syn" files), simply activate the replication mechanism on the subscriber site (function HSetReplication)..
   

   HSetReplication(rplReplicationUniversal)

2. The subscriber site must create its blank database (HCreation) before the first synchronization:
   

   HCreation(CUSTOMER)

   
   This database will be initialized during the first synchronization.

Step 4: Initial synchronization of master and subscriber sites

1. Creation of a transportable replica:
   A movable replica will be created from the master database. it will contain the data of the database from which the master replica was created. This operation is performed with HCreateMovableReplica. The HCreateMovableReplica function creates a log file (".rpa" file).
   

   HCreateMovableReplica(sMasterReplica, "Master","")

2. Integration of the transportable replica in the subscriber database:
   The data found in the master database is imported into the subscriber database by HSynchronizeReplica.
   

   sMovableReplica= gsMasterDirectory +RPL.File
   HSynchronizeReplica(sMovableReplica, ...
   	gsAbonneDirectory + "Replica_Abonne1.rpl", rplToSubscriber)
   fDelete(sMovableReplica)

3. The subscriber is now created. The subscriber files can now be moved to the subscriber site. This operation can be carried out by any means of copying, the key being to create an empty database and carry out an initial replication on the site.

• As soon as a subscriber replica is initialized, you must no longer replace/restore one of the master files (because they contain information regarding the ranges of identifiers for the subscriber replicas).
• All the database files do not necessarily have to be replicated. Replicate the necessary data files only.

Step 5: Daily synchronizations

1. Generate a movable replica (HCreateMovableReplica).
2. Transmit the movable replica to the relevant site (master or subscriber).
3. Synchronize the database via the movable replica via HSynchronizeReplica.

• rplPriorityMaster: this is the default replication mode. It is used to protect the database of the "master" site from the modifications performed in the "subscriber" site. The modifications made to the subscriber sites will not be carried over in this mode (except for the additions).
• rplSubscribedPriority: this replication mode gives the subscribed site(s) priority over the master site.. In this mode, the master site is a copy of the different subscribers but the modifications are not carried over among the different subscribers.
• rplPlusRecentPriority: this mode is used to propagate all changes made to databases.. This operating mode must be used when all the databases have the same priority (the modifications are carried over to all the databases).

• Check the replicated files. All the database files do not necessarily have to be replicated. Replicate the necessary data files only.
• The exchange of ".rpa" files is not necessarily symmetrical: it is possible to create and execute several logs in one direction without creating and executing a single log in the other direction.. However, to improve performance, you should avoid performing exchanges always in the same direction.
• The replication respects the filters applied to the tables or to the files (except for links, to respect the integrity).
• A filter can be implemented on the master side: the subscribers will receive a subset of the data from the master database. In this case, there is no need to implement a filter for the subscriber database.
  If, due to the filter, a record is not "visible" anymore on the master database, this record will be considered as being deleted. It will be automatically deleted from the subscriber computer.
• HRecreateSubscriberReplica is used to recreate a subscriber replica from the master replica.
• Take automatic data modification into account (HFSQL Classic or Client/Server databases):
  When creating the subscriber replica with HCreateSubscriberReplica, you can specify whether the automatic data modification must be performed during replication. In this case:
  • Changes in the structure of the master database will be carried over to the subscriber database. This will be done during replication.
    Caution: This operation can significantly increase the time required for replication.
  • The new items will be taken into account by the replication.
  Remarks:
  • This mechanism does not work if a unique key is added or deleted..
  • For an existing replication, it is necessary to recreate this replication (as well as the subscribers) to take into account this functionality.

• Each file or table must have at least one unique key.
• You must have the ability to associate a date with a record. If the item used to associate a date with the record is automatically filled by a trigger, this trigger must be disabled when running HSynchronizeReplica (to avoid filling this item with the replication date).
  Remark: For HFSQL databases (Classic or Client/Server), the record date field is automatically managed.
• The replication does not open the files or the tables. The files or the tables must have be opened by the program before starting the replication.
• During the replication, the memory consumption may be very high. Therefore, only the necessary records should be replicated toward a subscriber computer.
• Caution: specific case: only part of the linked tables is not replicated. In this case, replication sometimes replays certain modifications such as an {addition, deletion} pair.. If a non-replicated table is linked with cascading modifications, the linked records may be wrongly deleted.
• Replication will not be performed in the following cases: one of the files to be replicated is secure, password-protected and used in a link with integrity rules..