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 command. Refer the "MUPIP" chapter for detailed information.

/REPLICATION

Sets journal characteristics and changes the replication state simultaneously. Can also be used with the /JOURNAL qualifier.

ON

Use this qualifier to enable replication for the selected database file(s) or region(s). This action also turns before-image journaling on. The system creates a new journal file for each database file or region, and renames the existing journal file.

OFF

Use this qualifier to disable replication of the database file(s) or region(s).

Command syntax:

mupip replicate /source /start
{/secondary=<hostname:port> | /passive}
/log=<log file name>
[/buffsize=<Journal Pool size in bytes>]
[/filter=<filter command>]
[/connectparams="<hard tries>, <hard tries period>, <soft tries
period>, <alert time>, <heartbeat period>, <max heartbeat wait>"]

Qualifiers:

/REPLICATE

Use this qualifier to access the replication subsystem.

/SOURCE

Use this qualifier to identify the Source Server.

/START

Use this qualifier to start the Source Server.

/SECONDARY=<hostname:port>

Use this qualifier to identify the secondary system. The qualifier should include an IP address or hostname that resolves to an IP address and the port at which the Receiver Server is waiting for a connection.

/PASSIVE

Use this qualifier to start the Source Server in passive mode.

/LOG=<log file name>

Use this mandatory qualifier to specify the location of the log file.

/BUFFSIZE=<Journal Pool size in bytes>

Use this optional qualifier to specify the size of the Journal Pool. The server rounds the size up or down to suit its needs. Any size less than 1 MB is rounded up to 1 MB. If you do not specify a qualifier, the size defaults to the GT.M default value of 64 MB. 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.

/FILTER=<filter command>

Use this optional qualifier to specify the complete path of the filter program and any associated arguments. If you specify arguments, you must 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 secondary system. If the filter program is an M program with entry-ref OLD2NEW^FILTER, specify the following path:

filter="mumps /run OLD2NEW^FILTER"

The filter must be written to take its imput from SYS$INPUT and write its output to SYS$OUTPUT. 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.

/connectparams=<hard tries>,<hard tries period>, <soft tries period>,<alert time>,<heartbeat period>,<max heartbeat wait>

Use this optional qualifier to specify the connection retry parameters. If the connection between the Source and Receiver Servers is broken or the Source Server fails to connect to the Receiver Server at startup, the Source Server applies these parameters to the reconnection attempts.

First, the Source Server makes the number of reconnection attempts specified by the <hard tries> value every <hard tries period> milliseconds. Then, the Source Server attempts reconnection every <soft tries period> seconds and logs an alert message every <alert time> seconds. If the specified <alert time> value is less than <hard tries>*<hard tries period>/1000 + lt;soft tries period>, it is set to the larger value. The Source Server sends 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.

Command syntax:

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

Qualifiers:

/SHUTDOWN

Use this qualifier to shutdown the Source Server.

/TIMEOUT=<timeout in seconds>

Use this optional qualifier to specify the period of time the server should wait before shutting down. If you do not specify a qualifier, the default timeout period is 30 seconds. If you specify /TIMEOUT=0 , shutdown occurs immediately.

Command syntax:

mupip replicate /source /activate
/secondary=<hostname:port>
[/log=<log file name>]
[/connectparams="<hard tries>,<hard tries period>, <soft tries period>,
<alert time>,<heartbeat period>,<max heartbeat wait>"]

Qualifiers:

/ACTIVATE

Use this qualifier to activate a passive Source Server. Once activated, the Source Server reads journal records from the Journal Pool and transports them to the system specified by the /SECONDARY qualifier.

Command syntax:

mupip replicate /SOURCE /DEACTIVATE

Qualifiers:

/DEACTIVATE

Use this qualifier to make an active Source Server passive. To change the secondary system with which the Source Server is communicating, deactivate the Source Server and then activate it with a different secondary system.

Command syntax:

mupip replicate /source /stopsourcefilter

Qualifiers:

/STOPSOURCEFILTER

Use this qualifier to instruct the Source Server to stop any active filter.

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

Command syntax:

mupip replicate /source /checkhealth

Qualifiers:

/CHECKHEALTH

Use this qualifier to 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.

Command syntax:

>mupip replicate /source /changelog /log=<log file name>

Qualfiers:

/CHANGELOG

Use this qualifier to instruct the Source Server to change its log file.

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

Command syntax:

mupip replicate /source /statslog={ON | OFF} [/log=<log file name>]

Qualifiers:

/STATSLOG={ON | OFF}

Use this qualifier to enable or disable detailed logging. When ON, the system logs current-state information of the Source Server and messages exchanged between the Source and Receiver Servers. If / log is not specified the system logs information to the same file used for general logging. By default, detailed logging is OFF. Once you enable it (ON), changing /STATSLOG to OFF can stop detailed logging.

Command syntax:

mupip replicate /source /showbacklog

Qualifiers:

/SHOWBACKLOG

Use this qualifier to report the current backlog of journal records (in terms of JNL_SEQNO) on the output device (normally the standard output device). This qualifier does not affect the statistics logged in the log file. The backlog is the difference between the last JNL_SEQNO written to the Journal Pool and the last JNL_SEQNO sent by the Source Server to the Receiver Server.

Command syntax:

mupip replicate /receiver /start
/listenport=<port number>
/log=<log file name>
[/buffsize=<Receive Pool size in bytes>]
[/filter=<filter command>]
[/stopsourcefilter] [/updateresync]

Qualifiers:

/RECEIVER

Use this qualifier to identify the Receiver Server.

/LISTENPORT=<port number>

Use this qualifier to specify 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.

/STOPSOURCEFILTER

When a secondary restarts after an upgrade to a newer version, use this qualifier to stop any active filter at the primary Source Server. Alternatively, the filter at the primary system's Source Server can also be stopped by issuing the following command:

mupip replicate /source /stopsourcefilter

/updateresync

Indicates to the Source Server on the primary to update the last known synchronization point on the primary to that of the secondary.

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

Qualifiers:

/UPDATEONLY

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

Command syntax:

mupip replicate /receiver /shutdown [/updateonly]
[/timeout=<timeout in seconds>]

Qualifiers:

/UPDATEONLY

Use this qualifier to stop only the Update Process. If you do not specify this qualifier, both the Update Process and Receiver Server shut down.

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

Command syntax:

mupip replicate /receiver /checkhealth

Command syntax:

mupip replicate /receiver /changelog /log=<log file name>

Command syntax:

mupip replicate /receiver /statslog={ON | OFF}
[/log=<log file name>]

Command syntax:

mupip replicate /receiver /showbacklog

Qualifiers:

/SHOWBACKLOG

Use this qualifier to report the current backlog (i.e., 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>]}
/losttrans=<extract file> file-list

Qualifiers:

/ROLLBACK

Use this qualifier to rollback the database. If you do not use the /FETCHRESYNC qualifier, the database rolls back to the last consistent state.

/FETCHRESYNC=<port number>

Use this qualifier to roll back to the transaction that is identified by a reference point (a JNL_SEQNO) fetched from the primary system. This command rolls back a former primary to the journal sequence number at which the current primary took over.

The <port number> is the communication port number that the rollback command uses when fetching the reference point. Please provide, as <port number> for rollback, the same number used by the Receiver Server and with which the primary will attempt to establish communication.

The reference point sent by the primary system is the RESYNC_SEQNO (explained later) that the primary has maintained. The database/journal files are rolled back to the earlier RESYNC_SEQNO (i.e., the one received from primary or the one maintained locally).

/RESYNC=<JNL_SEQNO>

Use this qualifier to roll back to the transaction identified by <JNL_SEQNO> 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.

/LOSTTRANS=<extract file>

If failover occurs (i.e., primary system fails and secondary system assumes the primary system role), some transactions committed to A's database may not be reflected in B's database. Before the former primary becomes the new secondary, these transactions must be rolled off before it can assume the role of secondary. These transactions are known as "lost transactions."

The system stores extracted lost transactions in the file <extract file> specified by this mandatory qualifier. The starting point for the search for lost transactions is the JNL_SEQNO obtained from the primary system in the /FETCHRESYNC operation. If /FETCHRESYNC is not specified, <extract file> lists the post-consistent-state transactions that were undone by the rollback procedure to reach a consistent state.

	The extracted lost transactions list may contain broken transactions due to system failures that occurred during processing. Do not resolve these transactions–they are not considered to be committed.

FILE-LIST

Use this qualifier to indicate the list of journal files to be used in the rollback operation. When you specify * for file-list, GT.M uses the journal files of the database files listed in the Global Directory that GTM$GBLDIR points to for rollback.

	Currently, the only value accepted for file-list is *. This prevents incomplete input from being supplied to the rollback operation.

When a database file is rolled back, the corresponding journal file is also rolled back so that the two are synchronized. To roll back a journal file GT.M must truncate it at the JNL_SEQNO to which the database file is rolled back. Before the journal file is rolled back, GT.M makes a copy of it in the same directory. The name of the copy is the same as the name of the journal file; however, it includes the suffix _roll_bak. This "roll back" file is not created until the journal file is rolled back and truncated. A journal file whose entire contents are eliminated by a rollback is renamed with the suffix _rolled_bak. FIS recommends that you rename the roll back journal file immediately after a rollback if you want to save it, to prevent a subsequent rollback from overwriting it.

The journal file header includes a field that stores the name of the previous generation of the journal file when switched, thereby creating a chain of generations (i.e., each journal file points to its previous generation). The resynchronization and rollback operations use this chain to locate all the required generations of a journal file.

The previous generation of a journal file is listed as part of the output of the following command that displays the header information of a journal file. To display the header information of a journal file <jnl_file>, invoke the following command:

mupip journal /show=header <jnl_file>

Invoke the following command to change the previous generation journal file name in the journal file header:

mupip set /jnlfile <jnl_file> /[no]prevjnlfile=<jnlfilename> [-bypass]

Descriptions of the command qualifiers follow:

/JNLFILE

Use this qualifier to indicate that the target for the SET function is a journal file.

<journal file>

Use this qualifier to define the target journal file for the SET function.

/PREVJNLFILE = <jnlfilename>

Use this qualifier to change the name of the previous generation of the journal file in the header of <jnl_file> to <jnlfilename> (e.g., when moving the previous generation journal file to a different location). The file name can be a full path-name or a relative path name; however, before the file-name is stored in the header, it is expanded to its full path-name.

/NOPREVJNLFILE

Use this qualifier to cut the generation link of the journal file <jnl_file>. The name of the previous generation journal file is nullified in the header of <jnl_file>. Such an operation is appropriate when it is assured that there will never be a reason for a rollback to the previous generation journal file.

/BYPASS

Use this qualifier to override the requirement that database files (or their corresponding journal files) affected by the set command be available standalone.

	Changing the previous generation file link when a rollback operation is in progress or when the Source Server is actively replicating, can damage the journal file and hamper recoverability.

To eliminate the generation link of a journal file, specify noprevjnlfile option as part of the /JOURNAL=<journal-options> qualifier for MUPIP SET. When switching the journal file for database file mumps.dat, use the following command to cut the journal file generation link of the newly created journal file newmumps.mjl:

mupip set
/journal=(before,noprevjnlfile,file=newmumps.mjl)
/file mumps.dat

When journal files are switched as part of the online backup command, the generation link of a journal file can be cut. mupip backup accepts the /JOURNAL=<journal-options> qualifier along with /NEWJNLFILEs qualifier of online backup. Specify the noprevjnlfile as a journal-option to cut the journal file generation link of the newly created journal file.

The RESYNC_SEQNO of a system is the lesser of the following values:

The Source Server on the primary system records the JNL_SEQNO of the last transaction successfully sent in RESYNC_SEQNO. The Update Process on the secondary system records the JNL_SEQNO of the last transaction successfully processed in RESYNC_SEQNO. The RESYNC_SEQNO is maintained as resync_seqno in the file-header of each region.

The RESYNC_SEQNO of a system is the maximum of the local region resync_seqnos. If a rollback operation rolls a database/journal file to a JNL_SEQNO that is less than the resync_seqno of that database file, the resync_seqno is set to the largest JNL_SEQNO in that database/journal file.

When invoking the rollback /FETCHRESYNC command on the secondary, the RESYNC_SEQNO maintained on the secondary system is sent to the Source Server on the primary. This is part of the request message for the reference point of the resynchronization. The Source Server replies to this message with the primary system's RESYNC_SEQNO. For each replicated region, the Source Server also finds the per-region transaction number corresponding to the transaction that marks the synchronization point for that region. This transaction number is the largest JNL_SEQNO less than or equal to the minimum of the primary and secondary systems' RESYNC_SEQNO. The Source Server stores the transaction number found in resync_tn in the region file header. The set of all resync_tns represents the state of the database at the primary system when it synchronizes with the secondary system.