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}

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:

-BY[TESTREAM]

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.

The format of the DATABASE qualifier is:

-D[ATABASE]

Specifies the timeout period when a bytestream BACKUP data is either sent over a TCP/IP connection or restored using the RESTORE command. The format of the NETTIMEOUT qualifier is:

NET[TIMEOUT]=seconds

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]]

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]

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. In addition to storing the transaction number, -RECORD also stores a timestamp including the date and time of a successful backup operation in the database file. MUPIP DUMPFHEAD displays this timestamp as "sgmnt_data.last_start_backup" using a format such as "Sun Aug 15 13:37:32 2021". DSE DUMP -FILEHEADER -ALL also displays this date and time as "Last Record Backup Start" using the same format. These timestamps are displayed relative to the current timezone, and display as "Never" if the database file has never been successfully backed up with -RECORD. 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]

Overwrites the existing destination files.

The format of the REPLACE qualifier is:

-[REPL]ACE

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 source server for the instance must be started at least once before backing up the replication instance file.

The format of the REPLINSTANCE qualifier is:

-REPLI[NSTANCE]=<target_location>

Makes the specified number of retry attempts to perform BACKUP if the backup fails. If -RETRY is not specified, MUPIP retries file copy operation once if the first attempt fails for a retriable reason. In case of an error, retry attempts are always based on cp or pax even when another copy mechanism is available. If -RETRY=0 is specified, there is no retry for any failure that BACKUP encounters.

The format of the RETRY qualifier is:

-RET[RY]=<count>

When the backup copy mechanism supports monitoring, -SHOWPROGRESS periodically displays the transfer progress, estimated time left, speed, and the number of transaction applied to the database during backup.

The format of the SHOWPROGRESS qualifier is:

-SH[OWPROGRESS]

Incompatible with: -BYTESTREAM

Includes blocks changed since the last specified backup. The format of the SINCE qualifier is:

-SI[NCE]={DATABASE|BYTESTREAM|RECORD}

By default, MUPIP BACKUP -BYTESTREAM operates as -SINCE=DATABASE.

Incompatible with: -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

	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.

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.

Directs MUPIP to create a V6.3-014 compatible database file. This option is negatable to ensure that MUPIP CREATE always creates current version database files even when the environment variable gtm_db_create_ver is defined as V6. By default, MUPIP CREATE creates database files for the current version. The environment variable gtm_db_create_ver can override the default behavior.

The format of the V6 qualifier is:

-[NO]V6

-NOV6 creates a V7 database overriding the value of the environment variable gtm_db_create_ver.

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

	Note
	MUPIP CREATE silently ignores requests to create database files that have AutoDB enabled in the Global Directory. MUPIP CREATE prints no message even if the database region is specified by name. For more information on AutoDB, refer to “Region Qualifiers”.

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.

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

V63000A:

V63000A downgrades to any release older than V6.3-001. All releases up to V6.3-000A have an empty 512-bytes block logically after the last usable database block. VERSION=V63000A changes this terminating block from having the current size of a database block to 512-bytes.

Example:

$ mupip downgrade mumps.dat -VERSION=V5

This command changes the file-header of mumps.dat to V5 format.

Specifies the name of the database file for the MUPIP DUMPFHEAD operation. -FILE does not require a Global Directory. The format of the FILE qualifier is:

-FI[LE] database-file-name

Flushes the database file header flush before displaying the database file header fields. While this qualifier ensures the information is recent, under most production circumstances the output is sufficiently accurate without -FLUSH. Use of -FLUSH makes the operation significanly more heavyweight. If the database file header flush fails, MUPIP DUMPFHEAD -FLUSH produces a BUFFLUFAILED warning, but still produces output. The format of the FLUSH qualifier is:

-FL[USH] 

Specifies that the DUMPFHEAD command identifies one or more regions rather than a database file. The format of the REGION qualifier is:

-R[EGION] region-list

Example:

$ mupip dumpfhead -file mumps.dat

This command lists information about the database file mumps.dat in the current working directory.

$ mupip dumpfhead -region "*"

This command lists information about all the database files mapped by the global directory specified by $gtmgbldir.

Enables MUPIP ENDIANCVT to continue operations even if GT.M encounters the following errors:

Note that the OVERRIDE qualifier does not override critical errors (database integrity errors, and so on) that prevent a successful endian format conversion.

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

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. For more information about bitmaps, refer to Chapter 9: “GT.M Database Structure(GDS)”.

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

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

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:

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.

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

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.

Creates an encrypted binary extract with null IVs from a database with non-null IVs, which can be restored to a version that does not support non-null IVs. The format of the -NULL_IV qualifier is:

-[NO]NULL_IV

Restricts MUPIP EXTRACT to a set of regions. The format of the REGION qualifier is:

-R[EGION]=region-list 

region-list may specify more than one region of the current global directory in a list. Regions are case-insensitive, 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.

Specifies globals for a MUPIP EXTRACT operation. The format of the SELECT qualifier is:

-S[ELECT]= global-specification

The global-specification can be:

	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.

Redirects database extract to the standard output stream. The format of the STDOUT qualifier is:

-ST[DOUT]

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.

Clears a freeze set by another process with the same userid.

The format of the OFF qualifier is:

OF[F]

Specifies the start of a MUPIP FREEZE operation. The format of the ON qualifier is:

-ON

Incompatible with: -OFF, -OVERRIDE

Controls the behavior of a FREEZE specified with -ONLINE when GT.M must write to a database file. The format of the AUTORELEASE qualifier is:

-[NO]A[UTORELEASE]

Controls the potential impact of a FREEZE on concurrently updating processes. The format of the ONLINE qualifier is:

-[NO]ONL[INE]

	Note
	If a database is nearly full, and you about to use MUPIP FREEZE -ON -ONLINE, you may want to use MUPIP EXTEND first as a database file extension will either AUTORELEASE or "harden" the -ONLINE freeze effectively into a -NOONLINE freeze.

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]

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]

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.

Specifies that the file-name is a database file. By default, MUPIP FTOK uses -DB.

Specifies the signature use for the ftok; if unspecified, it defaults to the signature for a GT.M database file. if a file is not valid and accessible, FTOK reports -1 values. By default, the utility provides additional information about the file, including its file ID which provides the basis for the FTOK.

Displays or omits the header of the table. -ONLY output has no header, but by default other forms include a header that -NOHEADER suppresses.

Restricts the output to only the FTOK Key; if a file is not valid and accessible, FTOK reports -1 values. -ONLY does not report the table header even when -HEADER is specified. If the database file is unavailable, the utility defaults to the -ONLY behavior.

Specifies that the reported key is for the Journal Pool of the instance created by the current Global Directory.

Specifies that the reported key is for the Receive Pool of the instance created by the current Global Directory.

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.

The format of the ADJACENCY qualifier is:

-AD[JACENCY]=integer

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

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]

Specifies the maximum actual size of a data-level block in the database; any data block which contains data in excess of this size causes integ to report the block number, its path, and an error. The format of the DMAXBLOCKSIZE qualifier is:

-DMAX[BLOCKSIZE][=integer]

Checks only index blocks. FAST does not check data blocks.

The format of the FAST qualifier is:

-FA[ST]

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]

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]

Specifies the maximum actual size of an index-level block in the database; any index block which contains data in excess of this size causes integ to report the block number, its path, and an error. The format of the IMAXBLOCKSIZE qualifier is:

-IMAX[BLOCKSIZE][=integer]

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.

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]

	Note
	MUPIP INTEG reports all "incorrectly marked free" errors as they require prompt action. MAP does not restrict their reports.

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.

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]

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]

Specifies that the INTEG command identifies one or more regions rather than a database file. The format of the REGION qualifier is:

-R[EGION]=region-list

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:

-SU[BSCRIPT]=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

Specifies INTEG to check any active statistics database associated with the region(s) specified for the command. The format of the STATS qualifier is:

-[NO]ST[ATS]

Specify STATS only if you have reason to understand that statistics reporting is failing with database errors or reporting incorrect results. Because -FILE requires standalone access and statistic databases are automatically created and removed it is incompatible with -STATS. The default is NOSTATS.

Incompatible with: -BLOCK, -FILE, -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]

	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.

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]

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             110          25.732            NA
Index            1170          341639          88.298             6
Data           340578          519489          99.268        337888
Free             6809              NA              NA            NA
Total          348559          861238              NA        337894
[Spanning Nodes:3329 ; Blocks:341403]

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 may be able to improve the performance of a database if the all blocks are as adjacent as possible. "% Used" is the amount of space occupied across the in-use blocks divided by the space available in the in-use blocks, and thus represents the packing density for the in-use blocks (excluding local bit maps). Higher "% Used" may actually be undesirable from a performance perspective as they indicate a higher likelihood of block splits with upcoming updates.

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             110          25.732            NA
Index            1170          341639          88.298             4
Data           340578          519489          99.268        337617
Free             6809              NA              NA            NA
Total          348559          861238              NA        337621
[Spanning Nodes:3329 ; Blocks:341403]

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             110          25.732            NA
Index            1170          341639          88.298             4
Data           340578              NA              NA        337617
Free             6809              NA              NA            NA
Total          348559              NA              NA        337621

Note the NA entries 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           0.585           NA
    0               1             109          50.878           NA
Global variable ^#t
Level          Blocks         Records          % Used      Adjacent
    1               1               1           0.585             0
    0               1              80          49.609             1
Global variable ^versionContent
Level          Blocks         Records          % Used      Adjacent
    1               1               1           0.585             0
    0               1               1          94.018             0
Global variable ^x
Level          Blocks         Records          % Used      Adjacent
    1               1               2           1.464             0
    0               2             109          52.551             1

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"").

Specifies the format of the input file. If the format of the input file is not specified, MUPIP LOAD automatically detects file format (BINARY/ZWR/GO) based on the file header of the input file. If format is specified, it must match the actual format of the input file for LOAD to proceed.

The format codes are:

B[INARY] - Binary format
GO - Global Output format
Z[WR] - ZWRITE format

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.

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.

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

	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.

Determines the MUPIP LOAD behavior when it encounters an error. The format of the ONERROR qualifier is:

-[O]NERROR={STOP|PROCEED|INTERACTIVE}

By default MUPIP LOAD exits on encountering an error.

Specifies that MUPIP LOAD takes input from standard input (stdin). The format of the STDIN qualifier is:

-S[TDIN]

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.

Downgrades blocks to a prior major version DB format. Use REORG -DOWNGRADE only when you have determined there is a clear reason to downgrade the DB format of a database to a prior format and there are no conditions that preclude that possibility.

	Note:
	V7.0-000 and up do not support REORG -DOWNGRADE.

Encrypts an unencrypted database or changes the encryption key of a database while the database continues to be used by applications. Whether or not the prior encryption uses non-zero initialization vectors (IVs), database blocks encrypted with the new key use non-zero IVs The format of the ENCRYPT qualifier is:

-ENCR[YPT]=<key>

MUPIP provides <key> to the encryption plugin. The reference implementation of the plugin expects a key with the specified name in the encryption configuration file identified by $gtmcrypt_config. The configuration file must contain an entry in the database section for each database file mapping to a region specified in <region-list> that names the specified key as its key. The -ENCRYPT flag is incompatible with all other command line flags of MUPIP REORG except -REGION, and performs no operation other than changing the encryption key. If the specified key is already the encryption key of a database region, MUPIP REORG -ENCRYPT moves on to the next region after displaying a message (on stderr, where MUPIP operations send their output).

As MUPIP REORG -ENCRYPT reads, re-encrypts, and writes every in-use block in each database file, its operations take a material amount of time on the databases of typical applications, and furthermore add an additional IO load to the system on which it runs. You can use the environment variable gtm_poollimit to ameliorate, but not eliminate, the impact, at the cost of extending execution times. To minimize impact on production instances, FIS recommends running this operation on replicating secondary instances, rather than on originating primary instances.

-ENCRYPT switches the journal file for each database region when it begins operating on it, and again when it completes, and also records messages in the syslog for both events.

As is the case under normal operation when MUPIP REORG -ENCRYPT is not active, journaled databases are protected against system crashes when MUPIP REORG -ENCRYPT is in operation: MUPIP JOURNAL -ROLLBACK / -RECOVER recovers journaled database regions (databases that use NOBEFORE journaling continue to require -RECOVER / -ROLLBACK -FORWARD).

Because a database file utilizes two keys while MUPIP REORG -ENCRYPT is underway, the database section of the configuration file provides for a single database file entry to specify multiple keys. For example, if the keys of database regions CUST and HIST, mapping to database files cust.dat and hist.dat in directory /var/myApp/prod, are to be changed from key1 to key2 using the command:

MUPIP REORG -ENCRYPT=key2 -REGION CUST,HIST

then the database section of the configuration file must at least have the following entries:

 database: {
     keys: ({
         dat: "/var/myApp/cust.dat";
         key: "key1";
     },{
         dat: "/var/myApp/cust.dat";
         key: "key2";
     },{
         dat: "/var/myApp/hist.dat";
         key: "key1";
     },{
         dat: "/var/myApp/hist.dat";
         key: "key2";
     })
 };

In other words, each database file entry can have multiple keys, and a key can be associated with multiple database files. With a configuration file that has multiple keys associated with the same database file, MUPIP CREATE uses the last entry. Other database operations use whichever key associated with the database file has a hash matching one in the database file header, reporting an error if no key matches. To improve efficiency when opening databases, you can delete entries for keys that are no longer used from the configuration file.

MUPIP REORG -ENCR[YPT] can encrypt an unencrypted database only if the following command:

    MUPIP SET -ENCRYPTABLE -REGION <region-list>

has previously marked the database "encryptable".

The command requires standalone access to the database. It performs some basic encryption setup checks and requires the gtm_passwd environment variable to be defined and the GNUPGHOME environment variable to point to a valid directory in the environment. Just as encrypted databases use global buffers in pairs (for encrypted and unencrypted versions of blocks), a database marked as encryptable has global buffers allocated in pairs (that is, the actual number of global buffers is twice the number reported by DSE DUMP -FILEHEADER) and requires correspondingly larger shared memory segments. To revert unencrypted but encryptable databases back to "unencryptable" state, use the command:

MUPIP SET -NOENCRYPTABLE -REGION <region-list>

The above command only requires standalone access, and the result depends on the state of the database. It:

Under normal operation, a database file has only one key. Upon starting a MUPIP REORG -ENCRYPT to change the key, there are two keys, both of whose hashes GT.M stores in the database file header. With a MUPIP REORG -ENCRYPT operation underway to change the key, normal database operations can continue, except for another MUPIP REORG -ENCRYPT or MUPIP EXTRACT in binary format. Other MUPIP operations, such as MUPIP BACKUP and MUPIP EXTRACT in ZWR format can occur. A MUPIP REORG -ENCRYPT operation can resume after an interruption, either unintentional, such as after a system crash and recovery, or intentional, that is, an explicit MUPIP STOP of the MUPIP REORG -ENCRYPT process. To resume the REORG operation, reissue the original command, including the key parameter. (Note that supplying a key other than the one used in the original command produces an error.)

After the MUPIP REORG -ENCRYPT process completes, subsequent MUPIP REORG -ENCRYPT operations on the same region(s) are disallowed until the following command is run:

MUPIP SET -ENCRYPTIONCOMPLETE -REGION <region-list>

Blocking subsequent MUPIP REORG -ENCRYPT operations after one completes provides time for a backup of the entire database before enabling further key changes. MUPIP SET -ENCRYPTIONCOMPLETE reports an error for any database region for which MUPIP REORG -ENCRYPT has not completed.

Note

FIS recommends rotating (changing) the encryption key of the database for better security. The frequency of encryption key rotation depends on your security requirements and policies. MUPIP REORG -ENCRYPT does not enable switching between encryption algorithms. To migrate databases from Blowfish CFB to AES CFB requires that the data be extracted and loaded into newly created database files. To minimize the time your application is unavailable, you can deploy your application in a Logical Multi-Site (LMS) configuration, and migrate using a rolling upgrade technique. Refer to the Chapter 7: “Database Replication” for more complete documentation.

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

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.

Specifies which database to upgrade. The format of the FILE qualifier is:

FILE=file-name

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:

FILL[_FACTOR]=integer

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.

Directs REORG to only process blocks with a level greater than or equal to what is specified. -Min_level=1, for example, instructs REORG to only process index blocks. The format of the MIN_LEVEL qualifier is:

-M[IN_LEVEL]=integer

When the user intends to target only a subset of the blocks in a database for splitting, coalescing, and swapping, this setting can significantly reduce the overhead of doing so. -Min_level=1 can be understood as the REORG equivalent of an INTEG -FAST.

For a MUPIP REORG -TRUNCATE, -KEEP allows the user to specify, as a decimal integer number of blocks or a percentage from 0% to 99% of the starting total blocks, the total amount of space the truncate operation should leave (not truncate) in the database file at the completion of other REORG operations. The format of the KEEP qualifier is:

-KEEP={pct%|blocks}

-NOCOALESCE specifies to MUPIP REORG to skip actions that increase block density. The format of the NOCOALESCE qualifier is:

-NOCO[alesce]

-NOSPLIT specifies to MUPIP REORG to skip actions that decrease block density. The format of the NOSPLIT qualifier is:

-NOSP[lit]

-NOSWAP specifies to MUPIP REORG to skip actions that increase block adjacency. The format of the NOSWAP qualifier is:

-NOSW[ap]

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]

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

region-list may specify more than one region of the current global directory in a list. Regions are case-insensitive, 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.

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

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. TRUNCATE only applies to BG databases. 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.

	Warning
	Because any competing updates may interfere with MUPIP's ability to free space, minimize or prevent competing updates.

Upgrades blocks to current DB version format. A REORG with the -UPGRADE option cannot run concurrently on a file or region with any other REORG on the same file or region. Use REORG -UPGRADE when it is a part of a release notes procedure to upgrade the DB version format of a database or when you encounter a database integrity error that requires running REORG -UPGRADE.

Example:

$ mupip reorg 
Fill Factor:: Index blocks 100%: Data blocks 100%
   
Global: CUST (region DEFAULT)
Blocks processed    : 667340 
Blocks coalesced    : 601487 
Blocks split        : 0 
Blocks swapped      : 319211 
Blocks freed        : 646964 
Blocks reused       : 298814 
Blocks extended     : 0 
   
Global: HIST (region HIST)
%GTM-I-FILERENAME, File /var/myApp/prod/journals/hist.mjl is renamed to /var/myApp/prod/journals/hist.mjl_2015289165050
Blocks processed    : 337069 
Blocks coalesced    : 12888 
Blocks split        : 0 
Blocks swapped      : 329410 
Blocks freed        : 315998 
Blocks reused       : 308337
Levels Eliminated   : 1 
Blocks extended     : 0 
$

In this output:

Note also that owing the database update activity of REORG, the hist.mjl journal file reached its limit, requiring MUPIP to switch the journal file.

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 

Example:

The following example uses recorg -encrypt to encrypt a database "on the fly". This is a simple example created for demonstration purposes. It is NOT recommended for production use. Consult your GT.M support channel for specific instructions on encrypting an unencrypted database.

Create an empty default unencrypted database.

$gtm_dist/mumps -r ^GDE exit
  $gtm_dist/mupip create

Setup the GNUPG home directory.

export GNUPGHOME=$PWD/.helengnupg3    
mkdir $GNUPGHOME # Ensure that you protect this directory with appropriate permissions.  
chmod go-rwx $GNUPGHOME

Create a new key. Enter demo values. This example uses demo values from the database encryption example in the GT.M Acculturation Workshop document. Accept default values. Choose a strong passphrase.

gpg --gen-key  

Edit the key to add a new sub-key:

gpg --edit-key helen.keymaster@gt.m  

Type addkey, select option 6 RSA (encrypt only), and accept default values and execute the following commands:

gpg --gen-random 2 32 | gpg --encrypt --default-recipient-self --sign --armor > gtm_workshop_key.txt
gpg --decrypt < ./gtm_workshop_key.txt | gpg --encrypt --armor --default-recipient-self --output gtm.key

Refer to the 'man gpg; a description on the qualifiers for gpg.

Create a gtmcrypt_config file as following:

$ cat config
database: {
    keys:   (
              {
              dat: "/path/to/mumps.dat" ;
              key: "/path/to/gtm.key" ;
              }
            );
  }

Set the environment variable gtmcrypt_config to point to this config file.

export gtmcrypt_config=$PWD/config 

Set the enviroment varible gtm_passwd.

echo -n "Enter passphrase for gtm.key: " ; export gtm_passwd=`$gtm_dist/plugin/gtmcrypt/maskpass|cut -f 3 -d " "`

Execute the following commands:

$ mupip set -encryptable -region DEFAULT
$ mupip reorg -encrypt="gtm.key" -region DEFAULT
mupip reorg -encrypt="gtm.key" -region DEFAULT
Region DEFAULT : MUPIP REORG ENCRYPT started
Region DEFAULT : Database is now FULLY ENCRYPTED with the following key: gtm.key
Region DEFAULT : MUPIP REORG ENCRYPT finished

Execute the following command when encryption completes.

$ mupip set -encryptioncomplete -region DEFAULT
Database file /home/gtc_twinata/staff/nitin/tr11/mumps.dat now has encryption marked complete

Always keep the keys in a secured location. Always set gtmcrypt_config and gtm_passwd to access the encrypted database.

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.

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

$ mupip backup -bytestream region1,region2 tcp://hostname1:port1,tcp://hostname1:port2 -nettimeout=420

This command starts a MUPIP process waiting for a listening MUPIP RESTORE processes to send bytestream data of region1 and region2.

$ mupip restore region1.dat tcp://hostname1:port1 -nettimeout=420

This command start a TCP listening process to receive the bytstream data from region1 of the previous MUPIP BACKUP -BYTSTREAM command.

$ mupip restore region2.dat tcp://hostname1:port2 -nettimeout=420

This command start a TCP listening process to receive the bytstream data from region2 of the previous MUPIP BACKUP -BYTSTREAM command. Note that you cannot start RESTORE for region2 before the backup of region1 completes.

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

Overrides the protection that prevents MUPIP RUNDOWN from performing a rundown of a replication-enabled (with BEFORE_IMAGE) database or a non-replicated NOBEFORE-journaled database that was abnormally shutdown. The protection involves issuing the MUUSERLBK error for a previously crashed replication-enabled (with BEFORE IMAGE journaling) database and the MUUSERECOV error for a non-replicated or NOBEFORE-journaled database. Both these errors prevent complications related to data recovery from a journal file or a replication-enabled database.

The region-list identifies the target of the RUNDOWN. region-list may specify more than one region of the current global directory in a list. Regions are case-insensitive, 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.

Use the wildcard "*" 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.

Cleans up orphaned Relinkctl files. FIS strongly recommends avoiding actions that tend to make such cleanup necessary - for example, kill -9 of GT.M processes or ipcrm -m of active Relinkctl and/or Rtnobj shared memory segments.

If the optional dir1 is not specified, MUPIP RUNDOWN -RELINKCTL examines the environment variable $gtmroutines, attempts to verify and correct their attach counts and runs down all its inactive auto-relink-enabled directories (those with with a *-suffix). Alternatively, one can specify a directory path for the parameter dir1 and MUPIP RUNDOWN -RELINKCTL treats it as an auto-relink-enabled directory and runs down the resources associated with this one directory. It prints a RLNKCTLRNDWNSUC message on a successful rundown and a RLNKCTLRNDWNFL message on a failure (usually because live processes are still accessing the Relinkctl 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: -JNLFILE, -REGION and -REPLICATION

Specifies that the argument is a journal-file-name. The format of the JNLFILE qualifier is:

-JNLF[ILE] journal-file-name

Incompatible with: -FILE, -REGION and -REPLICATION

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] region-list

The region-list identifies the target of SET. region-list may specify more than one region of the current global directory in a list. Regions are case-insensitive, separated by a comma, and wild-cards can be used to specify them. Any region-name may include the wild-card 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.

Incompatible with: -FILE, -JNLFILE and -REPLICATION

Specifies whether replication is on or off. The format of the REPLICATION qualifier is:

-REP[LICATION]={ON|OFF}

Incompatible with: -JNLFILE

Specifies the access method (GT.M buffering strategy) for storing and retrieving data from the database file. The format of the ACCESS_METHOD qualifier is:

-AC[CESS_METHOD]=code

For more information on specifying the ACCESS_METHOD, refer to “Segment Qualifiers”.

Specifies whether to use asynchronous I/O for an access method BG database, rather than using synchronous I/O through the file system cache. ASYNCIO is incompatible with the MM access method and an attempt to combine the two with MUPIP SET produces a ASYNCIONOMM error. The format of the ASYNCIO qualifier is:

-[NO]AS[YNCIO]

For more information on specifying ASYNCIO,refer to “Segment Qualifiers”.

Specifies the size for GT.M to reserve in data-level database blocks. DATA_RESERVED_BYTES can be used as a user-managed fill factor when it is appropriate to have a different level of sparseness for data and index blocks. The format of the DATA_RESERVED_BYTES qualifier is:

-DATA[_RESERVED_BYTES]=size

Specifies, in MM access mode, the multiplying factor applied to the flush time to produce a wait after an update before ensuring a journal buffer write to disk; the default is 1. A value of 2 produces a wait of double the flush time. -NODEFER_TIME or a value of -1 turns off timed journal writing, leaving the journal, under light update conditions, to potentially get as stale as the epoch time. Note that, in MM mode without the sync_io option set, absent a VIEW("JNLFLUSH") from the application, GT.M only fsyncs the journal at the epoch. The format of the DEFER_TIME qualifier is:

-[NO]D[efer_time][=seconds]

With -DEFER_ALLOCATE, GT.M instructs the file system to create the database file as a sparse file. Before using -DEFER_ALLOCATE, ensure that your underlying file system supports sparse files. By default UNIX file systems, and GT.M, use sparse (or lazy) allocation, which defers actual allocation until blocks are first written. The format of the DEFER_ALLOCATE qualifier is:

-[NO]DEFER_Allocate

Tries to minimize epoch duration by reducing the number of buffers to flush by GT.M and the file system (via an fsync()) as the epoch (time-based or due to journal file auto-switch) approaches. Epoch tapering reduces the impact of I/O activity during an epoch event. Application that experience high load and/or need to reduce latency may benefit from epoch tapering. The format of the -EPOCHTAPER qualifier is:

-[NO]EPOCHTAPER

Performs some basic encryption checks and marks the database as encryptable. Note that marking a database as encryptable does not encrypt the database.For more information on encrypting a database, refer to “-Encrypt”. The format of the ENCRYPTABLE qualifier is:

-[NO]ENCRYPTA[BLE]

Checks whether a prior MUPIP REORG -ENCRYPT completed successfully and marks encryption as complete. For usage scenarios of MUPIP SET -ENCRYPTIONCOMPLETE, refer to “-Encrypt”. The format of the ENCRYPTIONCOMPLETE qualifier is:

-ENCRYPTI[ONCOMPELTE]

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:

-EX[TENSION_COUNT]=integer 

For more information on specifying the EXTENSION_COUNT, refer to “Segment Qualifiers”.

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

Determines whether GT.M writes only valid database blocks contents, or a full block including meaningless trailing content. Full block writes are more efficient with some secondary storage because they avoid read-before-write. The format of the FULLBLKWRT qualifier is:

-FU[LLBLKWRT]={0|1|2}

Note that when the file system block size and the database block size are the same there is no difference between the settings of 1 and 2.

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

For more information on ways to determine good working sizes for GLOBAL_BUFFERS, refer to “Segment Qualifiers”.

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 on memory constrained systems 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 2,097,151 buffers, but may vary depending on your platform. 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.

Specifies the maximum amount of time for processes to sleep while waiting to obtain critical sections for shared resources, principally those involving databases. The format of the -SPIN_SLEEP_MASK qualifier is:

-HARD_SPIN_COUNT=integer

The mutex hard spin count specifies the number of attempts to grab the mutex lock before initiating a less CPU-intensive wait period. The format of -HARD_SPIN_COUNT is:

Specifies the size for GT.M to reserve in index-level database blocks. INDEX_RESERVED_BYTES can be used as a user-managed fill factor when it is appropriate to have a different level of sparseness for data and index blocks. The format of the INDEX_RESERVED_BYTES qualifier is:

-INDEX[_RESERVED_BYTES]=size

Enables or disables custom errors in a region to automatically cause an Instance Freeze.

	Note
	GT.M creates a STATSDB region with INST_FREEZE_ON_ERROR disabled, preventing errors associated with such a region from causing an instance freeze even when INST_FREEZE_ON_ERROR for the base region is enabled.

This flag modifies the "Inst Freeze on Error" file header flag. The format of the INST_FREEZE_ON_ERROR qualifier is:

-[NO]INST[_FREEZE_ON_ERROR]

For more information on creating a list of custom errors that automatically cause an Instance Freeze, refer to “Instance Freeze”.

For more information on promptly setting or clearing an Instance Freeze on an instance irrespective of whether any region is enabled for Instance, refer to the “Starting the Source Server” section of the Database Replication chapter.

Specifies whether the database allows journaling and, if it does, characteristics for the journal file.:

	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 JOURNAL qualifier is:

-[NO]J[OURNAL][=journal-option-list]

For detailed description of the all JOURNAL qualifiers and its keywords, refer to “SET -JOURNAL Options ”.

Specifies the maximum key size in bytes for storing and retrieving data from the global database file. The maximum supported size is 1019 bytes. The format of the KEY_SIZE qualifier is:

-K[EY_SIZE=bytes

For more information on KEY_SIZE, refer to “Region Qualifiers”.

Specifies whether LOCK actions share the same resource and management as the database or use a separate resource and management. The format of the LCK_SHARES_DB_CRIT qualifier is:

 -[NO]LC[K_SHARES_DB_CRIT]

The default is Sep(arate)/FALSE.

For more information, refer to the -[NO]L[OCK_CRIT] section of GDE “Region Qualifiers”.

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

Sets the size of a structure that GT.M uses to manage contention for the principal critical section for a database on AIX. Performance issues may occur when there are many processes contending for database access and if this structure cannot accommodate all waiting processes. Therefore, FIS recommends setting this value to a minimum of slightly more than the maximum number of concurrent processes you expect to access the database.

The minimum value is 64 and the maximum value is 32768. The default value is 1024. The format of the MUTEX_SLOTS qualifier is:

-M[UTEX_SLOTS]=integer

Controls whether GT.M accepts null subscripts in database keys.

Usage:

-N[ULL_SUBSCRIPTS]=value

Specifies the approximate number of records a block in the region must exceed before GT.M considers a proactive block split. The format of the -PROBLKSPLIT qualifier is:

-PRO[BLKSPLIT]=integer

Shortens normal process shutdown when a large number of processes accessing a database file need to shutdown almost simultaneously, for example, in benchmarking scenarios or emergencies. The format of the QDBRUNDOWN qualifier is:

-[NO]Q[DBRUNDOWN]

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 that the last process to exit might leave the database shared memory and IPC resources in need of cleanup. Except after the number of concurrent processes exceeds 32Ki, QDBRUNDOWN minimizes the possibility of abandoned resources, but it cannot eliminate it. When using QDBRUNDOWN, use an explicit MUPIP command such as RUNDOWN or JOURNAL -RECOVER or -ROLLBACK of the database file after the last process exits, to ensure the cleanup of database shared memory and IPC resources; not doing so risk database damage.

When a database has QDBRUNDOWN enabled, if the number of attached processes ever exceeds 32Ki, GT.M stops tracking the number of attached processes, which means that it cannot recognize when the number reaches zero (0) and the shared resources can be released. The process that detects this event issues a NOMORESEMCNT in the system log. This means an orderly, safe shutdown requires a MUPIP JOURNAL -ROLLBACK -BACKWARD for replicated databases, a MUPIP JOURNAL -RECOVER -BACKWARD for unreplicated journaled databases and a MUPIP RUNDOWN for journal-free databases.

Sets the CORRUPT_FILE flag in the database file header to FALSE. The CORRUPT_FILE flag indicates whether a region completed a successful recovery. The format of the PARTIAL_RECOV_BYPASS qualifier is:

-PA[RTIAL_RECOV_BYPASS]

For more information, refer to the CORRUPT_FILE qualifier in “CHANGE -FIleheader Qualifiers”.

Indicates whether GT.M should treat an MM access method segment as read only for all users, including root. This designation augments UNIX authorizations and prevents any state updates that normally might require an operational action for a database with no current accessing (attached) processes. Setting the -READ_ONLY attribute on a database file with BG access method or setting the access method to BG on a -READ_ONLY database produces an error. The GT.M help databases have -READ_ONLY set by default. The format of the READ_ONLY qualifier is:

-[NO]REA[D_ONLY]

-NOREAD_ONLY makes a database file writable for users who have write permissions on the database file. Note that because of the way GT.M handles semaphores for READ_ONLY database files it does not enforce standalone access for setting the characteristic from READ_ONLY to NOREAD_ONLY. However, making a change from READ_ONLY to NOREAD_ONLY without standalone access will likely cause problems, such as errors on termination and failure to release IPC resources that would require additional MUPIP commands to clean up. Therefore FIS recommends using other means such as the following based on fuser return of one (1) to verify there are no processes are accessing the file:

fuser <db-filename> | awk -F: '{if(length($NF))exit(1)}' && $gtm_dist/mupip set -noread_only -file <db-filename>

	Note
	When the first process connects to a database, it creates a access-control semaphore as part of management of the shared resource. However, when a process connects to a -READ_ONLY database, each create a private copy of the in-memory structures for the database and thus a private semaphore.

Specifies the maximum record size in bytes for storing and retrieving data from the global database file. The maximum supported size is 1MiB bytes. The format of the RECORD_SIZE qualifier is:

-REC[ORD_SIZE=bytes

For more information on KEY_SIZE, refer to “Region Qualifiers”.

Specifies the size for GT.M to reserve in both data and index database blocks. RESERVED_BYTES is generally used as a user-managed fill factor. The format of the RESERVED_BYTES qualifier is:

-RES[ERVED_BYTES]=size

Specifies the number of times a process suspends its activity while waiting to obtain critical sections for shared resources, principally those involving databases. The format of the -SLEEP_SPIN_COUNT qualifier is:

-SLEEP_SPIN_COUNT=integer

Specifies the maximum amount of time for processes to sleep while waiting to obtain critical sections for shared resources, principally those involving databases. The format of the -SPIN_SLEEP_MASK qualifier is:

-SPIN_SLEEP_MASK=hex_mask

Specifies whether GT.M should permit statistics sharing for this region. This characteristic permits operational exclusion of statistics sharing for a region. The format of the STATS qualifier is:

-[NO]STATS

Specifies the initial number of GDS blocks for the shadow stats regions when the database region is first created. This qualifier requires standalone access and a file or region name. The format of the STATSDB_ALLOCATION qualifier is:

-STATSD[B_ALLOCATION]=integer

Specifies whether GT.M uses standard MUMPS collation or GT.M collation for null-subscripted keys. FIS strongly recommends that you use STDNULLCOLL and against using this non-standard null collation, which is the default for historical reasons. The format of the STDNULLCOLL qualifier is:

-[NO]STD[NULLCOLL]

Specifies the decimal value, in buffers, for the threshold at which processes start flushing dirty buffers after each update. The format of the TRIGGER_FLUSH qualifier is:

-T[RIGGER_FLUSH]=integer

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:

	Note:
	V7.0-000 and up do not support the -VERSION option.

-V[ERSION]={V5|V6}

Specifies the seconds to wait for disk space before giving up on a database block write, where zero (0) means to give an error immediately without waiting. The format of the WAIT_DISK qualifier is:

-WA[IT_DISK]=seconds

Specifies the decimal number of blocks to write in each flush. The default value is 7. The format of the WRITES_PER_FLUSH qualifier is:

-WR[ITES_PER_FLUSH]=integer

Example:

$ mupip set -journal=on,nobefore -region "*"

This example enables NOBEFORE image journaling and turns on journaling for all regions.

$ mupip set -version=V5 -file mumps.dat
Database file mumps.dat now has desired DB format V5

This example disables the V6 extensions for 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.

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"):

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.

To delete an existing trigger for global node ^Acct("ID"):

You have successfully deleted trigger "ValidateAccount".

To change a trigger name for global node ^Acct("ID"):

Example:

$ mupip upgrade -file mumps.dat

This example starts the first stage of the upgrade of mumps.dat to V7 format.