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}]
 -BY[TESTREAM] [-NET[TIMEOUT]]
 -DA[TABASE]
 -[NO]NEWJNLFILES[=[NO]PREVLINK],[NO]S[YNC_IO]]
 -[NO]O[NLINE]
 -REC[ORD]
 -REPLA[CE]
 -RET[RY]=count
 -REPLIN[STANCE]=target_location
 -SH[OWPROGRESS]
 -SI[NCE]={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, disk mirroring, 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.

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

  • If you are backing up an encrypted datababase, you need to backup your $gtmcrypt_config file and securely preserve the encryption key. You also need to backup the related algorithms used to generate that key. For example, if you are using gpg for encryption and signing services, you must backup the relevant files in your $GNUPGHOME directory as part of your backup in addition to preserving the encryption key. Look in the manpages of gpg (man gpg) to see what all files require backup. Remember that if you forget the password of the encryption key which was used at the time of taking the backup, there is no way to decrypt the data from the encrypted regions. Therefore, ensure that you have procedures in place to securely handle password storage and retrieval of the encryption key.

  • 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 the -NEWJNLFILES qualifier. This aligns the journal files with the backup and simplifies journal file retention. Use the NOPREVLINK option for this qualifier with caution if the original database is used for replication. If the link to the previous generation journal file is cut, then the source server cannot supply transactions from the prior generation journal files.

  • 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 -DATABASE) 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 may be appropriate.

Example:

$ mupip backup "*" /gtm/bkup

This example creates ready-to-run database backup of all regions.

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

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] [-[no]V6] [-R[EGION]=region-name]

The single optional -REGION qualifier specifies a region for which to create a database file.

Note that a GT.M 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
[Note]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 a??Region Qualifiersa??.

The MUPIP DUMPFHEAD command displays information about one or more database files. The format of the MUPIP DUMPFHEAD command is:

DU[MPFHEAD]  {-FI[LE] file-name |-R[EGION] region-list} 
[Note]Note

MUPIP DUMPFHEAD obtains the field values from the database file header and ^%PEEKBYNAME obtains field values from the shared memory. Therefore, it may be possible that MUPIP DUMPFHEAD reports stale values for unflushed fields. If you require more recent file header values, use the MUPIP DUMPFHEAD -FLUSH which flushes file headers fields from shared memory to disk before returning the file header values.

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.

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 ChapterA 9: a??GT.M Database Structure(GDS)a??.

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

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 MUPIP EXTRACT command is:

EXTR[ACT] 
[
 -FO[RMAT]={GO|B[INARY]|Z[WR]}
 -FR[EEZE]
 -LA[BEL]=text
 -[NO]L[OG]
 -R[EGION]=region-list
 -S[ELECT]=global-name-list]
]
{-ST[DOUT]|file-name}

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.

  2. GO - Global Output format, used for files to transport or archive. -FORMAT=GO stores the data in record pairs. Each global node produces two records - the first contains the key and the second contains the value. MUPIP EXTRACT -FORMAT=GO has two header records - the first is a text label (refer to the LABEL qualifier) and the second is the date and time of extract in $ZDATE() format DD-MON-YEAR 24:60:SS. If -LABEL is not specified, the default first header is "GT.M MUPIP EXTRACT".

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

Temporarily suspends (freezes) updates to the database after ensuring a consistent state between memory and secondary storage, which, with -ACCESS_METHOD=BG, means after flushing global buffers. 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 [[-ONL[INE] [-[NO]AUTORELEASE]] | [-NOONL[INE]] [-R[ECORD]]]} region-list

FREEZE must include one of the qualifiers:

-OF[F]
-ON

The optional qualifiers are:

-[NO]A[UTORELEASE] - only valid with -ONLINE
-ON[LINE] - only valid with -ON
-OV[ERRIDE]
-R[ECORD] - only valid with -ON

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]

Produces the "public" (system generated) IPC Keys (essentially hash values) of a given file-list or the journal/receiver pool in a table form.

The format of the MUPIP FTOK command is:

FT[OK] [-DB] [-JNLPOOL] [-RECVPOOL] [-ID] [-ONLY] [-[NO]HEADER] file-list

Example:

$ mupip ftok -id mumps.dat
                File ::            Semaphore Id ::        Shared Memory Id ::                FTOK Key ::                             FileId
-------------------------------------------------------------------------------------------------------------------------------------------
           mumps.dat :: 1044382209 [0x3e400201] ::  613417274 [0x2490013a] ::  725039842 [0x2b373ae2] :: 0x00000000000e09818000002900000001
    
$ mupip ftok -id -only mumps.dat
           mumps.dat  ::   725039842  [ 0x2b373ae2 ]
$ mupip ftok -id -noheader mumps.dat
           mumps.dat :: 1044382209 [0x3e400201] ::  613417274 [0x2490013a] ::  725039842 [0x2b373ae2] :: 0x00000000000e09818000002900000001
  
$ mupip ftok -jnlpool 
                File ::            Semaphore Id ::        Shared Memory Id ::                FTOK Key ::                             FileId
-------------------------------------------------------------------------------------------------------------------------------------------
          multi.repl ::         -1 [0xffffffff] ::         -1 [0xffffffff] ::  743218009 [0x2c4c9b59] :: 0x00000000000e09838000002900000001
             jnlpool ::  636486196 [0x25f00234] ::  578814256 [0x22800130]

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 MUPIP INTEG command is:

I[NTEG] 
[
 -A[DJACENCY]=integer
 -BL[OCK]=hexa;block-number
 -BR[IEF]
 -DMAX[BLOCKSIZE][=integer]
 -FA[ST]
 -FU[LL]
 -IMAX[BLOCKSIZE][=integer]
 -[NO]K[EYRANGES]
 -[NO]MAP[=integer]
 -[NO]MAXK[EYSIZE][=integer]
 -[NO]O[NLINE]
 -S[UBSCRIPT]=subscript] 
 -TN[_RESET]
 -[NO]TR[ANSACTION][=integer]
]
{[-FILE] file-name|-REG[ION] region-list}
[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 preexisting database integrity issues.

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 ChapterA 11: a??Maintaining Database Integritya??. Contact your GT.M support channel for help assessing INTEG errors.

The following sections describe the qualifiers of the INTEG command.

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]

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.

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

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

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]]} 
-[O]NERROR={STOP|PROCEED|INTERACTIVE} 
-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.

Reports information related to relinkctl files and their associated shared memory segments. The format of the MUPIP RCTLDUMP command is:

MUPIP RCTLDUMP [dir1]

If the optional parameter dir1 is not specified, MUPIP RCTLDUMP dumps information on all its active auto-relink-enabled directories (those with with a *-suffix) identified by $gtmroutines. With a directory path specified for dir1, MUPIP RCTLDUMP reports information on the one directory. An example output follows. It lists the full path of the Object directory; its corresponding relinkctl file name; the number of routines currently loaded in this relinkctl file; the number of processes including the reporting MUPIP process that have this Relinkctl file open; the shared memory id and length of the Relinkctl shared memory segment; one or more Rtnobj shared memory segment(s); and a listing of all the routine names loaded in this file (lines starting with rec#...).

Given a relinkctl file name, one can find the corresponding directory path using the Unix "strings" command on the Relinkctl file. For example, "strings /tmp/gtm-relinkctl-f0938d18ab001a7ef09c2bfba946f002", corresponding to the above MUPIP RCTLDUMP output example, would output "/obj" the corresponding directory name.

Example:

$ mupip rctldump .
Object Directory         : /tmp
Relinkctl filename       : /tmp/fis-gtm/V6.2-001_x86_64/gtm-relinkctl-61f9eb418212a24a75327f53106c1656
# of routines            : 1
# of attached processes  : 2
Relinkctl shared memory  : shmid: 11534344 shmlen: 0x57c6000
Rtnobj shared memory # 1 : shmid: 11567113 shmlen: 0x100000 shmused: 0x200 shmfree: 0xffe00 objlen: 0x1c0
 rec#1: rtnname: abcd cycle: 1 objhash: 0xedbfac8c7f7ca357 numvers: 1 objlen: 0x1c0 shmlen: 0x200 superseded: 1

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.

MUPIP REORG can also encrypt a database and/or change the encryption keys for database files "on the fly" while the database is in use.

The format of the MUPIP REORG command is:

REO[RG] 
[
 -D[OWNGRADE]
 -ENCR[YPT]=key
 -E[XCLUDE]=global-name-list
 -FILE=file-name
 -FILL[_FACTOR]=integer
 -I[NDEX_FILL_FACTOR]=integer
 -K[EEP]={pct% | blocks}
 -MIN[_LEVEL]=integer
 -NOCO[ALESCE]
 -NOSP[LIT]
 -NOSW[AP]
 -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:

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]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 ChapterA 7: a??Database Replicationa?? for more complete documentation.

Specifies that REORG not handle blocks that contain information about the globals in the associated lista??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 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

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.

Incrementally restores the output of the BACKUP -BYTESTREAM to a database file at the backup location.

The format of the RESTORE command is:

RE[STORE] [-NET[TIMEOUT]] [-[NO]E[XTEND]] dbfile bytestream-bkup-list|<TCP_socket_address>

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 MUPIP RUNDOWN command is:

RU[NDOWN] {-FILE file-name|-REGION region-list|-RELINKCTL [dir]|-OVERRIDE}

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.

A successful MUPIP RUNDOWN of a database region removes any current MUPIP FREEZE.

RUNDOWN -FILE can be directed to a statistics database file and works even if the corresponding actual database file does not exist.

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]=region-list
-RELinkctl [dir1] 
-Override

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. MUPIP RUNDOWN with no argument removes any statistics database file resources associated with actual database file resources it can remove.

Use MUPIP SET for performance tuning and/or modifying certain database and journal file attributes.

The format of the SET command is:

SE[T] {-FI[LE] file-name|-JN[LFILE] journal-file-name|-REG[ION] region-list}  
 -AC[CESS_METHOD]={BG|MM}
 -[NO]AS[YNCIO]
 -DATA[_RESERVED_BYTES]=integer
 -[NO]DE[FER_TIME][=seconds]
 -[NO]DEFER_ALLOCATE 
 -[NO]ENCRYPTA[BLE]
 -ENCRYPTI[ONCOMPELTE]
 -EX[TENSION_COUNT]=integer(no of blocks)
 -F[LUSH_TIME]=integer
 -FU[LLBLKWRT]={0|1|2}
 -G[LOBAL_BUFFERS]=integer
 -H[ARD_SPIN_COUNT]=integer
 -INDEX[_RESERVED_BYTES]=integer
 -[NO]INST[_FREEZE_ON_ERROR]
 -JN[LFILE] journal-file-name journal-file-quals
 -K[EY_SIZE]=bytes
 -[NO]LCK_SHARES_DB_CRIT
 -L[OCK_SPACE]=integer
 -M[UTEX_SLOTS]=integer
 -N[ULL_SUBSCRIPTS]=value
 -[NO]Q[DBRUNDOWN]
 -[NO]REA[D_ONLY]
 -REC[ORD_SIZE]=bytes
 -REG[ION] region-list
 -REP[LICATION]={ON|OFF}
 -RES[ERVED_BYTES]=integer
 -SL[EEP_SPIN_COUNT]=integer
 -SPIN_SLEEP_M[ASK]=hex_mask
 -[NO]STAT[S]
 -STATSD[B_ALLOCATION]=integer(no of blocks)
 -[NO]STD[NULLCOLL]
 -T[RIGGER_FLUSH]=integer
 -W[AIT_DISK]=integer
 -WR[ITES_PER_FLUSH=integer

The following sections describe the action qualifiers of the MUPIP SET command exclusive of the details related to journaling and replication, which are described in ChapterA 6: a??GT.M Journalinga?? and ChapterA 7: a??Database Replicationa??. All of these qualifiers are incompatible with the -JNLFILE and -REPLICATION qualifiers.

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 a??Segment Qualifiersa??.

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.

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

[Note]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 a??Instance Freezea??.

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 a??Starting the Source Servera?? section of the Database Replication chapter.

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.

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

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] [-se[lect]=global-name-list] [-r[egion]=region-list] [-a[djacency]=integer] [-su[bscript]]=global-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:

The 2 sigma column for the two sampling techniques addresses the dispersion of the samples (in blocks) by giving the probability (rounded to a whole percentage) that the actual value falls farther away from the reported value by more than two sigma; in other words, larger values indicate less confidence in the accuracy of the result. With the scan method the "sample" is "complete," so any inaccuracy comes from concurrent updates.

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

-Adjacency=integer

Specifies the logical adjacency of data blocks that MUPIP SIZE should assume during estimation. By default, MUPIP SIZE assumes -ADJACENCY=10 and reports the logical adjacency in the "Adjacent" column of the MUPIP SIZE report. Note that adjacency is only a proxy for database organization and its usefulness may be limited by the technology and configuration of your secondary storage. See the INTEG section of this chapter for additional comments on adjacency.

-Select

Specifies the global variables on which MUPIP SIZE runs. -SELECT is incompatible with -SUBSCRIPT.If neither -SELECT or -SUBSCRIPT is specified, MUPIP SIZE selects all global variables in the specified region(s).

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.

-Subscript

Specifies the subscripted/non-subscripted global variables on which MUPIP SIZE runs. -SUBSCRIPT is incompatible with -SELECT.

The format of the SUBSCRIPT qualifier is:

-su[bscript]=global-list

global-name-list can be:

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

On receipt of a MUPIP STOP signal, a GT.M process cleans up its participation in managing the database before shutting down. On receipt of three MUPIP STOP signals in a row within a minute, a GT.M process shuts down forthwith without cleaning up - the equivalent of a kill -9 signal. This can result in structural database damage, because GT.M does not have sufficient control of what happens in response to an immediate process termination to protect against database damage under all circumstances.

In all cases, on receipt of a MUPIP STOP, a process will eventually terminate once it gets the resources needed to clean up. Use three MUPIP STOPs in a row only as a last resort, and when you do, perform a MUPIP INTEG at your earliest opportunity thereafter to check for database structural damage, and repair any damage following the procedures in Chapter 11 (Maintaining Database Integrity).

You may never have to perform a MUPIP STOP if your application is designed in a way that it reduces or eliminates the probability of a process getting in the final try of a transaction. For more information, refer to the Programmers Guide.

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

Before you run the MUPIP TRIGGER command:

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 the Triggers chapter and the $ZTRIGGER() section in the Functions chapter of the 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. Trigger maintenance operations reserve their output until the transaction commits at which time they deliver the entire output in a consistent way. 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.

  • MUPIP TRIGGER replicate trigger definitions as logical actions from an originating/primary instance to a replicating/secondary instance based on LGTRIG journal records. This permits the instances to have different sets of triggers and differing database layouts (for example, different # of regions, different block sizes, different maximum-record-size, and so on).

  • MUPIP TRIGGER error messages associated with loading triggers limit trigger expression source lines to 80 characters including a trailing ellipsis to indicate there was more text, and they also replace any non-graphic characters with a dot (.)

  • GT.M triggers apply to spanning regions. When $ZTRIGGER() or MUPIP TRIGGER define triggers that apply to globals spanning multiple regions, each of the spanned regions install a definition.

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

[Important]Important

MUPIP TRIGGER treats the deletion of a non-existent trigger as a success; if that is the only operation, or one of a set of successful operations, it returns success 0 to the shell. Also, MUPIP TRIGGER returns failure in case of trigger selection using trigger names where the number after the pound-sign (#) starts with a 0 (which is an impossible auto-generated trigger name).

UPGRADE

Upgrades older trigger definitions into current format.

The format of the UPGRADE qualifier is:

-UPGRADE

If GT.M encounters an old trigger definition it produces a NEEDTRIGUPGRD message. To preserve the possibility of a straightforward downgrade to an earlier version, perform a select "*" action with MUPIP TRIGGER (or $ZTRIGGER() and save the result. Note that TRIGGER -UPGRADE assumes that the existing trigger definitions are properly defined; if the prior release has produced defective triggers delete them with a wild-card ("*"), and redefine the triggers in the new release. In the event of a downgrade, delete "*" all triggers before the downgrade and insert the saved version from before the upgrade. Attempting to perform a MUPIP TRIGGER -UPGRADE on a database without write authorization to the database produces a TRIGMODREGNOTRW error. The -UPGRADE qualifier is not compatible with any other MUPIP TRIGGER qualifier. Trigger upgrades from older versions may produce journal records based on the prior format that a MUPIP JOURNAL -RECOVER cannot process correctly, therefore, FIS recommends you do them with journaling off, and start with a backup and fresh journal files after the trigger upgrade.

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

loading table of contents...