Commands and Qualifiers
ChapterA 7.A Database Replication

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

Qualifiers:

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.

-name

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.

$ 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.

Command syntax:

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

Qualifiers:

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.

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.

Command syntax:

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

Qualifiers:

Command syntax:

mupip replicate -source -showbacklog

Qualifiers:

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

Command syntax:

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

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.

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