ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / Managing databases / HFSQL / HFSQL functions
  • Which data files can be replicated?
  • Synchronization parameters
  • Locking records during the log-based replication
  • Duplicate errors and/or integrity errors
  • Variables automatically initialized in the WLanguage procedure
  • Example: Replicating the data even if a conflict occurred (using a WLanguage procedure):
  • Replication and WithSpace function
  • Lifespan of movable replica
  • Replication and filter
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
HSynchronizeReplica (Function)
In french: HSynchroniseRéplica
ODBCOLE DBNot available with these kinds of connection
Synchronizes the master replica and the subscriber replica: the operations performed on one of the replicas are transferred into the other replica.
This function can be used in a log-based replication (between HFSQL data files) or a universal replication.
Remarks:
  • For a log-based replication, only the data files in the analysis with the option "Manage the replication for this file" checked will be taken into account.
  • HFSQL Client/Server Only the universal replication operates with the HFSQL Client/Server data files.
  • Universal Windows 10 AppAndroidAndroid Widget iPhone/iPad Only the universal replication is available.
Warning
From version 17, the replication files created with an application or a site in version 17 (or later) cannot be handled by an application or a site in version 16 (or earlier).
The applications or the sites in version 17 (or later) continue to handle the replication files created with an application or a site in version 16 (or earlier).
WINDEVWEBDEV - Server codeReports and QueriesUser code (UMC)AjaxHFSQL ClassicHyper File 5.5
// "Entering Orders" application for salesmen
// "[Enter the orders in the database]" button
// (the database is found on "X:\CORPDATA")
HSynchronizeReplica("X:\CORPDATA", "C:\SUBSCRIBER", rplToMaster)
WINDEVWEBDEV - Server codeReports and QueriesUser code (UMC)AjaxHFSQL ClassicHyper File 5.5
// "Catalog" application for salesmen
// "[Retrieve the new references]" button
// (the database is found on "X:\CORPDATA")
HSynchronizeReplica("X:\CORPDATA", "", rplToSubscriber)
WINDEVWEBDEV - Server codeReports and QueriesUser code (UMC)AjaxHFSQL ClassicHyper File 5.5
// In Montpellier: Prepare to send messages to Paris
HCreateMovableReplica("P:\MSG\MSG.RPM", "Paris", "C:\Temp\MsgMPL.WDZ")
// Send the file (by FTP for example)
FTPSend(ConnectionNum, "c:\temp\MsgMPL.WDZ", ...
"FTP.PCSOFT_PARIS.FR\MSG\MsgMPL.WDZ")
----------------
// In Paris: Retrieve the messages from Montpellier
HSynchronizeReplica("Z:\MSG", "\\FTPSERVER\MSG\MsgMPL.WDZ", rplToMaster)
Syntax

Synchronization with automatic conflict management Hide the details

<Result> = HSynchronizeReplica(<Master replica> , <Subscriber replica> , <Replication direction> [, <Management of conflicts>])
<Result>: Boolean
  • True if the operation was successful,
  • False otherwise.
<Master replica>: Character string
Location of the master replica. Depending on the replication type and direction, this parameter can correspond to:
  • the path of the replication file (xxxx.RPM file) for the master database.
  • the name of the movable file created by HCreateMovableReplica.
  • an empty string (""). The current data files are considered as the master database. The file corresponding to the master replica (.RPM) is sought either in the replication directory specified in the analysis (RPL subdirectory of data files by default), or in the directory specified with HChangeRplDir.
In most cases, this path corresponds either to the full path of a file located in a network directory, or to the path of a movable replica (USB key, email attachment, file retrieved by FTP).
For more details, see the remarks.
<Subscriber replica>: Character string
Location of the subscriber replica. Depending on the replication type and direction, this parameter can correspond to:
  • the path of replication file (xxxx.RPL file) for the subscriber database.
  • the name of the movable file created by HCreateMovableReplica
  • an empty string (""). The current data files are considered as being the subscriber database. The file corresponding to the subscriber replica (.RPL) is sought either in the replication directory specified in the analysis (RPL subdirectory of data files by default), or in the directory specified by HChangeRplDir.
In most cases, this path corresponds either to the full path of a file located in a network directory, or to the path of a movable replica (USB key, email attachment, file retrieved by FTP).
For more details, see the remarks.
<Replication direction>: Integer constant
Direction in which the replication will be performed:
rplBidirectionalUpdate the master database AND the subscriber database.

Universal replication: the bidirectional replication is not available.
rplToMasterUpdate the master database according to the subscriber database.

<Master replica> corresponds to the master replica, <Subscriber replica> corresponds to the movable replica created from the subscriber database.
rplToSubscriberUpdate the subscriber database according to the master database.

<Master replica> corresponds to the movable replica created from the master database, <Subscriber replica> corresponds to the subscriber replica
<Management of conflicts>: Optional Integer constant
Constant indicating the management mode of conflicts:
rplMasterFirst
(Default value)
The data found in the master database has priority during the replication.
rplMostRecentFirstThe most recent data has priority. Caution, the most recent data is evaluated according to the time on the subscriber replica.
rplSubscriberFirstThe data found in the subscriber database has priority during the replication.
Caution: By default, the master has priority: when performing a replication from subscriber to master, the master data will not be updated. We recommend that you use another constant (rplMostRecentFirst for example).

Synchronization with custom conflict management (WLanguage procedure) Hide the details

<Result> = HSynchronizeReplica(<Master replica> , <Subscriber replica> , <Replication direction> [, <Filter procedure>])
<Result>: Boolean
  • True if the operation was successful,
  • False otherwise.
<Master replica>: Character string
Location of the master replica. Depending on the replication type and direction, this parameter can correspond to:
  • the path of replication file (xxxx.RPM file) for the master database.
  • the name of movable file created by HCreateMovableReplica.
  • an empty string (""). The current data files are considered as being the master database. The file corresponding to the master replica (.RPM) is sought either in the replication directory specified in the analysis (RPL subdirectory of data files by default), or in the directory specified with HChangeRplDir.
In most cases, this path corresponds to the full path of a file located in a network directory or to the path of a movable replica (USB key, email attachment, file retrieved by FTP).
For more details, see remarks.
<Subscriber replica>: Character string
Location of the subscriber replica. Depending on the replication type and direction, this parameter can correspond to:
  • the path of replication file (xxxx.RPL file) for the subscriber database.
  • the name of the movable file created by HCreateMovableReplica
  • an empty string (""). The current data files are considered as being the subscriber database. The file corresponding to the subscriber replica (.RPL) is sought either in the replication directory specified in the analysis (RPL subdirectory of data files by default), or in the directory specified by HChangeRplDir.
In most cases, this path corresponds to the full path of a file located in a network directory or to the path of a movable replica (USB key, email attachment, file retrieved by FTP).
For more details, see the remarks.
<Replication direction>: Integer constant
Direction in which the replication will be performed:
rplBidirectionalUpdate the master database AND the subscriber database.

Universal replication: the bidirectional replication is not available.
rplToMasterUpdate the master database according to the subscriber database.

<Master replica> corresponds to the movable replica created from the master database, <Subscriber replica> corresponds to the subscriber replica
rplToSubscriberUpdate the subscriber database according to the master database.

<Master replica> corresponds to the master replica, <Subscriber replica> corresponds to the movable replica created from the subscriber database.
<Filter procedure>: Optional procedure name
Name of a WLanguage procedure found in the WINDEV or WEBDEV project (this name must be enclosed in quotes). This procedure must be created in your application. This procedure expects no parameter.
This procedure is called before each operation performed on the destination file. Several variables can be used in this procedure.
If this procedure returns False, the operation is not performed. This procedure is used to:
  • filter the records that must not be replicated.
  • manage the conflicts, by adjusting the values before a duplicate error occurs.
For more details, see the example of HSynchronizeReplica.
Remarks
WINDEVWEBDEV - Server codeReports and QueriesUser code (UMC)AjaxHFSQL ClassicHyper File 5.5Native Connectors (Native Accesses)

Which data files can be replicated?

The synchronization can be performed:
  • between two databases linked by network.
  • between a database and a movable replica (created by HCreateMovableReplica).
No replication can be performed toward a movable replica. You must create a movable replica with the database and replicate from the remote database.
Caution: If you perform an automatic update of your data files, all the replicas must be synchronized before this operation. Otherwise, all the modifications performed since the last synchronization and the automatic modification will be lost.

Synchronization parameters

The table below presents the different combinations of parameters that must be used according to the replication type and direction:
Replication direction<Master replica><Subscriber replica><Replication direction>
Replication from master to subscriber
This replication is performed on the subscriber computer
Name of movable replica (*.RPA) created from the master, with its eventual pathName of subscriber replica (*.RPL), with its eventual path.rplToSubscriber
Replication from subscriber to master
This replication is performed on the master computer
Name of master replica (*.RPM), with its eventual path.Name of movable replica (*.RPA) created from the subscriber, with its eventual path.rplToMaster
WINDEVWEBDEV - Server codeReports and QueriesUser code (UMC)AjaxHFSQL ClassicHyper File 5.5

Locking records during the log-based replication

During the replication, the JournalOpération.Fic file is locked: you cannot write, modify or save records in the files with logs in the destination database.
WINDEVWEBDEV - Server codeReports and QueriesUser code (UMC)AjaxHFSQL ClassicHyper File 5.5

Duplicate errors and/or integrity errors

If a duplicate error or an integrity error occurs, the standard mechanism for automatic management of errors is triggered. If the HFSQL engine returns an error, the replication is interrupted: only part of the data is replicated.
Universal replication: If an integrity error occurs during the replication, the replication continues but the function returns False.
To get the details of errors, you must read the HFSQL sub-errors with HError (with the hSubErrFirst and hSubErrNext constants) then call HErrorInfo.
WINDEVWEBDEV - Server codeReports and QueriesUser code (UMC)AjaxHFSQL ClassicHyper File 5.5Native Connectors (Native Accesses)

Variables automatically initialized in the WLanguage procedure

VariableTypeDescription and value
RPL.FileCharacter stringName of the file whose data will be replicated
RPL.OperationInteger constantHFSQL operation that will be replicated:
  • rplHAdd: replicate an addition
  • rplHModify: replicate a modification
  • rplHDelete: replicate a deletion
RPL.ConflictInteger constantIndicates whether a conflict was detected during the replication. The possible values are as follows:
  • rplNoConflict: no conflict was detected
  • rplModifyConflict: The record was modified both in the source replica and in the destination replica
  • rplDeleteConflict: The record was deleted from the destination replica and it was modified or deleted in the source replica.
To force the replication if a conflict occurred, RPL.Conflict must be initialized with the rplNoConflict variable.

Otherwise, the replication will be performed only if the conflict is a modification conflict and if the data to replicate comes from the master database.
RPL.DirectionInteger constantIndicates the direction of replication (useful for a bidirectional replication):
  • rplToSubscriber: replication from master to subscriber
  • rplToMaster: replication from subscriber to master
RPL.OperationNumIntegerNumber of the current operation. This value is included between 1 and RPL.OperationMax. This variable allows you to easily manage a progress bar.
RPL.OperationMaxIntegerTotal number of operations to replicate. This variable allows you to easily manage a progress bar.
RPL.SourceAliasCharacter stringName of the source alias for the replicated file (RPL.File). This file contains the values of items that will be copied (HAdd) or added (HModify) into the file currently replicated.
RPL.TargetAliasCharacter stringName of target alias of replicated file (RPL.File). This file contains the values of the items before performing the copy or the deletion in the file currently replicated.
WINDEVWEBDEV - Server codeReports and QueriesUser code (UMC)AjaxHFSQL ClassicHyper File 5.5Native Connectors (Native Accesses)

Example: Replicating the data even if a conflict occurred (using a WLanguage procedure):

This example is used to force the replication of data even if a modification conflict occurs. To do so, force the value of the RPL.Conflict variable with the rplNoConflict constant.
IF RPL.Conflict = rplModifyConflict THEN
RPL.Conflict = rplNoConflict
RETURN True
END

Replication and WithSpace function

The replication is not compatible with WithSpace in the code of the client application. This function changes the nehavior of HFSQL. Using this function in the client application can affect the efficiency of replication.
From version 21 update 3 (version 210065), the synchronization functions (programmed or assisted universal replication) return an error to the client application if WithSpace was applied to at least one of the replicated files.

Lifespan of movable replica

The replica is destroyed at the end of the replication in case of success. Replaying the replica will cause errors (for example, an addition causes a duplicate error). The replica uses the .syn file that is destroyed as well (another .syn file replaces it with the useless cleared information).
A "movable" replica is moved (copied) between the master and the subscriber or between the subscriber and the master. To store an archive, all you have to do is store the source file (the one created by HCreateMovableReplica).

Replication and filter

When browsing the data to replicate, the replication takes into account the filters positioned by HFilter.
Therefore, for a programmed universal replication without replication server, HFilter can be used to limit the data to synchronize.
On the contrary, for a replication performed via a replication server, all the filters must be disabled before performing the replication with HSynchronizeReplica.
Remark: HClose is used to delete all the filters defined by HFilter on a data file.
Component: wd290rpl.dll
Minimum version required
  • Version 9
This page is also available for…
Comments
Click [Add] to post a comment

Last update: 03/17/2023

Send a report | Local help