Data replication is a powerful FairCom DB feature providing near real-time data availability between one or more servers. These options configure specific attributes of this optional feature.
Auto-Numbering Replication Defaults Changed
In this release, changes were made to the FairCom Server defaults for replication behavior on SRLSEG and identity fields.
Compatibility Note: This is a change in behavior, but many of the FairCom Server configuration files included in FairCom products already contain this option so the behavior is already in effect in those cases. However, the FairCom RTG package did not include these options, so this will change the default behavior for FairCom RTG COBOL and FairCom ISAM.
The default values have been changed for the following options:
REPL_SRLSEG_ALLOW_UNQKEY now defaults to YES
This option allows a SRLSEG index to be used as a replication unique index. Without this option, a data file whose only unique index is a SRLSEG index would not qualify for replication. By changing this default to YES, the SRLSEG index can be used as a replication unique index, which is the commonly-expected behavior.
REPL_SRLSEG_USE_SOURCE now defaults to YES
This option uses the serial number value from the source FairCom Server when adding a record to a replicated file. This option applies to c-tree's asynchronous (source/target) replication model, in which a Replication Agent replicates changes from a source FairCom Server to a target FairCom Server. By changing this default to YES, records added to the target server will contain the SRLSEG value from the record on the source server, rather than the target server generating its own SRLSEG value for the new record. This default option corresponds to the behavior that is most likely to be expected.
REPL_SRLSEG_USE_MASTER now defaults to YES
This option uses the serial number value from the master FairCom Server when adding a record to a replicated file. This option applies to c-tree's synchronous (local/master) replication model, in which an update to a record on a local FairCom Server triggers an update to the record in the associated table on the master FairCom Server. By changing this default to YES, records added to the local server will contain the SRLSEG value from the record on the master server, rather than the local server generating its own SRLSEG value for the new record. This default option corresponds to the behavior that is most likely to be expected.
REPL_IDENTITY_USE_SOURCE now defaults to YES
This option uses the identity field value from the source FairCom Server when adding a record to a replicated file. This option applies to c-tree's asynchronous (source/target) replication model, in which a Replication Agent replicates changes from a source FairCom Server to a target FairCom Server. By changing this default to YES, records added to the target server will contain the identity field value from the record on the source server, rather than the target server generating its own identity field value for the new record. This default option corresponds to the behavior that is most likely to be expected.
REPL_IDENTITY_USE_MASTER now defaults to YES
This option uses the identity field value from the master FairCom Server when adding a record to a replicated file. This option applies to c-tree's synchronous (local/master) replication model, in which an update to a record on a local FairCom Server triggers an update to the record in the associated table on the master FairCom Server. By changing this default to YES, records added to the local server will contain the identity field value from the record on the master server, rather than the local server generating its own identity field value for the new record. This default option corresponds to the behavior that is most likely to be expected.
MAX_REPL_LOGS
MAX_REPL_LOGS <max_logs>
Changes the limit FairCom Server sets for the number of active transaction logs that are kept for deferred index and Replication Agent processing.
In V12 and later, the default is 100; prior to V12, the default was 50.
Specifying a value of zero for <max_logs> removes the limit.
Tip - If you find error 96 on startup due to logs not found, it is likely be due to MAX_DFRIDX_LOGS or MAX_REPL_LOGS settings removing logs after the max is reached. Be sure to review your operational environment for appropriate settings.
See also:
REPLICATE
REPLICATE <filename>
Server Configuration Option
The easiest method to define files that should be replicated is directly at the source using the REPLICATE keyword:
REPLICATE <filename>
When included in ctsrvr.cfg this specifies which file(s) to enable transaction log information for replication. Multiple REPLICATE statements are allowed. The file name may include wildcard characters (see FairCom DB Standard Wildcards). Multiple entries are supported.
Note: Choose wild cards carefully as certain FairCom files, such as REPLSTATEDT.FCS, must not be replicated. For example, REPLICATE *.dat is preferable to REPLICATE *. Another set of files that can be unexpectedly affected are c-tree Superfile members that match a wildcard specification.
External XML File Filters
File definitions can be specified by an external XML definition. This allows dynamically enabling replication without stopping and starting servers for configuration changes. This file can be set in ctreplagent.cfg and changed at runtime using repadm -c changefilter and -c removefilter with -x option indicating the external filter file name. repadm requests the replication agent to perform the specified filter operation and the replication agent applies the filter to the source server if the purposes indicate that it applies to the source server.
XML file filters are defined as follows:
<?xml version="1.0" encoding="us-ascii"?>
<replfilefilter version="1" update="1" persistent="y">
<file status="include">mark.dat</file>
<file status="exclude">donotreplicate*.dat</file>
<file status="include" regexPath=".\ctreeSQL.dbs">.*((data|dat|db))</file>
<purpose>create_file</purpose>
<purpose>open_file</purpose>
<purpose>read_log</purpose>
<purpose>sync_commit</purpose>
</replfilefilter>
Attributes
version="1.0" is the XML format version defining the current specification.
persistent="y" persists the filter definition on the source source such that it is automatically loaded on startup. REPLFFCHGDT.FCS
update="1" Processes an update to the current file filter.
Elements
<file> - list of files to include or exclude from replication. This supports regular expressions. The regexPath tag specifies an optional path as a regular expression and is applied to only the file name without path.
<purpose> indicates the purposes of the filter.
- open_file - applies names to the source server like the server configuration REPLICATE does. This enables matching files for replication.
- read_log - applies to the source server to determine which log entries are returned to the replication log reader like original replication file filter does.
- sync_commit - makes a synchronous commit of the specified replicated file
- create_file - create file on target if it doesn't exist
See Also
file_filter
Note: The low-level FairCom DB UpdateHeader() API can be used to enable replication on a per file basis. Use the ctREPLCIATEhdr mode with either NO (off) or YES (on) for the hdrval. If the file does not have an extended header, then the change will not persist once the file is closed and reopened. Because failure to enforce replication is a serious problem, UpdateHeader() returns a special error code, -EXTH_ERR (-734), when the request succeeds, but the file header is not extended. This is more of a warning than an error.
See Also
REPL_IDENTITY_USE_MASTER
REPL_IDENTITY_USE_MASTER <YES | NO>
Forces the local FairCom DB process to use the serial number value from the master server when adding a record to a local replica.
See Also
REPL_IDENTITY_USE_SOURCE
REPL_IDENTITY_USE_SOURCE <YES | NO>
Forces the target FairCom DB process to use the identity field value from the source server when adding a record to a replicated file.
See Also
REPL_MAPPINGS
REPL_MAPPINGS <mapfilename>
Specifies a local filename mapping to a master server. Multiple instances of this keyword can be used.
This keyword also forces the local FairCom DB process to attempt to load the multi-threaded c-tree client library (mtclient.dll or libmtclient.so), which it uses to communicate with a master FairCom DB process. If this library cannot be loaded, or if it does not contain the required functions, FairCom DB fails to start with the error TR_CLIL_ERR (850, Transactional replication: Failed to start c-tree remote client subsystem: see CTSTATUS.FCS for details).
See Also
REPL_NODEID
REPL_NODEID <nodeid>
The FairCom Server assigns a node ID to FairCom Replication. The Local/Master replication scheme also assigns a node ID to connections that are established from the target server to the source server.
A local c-tree Server can set its replication node ID by using the REPL_NODEID option in ctsrvr.cfg. For example, consider a source server and two target servers:
; source server configuration
SERVER_NAME MASTER
REPL_NODEID 10.0.0.1
; target server 1 configuration
SERVER_NAME LOCAL01
REPL_NODEID 10.0.0.2
; target server 2 configuration
SERVER_NAME LOCAL02
REPL_NODEID 10.0.0.3
ID values are arbitrary and do not need to match the IP address of the system on which the c-tree Server is running. They only need to be unique and not change during replication. (This example demonstrates IP v4 addresses.)
FairCom Replication reads the node ID of the source and target servers. If the node ID is not set for a source or target server, FairCom Replication uses the IP address of the system on which that FairCom DB is running.
Note: REPL_NODEID should be used if the entry for source_server or target_server in ctreplagent.cfg does not specify an IP address (e.g., if localhost or the DNS name is used).
Dynamically Set Replication Node ID
A replication node ID value (REPL_NODEID) associates a Replication Agent to a specific source or target server. Having this required association prevents Replication Agents from arbitrarily connecting to inappropriate servers. Setting a REPL_NODEID required modifying the server configuration file, ctsrvr.cfg, and restarting a server, which is challenging in round-the-clock production environments.
c-tree Server now supports setting a REPL_NODEID value dynamically at runtime if it has not yet been set. This keyword sets the node ID of a local c-tree Server for use in replication.
To set the value, use the ctadmn utility's option to change a server configuration option value using option 10 or call the ctSETCFG() function as shown here:
NINT rc;
rc = ctSETCFG(setcfgCONFIG_OPTION, value);
where value is the REPL_NODEID value to set, specified as a NULL-terminated string in IPv4 format (n.n.n.n.), for example "10.0.0.1". (ID values are arbitrary and do not need to match the IP address of the server.)
Note that the value is only changed in memory and not persisted to disk. Be sure to update the configuration file such that the new value is persisted and enabled on the next server startup.
REPL_READ_BUFFER_SIZE
REPL_READ_BUFFER_SIZE <size>
Sets the size of the replication log read buffer. Specify a value of zero to disable the use of the replication log read buffer.
Default: 8K
See Also
REPL_SRLSEG_ALLOW_UNQKEY
REPL_SRLSEG_ALLOW_UNQKEY <YES | NO>
Forces FairCom DB to allow an index that contains a SRLSEG segment to be the replication unique key.
See Also
REPL_SRLSEG_USE_MASTER
REPL_SRLSEG_USE_MASTER <YES | NO>
Forces a local FairCom DB process to fill in the serial number value from the master FairCom DB process when adding a record to a local replica. (Synchronous master/local replication model.)
See Also
REPL_SRLSEG_USE_SOURCE
REPL_SRLSEG_USE_SOURCE <YES | NO>
Forces a FairCom DB process replication writer thread to fill in the serial number value from the source server when adding a record to a replicated file. (Standard replication model.) This preserves existing serial numbering.
See Also
DIAGNOSTICS REPLICATE
DIAGNOSTICS REPLICATE
The configuration option DIAGNOSTICS REPLICATE enables FairCom DB to log messages to CTSTATUS.FCS when a file that is being created or opened matches the filename specified for the REPLICATE keyword, and it does not meet replication requirements. This is useful in initial setup to determine unexpected replication failures.
Sample Output
Mon Apr 09 10:48:21 2012
- User# 00014 REPLICATE_DIAG: None of the indexes for the file mark.dat qualify as a replication unique key:
Mon Apr 09 10:48:21 2012
- User# 00014 REPLICATE_DIAG: index 1 is not unique
Mon Apr 09 10:48:21 2012
- User# 00014 REPLICATE_DIAG: index 1 supports null keys
Mon Apr 09 10:48:21 2012
- User# 00014 REPLICATE_DIAG: index 2 is not unique
Mon Apr 09 10:48:21 2012
- User# 00014 REPLICATE_DIAG: index 3 is not unique
Mon Apr 09 10:48:21 2012
- User# 00014 REPLICATE_DIAG: index 3 supports null keys
Mon Apr 09 10:48:21 2012
- User# 00014 REPLICATE_DIAG: index 3 contains a SRLSEG segment
The SetSystemConfigurationOption() API function can be used to turn this diagnostic option on and off at run time.