iSharkFly-Open
/
fis-gtm
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
fis-gtm/sr_port/mupip.hlp

7132 lines
321 KiB
Plaintext
Raw Blame History

1 Introduction
Introduction
GT.M uses M Peripheral Interchange Program (MUPIP) for GT.M database
management, database journaling, and logical multisite replication (LMS).
This chapter summarizes the MUPIP commands pertaining to GT.M database
management and serves as a foundation for more advanced GT.M functionality
described for Journaling and LMS.
**Note**
Two MUPIP operations - INTRPT and STOP - perform process management
functions. All other MUPIP operations relate to the operation of the
database.
The GT.M installation procedure places the MUPIP utility program in a
directory specified by $gtm_dist.
Invoke MUPIP by executing the mupip program at the shell prompt. If this
does not work, consult your system manager (MUPIP requires that the
$gtm_dist point to the directory containing the MUPIP executable image).
$gtm_dist/mupip
MUPIP>
MUPIP asks for commands, with the MUPIP> prompt. Enter the EXIT command at
the MUPIP> prompt to stop the utility. MUPIP performs one operation at a
time, and automatically terminates after most operations.
When additional information appears on the command line after the mupip
program name, MUPIP processes the additional information as its command,
for example:
$gtm_dist/mupip stop 1158
This starts MUPIP and stops the process with Process ID (PID) 1158.
Some MUPIP commands require information contained in the global directory.
Therefore, a process must have access to a valid global directory before
using any MUPIP commands other than EXIT, INTRPT, JOURNAL, RESTORE, STOP
and the -file option of any command that has that option.
The environment variable gtmgbldir specifies the active global directory.
A gtmgbldir value of mumps.gld tells MUPIP to look for a global directory
file mumps.gld in the current directory. See the "Global Directory Editor"
chapter for more information on the global directory.
2 Operations
Operations
While most MUPIP operations can be performed when GT.M processes are
actively accessing database files, some operations require stand-alone
access. When using standalone access, no other process can access the
database file(s). When using concurrent access, other processes can read
or update the database file(s) while MUPIP accesses them. A few operations
permit concurrent access to read database files, but not to update them.
All MUPIP operations can be performed with stand-alone access - there is
never a requirement for another process to be accessing database files
when MUPIP operates on them.
Most MUPIP operations require write access to the database files with
which they interact. The exceptions are INTRPT and STOP, which do not
require database access, but may require other privileges; EXTRACT, which
requires read access; and INTEG, which may require write access, depending
on the circumstances it encounters and the qualifiers with which it is
invoked. The following table displays some of the MUPIP operations and
their database access requirements.
+------------------------------------------------------------------------+
| Operations | MUPIP command | Database Access Requirements |
|------------------------+---------------+-------------------------------|
| | | Backup never requires |
| Backup database files | MUPIP BACKUP | standalone access and |
| | | concurrent write access is |
| | | controlled by -[NO]ONLINE. |
|------------------------+---------------+-------------------------------|
| Create and initialize | MUPIP CREATE | Standalone access |
| database files | | |
|------------------------+---------------+-------------------------------|
| Converts a database | | |
| file from one endian | MUPIP | |
| format to the other | ENDIANCVT | Standalone access |
| (BIG to LITTLE or | | |
| LITTLE to BIG) | | |
|------------------------+---------------+-------------------------------|
| Recover database files | | |
| (for example, after a | | |
| system crash) and | MUPIP JOURNAL | Standalone access |
| extract journal | | |
| records | | |
|------------------------+---------------+-------------------------------|
| Restore databases from | | |
| bytestream backup | MUPIP RESTORE | Standalone access |
| files | | |
|------------------------+---------------+-------------------------------|
| Properly close | | |
| database files when | MUPIP RUNDOWN | Standalone access |
| processes terminate | | |
| abnormally. | | |
|------------------------+---------------+-------------------------------|
| | | Standalone access is required |
| | | if the MUPIP SET command |
| Modify database and/or | | specifies -ACCESS_METHOD, |
| journal file | MUPIP SET | -GLOBAL_BUFFERS, LOCK_SPACE |
| characteristics | | or -NOJOURNAL, or if any of |
| | | the -JOURNAL options ENABLE, |
| | | DISABLE, or BUFFER_SIZE are |
| | | specified. |
|------------------------+---------------+-------------------------------|
| Backup database files | MUPIP BACKUP | Concurrent access. |
|------------------------+---------------+-------------------------------|
| Grow the size of BG | MUPIP EXTEND | Concurrent access. |
| database files | | |
|------------------------+---------------+-------------------------------|
| | | Although MUPIP EXTRACT |
| | | command works with concurrent |
| Export data from | | access, it implicitly freezes |
| database files into | | the database to prevent |
| sequential (flat) or | MUPIP EXTRACT | updates. Therefore, from an |
| binary files | | application standpoint, you |
| | | might plan for a standalone |
| | | access during a MUPIP EXTRACT |
| | | operation. |
|------------------------+---------------+-------------------------------|
| Prevent updates to | MUPIP FREEZE | Standalone access. |
| database files | | |
|------------------------+---------------+-------------------------------|
| | | Concurrent access. However, |
| Check the integrity of | MUPIP INTEG | standalone access is required |
| GDS databases | | if MUPIP INTEG specifies |
| | | -FILE. |
|------------------------+---------------+-------------------------------|
| | | Although MUPIP LOAD works |
| | | with concurrent access, you |
| | | should always assess the |
| Import data into | | significance of performing a |
| databases | MUPIP LOAD | MUPIP LOAD operation when an |
| | | application is running |
| | | because it may result in an |
| | | inconsistent application |
| | | state for the database. |
|------------------------+---------------+-------------------------------|
| Defragment database | | |
| files to improve | MUPIP REORG | Concurrent access. |
| performance | | |
|------------------------+---------------+-------------------------------|
| Send an asynchronous | | |
| signal to a GT.M | MUPIP INTRPT | Non-database access. |
| process | | |
|------------------------+---------------+-------------------------------|
| Stop GT.M processes | MUPIP STOP | Non-database access. |
+------------------------------------------------------------------------+
2 Syntax
Syntax
The general format of MUPIP commands is:
mupip command [-qualifier[...]] [object[,...]] [destination]
MUPIP allows the abbreviation of commands and qualifiers. In each section
describing a command or qualifier, the abbreviation is also shown (for
example, B[ACKUP]). The abbreviated version of the command you can use on
the command line is B. To avoid future compatibility problems and improve
the readability, specify at least four characters when using MUPIP
commands in scripts.
Although you can enter commands in both upper and lower case (the mupip
program name itself must be in lower case on UNIX/Linux), the
typographical convention used in this chapter is all small letters for
commands. Another convention is in the presentation of command syntax. If
the full format of the command is too long for a single line of print, the
presentation wraps around into additional lines.
mupip backup -bytestream -transaction=1 accounts,history,tables,miscellaneous /var/production/backup/
When you enter a MUPIP command, one of its variable arguments is the
region-list. region-list identify the target of the command and may
include the UNIX wildcards "?" and "*". Region-lists containing UNIX
wildcard characters must always be quoted, for example, "*" to prevent
inappropriate expansion by the UNIX shell. Similarly, for file and
directory names you might want to avoid non-graphic characters and most
punctuations except underbars (_), not because of GT.M conventions but
because of inappropriate expansion by UNIX shells.
MUPIP qualifier values are restricted only by the maximum size of the
command input line, which is 4KB on some systems and upto 64KB on others.
1 GDM
GDM
The MUPIP commands described in this seciton are used for common database
operations and serves as the foundation for more advanced functionality
like Journaling and Replication.
2 BACKUP
BACKUP
Saves the contents of the database. It provides a consistent application
snapshot across all database regions involved in the backup operation.
The format of the MUPIP BACKUP command is:
B[ACKUP]
[
-BK[UPDBJNL]={DISABLE|OFF}]
-B[YTESTREAM] [-NET[TIMEOUT]]
-DA[TABASE]
-DBG
-[NO]NEWJNLFILES[=[NO]PREVLINK],[NO]S[YNC_IO]]
-O[NLINE]
-REC[ORD]
-REPL[ACE]
-REPLINSTANCE=target_location
-S[INCE]={DATABASE|BYTESTREAM|RECORD}
-T[RANSACTION]=hexadecimal_transaction_number
] region-list[,...] destination-list
**Important**
MUPIP BACKUP does a more comprehensive job of managing backup activities
than other backup techniques such as a SAN backup, breaking a disk mirror,
or a file system snapshot because it integrates journal management,
instance file management, and records timestamps in the database file
headers. To use other techniques, you must first freeze all regions
concurrently with a command such as MUPIP FREEZE -ON "*" in order to
ensure a consistent copy of files with internal structural integrity. FIS
neither endorses nor tests any third party products for backing up a GT.M
database.
o MUPIP BACKUP supports two methods of database backup: -BYTESTREAM and
-DATABASE. MUPIP BACKUP -BYTESTREAM directs the output to a broad
range of devices, including disks, TCP sockets, and pipes. MUPIP
BACKUP -DATABASE directs the output to random access devices (that is,
disks).
o [NO]ONLINE qualifier determines whether MUPIP BACKUP should suspend
updates to regions. For example, MUPIP BACKUP -NOONLINE suspends
updates to all regions from the time it starts the first region until
it finishes the last region. However, it does not suspend processes
that only read from the database.
o By default, MUPIP BACKUP is -DATABASE -ONLINE.
o If any region name does not map to an existing accessible file, or if
any element of the destination list is invalid, BACKUP rejects the
command with an error.
o region-list may specify more than one region of the current global
directory in a list. Regions are separated by a comma, and wildcards
can be used to specify them. Any region-name may include the wildcard
characters * and % (remember to escape them to protect them from
inappropriate expansion by the shell). Any region name expansion
occurs in M (ASCII) collation order.
o Depending on the type of backup, destination-list may be a single
directory, or a comma separated list of destinations including files,
piped commands, or TCP sockets.
o Region-list and destination-list items are matched in order - the
first region is mapped to the first destination, the second to the
second destination, and so on. If GT.M encounters a region mapped to a
directory, GT.M treats that directory as the destination for all
subsequent regions in the region-list.
o GT.M implicitly timestamps both BYTESTREAM and DATABASE backups using
relative timestamps (transaction numbers). You can also explicitly
specific a RECORD timestamp for custom-control (SANS or mirrored disk)
backup protocol. You might want to use these timestamps as reference
points for subsequent backups.
o It takes approximately one (1) minute (per region) for BACKUP -ONLINE
to give up and bypass a KILLs in progress; backup does not wait for
Abandoned Kills to clear.
o The environment variable gtm_baktmpdir specifies the directory where
mupip backup creates temporary files. If gtm_baktmpdir is not defined,
GT.M uses the deprecated GTM_BAKTMPDIR environment variable if
defined, and otherwise uses the current working directory.
o When you restrict access to a database file, GT.M propagates those
restrictions to shared resources associated with the database file,
such as semaphores, shared memory, journals and temporary files used
in the course of MUPIP BACKUP.
o GT.M supports only one concurrent -ONLINE backup on a database. MUPIP
BACKUP displays the BKUPRUNNING message if started when there is an
already running BACKUP.
o MUPIP BACKUP protects against overwriting of existing destination
files. However, it cannot protect other destinations, for example, if
the destination is a pipe into a shell command that overwrites a file.
Before starting a MUPIP BACKUP
Perform the following tasks before you begin a database backup.
o Ensure adequate disk space for target location and temporary files.
Set the environment variable gtm_baktmpdir to specify the directory
where MUPIP BACKUP creates temporary files. If gtm_baktmpdir is not
defined, GT.M uses the deprecated GTM_BAKTMPDIR environment variable
if defined, and otherwise uses the current working directory. Do not
place temporary files in the current directory for large databases in
production environments.
o When using replication, ensure that the Source/Receiver process is
alive (MUPIP REPLIC -SOURCE/-RECEIVER -CHECKHEALTH). Always backup the
replicating instance file with the database (BACKUP -REPLINST).
o If you intend to use a -DATABASE backup at the same time in the same
computer system as the source database, be sure to disable journaling
in the backed up database with -BKUPDBJNL=DISABLE.
o When doing a complete backup, switch journal files as part of the
backup command using -NEWJNLFILES=NOPREVLINK. This aligns the journal
files with the backup and simplifies journal file retention.
o If you follow separate procedures for backup and archive (moving to
secondary storage), you can save time by starting archive as soon as
MUPIP BACKUP completes the process of creating a backup database file
for a region. You do not need to wait for MUPIP BACKUP to complete
processing for all regions before starting archive. For example, a
message like:
DB file /home/jdoe/.fis-gtm/V6.0-001_x86_64/g/gtm.dat backed up in file /backup/gtm.dat
Transactions up to 0x0000000000E92E04 are backed up.
confirms that gtm.dat is backed up correctly and is ready for archive.
o Determine an appropriate frequency, timing, and backup method
(-BYTESTREAM or -COMPREHENSIVE) based on the situation.
o Ensure the user issuing backup commands has appropriate permissions
before starting the backup. Backup files hav e the ownership of the
user running MUPIP BACKUP.
o There is one circumstance under which a MUPIP BACKUP is not advised.
When your operational procedures call for taking backups of unmodified
databases and journal files on rebooting a system after a crash, then
use an underlying operating system command (cp, cpio, gzip, tar, and
so on) which will open the files read-only. Note that for ordinary
system crashes where the system simply stops writing to open files at
power down, you can use MUPIP JOURNAL to recover journaled database
files, and taking backups on reboot should not be required. However,
for system crashes with the possibility of damage to files already
written to disk (for example, if the crash involved an IO controller
with the potential for having written random data to disk immediately
prior to power down), such backups on reboot are appropriate.
Example:
$ mupip backup "*" /gtm/bkup
This example creates ready-to-run database backup of all regions.
3 BKupdbjnl
BKupdbjnl
A backup database shares the same journaling characteristics of the source
database. However, with BKUPDBJNL you can disable or turns off journaling
in the backup database. Use this qualifier if you intend to open your
backup database at the same time in the same environment as the source
database.
The format of the BKUPDBJNL qualifier is:
-BK[UPDBJNL]={DISABLE|OFF}
o Specify DISABLE to disable journaling in the backup database.
o Specify OFF to turn off journaling is in the backup database.
o Only one of the qualifiers DISABLE or OFF can be specified at any
given point.
3 Bytestream
Bytestream
Ttransfers MUPIP BACKUP output to a TCP connection, file (or a backup
directory), or a pipe. If there are multiple .dat files, BYTESTREAM
transfers output to a comma separated list of TCP connections, incremental
backup files and/or directories, or pipes. When used with -SINCE or
-TRANSACTION, MUPIP BACKUP allow incremental backup, that is, include
database blocks that have changed since a prior point specified by the
-SINCE or -TRANSACTION.
**Note**
MUPIP BACKUP output to a TCP connection saves disk I/O bandwidth on the
current system.
All bytream backups needs to be restored to a random access file (with
MUPIP RESTORE) before being used as a database file. -BYTESTREAM can also
send the output directly to a listening MUPIP RESTORE process via a TCP/IP
connection or a pipe.
The format of the BYTESTREAM qualifier is:
-B[YTESTREAM]
o -BYTESTREAM is compatible with -SINCE and -TRANSACTION.
o -INCREMENTAL is deprecated in favor of -BYTESTREAM. For upward
compatibility, MUPIP temporarily continues to support the deprecated
-INCREMENTAL.
3 Database
Database
Creates a disk-to-disk backup copy of the files of all selected regions.
DATABASE backup copy is a ready-to-use a GT.M database unlike BYTESREAM
backup which is required to be restored to a random access file.
**Note**
The DATABASE qualifier does not support backup to magnetic tape.
The format of the DATABASE qualifier is:
-D[ATABASE]
o By default, MUPIP BACKUP uses -DATABASE.
o The DATABASE qualifier is only compatible with the -[NO]NEW[JNLFILES],
-ONLINE, and -RECORD qualifiers.
o -COMPREHENSIVE is depreciated in favor of -DATABASE. For upward
compatibility, MUPIP temporarily continues to support the deprecated
-COMPREHENSIVE.
3 NETtimeout
NETtimeout
Specifies the timeout period when a bytestream BACKUP data is sent over a
TCP/IP connection. The format of the NETTIMEOUT qualifier is:
NET[TIMEOUT]=seconds
o The default value is 30 seconds.
o Use only with: -BYTESTREAM.
3 NEWJNLFILES
NEWJNLFILES
Determines the journaling charactertistics of the database files being
backed-up. All the established journaling characteristics apply to new
journal files. This qualifier is effective only for an ONLINE backup (the
default), when the database has journaling enabled.
The format of the NEWJNLFILES qualifier is:
-[NO]NEWJNLFILES[=[NO]PREVLINK], [NO]S[YNC_IO]]
o -NEWJNLFILES can take the following three values:
o PREVLINK: Back links new journal files with the prior generation
journal files. This is the default value.
o NOPREVLINK: Indicates that there should be no back link between
the newly created journals and prior generation journal files.
o SYNC_IO: Specifies that every WRITE to a journal file to be
committed directly to disk. On high-end disk subsystems (for
example, those that include non-volatile cache and that consider
the data to be committed when it reaches this cache), this might
result in better performance than the NOSYNC_IO option. NOSYNC_IO
turn off this option.
o -NONEWJNLFILES causes journaling to continue with the current journal
files. It does not accept any arguments.
o The default is -NEWJNLFILES=PREVLINK.
3 Online
Online
Specifies that while a MUPIP BACKUP operation is active, other processes
can update the database without affecting the result of the backup. The
format of the ONLINE qualifier is:
-[NO]O[NLINE]
o MUPIP BACKUP -ONLINE creates a backup of the database as of the moment
the backup starts. If the running processes subsequently update the
database, the backup does not reflect those updates.
o MUPIP BACKUP -ONLINE on regions(s) waits for up to one minute so any
concurrent KILL or MUPIP REORG operations can complete. If the KILL or
MUPIP REORG operations do not complete within one minute, MUPIP BACKUP
-ONLINE starts the backup with a warning that the backup may contain
incorrectly marked busy blocks. Such blocks waste space and can
desensitize operators to much more dangerous errors, but otherwise
don't affect database integrity. If you get such an error, it may be
better to stop the backup and restart it when KILL or MUPIP REORG
operations are less likely to interfere. Performing MUPIP STOP on a
process performing a KILL or MUPIP REORG operation may leave the
database with incorrectly marked busy blocks. In this situation, GT.M
converts the ongoing KILLs flag to abandoned KILLs flag. If MUPIP
BACKUP -ONLINE encounters ADANDONED_KILLS, it gives a message and then
starts the backup. An ABANDONED_KILLS error means both the original
database and the backup database possibly have incorrectly busy blocks
which should be corrected promptly.
o By default, MUPIP BACKUP is -ONLINE.
3 Record
Record
Timestamps (in the form of a transaction number) a database file to mark a
reference point for subsequent bytestream, database, or custom backup
(SANS or disk mirror) protocols. Even though -DATABASE and -BYTESTREAM
both mark their own relative timestamps, -RECORD provides an additional
timestamp option. MUPIP FREEZE also provides the -RECORD qualifier because
a FREEZE may be used to set the database up for a SAN or disk-mirror based
backup mechanism.
The format of the RECORD qualifier is:
-R[ECORD]
o Use -RECORD (with the hypen) to timpestamp a refererence point and use
RECORD as a keyword (as in -SINCE=RECORD) to specific the starting
point for a MUPIP BACKUP operation.
o -RECORD replaces the previously RECORDed transaction identifier for
the database file.
3 REPLace
REPLace
Overwrites the existing destination files.
The format of the REPLACE qualifier is:
-[REPL]ACE
o By default, MUPIP BACKUP protect against overwriting the destination
files. -REPLACE disables this default behavior.
o -REPLACE is compatible only with -DATABASE.
3 REPLInstance
REPLInstance
Specifies the target location to place the backup of the replication
instance file.
**Note**
The replication instance file should always be backed up with the database
file.
The format of the REPLINSTANCE qualifier is:
-REPLI[NSTANCE]=<target_location>
3 Since
Since
Includes blocks changed since the last specified backup. The format of the
SINCE qualifier is:
-S[INCE]={DATABASE|BYTESTREAM|RECORD}
o keyword can include any one of the following:
o D[ATABASE] - Backup all changes since the last MUPIP BACKUP
-DATABASE.
o B[YTESTREAM] - Backup all changes since the last MUPIP BACKUP
-BYTESTREAM.
o R[ECORD] - Backup all changes since the last MUPIP BACKUP
-RECORD.
o By default, MUPIP BACKUP -BYTESTREAM operates as -SINCE=DATABASE.
o Incompatible with: -TRANSACTION.
3 Transaction
Transaction
Specifies the transaction number of a starting transaction that causes
BACKUP -BYTESTREAM to copy all blocks that have been changed by that
transaction and all subsequent transactions. The format of the TRANSACTION
qualifier is:
-T[RANSACTION]=transaction-number
o A Transaction number is always 16 digit hexadecimal number. It appears
in a DSE DUMP -FILEHEADER with the label "Current transaction".
o If the transaction number is invalid, MUPIP BACKUP reports an error
and rejects the command.
o It may be faster than a DATABASE backup, if the database is mostly
empty.
o Incompatible with: -DATABASE, -SINCE
**Note**
A point in time that is consistent from an application perspective is
unlikely to have the same transaction number in all database regions.
Therefore, except for -TRANSACTION=1, this qualifier is not likely to be
useful for any backup involving multiple regions.
3 Examples
Examples
Example:
$ mupip backup -bytestream REPTILES,BIRDS bkup
Suppose that the environment variable gtmgbldir has regions REPTILES and
BIRDS that map to files called REPTILES.DAT and BIRDS.DAT (no matter which
directory or directories the files reside in). Then the above example
creates bytestream backup files REPTILES.DAT and BIRDS.DAT in the bkup
directory since the last DATABASE backup.
Example:
$ mupip backup -bkupdbjnl="OFF" "*"
This command turns off journaling in the backup database.
Example:
$ mupip backup -bytestream "*" tcp://philadelphia:7883,tcp://tokyo:8892
Assuming a Global Directory with two regions pointing to ACN.DAT and
HIST.DAT, this example creates a backup of ACN.DAT to a possible MUPIP
RESTORE process listening at port 7883 on server philadelphia and HIST.DAT
to a possible MUPIP RESTORE process listening at port 8893 on server
tokyo.
Always specify the <machine name> and <port> even if both backup and
restore are on the same system, and ensure that the MUPIP RESTORE process
is started before the MUPIP BACKUP process.
Example:
$ mupip backup -database -noonline "*" bkup
DB file /home/gtmnode1/gtmuser1/mumps.dat backed up in file bkup/mumps.dat
Transactions up to 0x00000000000F42C3 are backed up.
BACKUP COMPLETED.
This command creates a disk-to-disk backup copy of all regions of the
current database in directory bkup. GT.M freezes all the regions during
the backup operation.
Example:
$ mupip backup -bytestream -nettimeout=420 DEFAULT tcp://${org_host}:6200
This command creates a backup copy of the DEFAULT region with timeout of
420 seconds.
Example:
$ mupip backup -bytestream DEFAULT '"| gzip -c > online5pipe.inc.gz"'
This command sends (via a pipe) the backup of the DEFAULT region to a gzip
command.
Example:
$ mupip backup -online DEFAULT bkup
DB file /gtmnode1/gtmuser1/mumps.dat backed up in file bkup/mumps.dat
Transactions up to 0x00000000483F807C are backed up.
BACKUP COMPLETED.
This command creates a backup copy of the DEFAULT region of the current
database in directory bkup. During the backup operation, other processes
can read and update the database.
Example:
$ mupip backup -record DEFAULT bkup
This command sets a reference point and creates a backup copy of the
DEFAULT region of the current database in directory bkup.
Example:
$ mupip backup -online -record DEFAULT bkup1921
DB file /home/reptiles/mumps.dat backed up in file bkup1921/mumps.dat
Transactions up to 0x00000000000F4351 are backed up.
Example:
$ mupip backup -bytestream -since=record DEFAULT bkup1921onwards
MUPIP backup of database file /home/reptiles/mumps.dat to bkup1921onwards/mumps.dat
DB file /home/reptiles/mumps.dat incrementally backed up in file bkup1921onwards/mumps.dat
6 blocks saved.
Transactions from 0x00000000000F4351 to 0x00000000000F4352 are backed up.
BACKUP COMPLETED.
The first command sets a reference point and creates a backup copy of the
DEFAULT region of the current database in directory bkup1921. The second
command completes a bytestream backup starting from the reference point
set by the first command.
Example:
$ mupip backup -bytestream -transaction=1 DEFAULT bkup_dir
MUPIP backup of database file /gtmnode1/gtmuser1/mumps.dat to bkup_dir/mumps.dat
DB file /gtmnode1/gtmuser1/mumps.dat incrementally backed up in file bkup/mumps.dat
5 blocks saved.
Transactions from 0x0000000000000001 to 0x0000000000000003 are backed up.
BACKUP COMPLETED.
This command copies all in-use blocks of the DEFAULT region of the current
database to directory bkup_dir.
Example:
$ mupip backup -newjnlfiles=noprevlink,sync_io "*" backupdir
This example creates new journal files for the current regions, cuts the
previous journal file link for all regions in the global directory,
enables the SYNC_IO option and takes a backup of all databases in the
directory backupdir.
2 CREATE
CREATE
Creates and initializes database files using the information in a Global
Directory file. If a file already exists for any segment, MUPIP CREATE
takes no action for that segment.
The format of the CREATE command is:
CR[EATE] [-R[EGION]=region-name]
The single optional -REGION qualifier specifies a region for which to
create a database file.
Note that one GT.M database file grows to a maximum size of 224M
(234,881,024) blocks. This means, for example, that with an 8KB block
size, the maximum single database file size is 1,792GB (8KB*224M). Note
that this is the size of one database file -- a logical database (an M
global variable name space) can consist of an arbitrary number of database
files.
3 Region
Region
Specifies a single region for creation of a database file. By default,
MUPIP CREATE creates database files for all regions in the current Global
Directory that do not already have a database file.
The format of the REGION qualifier is:
-R[EGION]=region-name
3 Examples
Examples
Example:
$ mupip create -region=REPTILES
This command creates the database file specified by the Global Directory
(named by the GT.M Global Directory environment variable) for region
REPTILES.
2 DOWNGRADE
DOWNGRADE
The MUPIP DOWNGRADE command changes the file header format to V4 or V5.
The format of the MUPIP DOWNGRADE command is:
D[OWNGRADE] -V[ERSION]={V4|V5} file-name
For V4:
o It reduces the size from 8 bytes to 4 bytes for fields like current
transaction (CTN), maximum tn (MTN) and others that contain
transaction numbers.
o It removes the results of any prior DBCERTIFY run on the database.
o You cannot downgrade a V5 database which has standard null collation.
In such a case, perform a MUPIP EXTRACT -FORMAT=ZWR operation on the
V5 database and then perform a MUPIP LOAD operation on a V4 database.
3 VERSION
VERSION
Specifies file header format. For more information on the downgrade
criteria for your database, refer to the release notes document of your
current GT.M version.
3 Examples
Examples
Example:
$ mupip downgrade mumps.dat
This command changes the file-header of mumps.dat to V4 format.
2 ENDIANCVT
ENDIANCVT
Converts a database file from one endian format to the other (BIG to
LITTLE or LITTLE to BIG). The format of the MUPIP ENDIANCVT command is:
ENDIANCVT [-OUTDB=<outdb-file>] -OV[ERRIDE] <db-file>
o <db-file> is the source database for endian conversion. By default
ENDIANCVT converts <db-file> in place.
o outdb writes the converted output to <outdb-file>. In this case,
ENDIANCVT does not modify the source database <db-file>.
o ENDIANCVT produces a <outdb-file>of exactly the same size as
<db-file>.
**Important**
Ensure adequate storage for <outdb-file> to complete the endian
conversion successfully.
o ENDIANCVT requires standalone access to the database.
o GT.M displays a confirmation request with the "from" and "to" endian
formats to perform the conversion. Conversion begins only upon
receiving positive confirmation, which is a case insensitive "yes".
o In a multi-site replication configuration, the receiver server
automatically detects the endian format of an incoming replication
stream and converts it into the native endian format. See Database
Replication chapter for more information.
o Encrypted database files converted with ENDIANCVT require the same key
and the same cipher that were used to encrypt them.
**Note**
GT.M on a big endian platform can convert a little endian database into
big endian and vice versa; as can GT.M on a little endian platform. GT.M
(run-time and utilities other than MUPIP ENDIANCVT) on a given endian
platform opens and processes only those databases that are in the same
endian format. An attempt to open a database of a format other than the
native endian format produces an error.
3 OVerride
OVerride
Enables MUPIP ENDIANCVT to continue operations even if GT.M encounters the
following errors:
o "minor database format is not the current version"
o "kills in progress"
o "a GT.CM server is accessing the database"
Note that the OVERRIDE qualifier does not override critical errors
(database integrity errors, and so on) that prevent a successful endian
format conversion.
3 Examples
Examples
$ mupip endiancvt mumps.dat -outdb=mumps_cvt.dat
Converting database file mumps.dat from LITTLE endian to BIG endian on a LITTLE endian system
Converting to new file mumps_cvt.dat
Proceed [yes/no] ?
This command detects the endian format of mumps.dat and converts it to the
other endian format if you type yes to confirm.
2 EXIT
EXIT
Stops a MUPIP process and return control to the process from which MUPIP
was invoked.
The format of the MUPIP EXIT command is:
EXI[T]
The EXIT command does not accept any qualifiers.
2 EXTEND
EXTEND
Increases the size of a database file. By default, GT.M automatically
extends a database file when there is available space.
The format of the MUPIP EXTEND command is:
EXTE[ND] [-BLOCKS=<data-blocks-to-add>] region-name
o The only qualifier for MUPIP EXTEND is BLOCKS.
o The required region-name parameter specifies the name of the region to
expand.
o EXTEND uses the Global Directory to map the region to the dynamic
segment and the segment to the file.
3 Blocks
Blocks
Specifies the number of GDS database blocks by which MUPIP should extend
the file. GDS files use additional blocks for bitmaps. MUPIP EXTEND adds
the specified number of blocks plus the bitmap blocks required as
overhead. The format of the BLOCK qualifier is:
-BLOCKS=data-blocks-to-add
By default, EXTEND uses the extension value in the file header as the
number of GDS blocks by which to extend the database file. You can specify
as many blocks as needed as long as you are within the maximum total
blocks limit (which could be as high as 224 million GDS blocks).
3 Examples
Examples
$ mupip extend DEFAULT -blocks=400
This command adds 400 GDE database block to region DEFAULT.
Example:
$ mupip extend REPTILES -blocks=100
This command adds 100 GDE database blocks to the region REPTILES.
2 EXTRACT
EXTRACT
Backups certain globals or to extract data from the database for use by
another system. The MUPIP EXTRACT command copies globals from the current
database to a sequential output file in one of three formats-GO, BINARY,
or ZWR. The format of the EXTRACT command is:
EXTR[ACT]
[
-FO[RMAT]={GO|B[INARY]|Z[WR]}
-FR[EEZE]
-LA[BEL]=text
-[NO]L[OG]
-S[ELECT]=global-name-list]
]
{-ST[DOUT]|file-name}
o By default, MUPIP EXTRACT uses -FORMAT=ZWR.
o MUPIP EXTRACT uses the Global Directory to determine which database
files to use.
o MUPIP EXTRACT supports user collation routines. When used without the
-FREEZE qualifier, EXTRACT may operate concurrently with normal GT.M
database access.
o To ensure that MUPIP EXTRACT reflects a consistent application state,
suspend the database updates to all regions involved in the extract,
typically with the FREEZE qualifier, or backup the database with the
ONLINE qualifier and extract files from the backup.
o EXTRACT places its output in the file defined by the file- name.
EXTRACT may output to a UNIX file on any device that supports such
files, including magnetic tapes.
o In UTF-8 mode, MUPIP EXTRACT write sequential output file in the UTF-8
character encoding. Ensure that MUPIP EXTRACT commands and
corresponding MUPIP LOAD commands execute with the same setting for
the environment variable gtm_chset.
**Note**
Magnetic tapes may have a smaller maximum file size than disks.
For information on extracting globals with the %GO utility, refer to "M
Utility Routines" chapter of the GT.M Programmer's Guide. MUPIP EXTRACT is
typically faster, but %GO can be customized.
The following sections describe the qualifiers of MUPIP EXTRACT command.
3 FOrmat
FOrmat
Specifies the format of the output file. The format of the FORMAT
qualifier is:
-FO[RMAT]=format_code
The format code is any one of the following:
o B[INARY] - Binary format, used for database reorganization or short
term backups. MUPIP EXTRACT -FORMAT=BINARY works much faster than
MUPIP EXTRACT -FORMAT=GO and MUPIP EXTRACT -FORMAT=ZWR. Note: There is
no defined standard to transport binary data from one GT.M
implementation to another. Further, FIS reserves the right to modify
the binary format in new versions. The first record of a BINARY format
data file contains the header label. The header label is 87 characters
long. The following table illustrates the components of the header
label.
+--------------------------------------------------------------------+
| BINARY Format Data File Header Label |
|--------------------------------------------------------------------|
| CHARACTERS | EXPLANATION |
|------------+-------------------------------------------------------|
| 1-26 | Fixed-length ASCII text: "GDS BINARY EXTRACT LEVEL |
| | 4". |
|------------+-------------------------------------------------------|
| 27-40 | Date and time of extract in the $ZDATE() format: |
| | "YEARMMDD2460SS". |
|------------+-------------------------------------------------------|
| 41-45 | Decimal maximum block size of the union of each |
| | region from which data was extracted. |
|------------+-------------------------------------------------------|
| 46-50 | Decimal maximum record size of the union of each |
| | region from which data was extracted. |
|------------+-------------------------------------------------------|
| 51-55 | Decimal maximum key size of the union of each region |
| | from which data was extracted. |
|------------+-------------------------------------------------------|
| | Space-padded label specified by the -LABEL qualifier. |
| 56-87 | For extracts in UTF-8 mode, GT.M prefixes UTF-8 and a |
| | space to -LABEL. The default LABEL is "GT.M MUPIP |
| | EXTRACT" |
+--------------------------------------------------------------------+
o GO - Global Output format, used for files to transport or archive.
-FORMAT=GO stores the data in record pairs. Each global node produces
one record for the key and one for the data. MUPIP EXTRACT -FORMAT=GO
has two header records - the first is a test label (refer to the LABEL
qualifier) and the second contains a data, and time.
o ZWR - ZWRITE format, used for files to transport or archive that may
contain non-graphical information. Each global node produces one
record with both key and data. MUPIP EXTRACT -FORMAT=ZWR has two
header records, which are the same as for FORMAT=GO, except that the
second record ends with the text " ZWR"
3 FReeze
FReeze
Prevents database updates to all database files from which the MUPIP
EXTRACT command is copying records. FREEZE ensures that a MUPIP EXTRACT
operation captures a "sharp" image of the globals, rather than one
"blurred" by updates occurring while the copy is in progress.
The format of the FREEZE qualifier is:
-FR[EEZE]
By default, MUPIP EXTRACT does not "freeze" regions during operation.
3 LAbel
LAbel
Specifies the text string that becomes the first record in the output
file. MUPIP EXTRACT -FORMAT=BINARY truncates the label text to 32
characters. The format of the LABEL qualifier is:
-LA[BEL]=text
o By default, EXTRACT uses the label "GT.M MUPIP EXTRACT."
o For more detailed information about the -FORMAT=BINARY header label,
refer to the description of EXTRACT -FORMAT=BINARY.
3 LOg
LOg
Displays a message on stdout for each global extracted with the MUPIP
EXTRACT command. The message displays the number of global nodes, the
maximum subscript length and maximum data length for each global. The
format of the LOG qualifier is:
-[NO]LO[G]
By default, EXTRACT operates -LOG.
3 Select
Select
Specifies globals for a MUPIP EXTRACT operation. The format of the SELECT
qualifier is:
-S[ELECT]= global-specification
o By default, EXTRACT selects all globals, as if it had the qualifier
-SELECT=*
o The caret symbol (^) in the specification of the global name is
optional.
The global-specification can be:
o A parenthetical list, such as (a,B,C). In this case, MUPIP EXTRACT
selects all globals except ^a, ^B, and ^C.
o A global name, such as MEF. In this case, MUPIP EXTRACT selects only
global ^MEF.
o A range of global names, such as A7:B6. In this case, MUPIP EXTRACT
selects all global names between ^A7 and ^B6, inclusive.
o A list, such as A,B,C. In this case, MUPIP EXTRACT selects globals ^A,
^B, and ^C.
o Global names with the same prefix, such as PIGEON*. In this case,
EXTRACT selects all global names from ^PIGEON through ^PIGEONzzzzz.
**Note**
If the rules for selection are complex, it may be easier to construct an
ad hoc Global Directory that maps the global variables to be extracted to
the database file. This may not be permissible if the database file is
part of a replicated instance. If this is the case, work with a backup of
the database.
3 STdout
STdout
Redirects database extract to the standard output stream. The format of
the STDOUT qualifier is:
-ST[DOUT]
3 Examples
Examples
Example:
$ mupip extract -format=go -freeze big.glo
This command prevents database updates during a MUPIP EXTRACT operation.
Example:
$ mupip extract -format=GO mumps_i.go
This command creates an extract file called mumps_i.go in "Global Output"
format. Use this format to transport or archive files. The first record of
a GO format file contains the header label, "GT.M MUPIP EXTRACT," as text.
Example:
$ mupip extract -format=BINARY v5.bin
This command creates an extract file called v5.bin in Binary format. Use
this format for reorganizing a database or for short-term backups.
Example:
$ mupip extract -format=ZWR -LABEL=My_Label My_Extract_File
This example extracts all globals from the current database to file
My_Extract_File (in ZWRITE format) with label My_Label.
Example:
$ mupip extract -nolog FL.GLO
This command creates a global output file, FL.GLO, (which consists of all
global variables in the database) without displaying statistics on a
global-by-global basis. As there is no label specified, the first record
in FL.GLO contains the text string "GT.M MUPIP EXTRACT."
Example:
$ mupip extract -select=Tyrannosaurus /dev/tty
This command instructs EXTRACT to dump the global ^Tyrannosaurus to the
device (file-name) /dev/tty.
2 FREEZE
FREEZE
Temporarily suspends (freezes) updates to the database. If you prefer a
non-GT.M utility to perform a backup or reorganization, you might use this
facility to provide standalone access to your GT.M database. You might use
MUPIP FREEZE to suspend (and later resume) database updates for creating
mirrored disk configuration or re-integrating a mirror.
GT.M BACKUP, INTEG, and REORG operations may implicitly freeze and
unfreeze database regions. However, for most operations, this
freeze/unfreeze happens internally and is transparent to the application.
The format of the MUPIP FREEZE command is:
F[REEZE] {-OF[F] [-OV[ERRIDE]]|-ON [-R[ECORD]]} region-list
o The region-list identifies the target of the FREEZE.
o MUPIP FREEZE waits for one minute so that concurrent KILL or MUPIP
REORG operations can complete. If the KILL or MUPIP REORG commands do
not complete within one minute, MUPIP FREEZE terminates operations and
unfreezes any regions it had previously marked as frozen.
o To ensure that a copy or reorganized version of a database file
contains a consistent set of records, concurrent MUPIP utilities, such
as BACKUP (without the ONLINE qualifier) and EXTRACT, include
mechanisms to ensure that the database does not change while the MUPIP
utility is performing an action. FIS recommends the use of the -ONLINE
qualifier with BACKUP.
o A MUPIP FREEZE can be removed only by the user who sets the FREEZE or
by using -OVERRIDE.
o After MUPIP FREEZE -ON, processes that are attempting updates "hang"
until the FREEZE is removed by the MUPIP FREEZE -OFF command or DSE.
Make sure that procedures for using MUPIP FREEZE, whether manual or
automated, include provisions for removing the FREEZE in all
appropriate cases, including when errors disrupt the normal flow.
o A -RECOVER/-ROLLBACK for a database reverts to a prior database update
state. Therefore, a -RECOVER/-ROLLBACK immediately after a MUPIP
FREEZE -ON removes the freeze. However, -RECOVER/-ROLLBACK does not
succeed if there are processes attached (for example when a process
attempt a database update immediately after a MUPP FREEZE -ON) to the
database.
FREEZE must include one of the qualifiers:
-OF[F]
-ON
The optional qualifiers are:
-OV[ERRIDE]
-R[ECORD]
3 OFf
OFf
Clears a freeze set by another process with the same userid.
The format of the OFF qualifier is:
OF[F]
o When used with -OVERRIDE, -OFF stops a freeze operation set by a
process with a different userid.
o Incompatible with: -ON, -RECORD
3 ON
ON
Specifies the start of a MUPIP FREEZE operation. The format of the ON
qualifier is:
-ON
Incompatible with: -OFF, -OVERRIDE
3 OVERRIDE
OVERRIDE
Release a freeze set by a process with a different userid. GT.M provides
OVERRIDE to allow error recovery in case a procedure with a freeze fails
to release. The format of the OVERRIDE qualifier is:
-OV[ERRIDE]
o OVERRIDE should not be necessary (and may even be dangerous) in most
schemes.
o Incompatible with: -ON, -RECORD
3 Record
Record
Specifies that a MUPIP FREEZE operation should record an event as a
reference point. You might use MUPIP FREEZE to set up your database for a
custom-backup mechanism (SAN or mirror-based).
The format of the RECORD qualifier is:
-R[ECORD]
o You might use -RECORD to integrate MUPIP BACKUP -BYTESTREAM with an
external backup mechanism.
o -RECORD replaces the previously RECORDed transaction identifier for
the database file.
o Incompatiable with: -OFF and -OVERRIDE.
3 Examples
Examples
Example:
$ mupip freeze -off DEFAULT
This command stops an ongoing MUPIP FREEZE operation on the region
DEFAULT.
Example:
$ mupip freeze -on "*"
This command prevents updates to all regions in the current Global
Directory.
Example:
$ set +e
$ mupip freeze -on -record "*"
$ tar cvf /dev/tape /prod/appl/*.dat
$ mupip freeze -off
$ set -e
The set +e command instructs the shell to attempt all commands in the
sequence , regardless of errors encountered by any command. This ensures
that the freeze -off is processed even if the tar command fails. FREEZE
prevents updates to all database files identified by the current Global
Directory. The -record qualifier specifies that the current transaction in
each database be stored in the RECORD portion of the database file header.
The tar command creates a tape archive file on the device /dev/tape,
containing all the files from /prod/app that have an extension of .dat.
Presumably all database files in the current Global Directory are stored
in that directory, with that extension. The second FREEZE command
re-enables updates that were suspended by the first FREEZE. The set -e
command re-enables normal error handling by the shell.
Example:
$ mupip freeze -override -off DEFAULT
This command unfreezes the DEFAULT region even if the freeze was set by a
process with a different userid.
2 FTOK
FTOK
Produces the "public" (system generated) IPC Keys (essentially hash
values) of a given file.
The format of the MUPIP FTOK command is:
FT[OK] [-DB] [-JNLPOOL] [-RECVPOOL] file-name
3 DB
DB
Specifies that the file-name is a database file. By default, MUPIP FTOK
uses -DB.
3 JNLPOOL
JNLPOOL
Specifies that the reported key is for the Journal Pool of the instance
created by the current Global Directory.
3 RECVPOOL
RECVPOOL
Specifies that the reported key is for the Receive Pool of the instance
created by the current Global Directory.
2 INTEG
INTEG
Performs an integrity check on a GT.M database file. You can perform
structural integrity checks on one or more regions in the current Global
Directory without bringing down (suspending database updates) your
application. However, a MUPIP INTEG on a single file database requires
standalone access but does not need a Global Directory. The order in which
the MUPIP INTEG command selects database regions is a function of file
system layout and may vary as files are moved or created. Execute a MUPIP
INTEG operations one database file at a time to generate an report where
the output always lists database files in a predictable sequence. For
example, to compare output with a reference file, run INTEG on one file at
a time.
Always use MUPIP INTEG in the following conditions:
o Periodically - to ensure ongoing integrity of the database(s); regular
INTEGs help detect any integrity problems before they spread and
extensively damage the database file.
o After a crash - to ensure the database was not corrupted. (Note: When
using before-image journaling, when the database is recovered from the
journal file after a crash, an integ is not required).
o When database errors are reported - to troubleshoot the problem.
Improving the logical and physical adjacency of global nodes may result in
faster disk I/O. A global node is logically adjacent when it is stored
within a span of contiguous serial block numbers. A global node is
physically adjacent when it resides on adjacent hard disk sectors in a way
that a single seek operation can access it. Database updates (SETs/KILLs)
over time affect the logical adjacency of global nodes. A MUPIP INTEG
reports the logical adjacency of your global nodes which may indicate
whether a MUPIP REORG could improve the database performance. A native
file system defragmentation improves physical adjacency.
**Note**
Most modern SAN and I/O devices often mask the performance impact of the
adjustments in logical and physical adjacency. If achieving a particular
performance benchmark is your goal, increasing the logical and physical
adjacency should be only one of many steps that you might undertake. While
designing the database, try to ensure that the logical adjacency is close
to the number of blocks that can physically reside on your hard disk's
cylinder. You can also choose two or three cylinders, with the assumption
that short seeks are fast.
The format of the INTEG command is:
I[NTEG]
[
-A[DJACENCY]=integer
-BL[OCK]=hexa;block-number
-BR[IEF]
-FA[ST]
-FU[LL]
-[NO]K[EYRANGES]
-[NO]MAP[=integer]
-[NO]MAXK[EYSIZE][=integer]
-S[UBSCRIPT]=subscript]
-TN[_RESET]
-[NO]TR[ANSACTION][=integer]
-[NO]O[NLINE]
]
{[-FILE] file-name|-REG[ION] region-name}
o MUPIP INTEG requires specification of either file(s) or region(s).
o Press <CTRL-C> to stop MUPIP INTEG before the process completes.
o The file-name identifies the database file for a MUPIP INTEG
operation.The region-list identifies one or more regions that, in
turn, identify database files through the current Global Directory.
o MUPIP INTEG operation keeps track of the number of blocks that do not
have the current block version during a non-fast integ (default or
full) and matches this value against the blocks to upgrade counter in
the file-header. It issues an error if the values are unmatched and
corrects the count in the file header if there are no other integrity
errors.
**Important**
Promptly analyze and fix all errors that MUPIP INTEG reports. Some errors
may be benign while others may be a signs of corruption or compromised
database integrity. If operations continue without fixes to serious
errors, the following problems may occur:
o Invalid application operation due to missing or incorrect data.
o Process errors, including inappropriate indefinite looping, when a
database access encounters an error.
o Degrading application level consistency as a result of incomplete
update sequences caused by the prior symptoms.
FIS strongly recommends fixing the following errors as soon as they are
discovered:
o Blocks incorrectly marked free - these may cause accelerating damage
when processes make updates to any part of the database region.
o Integrity errors in an index block - these may cause accelerating
damage when processes make updates to that area of the database region
using the faulty index.
MUPIP INTEG -FAST and the "regular" INTEG both report these errors (These
qualifiers are described later in this section). Other database errors do
not pose the threat of rapidly spreading problems in GDS files. After the
GT.M database repair, assess the type of damage, the risk of continued
operations, and the disruption in normal operation caused by the time
spent repairing the database. Contact your GT.M support channel for help
assessing INTEG errors.
The following sections describe the qualifiers of the INTEG command.
3 ADjacency
ADjacency
Specifies the logical adjacency of data blocks that MUPIP INTEG should
assume while diagnosing the database. By default, MUPIP INTEG operates
with -ADJACENCY=10 and reports the logical adjacency in the "Adjacent"
column of the MUPIP INTEG report.
o The complexity of contemporary disk controllers and the native file
system may render this report superfluous. But when it is meaningful,
this report measures the logical adjacency of data.
o A MUPIP REORG improves logical adjacency and a native file system
defragmentation improves physical adjacency.
The format of the ADJACENCY qualifier is:
-AD[JACENCY]=integer
3 BLock
BLock
Specifies the block for MUPIP INTEG command to start checking a sub-tree
of the database. MUPIP INTEG -BLOCK cannot detect "incorrectly marked busy
errors"
The format of the BLOCK qualifier is:
-BL[OCK]=block-number
o Block numbers are displayed in an INTEG error report or by using DSE.
o Incompatible with: -SUBSCRIPT and -TN_RESET
3 BRief
BRief
Displays a single summary report by database file of the total number of
directory, index and data blocks. The format of the BRIEF qualifier is:
-BR[IEF]
o By default, MUPIP INTEG uses the BRIEF qualifier.
o Incompatible with: -FULL
3 FAst
FAst
Checks only index blocks. FAST does not check data blocks.
The format of the FAST qualifier is:
-FA[ST]
o -FAST produces results significantly faster than a full INTEG because
the majority of blocks in a typical database are data blocks.
o While INTEG -FAST is not a replacement for a full INTEG, it very
quickly detects those errors that must be repaired immediately to
prevent accelerated database damage.
o By default, INTEG checks all active index and data blocks in the
database.
o Incompatible with: -TN_RESET.
3 FIle
FIle
Specifies the name of the database file for the MUPIP INTEG operation.
FILE requires exclusive (stand-alone) access to a database file and does
not require a Global Directory. The format of the FILE qualifier is:
-FI[LE]
o With stand-alone access to the file, MUPIP INTEG -FILE is able to
check whether the reference count is zero. A non-zero reference count
indicates prior abnormal termination of the database.
o The -FILE qualifier is incompatible with the -REGION qualifier.
o By default, INTEG operates on -FILE.
3 FUll
FUll
Displays an expanded report for a MUPIP INTEG operation. With -FULL
specified, MUPIP INTEG displays the number of index and data blocks in the
directory tree and in each global variable tree as well as the total
number of directory, index and data blocks. The format of the FULL
qualifier is:
-FU[LL]
o The -FULL qualifier is incompatible with the -BRIEF qualifier.
o By default, INTEG reports are -BRIEF.
o Use -FULL to have INTEG report all global names in a region or list of
regions.
3 Keyranges
Keyranges
Specify whether the MUPIP INTEG report includes key ranges that identify
the data suspected of problems it detects. The format of the KEYRANGES
qualifier is:
-[NO]K[EYRANGES]
By default, INTEG displays -KEYRANGES.
3 MAP
MAP
Specifies the maximum number of "incorrectly marked busy errors" that
MUPIP INTEG reports. The format of the MAP qualifier is:
-[NO]MAP[=max_imb_errors]
o <max_imb_errors> specifies the threshold limit for the number of
incorrectly marked busy errors.
o -NOMAP automatically sets a high threshold limit of 1000000 (1
million) incorrectly marked busy errors (-MAP=1000000).
o By default, INTEG reports a maximum of 10 map errors (-MAP=10).
**Note**
MUPIP INTEG reports "incorrectly marked free" errors as they require
prompt action. MAP does not restrict them.
An error in an index block prevents INTEG from processing potentially
large areas of the database. A single "primary" error may cause large
numbers of "secondary" incorrectly marked busy errors, which are actually
useful in identifying valid blocks that have no valid index pointer.
Because "real" or primary incorrectly marked busy errors only make "empty"
blocks unavailable to the system, they are low impact and do not require
immediate repair.
**Note**
After a database recovery with -RECOVER (for example, using -BEFORE_TIME)
or -ROLLBACK (for example, using -FETCHRESYNC), the database may contain
incorrectly marked busy errors. Although these errors are benign, they
consume available space. Schedule repairs on the next opportunity.
3 MAXkeysize
MAXkeysize
Specifies the maximum number of "key size too large" errors that a MUPIP
INTEG operation reports. The format of the MAXKEYSIZE qualifier is:
-[NO]MAX[KEYSIZE][=integer]
o By default, INTEG reports a maximum of 10 key size errors (-
MAXKEYSIZE=10).
o -NOMAXKEYSIZE removes limits on key size reporting so that INTEG
reports all key size too large errors.
o -NOMAXKEYSIZE does not accept assignment of an argument.
o "Key size too large" errors normally occur only if a DSE CHANGE
-FILEHEADER -KEY_MAX_SIZE command reduces the maximum key size.
3 Online
Online
Specifies that while a MUPIP INTEG operation is active, other processes
can update the database without affecting the result of the backup. Allows
checking database structural integrity to run concurrently with database
updates. The format of the ONLINE qualifier is:
-[NO]O[NLINE]
o -NOONLINE specifies that the database should be frozen during MUPIP
INTEG.
o By default, MUPIP INTEG is online except for databases containing V4
blocks for which the default is -NOONLINE. Note that databases
containing V4 blocks should exist only in databases that are in the
process of being migrated from V4 to V5; please complete your
migration to the V5 format before using MUPIP INTEG -ONLINE.
o Since MUPIP INTEG -ONLINE does not freeze database updates, it cannot
safely correct errors in the "blocks to upgrade" and "free blocks"
fields in the file header, while MUPIP INTEG -NOONLINE can correct
these fields.
o As it checks each database file, MUPIP INTEG -ONLINE creates a sparse
file of the same size as the database. As each GT.M process updates
the database, it places a copy of the old block in the sparse file
before updating the database. For any database blocks with a newer
transaction number than the start of the INTEG, MUPIP uses the copy in
the sparse file. Thus, analogous with MUPIP BACKUP -ONLINE, INTEG
reports on the state of the database as of when it starts, not as of
when it completes. Note: a command such as ls -l command shows sparse
files at their full size, but does not show actual disk usage. Use a
command such as du -sh to see actual disk usage.
o The environment variable GTM_BAKTMPDIR (unlike most GT.M environment
variables, this is upper case; it is the same directory used for MUPIP
BACKUP -ONLINE) can be used to indicate a directory where MUPIP should
place the snapshot files (used by MUPIP INTEG -ONLINE). If
GTM_BAKTMPDIR does not exist, MUPIP places the snapshot files in the
current directory at the time you issue the INTEG command. MUPIP and
GT.M processes automatically cleans up these temporary snapshot files
under a wider variety of conditions.
o Temporary directory security settings must allow write access by the
the MUPIP process and read access by all processes updating the
database. MUPIP creates the temporary file with the same access as the
database file so processes updating the database can write to the
temporary file. If the database is encrypted, the updating processes
write encrypted blocks to the snapshot file and the MUPIP INTEG
process must start with access to appropriate key information as it
does even -NOONLINE.
o MUPIP INTEG -NOONLINE [-FAST] {-REGION|-FILE} clears the KILLs in
progress and Abandoned Kills flags if the run includes the entire
database and there are no incorrectly marked busy blocks.
o Only one online integ can be active per database region. If an online
integ is already active, a subsequent one issues an error and
immediately terminates. If an online integ does not successfully
complete, GT.M cleans it up in one of the following ways:
o A subsequent online integ detects that an earlier one did not
successfully complete and releases the resources held by the
prior online integ before proceeding.
o If a MUPIP STOP was issued to the online integ process, the
process cleans up any resources it held. Note: since the process
was stopped the results of the integ may not be valid.
o subsequent MUPIP RUNDOWN ensures the release of resources held by
prior unsuccessful online integs for the specified regions.
o For every 64K transactions after the online integ initiation,
online integ checks GT.M health for improperly abandoned online
integs and releases resources held by any it finds.
o Incompatible with: -FILE, -TN_RESET (there should be no need to use
-TN_RESET on a GT.M V5 database).
3 Region
Region
Specifies that the INTEG parameter identifies one or more regions rather
than a database file. The format of the REGION qualifier is:
-R[EGION]
o MUPIP INTEG -REGION does not require stand alone access to databases.
Instead, it freezes updates (but not reads) to the database during the
check. The region-list argument may specify more than one region of
the current Global Directory in a list separated with commas. INTEG
-REGION requires the environment variable gtmgbldir to specify a valid
Global Directory. For more information on defining gtmgbldir, refer to
the "Global Directory Editor" chapter.
o Because a KILL may briefly defer marking the blocks it releases "free"
in the bit maps, INTEG -REGION may report spurious block incorrectly
marked busy errors. These errors are benign. If these errors occur in
conjunction with a "Kill in progress" error, resolve the errors after
the "Kill in progress" error is no longer present.
o By default, INTEG operates -FILE.
o Incompatible with: -FILE, -TN_RESET
3 Subscript
Subscript
Specifies a global or a range of keys to INTEG. The global key may be
enclosed in quotation marks (" "). Identify a range by separating two
subscripts with a colon (:). -SUBSCRIPT cannot detect incorrectly marked
busy errors. The format of the SUBSCRIPT qualifier is:
-S[UBSCRIPT]=subscript
Specify SUBSCRIPT only if the path to the keys in the subscript is not
damaged. If the path is questionable or known to be damaged, use DSE to
find the block(s) and INTEG -BLOCK.
Incompatible with: -BLOCK, -TN_RESET
3 TN_reset
TN_reset
Resets block transaction numbers and backup event recorded transaction
numbers to (one) 1, and the current transaction number to two (2) which
makes the backup event recorded transaction numbers more meaningful and
useful. It also issues an advisory message to perform a backup.
The format of the TN_RESET qualifier is:
-TN[_RESET]
o Transaction numbers can go up to 18,446,744,073,709,551,615. This
means that a transaction processing application that runs flat out at
a non-stop rate of 1,000,000 updates per second would need a TN reset
approximately every 584,554 years.
o The -TN_RESET qualifier rewrites all blocks holding data. If the
transaction overflow resets to zero (0) database operation is
disrupted.
o The -TN_RESET qualifier is a protective mechanism that prevents the
transaction overflow from resetting to 0.
o By default, INTEG does not modify the block transaction numbers.
**Important**
There should never be a need for a -TN_RESET on a database with only
V5 blocks, even when cleaning up after a runaway process.
o The -TN_RESET qualifier is incompatible with the -FAST, -BLOCK,
-REGION, and -SUBSCRIPT qualifiers.
**Note**
Any time a GT.M update opens a database file that was not properly closed,
GT.M increments the transaction number by 1000. This automatic increment
prevents problems induced by abnormal database closes, but users must
always consider this factor in their operational procedures. The rate at
which GT.M "uses up" transaction numbers is a function of operational
procedures and real database updates.
3 TRansaction
TRansaction
Specifies the maximum number of block transaction- number-too-large errors
that MUPIP INTEG reports. The format of the TRANSACTION qualifier is:
-[NO]TR[ANSACTION][=integer]
o -NOTRANSACTION removes limits on transaction reporting so MUPIP INTEG
reports all transaction number errors.
o -NOTRANSACTION does not accept assignment of an argument.
o A system crash may generate many "block transaction number too large"
errors. These errors can cause problems for BACKUP -INCREMENTAL and
for transaction processing. Normally, the automatic increment of 1000
blocks that GT.M adds when a database is reopened averts these errors.
If a problem still exists after the database is reopened, users can
use a value in the DSE CHANGE -FILEHEADER -CURRENT_TN= command to
quickly fix "block transaction number too large number" errors.
o By default, INTEG reports a maximum of 10 block transaction errors
(-TRANSACTION=10).
3 Examples
Examples
Example:
$ mupip integ -block=4 mumps.dat
This command performs a MUPIP INTEG operation on the BLOCK 4 of mumps.dat.
Example:
$ mupip integ -adjacency=20
A sample output from the above command follows:
Type Blocks Records % Used Adjacent
Directory 2 5 4.150 NA
Index 18 1151 77.018 1
Data 1137 94189 97.894 1030
Free 43 NA NA NA
Total 1200 95345 NA 1031
This example performs a MUPIP INTEG operation assuming that logically
related data occupies 20 data blocks in the current database. The sample
output shows that out of 1137 data blocks, 1030 data blocks are adjacent
to each other. One can improve the performance of a database if the all
blocks are as adjacent as possible.
Example:
$ mupip integ -brief mumps.dat
This command performs a MUPIP INTEG operation on the database mumps.dat. A
sample output from the above command follows:
No errors detected by integ.
Type Blocks Records % Used Adjacent
Directory 2 2 2.490 NA
Index 1 1 2.343 1
Data 1 3 6.738 1
Free 96 NA NA NA
Total 100 6 NA 2
Example:
$ mupip integ -fast mumps.dat
This command performs a MUPIP INTEG operation only on the index block of
the database file mumps.dat. A sample output from the above command
follows:
No errors detected by fast integ.
Type Blocks Records % Used Adjacent
Directory 2 2 2.490 NA
Index 1 1 2.343 1
Data 1 NA NA NA
Free 96 NA NA NA
Total 100 NA NA 1
Note the NA entries (highlighted in bold) for Data type. It means that the
MUPIP INTEG -FAST operation checked only index blocks.
$ mupip integ -full mumps.dat
The sample output from the above command follows:
Directory tree
Level Blocks Records % Used Adjacent
1 1 1 2.343 NA
0 1 1 2.636 NA
Global variable ^Dinosaur
Level Blocks Records % Used Adjacent
1 1 6 8.398 1
0 6 500 83.902 6
No errors detected by integ.
Type Blocks Records % Used Adjacent
Directory 2 2 2.490 NA
Index 1 6 8.398 1
Data 6 500 83.902 6
Free 91 NA NA NA
Total 100 508 NA 7
Example:
$ mupip integ -map=20 -maxkeysize=20 -transaction=2 mumps.dat
This command performs a MUPIP INTEG operation and restricts the maximum
number of "key size too large" errors to 20.
Example:
$ mupip integ -map=20 -transaction=2 mumps.dat
This command performs a MUPIP INTEG operation and restricts the maximum
number of "block transaction- number-too-large errors" to 2.
$ mupip integ -file mumps.dat -tn_reset
This command resets the transaction number to one in every database block.
Example:
$ mupip integ -subscript="^Parrots" mumps.dat
This example performs a MUPIP INTEG operation on the global variable
^Parrots in the database file mumps.dat.
Example:
$ mupip integ -subscript="^Amsterdam(100)":"^Bolivia(""Chimes"")" -region DEFAULT
This example performs a MUPIP INTEG operation all global variables greater
than or equal to ^Amsterdam (100) and less than or equal to
^Bolivia("Chimes") in the default region(s).
**Note**
To specify a literal in the command string, use two double quotation marks
for example, ^b(""c"").
2 INTRPT
INTRPT
Sends an interrupt signal to the specified process. The signal used is
[POSIX] SIGUSR1. The format of the MUPIP INTRPT command is:
INTRPT process-id
**Important**
Ensure that signal SIGUSR1 is not be used by any C external function calls
or any (initially non-GT.M) processes that use call-in support, as it is
interpreted by GT.M as a signal to trigger the $ZINTERRUPT mechanism.
o To INTRPT a process belonging to its own account, a process requires
no UNIX privilege.
o To INTRPT a process belonging to its own GROUP, a process requires
UNIX membership in the user group of the target process privilege. To
INTRPT a process belonging to an account outside its own GROUP, a
process requires UNIX superuser privilege.
2 LOAD
LOAD
Puts the global variable names and their corresponding data values into a
GT.M database from a sequential file.
The format of the LOAD command is:
L[OAD]
[
-BE[GIN]=integer
-E[ND]=integer
-FI[LLFACTOR]=integer
-FO[RMAT]={GO|B[INARY]|Z[WR]]}
-S[TDIN]
]
file-name
**Caution**
From an application perspective, performing a MUPIP LOAD operation while
an application is running may result in an inconsistent application state
for the database.
o MUPIP LOAD uses the Global Directory to determine which database files
to use.
o LOAD supports user collation routines.
o LOAD takes its input from the file defined by the file-name
o LOAD may take its input from a UNIX file on any device that supports
such files.
o MUPIP LOAD command considers a sequential file as encoded in UTF-8 if
the environment variable gtm_chset is set to UTF-8. Ensure that MUPIP
EXTRACT commands and corresponding MUPIP LOAD commands execute with
the same setting for the environment variable gtm_chset.
o For information on loading with an M "percent utility," refer to the
%GI section of the "M Utility Routines" chapter in GT.M Programmer's
Guide. LOAD is typically faster, but the %GI utility can be
customized.
o Press <CTRL-C> to produce a status message from LOAD. Entering
<CTRL-C> twice in quick succession stops LOAD. A LOAD that is manually
stopped or stops because of an internal error is incomplete and may
lack application level integrity, but will not adversely affect the
database structure unless terminated with a kill -9.
**Note**
The MUPIP EXTRACT or MUPIP LOAD procedure for large databases are time
consuming due to the volume of data that has to be converted from binary
to ZWR format (on source) and vice versa (on target). One must also
consider the fact that the extract file can be very large for a large
database. Users must ensure adequate storage support the size of the
extract file and the space occupied by the source and target databases. In
order to reduce the total time and space it takes to transfer database
content from one endian platform to another, it is efficient to convert
the endian format in-place for a database and transfer the converted
database. See MUPIP ENDIANCVT for more information on converting the
endian format of a database file.
The following sections describe the optional qualifiers of the MUPIP LOAD
command.
3 FOrmat
FOrmat
Specifies the format of the input file. The format must match the actual
format of the input file for LOAD to operate.
The format codes are:
GO - Global Output format
B[INARY] - Binary format
Z[WR] - ZWRITE format
o By default, LOAD uses FORMAT=ZWR.
o -FORMAT=GO expects the data in record pairs. Each global node requires
one record for the key and one for the data.
o -FORMAT=ZWR expects the data for each global node in a single record.
o -FORMAT=BINARY only applies to Greystone Database Structure (GDS)
files. A BINARY format file loads significantly faster than a GO or
ZWR format file. -FORMAT=BINARY works with data in a proprietary
format. -FORMAT=BINARY has one header record, therefore LOAD
-FORMAT=BINARY starts active work with record number two (2).
3 BEgin
BEgin
Specifies the record number of the input file with which LOAD should
begin. Directing LOAD to begin at a point other than the beginning of a
valid key causes an error. The format of the BEGIN qualifier is:
-BE[GIN]=integer
**Important**
Always consider the number of header records for choosing a -BEGIN point.
See FORMAT qualifier for more information.
o For -FORMAT=GO input, the value is usually an odd number. As
-FORMAT=BINARY requires important information from the header, this
type of load requires an intact file header regardless of the -BEGIN
value.
o For -FORMAT = ZWR input, each record contains a complete set of
reference and data information. The beginning values are not
restricted, except to allow two records for the header.
o By default, LOAD starts at the beginning of the input file.
3 End
End
Specifies the record number of the input file at which LOAD should stop.
-END=integer must be greater than the -BEGIN=integer for LOAD to operate.
LOAD terminates after processing the record of the number specified by
-END or reaching the end of the input file. The format of the END
qualifier is:
-E[ND]=integer
The value of -FORMAT=GO input should normally be an even number. By
default, LOAD continues to the end of the input file.
3 FIll_factor
FIll_factor
Specifies the quantity of data stored in a database block. Subsequent
run-time updates to the block fill the remaining available space reserved
by the FILL_FACTOR. Blocks that avoid block splits operate more
efficiently. The format of the FILL_FACTOR qualifier is:
-FI[LL_FACTOR]=integer
o Reserves room and avoid unnecessary block split to accommodate the
forecasted growth in a global variable that may experience significant
rate of additions over a period.
o Users having database performance issues or a high rate of database
updates must examine the defined FILL_FACTORs. Unless the application
only uses uniform records, which is not typical for most applications,
FILL_FACTORs do not work precisely.
o By default, LOAD uses -FILL_FACTOR=100 for maximum data density.
**Note**
FILL_FACTOR is useful when updates add or grow records reasonably
uniformly across a broad key range. If updates are at ever ascending or
descending keys, or if the record set and record sizes are relatively
static in the face of updates, FILL_FACTOR won't provide much benefit.
3 Stdin
Stdin
Specifies that MUPIP LOAD takes input from standard input (stdin). The
format of the STDIN qualifier is:
-S[TDIN]
3 Examples
Examples
Example:
$ mupip load ex_file.go
This command loads the content of the extract file ex_file.go to the
current database.
Example:
$ mupip load -format=go big.glo
This command loads an extract file big.glo in the current database.
Example:
$ mupip load -begin=5 -end=10 rs.glo
This command begins MUPIP LOAD operation from record number 5 and ends at
record number 10. Note that the value for BEGIN is an odd number. A sample
output from the above command follows:
GT.M MUPIP EXTRACT
02-MAR-2011 18:25:47 ZWR
Beginning LOAD at record number: 5
LOAD TOTAL Key Cnt: 6 Max Subsc Len: 7 Max Data Len: 1
Last LOAD record number: 10
Example:
$ mupip load -fill_factor=5 reobs.glo
This command set the FILL_FACTOR to 5 for loading an extract file in the
current database.
Example:
$cat big.glo | mupip load -stdin
$mupip load -stdin < big.glo
These commands loads the extract file big.glo using -stdin.
2 REORG
REORG
Improves database performance by defragmenting and reorganizing database
files and attempts to reduce the size of the database file. MUPIP REORG
runs concurrently with other database activity, including updates.
Competing activity generally increases the time required to perform a
REORG, as well as that of the competing operations.
The format of the REORG command is:
REO[RG]
[
-D[OWNGRADE]
-E[XCLUDE]=global-name-list
-FI[LL_FACTOR]=integer
-I[NDEX_FILL_FACTOR]=integer
-R[ESUME]
-SAFEJNL
-S[ELECT]=global-name-list
-STA[RTBLK]=hexa
-STO[PBLK]=hexa
-T[RUNCATE][=percentage]
-UP[GRADE]
-US[ER_DEFINED_REORG]=reorg_list
-REG[ION]=region-list
]
**Note**
While REORG optimizes the GDS structure of database files, it does not
handle native file system file fragmentation. In most cases, fragmentation
at the native file system level is more likely than fragmentation at the
GDS structure level. Therefore, FIS recommends users create files with
appropriate allocations and extensions, on disks with large amounts of
contiguous free space. Use native utilities and MUPIP utilities (depending
on operational procedures) to eliminate file fragmentation when database
files have been extended more than a dozen times.
o Using REORG concurrently with normal database access affects the
performance of normal operation. To reduce this impact, lower the
priority of the process performing the REORG.
o MUPIP REORG does not change the logical contents of the database, and
can run on either the originating instance or replicating instance of
an LMS application. In such cases, resuming REORGs in process should
be part of the batch restart. See "GT.M Database Replication" chapter
for more information about running REORG on a dual site application.
o If you run MUPIP STOP for an ongoing MUPIP REORG process, it may leave
the database blocks in an inconsistent state. In this situation, GT.M
converts the ongoing KILLs flag to abandoned KILLs flag. If a
subsequent MUPIP REORG encounters these abandoned KILLs flags, it
gives a message and then starts its REORG actions.
o <CTRL-C> terminates REORG. A REORG terminated abnormally by operator
action or error is incomplete but does not adversely affect the
database structure, unless terminated with a kill -9.
Assume two scenarios of putting values of ^x(1) to ^x(10000). In the first
scenarios, fill values in a sequential manner. In the second scenario,
enter values for odd subscripts and then enter values for the even
subscripts.
Scenario 1:
At the GT.M prompt, execute the following command sequence:
GTM>for i=1:1:10000 set ^x(i)=$justify(i,200)
Then, execute the following MUPIP INTEG command.
$ mupip integ -region "*"
This command produces an output like the following:
Integ of region DEFAULT
No errors detected by integ.
Type Blocks Records % Used Adjacent
Directory 2 2 2.490 NA
Index 29 2528 95.999 1
Data 2500 10000 82.811 2499
Free 69 NA NA NA
Total 2600 12530 NA 2500
Note the high density (percent used) for index and data blocks from the
report.
Scenario 2:
At the GT.M prompt, execute the following command sequence:
GTM>for i=1:2:10000 s ^x(i)=$justify(i,200)
GTM>for i=2:2:10000 set ^x(i)=$justify(i,200)
Then, execute the following command:
$ mupip integ -region "*"
This command produces an output like the following:
Integ of region DEFAULT
No errors detected by integ.
Type Blocks Records % Used Adjacent
Directory 2 2 2.490 NA
Index 153 3902 29.211 57
Data 3750 10000 55.856 1250
Free 95 NA NA NA
Total 4000 13904 NA 1307
Note that there are more and less dense index and data blocks used than in
scenario 1. MUPIP REORG addresses such issues and makes the database
(depending on the FILL_FACTOR) more compact.
The optional qualifiers for MUPIP REORG are:
3 Exclude
Exclude
Specifies that REORG not handle blocks that contain information about the
globals in the associated list-this means they are neither reorganized nor
swapped in the course of reorganizing other globals; -EXCLUDE can reduce
the efficiency of REORG because it complicates and interferes with the
block swapping actions that try to improve adjacency.
The format of the EXCLUDE qualifier is:
-E[XCLUDE]=global-name-list
o Assume that a single MUPIP command organizes a subset of the globals
in a database or region. If a second MUPIP REORG command selects the
remaining globals, it may tend to disrupt the results of the first
REORG by de-optimizing the previously organized blocks. This is
because there is no information passed from the previous MUPIP REORG
command to the next command. The EXCLUDE qualifier allows users to
list the name of the previously REORGed globals, so that the MUPIP
REORG bypasses the GDS blocks containing these globals.
o If global-name-list contains globals that do not exist, REORG issues a
message to the terminal and continues to process any specified globals
that exist. If REORG is unable to process any globals, it terminates
with an error.
o Global-name-list can be an individual global name, a range of global
names, or a list of names and prefixes followed by the wildcard
symbol. For example:
1. A global name, such as ACN.
2. A range of global names, such as A7:B7.
3. A list, such as A,B,C.
4. Global names with the same prefix such as TMP*.
In the first case, REORG only excludes global ^ACN. In the second case,
REORG excludes all global names in the collating sequence A7 to B7. For
the third case, REORG excludes A, B, and C. In the last case, REORG
excludes all globals prefixed with TMP.
o Enclose wildcards in double-quotes ("") to prevent inappropriate
expansion by the shell. The caret symbol (^) in the specification of
the global is optional.
o By default, REORG does not EXCLUDE any globals.
o In case any global appears in the argument lists of both -SELECT and
-EXCLUDE, REORG terminates with an error.
3 Fill_factor
Fill_factor
Specifies how full you want each database block to be. This is a target
number. Individual blocks may be more or less full than the fill factor.
The format of the FILL_FACTOR qualifier is:
F[ILL_FACTOR]=integer
o The arguments for the FILL_FACTOR qualifier must be integers from 30
to 100. These integers represent the percentage of the data block that
REORG can fill. By default, the FILL_FACTOR value is 100 for maximum
data density.
o Users who come upon database performance issues or a high rate of
database updates must examine the defined FILL_FACTORs. Unless the
application uses entirely uniform records, which is not typical for
most applications, FILL_FACTORs do not work precisely.
o The FILL_FACTOR for data that is relatively static, or grows by the
addition of new nodes that collate before or after pre-existing nodes,
should be 100 percent. The FILL_FACTOR for data that is growing by
additions to existing nodes may be chosen to leave room in the typical
node for the forecast growth for some period. Generally, this is the
time between the LOAD and first REORG, or between two REORGs. This is
also true for additions of nodes that are internal to the existing
collating sequence.
3 Index_fill_factor
Index_fill_factor
Directs REORG to leave free space within index blocks for future updates.
Arguments to this qualifier must be integers from 30 to 100 that represent
the percentage of the index block that REORG can fill. REORG uses this
number to decide whether to place more information in an index block, or
create space by moving data to another block. The format of the
INDEX_FILL_FACTOR qualifier is:
-I[NDEX_FILL_FACTOR]=integer
Under certain conditions, especially with large database block sizes, it
may be possible to achieve faster throughput by using a smaller fill
factor for index blocks than for data blocks. By default, the
INDEX_FILL_FACTOR is the value of FILL_FACTOR regardless of whether that
value is explicitly specified or implicitly obtained by default.
3 Resume
Resume
For an interrupted REORG operation, -RESUME allows the user to resume the
REORG operation from the point where the operation stopped. REORG stores
the last key value in the database file header. The format of the RESUME
qualifier is:
-R[ESUME]
o With RESUME specified, the program retrieves the last key value, from
the database file header, and restarts operations from that key.
3 Region
Region
Specifies that REORG operate in the regions in the associated list and
restricts REORG to the globals in those regions that are mapped by the
current global directory; it does not have the same interactions as
-EXCLUDE and -SELECT, but it does not mitigate those interactions when
combined with them.
The format of the REGION qualifier is:
-R[EGION]=region-list
3 Select
Select
Specifies that REORG reorganizes only the globals in the associated list;
globals not on the list may be modified by block swaps with selected
globals unless they are named with -EXCLUDE; -SELECT can be difficult to
use efficiently because it tends to deoptimize unselected globals unless
they are name in an -EXCLUDE list (which introduces inefficiency).
The format of the SELECT qualifier is:
-S[ELECT]=global-name-list
o By default, REORG operates on all globals in all database files
identified by the current Global Directory for the process executing
the MUPIP command.
o One of the functions performed by REORG is to logically order the
globals on which it operates within the file. Unless the EXCLUDE and
SELECT qualifiers are properly used in tandem, repeating the command
with different selections in the same file wastes work and leaves only
the last selection well organized.
o If you enter the REORG -SELECT=global-name-list command and the
specified globals do not exist, REORG issues a message to the screen
and continues to process any specified globals that exist. If REORG is
unable to process any globals, it terminates with an error.
o Arguments for this qualifier may be an individual global name, a range
of global names, or a list of names and prefixes followed by the
wildcard symbol. The caret symbol (^) in the specification of the
global is optional.
o The global name can be:
1. A global name, such as ACN
2. A range of global names, such as A7:B7
3. A list, such as A,B,C.
4. Global names with the same prefix such as TMP*.
o In the first case, REORG only includes global ^ACN. In the second
case, REORG includes all global names in the collating sequence A7 to
B7. For the third case, REORG includes A, B, and C. In the last case,
REORG includes all globals prefixed with TMP.
o By default, REORG selects all globals.
3 Truncate
Truncate
Specifies that REORG, after it has rearranged some or all of a region's
contents, should attempt to reduce the size of the database file and
return free space to the file system. The format of the TRUNCATE qualifier
is:
-T[RUNCATE][=percentage]
The optional percentage (0-99) provides a minimum amount for the
reclamation; in other words, REORG won't bother performing a file truncate
unless it can give back at least this percentage of the file; the default
(0) has it give back anything it can. TRUNCATE always returns space
aligned with bit map boundaries, which fall at 512 database block
intervals. TRUNCATE analyses the bit maps, and if appropriate, produces
before image journal records as needed for recycled (formerly used)
blocks; The journal extract of a truncated database file may contain INCTN
records having the inctn opcode value 9 indicating that the specific block
was marked from recycled to free by truncate.
**Note**
TRUNCATE does not complete if there is a concurrent online BACKUP or use
of the snapshot mechanism, for example by INTEG.
3 Examples
Examples
Example:
$ mupip reorg -exclude="^b2a,^A4gsEQ2e:^A93"
This example performs a MUPIP REORG operation on all globals excluding
^b2a and all globals ranging from ^A4gsEQ2e to ^A93.
Example:
If the forecasted growth of a global is 5% per month from relatively
uniformly distributed updates, and REORGs are scheduled every quarter, the
FILL_FACTOR for both the original LOAD and subsequent REORGs might be 80
percent 100 - ((3 months + 1 month "safety" margin) * five percent per
month). The REORG command based on the above assumptions is as follows:
$ mupip reorg -fill_factor=80
2 RESTORE
RESTORE
Integrates one or more BACKUP -INCREMENTAL files into a corresponding
database. The transaction number in the first incremental backup must be
one more than the current transaction number of the database. Otherwise,
MUPIP RESTORE terminates with an error.
The format of the RESTORE command is:
RE[STORE] [-[NO]E[XTEND]] file-name file-list
o file-name identifies the name of the database file that RESTORE uses
as a starting point.
o file-list specifies one or more files produced by BACKUP -INCREMENTAL
to RESTORE into the database. The file-name are separated by commas
(,) and must be in sequential order, from the oldest transaction
number to the most recent transaction number. RESTORE may take its
input from a UNIX file on any device that supports such files.
o The current transaction number in the database must match the starting
transaction number of each successive input to the RESTORE.
o If the BACKUP -INCREMENTAL was created using -TRANSACTION=1, create a
new database with MUPIP CREATE and do not access it, except the
standalone MUPIP commands INTEG -FILE, EXTEND, and SET before
initiating the RESTORE.
3 Extend
Extend
Specifies whether a MUPIP RESTORE operation should extend the database
file automatically if it is smaller than the size required to load the
data.
The format of the EXTEND qualifier is:
-[NO]E[XTEND]
M activity between backups may automatically extend a database file.
Therefore, the database file specified as the starting point for a RESTORE
may require an extension before the RESTORE. If the database needs an
extension and the command specifies -NOEXTEND, MUPIP displays a message
and terminates. The message provides the sizes of the input and output
database files and the number of blocks by which to extend the database.
If the RESTORE specifies more than one incremental backup with a file
list, the database file may require more than one extension.
By default, RESTORE automatically extends the database file.
3 Examples
Examples
$ mupip restore backup.dat $backup_dir/backup.bk1, $backup_dir/backup.bk2, $backup_dir/backup.bk3
This command restores backup.dat from incremental backups stored in
directory specified by the environment variable backup_dir.
$ mupip restore gtm.dat '"gzip -d -c online5pipe.inc.gz |"'
This command uses a pipe to restore gtm.dat since its last DATABASE backup
from the bytestream backup stored in online5pipe.inc.gz.
2 RUNDOWN
RUNDOWN
When database access has not been properly terminated, RUNDOWN properly
closes currently inactive databases, removes abandoned GT.M database
semaphores, and releases any IPC resources used. Under normal operations,
the last process to close a database file performs the RUNDOWN actions,
and a MUPIP RUNDOWN is not required. If a database file is already
properly rundown, a MUPIP RUNDOWN has no effect. If in doubt, it is always
to safe to perform a rundown. FIS recommends the following method to
shutdown a GT.M application or the system:
o Terminate all GT.M processes, and
o Rundown any and all database files that may be active.
MUPIP RUNDOWN checks for version mismatch. If there is a mismatch, it
skips the region and continues with the next region. This makes it easier
for multiple (non-interacting) GT.M versions to co-exist on the same
machine. Note that GT.M does not support concurrent access to the same
database file by multiple versions of the software.
The format of the RUNDOWN command is:
RU[NDOWN] {-FILE file-name|-REGION region-list]}
MUPIP RUNDOWN clears certain fields in a file that is already closed. This
facilitates recovery from a system crash or other operational anomaly.
Use RUNDOWN after a system crash or after the last process accessing a
database terminates abnormally. RUNDOWN ensures that open databases are
properly closed and ready for subsequent use. RUNDOWN has no effect on any
database that is actively being accessed at the time the RUNDOWN is
issued.
To ensure database integrity, all system shutdown algorithms should
include scripts that stop at GT.M processes and perform RUNDOWN on all
database files.
The RUNDOWN command may include one of the following qualifiers:
-F[ile]
-R[egion]
If the RUNDOWN command does not specify either -File or -Region, it checks
all the IPC resources (shared memory) on the system and if they are
associated with a GT.M database, attempts to rundown that file.
3 File
File
Specifies that the argument is a file-name for a single database file. The
-FILE qualifier is incompatible with the REGION qualifier. If the rundown
parameter consists of a list of files, the command only operates on the
first item in the list.
Incompatible with: -REGION
3 Region
Region
Specifies that the argument contains one or more region-names that
identify database files mapped by the current Global Directory. Use the
wild card "*" to rundown all inactive regions in a global directory.
Incompatible with: -FILE
When MUPIP RUNDOWN has no qualifier, it performs rundown on all inactive
database memory sections on the node. Because this form has no explicit
list of databases, it does not perform any clean up on regions that have
no abandoned memory segments but may not have been shutdown in a crash.
2 SET
SET
Modifies certain database characteristics. MUPIP SET operates on either
regions or files.
**Note**
In regions that have journaling enabled and on, users can switch journal
files without either requiring standalone access or freezing updates.
The format of the SET command is:
SE[T] {-FI[LE] file-name|-REG[ION] region-list}
-A[CCESS_METHOD]={BG|MM}
-B[YPASS]
-DE[FER_TIME]=seconds
-E[XTENSION_COUNT]=integer(no of blocks)
-F[LUSH_TIME]=integer
-G[LOBAL_BUFFERS]=<integer>
-JN[LFILE]
-JO[URNAL]=journal-option-list
-L[OCK_SPACE]=integer
-[NO]INST[_FREEZE_ON_ERROR]
-PA[RTIAL_RECOV_BYPASS]
-REP[LICATION]={ON|OFF}
-RES[ERVED_BYTES]=integer]
-S[TANDALONENOT]
-V[ERSION]={V4|V6}
-W[AIT_DISK]=integer
o The file-name (or region-list) identifies the target of the SET.
o The SET command must include one of the following qualifiers which
determine whether the argument to the SET is a file-name or a
region-list.
o Exclusive access to the database is required if the MUPIP SET command
specifies -ACCESS_METHOD, -GLOBAL_BUFFERS, -LOCK_SPACE or -NOJOURNAL,
or if any of the -JOURNAL options ENABLE, DISABLE, or BUFFER_SIZE are
specified.
The following section describe the qualifiers of the MUPIP SET command.
3 Access_method
Access_method
Specifies the access method (GT.M buffering strategy) for storing and
retrieving data from the global database file. The format of the
ACCESS_METHOD qualifier is:
-A[CCESS_METHOD]=code
3 PArtial_recov_bypass
PArtial_recov_bypass
Sets the CORRUPT_FILE flag in the database fileheader to FALSE. The
CORRUPT_FILE flag indicates whether a region completed a successful
recovery.
3 File
File
Specifies that the argument is a file-name for a single database file. The
format of the FILE qualifier is:
-F[ILE]
Incompatible with: -REGION
3 Region
Region
Specifies that the argument is a region-list which identifies database
file(s) mapped by the current Global Directory. The format of the REGION
qualifier is:
-R[EGION]
SET -REGION changes multiple files when the parameter contains a list
and/or wildcards.
Incompatible with: -FILE
3 Extension_count
Extension_count
Specifies the number of GDS blocks by which an existing database file
extends. A file or region name is required. This qualifier requires
standalone access.
The format of the EXTENSION_COUNT qualifier is:
-E[XTENSION_COUNT]=integer
3 Flush_time
Flush_time
Specifies the amount of time between deferred writes of stale cache
buffers. The default value is 1 second and the maximum value is 1 hour.
-FLUSH_TIME requires standalone access. The format of the FLUSH_TIME
qualifier is:
-F[LUSH_TIME]=[[[HOURS:]MINUTES:]SECONDS:]CENTISECONDS
3 Global_buffers
Global_buffers
Specifies the number of cache buffers for a BG database. This qualifier
requires standalone access.The format of the GLOBAL_BUFFERS qualifier is:
-G[LOBAL_BUFFERS]=integer
In general, increasing the number of global buffers improves performance
by smoothing the peaks of I/O load on the system. However, increasing the
number of global buffers also increases the memory requirements of the
system, and a larger number of global buffers can increase the probability
of the buffers getting swapped out. If global buffers are swapped out, any
performance gain from increasing the number of global buffers will be more
than offset by the performance impact of swapping global buffers. Most
applications use from 1,000 to 4,000 global buffers for database regions
that are heavily used. FIS does not recommend using fewer than 256 buffers
except under special circumstances.
The minimum is 64 buffers and the maximum is 65536 buffers. By default,
MUPIP CREATE establishes GLOBAL_BUFFERS using information entered in the
Global Directory.
On many UNIX systems, default kernel parameters may be inadequate for GT.M
global buffers, and may need to be adjusted by a system administrator.
3 Lock_space
Lock_space
Specifies the number of pages allocated to the management of M locks
associated with the database. The size of a page is always 512 bytes.
The format of the LOCK_SPACE qualifier is:
-L[OCK]_SPACE=integer
o The maximum LOCK_SPACE is 65,536 pages.
o The minimum LOCK_SPACE is 10 pages.
o The default LOCK_SPACE is 40 pages.
o A file or region name is required to assign lock space.
o
o This qualifier requires standalone access.
3 INST_freeze_on_error
INST_freeze_on_error
Enables or disables custom errors in a region to automatically cause an
Instance Freeze. This flag modifies the "Inst Freeze on Error" file header
flag.
3 Journal
Journal
Specifies whether the database allows journaling and, if it does,
characteristics for the journal file. The format of the JOURNAL qualifier
is:
-[NO]J[OURNAL][=journal-option-list]
o -NOJOURNAL specifies that the database does not allow journaling. And
also it does not accept an argument assignment.
o -JOURNAL specifies journaling is allowed. It takes one or more
arguments in a journal-option-list.
3 Qdbrundown
Qdbrundown
Quickens normal process shutdown where a large number of processes
accessing a database file are required to shutdown almost simultaneously,
for example, in benchmarking scenarios. When a terminating GT.M process
observes that a large number of processes are attached to a database file
and QDBRUNDOWN is enabled, it bypasses checking whether it is the last
process accessing the database. Such a check occurs in a critical section
and bypassing it also bypasses the usual RUNDOWN actions which accelerates
process shutdown removing a possible impediment to process startup. By
default, QDBRUNDOWN is disabled.
Note that with QDBRUNDOWN there is a possibility of race condition that
might leave the database fileheader and IPC resources in need of cleanup.
Although QDBRUNDOWN minimizes the probability of such a race condition, it
cannot eliminate it. When using QDBRUNDOWN, FIS recommends an explicit
MUPIP RUNDOWN of the database file after the last process exits, to ensure
the cleanup of database fileheader and IPC resources.
3 REServed_bytes
REServed_bytes
Specifies the size to be reserved in each database block. RESERVED_BYTES
is generally used to reserve room for compatibility with other
implementations of M or to observe communications protocol restrictions.
The format of the RESERVED_BYTES qualifier is:
-RES[ERVED_BYTES]=size
o RESERVED_BYTES may also be used as a user-managed fill factor.
o The minimum RESERVED_BYTES is 0 bytes. The maximum RESERVED_BYTES is
the block size minus the size of the block header which is 7 or 8
depending on your platform. Realistic determinations of this amount
should leave room for at least one record of maximum size.
3 Version
Version
Sets the block format version (Desired DB Format field in the file header)
for all subsequent new blocks. The format of the VERSION qualifier is:
-V[ERSION]={V4|V6}
o MUPIP UPGRADE and MUPIP REORG -UPGRADE set the Desired DB Format field
in the database file header to V6 while MUPIP REORG -DOWNGRADE sets it
to V4.
o To set the version to V4, the current transaction number (CTN) of the
database must be within the range of a 32-bit maximum.
o V6 block format is compatible with the V5 block format. The longer key
and longer records (spanning nodes) features of V6 format are
automatically disabled when used with GT.M V5.* versions.
o For more information on the upgrading or downgrading your database,
refer to the release notes document of your current GT.M version.
3 Examples
Examples
Example:
$ mupip set -journal=on,nobefore -region "*"
This example enables NOBEFORE image journaling and turns on journaling for
all regions.
$ mupip set -version=V4 -file mumps.dat
Database file mumps.dat now has d esired DB format V4
This example sets the block format to V4 for all subsequent new blocks in
V6 database file mumps.dat.
Example:
$ mupip set -version=v6 -file mumps.dat
Database file mumps.dat now has desired DB format V5
This example sets the block format to V6 for all subsequent new blocks in
V4 database file mumps.dat.
Example:
mupip set -flush_time=01:00:00:00 -region DEFAULT
This example sets flush time to 1 hour. You can also specify flush time in
any combination of [[[HOURS:]MINUTES:]SECONDS:]CENTISECONDS. MUPIP
interprets -FLUSH_TIME=360000 or -FLUSH_TIME=00:60:00:00 as
-FLUSH_TIME=01:00:00:00.
Example:
$ mupip set -region REPTILES -inst_freeze_on_error
This example enables custom errors in region REPTILES to cause an Instance
Freeze.
2 SIZE
SIZE
Estimates and reports the size of global variables using a format that is
similar to the one that appears at the end of the MUPIP INTEG -FULL
report. In comparison with MUPIP INTEG -FAST -FULL, MUPIP SIZE provides
the option of choosing any one of the three estimation techniques to
estimate the size of global variables in a database file. These techniques
vary in measurement speed and estimate accuracy. The format of the MUPIP
SIZE command is:
MUPIP SI[ZE] [-h[euristic]=estimation_technique] [-s[elect]=global-name-list] [-r[egion]=region-list]
The optional qualifiers of MUPIP SIZE are:
-Heuristic=estimation_technique
Specifies the estimation technique that MUPIP SIZE should use to estimate
the size of global variables. The format of the -HEURISTIC qualifier is:
-h[euristic]={sc[an][,level=<lvl>] | a[rsample][,samples=<smpls>] | i[mpsample][,samples=<smpls>]}
o smpls is the number of samples and must be greater than zero (0)
o lvl is a positive or negative tree level designation and -(level of
the root block) <= lvl <= (level of the root block)
estimation-technique is one of the following:
o scan,level=<lvl>
Traverses the global variable tree and counts the actual number of
records and blocks at levels from the root down to the level specified
by lvl (default is 0, the data blocks). If the given level is
non-negative, it is the lowest block level of the global for which the
count is requested. So, 0 means all blocks, 1 means all index blocks,
2 means all index blocks of level 2 and above, and so on. SCAN counts
a negative level from the root of the global tree where -1 means
children of the root.
o arsample,samples=<smpls>
Uses acceptance/rejection sampling of random tree traversals to
estimate the number of blocks at each level. It continues until the
specified number of samples (default is 1,000) is accepted.
o impsample,samples=<smpls>
Uses importance sampling of random tree traversals to weight each
sample of the specified number of samples (default is 1,000) in order
to estimate size of the tree at each level.
o If -HEURISTIC is not specified, MUPIP SIZE uses the
ARSAMPLE,SAMPLE=1000 estimation technique.
**Important**
For large databases, MUPIP SIZE is faster than MUPIP INTEG -FAST -FULL.
IMPSAMPLE is expected to be the fastest estimation technique, followed by
ARSAMPLE and then SCAN.
In terms of accuracy, MUPIP INTEG -FAST -FULL is the most accurate.
-Select
Specifies the global variables on which MUPIP SIZE runs. If -SELECT is not
specified, MUPIP SIZE selects all global variables.
The format of the SELECT qualifier is:
-s[elect]=global-name-list
global-name-list can be:
o A comma separated list of global variables.
o A range of global variables denoted by start:end syntax. For example,
-select="g1:g4".
o A global variable with wildcards, for example, "g*" (the name must be
escaped to avoid shell filename expansion)
o "*" to select all global variables.
-Region
Specifies the region on which MUPIP SIZE runs. If REGION is not specified,
MUPIP SIZE selects all regions. The format of the REGION qualifier is:
-R[EGION]=region-list
Examples:
$ mupip size -heuristic="impsample,samples=2000" -select="y*" -region="AREG"
This example estimates the size of all global variable starting with "y".
It uses importance sampling with 2000 samples on the region AREG.
$ mupip size -heuristic="scan,level=-1"
This example counts the number of blocks and records at 1 level below the
root of the database tree.
$ mupip size -heuristic="arsample" -select="g1:g3"
This example estimates the size of global variables g1, g2 and g3 using
accept/reject sampling with the default number of samples regardless of
the region in which they reside.
**Note**
Apart from randomness caused by sampling heuristics, MUPIP SIZE also has
randomness from concurrent updates because it does not use the snapshot
technique that MUPIP INTEG uses.
2 STOP
STOP
Terminates a GT.M image. The image executes an orderly disengagement from
all databases that are currently open by the process, and then exits. A
MUPIP STOP performs a kill -15 and therefore may also be used to stop
non-GT.M images.
The format of the STOP command is:
MUPIP ST[OP] process-id
o Use the shell command ps to display a list of active process names and
process identifiers (PIDs).
o To STOP a process belonging to its own account, a process requires no
privileges. To STOP a process belonging to another account, MUPIP STOP
must execute as root.
2 TRIGGER
TRIGGER
Examines or loads trigger definitions. The format of the MUPIP TRIGGER
command is:
TRIGGER {-TRIG[GERFILE]=<trigger_definitions_file> [-NOPR[OMPT]]|
[-SELE[CT][=name-list|*][<select-output-file>]}
Before you run the MUPIP TRIGGER command:
1. Set the value of the environment variable gtmgbldir: to specify the
value of a current global directory.
2. Ensure that the key size, record size, block size of your database is
sufficient for storing trigger definition. You may have to set the key
and record sizes larger than the database content would otherwise
require.
The qualifiers of the MUPIP TRIGGER command are as follows:
TRIGgerfile=<trigger_definitions_file>
Loads a trigger definition file to the database. The format of the
TRIGGERFILE qualifier is:
-TRIG[GERFILE]=<trigger_definitions_file> [-NOPR[OMPT]]
o For information on the syntax and usage of a trigger definition file,
refer to GT.M Programmer's Guide.
o A MUPIP TRIGGER -TRIGGERFILE operation occurs within a transaction
boundary, therefore, if even one trigger from the trigger definition
file fails to parse correctly, MUPIP TRIGGER rolls back the entire
trigger definition file load. MUPIP TRIGGER operations have an
implicit timeout of zero (0), meaning the read must succeed on the
first try or the command will act as if it received no input.
o MUPIP TRIGGER -TRIGGERFILE ignores blank lines and extra whitespace
within lines. It treats lines with a semi-colon in the first position
as comments and ignores their content.
o MUPIP TRIGGER compiles the XECUTE action string and rejects the load
if the compilation has errors.
o Always specify the same value for the environment variable gtm_chset
during loading and executing triggers. If you specify different values
of gtm_chset during loading and executing triggers, MUPIP TRIGGER
generates a run-time error (TRIGINVCHSET). GT.M does not prevent a
process from updating different nodes with triggers using a different
character set, however, GT.M prevents a process from updating the same
triggering node with different character sets. Your coding practice,
for all database updates, should be to ensure that you provide the
same value for gtm_chset during load compilation and run-time
compilation.
o Incompatible with: -SELECT
**Note**
The trigger update summary reports count not only names and option changes
as "modified" but also cases where a -COMMANDS list changed, even though
those are functionally additions or deletions of separate trigger
definitions.
SELECT=name-list
Provides a facility to examine the current trigger definition. SELECT
produces a list of the current triggers for a comma-separate list of
global variables or trigger names. The format of the SELECT qualifier is:
-SELE[CT][=name-list[*]|*][ <select-output-file>]
1. Name-list can include global names, delimited with a leading caret
(^), and/or trigger names (user-defined or auto-generated) with no
leading caret. You can specify a trailing asterisk(*) with either.
2. With no arguments specified, GT.M treats -SELECT as -SELECT="*" and
extracts a list of all current triggers.
3. Optionally, you can specify a file name to redirect the output of the
command. If you do not specify a file name, MUPIP TRIGGER prompts for
a file name. If you respond with an empty string (RETURN), MUPIP
TRIGGER directs the output to STDOUT.
**Note**
The output from the MUPIP TRIGGER -SELECT command may not be identical to
your trigger definition file. This is because GT.M converts some
semantically identical syntax into a single internal representation; while
-SELECT output may not be identical to the -TRIGGERFILE input, it has the
same meaning. Additionally, MUPIP TRIGGER -SELECT displays a field called
"Cycle" as part of a comment. Cycle is the number of trigger definition
updates (addition, modification, or deletion) performed on a global.
3 Examples
Examples
This section provides step-by-step instructions for creating, modifying,
and deleting triggers. Triggers affect all processes updating a database
unlike, for example, environment variables such as $gtmroutines which work
on a per process basis. Therefore, FIS recommends that you should always
have carefully planned procedures for changing triggers in your production
environment.
To create a new trigger for global node ^Acct("ID"):
1. Using your editor, create a trigger definition file called
triggers.trg with the following entry:
+^Acct("ID") -name=ValidateAccount -commands=S -xecute="Write ""Hello Earth!"""
2. Execute a command like the following:
$ mupip trigger -triggerfile=triggers.trg
This command adds a trigger for ^Acct("ID"). On successful trigger
load, this command displays an output like the following:
File triggers.trg, Line 1: ^Acct trigger added with index 1
=========================================
1 triggers added
0 triggers deleted
0 trigger file entries not changed
0 triggers modified
=========================================
Now, every S[et] operation on the global node ^Acct("ID") executes the
trigger.
3. Execute a command like the following:
$ mupip trigger -select="^Acct*"
This command displays the triggers. A sample output looks like the
following:
;trigger name: ValidateAccount# cycle: 1
+^Acct("ID") -name=ValidateAccount -commands=S -xecute="Write ""Hello Earth!"""
To modify an existing trigger for global node ^Acct("ID"):
You cannot directly replace an existing trigger definition with a new one.
With the exception of -NAME and -OPTIONS, to change an existing trigger,
you have to delete the existing trigger definition and then add the
modified trigger definition as a new trigger. Note that GT.M performs two
different trigger comparisons to match trigger definitions depending on
whether or not S[ET] is the trigger invocation command. If there is a
S[ET], then the comparison is based on the global name and subscripts,
PIECES, [Z]DELIM, and XECUTE. If there is no SET, GT.M compares only the
global node with subscripts and the -XECUTE code value.
1. Begin by executing the following command:
$ mupip trigger -select="^Acct*"
Output file:
2. Specify trigger_mod.trg as the output file. This file contains entries
like the following:
;trigger name: ValidateAccount# cycle: 1
+^Acct("ID") -name=ValidateAccount -commands=S -xecute="Write ""Hello Earth!"""
3. Using your editor, open trigger_mod.trg and change + (plus) to -
(minus) for the trigger definition entry for ValidateAccount and add a
new trigger definition for ^Acct("ID"). To avoid inconsistent
application behavior, it is important to replace an old trigger with a
new one in the same transaction (Atomic). The trigger_mod.trg file
should have entries like:
;trigger name: ValidateAccount# cycle: 1-^Acct("ID") -name=ValidateAccount -commands=Set -xecute="Write ""Hello Earth!"""
;trigger name: ValidateAccount#+^Acct("ID") -name=ValidateAccount -commands=Set -xecute="Write ""Hello Mars!"""
4. Execute a command like the following:
$ mupip trigger -triggerfile=trigger_mod.trg
5. This command displays an output like the following:
File trigger_mod.trg, Line 1: ^Acct trigger deleted
File trigger_mod.trg, Line 3: ^Acct trigger added with index 1
=========================================
1 triggers added
1 triggers deleted
0 trigger file entries not changed
0 triggers modified
=========================================
Congratulations! You have successfully modified the xecute string of
ValidateAccount with the new one.
To delete an existing trigger for global node ^Acct("ID"):
1. Begin by executing the following command:
$ mupip trigger -select="^Acct*"
Output file:
2. Specify trigger_delete.trg as the output file. This file contains
entries like the following:
;trigger name: ValidateAccount# cycle: 3
+^Acct("ID") -name=ValidateAccount -commands=S -xecute="Write ""Hello Mars!"""
3. Using your editor, change + (plus) to - (minus) for the trigger
definition entry for ValidateAccount. Alternatively, you can create a
file with an entry like -ValidateAccount.
4. Now, execute a command like the following:
$ mupip trigger -triggerfile=trigger_delete.trg
This command displays an output like the following:
File trigger_delete.trg, Line 2: ^Acct trigger deleted
=========================================
0 triggers added
1 triggers deleted
0 trigger file entries not changed
0 triggers modified
=========================================
You have successfully deleted trigger "ValidateAccount".
To change a trigger name for global node ^Acct("ID"):
1. Using your editor, create a new file called trigger_rename.trg and add
a trigger definition entry for ValidateAcct with the same trigger
signature as ValidateAccount. Your trigger definition would look
something like:
+^Acct("ID") -name=ValidateAcct -commands=S -xecute="Write ""Hello Mars!"""
2. Verify that the ValidateAccount trigger exists by executing the
following command:
$ mupip trigger -select="^Acct*"
Output file:
3. Respond with an empty string (Press Enter). Confirm that the trigger
summary report contains an entry like the following:
;trigger name: ValidateAccount# cycle: 3
+^Acct("ID") -name=ValidateAccount -commands=S -xecute="Write ""Hello Mars!"""
4. Now, execute a command like the following:
$ mupip trigger -triggerfile=trigger_rename.trg
This command displays an output like the following:
=========================================
0 triggers added
0 triggers deleted
0 trigger file entries not changed
1 triggers modified
=========================================
You have successfully changed the trigger name ValidateAccount to
ValidateAcct.
2 UPGRADE
UPGRADE
Upgrades the file-header of a database. The format of the MUPIP UPGRADE
command is:
UP[GRADE]
o It increases the size from 4 bytes to 8 bytes of file-header fields
such as current transaction number (CTN), maximum TN and others that
contain transaction numbers.
o It resets the various trace counters and changes the database format
to V5. This change does not upgrade the individual database blocks but
sets the database format flag to V5.
o It also initializes a counter of the current blocks that are still in
V4 format. It decrements this counter each time an existing V4 format
block is converted to V5 format. When the counter is 0, the entire
database gets converted.
3 Example
Example
Example:
$ mupip upgrade mumps.dat
This example upgrades the file-header of mumps.dat to V5 format.
1 Journaling
Journaling
2 SET
SET
MUPIP SET is the primary utility used to establish and activate journaling
(using the -JOURNAL) and replication (using the -REPLICATION).
When GDE creates a Global Directory, it stores either the explicitly
specified journaling information, or the GDE default value for any
unspecified characteristics.
MUPIP CREATE copies existing journaling information from the Global
Directory to the database file, establishing journaling characteristics
for all GDE supported journal-options.
**Important**
GT.M applies journaling information in the Global Directory to a database
file only when it is created. Thereafter use MUPIP, or possibly DSE, to
change journaling characteristics in database files. Be sure to use GDE to
reflect current journaling needs so that the next time you use MUPIP
CREATE you get the desired journaling characteristics.
DSE DUMP -FILEHEADER displays the current values for all established
journaling characteristics.
This section provides a description of the MUPIP SET command with specific
reference to the journaling related qualifiers.
MUPIP SET -JOURNAL can change some database characteristics when
journaling is active for a specific file or region(s). The first run of
MUPIP SET -JOURNAL on an older database automatically changes the
maximum/minimum journal settings to match those required by the current
GT.M version. MUPIP SET operates on either regions or files.
The format for the MUPIP SET command is:
MUPIP SE[T] -qualifier... {-F[ILE] file-name|-REG[ION] region-list}
The file-specification or region-list identifies the target of the SET.
Region-names separated by commas (,) make up a region-list.
To establish journaling characteristics, use the MUPIP SET command with
the -[NO]JOURNAL[=journal-option-list] qualifier and one of the following
SET object identifying qualifiers:
-F[ILE]
-R[EGION]
Together with one or more of the SET action qualifiers:
-[NO]JOURNAL[=journal-option-list] -REPLICATION=<replication-option>'
3 Object_Identifying_Qualifiers
Object Identifying Qualifiers
The following qualifiers identify the journaling targets:
-F[ILE]
Specify that the argument to the SET is a file-specification for a single
database file. A Journal file's name can now include characters in
Unicode.
Old journal files stay open for about 10 seconds after a switch to a new
journal file.
-R[EGION]
Specify that the argument to the SET is a list of one or more
region-names, possibly including wildcards, which, through the mapping of
the current Global Directory, identifies a set of database files. SET
-REGION modifies multiple files when the parameter contains more than one
name.
The -REGION qualifier is incompatible with the -FILE qualifier.
-J[NLFILE]
Specifies that the target for SET is a journal file. The format of the
JNLFILE qualifier is:
-jnlfile jnl_file [-[no]prevjnlfile=jnlfilename] [-bypass]
[-repl_state={on|off}] [-dbfilename=file_name]
jnl_file specifies the name of the target journal file.
-prevjnlfile=jnlfilename
Changes the name of the previous generation of the journal file in the
header of jnl_file to jnlfilename (for example, 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
Cuts 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
Override the requirement that database files (or their corresponding
journal files) affected by the set command be available standalone.
**Caution**
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.
-repl_state={on|off}
Change the replication state of a journal file; this command is intended
for use only under instructions from your GT.M support provider.
-dbfilename=file_name
Associates a journal file with a different database file; this command may
be useful in arranging unusual RECOVER or ROLLBACK scenarios.
3 Action_Qualifiers
Action Qualifiers
The -JOURNAL and -REPLICATION qualifiers are the only SET qualifiers
relevant for journaling.
-[NO]J[OURNAL][=journal-option-list]
Enables or disables journaling for the specified database file or
region(s). MUPIP SET commands with this qualifier also establish the
characteristics for journal files. FIS believes the defaults and minimum
for journal file characteristics are in line with current hardware
capabilities and suitable for a production environment.
The journal-option-list contains keywords separated with commas (,)
enclosed in double quotes "". These double quotes are optional when the
list contains only one keyword. This option list is a super set of the
journal-option-list available through GDE.
o -NOJOURNAL specifies that the database does not allow journaling, or
disables journaling for a database that currently has it enabled. It
is equivalent to -JOURNAL=DISABLE.
o -NOJOURNAL does not accept an argument assignment. It does not create
new journal files. When a database has been SET -NOJOURNAL, it appears
to have no journaling file name or other characteristics.
o -JOURNAL= enables journaling for a database file. -JOURNAL= takes one
or more arguments in a journal-option-list. As long as journaling is
ENABLED and turned ON at the end of the command, SET -JOURNAL= always
creates a new version of the specified journal file(s).
o -NOJOURNAL specifies that the database does not allow journaling, or
disable journaling for a database where journaling is active.
o Enable BEFORE_IMAGE or NOBEFORE_IMAGE journaling for a database file.
o As long as journaling is ENABLED and turned ON at the end of the
command, SET -JOURNAL= always creates a new version of the specified
journal file(s).
o Every MUPIP SET -JOURNAL command on a database file that specifies an
ON or OFF journal-activation option causes the values of all
explicitly specified journal-file-options to be stored in the database
overriding any previously established characteristics for those
options.
o If you specify both -JOURNAL and -NOJOURNAL in the same command line,
the latter takes effect.
o Whenever MUPIP SET creates a new journal file, it uses all values for
journal-file-options that the user explicitly specifies in the command
line for the new journal file. If you do not specify a
journal-file-option, MUPIP SET takes the char acteristics of the
existing journal file.
o MUPIP SET supports qualifiers (like -ACCESS_METHOD, and so on) to
change non-journaling characteristics of database file(s). If you
specify these qualifiers -JOURNAL , MUPIP SET modifies the
non-journaling characteristics first and then moves on to modify the
journaling characteristics. Command execution stops when it encounters
an error. If MUPIP SET encounters an error in processing the command
line or the non-journaling characteristics, it makes no changes to any
characteristics. However, if MUPIP SET encounters an error in
processing the journaling characteristics, the non-journaling
characteristics have already been successfully changed.
o -NOJOURNAL is equivalent to -JOURNAL=DISABLE.
o -NOJOURNAL does not accept an argument assignment. It does not create
new journal files. When a database has been SET -NOJOURNAL, it appears
to have no journaling file name or other characteristics.
-REPLI[CATION]=replication-option
-REPLICATION sets journal characteristics and changes the replication
state simultaneously. It can also be used with the -JOURNAL qualifier. If
journaling is ENABLED and turned ON, SET -REPLICATION=ON creates new set
of journal files, cuts the back-link to the prior generation journal
files, and turns replication ON.
4 JOURNAL_Options
JOURNAL Options
ALI[GNSIZE]=blocks
o Specifies the number of 512-byte-blocks in the ALIGNSIZE of the
journal file.
o If the ALIGNSIZE is not a perfect power of 2, GT.M rounds it up to the
nearest power of 2.
o The default and minimum ALIGNSIZE value is 4096 blocks. The maximum
value is 4194304 (=2 GigaBytes).
o A journal file consists of a sequential stream of journal records each
of varying size. It is typically not easy to detect the beginning of
the last valid journal record in an abnormally terminated journal file
(for example, system crash). To facilitate journal recovery in the
event of a system crash, the GT.M run-time system ensures that offsets
in the journal file which are multiple of ALIGNSIZE (excepting offset
0 which houses the journal file header) is always the beginning of a
valid journal record. In order to ensure this, GT.M run-time system
writes padding data (if necessary) in the form of ALIGN journal
records just before the ALIGNSIZE boundary. These ALIGN records also
help in skipping past invalid records in the middle of a journal file
allowing MUPIP JOURNAL -EXTRACT -FORWARD -FULL to extract as much data
of a corrupt journal file as possible.
o While a larger align size trade off crash recovery time in favor of
increased journaling throughput, especially when before image
journaling is in use, there is marginal value in using an align size
larger than a few MB.
o The minimum ALIGNSIZE supported is always be greater than or equal to
the maximum journal record size, which in turn depends on the maximum
database block size.
o Note that a large value of ALIGNSIZE implies less aligned boundaries
for recovery to use and hence slows backward recovery down so
drastically that, for example, the maximum value of 4194304 causes
backward recovery (in case of a crash) to take as much time as forward
recovery on that journal file.
ALL[OCATION]=blocks
Sets the allocation size of the journal file. GT.M uses this information
to determine when it should first review the disk space available for the
journal file. The size of the journal file at creation time is a constant
(depending on the GT.M version) but once the journal file reaches the size
specified by ALLOCATION, every extension produces a check of free space
available on the device used for the journal file.
GT.M issues informational messages to the system log whenever the free
space available is not much more than the extension size. GT.M provides
these extension checks as an operational aid for identifying, before space
runs out, that a file system holding the journal file is low on space.
When there is no more free space available on the file system holding a
journal file, GT.M shuts off journaling for the corresponding database
file.
The default ALLOCATION value is 2048 blocks. The minimum value allowed is
2048. The maximum value is 8,388,607 (4GB-512 bytes, the maximum journal
file size).
AU[TOSWITCHLIMIT]=blocks
Specifies the limit on the size of a journal file. When the journal file
size reaches the limit, GT.M automatically performs an implicit online
switch to a new journal file.
**Note**
It is possible to set the AUTOSWITCHLIMIT to a value higher than the
maximum file size (in blocks) for the file system. Currently GT.M does not
attempt to check for this condition at specification time. GT.M produces a
run-time error when a journal file reaches the maximum size for the file
system. Therefore, ensure that the AUTOSWITCHLIMIT never exceeds the
file-system limit.
The default value for AUTOSWITCHLIMIT is 8388600 & the maximum value is
8388607 blocks (4GB-512 bytes). The minimum value for AUTOSWITCHLIMIT is
16384. GT.M produces an error if the AUTOSWITCHLIMIT value is less than
the sum of allocation and extension values. If the difference between the
AUTOSWITCHLIMIT and the allocation value is not a multiple of the
extension value, GT.M rounds-down the value to make it a multiple of the
extension value and displays an informational message. GT.M produces an
error when the rounded value of AUTOSWITCHLIMIT is less that the minimum
value.
If you specify values for ALLOCATION, EXTENSION, and AUTOSWITCHLIMIT for a
region such that (ALLOCATION+EXTENSION>AUTOSWITCHLIMIT), either using GDE
or MUPIP SET -JOURNAL, GT.M sets ALLOCATION to match the AUTOSWITCHLIMIT,
and produces a JNLALLOCGROW message.
At journal extension time, including journal autoswitch time, if
(ALLOCATION+EXTENSION>AUTOSWITCHLIMIT) for a region, GT.M uses the larger
of EXTENSION and AUTOSWITCHLIMIT as the increment to warn of low available
journal disk space. Otherwise, it uses EXTENSION.
[NO]BEFORE_IMAGES
Controls whether the journal should capture BEFORE_IMAGES of GDS blocks
that an update is about to modify. A SET -JOURNAL=ON must include either
BEFORE_IMAGES or NOBEFORE_IMAGES in the accompanying journal-option-list.
If you specify both NOBEFORE_IMAGES and BEFORE_IMAGES in the same
journal-option-list, the last specification overrides any previous one(s).
As GT.M creates new journal files only with the ON option and every ON
specification must include either BEFORE_IMAGES or NOBEFORE_IMAGES. If the
user specifies [NO]BEFORE_IMAGES along with the OFF option serve no
purpose.
Although it is possible to perform an online switch of a database from (or
to) NOBEFORE-IMAGE journaling to (or from) BEFORE-IMAGE journaling, it is
important to understand that backward recovery can never succeed if it
encounters even one in a set of journal files for a database without
BEFORE-IMAGES.
BU[FFER_SIZE]=blocks
Specifies the amount of memory used to buffer journal file output.
MUPIP requires standalone access to the database to modify BUFFER_SIZE.
Therefore, GT.M restricts the use of the BUFFER_SIZE option to change the
current journal-buffer-size as part of an online switch of the journal
files.
The default value is 2308 blocks. The minimum BUFFER_SIZE is 2307 blocks.
The maximum BUFFER_SIZE is 32K blocks which means that the maximum buffer
you can set for your journal file output is 16MB.
DISABLE
Equivalent to the -NOJOURNAL qualifier of MUPIP SET. It specifies that
journaling is not an option for the region or file named. If the user
specifies DISABLE, then MUPIP SET ignores all other options in the
journal-option-list.
ENABLE
Makes the database file or region available for journaling. By default,
ENABLE turns journaling ON unless OFF is specified in the same option
list. A command that includes ENABLE must also specify BEFORE_IMAGES or
NOBEFORE_IMAGES.
EP[OCH_INTERVAL]=seconds
seconds specifies the elapsed time interval between two successive EPOCHs.
An EPOCH is a checkpoint, at which all updates to a database file are
committed to disk. All journal files contain epoch records.
A smaller EPOCH_INTERVAL reduces the time to recover after a crash at the
cost of increased I/O load on the run-time system (due to more frequent
checkpoints). A larger EPOCH_INTERVAL has the opposite effect. Therefore,
set EPOCH=interval for a more efficient run-time with larger values of
interval and more efficient ROLLBACK processing with smaller values of
interval.
The default EPOCH_INTERVAL value is 300 seconds (5 minutes). The minimum
value is 1 second. The maximum value is 32,767 (one less than 32K)
seconds, or approximately 9.1 hours. If you enable journaling and do not
specify a value for EPOCH_INTERVAL, GT.M inherits the value of
EPOCH_INTERVAL of the last journal file in that region. EPOCH_INTERVAL
only makes takes effect when the user turns journaling ON and there is no
earlier journal file.
EX[TENSION]=blocks
blocks specifies the size of the journal file extension by which file
expands and becomes full.
EXTENSION=blocks specifies when GT.M should review disk space available
for the journal file after the ALLOCATION has been used up. It also
specifies how much space should be available at each review.
As UNIX file systems use lazy allocation schemes, allocation and extension
values do not result in physical disk block allocation for the journal
file.
The values determine when GT.M checks the file systems to see if it has
enough space to hold an extension worth of journal data. When a journal
file reaches the size of ALLOCATION and any multiple of EXTENSION, GT.M
checks the file system for room, and if the available space is less than
three times the EXTENSION, it writes warnings to the operator log. GT.M
provides these extension checks as an operational aid for identifying,
before space runs out, that a file system holding the journal file is low
on space. When there is no more free space available ) on the file system
holding a journal file or there is no authorization of a process
attempting to autoswitch a journal file, GT.M shuts off journaling for the
corresponding database file.
The default EXTENSION value is 2048 blocks. The minimum EXTENSION is zero
(0) blocks and the maximum is 1073741823 (one less than 1 giga) blocks.
F[ILENAME]=journal_filename
journal_filename specifies the name of the journal file. FILENAME is
incompatible with SET -REGION, if you specify more than one region.
GT.M treats the filename as having two components - basename and
extension. The format of the journal filename is basename.extension, where
extension does not contain any periods (.), but if the filename contains
more than one period (.), basename contains all but the last period (.).
Also note that "extension" is the empty string ("") if the filename does
not contain any periods (.).
The convention of the default value for the FILENAME is as follows:
o GT.M takes the basename of the database filename as the basename for
the journal file with an extension of mjl if the database has a dat
extension. For example, database name mumps.dat results in a default
name mumps.mjl. If the database filename does not have a dat
extension, GT.M replaces all occurrences of periods (.) with
underscores (_) with an extension of mjl and takes the full database
filename. For example, database name mumps.acn results in a default
name mumps_acn.mjl. Therefore, by default, a journal file has an
extension of mjl unless you explicitly specify a different extension
with the FILENAME journal option. If the new journal filename (the one
specified in the FILENAME option or the default) already exists, GT.M
renames the existing file with the string "_YYYYJJJHHMMSS" appended to
the existing file extension where the string denotes the time of
creation of the existing journal file in the following format:
YYYY 4-digit-year such as 2011
JJ 3-digit-Julian-day (between 1 and 366) such as 199
HH 2-digit-hour in 24 hr format such as 14
MM 2-digit minute such as 40
SS 2-digit seconds such as 30
Assuming the above example for the string value, GT.M renames a
journal file mumps.mjl to mumps.mjl_2010199144030 when it switches to
a new journal file.
o If GT.M detects that the rename-logic yields a filename that already
exists, the string "_N[N[N[N...]]]" is appended to the renamed
filename where "N[N[N...]]" denotes the sequence of numbers
0,1,2,3,4,5,6,7,8,9,90,91,92,93,94,95,96,97,98,99,990,991,...
GT.M tries all numbers from the order in the above sequence until it
finds a non-existing rename-filename.
Taking the same example as above, in case mumps.mjl_2010199144030 and
mumps.mjl_2010119144030_0 already exists, the rename string would be
mumps.mjl_2010199144030_1.
o If the existing file renaming scheme or the default journal file
naming scheme discussed above results in a filename longer than 255
characters (due to the suffix creation rules), GT.M produces an error
and turns off journaling.
A journal file name can include characters in Unicode.
**Note**
Whenever GT.M implicitly turns off journaling due to run-time conditions
such as no available disk space or no authorization for a process
attempting to auto-switch a journal file (and so on) , it produces an
error and accompanying messages identify the reason for that condition.
For journal recovery, GT.M maintains a field in every journal file's
header that stores the name of the previous generation journal file for
the same database file. When a MUPIP SET changes the journal state from
DISABLED or OFF to ON, GT.M creates new journal files with no previous
generation journal file name. This indicates that this is a fresh start of
journaling for the particular database. When journaling is already ON, and
GT.M is implicitly (due to AUTOSWITCHLIMIT being reached) or explicitly
(due to MUPIP SET JOURNAL) required to create new journal files, GT.M
maintains the previous generation journal filename (after any appropriate
rename), in the new journal file's header.
In all cases where journaling is ON both before and after a journal file
switch, GT.M maintains the previous generation journal file name in the
new journal file's header except when GT.M creates a new journal file due
to an implicit switch because it detects an abnormal termination of the
current journal file or if the current journal file was not properly
closed due to a system crash and the database was the subject of a MUPIP
RUNDOWN afterwards.
**Note**
In the event of a crash, FIS strongly recommends performing a MUPIP
JOURNAL ROLLBACK on a database with replication, MUPIP JOURNAL RECOVER on
a journaled database, and MUPIP RUNDOWN only if using neither journaling
nor replication. GT.M error messages provide context-specific instructions
to promote this decision-making model which helps protect and recover data
after a crash.
The previous generation journal filename is a back link from the current
generation journal.
GT.M produces an error and makes no change to the journaling state of the
database when the FILENAME is an existing file and is not the active
journal file for that database. In this way, GT.M prevents possible cycles
in the back-links (such as, a3.mjl has a back-link to a2.mjl which in turn
has a back-link to a1.mjl which in turn has a back-link to a3.mjl thereby
creating a cycle). Cycles could prevent journal recovery. Also, note that
cycles in back-links are possible only due to explicit FILENAME
specifications and never due to an existing FILENAME characteristics from
the database or by using the default FILENAME.
NOPREVJNLFILE
Eliminates the back link of a journal file.
[NO]S[YNC_IO]
Directs GT.M to open the journal file with certain additional IO flags
(the exact set of flags varies by the platform where SYNC_IO is supported,
for example on Linux you might utilize the O_DIRECT flag). Under normal
operation, data is written to but not read from the journal files.
Therefore, depending on your actual workload and your computer system, you
may see better throughput by using the SYNC_IO journal option.
You should empirically determine the effect of this option, because there
is no way to predict the performance gain or impact in advance. There is
no functional difference in GT.M behavior with the use of SYNC_IO. If you
determine that different workloads perform best with a different setting
of SYNC_IO, you can change it with MUPIP SET at any time.
The default is NOSYNC_IO. If you specify both NOSYNC_IO and SYNC_IO in the
same journal-option-list, GT.M uses the last occurrence.
OFF
Stops recording subsequent database updates in the journal file. Specify
OFF to establish journaling characteristics without creating a journal
file or starting journaling.
The default for SET -JOURNAL= is ON.
ON
Records subsequent database updates in that journal file. MUPIP SET
-JOURNAL=ON must include either BEFORE_IMAGES or NOBEFORE_IMAGES in the
accompanying journal-option-list. By default GT.M sets journal operation
to BEFORE_IMAGE if this command changes the database replication state
from OFF to ON and JOURNAL=NOBEFORE_IMAGE is not specified.
**Important**
ON keyword works only on previously ENABLEd regions. GT.M ignores ON if
Journaling is DISABLEd. In other words, an ENable / DISable is like the
power switch on the back of many television sets and ON/OFF is like the
ON/OFF on the remote control. The ON/OFF on the remote control works only
when the power switch on the back of the television set is enabled.
If the current generation journal file is damaged/missing, MUPIP SET
-JOURNAL=ON implicitly turns off journaling for the specified region,
creates a new journal file with no back pointers to the prior generation
journal file, and turns journaling back on. Further, if replication is
enabled, MUPIP SET -JOURNAL=ON temporarily switches the replication WAS_ON
state in the time window when MUPIP SET command turns off journaling and
returns normal as long as it operates out of the journal pool buffer and
doesn't need to reference the damaged journal file(s). During this
operation, MUPIP SET -JOURNAL=ON also sends the PREJNLLINKCUT message for
the region to the application and the operator log. While this operation
ensures that journaling continues even if the current generation journal
file is damaged/missing, creating a new journal file with no back pointers
creates a discontinuity with the previous journal files. Therefore, FIS
recommends taking a database backup at the earliest convenience because a
MUPIP RECOVER/ROLLBACK will not be able to go back past this
discontinuity. Also, consider switching the journal files on all regions
in the instance (with REGION "*") to ensure the RECOVER/ROLLBACK for other
regions remains unaffected.
The default for SET -JOURNAL= is ON.
Y[IELD_LIMIT]=yieldcount
yieldcount specifies the number of times a process that tries to flush
journal buffer contents to disk yields its timeslice and waits for
additional journal buffer content to be filled-in by concurrently active
processes, before initiating a less than optimal I/O operation.
A smaller YIELD_LIMIT is appropriate for light load conditions while
larger values are appropriate as the load increases.
**Note**
A small YIELD_LIMIT may cause performance loss due to partial page writes
while a large YIELD_LIMIT may cause performance loss due to significant
idle times (due to a lot of yields).
The minimum YIELD_LIMIT is zero (0), the maximum YIELD_LIMIT is 2048 and
the default YIELD_LIMIT is 8.
As the disk can only write entire blocks of data, many I/O subsystems
perform a READ-MODIFY-WRITE operation when data to be written is a partial
block as opposed to simple writes for an entire block. The YIELD_LIMIT
qualifier tries to reduce the frequency of sub-optimal partial block
writes by deferring such writes as much as possible in the hope that in
the meantime the journal buffer accumulates more content and qualifies for
an optimal entire block write.
3 Examples
Examples
$ mupip set -journal="enable,nobefore" -file mumps.dat
This example enables NOBEFORE_IMAGE journaling on mumps.dat. If journaling
is already enabled, this command switches the current journal file.
Example:
$ mupip set -journal=on,enable,before -region "*"
This example turn on journaling with BEFORE_IMAGE journaling. If
journaling is already enabled, this command switches the current journal
file for all regions.
$ mupip set -file -journal="nobefore,buff=2307" gtm.dat
This example initiates NOBEFORE_IMAGE journaling for the database file
gtm.dat with a journal buffer size of 2307 blocks. It also switches to new
journal file. This command assumes that some prior MUPIP SET -JOURNAL
specified ENABLE for gtm.dat.
Example:
$ mupip set -region -journal=enable,before_images,allocation=50000,ext=5000 "*"
This example enables journaling with BEFORE_IMAGES on all regions of the
current Global Directory and gives each journal file an ALLOCATION of
50000 blocks and an EXTENSION of 5000 blocks. If the regions have
significantly different levels of update, use several MUPIP SET -FILE or
-REGION commands.
Example:
$ mupip set -region -journal="enable,before" areg,breg
This example declares journaling active with BEFORE_IMAGES for the regions
areg and breg of the current Global Directory.
Example:
$ mupip set -file -nojournal mumps.dat
This example disables journaling on the database file mumps.dat.
Example:
$ mupip set -journal="ENABLE,BEFORE_IMAGES" -region "AREG"
$ mupip set -journal="ON,BEFORE_IMAGES" -region "*"
This example turns on journaling only for the region AREG. Note that AGREG
is the only region that is "available" for journaling.
Example:
$ mupip set -access_method=MM -file gtm.dat
This example sets MM (Memory Mapped) as the access method or GT.M
buffering strategy for storing and retrieving data from the database file
gtm.dat. Since MM is not supported with BEFORE_IMAGE journaling, this
example produces an error on a database with BEFORE_IMAGE journaling
enabled. You can also use -access_method=BG to set BG (Buffered Global) as
your buffering strategy.
Example:
$ mupip set -journal=before,noprevjnlfile,file=newmumps.mjl -file mumps.dat
The above command cuts the back link of the newly created journal file
newmumps.mjl.
2 JOURNAL
JOURNAL
MUPIP JOURNAL command analyzes, extracts from, reports on, and recovers
journal files. The format for the MUPIP JOURNAL command is:
MUPIP J[OURNAL] -qualifier[...] file-selection-argument
file-selection-argument is a comma-separated list of journal files.
-qualifier [...] is a combination of Action, Direction, Time, Sequence
Number, Control, and Selection qualifiers that perform various MUPIP
JOURNAL operations. To create any MUPIP JOURNAL command, select an
appropriate combination of qualifiers by moving horizontally from the
Action column extending to the Selection column:
+---------------------------------------------------------------------------------------+
| | | | Sequence | Control | Selection |
| Action |Direction| Time (optional) | Number | (optional) | (optional) |
| | | |(optional)| | |
|---------------+---------+--------------------+----------+--------------+--------------|
|One or more |Only one |One or more |Only one |One or more |One or more |
|---------------+---------+--------------------+----------+--------------+--------------|
| | | | |-[NO]AP | |
| | | | | | |
| | | | |-BR=extract | |
| | | | |file name | |
| | | | | | |
| | | | |-[NO]CHA | |
| | | | | | |
| | | | |-[NO]CHE | |
|-EX[=file | | | | | |
|specification] | | | |-[NO]ER[= | |
| | |-A=time | |integer] |-G=global list|
|-REC | | |-FET=port | | |
| | |-BE=time |number |-FE=fence |-ID=pid list |
|-RO |-BA -FO | | |option | |
| | |-[NO]LOO= lookback |-RES=jnl | |-T=transaction|
|-SH=show option| |option list] |sequence |-FU |type |
|list] | | |number | | |
| | |-SI=time | |-[NO]IN |-U=user list |
|-[NO]V | | | | | |
| | | | |-LOST=extract | |
| | | | |file name | |
| | | | | | |
| | | | |-RED=file pair| |
| | | | |list | |
| | | | | | |
| | | | |-VERB | |
| | | | | | |
| | | | |-DE | |
+---------------------------------------------------------------------------------------+
Also ensure that you adhere to the following rules:
1. -BEFORE is compatible with all other JOURNAL qualifiers except
-ROLLBACK.
2. -AFTER is incompatible with -BACKWARD and all action qualifiers,
except -EXTRACT, -SHOW, and -VERIFY.
3. -APPLY_AFTER_IMAGE is compatible only with -RECOVER, or -ROLLBACK.
4. -BACKWARD is incompatible with -FORWARD, -AFTER, -CHECKTN, -NOCHAIN,
and -REDIRECT.
5. -BROKENTRANS is compatible only with -RECOVER, -ROLLBACK, or -EXTRACT.
6. -CHAIN is only compatible with -FORWARD.
7. -DETAIL is compatible only with -EXTRACT.
8. -FETCHRESYNC or -RESYNC are compatible only with -ROLLBACK.
9. -FORWARD is incompatible with -BACKWARD, -ROLLBACK, -SINCE, and
-LOOKBACK_LIMIT.
10. -FULL is compatible only with -EXTRACT, -SHOW, or -VERIFY.
11. -LOSTTRANS is compatible only with -RECOVER, -ROLLBACK, or -EXTRACT.
12. -REDIRECT is compatible only with -RECOVER.
13. -ROLLBACK is incompatible with -RECOVER, FORWARD, -CHAIN, -CHECKTN,
-REDIRECT, time qualifiers of -SHOW.
14. -SINCE is incompatible with -FORWARD.
15. -TRANSACTION is compatible only with -EXTRACT and -SHOW.
16. -USER is compatible only with -EXTRACT and -SHOW.
17. file list must not be asterisk (*) for -REDIRECT.
18. file list must be asterisk (*) for -ROLLBACK.
19. Journal selection qualifiers are incompatib le with -RECOVER,
-ROLLBACK, and -VERIFY.
20. Journal time qualifiers are incompatible with -ROLLBACK.
For example, MUPIP JOURNAL -EXTRACT=gtm.mjf -FORWARD -DETAIL is a valid
command which performs forward processing to extract detailed the journal
records to gtm.mjf. However, MUPIP JOURNAL -EXTRACT
-REDIRECT=gtm.dat=test/gtm.dat -FORWARD is an invalid command because
-REDIRECT is not compatible with -EXTRACT.
MUPIP JOURNAL manipulates an inactive journal file that is available for
exclusive (standalone) use. You can transcribe Journal files to tape.
However, you must always restore them to disk for processing by MUPIP
JOURNAL.
Press CTRL+C to stop JOURNAL processing. A JOURNAL command that terminates
abnormally by operator action or error produces an incomplete result. In
this case, the resulting database may be corrupt. If you stop a JOURNAL
operation by mistake, reissue the command to produce the proper result for
-RECOVER (or -ROLLBACK) -BACKWARD. For -RECOVER -FORWARD, restore the
database from backup and reissue the command.
3 Action_Qualifiers
Action Qualifiers
This section describes the journaling action qualifiers.
4 EXtract
EXtract
Transfers information from journal files into files formatted for
processing by M routines. It reports the journal time stamps using the $H
format, as controlled by the time zone setting from the OS and the process
environment for the process running the EXTRACT.
-EXTRACT takes <file-name> or -stdout as an optional argument.
<file-name> specifies the name of the output file. -stdout specifies that
-EXTRACT write to standard output (stdout) instead of writing to a file.
With no arguments, MUPIP JOURNAL derives the output file specification of
the extract file using the name of the first journal file that is
processed in the forward processing phase and a file type of .mjf. Note
that, if multiple journal names are specified in the command line the
first journal specified might be different from the first journal
processed in the forward phase. When -EXTRACT is specified with -RECOVER
(or -ROLLBACK), the -JOURNAL command extracts all the journal records
processed during a -RECOVER -FORWARD command or the forward phase of
(-RECOVER or -ROLLBACK) -BACKWARD command.
-EXTRACT applies to forward processing of the journal file; if the
combined state of the journal file and the Journal Time qualifiers does
not cause forward processing, -EXTRACT does not create an output file.
When used independent of -RECOVER (or -ROLLBACK), -EXTRACT option can
produce a result even though the database file does not exist, although it
does try to access the database if it is available.
If a database having custom collation is inaccessible or the replication
instance is frozen with a critical section required for the access held by
another process and the environment variable gtm_extract_nocol is defined
and evaluates to a non-zero integer or any case-independent string or
leading substrings of "TRUE" or "YES", MUPIP JOURNAL -EXTRACT issues the
DBCOLLREQ warning and proceeds with the extract using the default
collation. If gtm_extract_nocol is not set or evaluates to a value other
than a positive integer or any case-independent string or leading
substrings of "FALSE" or "NO", MUPIP JOURNAL -EXTRACT exits with the
SETEXTRENV error if it encounters such a situation. Note that if default
collation is used for a database with custom collation, the subscripts
reported by MUPIP JOURNAL -EXTRACT are those stored in the database, which
may differ from those read and written by application programs.
Note that, a broken transaction, if found, is extracted to a broken
transaction file for details), and all future complete transactions are
considered as lost transactions, and are extracted to a lost transaction
file for details).
To avoid broken transaction or lost transaction processing and instead
extract all journal records into one file, use the control qualifier
-FENCES=NONE. FIS strongly recommended against using -FENCES=NONE if
-RECOVER/-ROLLBACK is also specified.
4 RECover
RECover
Instructs MUPIP JOURNAL to initiate database recovery. -RECOVER initiates
the central JOURNAL operation for non-replicated database. From the list
of JOURNAL action qualifiers, select RECOVER alone or with any other
action qualifiers except -ROLLBACK.
-RECOVER -FORWARD with time qualifiers initiates forward recovery. Forward
recovery ignores the current journaling state of the target database file.
It disables journaling of the target database file, (if currently ENABLE
and ON), while playing forward the database updates. However, it restores
the journaling state of the database at the end of a successful recovery
(if necessary), except when journaling is ENABLE'd and ON before the
recovery. In the latter case, the journaling state at the end of a
successful recovery, is switched to ENABLE and OFF. No journaling is
performed for the logical updates to the database for JOURNAL -RECOVER
-FORWARD. If the target database's current transaction number is less than
first transaction number to be processed in the specified journal file for
that region, -RECOVER attempts to include previous generation journal
file(s) in its processing, unless the -NOCHAIN qualifier is specified.
Following the successive previous links of journal files -RECOVER tries to
include previous generations of journal files until the transaction number
when the journal file was created is less than, or equal to that of the
target database. -RECOVER issues one or more informational messages when
it includes previous generation journal files. If target database's
current transaction number is not equal to the first transaction number of
the earliest journal file to be processed for a region, -RECOVER exits
with an error. If multiple journal files for a single region are specified
with -RECOVER -FORWARD, it behaves as if -NOCHAIN was specified. If the
journal files are not a complete set (for example mumps1.mjl and
mumps3.mjl were specified, with mumps2.mjl missing from the command line),
MUPIP JOURNAL produces an error because the journal files specified are
discontinuous in terms of database transaction numbers. On the other hand,
specifying just mumps3.mjl automatically includes mumps2.mjl and
mumps1.mjl in the recovery.
-RECOVER -BACKWARD with time qualifiers initiates backward recovery. For
backward recovery, the target database file should be the same as when
GT.M wrote the last complete transaction to the journal. Because the
database may be in an indeterminate state due to a failure, exact checks
for this match are not possible. If the target database has journaling
DISABLE'd (or ENABLE, OFF), -RECOVER -BACKWARD exits with an error
message.
If the target database has journaling ENABLE, ON, but the journal file
name in database file header does not match the latest generation journal
file name specified for that region, -RECOVER exits with an error.
During forward processing phase of JOURNAL -RECOVER -BACKWARD, MUPIP
journals the logical updates to the database. It also creates before
images. It is always required to have journaling ENABLE'd and ON for
-RECOVER -BACKWARD or -ROLLBACK.
If a transaction is found with incomplete fence, it is considered broken.
During forward phase of recovery, if a complete transaction (fenced or
unfenced) is found after a broken transaction. -RECOVER increments the
error count. If -ERRORLIMIT is reached, the complete transaction goes to
lost transaction file, otherwise, it is applied to the database.
All broken and lost transactions are made available as the result of the
-RECOVERY. They are written as journal extract format in two different
text files. They are the broken transaction file and the lost transaction
file.
When performing JOURNAL -RECOVER with fences (FENCES="PROCESS" or
FENCES="ALWAYS"), it is essential for the command to include all the
journal files corresponding to the complete set of database files that
make up the logical database. If the specified set of journals is
incomplete, the recovery reports all transactions that included any
missing region as broken. Typically, this means that the results of the
recovery are unsatisfactory or even unusable.
MUPIP JOURNAL -RECOVER requires exclusive access to database files before
recovery can occur. It keeps the exclusive access to the database files,
which means that the database files become inaccessible during the time of
recovery.
If time qualifiers are not specified, -BACKWARD -RECOVER/-ROLLBACK
performs optimal recovery. An optimal recovery checks whether the
datatabase is in a wholesome state and attempts to perform an automatic
recovery if there is a crash. If needed, optimal recovery goes back to
include some previous generation files in order to get a consistent
starting point and then comes forward as far as the available journal
record allow it to while preserving consistent application state. At the
end, the journaling state of the database stays ENABLE, ON. Note that the
gtm script performs an optimal recovery on every run.
When a database file is rolled back by -RECOVER -BACKWARD, the
corresponding journal file is also rolled back so that the two are
synchronized. -RECOVER -BACKWARD then creates a new journal file. If no
forward play of journal records is neccessary, the newly created journal
file stays empty and the database points to the new journal file. The
values for journal allocation and extension in the new journal file, are
copied over from the database. The autoswitchlimit value in the new
journal file is the maximum of the autoswitchlimit values of all journal
files from the latest generation journal file until the turnaround point
journal file generation (turnaround point is the point in the journal file
where backward processing stops and forward processing begins). The
journal allocation/extension values in the new journal file are picked up
from the earliest generation of the set of those journal files sharing the
maximum autoswitchlimit value.
GT.M adds a prefix rolled_bak_ to the journal file whose entire contents
are eliminated (rolled back) by -RECOVER -BACKWARD. GT.M does not use
these files after a successful recovery therefore you might want to
consider moving or deleting them. You should never use rolled_bak* files
for any future database recovery. If there is a need to process
rolled_bak* files, you should extract the journal records from
rolled_back* files and process them using a M program.
4 ROLLBACK
ROLLBACK
-ROLLBACK initiates the central JOURNAL operation for a replicated
database. MUPIP JOURNAL commands may specify -ROLLBACK with other action
qualifiers but not with -RECOVER. If you do not use -FETCHRESYNC, the
database rolls back to the last consistent state. Only asterisk (*)
qualifier is allowed for the journal file selection, that is, -ROLLBACK
selects journal files by itself.
-NOO[NLINE]
Specifies that ROLLBACK requires exclusive access to the database and the
replication instance file. This means that the database and the
replication instance files are inaccessible during a -ROLLBACK -NOONLINE.
By default, MUPIP JOURNAL -ROLLBACK is -NOONLINE.
-ON[LINE]
Specifies that ROLLBACK should run without requiring exclusive access to
the database and the replication instance file.
GT.M increments ISV $ZONLNRLBK every time a process detects a concurrent
MUPIP JOURNAL -ONLINE -ROLLBACK.
If the logical state of the database after the completion of MUPIP JOURNAL
-ONLINE -ROLLBACK matches the logical state of the database at the start
of MUPIP JOURNAL -ONLINE -ROLLBACK, that is, only removes or commits an
uncommitted TP transaction or non-TP mini-transaction, any transaction (TP
or Non-TP) incurs a restart.
If MUPIP JOURNAL -ONLINE -ROLLBACK changes the logical state of the
database, the behavior is as follows:
o -ONLINE -ROLLBACK increments ISV $ZONLNRLBK
o In a TP transaction including trigger code within a transaction,
-ONLINE -ROLLBACK restarts the transaction.
o In a non-TP mini-transaction, including within an implicit transaction
caused by a trigger, -ONLINE -ROLLBACK produces a DBROLLEDBACK error,
which, in turn, invokes the error trap if $ETRAP or $ZTRAP are in
effect.
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.
**Note**
Because MUPIP ROLLBACK -ONLINE can take a database backwards in state
space, please make sure that you understand what it is that you intend it
to do when you invoke it. FIS developed it as a step towards a much larger
project and anticipates that it will not be broadly useful as is.
-ROLLBACK -BACKWARD exits with an error message for following conditions:
1. Any database region corresponding to a journal file processed has
replication state turned OFF. Note that, a configuration where there
are replicated regions and at least one non-replicated-but-journaled
region is not permitted by the replication source server. The source
server errors out at startup on such a configuration without having
set up the journal pool. Since all GT.M updates to replicated regions
need the source server to have set up a journal pool, no updates are
possible until the configuration is changed to have only replicated
regions or non-replicated-and-non-journaled regions.
2. Any database region corresponding to a journal file identified by the
command argument has journaling state DISABLE'd or ENABLE'd and OFF.
3. Any database region corresponding to a journal file has journal state
ENABLE'd and ON, but the journal file name specified in the database
file header is different than one identified by the command argument.
If a transaction is found with incomplete fence, it is considered broken.
For the duration of the rollback, replication is turned OFF on all regions
and turned back ON at the end of the rollback.
During the forward phase of rollback, if a complete transaction (fenced or
unfenced) is found after a broken transaction, it is considered as a lost
transaction. During forward phase of rollback, MUPIP journals the logical
updates to the database. All broken and lost transactions are made
available as a result of the rollback. These are written as journal
extract format in two different text files.
When a database file is rolled back by -ROLLBACK, the corresponding
journal file is also rolled back so that the two are synchronized.
-ROLLBACK then creates a new journal file. If no forward play of journal
records is necessary, the newly created journal file is empty and the
database points to the new journal file. The journal
allocation/extension/autoswitchlimit values in the new journal file is set
in the way as described for -RECOVER -BACKWARD in the previous section
under -RECOVER.
A prefix rolled_bak_ is added to the journal file, whose entire contents
are eliminated by a -ROLLBACK. These files are not used by GT.M after the
MUPIP JOURNAL -RECOVER, and can be moved/deleted as needed.
For -ROLLBACK the target database file should be the same as when GT.M
wrote the last complete transaction to the journal.
If the -FETCHRESYNC or -RESYNC qualifiers are not specified, MUPIP does an
optimal rollback (that is, check whether the database is in a wholesome
state and attempt to automatically recover a database if there is a
crash).
**Note**
If ROLLBACK (either -NOONLINE or -ONLINE) terminates abnormally (say
because of a kill -9), it leaves the database in a potentially
inconsistent state indicated by the FILE corrupt field in the database
file header. When a ROLLBACK terminates leaving this field set, all other
processes receive DBFLCORRP errors any time they attempt to interact with
the database. You can clear this condition as following in descending
order of risk:
o Rerun ROLLBACK to completion
o MUPIP SET -FILE -PARTIAL_RECOV_BYPASS
o DSE CHANGE -FILEHEADER -CORRUPT=FALSE -NOCRIT
However, the MUPIP and DSE actions do not ensure that the database has
consistent state; check for database integrity with MUPIP INTEG.
4 SHow
SHow
Specifies which information for the JOURNAL command to display about a
journal file.
Use -FORWARD with -SHOW together (but without -RECOVER ) to process the
entire journal file. Specify -SHOW with -RECOVER (or -ROLLBACK) to
consider all the journal files/records processed during a -RECOVER
-FORWARD command or forward phase of a -RECOVER (or -ROLLBACK) -BACKWARD
command. Without -RECOVER (or -ROLLBACK), -SHOW does not require database
access.
The show-option-list includes (these are not case-sensitive):
o AL[L]
Displays all the available type of information about the journal file.
ALL is the default if you omits the show-option-list.
o AC[TIVE_PROCESSES]
Displays all processes active at the end of the period specified
implicitly or explicitly by the JOURNAL command time qualifiers.
o B[ROKEN_TRANSACTIONS]
Display all processes that had incomplete fenced transactions at the
end of the period covered by the JOURNAL command.
o H[EADER]
Displays the journal file header information. If the MUPIP JOURNAL
command includes only the -SHOW=HEADER action qualifier, GT.M
processes only the journal file header (not the contents) even if you
specify -BACKWARD or -FORWARD with it. The size of a journal file
header is 64K.
HEADER displays almost all the fields in the journal file header. The
NODE field is printed up to a maximum of the first 12 characters. The
following is an example of SHOW=HEADER output:
-------------------------------------------------------------------------------
SHOW output for journal file /home/jdoe/.fis-gtm/V6.0-000_x86/g/gtm.mjl
-------------------------------------------------------------------------------
Journal file name /home/jdoe/.fis-gtm/V6.0-000_x86/g/gtm.mjl
Journal file label GDSJNL23
Database file name /home/jdoe/.fis-gtm/V6.0-000_x86/g/gtm.dat
Prev journal file name /home/jdoe/.fis-gtm/V6.0-000_x86/g/gtm.mjl_2012310190106
Next journal file name
Before-image journal ENABLED
Journal file header size 65536 [0x00010000]
Virtual file size 2048 [0x00000800] blocks
Journal file checksum seed 2272485152 [0x87735F20]
Crash FALSE
Recover interrupted FALSE
Journal file encrypted FALSE
Journal file hash 00000000000000000000000000000000000
Blocks to Upgrade Adjustment 0 [0x00000000]
End of Data 65960 [0x000101A8]
Prev Recovery End of Data 0 [0x00000000]
Endian Format LITTLE
Journal Creation Time 2012/11/06 17:30:33
Time of last update 2012/11/06 17:30:33
Begin Transaction 1 [0x0000000000000001]
End Transaction 1 [0x0000000000000001]
Align size 2097152 [0x00200000] bytes
Epoch Interval 300
Replication State CLOSED
Jnlfile SwitchLimit 8386560 [0x007FF800] blocks
Jnlfile Allocation 2048 [0x00000800] blocks
Jnlfile Extension 2048 [0x00000800] blocks
Maximum Journal Record Length 1048672 [0x00100060]
Turn Around Point Offset 0 [0x00000000]
Turn Around Point Time 0
Start Region Sequence Number 1 [0x0000000000000001]
End Region Sequence Number 1 [0x0000000000000001]
Process That Created the Journal File:
PID NODE USER TERM JPV_TIME
---------------------------------------------------------
0000006706 jdoe-laptop jdoe 0 2012/11/06 17:30:33
Process That First Opened the Journal File:
PID NODE USER TERM JPV_TIME
---------------------------------------------------------
0000006706 jdoe-laptop jdoe 0 2012/11/06 17:30:33
o P[ROCESSES]
Displays all processes active during the period specified implicitly
or explicitly by the JOURNAL command time qualifiers.
o S[TATISTICS]
Displays a count of all journal record types processed during the
period specified implicitly or explicitly by the JOURNAL command time
qualifiers.The following is an example of SHOW=STATISTICS output:
-------------------------------------------------------------------------------
SHOW output for journal file /home/jdoe/.fis-gtm/V6.0-000_x86/g/gtm.mjl
-------------------------------------------------------------------------------
Record type Count
----------------------
*BAD* 0
PINI 2
PFIN 2
ZTCOM 0
KILL 1333533
FKILL 0
GKILL 0
SET 0
FSET 0
GSET 0
PBLK 4339
EPOCH 2
EOF 1
TKILL 0
UKILL 0
TSET 0
USET 0
TCOM 0
ALIGN 49
NULL 0
ZKILL 0
FZKIL 0
GZKIL 0
TZKIL 0
UZKIL 0
INCTN 4314
AIMG 0
TZTWO 0
UZTWO 0
TZTRI 0
UZTRI 0
TRUNC 0
%GTM-S-JNLSUCCESS, Show successful
%GTM-S-JNLSUCCESS, Verify successful
%GTM-I-MUJNLSTAT, End processing at Tue Nov 6 17:42:21 2012
The following example displays the cryptographic hash of the symmetric key
stored in the journal file header (the output is one long line).
$ mupip journal -show -backward mumps.mjl 2>&1 | grep hash
Journal file hash F226703EC502E975784
8EEC733E1C3CABE5AC146C60F922D0E7D7CB5E
2A37ABA005CE98D908B219249A0464F5BB622B72F5FDA
0FDF04C8ECE52A4261975B89A2
4 Verify
Verify
Verifies a journal file for integrity. This qualifier cannot have a value.
-VERIFY scans the files and checks if it is in legal form, if not, it
terminates without affecting the database files.
-VERIFY when specified along with -FORWARD verifies the entire journal
file For -NOVERIFY -FORWARD, only the tail of a journal file is verified
for cross region integrity. In both cases, if -RECOVER is also specified,
the forward play of journal records is done in a separate pass only after
the verification pass is complete and error-free.
-VERIFY along with -BACKWARD verifies all journal records from the end of
the journal file till the turn around point. When -VERIFY -BACKWARD is
specified along with -RECOVER or -ROLLBACK, backward processing involves
two passes, the first pass to do the verification until the turn around
point, and the second pass to apply before image (PBLK) records.
When -NOVERIFY -BACKWARD is specified along with -RECOVER or -ROLLBACK,
PBLKs are applied to the database in the same pass as the verification.
This speeds up processing. But the disadvantage of this approach is that
in the event of verification terminating in the middle of backward
processing, there is no protection of cross-region integrity. FIS
recommends the use of -VERIFY with -RECOVER or -ROLLBACK.
When used independent of -RECOVER (or -ROLLBACK), -[NO]VERIFY option does
not need database access. The default is -VERIFY.
3 Direction_Qualifiers
Direction Qualifiers
The following two qualifiers control the journal processing direction:
-BACKWARD
Specifies that MUPIP JOURNAL processing should proceed from the end of the
journal file. If the actions include -RECOVER, JOURNAL -BACKWARD restores
before-images from the end-of the file back to an explicitly or implicitly
specified point (the turn around point), before it reverses and processes
database updates in the forward direction (the forward phase).
**Note**
-BACKWARD is incompatible with -FORWARD.
-FO[RWARD]
Specifies that MUPIP JOURNAL processing for the specified action qualifier
should proceed from the beginning of the given journal file. When
processing a -RECOVER action qualifier, in certain cases, MUPIP JOURNAL
may need to go before the first record of the specified journal file, that
is, it can start from a previous generation journal file.
If multiple journal files are specified in the command line, -FORWARD
sorts the journal files within each region based on creation time and
processes them starting from the earliest journal file. Unless the
-NOCHECKTN qualifier is specified, -FORWARD performs checks on journal
files corresponding to each region to ensure they are contiguous, both in
terms of time span, as well as, transaction number span. -FORWARD errors
out if it detects a discontinuity.
**Note**
-FORWARD is incompatible with -BACKWARD and -ROLLBACK.
3 Time_Qualifiers
Time Qualifiers
Journal qualifiers specifying time accept arguments in absolute or delta
time format. Enclose time arguments in quotation marks (" ") . Include a
back-slash (\) delimiter before both, the beginning and ending quotation
marks to escape it from being processed by the UNIX shell.
Absolute format is day-mon-yyyy hh:mm:ss , where day denotes the date of
the month, mon indicates the abbreviated 3-letter month name (for example,
Jan, Feb,..) and the year yyyy and hour hh are separated by a space.
Absolute time may indicate today's date with "-- " before the hours.
Delta format is day hh:mm:ss, indicating the number of days, hours,
minutes, and seconds; where the day and the hours (hh) are separated by a
space. If delta time is less than a day, it must start with zero (0)
followed by a space.
Delta time is always relative to the maximum time of the last record in
all journal files specified by arguments to the MUPIP JOURNAL command.
**Note**
All time qualifiers are incompatible with -ROLLBACK.
The following section describes the time qualifiers in more detail:
-A[FTER]=time
Specifies reference time stamps in the journal and identifies the point
after which JOURNAL starts processing in the journal file(s). This time
qualifier applies to -FORWARD only.
If -AFTER= provides a time following the last time recorded in the journal
file or following any -BEFORE= time, JOURNAL processing produces no result
and a warning message is displayed. If -AFTER provides a time preceding
the first time recorded in the journal file specified in the command line,
and, previous generation journal file(s) exists for that journal file,
then previous generation journal file(s) are not included for the
processing. You must specify previous generation journal files explicitly
in the command line in order for them to be considered.
Using -BEFORE with -AFTER restricts processing to a particular period of
time in the journal file.
-BE[FORE]=time
Specifies an ending time for any action -FORWARD or -BACKWARD. The time
specified references time stamps in the journal files. If -BEFORE=
specifies a time preceding the first time recorded in the journal file, or
preceding any -AFTER= or -SINCE= time, JOURNAL processing produces no
result, and a warning message is displayed.
If -BEFORE= time exceeds the last time recorded in journal files, JOURNAL
processing effectively ignores the qualifier and terminates at the end of
the journal file. By default, JOURNAL processing terminates a t the end of
the journal file.
-[NO]LOO[KBACK_LIMIT][=lookback-option-list]
Specifies how far JOURNAL -BACKWARD processes past the turnaround point
(the explicit or implicit point in journal file up to which -RECOVER
proceeds backward before it reverses and processes database in forward
direction), while attempting to resolve open transaction fences. This
option is applicable only for transactions fenced with ZTSTART and
ZTCOMMIT. For transaction fenced with TSTART and TCOMMIT, -RECOVER always
resolves open transaction fences.
-LOOKBACK_LIMIT=options, include time and transaction counts.
-NOLOOKBACK_LIMIT specifies that JOURNAL -BACKWARD can process all the way
to the beginning of the journal file, if necessary, to resolve open
transaction fences. -LOOKBACK_LIMIT= is incompatible with -FORWARD.
When -FENCES=NONE, JOURNAL processing ignores -LOOKBACK_LIMIT.
The -LOOKBACK_LIMIT options are:
o TIME=time
This limits LOOKBACK by a specified amount of delta or absolute
journal time.
o OPERATIONS=integer
This limits LOOKBACK to the specified number of database transactions.
The TIME LOOKBACK option name and its value must be enclosed in quotes
("").
For example:
-lookback=\"time=0 00:00:30\"
When -LOOKBACK_LIMIT= specifies both options, they must be separated by a
comma (,), for example:
-lookback=\"time=0 00:00:30,operations=35\"
When -LOOKBACK_LIMIT= specifies both options, the first limit reached
terminates the LOOKBACK.
By default, MUPIP JOURNAL uses -LOOKBACK_LIMIT=\"TIME=0 00:05\" providing
five minutes of journal time prior to -SINCE= to resolve open fences. A
-LOOKBACK_LIMIT that specifies a limit much before the beginning of the
earliest journal file acts as if -NOLOOKBACK_LIMIT was specified.
-SI[NCE]=time
Specifies a starting (or checkpoint) time for an action qualifier with
-BACKWARD, that is, -SINCE specifies how far back in time JOURNAL
-BACKWARD should process (from the end of the journal file), before
starting the forward processing.
The time specified references time stamps in the journal files. If there
are open fenced transactions when JOURNAL -BACKWARD locates the -SINCE=
time, it continues processing backward to resolve them, unless the command
also specifies -FENCES=NONE. If -SINCE= time exceeds the last time
recorded in the journal files or, follows any -BEFORE=time, JOURNAL
processing effectively ignores the qualifier, and displays a warning
message.
By default, -SINCE= time is 0 00:00:00 which denotes the time at the end
of the journal file (the time when the last journal record was updated).
3 SEQNO_Qualifiers
SEQNO Qualifiers
These qualifiers are compatible only with -ROLLBACK.
-FET[CHRESYNC]=<port number>
In an LMS configuration, rollbacks the replicating instance to a common
synchronization point from which the originating instance can transmit
updates to allow it to catch up. This command rolls back a former
originating instance to the journal sequence number at which the current
originating instance took over. The format of the fetchresync qualifier
is:
-fetchresync=<port number> -losttrans=<extract file> file-list
The <port number> is the communication port number that the rollback
command uses when fetching the reference point. Always use the same <port
number> on the originating instance for rollback as the one used by the
Receiver Server.
**Important**
FIS recommends you to unconditionally script the mupip journal -rollback
-fetchresync command prior to starting any Source Server on the
replicating instance to avoid a possible out-of-sync situation.
The reference point sent by the originating instance is the RESYNC_SEQNO
(explained later) that the originating instance once maintained. The
database/journal files are rolled back to the earlier RESYNC_SEQNO (that
is, the one received from originating instance or the one maintained
locally). If you do not use -fetchresync, the database rolls back to the
last consistent replicating instance state.
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 originating
instance 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.
**Note**
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.
**Caution**
The database header may get corrupted if you suspend an ongoing ROLLBACK
-FETECHRESYNC operation or if the TCP connection between the two instances
gets broken. The workaround is to restart the ROLLBACK -FETCHRESYNC
operation or wait 60 seconds for the FETCHRESYNC operation to timeout.
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.
-RES[YNC]=<journal sequence number>
Specifies the journal sequence number to which GT.M must rollback the the
database/journal files need to be rolled back to a specific point. If you
specify a journal sequence number that is greater than the last consistent
state, GT.M rolls back the database/journal files to the last consistent
state. Under normal operating conditions, this qualifier is not needed.
3 Control_Qualifiers
Control Qualifiers
The following qualifiers control journal processing:
-[NO]AP[PLY_AFTER_IMAGE]
Specifies that after image records (AIMG) be applied to the database as
part of forward processing of backward recovery or rollback. AIMG are
"snapshots" of the database updates captured by GTM immediately after the
change caused by a DSE update. By default, during forward phase of
backward recovery or rollback, AIMG records are applied to the database.
By default, -RECOVER -FORWARD does not apply AIMG record into the
database. -APPLY_AFTER_IMAGE is compatible with -RECOVER, or -ROLLBACK
action qualifiers only.
-BR[OKENTRANS]=<extract file>
-BROKENTRANS is an optional qualifier for -ROLLBACK, -RECOVER and
-EXTRACT. If this is not specified and a broken transaction file creation
is necessary, MUPIP JOURNAL creates one using the name of the current
journal file being processed with a .broken extension.
Note that, if selection qualifiers are specified, the broken transaction
determination (and therefore lost transaction determination as well) is
done based on the journal file that is filtered by the selection
qualifiers. This means that a transaction's journal records may be
considered complete or broken or lost, depending on the nature of the
selection qualifiers. Using -FENCES=NONE along with the selection
qualifiers will result in every journal record to be considered complete
and hence prevent broken or lost transaction processing.
-[NO]CHA[IN]
-CHAIN allows JOURNAL processing to include previous generations of
journal files with -FORWARD. If JOURNAL -RECOVER needs to process previous
generation journal file(s) and -NOCHAIN is specified, MUPIP JOURNAL exits
with an error.
-CHAIN is the default.
-[NO]CHE[CKTN]
-CHECKTN specifies that JOURNAL -FORWARD must verify for each region that
the begin transaction number of the earliest journal file to be processed
for that region is same as the current transaction in the database file
and that the end transaction number of every journal file is equal to the
the begin transaction number of the next generation journal file for a
given region. By default, -FORWARD uses -CHECKTN.
-NOCHECKTN forces forward recovery by overriding inbuilt mechanisms for
checking transaction integrity. Use -NOCHECKTN with caution because it may
lead to integrity issues in the recovered database and journal files.
-CHECKTN is incompatible with -BACKWARD and -ROLLBACK.
-[NO]ER[ROR_LIMIT][=integer]
Specifies the number of errors that MUPIP JOURNAL processing accepts. When
the number of errors exceeds the -ERROR_LIMIT, the -INTERACTIVE qualifier
determines whether JOURNAL processing halts or defers to the operator.
-NOERROR_LIMIT prevents MUPIP JOURNAL from stopping because of errors.
Journal processing continues until it reaches the end of the journal file,
regardless of the number of errors.
Note that, -NOERROR_LIMIT is not the same as -ERROR_LIMIT=0.
By default, MUPIP JOURNAL uses -ERROR_LIMIT=0, causing the first error to
initiate the appropriate error action. In case of a crash there could be
some incomplete journal records at the end of a journal file. MUPIP
JOURNAL does not consider these as errors. In addition, fenced
transactions that are broken are not considered as errors.
During the forward phase of recovery, if a broken transaction is found,
all the logical records processed afterwards are considered suspect. If a
complete transaction is found after any broken transactions, MUPIP JOURNAL
-RECOVER increments the error count and, if it is less than the error
limit, it is applied to the database. Otherwise, it is treated as a lost
transaction and extracted. If a complete transaction is found after any
broken transactions, MUPIP JOURNAL -ROLLBACK treats it as a lost
transaction and extracts it irrespective of the error limit.
If MUPIP JOURNAL needs to increment error count during its processing, a
warning message is issued for every error encountered except in the
following cases when the error count is incremented but no warning message
is displayed:
o When a complete transaction is found after a broken transaction
o When -EXTRACT -FULL encounters errors
If MUPIP JOURNAL completes successfully with a non-zero value of error
count, the return status is not a success, but a warning.
-FE[NCES][=fence-option]
Specifies how JOURNAL processes fenced transactions. Fenced transactions
are logical transactions made up of database updates preceded by a TSTART
or ZTSTART command and followed, respectively, by a TCOMMIT or ZTCOMMIT
command. All updates between a TSTART or ZTSTART and a TCOMMIT or ZTCOMMIT
are designed to occur together so that after journal recovery the database
contains either all the updates corresponding to a fenced transaction, or
none of them.
The argument values for -FENCES option for MUPIP -RECOVER are not
case-sensitive.
The fence options are:
o NONE
This causes MUPIP JOURNAL to apply all individual updates as if
transaction fences did not exist. Note that, this means a SET/KILL
within a TP or ZTP transaction would be played as if it was an
unfenced SET/KILL. This may cause the database and new journals
created (if -BACKWARD is specified), to be different from the state
before the recovery took place.
o ALWAYS
This causes MUPIP JOURNAL to treat any unfenced or improperly fenced
updates as broken transactions.
o PROCESS
This causes MUPIP JOURNAL to accept unfenced database updates, and
also to observe fences when they appear, generating broken transaction
files in the case of a TSTART with no corresponding TCOMMIT, or a
ZTSTART with no corresponding ZTCOMMIT. It also generates broken
transactions if a multi-region transaction with TSTART and TCOMMIT
expects N regions to participate, but the number of TSTART/TCOMMIT
pairs found is less than N. The same happens for multi-region ZTSTART
and ZTCOMMIT.
By default, MUPIP JOURNAL uses -FENCES=PROCESS.
-FU[LL]
-FULL when used with -EXTRACT, specifies that all journal records be
extracted. A journal file's contents can be rolled back in case of
backward recovery or rollback in order to keep the database and journal in
sync. This is achieved not by truncating the contents of the journal file
but instead setting a field in the journal file header, which shows up as
"Prev Recovery End of Data" in a MUPIP JOURNAL -SHOW=HEADER output, to
indicate the end of the journal file before rolling back and setting
another field in the file header to indicate the new end of the journal
file (this field shows up as "End of Data" in a MUPIP JOURNAL -SHOW=HEADER
output). Once a journal file's contents are rolled back, all future MUPIP
JOURNAL commands (including -EXTRACT) operate on the rolled back journal
file only. But if -FULL is specified along with -EXTRACT, the entire
journal file contents (including those records that were rolled back) are
extracted. This qualifier is to be used only as a diagnostic tool and not
in normal operation.
-FULL qualifier is compatible with -EXTRACT only.
-[NO]IN[TERACTIVE]
Specifies whether, for each error over the -ERROR_LIMIT, JOURNAL
processing prompts the invoking operator for a response to control
continuation of processing. If the operator responds that processing
should not continue, the MUPIP JOURNAL command terminates.
-NOINTERACTIVE terminates the journal processing as soon as the MUPIP
JOURNAL command generates the number of errors specified in -ERROR_LIMIT.
This qualifier is applicable only to interactive mode or terminal mode.
The default is -INTERACTIVE.
-LOST[TRANS]=<extract file>
-LOSTTRANS is an optional qualifier for -RECOVER, -ROLLBACK and -EXTRACT.
If this is not specified and a lost transaction file creation is
necessary, MUPIP JOURNAL creates one using the name of the current journal
file being processed with a .lost extension.
Any complete transactions after a broken transaction is considered a lost
transaction. They are written into the lost transaction file. For -RECOVER
it might be considered as good transaction and applied to the database, if
-ERROR_LIMIT qualifier allows it to do so.
Note that, if selection qualifiers are specified, the broken transaction
determination (and therefore lost transaction determination as well) is
done based on the journal file that is filtered by the selection
qualifiers. This means that a transaction's journal records may be
considered complete or broken or lost, depending on the nature of the
selection qualifiers. Using -FENCES=NONE along with the selection
qualifiers will result in every journal record to be considered complete
and hence prevent broken or lost transaction processing.
In the case of a replicated database, lost transaction can have an
additional cause. If failover occurs (that is, the originating Source
Server, A, fails and the replicating Source Server, B, assumes the
originating instance's role), some transactions committed to A's database
may not be reflected in B's database. Before the former originating
instance becomes the new replicating instance, these transactions must be
rolled back. These transactions are known as "lost transactions". Note
that these are complete transactions and different from a broken
transaction. MUPIP JOURNAL -ROLLBACK stores extracted lost transactions in
the extract-file specified by this qualifier. The starting point for the
search for lost transactions is the journal sequence number obtained from
the originating Source Server in the -FETCHRESYNC operation.
-RED[IRECT]=file-pair-list
Replays the journal file to a database different than the one for which it
was created. Use -REDIRECT to create or maintain databases for training or
testing.
This qualifier applies to -RECOVER action and -FORWARD direction qualifier
only. JOURNAL rejects -REDIRECT unless it appears with -RECOVER.
The file-pair-list consists of one or more pairs of file-names enclosed in
parentheses () and separated by commas (,). The pairs are separated by an
equal sign in the form:
old-file-name=new-file-name
where the old file-name identifies the original database file and the new
file-specification file-name identifies the target of the -RECOVER. The
old-file-specification can always be determined using -SHOW.
By default, JOURNAL directs -RECOVER to the database file from which the
journal was made. -REDIRECT is not compatible with -ROLLBACK.
Example:
$ mupip journal -recover -forward -redirect="bgdbb.dat=test.dat" bgdbb.mjl
This JOURNAL command does a forward recovery that -REDIRECTs the updates
in bgdbb.mjl from bgdbb.dat to test.dat.
-VERB[OSE]
Prints verbose output in the course of processing. It is not negatable and
it is set to OFF by default.
3 Selection_Qualifiers
Selection Qualifiers
Journal Selection Qualifiers are compatible with -EXTRACT and -SHOW
operations only. This is because most applications are not constructed to
safely remove a subset of transactions based on criteria that is exterior
to the application design. To exclude transactions from a recovery based
on some selection criteria, the methodology is to -EXTRACT the records,
and then reapply them through application logic rather than by journal
recovery. This approach permits the application logic to appropriately
handle any interactions between the removed and the retained transactions.
Note that, selection qualifiers might result in only a subset of a fenced
transaction's journal records to be extracted (for example, a TSTART
record may not be extracted because the first update in that transaction
was filtered out by a selection qualifier, while the corresponding TCOMMIT
record may get extracted). This can cause a fenced transaction to seem
broken when actually it is not.
The following qualifiers control the selection criteria for journal
processing.
Except for -TRANSACTION, all qualifiers allow for specifying a comma (,)
seperated list of values.
-G[LOBAL]=global-list
Specifies globals for MUPIP JOURNAL to include or exclude from processing.
You might find this qualifier useful for extracting and analyzing specific
data.
The global-list contains one or more global-names (without subscripts)
preceded by a caret symbol (^). To include more than one global use one of
the following syntaxes.
$ mupip journal -forward -extract -global="^A*,^C" mumps.mjl
or
$ mupip journal -forward -extract -global="(^A*,^C)" mumps.mjl
The names may include the asterisk (*) wildcard. That is, -GLOBAL="^A*"
selects all global variables with names starting with A. The entire list
or each name may optionally be preceded by a tilda sign (~), requiring
JOURNAL to exclude database updates to the specified global(s). When the
global-list with a MUPIP JOURNAL -GLOBAL does not start with a tilda sign
(~), JOURNAL processes only the explicitly named globals. By default,
JOURNAL processes all globals.
To specify subscripts, using -GLOBAL="^A(1)" results in all keys under the
^A(1) tree to be included, that is, it is equivalent to using
-GLOBAL="^A(1,*)". An asterisk (*) or a percent (%) anywhere in the global
specification is permitted. Percent (%) matches any character, and
asterisk (*) matches any string (possibly zero length too). The asterisk
(*) or percent (%) specification can be used for -USER qualifier too.
Example:
To extract all ^GBL* except for ^GBLTMP:
$ mupip journal -extract -global="^GBL*,~^GBLTMP" -forward mumps.mjl
To extract all ^GBL except for ^GBL(1,"TMP"):
$ mupip journal -extract -global=\"^GBL,~^GBL\(1,\"\"TMP\"\"\)\" -forward mumps.mjl
The backslash (\) delimiter characters are required in UNIX to pass MUPIP
the double quotes (") of the string subscript.
An INVGLOBALQUAL error is issued along with the error offset in the
command line, whenever a parse error of the global qualifier string is
encountered.
-ID=pid-list
Specifies that JOURNAL processing include or exclude database updates
generated by one or more processes, identified by process identification
numbers (PIDs). The entire list or each PID may optionally be preceded by
a tilda sign (~), requiring JOURNAL to exclude database updates initiated
by the specified PID. You may use this qualifier for trouble shooting or
analyzing data.
By default, JOURNAL processes database updates regardless of the PID that
initiated it.
-T[RANSACTION]=transaction-type
Specifies transaction-types for JOURNAL to include or exclude from
processing. For example, you may use this qualifier to report only on KILL
operations to locate possible causes for missing data.
The transaction-types are SET and KILL and can be negated. These types
correspond to the M commands of the same names. When the transaction-type
with a JOURNAL -TRANSACTION is not negated, JOURNAL processes only
transactions of the type named (for example, -TRANSACTION=KILL), whereas
if it is negated, JOURNAL does not process transactions of the type named
(for exmaple, -TRANSACTION=NOKILL).
By default, JOURNAL processes transactions, regardless of its type.
-U[SER]=user-list
Specifies that MUPIP JOURNAL processing include or exclude database
updates generated by one or more users. You can use this qualifier to
audit the actions of a particular user. The user-list contains names of
one or more users. Indicate multiple users by separating the names with
commas (,). The names may include the wildcard asterisk (*). The entire
list or each name may optionally be preceded by a minus sign (-) tilda
sign (~), requiring JOURNAL to exclude database updates initiated by the
specified user(s). When the user-list with a JOURNAL -USER does not start
with a tilda sign (~), JOURNAL processes only those database updates,
which are generated by explicitly named users. The asterisk (*) or percent
(%) specification can be used for -USER qualifier. Percent (%) matches any
character, and asterisk (*) matches any string (possibly zero length too).
By default, JOURNAL processes database updates regardless of the user who
initiated them.
2 Extract_Formats
Extract Formats
Journal EXTRACT files always start with a label. For the current release
of GT.M, the label is GDSJEX06 for a simple journal extract file. This
label is necessary to identify the format of the file.
If the environment variable gtm_chset is set of UTF-8, then file format
label is followed by another label called "UTF-8" to indicate UTF-8 mode.
After this label, the journal record extracts follow. These journal record
extracts include fields or pieces delimited by a back slash (\).
The first piece of an -EXTRACT output record contains a two-digit decimal
transaction record type (for example, 01 for a process initialization
record). The second piece contains the full date and time of the
operation, represented in the $HOROLOG format. The third piece contains a
GT.M assigned number (database transaction number) which uniquely
identifies the transaction within the time covered by the journal file.
The fourth piece contains the process ID (PID) of the process that
performed the operation, represented as a decimal number. The remainder of
the record depends on the record type.
Records of type SET, KILL, ZKILL, TSTART, and TCOMMIT include the
token_seq as part of the output. It is the sixth field in the output of
the journal record extract. When replication is in use, token_seq is a
journal sequence number (jsnum) that uniquely identifies each transaction.
When replication is not in use and the transaction is a TP or ZTP
transaction, token_seq is an 8-byte token that uniquely identifies the
entire TP or ZTP transaction. For non-replicated, non-TP, and non-ZTP
journal records, token_seq has a zero (0) value.
The format of the plain journal extract is as follows:
NULL 00\time\tnum\pid\clntpid\jsnum\strm_num\strm_seq
PINI(U) 01\time\tnum\pid\nnam\unam\term\clntpid\clntnnam\clntunam\clntterm
PINI(V) 01\time\tnum\pid\nnam\unam\term\mode\logintime\image_count\pname\clntpid\clntnnam\clntunam\clntterm\clntmode\clntlogintime\clntimage_count\clntpname
PFIN 02\time\tnum\pid\clntpid
EOF 03\time\tnum\pid\clntpid\jsnum
KILL 04\time\tnum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
SET 05\time\tnum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node=sarg
ZTSTART 06\time\tnum\pid\clntpid\token
ZTCOM 07\time\tnum\pid\clntpid\token\partners
TSTART 08\time\tnum\pid\clntpid\token_seq\strm_num\strm_seq
TCOM 09\time\tnum\pid\clntpid\token_seq\strm_num\strm_seq\partners\tid
ZKILL 10\time\tnum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
ZTWORM 11\time\tnum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\ztwormhole
ZTRIG 12\time\tnum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
where:
01 record indicates a process/image-initiated update (PINI) into the
current journal file for the first time.
02 record indicates a process/image dropped interest (PFIN) in the current
journal file.
03 record indicates all GT.M images dropped interest in this journal file
and the journal file was closed normally.
04 record indicates a database update caused by a KILL command.
05 record indicates a database update caused by a SET command.
06 record indicates a ZTSTART command.
07 record indicates a ZTCOMMIT command.
08 record indicates a TSTART command.
09 record indicates a TCOMMIT command.
10 record indicates a database update caused by a ZKILL command.
11 records indicates a value for/from $ZTWORMHOLE (when replication is
turned on).
12 record indicates a ZTRIGGER command.
Journal extracts contain NULL records only in a multisite replication
configuration where triggers or external M-filters are active. Here are
two examples when NULL records are sent to the journal files:
o An external filter on an instance transforms a SET record to a NULL
record that has a different schema.
o If the source side has triggers enabled and its receiver side either
runs a pre-trigger version of GT.M or runs on a platform where
triggers are not supported (for example, AXP VMS or HPUX HPPA),
trigger definition journal records from the source side are
transformed to NULL records on the receiver side.
**Important**
A NULL record does not have global information. Therefore, it resides in
the alphabetically last replicated region of the global directory.
The format of the detail journal extract is as follows:
PINI(U) time\tnum\chksum\pid\nnam\unam\term\clntpid\clntnnam\clntunam\clntterm
PINI(V) time\tnum\chksum\pid\nnam\unam\term\mode\logintime\image_count\pname\clntpid\clntnnam\clntunam\clntterm\clntmode\clntlogintime\clntimage_count\clntpname
PFIN time\tnum\chksum\pid\clntpid
EOF time\tnum\chksum\pid\clntpid\jsnum
SET time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node=sarg
KILL time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
ZKILL time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
ZTWORM time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\ztwormhole
ZTRIG time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
TSTART time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq
TSET time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node=sarg
TKILL time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
TZKILL time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
TZTWORM time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\ztwormhole
TZTRIG time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
USET time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodef
lags\node=sarg
UKILL time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
UZKILL time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
UZTWORM time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\ztwormhole
UZTRIG time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
TCOM time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\partners\tid
INCTN time\tnum\chksum\pid\clntpid\opcode\incdetail
EPOCH time\tnum\chksum\pid\clntpid\jsnum\blks_to_upgrd\free_blocks\total_blks\fully_upgraded[\strm_num\strm_seq]...
PBLK time\tnum\chksum\pid\clntpid\blknum\bsiz\blkhdrtn\ondskbver
AIMG time\tnum\chksum\pid\clntpid\blknum\bsiz\blkhdrtn\ondskbver
NULL time\tnum\pid\clntpid\jsnum\strm_num\strm_seq
ZTSTART time\tnum\chksum\pid\clntpid\token
FSET time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node=sarg
FKILL time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
FZKILL time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
GSET time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node=sarg
GKILL time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
GZKILL time\tnum\chksum\pid\clntpid\token_seq\strm_num\strm_seq\updnum\nodeflags\node
ZTCOM time\tnum\chksum\pid\clntpid\token\partners
ALIGN time\tnum\chksum\pid\clntpid
where:
AIMG records are unique to DSE action and exist because those actions do
not have a "logical" representation.
EPOCH records are status records that record information related to check
pointing of the journal.
NCTN records are the transaction numbers of the sequence of critical
sections in which the process and marked the database blocks of the
globals as previously used but no longer in use in the bit maps.
PBLK records are the before image records of the bit maps.
ALIGN records pad journal records so every alignsize boundary (set with
MUPIP SET -JOURNAL and is visible in DSE DUMP -FILEHEADER output) in the
journal file starts with a fresh journal record. The sole purpose of these
records is to help speed up journal recovery.
Legend (All hexadecimal fields have a 0x prefix. All numeric fields
otherwise are decimal):
+------------------------------------------------------------------------+
| tnum | Transaction number |
|----------------+-------------------------------------------------------|
| chksum | Checksum for the record. |
|----------------+-------------------------------------------------------|
| fully_upgraded | 1 if the db was fully upgraded (indicated by a dse |
| | dump -file -all) at the time of writing the EPOCH |
|----------------+-------------------------------------------------------|
| pid | Process id that wrote the jnl record. |
|----------------+-------------------------------------------------------|
| clntpid | If non-zero, clntpid is the process id of the GT.CM |
| | client that initiated this update on the server side. |
|----------------+-------------------------------------------------------|
| jsnum | Journal sequence number. |
|----------------+-------------------------------------------------------|
| token | Unique 8-byte token. |
|----------------+-------------------------------------------------------|
| | If replication is true and this update originated in |
| | a non-supplementary instance but was replicated to |
| | and updated a supplementary instance, this number is |
| | a non-zero value anywhere from 1 to 15 (both |
| | inclusive) indicating the non-supplementary stream |
| strm_num | number. In all other cases, this stream # value is 0. |
| | In case of an EPOCH record, anywhere from 0 to 16 |
| | such "strm_num" numbers might be displayed depending |
| | on how many sources of supplementary instance |
| | replication have replicated to the instance in its |
| | lifetime. |
|----------------+-------------------------------------------------------|
| | If replication is true and this update originated in |
| | a non-supplementary instance but was replicated to |
| | and updated a supplementary instance, this is the |
| | journal sequence number of the update on the |
| | originating non-supplementary instance. If |
| | replication is true and this update originated in a |
| | supplementary instance, this is the journal sequence |
| strm_seq | number of the update on the originating supplementary |
| | instance. In all other cases, this stream sequence |
| | number is 0. Note that the journal seqno is actually |
| | 1 more than the most recent update originating on |
| | that stream number. In case of an EPOCH record, |
| | anywhere from 0 to 16 such "strm_seq" numbers might |
| | be displayed depending on how many sources of |
| | supplementary instance replication have replicated to |
| | the instance in its lifetime. |
|----------------+-------------------------------------------------------|
| | TRANSACTIONID string (BATCH or any string of |
| | descriptive text chosen by the application) specified |
| | as an argument of the corresponding TSTART command. |
| tid | If TRANSACTIONID is not specified with TSTART, GT.M |
| | sets tid to null. TRANSACTIONID can specify any value |
| | for tid but affects GT.M behavior only when |
| | TRANSACTIONID specifies BATCH or BA. |
|----------------+-------------------------------------------------------|
| token_seq | If replication is turned on, it is the journal |
| | sequence number. If not, it is a unique 8-byte token. |
|----------------+-------------------------------------------------------|
| | =n where this is the nth update in the TP or ZTP |
| updnum | transaction. n=1 for the 1st update etc. 0 for |
| | non-TP. |
|----------------+-------------------------------------------------------|
| | Decimal number interpreted as a binary mask.. |
| | Currently only 5 bits are used. |
| | |
| | o 00001 (1) => update journaled but NOT replicated |
| | (For example, update inside a trigger) |
| | o 00010 (2) => update to a global that had at least |
| | one trigger defined, even if no trigger matched |
| | this update |
| | o 00100 (4) => $ZTWORMHOLE holds the empty string |
| | ("") at the time of this update or was not |
| | referenced during this update |
| | o 01000 (8) => update did not invoke any triggers |
| | even if they existed (For example, MUPIP LOAD) |
| | o 10000 (16) => whether the update (set or kill) is |
| nodeflags | a duplicate. In case of a KILL, it is a kill of |
| | some non-existing node aka duplicate kill. Note |
| | that the dupkill occurs only in case of the |
| | Update Process. In case of GT.M, the KILL is |
| | entirely skipped. In both cases (duplicate set or |
| | kill), only a jnl record is written, the db is |
| | untouched. |
| | |
| | Combinations of the above bits would mean each of the |
| | individual bit characteristics. For example, 00011 => |
| | update within a trigger context, and to a global with |
| | at least one trigger defined. For example, 00011 => |
| | update inside a trigger and to a global with at least |
| | one trigger defined. Certain bit combinations are |
| | impossible. For example, 01001 since GT.M replicates |
| | any update that does not invoke triggers. |
|----------------+-------------------------------------------------------|
| node | Key that is being updated in a SET or KILL. |
|----------------+-------------------------------------------------------|
| sarg | Right-hand side argument to the SET (that is, the |
| | value that the key is being SET to). |
|----------------+-------------------------------------------------------|
| | Number of journaled regions participating in this TP |
| partners | or ZTP transaction (TCOM/ZTCOM record written in this |
| | TP or ZTP) . |
|----------------+-------------------------------------------------------|
| opcode | Inctn opcode. See gdsfhead.h inctn_opcode_t for all |
| | possible values. |
|----------------+-------------------------------------------------------|
| blknum | Block number corresponding to a PBLK or AIMG or INCTN |
| | record. |
|----------------+-------------------------------------------------------|
| bsiz | Block size from the header field of a PBLK or AIMG |
| | record. |
|----------------+-------------------------------------------------------|
| blkhdrtn | Transaction number from the block header of a PBLK or |
| | AIMG record. |
|----------------+-------------------------------------------------------|
| ondskbver | On disk block version of this block at the time of |
| | writing the PBLK or AIMG record. 0 => V4, 1 => V5. |
|----------------+-------------------------------------------------------|
| incdetail | 0 if opcode=1,2,3; blks2upgrd if opcode=4,5,6; blknum |
| | if opcode=7,8,9,10,11,12,13 |
|----------------+-------------------------------------------------------|
| ztwormhole | string corresponding to $ZTWORMHOLE |
|----------------+-------------------------------------------------------|
| blks2upgrd | # of new V4 format bitmap blocks created if |
| | opcode=4,5; csd->blks_to_upgrd if opcode=6 |
|----------------+-------------------------------------------------------|
| uname | Name of the user that wrote this PINI record. |
|----------------+-------------------------------------------------------|
| clntunam | If non-empty, clntunam is the name of the GT.CM |
| | client that initiated this update on the server side. |
+------------------------------------------------------------------------+
1 Replication
Replication
The following MUPIP commands and qualifiers control database replication
in a GT.M environment.
2 Change_replication_state
Change replication state
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.
-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.
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.
2 Create_instance
Create instance
Command Syntax:
mupip replicate -instance_create -name=<instance name> [-noreplace] [-supplementary]
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 gtm_repl_instname is not set
and -name is not specified, GT.M produces an error.
-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.
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.
2 Edit_instance
Edit instance
Command Syntax:
mupip replicate
-edit[instance] {<instance-file>|-source -jnlpool}
{-show [-detail]|-change [-offset=] [-size=] [-value=]}
[-name=<new-name>]
-editinstance
Displays or changes the attributes of the specified instance-file. Use
-editinstance in combination with SHOW or CHANGE qualifiers.
-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.
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.
2 Start_Source_Server
Start Source Server
Command syntax:
mupip replicate -source -start
{-secondary=<hostname:port>|-passive}
[-buffsize=<Journal Pool size in bytes>]
[-filter=<filter command>]
[-freeze[=on|off] -[no]comment[='"<string>"']
[-connectparams=<hard tries>,<hard tries period>,
<soft tries period>, <alert time>, <heartbeat period>,
<max heartbeat wait>]
-instsecondary=<replicating instance name>
-log=<log file name> [-log_interval=<integer>]
{-rootprimary|-propagateprimary} [{-updok|-updnotok}]
[-cmplvl=<compression level>]
Qualifiers:
-replicate
Use this qualifier to access the replication subsystem.
-source
Identifies the Source Server.
-start
Starts the Source Server.
-secondary=<hostname:port>
Identifies the replicating instance. <hostname:port> includes an IP
address (or a hostname that resolves to an IP address) and the port at
which the Receiver Server is waiting for a connection.
-passive
Starts the Source Server in passive mode.
-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.
-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 sets the logging interval to the default value.
-buffsize=<Journal Pool size in bytes>
Specifies 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>
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.
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 mupip replic -source -start -buffsize=$gtm_buffsize
;-instsecondary=$secondary_instance -secondary=$IP_Address:$portno
;-filter='"$gtm_exe/mumps -run ^extfilter"' -log=$SRC_LOG_FILE
;deploys this filter on the Source Server.
set $ztrap="goto err"
set TSTART="08"
set TCOMMIT="09"
set EOT="99"
set log=$ztrnlnm("filterlog")
; use the environment variable filterlog" (if defined)
;to specify which logfile to use
if logersion="" set log="logcharout" char
if $zv["VMS" sechar EOL=$C(13)_$C(10)
else set EOL=$C(10)
open log:newve:sion
use $principal:nowrap
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
... 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
.. ; do not write more than width characters in one output operation to avoid "chopping".
.. ; and/or eol in the middle of output stream
.. ; default width=32K-1
.. ; use $zsubstr to chop at valid character boundary (single or multi byte character)
.. set cntr=0,tmp=filtrOut
.. for quit:tmp="" do
... set cntr=cntr+1,$x=0,record(cntr)=$zsubstr(tmp,1,32767),tmp=$zextract(tmp,$zlength(record(cntr))+1,$zlength(tmp))
... write record(cntr)
. use log
. write "Received: ",EOL,$s(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 log.out 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.
-freeze[=on|off] -[no]comment[='"<string>"']
Promptly 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.
-[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.
-connectparams=<hard tries>,<hard tries period>, <soft tries
period>,<alert time>,<heartbeat period><max heartbeat wait>
Specifies 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.
-instsecondary
Identifies the replicating instance to which the Source Server replicates
data.
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 (kill -9ed). 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 (kill -9ed). 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.
-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.
-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.
-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.
**Important**
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.
-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.
-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 zlib 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 UNIX 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. Simple instructions for compiling zlib on a
number of platforms follow. Although GT.M uses zlib, zlib is not FIS
software and FIS does not support zlib. These instructions are merely
provided as a convenience to you.
If a package for zlib is available with your operating system, FIS
suggests that you use it rather than building your own.
Solaris/cc compiler from Sun Studio:
./configure --shared
make CFLAGS="-KPIC -m64"
HP-UX(IA64)/HP C compiler:
./configure --shared
make CFLAGS="+DD64"
AIX/XL compiler:
./configure --shared
Add -q64 to the LDFLAGS line of the Makefile
make CFLAGS="-q64"
Linux/gcc:
./configure --shared
make CFLAGS="-m64"
z/OS:
Download the zlib 1.1.4 from the libpng project's download page on
SourceForge.com. Use a transfer mechanism that does not perform automatic
conversion to download a source tarball. If pax cannot read the archive,
it is a sign that the download mangled the archive. Use pax to unpack the
tarball, converting files from ASCII to EBCDIC.
pax -r -o setfiletag -ofrom=ISO8859-1,to=IBM-1047 -f zlib-1.1.4.tar.gz
Apply the following patch to the zlib 1.1.4 sources:
---------------------------------- zlib_1.1.4_zos.patch
--------------------------------------------------diff -purN
downloads/zlib/src.orig/configure downloads/zlib/src/configure---
downloads/zlib/src.orig/configure Tue Dec 16 14:09:57 2008+++
downloads/zlib/src/configure Mon Feb 9 14:30:49 2009@@ -116,6 +116,11 @@
else SFLAGS=${CFLAGS-"-Kconform_pic -O"} CFLAGS=${CFLAGS-"-O"}
LDSHARED=${LDSHARED-"cc -G"};;+ OS/390*)+ CC=xlc+ SFLAGS=${CFLAGS-"-qascii
-q64 -Wc,DLL,LP64,XPLINK,EXPORTALL -D_ALL_SOURCE_NOTHREADS"}+
CFLAGS=${CFLAGS-"-qascii -q64 -Wc,DLL,LP64,XPLINK,EXPORTALL
-D_ALL_SOURCE_NOTHREADS"}+ LDSHARED=${LDSHARED-"xlc -qascii -q64
-Wl,dll,LP64,XPLINK "};; # send working options for other systems to
support@gzip.org *) SFLAGS=${CFLAGS-"-O"} CFLAGS=${CFLAGS-"-O"}
Build and install the zlib DLL, placing the xlc compilers in compatibility
to mode by setting the environment variable C89_CCMODE to 1. When not in
compatibility mode, xlc follows strict placement of command line options.
Configure and build the zlib software with ./configure --shared && make.
By default, the configure script places zlib in /usr/local/lib. Install
the software with make install. To ensure that GT.M finds zlib, include
/usr/local/lib in LIBPATH, the environment variable that provides a search
path for processes to use when they link DLLs.
By default, GT.M searches for the libz.so shared library (libz.sl on HPUX
PA-RISC) 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.
2 Shutdown_Source_Server
Shutdown Source Server
Command syntax:
mupip replicate -source -shutdown [-timeout=<timeout in seconds>]
Qualifiers:
-shutdown
Shuts down the Source Server.
-timeout=<timeout in seconds>
Specifies the time (in seconds) the Source Server should wait before
shutting down. If you do not specify -timeout, the default timeout period
is 120 seconds. If you specify -timeout=0 , shutdown occurs immediately.
2 Activate_Passive_Source_Server
Activate Passive Source Server
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>]
-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.
-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.
Example:
$ mupip replicate -source -activate -secondary=localhost:8998 -log=A2B.log -instsecondary=America
This example activates a Source Server from passive mode.
2 Deactive_Active_Source_Server
Deactive Active Source Server
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.
-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.
2 Stop_Source_Filter
Stop Source Filter
There are two ways to stop an active filter on the Source Server.
o Execute mupip replicate -source -stopsourcefilter on the originating
Source Server.
o Specify -stopsourcefilter as an option for starting the Receiver
Server.
2 Check_Server_Health
Check Server Health
Use the following command and qualifier to determine whether the Source
Server is running.
Command syntax:
mupip replicate -source -checkhealth
[-instsecondary=<instance_instance>] [-he[lpers]]
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.
With helpers specified, -checkhealth displays the status of Helper
Processes in addition to the status of Receiver Server and Update Process.
-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
2 Change_Source_log
Change Source log
Command syntax:
mupip replicate -source -changelog -log=<log file name> [-log_interval=<integer>] -instsecondary=<instance_name>
Qualfiers:
-changelog
-instsecondary=<instance_name>
Identifies a Source Server process.
Instructs 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.
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 prior value.
2 Source_Logging
Source Logging
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 prior value.
2 Stop_Source_Server
Stop Source Server
Command Syntax:
mupip replic -source -shutdown [-instsecondary=<instance_name>] [-timeout=<seconds>]
Qualifiers:
-instsecondary=<instance_name>
Identifies a Source Server process.
If -instsecondary is not specified, -shutdown stops all Source Server
processes.
-timeout=<seconds>
Specifies the period of time (in seconds) a Source Server should wait
before shutting down. If you do not specify -timeout, the default timeout
period is 30 seconds. If you specify -timeout=0, shutdown occurs
immediately.
2 Source_backlog
Source backlog
Command syntax:
mupip replicate -source -showbacklog
Qualifiers:
-showbacklog
Reports 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. In the
WAS_ON state, -showbacklog reports the backlog information even if the
Source Server is shut down.
Example:
$ mupip replic -source -showbacklog -inst=INSTB
Wed May 19 18:58:29 2010 : Initiating SHOWBACKLOG operation on source server pid [0] for secondary
instance [INSTB]
101 : 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
1 : sequence number of last transaction sent by source server
%GTM-E-SRCSRVNOTEXIST, Source server for secondary instance INSTB is not alive
2 Process_Lost_Transactions
Process Lost Transactions
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:
o The replicating instance is connected to the originating instance at
the time the command is run on the originating instance.
o The replicating instance is not connected at the time the command is
run on the originating instance but connects to the originating
instance, before the originating instance is brought down.
-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 Zqgbl mod 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.
2 Start_Receiver_Server
Start Receiver Server
Command syntax:
mupip replicate -receiver -start
-listenport=<port number>
-log=<log file name> [-log_interval="[integer1],[integer2]"]
[-autorollback[=verbose]]
[-buffsize=<Receive Pool size in bytes>]
[-filter=<filter command>]
[-noresync]
[-stopsourcefilter]
[-updateresync=</path/to/bkup-orig-repl-inst-file>
{[-resume=<strm_num>|-reuse=<instname>]}
[-initialize] [-cmplvl=n]
Qualifiers:
-receiver
Identifies the Receiver Server.
-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.
-autorollback[=verbose]
Allows the receiving instance of SI or BC replication to roll back as
required when the source instance rolls back with a mupip journal
-rollback -backward command. The optional value keyword VERBOSE allows
roll back to provide more diagnostic information.
**Caution**
As autorollback uses mupip online rollback under the covers, it should be
considered field test grade functionality as long as that function is
considered field test grade functionality.
-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 is set to the default
value.
-stopsourcefilter
Starting the Receiver Server with -stopsourcefilter turns off any active
filter on the originating Source Server. Use this option at the time of
restarting the Receiver Server after a rolling upgrade is complete.
-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:
o To replace an existing replication instance files when an upgrade to a
GT.M version changes the instance file format. Consult the release
notes to determine whether this applies to your upgrade.
o When an existing replication instance file is unusable because it was
damaged or deleted, and is replaced by a new replication instance
file.
o Setting up an A->P configuration for the first time if P is an
existing instance with existing updates that are not, and not expected
to be, in the originating instance.
o Setting up a new replicating instance from a backup of the originating
instance (A->P only) or one of its replicating secondary instances.
o If you are running a GT.M version prior to V5.5-000 and you have to
set up a replicating instance from a backup of an originating
instance.
-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.
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.
-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).
-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 is 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.
2 Start_Update_Process
Start Update Process
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.
o m is the total number of helper processes and n is the number of
reader helper processes, in other words m>=n.
o Helper processes can start only on a receiver server.
o If helper processes are already running, specifying -helpers[=m[,n]]
again starts additional helper processes. There can be a maximum of
128 helper processes for a receiver server.
o If -helpers=0[,n] is specified, GT.M starts no helper processes.
o With the HELPERS qualifier specified but neither m nor n specified,
GT.M starts the default number of helper processes with the default
proportion of roles. The default number of aggregate helper processes
is 8, of which 5 are reader helpers and 3 writers.
o With only m specified, helper processes are started of which
floor(5*m/8) processes are reader helpers.
o With both m and n specified, GT.M starts m helper processes of which n
are reader helpers and m-n are writers. If m<n, mupip starts m
readers, effectively reducing n to m and starting no writers.
o GT.M reports helper processes (for example, by the ps command and in
/proc/<pid>/cmdline on platforms that implement a /proc filesystem) as
mupip replicate -updhelper -reader and mupip replicate -updhelper
-writer.
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
2 Stop_Update_Process
Stop Update Process
Command syntax:
mupip replicate -receiver -shutdown [-updateonly|-helpers] [-timeout=<timeout in seconds>]
Qualifiers:
-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.
-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 Receiver Server should wait
before shutting down. If you do not specify -timeout, the default timeout
period is 30 seconds. If you specify -timeout=0, shutdown occurs
immediately.
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.
2 Check_Receiver_Health
Check Receiver Health
Use the following command to determine whether the Receiver Server is
running.
Command syntax:
mupip replicate -receiver -checkhealth
2 Change_Receiver_log
Change Receiver log
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.
2 Receiver_logging
Receiver logging
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.
2 Receiver_backlog
Receiver backlog
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.
2 Rollback_Database
Rollback Database
Command syntax:
mupip journal -rollback
{[-fetchresync=<port number>|-resync=<JNL_SEQNO>]
[-rsync_strm=<strm_num>]}
-losttrans=<extract file> -backward *
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>
The <port number> is the communication port number that the rollback
command uses when fetching the reference point. Always use the same <port
number> on the originating instance for rollback as the one used by the
Receiver Server.
**Important**
FIS recommends you to unconditionally script the mupip journal -rollback
-fetchresync command prior to starting any Source Server on the
replicating instance to avoid a possible out-of-sync situation.
The reference point sent by the originating instance is the RESYNC_SEQNO
(explained later) that the originating instance once maintained. The
database/journal files are rolled back to the earlier RESYNC_SEQNO (that
is, the one received from originating instance or the one maintained
locally). If you do not use -fetchresync, the database rolls back to the
last consistent replicating instance state.
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 originating
instance 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.
**Note**
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.
**Caution**
The database header may get corrupted if you suspend an ongoing ROLLBACK
-FETECHRESYNC operation or if the TCP connection between the two instances
gets broken. The workaround is to restart the ROLLBACK -FETCHRESYNC
operation or wait 60 seconds for the FETCHRESYNC operation to timeout.
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.
-losttrans=<extract file>
If failover occurs (that is, originating instance fails and replicating
instance assumes the originating instance role), some transactions
committed to A's database may not be reflected in B's database. Before the
former originating instance becomes the new replicating instance, these
transactions must be rolled off before it can assume the role of an
originating instance. 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 originating
instance 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.
**Note**
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.
-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.
1 Summary
Summary
+------------------------------------------------------------------------------+
| COMMAND | OBJECTS | MAIN QUALIFIER |
|-------------+----------------+-----------------------------------------------|
| | |-BK[UPDBJNL]=DISABLE | OFF |
| | |-B[YTESTREAM] -NET[TIMEOUT]=seconds |
| | |-C[OMPREHENSIVE] |
| | |-DA[TABASE] -REPLA[CE] |
| | |-DBG |
| | |-I[NCREMENTAL] |
| |region-name |-[NO]J[OURNAL][=journal-options-list] |
|B[ACKUP] | | |
| |file-name |-NETTIMEOUT |
| | |-[NO]NEWJNLFILES[=[NO]PREVLINK],[NO]S[YNC_IO] |
| | |-O[NLINE] |
| | |-RECORD |
| | |-REPLI[NSTANCE]=OFF | ON |
| | |-S[INCE]={DATABASE|BYTESTREAM|RECORD} |
| | |-T[RANSACTION=hexa;transaction_number] |
|-------------+----------------+-----------------------------------------------|
|CR[EATE] |- |-R[EGION]=region-name |
|-------------+----------------+-----------------------------------------------|
| | |-OUTDB=<outdb-file> |
|EN[DIANCVT] |file-name | |
| | |-OV[ERRIDE] |
|-------------+----------------+-----------------------------------------------|
|EXI[T] |- |- |
|-------------+----------------+-----------------------------------------------|
|EXTE[ND] |region-name |-B[LOCKS]=blocks |
|-------------+----------------+-----------------------------------------------|
| | |-FO[RMAT]=GO|B[INARY]|Z[WR] |
| | |-FR[EEZE] |
| | |-LA[BEL]=text |
|EXTR[ACT] |- | |
| | |-[NO]L[OG] |
| | |-S[ELECT]=global-name-list |
| | |-O[CHSET]=character-set |
|-------------+----------------+-----------------------------------------------|
| | |-DBG |
| | |-OF[F] |
|F[REEZE] |region-list | |
| | |-OV[ERRIDE] |
| | |-ON[-R[ECORD]] |
|-------------+----------------+-----------------------------------------------|
| | |-D[B] |
|FT[OK] |File-name |-J[NLPOOL] |
| | |-R[ECVPOOL] |
|-------------+----------------+-----------------------------------------------|
|H[ELP] |command-option |- |
|-------------+----------------+-----------------------------------------------|
| | |-A[DJACENCY]=integer] |
| | |-BL[OCK]=hexa;block-number] |
| | |-BR[IEF] |
| | |-FA[ST] |
| | |-FI[LE] |
| | |-FU[LL] |
| |File-name or | |
|I[NTEG] |region-list |-NO]K[EYRANGES |
| | |-[NO][MAP]=integer |
| | |-[NO]MAXK[EYSIZE]=integer |
| | |-R[EGION] |
| | |-S[UBSCRIPT]=subscript |
| | |-TN[_RESET] |
| | |-[NO]TR[ANSACTION][=integer] |
|-------------+----------------+-----------------------------------------------|
| | |-EX[TRACT][=file-specification|-stdout] |
| | |-REC[OVER] | -RO[LLBACK] |
|J[OURNAL] |file-name |-SH[OW][=show-option-list] |
| | |-[NO]V[ERIFY] |
| | |-BA[CKWARD] | -FO[RWARD] |
|-------------+----------------+-----------------------------------------------|
| | |-BE[GIN]=integer |
| | |-BLOCK_DENSITY |
| | |-E[ND]=integer |
|L[OAD] |file-name | |
| | |-FI[LLFACTOR]=integer |
| | |-FO[RMAT]=GO|B[INARY]|Z[WR] |
| | |-S[TDIN] |
|-------------+----------------+-----------------------------------------------|
| | |-DOWNGRADE |
| | |-E[XCLUDE]=global-name-list |
| | |-FI[LL_FACTOR]=integer |
| | |-I[NDEX_FILL_FACTOR]=integer |
| | |-REG[ION] |
| | |-RES[UME] |
|REO[RG] | |-SA[FEJNL] |
| | |-S[ELECT]=global-name-list |
| | |-STA[RTBLK]=hexa |
| | |-STO[PBLK]=hexa |
| | |-T[RUNCATE][=percentage] |
| | |-UP[GRAD E] |
| | |-USER_DEFINED_REORG=reorg_list |
|-------------+----------------+-----------------------------------------------|
| | |-E[DITINSTANCE] |
| | |-I[NSTANCE_CREATE] |
| | |-R[ECEIVER |
|REP[LICATE] |file-name | |
| | |-S[OURCE] |
| | |-UPDA[TEPROC] |
| | |-UPDH[ELPER] |
|-------------+----------------+-----------------------------------------------|
|RE[STORE] |file-name or |-[NO]E[XTEND] |
| |file-list | |
|-------------+----------------+-----------------------------------------------|
| |file-name or |-F[ILE] |
|RU[NDOWN] |region-name | |
| | |-R[EGION] |
|-------------+----------------+-----------------------------------------------|
| | |-A[CCESS_METHOD=BG|MM] |
| | |-B[YPASS] |
| | |-DB[FILENAME]=database_file |
| | |-DE[FER_TIME]=seconds |
| | |-E[XTENSION_COUNT]=integer(no of blocks) |
| | |-FILE |
| | |-F[LUSH_TIME]= integer |
| | |-G[LOBAL_BUFFERS]=integer |
| | |-JN[LFILE] |
| |file-name or |-JO[URNAL]=journal-option-list |
|SE[T] |region-name | |
| | |-L[OCK_SPACE]=integer |
| | |-PA[RTIAL_RECOV_BYPASS] |
| | |-PR[EVJNLFILE]=jnl_file_name |
| | |-RE[GION] |
| | |-REPLI[CATION]=ON|OFF |
| | |-REPL_[STATE]=ON|OFF |
| | |-RES[ERVED_BYTES]=integer |
| | |-S[TANDALONENOT] |
| | |-V[ERSION]=V4|V5 |
| | |-W[AIT_DISK]=integer |
|-------------+----------------+-----------------------------------------------|
|ST[OP] |process-id |process-id |
|-------------+----------------+-----------------------------------------------|
|UP[GRADE] |- |- |
+------------------------------------------------------------------------------+
+------------------------------------------------------------------------------------------------------------+
| Main Qualifier | MUPIP Command | Options/Qualifiers |
|--------------------------------------+--------------------------+------------------------------------------|
| | |-CHANGE |
| | |-DETAIL |
| | |-OFFSET=hexa |
|-EDITINSTANCE |REPLICATE | |
| | |-VALUE=hexa |
| | |-SIZE=hexa |
| | |-VALUE=hexa |
|--------------------------------------+--------------------------+------------------------------------------|
| | |ALWAYS |
|-FENCES=<fence-options-list> |JOURNAL-RECOVER-ROLLBACK |NONE |
| | |PROCESS |
|--------------------------------------+--------------------------+------------------------------------------|
| | |ALIGNSIZE=integer |
| | |ALLOCATION=integer |
| | |AUTOSWITCHLIMIT=integer |
| | |BEFORE_IMAGES |
| | |BUFFER_SIZE=integer |
| | |DISABLE |
| |BACKUP |ENABLE |
|-JOURNAL=<journal-options-list> | | |
| |SET |EPOCH_INTERVAL=integer |
| | |EXTENSION=integer |
| | |FILENAME=file_name |
| | |OFF |
| | |ON |
| | |SYNC_IO |
| | |YIELD_LIMIT=integer |
|--------------------------------------+--------------------------+------------------------------------------|
| |-RECOVER |TIME="time" |
|-LOOKBACK_LIMIT=lookback-option-list | | |
| |-ROLLBACK |OPERATIONS=integer |
|--------------------------------------+--------------------------+------------------------------------------|
| | |-BUFFSIZE=integer |
| | |-CHANGELOG |
| | |-CHECKHEALTH |
| | |-CMPLVL=integer |
| | |-FILTER=filter_name |
| | |-he[lpers]=[m[,n]] |
| | |-LISTENPORT=integer |
| | |-LOG=logfile |
|-RECEIVER |REPLICATE |-LOG_INTERVAL=integer |
| | |-SHOWBACKLOG |
| | |-SHUTDOWN |
| | |-START |
| | |-STATSLOG=[ON|OFF] |
| | |-STOPSOURCEFILTER |
| | |TIMEOUT=seconds |
| | |-UPDATEONLY |
| | |-UPDATERESYNC |
|--------------------------------------+--------------------------+------------------------------------------|
| | |-AFTER=time |
| | |-APPLY_AFTER_IMAGE |
| | |-BACKWARD |
| | |-BEFORE=time |
| | |-BROKENTRANS=file |
| | |-CHAIN |
| | |-CHECKTN |
| | |-[NO]ER[ROR_LIMIT][=integer] |
| | |-FENCES=fence-option-list |
| | |-FORWARD |
|-RECOVER |JOURNAL | |
| | |-FULL |
| | |-GLOBAL=<global_list> |
| | |-ID=<pid_list> |
| | |-INTERACTIVE |
| | |-LOOKBACK_LIMIT=<lookback_limit_options> |
| | |-LOSTTRANS[=file] |
| | |-RED[IRECT]=file-pair-list |
| | |-SINCE=time |
| | |-VERBOSE |
| | |-VERIFY |
|--------------------------------------+--------------------------+------------------------------------------|
| | |-AFTER=time |
| | |-BEFORE=time |
| | |-BROKENTRANS=file |
| | |-CHAIN |
| | |-CHECKTN |
| | |-[NO]ER[ROR_LIMIT]=integer] |
| | |-FENCES=fence-option-list |
| | |-FULL |
|-EXTRACT |JOURNAL | |
| | |-GLOBAL=<global_list> |
| | |-ID=<pid_list> |
| | |-INTERACTIVE |
| | |-LOOKBACK_LIMIT=<lookback_limit_options> |
| | |-LOSTTRANS[=file] |
| | |-SINCE=time |
| | |-VERBOSE |
| | |-VERIFY |
|--------------------------------------+--------------------------+------------------------------------------|
| | |-APPLY_AFTER_IMAGE |
| | |-BACKWARD |
| | |-BEFORE=time |
| | |-BROKENTRANS=file |
| | |-[NO]ER[ROR_LIMIT][=integer] |
| | |-FENCES=fence-option-list |
|-ROLLBACK |JOURNAL | |
| | |-FETCHRESYNC |
| | |-LOOKBACK_LIMIT=<lookback_limit_options> |
| | |-LOSTTRANS[=file] |
| | |-RES[YNC]=hexa;journal_sequence_number |
| | |-VERBOSE |
| | |-VERIFY |
|--------------------------------------+--------------------------+------------------------------------------|
| | |-ACTIVE_PROCESSES |
| | |-ALL |
| | |-BROKEN_TRANSACTIONS |
| | |-HEADER |
| | |-PROCESSES |
| | |-STATISTICS |
|-SHOW=<show-option-list> |JOURNAL |-AFTER=time |
| | |-USER=user-list |
| | |-TRANSACTION=[KILL|SET] |
| | |-INTERACTIVE |
| | |-GLOBAL=<global_list> |
| | |-ID=<pid_list> |
| | |-INTERACTIVE |
|--------------------------------------+--------------------------+------------------------------------------|
| | |-BYTESTREAM |
| | |-COMPREHENSIVE |
|-SINCE |BACKUP |-DATABASE |
| | |-INCREMENTAL |
| | |-RECORD |
|--------------------------------------+--------------------------+------------------------------------------|
| | |-ACTIVATE |
| | |-BUFFSIZE=Buffer_size |
| | |-CHANGELOG |
| | |-CHECKHEALTH |
| | |-CMPLVL=integer |
| | |-CONNECTPARAMS=connection_options |
| | |-DEACTIVATE |
| | |-DETAIL |
| | |-FILTER=filter_name |
| | |-INSTSECONDARY=secondary_instance name |
| | |-JNLPOOL-LOG=log_file |
| | |-LOG_INTERVAL=integer |
|-SO[URCE] |REPLICATE | |
| | |-LOSTTNCOMPLETE |
| | |-NEEDRESTART |
| | |-PASSIVE |
| | |-PROPAGATEPRIMARY |
| | |-ROOTPRIMARY |
| | |-SECONDARY=secondary_instance_name |
| | |-SHOWBACKLOG |
| | |-SHUTDOWN |
| | |-START |
| | |-STATSLOG |
| | |-STOPSOURCEFILTER |
| | |-TIMEOUT=seconds |
+------------------------------------------------------------------------------------------------------------+
Reference in New Issue View Git Blame Copy Permalink