Command Syntax:

mupip set {-file db-file|-region reg-list} -replication={ON|OFF}

Qualifiers:

-file and -region

Use these qualifiers in the same manner that you would use them for a MUPIP SET. For more information refer to Chapter 5: “General Database Management”.

-replication=replication-state

Switches the GT.M replication subsystem ON/OFF and possibly modify the current journaling [no-]before image field (which is stored in the database file header).

replication-state is either of the following keywords:

OFF

Disable replication of the database file(s) or region(s). Even if you turn off replication, journaling continues to operate as before.

Important

GT.M creates a new set of journal files and cuts the back link to the previous journal files if the replication-state is OFF and then turned ON again. The database cannot rollback to a state prior to ON. Therefore, ensure that replication-state remains ON throughout the span of database replication. Turn replication-state OFF only if database replication is no longer needed or the instance is about to be refreshed from the backup of the originating instance.

ON

Enables replication for the selected database file(s) or region(s). When the JOURNAL qualifier is not specified, this action turns BEFORE_IMAGE journaling on. Specify -JOURNAL=NOBEFORE_IMAGE to enable replication with no-before-image journaling. In both cases, GT.M creates a new journal file for each database file or region, and switches the current journal file. FIS recommends you to specify the desired journaling characteristics (MUPIP SET -JOURNAL=BEFORE_IMAGE or MUPIP SET -JOURNAL=NOBEFORE_IMAGE).

When replication is ON, a MUPIP SET REPLICATION=ON command with no JOURNAL qualifier assumes the current journaling characteristics (which are stored in the database file header). By default GT.M sets journal operation to BEFORE_IMAGE if this command changes the replication state from OFF to ON and JOURNAL=NOBEFORE_IMAGE is not specified. Therefore, conservative scripting should always specify the desired journaling characteristics using the JOURNAL qualifier of the MUPIP SET command.

The replication state ON in the file header denotes normal replication operation.

[WAS_ON] OFF

Denotes an implicit replication state when GT.M attempts to keep replication working even if run-time conditions such as no available disk space or no authorization for a process attempting to auto-switch a journal file cause GT.M to turn journaling off. Even with journaling turned off, the Source Server attempts to continue replication using the records available in the replication journal pool. In this state, replication can only continue as long as all the information it needs is in the replication journal pool. Events such as an operationally significant change on the replicating instance(s) or communication problems are likely to cause the Source Server to need information older than that in the replication journal pool and because it cannot look for that information in journal files, at that point the Source Server shuts down.

	Note
	If the replication ON state is like a bicycle running smoothly on the road, replication WAS_ON is like a bicycle with a flat front tire being ridden like a unicycle - the system is operating outside its intended mode of use and is more subject to misfortune.

WAS_ON is an implicit replication state. At all times during the WAS_ON state, you can see the current backlog of transactions and the content of the Journal Pool (MUPIP REPLICATE -SOURCE -SHOWBACKLOG and MUPIP REPLICATE -SOURCE -JNLPOOL -SHOW). This information is not available in the replication OFF state.

For more information on recovering originating and replicating instances from WAS_ON, refer to Recovering from the replication WAS_ON state .

Example:

$ mupip set -replication=on -file mumps.dat

This example enables database replication and turns before-image journaling on for mumps.dat.

$ mupip set -replication=on -journal=nobefore_image -file mumps.dat

This example enables database replication and turns no-before-image journaling on for mumps.dat.

$ mupip set -replication=off -file mumps.dat

This example turns off database replication for mumps.dat.

Command Syntax:

mupip replicate -instance_create -name=<instance name> [-noreplace] [-supplementary] [-noqdbrundown] 

Qualifiers:

-instance_create

Creates a replication instance file. mupip replicate -instance_create takes the file name of the replication instance file from the environment variable gtm_repl_instance.

If an instance file already exists, GT.M renames it with a timestamp suffix, and creates a new replication instance file. This behavior is similar to the manner in which GT.M renames existing journal files while creating new journal files. Creating an instance file requires standalone access.

-name

Specifies the instance name that uniquely identifies the instance and is immutable. The instance name can be from 1 to 16 characters. GT.M takes the instance name (not the same as instance file name) from the environment variable gtm_repl_instname. If either gtm_repl_instname is not set or -name is not specified, GT.M produces an error. For more information, refer to the entries for gtm_repl_instname and gtm_repl_instance in “Environment Variables”.

-noreplace

Prevents the renaming of an existing replication instance file.

-supplementary

Specifies that the replication instance file is suitable for use in a supplementary instance.

-noqdbrundown

Permits more than 32,767 udpating processes to concurrently the replication instance file and database file(s). The default (-noqdbrundown) permits up to 32,767 concurrent updating processes to access a database file or a replication instance file.

This permission is effected by the QDBRUNDOWN flags in database file headers and in replication instance files. When an open database file or replication instance file with QDBRUNDOWN set is first concurrently accessed by more than 32,767 processes, GT.M:

Except in application configurations that require it, FIS recommends not setting QDBRUNDOWN. Not setting QDBRUNDOWN allows GT.M to clean up resources, instead of putting the burden on the operational procedures. Where GT.M cannot perform an orderly shutdown, an explicit, clean shutdown must be performed as follows:

Example:

$ export gtm_repl_instance=mutisite.repl
$ export gtm_repl_instname=America
$ mupip replicate -instance_create

This example creates a replication instance file called multisite.repl specified by gtm_repl_instance with an instance name America specified by environment variable gtm_repl_instname.

Command Syntax:

mupip replicate
 -edit[instance] {<instance-file>|-source -jnlpool} 
  {-show [-detail]|-change [-offset=] [-size=] [-value=]|-cleanslots} 
 [-name=<new-name>]
 [-[no]qdbrundown]

-editinstance

Displays or changes the attributes of the specified instance-file. Use -editinstance in combination with the SHOW, CHANGE, or CLEANSLOTS qualifiers.

-cleanslots

Goes through all 16 slots in the replication instance file, identifies the slots that are inactive, and clears them to make them available for reuse.

Note

Initially, all the slots are unused. A Source Server replicating to a secondary instance for the first time utilizes an unused slot to store the information related to that secondary. Any Source Server process replicating to the same secondary instance updates information using the same slot until -CLEANSLOT clears the slot to make it reusable. Use -CLEANSLOT to clear inactive slots when the originating instance connects to more than 16 different secondary instances throughout its lifetime.

-jnlpool

Displays or changes the attributes of Journal Pool. Always specify -source with -jnlpool. Use -jnlpool in combination with SHOW or CHANGE qualifiers.

-change

The CHANGE qualifier is intended only for use under the guidance of FIS and serves two purposes. When used with -editinstance -offset -size, it changes the contents of the replication instance file. When used with -jnlpool, it changes the contents of journal pool header. Although MUPIP does not enforce standalone access when using this feature on the instance file or the journal pool, doing so when replication is actively occurring can lead to catastrophic failures.

-name=<new-name>

Changes the instance name in the replication instance file header to the new-name. Note that changing an instance name preserves the instance history.

-show

Displays File Header, Source Server slots, and History Records from the Replication Instance file.

-detail

When specified, all fields within each section are displayed along with their offset from the beginning of the file and the size of each field. Use this qualifier to find the -offset and -size of the displayed field. To edit any displayed field, use the -change qualifier.

-size

Indicates the new size of the new value in bytes. The value of size can be either 1, 2, 4, or 8.

-offset

Takes a hexadecimal value that is a multiple of -size. With no -offset specified, GT.M produces an error. GT.M also produces an error if the offset is greater than the size of the instance file or the journal pool header.

-value

Specifies the new hexadecimal value of the field having the specified -offset and -size. With no value specified, GT.M displays the current value at the specified offset and does not perform any change. Specifying -value=<new_value> makes the change and displays both the old and new values.

	Caution
	Change the instance file or the journal pool only on explicit instructions from FIS.

-show

The SHOW qualifier serves two purposes. When used with -editinstance, it displays the content of the replication instance file. When used with -jnlpool, it displays the content of the journal pool.

-[no]qdbrundown

Controls the setting of the "HDR Quick database rundown is active" field in a replication instance file. For more information about this setting, refer to “Creating the Replication Instance File”.

Example:

$ mupip replicate -editinstance -show -detail multisite.repl

This example displays the content of the replication instance file multisite.repl. The optional detail qualifier displays each section along with its offset from the beginning of the file and the size of each field. Use this information when there is a need to edit the instance file.

Example:

$ mupip replicate -editinstance -change -offset=0x00000410 -size=0x0008 -value=0x010 multisite.repl

This command sets the value of the field having the specified offset and size to 16. Note that mupip replicate -editinstance -show -detail command displays the offset and size of all fields in an instance file.

The MUPIP REPLICATE -SOURCE -START command starts a Source Server process. The general syntax for starting a Source Server in active mode is:

mupip replicate -source -start 
[connection_qualifiers] 
[instance_freeze_qualifiers]
[jnlpool_setup_qualifiers]
log_file_management_qualifiers
[primary_role_qualifiers]
secondary_identification_qualifiers
[tls_replication_qualifiers]
[replication_filter_qualifier]

The square brackets [] denote an optional qualifier group. The optional and mandatory qualifiers in each qualifier group are as follows:

You can start the Source Server in passive mode with mupip replicate -source -start -passive. The general syntax for starting a Source Server in passive mode is the same as that of starting a Source Server in active mode except that -passive is not compatible with -secondary=<hostname:port>.

Connection Qualifiers:

-cmplvl=n

Specifies the desired compression level for the replication stream. n is a positive integer value indicating the level of compression desired. Level 0 offers no compression. Level 1 offers the least compression while Level 9 (as of version 1.2.3.3 of the zlib library) offers the most compression (at the cost of the most CPU usage). Specifying -cmplvl without an accompanying -start produces an error. In the case of the source server, if N specifies any value outside of the range accepted by the compression library or if -cmplvl is not specified, the compression level defaults to zero (0). In the case of the receiver server, as long as N is non-zero the decompression feature is enabled; since the source server setting determines the actual level, any legal non-zero value enables compressed operation at the receiver.

Alternatively, the environment variable gtm_zlib_cmp_level can specify the desired compression level (in the same value range as N above) and the source server can then be started without -cmplvl. This has the same effect as starting it with -cmplvl specified. An explicitly specified value on the command line overrides any value specified by the environment variable.

Whenever the source and receiver server connect with each other, if the source server was started with a valid non-zero compression level, they first determine whether the receiver server is running a version of GT.M which handles compressed records and has been started with a non-zero compression level. Only if this is true, do they agree to use compressed journal records. They also verify with a test message that compression/decompression works correctly before sending any compressed journal data across. They automatically fall back to uncompressed mode of transmission if this test fails or if, at any point, either side detects that compression or decompression has failed. That is, any runtime error in the compression/decompression logic results in uncompressed replication (thereby reducing replication throughput) but never jeopardizes the functional health of replication.

The Source and Receiver Servers log all compression related events and/or messages in their respective logs. The source server also logs the length of the compressed data (in addition to the uncompressed data length) in its logfile.

Note

If you plan to use the optional compression facility for replication, you must provide the compression library. The GT.M interface for compression libraries accepts the zlib compression libraries without any need for adaptation. These libraries are included in many distributions and are downloadable from the zlib home page. If you prefer to use other compression libraries, you need to configure or adapt them to provide the same API provided by zlib.

By default, GT.M searches for the libz.so shared library in the standard system library directories (for example, /usr/lib, /usr/local/lib, /usr/local/lib64). If the shared library is installed in a non-standard location, before starting replication, you must ensure that the environment variable $LIBPATH (AIX and z/OS) or $LD_LIBRARY_PATH (other UNIX platforms) includes the directory containung the library. The Source and Receiver Server link the shared library at runtime. If this fails for any reason (such as file not found, or insufficient authorization), the replication logic logs a DLLNOOPEN error and continues with no compression.

-connectparams=<hard tries>,<hard tries period>,<soft tries period>,<REPLALERT time>,<heartbeat period>,<max heartbeat wait>

Specifies the connection parameters as a comma delimited series of integer values. If the connection between the Source and Receiver Servers breaks or the Source Server fails to connect to the Receiver Server at startup, the Source uses the first four parameters for reconnection attempts as follows:

The Source Server uses the fifth and sixth parameters when the connection is established with the Receiver Server. It send a heartbeat message to the Receiver Server every <heartbeat period> seconds and expects a response back from the Receiver Server within <max heartbeat wait> seconds. If the response does not arrive within <max heartbeat wait>, the Source Server closes the connection and starts to establish a new conection using the first four parameters. The Source Server temporarily stalls the heartbeat message interchange mechanism during events such as secured renegotiation or online rollback. The stalling of heartbeat connection attempts may also occur when the Receiver Server is not started or is not accessible on the network.

GT.M automatically adjusts the values for <soft tries period> and <hard tries period> to about half of the GT.M determined shutdown wait time. GT.M logs these adjustments in the Source Server log file. This helps prevent inadvertent timeouts of a Source Server shutdown due to high <soft tries period> and/or <hard tries period> and prevents out-of-design conditions.

The default -CONNECTPARAMS values are 5,500,5,0,15,60. With this setting, the Source Server makes 5 hard connection attempts in 500 milliseconds intervals, and then makes soft connection attempts every 5 seconds without logging the REPLALERT message. Once the connection is established, the Source Server sends a heartbeat messages every 15 seconds and closes the connection if a response does not arrive in 60 seconds. Then, the Source Server starts establishings a new connection with hard connection attempts.

You can specify up to six parameters with -CONNECTPARAMS. MUPIP uses the defaults for the parameters not specified.

-[NO]{SEND|RECV}BUFFSIZE[=n]

Specifies the desired minimum TCP send and/or receive buffer sizes. This affects the SO_SNDBUF and SO_RCVBUF socket options of the socket GT.M uses for replication, not the journalpool or any other application-level buffer. n is a positive integer value indicating the desired minimum buffer size. If GT.M finds that the specified buffer already has a sufficient size when it is created, GT.M will avoid setting the buffer explicitly. The -NO{SEND|RECV}BUFFSIZE version of this qualifier instructs GT.M to avoid setting the buffer sizes under any circumstance. In some environments, when the size of these buffers are dynamically adjusted except in cases where an application sets their size explicitly, -NO{SEND|RECV}BUFFSIZE can lead to good performance in a wide variety of network conditions. By default and without passing this qualifier, GT.M enforces a minimum size of approximately 1MiB for each buffer. This qualifier may only be passed to a -START command.

Note

The actual size of a tcp buffer depends on a variety of environmental conditions, including system configuration, operating system, and available memory. Users of GT.M on Linux may observe that GT.M will report in the source and/or receiver logs buffers that are approximately twice what is requested, if the request has been honored by the OS. This is due to a quirk in the way that the Linux kernel reports TCP buffer sizes: the user-available size is approximately equal to what is requested, and the additional space is used internally by the kernel.

Journal Pool Setup Qualifiers:

-buffsize=<Journal Pool size in bytes>

On the Source Server, -BUFFSIZE specifies the size of the Journal Pool. The server rounds the size up or down to align with other specified or implicit requirements. Any size less than 1 MiB is rounded up to 1 MiB. If -BUFFSIZE is not specified, MUPIP defaults the Journal Pool size to 64 MiB. Remember that you cannot exceed the system-provided maximum shared memory. For systems with high update rates, specify a larger buffer size to avoid the overflows and file I/O that occur when the Source Server reads journal records from journal files. The maximum value is 68719476736 (64GiB). The first Source Server process started on an instance sets up the Journal Pool. MUPIP REPLICATE -SOURCE ignores -BUFFSIZE if the Journal Pool is already set up.

On the Receiver Server, -BUFFSIZE specifies the size of the Receiver Pool. For applications having periodic spikes in the replication volume, FIS recommends having a larger Receiver Pool. The Receiver Pool is a memory structure that temporarily holds updates coming from the Source Server. The Update Process transfers these updates to permanent storage so that they can become accessible by mumps processes. As long as the Update Process is alive and running, it is safe to assume that updates in the Receiver Pool will eventually get transferred to permanent storage even if a network failure happens between the Source and Receiver Servers. The Receiver Pool becomes full when the speed of applying updates by the Update Process is slower than the speed of receiving updates from the Source Server. When the Receiver Pool becomes full, the network refuses to accept more updates from the Source Server which increases the backlog on the Source Server. Therefore, a larger size Receiver Pool delays this condition and helps cushion the impact of periodic spike in replication volumes.

Note

On the Originating Instance, GT.M processes can access updates as soon as any other GT.M process commits them. However, mumps processes on a Replicating Instance cannot access updates from the Originating Instance until the Source Server sends them, the Receiver Process moves them to the Receive Pool and the Update Process picks and commits them. Please bear this distinction in mind while configuring replicating/reporting instances for your application.

-[no]jnlfileonly

Forces the Source Server to read transactions from journal files instead of journal pool shared memory. When combined with the SYNC_IO journal option, this feature delays replication of transactions until their journal records are hardened to disk. This may be useful when replicating to a supplementary instance, as a crash and rollback on the primary could otherwise necessitate a rollback of local updates on the receiving instance. The default is -NOJNLFILEONLY.

Log File Management Qualifiers:

-log=<log file name>

Specifies the location of the log file. The Source Server logs its unsuccessful connection attempts starting frequently and slowing to approximately once every five minutes. This interval does not affect the rate of connection attempts. The Source Server also directs errors to the log file. Operators should check the Source Server log file for errors.

-log_interval=<integer>

Specifies the number of transactions for which the Source Server should leave between writing progress to the log file. The default logging interval is 1000 transactions.

-log_interval=0 sets the logging interval to the default value.

Replication Filter Qualifiers:

-filter=<filter command>

Specifies the complete path of the filter program and any associated arguments. If you specify arguments, then enclose the command string in quotation marks. If a filter is active, the Source Server passes the entire output stream to the filter as input. Then, the output from the filter stream passes to the replicating instance. If the filter program is an M program with entry-ref OLD2NEW^FILTER, specify the following path:

filter='"$gtm_dist/mumps -run OLD2NEW^FILTER"'

Write the filter as a UNIX process that takes its input from STDIN and writes its output to STDOUT.

You can also define an environment variable like export gtmfilter=""$gtm_dist/mumps -run ^OLD2NEW^FILTER"" to bypass shell escaping and use it in the MUPIP command as follows:

$gtm_dist/mupip replic -receiver -start -listenport=$portno -filter=$gtmfilter -log=$REC_LOG_FILE 

The format of the input and output data is the MUPIP journal file extract format. The filter must maintain a strict 1:1 relationship between transactions on the input stream and transactions on the output stream. If a transaction on the input results in no sets and kills in the output, the filter must still write an empty transaction to the output stream.

Example:

extfilter
  ; A command like the following deploys this filter on the Receiver Server:
  ; export gtmfilter=""$gtm_dist/mumps -run ^extfilter""
  ; $gtm_dist/mupip replic -receiver -start -buffsize=$gtm_buffsize 
  ;-listenport=$portno  
  ;-filter=$gtmfilter -log=$REC_LOG_FILE 
  ; deploys this demo filter on the Receiver Server. 
  ; 
  ; This program is a simple filter program that receives journal records 
  ; from standard input and write them back to standard output. 
  ; Journal records between TSTART 
  ; and TCOMMIT are written with single write command. 
  ; 
  ; Do not use this filter program as-is in a production environment.  
  ; While writing filter programs ensure that your programming logic never 
  ; exposes non-public information (NPI) stored in GT.M local variables 
  ; and global variables. You should take additional care about 
  ; managing and sharing GTM_FATAL_ERROR.ZSHOW_DMP_*.txt 
  ; and core dump files that may contain NPI. 
  new TSTART,TCOMMIT,EOT,EOL,log,extrRec,filtrOut,cntr,tmp,rectype,max
  set $ztrap="goto err"
  set TSTART="08"
  set TCOMMIT="09"
  set EOT="99"
  set max=1024*1024               ; maximum size of a local variable;  
  set log=$ztrnlnm("filterlog")   ; use environment variable "filterlog" (if defined) to indicate which logfile to use
  set:log="" log="/dev/null"      ; if filterlog is not defined, write log file output to /dev/null 
  set EOL=$char(10)
  open log:newversion
  use $principal:(nowrap:width=max)
  for  do
  . use $principal
  . read extrRec
  . if $zeof halt
  . set rectype=$piece(extrRec,"\",1)
  . if rectype'=EOT do
  .. if rectype'=TSTART set filtrOut=extrRec_EOL  
  .. else  do  ; Write Journal Records within TSTART and TCOMMIT boundary in one go (1MiB limit). 
  ... set filtrOut=extrRec_EOL
  ... for  read extrRec set filtrOut=filtrOut_extrRec_EOL quit:$zextract(extrRec,1,2)=TCOMMIT
  ... if $zeof halt
  .. ; set $x=0 is needed so every write starts at beginning of record position
  .. ; don't write more than "width" characters in one output operation to avoid "chopping" of output
  .. ; and/or eol in the middle of output stream
  .. ; default width=1024*1024
  .. ; use $zsubstr to chop at valid character boundary (single or multi byte character)
  .. set tmp=filtrOut
  .. for  quit:tmp=""  do
  ... set $x=0,record($increment(cntr))=$zsubstr(tmp,1,max-1),tmp=$zextract(tmp,$zlength(record(cntr))+1,$zlength(tmp))
  ... write record(cntr)
  ... kill record(cntr)
  . use log
  . write "Received: ",EOL,$select(rectype'=TSTART:extrRec_EOL,1:filtrOut)  
  . if rectype'=EOT write "Sent: ",EOL,filtrOut
  . else  write "EOT received, halting..." halt
  quit
err
  set $ztrap=""
  use log
  write !!!,"**** ERROR ENCOUNTERED ****",!!!
  zshow "*" 
  halt

This example reads logical database updates associated with a transaction from STDIN and writes them to a filter log (if filterlog environment variable is defined) and STDOUT just like the UNIX tee command. It runs on GT.M V5.5-000 where it is no longer required to treat filter output as a transaction. To run this example on a pre-GT.M V5.5-000 version, replace the line:

.. if rectype'=TSTART set filtrOut=extrRec_EOL

with

.. if rectype'=TSTART set filtrOut=TSTART_EOL_extrRec_EOL_TCOMMIT_EOL

to wrap mini-transactions in 08 09.

Primary Role Qualifiers:

-propagate[primary]

Use this optional qualifier to assign the current instance as a propagating instance. Specifying -propagateprimary disables updates on the current instance.

Note that it is not possible to transition an originating instance to a propagating instance without bringing down the Journal Pool. However, it is possible to transition a propagating instance to an originating instance without bringing down the Journal Pool for an already running passive Source Server (start one with -propagateprimary if none is running).

Both -rootprimary and -propagateprimary are optional and mutually exclusive. However, FIS recommends you to specify both -rootprimary and -propagateprimary explicitly in the script for clarity.

Example:

$ mupip replicate -source -activate -rootprimary

This command transitions a propagating originating instance to an originating instance without bringing down the Journal Pool.

With neither -rootprimary nor -propagateprimary specified, GT.M uses a default value of -propagateprimary for the passive Source Server startup command (mupip replic -source -start -passive) and the deactivate qualifier (mupip replicate -source -deactivate). GT.M uses a default value of -rootprimary for the mupip replicate -source -start -secondary=... and the mupip replic -source -activate commands. These default values make the replication script simpler for users who are planning to limit themselves to one originating instance and multiple replicating instance (without any further replicating instances downstream).

$ export gtm_repl_instance=multisite.repl
$ mupip set -journal="enable,before,on" -replication=on -region "*"
$ mupip replicate -instance_create -name=America
$ mupip replicate -source -start -buffsize=$jnlpool_size -secondary=localhost:1234 -log=A2B.log -instsecondary=Brazil

This example starts the Source Server at port 1234 for the replicating instance Brazil. The Source Server creates a Journal Pool. A GT.M Process writes the updated journal records to the Journal Pool. Then, the Source Server process transports each record from the Journal Pool to Brazil via a TCP/IP connection.

	Note
	Before starting replication, always remember to rundown every replicated database region then start the Source Server. GT.M updates to replicated regions are permitted only on the originating instance and disabled on ALL other replicating instances.

The Source Server records actions and errors in A2B.log. It also periodically record statistics such as the current backlog, the number of journal records sent since the last log, the rate of transmission, the starting and current JNL_SEQNO, and the path of the filter program, if any.

-rootprimary

Assign the current instance as the originating instance. You can specify -rootprimary either explicitly or implicitly to start an instance as an originating instance.

-updnotok

Instructs the Source Server to not allow local updates on this instance. This is a synonym for -propagateprimary but is named so it better conveys its purpose.

-updok

Instructs the Source Server to allow local updates on this instance. This is a synonym for -rootprimary but is named so it better conveys its purpose.

Secondary Identification Qualifiers:

-instsecondary

Specifies the replicating instance to which the Source Server replicates data. -instsecondary also identifies a Source Server process target for actions like changing to active mode or passive mode, checking Source Server health, or shutting down a Source Server.

With no -instsecondary specified, the Source Server uses the environment variable gtm_repl_instsecondary for the name of the replicating instance.

With no -instsecondary specified and environment variable gtm_repl_instsecondary not set, mupip replicate -source -checkhealth looks at all the Source Servers (Active or Passive) that are alive and running and those that were abnormally shutdown (say by a kill -9). Any Source Server that was kill -15ed or MUPIP STOPped is ignored because GT.M considers those Source Server shut down in the normal way. This command reports something only if it finds at least one Source Server that is alive and running or was abnormally shutdown. Otherwise it returns a zero (0) status without anything to report even when the Journal Pool exists and GT.M processes (Update Process or Receiver Server on the replicating instance) are up and running.

You can start multiple Source Servers from the same originating instance as long as each of them specifies a different name for -instsecondary.

Specify -instsecondary explicitly (by providing a value) or implicitly (through the environment variable gtm_repl_instsecondary) even for starting a Passive Source Server. Whenever it activates, a Passive Source Server connects to this replicating instance.

Example:

$ mupip replicate -source -start -buffsize=$gtm_buffsize -secondary=localhost:1234 -log=A2B.log -instsecondary=B

This command starts the Source Server for the originating instance with instance B as its replicating instance.

-secondary=<hostname:port>

Identifies the replicating instance. <hostname:port> specifies an IPv4 or IPv6 address optionally encapsulated by square-brackets ([]) like "127.0.0.1", "::1", "[127.0.0.1]", or "[::1]" or a hostname that resolves to an IPv4 or IPv6 address and the port at which the Receiver Server is waiting for a connection.

If, in your environment, the same hostname is used for both IPv4 and IPv6, GT.M defaults to IPv6. If you wish to use IPv4, perhaps because you have a Receiver Server running a pre-V6.0-003 version of GT.M that does not support IPv6, set the environment variable gtm_ipv4_only to "TRUE", "YES", or a non-zero integer in order to force GT.M to use IPv4.

TLS Replication Qualifiers:

-tlsid=<label>

Instructs the Source or Receiver Server to use the TLS certificate and private key pairs having <label> as the TLSID in the configuration file pointed to by the gtmcrypt_config environment variable. TLSID is a required parameter if TLS/SSL is to be used to secure replication connection between instances. If private keys are encrypted, an environment variable of the form gtmtls_passwd_<label> specifies their obfuscated password. You can obfuscate passwords using the 'maskpass' utility provided along with the encryption plugin. If you use unencrypted private keys, set the gtmtls_passwd_<label> environment variable to a non-null dummy value; this prevents inappropriate prompting for a password.

-[NO]PLAINtextfallback

Specifies whether the replication server is permitted to fallback to plaintext communication. The default is -NOPLAINtextfallback. If NOPLAINTEXTFALLBACK is in effect, GT.M issues a REPLNOTLS error in the event it is unable to establish a TLS connection. [Note: GT.M versions prior to V6.1-000 did not support TLS for replication - if needed it could be implemented with an external application such as stunnel (http://stunnel.org).] If PLAINTEXTFALLBACK is in effect, in the event of a failure to establish a TLS connection, GT.M issues REPLNOTLS as a warning. Once a permitted plaintext replication connection is established for a connection session, GT.M never attempts to switch that connection session to TLS connection.

-RENEGotiate_interval=<minutes>

Specifies the approximate time in minutes to wait before attempting to perform a TLS renegotiation. The default -RENEGOTIATE_INTERVAL is a little over 120 minutes. The minimum -RENEGOTIATE_INTERVAL is 1 minute. A value of zero causes GT.M never to attempt a renegotiation. The MUPIP REPLIC -SOURCE -JNLPOOL -SHOW [-DETAIL] command shows the time at which the next TLS renegotiation is scheduled, and how many such renegotiations have occurred thus far for a given secondary instance connection. As renegotiation requires the replication pipeline to be temporarily flushed, followed by the actual renegotiation, TLS renegotiation can cause momentary spikes in replication backlog.

TLSv1.3 introduces a number of protocol changes. The concept of renegotiation was removed. As a result, when using TLSv1.3, this qualifier takes on a different meaning. GT.M used TLSv1.2 renegotiation to ensure appropriate refresh of session keys (for rationale, see Luykx, A. and K. Paterson, "Limits on Authenticated Encryption Use in TLS", 2016; http://www.isg.rhul.ac.uk/~kp/TLS-AEbounds.pdf). As a result, GT.M uses the term "renegotiation" for SOCKET devices where the mode is "server" and "renegotiation_interval" for the frequency of renegotiation during database replication. For TLSv1.3 sessions, the GT.M Reference TLS plugin treats the "renegotiation" as a request to update the session keys.

OpenSSL 3.0 by default does not allow client-side initiated TLSv1.2 renegotiation requests due to potential DoS attacks. Due to security enhancements in OpenSSL 3.0, the reference TLS implementation in GT.M versions before V7.0-004 do not use the appropriate OpenSSL 3.0 API to enable support for renegotiation. Due to these OpenSSL changes, customers needing to replicate to/from GT.M versions before V7.0-004 with OpenSSL 3.0 must use-RENEGOTIATE_INTERVAL=0 in the Source Server startup. Because of this, the GT.M Reference TLS plugin built with a pre-OpenSSL 3.0 version does not support client initiated renegotiation when communicating with a plugin build with OpenSSL 3.0. This limitation only affects database replication and not SOCKET devices.

Command syntax:

mupip replicate -source -shutdown 
 [-timeout=<timeout in seconds>]
 [-zerobacklog]

Qualifiers:

-shutdown

Shuts down the Source Server.

-timeout=<timeout in seconds>

Specifies the time (in seconds) the shutdown command should wait before signaling the Source Server to shut down. If you specify -timeout=0, MUPIP initiates the shutdown immediately. The default is 120 seconds and the maximum timeout is 3600 seconds. Any value higher than 3600 produces the INVSHUTDOWN error.

After initiating shutdown of the Source Server, GT.M waits up to 90 * number_of_regions seconds (with a minimum of 120 seconds) for the Source Server process to exit normally.

-zerobacklog

Restricts Journal Pool in a way that only existing processes can complete their updates and shuts down the Source Server:

The REPL0BACKLOG message helps confirm that two instances are in sync (seqno-wise) because all Source Server updates have reached the Receive Pool at the time of shutdown and there are no-inflight updates. The REPL0BACKLOG message also causes the timeout to expire prematurely. In planned switchover scenarios, the REPL0BACKLOG message assists in operationally preventing lost transaction file generation.

Command syntax:

mupip replicate -source -activate 
 -secondary=<hostname:port> 
 -log=<log file name> 
 [-log_interval=<integer>]
 -connectparams=<hard tries>,<hard tries period>,
 <soft tries period>,<alert time>,<heartbeat period>,
 <max heartbeat wait>] 
 -instsecondary=<instance_name>
 {-rootprimary|-propagateprimary}

Qualifiers:

-activate

Activates a passive Source Server. Once activated, the Source Server reads journal records from the Journal Pool and transports them to the system specified by -secondary.

Before activation, -activate sets the Source Server to ACTIVE_REQUESTED mode. On successful activation, GT.M sets the Source Server mode to ACTIVE. GT.M produces an error when there is an attempt to activate a Source Server in ACTIVE_REQUESTED mode.

-instsecondary=<instance_name>

Identifies the replicating instance to which the passive Source Server connects after activation.

With no -instsecondary specified, the passive Source Server uses the environment variable gtm_repl_instsecondary as the value of -instsecondary.

-rootprimary

Specifies that the passive Source Server activation occurs on an originating instance.

-propagateprimary

Specifies that the passive Source Server activation occurs on a propagating instance.

If neither -rootprimary nor -propagateprimary are specified, this command assumes -propagateprimary.

-log_interval

Specifies the number of transactions for which the Source Server should wait before writing to the log file. The default logging interval is 1000 transactions.

-log_interval=0 reverts the logging interval to the default value.

Example:

$ mupip replicate -source -activate -secondary=localhost:8998 -log=A2B.log -instsecondary=America

This example activates a Source Server from passive mode.

Command syntax:

mupip replicate -source -deactivate -instsecondary=<instance_name>

Qualifiers:

-deactivate

Makes an active Source Server passive. To change the replicating instance with which the Source Server is communicating, deactivate the Source Server and then activate it with a different replicating instance.

Before deactivation, -deactivate sets the Source Server to PASSIVE_REQUESTED mode. On successful deactivation, GT.M sets the Source Server mode to PASSIVE. GT.M produces an error when there is an attempt to deactivate a Source Server in PASSIVE_REQUESTED mode.

-instsecondary=<instance_name>

Identifies the active Source Server to transition to the passive (standby) state.

With no -instsecondary specified, $gtm_repl_instsecondary determines the active Source Server.

-rootprimary

Specifies that the active Source Server is on originating instance.

-propagateprimary

Specifies that the active Source Server is on a propagating instance.

If neither -rootprimary nor -propagateprimary are specified, this command assumes -propagateprimary.

There are two ways to stop an active filter on the Source Server.

	If a filter fails to respond within just over a minute to delivery of a mini-transaction or TP transaction, a Source or Receiver Server issues a FILTERTIMEDOUT error, stops the filter, and exits.

Command Syntax:

mupip replicate -receiver -stopreceiverfilter

Qualifiers:

-stopreceiverfilter

Turns off any active filter on the Receiver Server without turning off the Receiver Server. Using -stopreceiverfilter when no filter is active returns a non-success return code. -stopreceiverfilter is not compatible with any other -receiver qualifier.

The MUPIP REPLICATE -SOURCE command with instance freeze qualifiers manage the Instance Freeze facility of an instance. The syntax is:

mupip replicate -source 
  [-[no]comment[='"<string>"']]
  -freeze[=on|off]

Qualifiers:

-[no]comment[='"<string>"']

Allows specifying a comment/reason associated with an Instance Freeze. Specify -nocomment if you do not wish to specify a comment/reason.

-freeze[=on|off]

Sets or clears an Instance Freeze on an instance irrespective of whether a region is enabled for an Instance Freeze. -freeze with no arguments displays the current state of the Instance Freeze on the instance.

For more information on enabling a region to invoke an Instance Freeze on custom errors, refer to the -INST_FREEZE_ON_ERROR section of “SET”.

For more information on Instance Freeze, refer to “Instance Freeze”.

Use the following command and qualifier to determine whether the Source Server is running.

Command syntax:

mupip replicate -source -checkhealth [-instsecondary=<instance_instance>]

Qualifiers:

-checkhealth

Determine whether the Source Server is running. If the Source Server is running, the exit code is 0 (zero). If the Source Server is not running or an error exists, the exit code is not 0.

-instsecondary=<instance_name>

Identifies a Source Server process.

If -instsecondary is not specified, -checkhealth checks all Source Server processes.

Example:

$ mupip replic -source -checkhealth -inst=INSTB
Fri May 21 15:26:18 2010 : Initiating CHECKHEALTH operation on source server pid [15511] for secondary 
instance name [INSTB]
PID 15511 Source server is alive in ACTIVE mode
$ mupip replic -source -checkhealth -inst=INSTB
Fri May 21 15:29:52 2010 : Initiating CHECKHEALTH operation on source server pid [0] for secondary 
instance name [INSTB]
PID 0 Source server is NOT alive
%GTM-E-SRCSRVNOTEXIST, Source server for secondary instance INSTB is not alive

Command syntax:

mupip replicate -source -changelog -log=<log file name> [-log_interval=<integer>] -instsecondary=<instance_name>

Qualfiers:

-changelog

Instructs the Source Server to change its log file.

-instsecondary=<instance_name>

Identifies a Source Server process.

-log=<log file name>

Use this mandatory qualifier to specify the name of the new log file. If you specify the name of the current log file, no change occurs.

Example:

$ mupip replicate -source -changelog -log=/more_disk_space/newA2B.log -instsecondary=Brazil

-log_interval=<integer>

Specifies the number of transactions for which the Source Server should wait before writing to the log file. The default logging interval is 1000 transactions.

-log_interval=0 reverts the logging interval to the default value.

Command syntax:

mupip replicate -source -statslog={ON|OFF} 
 [-log_interval=<integer>

Qualifiers:

-statslog={ON | OFF}

Enables or disables detailed logging. When ON, the system logs current-state information of the Source Server and messages exchanged between the Source and Receiver Servers. By default, detailed logging is OFF. Once you enable it (ON), changing -statslog to OFF can stop detailed logging.

-log_interval=<integer>

Specifies the number of transactions for which the Source Server should wait before writing to the log file. The default logging interval is 1000 transactions.

-log_interval=0 reverts the logging interval to the default value.

Command syntax:

mupip replicate -source -showbacklog

Qualifiers:

-showbacklog

Reports four fields that help determine the backlog of updates on the Source Server. These fields are:

The backlog is the difference between the second and third fields. When backlog is 0 and the remaining three fields have the same value, it means that all Source Server updates have reached the Receiver Pool and there are no in-flight updates.

	Important
	A -SHOWBACKLOG operation momentarily restricts access to the Journal Pool to determine the backlog. If your operations demand frequent checking for replication backlogs, FIS recommends using the ^%PEEKBYNAME function instead of performing a -SHOWBACKLOG in a continuous loop. Please refer to the examples for more information on using ^%PEEKBYNAME for monitoring replication speed and backlog.

Example:

$ mupip replic -source -showbacklog -inst=INSTB
Tue Jan  5 10:36:46 2021 : Initiating SHOWBACKLOG operation on source server pid [0] for secondary instance [INSTB]
52 : backlog number of transactions written to journal pool and yet to be sent by the source server
102 : sequence number of last transaction written to journal pool
50 : sequence number of last transaction sent by source server
25 : sequence number acknowledged by the secondary instance [INSTB]

Example:

replspeed
  ; This routine returns the replication speed, that is the number of seqno updates per second acknowledged by the replicating instance during heartbeat intervals
  ; Usage: $gtm_exe/mumps -r ^replspeed INSTANCE3 20
  ; The second parameter is the sampling size
  set $etrap="write ""REPLSPEED-E-ACKSMPL : unable to fetch sampling data due to "",$zstatus  halt  "
  set $ztimeout="300:write ""Timeout occurred out after 5 minutes"",! zwrite  halt"
  new hrtbtperiod,instance,samplingsize,hrtbts,slot,i,hrtbtdiffs,diff,dump
  set instance=$piece($zcmdline," ",1),slot=0
  set samplingsize=$piece($zcmdline," ",2),hrtbtdiffs=0
  set:$length(samplingsize)=0 samplingsize=10
  if '($length(instance)) write "REPLSPEED-E-ARGS : ",$zcmdline," was specified. This routine requires specifying an instance name.",! halt
  for i=0:1:15 set instname=$$^%PEEKBYNAME("gtmsource_local_struct.secondary_instname",i),instname=$piece(instname,$char(0),1) set:(instname=instance) slot=i
  ; capture heartbeat_jnl_seqno samplingsize times. Wait for hrtbtperiod after every capture of heartbeat_jnl_seqno
  set hrtbtperiod=$piece($$^%PEEKBYNAME("gtmsource_local_struct.connect_parms",slot),",",5)
  for j=1:1:samplingsize do
  . set hrtbts(j)=$$^%PEEKBYNAME("gtmsource_local_struct.heartbeat_jnl_seqno",slot,"I")
  . do:(j>1)
  . . set diff=hrtbts(j)-hrtbts(j-1)
  . . do:(diff<0)
  . . . write "REPLSPEED-E-ACKSEQNO : acknowledgement sequence number received is lower than previous acknowledgement seqno."
  . . . set dump="replspeed.dump" open dump use dump zwrite hrtbts  close dump
  . . . halt
  . . set hrtbtdiffs=hrtbtdiffs+diff
  . hang hrtbtperiod
  set hrtbtdiffs=hrtbtdiffs/samplingsize
  write $justify(hrtbtdiffs/hrtbtperiod,0,0)
  quit

Example:

waitforhrtbt
  ; This routine returns 0 when the acknowledged seqno from the specified instance matches or exceeds the specified seqno
  ; If there is no confirmation (network issues etc) from the Receiver Server for 300 seconds, this routines returns 1.
  ; Usage: $gtm_exe/mumps -r ^waitforhrtbt <instname> <seqnocheckpoint>
  set $etrap="write ""WAITFORHRTBT-E-ERROR, Error occurred while waiting for ackseqno confirmation due to "",$zstatus  halt  "
  new heartbeatseqno,hangduration,instance,checkseqno,i,instname,slot
  ; set $ztimeout to align with the REPLALERT threshold for the test system
  set $ztimeout="900:write 1 halt"
  set hangduration=1,slot=""
  set instance=$piece($zcmdline," ",1)
  set checkseqno=$piece($zcmdline," ",2)
  if '($length(instance)&$length(checkseqno)) write "WAITFORHRTBT-E-ARGS : ",$zcmdline," was specified. This routine requires specifying instance name and seqno.",! halt
  for i=0:1:15 set instname=$$^%PEEKBYNAME("gtmsource_local_struct.secondary_instname",i),instname=$piece(instname,$char(0),1) set:(instname=instance) slot=i
  if '($length(slot)) write "WAITFORHRTBT-E-INSTNOMATCH : No matching instance name for ",instance,! halt
  for  do
  . set heartbeatseqno=$$^%PEEKBYNAME("gtmsource_local_struct.heartbeat_jnl_seqno",slot,"I")-1
  . if (heartbeatseqno>=checkseqno) write 0 halt
  . hang hangduration
  quit

Example:

waitforseqnosync
  ; This routine returns 0 when there the sequence numbers of the Source Server and the acknowledged sequence number from the Receiver Server is the same.
  ; It returns a non-zero value when there is no confirmation of the receipt of the latest seqno from the secondary even when there is no backlog.
  ; If there is no confirmation (network issues etc) from the Receiver Server for 150 seconds, this routines returns 1.
  ; Usage: $gtm_exe/mumps -r ^waitforseqnosync <instname>
  set $etrap="write ""WAITFORSEQNOSYNC-E-SRCBACKLOG : unable to get current Source Server backlog and seqno updates status due to "",$zstatus  halt  "
  new readseqno,heartbeatseqno,instance,i,instname,slot,hrtbtperiod
  set $ztimeout="150:write 1 halt"
  set slot=""
  ; hrtbtperiod: the heartbeat period (the fifth parameter of -CONNECTPARAMS)
  set instance=$zcmdline
  if '$length(instance) write "WAITFORSEQNOSYNC-E-ARGS : This routine requires specifying an instance name.",! halt
  for i=0:1:15 set instname=$$^%PEEKBYNAME("gtmsource_local_struct.secondary_instname",i),instname=$piece(instname,$char(0),1) set:(instname=instance) slot=i
  if '($length(slot)) write "WAITFORSEQNOSYNC-E-INSTNOMATCH : No matching instance name for ",instance halt
  set hrtbtperiod=$piece($$^%PEEKBYNAME("gtmsource_local_struct.connect_parms",slot),",",5)
  for  do
  . set seqno=$$^%PEEKBYNAME("jnlpool_ctl_struct.jnl_seqno","","I")
  . set readseqno=$$^%PEEKBYNAME("gtmsource_local_struct.read_jnl_seqno",i,"I")
  . set heartbeatseqno=$$^%PEEKBYNAME("gtmsource_local_struct.heartbeat_jnl_seqno",i,"I")
  . if (seqno=readseqno=heartbeatseqno) write 0 halt
  . hang hrtbtperiod
  quit

Except following a failover when the backlog is zero, whenever a former originating instance comes up as a new replicating instance, there is always a lost transaction file. Apply this lost transaction file at the new originating instance as soon as practicable because there could be additional lost transaction files in the event of other failovers. For example, failure of the new originating instance before the lost transaction file is processed. These additional lost transactions files can complicate the logic needed for lost transaction processing.

Apply the lost transactions on the new originating instance either manually or in a semi-automated fashion using the M-intrinsic function $ZQGBLMOD(). If you use $ZQGBLMOD() , two perform 2 additional steps ( mupip replicate -source -needrestart and mupip replicate -source -losttncomplete ) as part of lost transaction processing. Failure to run these steps can cause $ZQGBLMOD() to return false negatives that in turn can result in application data consistency issues.

Command Syntax:

mupip replicate -source
{-losttncomplete | -needrestart}
-instsecondary=<replicating instance name>

-losttncomplete

Indicate to GT.M that all lost transaction processing using $ZQGBLMOD() is complete. Use this qualifier either explicitly or implicitly to prevent a future $ZQGBLMOD() on an instance from returning false positives when applying future lost transactions. This ensures accuracy of future $ZQGBLMOD() results.

Always use this qualifier when an originating instance comes up as a replicating instance.

Always run MUPIP REPLICATE -SOURCE -LOSTTNCOMPLETE on each of the replicating instances after applying all lost transaction files except on the following occasions:

-needrestart

Checks whether the originating instance ever communicated with the specified replicating instance (if the receiver server or a fetchresync rollback on the replicating instance communicated with the Source Server) since the originating instance was brought up. If so, this command displays the message SECONDARY INSTANCE xxxx DOES NOT NEED TO BE RESTARTED indicating that the replicating instance communicated with the originating instnace and hence does not need to be restarted. If not, this command displays the message SECONDARY INSTANCE xxxx NEEDS TO BE RESTARTED FIRST. In this case, bring up the specified instance as a replicating instance before the lost transactions from this instance are applied. Failure to do so before applying the corresponding lost transactions causes $ZQGBLMOD() to return false negatives which can result in application data inconsistencies.

The mupip replic -source -needrestart command should be invoked once for each lost transaction file that needs to be applied. It should be invoked on the new originating instance before applying lost transactions. Specify -instsecondary to provide the instance name of the replicating instance where the lost transaction file was generated. If not, the environment variable gtm_repl_instsecondary is implicitly assumed to hold the name of the replicating instance.

If the lost transaction file was generated from the same instance to which it is to be applied, a mupip replicate -source -needrestart command is not required.

Always remember to bring the replicating instance (specified in the -needrestart command) as an immediate replicating instance of the current originating instance. If it is brought up as a replicating instance through a different intermediate replicating instance, the -needrestart command unconditionally considers the instance as not having communicated with the originating instance even though it might be up and running.

The Source Server on the originating instance and/or Receiver Server or fetchresync rollback on the replicating instance need not be up and running at the time you run this command.

However, it is adequate if they were up at some point in time after the originating instance was brought up.

This command protects against a scenario where the originating instance when the lost transaction file is generated is different from the primary instance when the lost transactions are applied (note that even though they can never be different in case of a dual-site configuration, use of this command is nevertheless still required).

$ZQGBLMOD() relies on two fields in the database file header of the originating instance to be set appropriately. Zqgblmod Trans and Zqgblmod Seqno. In an LMS configuration, if there are more than two instances, and no instances other than the originating and replicating instances are involved in the rollback -fetchresync participate in the sequence number determination. Hence, they do not have their Zqgblmod Seqno (and hence Zqgblmod Trans) set when that particular lost transaction file is generated. If any of the non-participating instances is brought up as the new originating instance and that particular lost transaction file is applied on the originating instance, the return values of $ZQGBLMOD() will be unreliable since the reference point (Zqgblmod Trans) was not set appropriately. Hence, this command checks whether the replicating instance where the lost transaction was previously generated has communicated with the current originating instance after it came up as the originating instance. If it is affirmative, the Zqgblmod Seqno and Zqgblmod Trans fields would have been appropriately set and hence $ZQGBLMOD() values will be correct.

Example:

$ mupip replic -source -losttncomplete

This command updates the Zqgblmod Seqno and Zqgblmod Trans fields (displayed by a dse dump -fileheader command) in the database file headers of all regions in the global directory to the value 0. Doing so causes a subsequent $ZQGBLMOD() to return the safe value of one unconditionally until the next lost transaction file is created.

GDSJEX07 ROLLBACK SECONDARY Perth

The MUPIP REPLICATE -RECEIVER -START command starts a Receiver Server and the Update Process. The general syntax for starting a Receiver Server and the Update Process is:

mupip replicate -receiver -start 
[autorollback_qualifier]
connection_qualifiers 
logfile_management_qualifiers 
[operator_override_qualifiers]
[replication_filter_qualifers]
[si_replication_qualifiers]
[tls_replication_qualifier]

The square brackets [] denote an optional qualifier group. The optional and mandatory qualifiers in each qualifier group are as follows:

Autorollback Qualifier:

-autorollback[=verbose]

-AUTOROLLBACK in a Receiver Server startup command of a BC/SI replication instance performs an automatic MUPIP JOURNAL -ROLLBACK -BACKWARD -FETCHRESYNC=<portno>. Choosing between -AUTOROLLBACK and -FETCHRESYNC (with -[NO]LOSTTRANS and -[NO]BROKENTRANS) depends on your replicating configuration and how your application processes lost transaction files. Use a MUPIP JOURNAL -ROLLBACK command with -FETCHRESYNC when you need:

For more information on MUPIP JOURNAL -ROLLBACK -BACKWARD -FETCHRESYNC, refer to “Rolling Back a Replicated Database ”.

Use -AUTOROLLBACK when there are no application side restraints on the timing/need of processing of the lost transaction file. With -AUTOROLLBACK, the Receiver Server performs a connection handshake with the originating/upstream Source Server. If the upstream Source Server sends the REPL_ROLLBACK_FIRST message during the handshake, the Receiver Server with -AUTOROLLBACK performs the following operations:

Connection Qualifiers:

-listenport=<port number>

Specifies the TCP port number the Receiver Server will listen to for incoming connections from a Source Server. Note that the current implementation of the Receiver Server does not support machines with multiple IP addresses.

-[NO]{SEND|RECV}BUFFSIZE[=n]

Specifies the desired minimum TCP send and/or receive buffer sizes. This affects the SO_SNDBUF and SO_RCVBUF socket options of the socket GT.M uses for replication, not the journalpool or any other application-level buffer. n is a positive integer value indicating the desired minimum buffer size. If GT.M finds that the specified buffer already has a sufficient size when it is created, GT.M will avoid setting the buffer explicitly. The -NO{SEND|RECV}BUFFSIZE version of this qualifier instructs GT.M to avoid setting the buffer sizes under any circumstance. In some environments, when the size of these buffers are dynamically adjusted except in cases where an application sets their size explicitly, -NO{SEND|RECV}BUFFSIZE can lead to good performance in a wide variety of network conditions. By default and without passing this qualifier, GT.M enforces a minimum size of approximately 1MiB for each buffer. This qualifier may only be passed to a -START command.

Note

The actual size of a tcp buffer depends on a variety of environmental conditions, including system configuration, operating system, and available memory. Users of GT.M on Linux may observe that GT.M will report in the source and/or receiver logs buffers that are approximately twice what is requested, if the request has been honored by the OS. This is due to a quirk in the way that the Linux kernel reports TCP buffer sizes: the user-available size is approximately equal to what is requested, and the additional space is used internally by the kernel.

Logfile Management Qualifiers:

-log=<recsrv_log_file_name >

Specifies the location of the log file of the Receiver Server. When -log is specified, the Update Process writes to a log file named <recsrv_log_file_name>.updproc. Note that the name of the Update Process log file name has .updproc at the end to distinguish it from the Receiver Server's log file name.

-log_interval="[integer1],[integer2]"

integer1 specifies the number of transactions the Receiver Server should process between updates to its log file. integer2 specifies the number of transactions the Update Process should process between updates to its log file. The default logging interval is 1000 transactions.

If integer1 or integer2 is 0, the logging interval is set to the default value.

Operator Override Qualifiers:

-updateresync=</path/to/bkup-orig-repl-inst-file>

-updateresync guarantees GT.M that the replicating instance was, or is, in sync with the originating instance and it is now safe to resume replication. Use -updateresync only in the following situations:

-updateresync uses the journal sequence number stored in the replicating instance's database and the history record available in the backup copy of the replication instance file of the originating instance (</path/to/bkup-orig-repl-inst-file>) to determine the journal sequence number at which to start replication.

When replication resumes after a suspension (due to network or maintenance issues), GT.M compares the history records stored in the replication instance file of the replicating instance with the history records stored in the replication instance file of the originating instance to determine the point at which to resume replication. This mechanism ensures that two instances always remain in sync when a replication connection resumes after an interruption. -updateresync bypasses this mechanism by ignoring the replication history of the replicating instance and relying solely on the current journal sequence number and its history record in the originating instance's history to determine the point for resuming replication. As it overrides a safety check, use -updateresync only after careful consideration. You can check with your GT.M support channel as to whether -updateresync is appropriate in your situation.

To perform an updateresync, the originating instance must have at least one history record. You need to take a backup (BACKUP -REPLINST) of the replication instance file of the originating instance while the Source Server is running. This ensures that the instance file has at least one history record. Even though it is safe to use a copy (for example, an scp) of the replication instance file of the originating instance taken after shutting down its Source Server, BACKUP -REPLINST is recommended because it does not require Source Server shutdown. You also need an empty instance file (-INSTANCE_CREATE) of the replicating instance to ensure that it bypasses the history information of the current and prior states.

When started with -updateresync, the receiver server continues trying connection attempts to the source server until it gets a successful update in response. Once an update goes through, subsequent connection restarts behave as if the receiver was started without -updateresync.

You also need use -updateresync to replace your existing replication instance files if a GT.M version upgrade changes the instance file format. The instance file format was changed in V5.5-000. Therefore, upgrading a replicating instance from a version prior to GT.M V5.5-000 up to V5.5-000 or higher requires replacing its instance file.

Prior to V5.5-000, -updateresync did not require the argument (<bckup_orig_repl_inst_file>). The syntax for -updateresync depends on the GT.M version.

For information on the procedures that use -updateresync, refer to “Setting up a new replicating instance of an originating instance (A→B, P→Q, or A→P)”, “Replacing the replication instance file of a replicating instance (A→B and P→Q)”, “Replacing the replication instance file of a replicating instance (A→P)”, and “Setting up a new replicating instance from a backup of the originating instance (A→P)”.

-noresync

Instructs the Receiver Server to accept a SI replication stream even when the receiver is ahead of the source. In this case, the source and receiver servers exchange history records from the replication instance file to determine the common journal stream sequence number and replication resumes from that point onwards. Specifying -noresync on a BC replication stream produces a NORESYNCSUPPLONLY error. Specifying -noresync on a SI replication stream receiver server where the receiving instance was started with -UPDNOTOK (updates are disabled) produces a NORESYNCUPDATERONLY error. Note also that the noresync qualifier is not the opposite of the resync qualifier of rollback (mupip journal -rollback -resync), which is intended for use under the direction of FIS GT.M support.

SI Replication Qualifiers:

-initialize

Used when starting a Receiver Server of an SI replication stream with -updateresync to specify that this is the first connection between the instances. MUPIP ignores these qualifiers when starting BC replication (that is, no updates permitted on the instance with the Receiver Server). This qualifier provides additional protection against inadvertent errors.

-resume=<strm_num>

Used when starting a Receiver Server of an SI replication stream with -updateresync in case the receiver instance has previously received from the same source but had only its instance file (not database files) recreated in between (thereby erasing all information about the source instance and the stream number it corresponds to recorded in the receiver instance file). In this case, the command mupip replic -receiv -start -updateresync=<instfile> -resume=<strm_num>, where strm_num is a number from 1 to 15, instructs the receiver server to use the database file headers to find out the current stream sequence number of the receiver instance for the stream number specified as <strm_num>, but uses the input instance file (specified with -updateresync) to locate the history record corresponding to this stream sequence number and then exchange history with the source to verify the two instances are in sync before resuming replication. Note that in case -resume is not specified and only -updateresync is specified for a SI replication stream, it uses the input instance file name specified with -updateresync to determine the stream sequence number as well as provide history records to exchange with the source instance (and verify the two are in sync). Assuming that instance files are never recreated (unless they are also accompanied by a database recreate), this qualifier should not be required in normal usage situations.

-reuse=<instname>

Used when starting a Receiver Server of an SI replication stream with -updateresync in case the receiver instance has previously received from fifteen (all architecturally allowed) different externally sourced streams and is now starting to receive from yet another source stream. The command mupip replic -receiv -start -updateresync=<instfile> -reuse=<instname>, where instname is the name of a replication instance, instructs the receiver server to look for an existing stream in the replication instance file header whose Group Instance Name (displayed by a mupip replic -editinstance -show command on the receiver replication instance file) matches the instance name specified and if one does, reuse that stream number for the current source connection (erasing any record of the older Group using the same stream number).

TLS Replication Qualifiers:

-tlsid=<label>

Instructs the Source or Receiver Server to use the TLS certificate and private key pairs having <label> as the TLSID in the configuration file pointed to by the gtmcrypt_config environment variable. TLSID is a required parameter if TLS/SSL is to be used to secure replication connection between instances. If private keys are encrypted, an environment variable of the form gtmtls_passwd_<label> specifies their obfuscated password. You can obfuscate passwords using the 'maskpass' utility provided along with the encryption plugin. If you use unencrypted private keys, set the gtmtls_passwd_<label> environment variable to a non-null dummy value; this prevents inappropriate prompting for a password.

The following command starts the Update Process only, if it has been shutdown independent of the Receiver Server.

Command syntax:

mupip replicate -receiver -start {-updateonly|-helpers[=m[,n]]

Qualifiers:

-updateonly

If the Update Process has been shutdown independent of the Receiver Server, use this qualifier to restart the Update Process.

-helpers[=m[,n]]

Starts additional processes to help improve the rate at which updates from an incoming replication stream are applied on a replicating instance.

Example:

$ mupip replicate -receiver -start -listenport=1234 -helpers -log=B2C.log -buffsize=$recpool_size

This command starts the Receiver Server with Helper Processes. The following sample output from the ps command shows that there are 5 reader processes and 3 writer processes.

gtmuser1 11943 1     0 06:42 ? 00:00:00 /usr/library/GTM/mupip replicate -receiver -start 
-listenport=1234 -helpers -log=B2C.log -buff=$rec_pool_size
gtmuser1 11944 11943 0 06:42 ? 00:00:00 /usr/library/GTM/mupip replicate -updateproc
gtmuser1 11945 11943 0 06:42 ? 00:00:00 /usr/library/GTM/mupip replicate -updhelper -reader
gtmuser1 11946 11943 0 06:42 ? 00:00:00 /usr/library/GTM/mupip replicate -updhelper -reader
gtmuser1 11947 11943 0 06:42 ? 00:00:00 /usr/library/GTM/mupip replicate -updhelper -reader
gtmuser1 11948 11943 0 06:42 ? 00:00:00 /usr/library/GTM/mupip replicate -updhelper -reader
gtmuser1 11949 11943 0 06:42 ? 00:00:00 /usr/library/GTM/mupip replicate -updhelper -reader
gtmuser1 11950 11943 0 06:42 ? 00:00:00 /usr/library/GTM/mupip replicate -updhelper -writer
gtmuser1 11951 11943 0 06:42 ? 00:00:00 /usr/library/GTM/mupip replicate -updhelper -writer
gtmuser1 11952 11943 0 06:42 ? 00:00:00 /usr/library/GTM/mupip replicate -updhelper -writer

Command syntax:

mupip replicate -receiver -shutdown [-helpers | -updateonly] [-timeout=<timeout in seconds>] 

Qualifiers:

-shutdown

Initiates the shutdown procedures of the Receiver Server, Update Process, and/or helper processes. If the Receiver Server previously shut down abnormally, -shutdown can shut down helper processes left running.

-helper

Shuts down only the Helper Processes and leaves the Receiver Server and Update Process to continue operating as before. All helpers processes shut down even if -helper values are specified.

-timeout

Specifies the period of time (in seconds) the shutdown command should wait before signaling the Receiver Server, Update Process, and/or helper processes to shut down.If you do not specify -timeout, the default timeout period is 30 seconds. If you specify -timeout=0, shutdown occurs immediately.

-updateonly

Use this qualifier to stop only the Update Process. If neither -updateonly nor -helper are specified, the Update Process, all helper processes (if any), and Receiver Server shut down.

Example:

$ mupip replicate -receiver -shutdown -helper

This example shuts down only the helper processes of the current Receiver Server. Note that all helpers processes shut down even if HELPER values are specified.

Use the following command to determine whether the Receiver Server is running.

Command syntax:

mupip replicate -receiver -checkhealth [-he[lpers]]

With helpers specified, -checkhealth displays the status of Helper Processes in addition to the status of Receiver Server and Update Process.

Command syntax:

mupip replicate -receiver -changelog -log=<log file name> [-log_interval="[integer1],[integer2]"]

-log_interval="[integer1],[integer2]"

integer1 specifies the number of transactions for which the Receiver Server should wait before writing to the log file. integer2 specifies the number of transactions for which the Update Process should wait before writing to the log file. The default logging interval is 1000 transactions.

If integer1 or integer2 is 0, the logging interval reverts to the prior value.

Command syntax:

mupip replicate -receiver -statslog={ON|OFF} 
 [-log_interval="[integer1],[integer2]"]

-log_interval="[integer1],[integer2]"

integer1 specifies the number of transactions for which the Receiver Server should wait before writing to the log file. integer2 specifies the number of transactions for which the Update Process should wait before writing to the log file. The default logging interval is 1000 transactions.

If integer1 or integer2 is 0, the logging interval reverts to the prior value.

Command syntax:

mupip replicate -receiver -showbacklog

Qualifiers:

-showbacklog

Use this qualifier to report the current backlog (that is, the difference between the last JNL_SEQNO written to the Receive Pool and the last JNLSEQNO processed by the Update Process) of journal records on the Receiver Server.

Command syntax:

mupip journal -rollback 
 {[-fetchresync=<port number>|-resync=<JNL_SEQNO>] 
  -[no]losttrans=[/dev/null|<unreplicated_updates.lost>]
 -[no]brokentrans=[/dev/null|<brokentrans.broken>] 
 -[no]online
  [-rsync_strm=<strm_num>]}
 -backward *

Qualifiers:

-rollback

Use -FETCHRESYNC or -RESYNC to rollback the database as a recovery step after a system failure or to make a change in the LMS replication configuration. If you do not use -FETCHRESYNC or -RESYNC, the database rolls back to the last consistent state.

-online

Specifies that ROLLBACK can run without requiring exclusive access to the database and the replication instance file. Any utility/command attempted while MUPIP JOURNAL -ONLINE -ROLLBACK operates waits for ROLLBACK to complete; the $gtm_db_startup_max_wait environment variable configures the wait period. For more information on -ROLLBACK -ONLINE, refer to “-ROLLBACK [{-ON[LINE]|-NOO[NLINE]}] ”.

-fetchresync

When there are unreplicated updates on a former primary/secondary instance, it cannot become a new replicating instance as its journal sequence number is higher than the journal sequence number of its new replication source. Use -ROLLBACK -FETCHRESYNC to roll back a BC/SI replicating instance to a journal sequence number that matches the journal sequence number of its replication source and generate a lost transaction file containing the unreplicated updates for the organization to reconcile. After the reconcilation (or rejection as the case may be) of the lost transaction file, run MUPIP REPLICATE -SOURCE -LOSTTNCOMPLETE to provide confirmation to GT.M that you have applied the lost transaction file. For -FETCHRESYNC to work on the replicating instance, you need to ensure that an active Source Server is running on the replication source/originating instance.

The format of the -FETCHRESYNC qualifier is:

-fetchresync=<port number> -[no]brokentrans=[/dev/null|<brokentrans.broken>] -[no]losttrans=[/dev/null|<unreplicated_updates.lost>]

Example:

$ mupip journal -rollback -fetchresync=2299 -losttrans="glo.lost" -backward

This command performs a ROLLBACK -FETCHRESYNC operation on a replicating instance to bring it to a common synchronization point from where the originating instance can begin to transmit updates to allow it to catch up. It also generates a lost transaction file glo.lost of all those transactions that are present on the replicating instance but not on the originating instance at port 2299.

-resync=<JNL_SEQNO>

Use this qualifier to roll back to the transaction identified by JNL_SEQNO (in decimal) only when the database/ journal files need to be rolled back to a specific point. If you specify a JNL_SEQNO that is greater than the last consistent state, the database/journal files will be rolled back to the last consistent state. Under normal operating conditions, you would not need this qualifier.

-rsync_strm=<strm_num>

Used when starting a rollback command with the -resync qualifier. The command mupip journal -rollback -resync=<sequence_num> -rsync_strm=<strm_num> instructs rollback to roll back the database to a sequence number specified with the -resync=<sequence_num> qualifier but that <sequence_num> is a journal stream sequence number (not a journal sequence number) corresponding to the stream number <strm_num> which can be any value from 0 to 15. Note that like the -resync qualifier, the -rsync_strm qualifier is also intended for use under the direction of your GT.M support channel.