Commands and Qualifiers

The MUPIP commands described in this section are used for common database operations and serves as the foundation for more advanced functionality like Journaling and Replication.

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

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

  • [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.

  • By default, MUPIP BACKUP is -DATABASE -ONLINE.

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

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

  • 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 a TCP socket address (a combination of IPv4 or IPV6 hostname and a port number).

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

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

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

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

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

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

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

[Tip]Before starting a MUPIP BACKUP

Perform the following tasks before you begin a database backup.

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

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

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

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

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

  • Determine an appropriate frequency, timing, and backup method (-BYTESTREAM or -COMPREHENSIVE) based on the situation.

  • Ensure the user issuing backup commands has appropriate permissions before starting the backup. Backup files have the ownership of the user running MUPIP BACKUP.

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

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

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

The DATABASE qualifier does not support backup to magnetic tape.

The format of the DATABASE qualifier is:

-D[ATABASE]

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

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

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

-S[INCE]={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]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.

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 namespace) can consist of an arbitrary number of database files.

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

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.

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:

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.

Example:

$ mupip downgrade mumps.dat

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

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>
[Note]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.

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.

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.

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

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.

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}
[Note]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.

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:

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

    56-87

    Space-padded label specified by the -LABEL qualifier. For extracts in UTF-8 mode, GT.M prefixes UTF-8 and a space to -LABEL. The default LABEL is "GT.M MUPIP EXTRACT"

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

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

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.

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

-S[ELECT]= global-specification

The global-specification can be:

[Note]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.

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

FREEZE must include one of the qualifiers:

-OF[F]
-ON

The optional qualifiers are:

-OV[ERRIDE]
-R[ECORD]

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

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.

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

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

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.

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:

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]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}
[Important]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:

  • Invalid application operation due to missing or incorrect data.

  • Process errors, including inappropriate indefinite looping, when a database access encounters an error.

  • 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:

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. For information on analyzing and correcting database errors, refer to Chapter 11: “Maintaining Database Integrity”. Contact your GT.M support channel for help assessing INTEG errors.

The following sections describe the qualifiers of the INTEG command.

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]

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]

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]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]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 parameter identifies one or more regions rather than a database file. The format of the REGION qualifier is:

-R[EGION]

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

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

To specify a literal in the command string, use two double quotation marks for example, ^b(""c"").

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

Analyzes, extracts, reports, and recovers data using journal files. For a description of the JOURNAL command, refer to Chapter 6: “GT.M Journaling”.

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

[Note]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.

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

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

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.

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]
 -S[ELECT]=global-name-list
 -T[RUNCATE][=percentage]
 -UP[GRADE]
 -REG[ION]=region-list
]
[Note]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.

[Caution]Caution

REORG focuses on optimum adjacency and a change to even a single block can cause it to perform a large number of updates with only marginal benefit. Therefore, FIS recommends not running successive REORGs close together in time as that can provide minimal benefit for a significant increase in database and journal activity. For the same reason, FIS recommends careful research and planning before using the -RESUME qualifier or complex uses of -EXCLUDE and -SELECT.

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:

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

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.

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

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

TRUNCATE does not complete if there is a concurrent online BACKUP or use of the snapshot mechanism, for example by INTEG.

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

Control the logical multi-site operation of GT.M. For more information on the qualifiers of the MUPIP REPLICATE command, refer to Chapter 7: “Database Replication” .

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

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.

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:

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.

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

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.

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.

Modifies certain database characteristics. MUPIP SET operates on either regions or files.

[Note]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
 -M[UTEX_SLOTS]=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

The following section describe the qualifiers of the MUPIP SET command.

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

Sets the CORRUPT_FILE flag in the database fileheader to FALSE. The CORRUPT_FILE flag indicates whether a region completed a successful recovery. For more information, refer to the CORRUPT_FILE qualifier in Chapter 10, Database Structure Editor.

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

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

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

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

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 Chapter 4: “Global Directory Editor”.

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.

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

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.

For more information on creating a list of custom errors that automatically causae 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.

Sets the size of a structure that GT.M uses to manage contention for the principal critical section for a database. 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.

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]

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.

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

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}

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

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

estimation-technique is one of the following:

[Important]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:

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

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

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

  • For information on the syntax and usage of a trigger definition file, refer to GT.M Programmer's Guide.

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

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

  • MUPIP TRIGGER compiles the XECUTE action string and rejects the load if the compilation has errors.

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

  • Incompatible with: -SELECT

[Note]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]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.

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.

Upgrades the file-header of a database. The format of the MUPIP UPGRADE command is:

UP[GRADE]

Example:

$ mupip upgrade mumps.dat

This example upgrades the file-header of mumps.dat to V5 format.

Prev Up Next
 Home 
loading table of contents...