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 |
---|---|
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. |
![]() | Before starting a MUPIP BACKUP |
---|---|
Perform the following tasks before you begin a database backup.
|
$ mupip backup "*" /gtm/bkup
This example creates ready-to-run database backup of all regions.
![]() | Note |
---|---|
MUPIP BACKUP output to a TCP connection saves disk I/O bandwidth on the current system. |
The format of the BYTESTREAM qualifier is:
-BY[TESTREAM]
The format of the NEWJNLFILES qualifier is:
-[NO]NEWJNLFILES[=[NO]PREVLINK], [NO]S[YNC_IO]]
Specifies the target location to place the backup of the replication instance file.
![]() | Note |
---|---|
The replication instance file should always be backed up with the database file. The source server for the instance must be started at least once before backing up the replication instance file. |
The format of the REPLINSTANCE qualifier is:
-REPLI[NSTANCE]=<target_location>
Includes blocks changed since the last specified backup. The format of the SINCE qualifier is:
-SI[NCE]={DATABASE|BYTESTREAM|RECORD}
By default, MUPIP BACKUP -BYTESTREAM operates as -SINCE=DATABASE.
-T[RANSACTION]=transaction-number
![]() | Note |
---|---|
A point in time that is consistent from an application perspective is unlikely to have the same transaction number in all database regions. Therefore, except for -TRANSACTION=1, this qualifier is not likely to be useful for any backup involving multiple regions. |
$ mupip backup -bytestream REPTILES,BIRDS bkup
$ mupip backup -bkupdbjnl="OFF" "*"
This command turns off journaling in the backup database.
$ mupip backup -bytestream "*" tcp://philadelphia:7883,tcp://tokyo:8892
$ 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.
$ 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.
$ 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.
$ 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.
$ mupip backup -record DEFAULT bkup
$ 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.
$ 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.
$ 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.
$ mupip backup -newjnlfiles=noprevlink,sync_io "*" backupdir
The format of the CREATE command is:
CRE[ATE] [-[no]V6] [-R[EGION]=region-name]
The single optional -REGION qualifier specifies a region for which to create a database file.
The format of the V6 qualifier is:
-[NO]V6
-NOV6 creates a V7 database overriding the value of the environment variable gtm_db_create_ver.
The format of the REGION qualifier is:
-R[EGION]=region-name
![]() | Note |
---|---|
MUPIP CREATE silently ignores requests to create database files that have AutoDB enabled in the Global Directory. MUPIP CREATE prints no message even if the database region is specified by name. For more information on AutoDB, refer to a??Region Qualifiersa??. |
D[OWNGRADE] -V[ERSION]={V5|V63000A}} file-name
![]() | Note |
---|---|
V7.0-000 and up do not support DOWNGRADE, even when running on a V6 database. |
![]() | Note |
---|---|
You must perform a GT.M database integrity check using the -noonline parameter prior to downgrading a database. The integrity check verifies and clears database header fields required for an orderly downgrade. If an integrity check is not possible due to time constraints, please rely on a rolling upgrade scheme using replication and / or take a backup prior to upgrading the database. |
DU[MPFHEAD] {-FI[LE] file-name |-R[EGION] region-list}
![]() | 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. |
-R[EGION] region-list
The region-list argument may specify more than one region of the current Global Directory in a list separated with commas. DUMPFHEAD -REGION requires the environment variable gtmgbldir to specify a valid Global Directory. For more information on defining gtmgbldir, refer to ChapterA 4: a??Global Directory Editora??.
The -REGION qualifier is incompatible with the -FILE qualifier.
ENDIANCVT [-OUTDB=<outdb-file>] -OV[ERRIDE] <db-file>
ENDIANCVT produces a <outdb-file>of exactly the same size as <db-file>.
Important Ensure adequate storage for <outdb-file> to complete the endian conversion successfully.
![]() | 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. |
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 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).
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:
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-2
Hexadecimal representation of the length of the label (by default 64 - decimal 100).
3-28
Fixed-length ASCII text containing:
"GDS BINARY EXTRACT LEVEL 6": when no region is encrypted.
"GDS BINARY EXTRACT LEVEL 8": when one more regions are encrypted using null IVs.
"GDS BINARY EXTRACT LEVEL 9": when one or regions are encrypted using non-null IVs.
29-41
Fixed-length ASCII text: Date and time of extract in the $ZDATE() format: "YEARMMDD2460SS".
42-48
Fixed-length ASCII text: Decimal maximum block size of the union of each region from which data was extracted.
49-55
Fixed-length ASCII text: Decimal maximum record size of the union of each region from which data was extracted.
56-62
Fixed-length ASCII text:Decimal maximum key size of the union of each region from which data was extracted.
63-69
Fixed-length ASCII text:Boolean indicator of Standard NULL collation (1) or GT.M legacy collation (0).
70-100
Fixed-length ASCII text: Space-padded label specified by the -LABEL qualifier; the default LABEL is "GT.M MUPIP EXTRACT"
For extracts in UTF-8 mode, GT.M prefixes UTF-8 and a space to -LABEL.
The format of the FREEZE qualifier is:
-FR[EEZE]
By default, MUPIP EXTRACT does not "freeze" regions during operation.
-[NO]NULL_IV
Restricts MUPIP EXTRACT to a set of regions. The format of the REGION qualifier is:
-R[EGION]=region-list
Specifies globals for a MUPIP EXTRACT operation. The format of the SELECT qualifier is:
-S[ELECT]= global-specification
The global-specification can be:
![]() | Note |
---|---|
If the rules for selection are complex, it may be easier to construct an ad hoc Global Directory that maps the global variables to be extracted to the database file. This may not be permissible if the database file is part of a replicated instance. If this is the case, work with a backup of the database. |
Redirects database extract to the standard output stream. The format of the STDOUT qualifier is:
-ST[DOUT]
$ mupip extract -format=go -freeze big.glo
This command prevents database updates during a MUPIP EXTRACT operation.
$ mupip extract -format=GO mumps_i.go
$ mupip extract -format=BINARY v5.bin
$ mupip extract -format=ZWR -LABEL=My_Label My_Extract_File
$ mupip extract -nolog FL.GLO
$ mupip extract -select=Tyrannosaurus /dev/tty
This command instructs EXTRACT to dump the global ^Tyrannosaurus to the device (file-name) /dev/tty.
The format of the MUPIP FREEZE command is:
FR[EEZE] {-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
-[NO]A[UTORELEASE] - only valid with -ONLINE -ON[LINE] - only valid with -ON -OV[ERRIDE] -R[ECORD] - only valid with -ON
Clears a freeze set by another process with the same userid.
The format of the OFF qualifier is:
OF[F]
-[NO]A[UTORELEASE]
-[NO]ONL[INE]
![]() | Note |
---|---|
If a database is nearly full, and you about to use MUPIP FREEZE -ON -ONLINE, you may want to use MUPIP EXTEND first as a database file extension will either AUTORELEASE or "harden" the -ONLINE freeze effectively into a -NOONLINE freeze. |
$ mupip freeze -off DEFAULT
This command stops an ongoing MUPIP FREEZE operation on the region DEFAULT.
$ mupip freeze -on "*"
This command prevents updates to all regions in the current Global Directory.
$ set +e $ mupip freeze -on -record "*" $ tar cvf /dev/tape /prod/appl/*.dat $ mupip freeze -off $ set -e
$ mupip freeze -override -off DEFAULT
The format of the MUPIP FTOK command is:
FT[OK] [-DB] [-JNLPOOL] [-RECVPOOL] [-ID] [-ONLY] [-[NO]HEADER] file-list
$ 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]
Always use MUPIP INTEG in the following conditions:
![]() | 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:
INTE[G] [ -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 |
---|---|
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:
|
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.
Checks only index blocks. FAST does not check data blocks.
The format of the FAST qualifier is:
-FA[ST]
-[NO]MAP[=max_imb_errors]
![]() | Note |
---|---|
MUPIP INTEG reports all "incorrectly marked free" errors as they require prompt action. MAP does not restrict their reports. |
![]() | 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. |
-[NO]MAX[KEYSIZE][=integer]
-R[EGION]=region-list
The region-list argument may specify more than one region of the current Global Directory in a list separated with commas. INTEG -REGION requires the environment variable gtmgbldir to specify a valid Global Directory. For more information on defining gtmgbldir, refer to ChapterA 4: a??Global Directory Editora??.
Because a KILL may briefly defer marking the blocks it releases "free" in the bit maps, INTEG -REGION may report spurious block incorrectly marked busy errors. These errors are benign. If these errors occur in conjunction with a "Kill in progress" error, resolve the errors after the "Kill in progress" error is no longer present.
By default, INTEG operates -FILE.
Incompatible with: -FILE, -TN_RESET
The format of the TN_RESET qualifier is:
-TN[_RESET]
By default, INTEG does not modify the block transaction numbers.
Important There should never be a need for a -TN_RESET on a database with only V5 blocks, even when cleaning up after a runaway process.
The -TN_RESET qualifier is incompatible with the -FAST, -BLOCK, -REGION, and -SUBSCRIPT qualifiers.
![]() | Note |
---|---|
Any time a GT.M update opens a database file that was not properly closed, GT.M increments the transaction number by 1000. This automatic increment prevents problems induced by abnormal database closes, but users must always consider this factor in their operational procedures. The rate at which GT.M "uses up" transaction numbers is a function of operational procedures and real database updates. |
-[NO]TR[ANSACTION][=integer]
$ mupip integ -block=4 mumps.dat
This command performs a MUPIP INTEG operation on the BLOCK 4 of mumps.dat.
$ 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]
$ mupip integ -brief mumps.dat
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]
$ mupip integ -fast mumps.dat
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
$ 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
$ mupip integ -map=20 -maxkeysize=20 -transaction=2 mumps.dat
$ mupip integ -map=20 -transaction=2 mumps.dat
$ mupip integ -file mumps.dat -tn_reset
This command resets the transaction number to one in every database block.
$ mupip integ -subscript="^Parrots" mumps.dat
$ mupip integ -subscript="^Amsterdam(100)":"^Bolivia(""Chimes"")" -region DEFAULT
![]() | Note |
---|---|
To specify a literal in the command string, use two double quotation marks for example, ^b(""c""). |
INTRPT process-id
![]() | Important |
---|---|
Ensure that signal SIGUSR1 is not be used by any C external function calls or any (initially non-GT.M) processes that use call-in support, as it is interpreted by GT.M as a signal to trigger the $ZINTERRUPT mechanism. |
Analyzes, extracts, reports, and recovers data using journal files. For a description of the JOURNAL command, refer to ChapterA 6: a??GT.M Journalinga??.
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 |
---|---|
From an application perspective, performing a MUPIP LOAD operation while an application is running may result in an inconsistent application state for the database. |
MUPIP LOAD uses the Global Directory to determine which database files to use.
For information on loading with an M "percent utility," refer to the %GI section of the "M Utility Routines" chapter in GT.M Programmer's Guide. LOAD is typically faster, but the %GI utility can be customized.
Press <CTRL-C> to produce a status message from LOAD. Entering <CTRL-C> twice in quick succession stops LOAD. A LOAD that is manually stopped or stops because of an internal error is incomplete and may lack application level integrity, but will not adversely affect the database structure unless terminated with a kill -9.
![]() | Note |
---|---|
The MUPIP EXTRACT or MUPIP LOAD procedure for large databases are time consuming due to the volume of data that has to be converted from binary to ZWR format (on source) and vice versa (on target). One must also consider the fact that the extract file can be very large for a large database. Users must ensure adequate storage support the size of the extract file and the space occupied by the source and target databases. In order to reduce the total time and space it takes to transfer database content from one endian platform to another, it is efficient to convert the endian format in-place for a database and transfer the converted database. See MUPIP ENDIANCVT for more information on converting the endian format of a database file. |
The following sections describe the optional qualifiers of the MUPIP LOAD command.
B[INARY] - Binary format GO - Global Output format Z[WR] - ZWRITE format
-BE[GIN]=integer
![]() | Important |
---|---|
Always consider the number of header records for choosing a -BEGIN point. See FORMAT qualifier for more information. |
-FI[LL_FACTOR]=integer
![]() | Note |
---|---|
FILL_FACTOR is useful when updates add or grow records reasonably uniformly across a broad key range. If updates are at ever ascending or descending keys, or if the record set and record sizes are relatively static in the face of updates, FILL_FACTOR won't provide much benefit. |
$ mupip load ex_file.go
This command loads the content of the extract file ex_file.go to the current database.
$ mupip load -format=go big.glo
This command loads an extract file big.glo in the current database.
$ mupip load -begin=5 -end=10 rs.glo
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
$ mupip load -fill_factor=5 reobs.glo
This command set the FILL_FACTOR to 5 for loading an extract file in the current database.
$cat big.glo | mupip load -stdin $mupip load -stdin < big.glo
MUPIP RCTLDUMP [dir1]
$ 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
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 |
---|---|
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 |
---|---|
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. |
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.
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
The optional qualifiers for MUPIP REORG are:
![]() | Note: |
---|---|
V7.0-000 and up do not support REORG -DOWNGRADE. |
-ENCR[YPT]=<key>
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"; }) };
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".
MUPIP SET -NOENCRYPTABLE -REGION <region-list>
MUPIP SET -ENCRYPTIONCOMPLETE -REGION <region-list>
![]() | Note |
---|---|
|
-T[RUNCATE][=percentage]
![]() | Note |
---|---|
TRUNCATE does not complete if there is a concurrent online BACKUP or use of the snapshot mechanism, for example by INTEG. |
![]() | Warning |
---|---|
Because any competing updates may interfere with MUPIP's ability to free space, minimize or prevent competing updates. |
$ 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 $
Blocks processed - the number of blocks originally used by the global variable
Blocks coalesced - the number of blocks that were sufficiently compacted enough to free a block
Blocks split - the number of blocks expanded enough to require the allocation of a new block
Levels eliminated - reduction in the depth of the global variable tree
Blocks extended - the number of blocks the database grew during the reorg
$ mupip reorg -exclude="^b2a,^A4gsEQ2e:^A93"
$ mupip reorg -fill_factor=80
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
gpg --gen-key
Edit the key to add a new sub-key:
gpg --edit-key helen.keymaster@gt.m
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
Control the logical multi-site operation of GT.M. For more information on the qualifiers of the MUPIP REPLICATE command, refer to ChapterA 7: a??Database Replicationa?? .
The format of the RESTORE command is:
RES[TORE] [-NET[TIMEOUT]] [-[NO]E[XTEND]] dbfile bytestream-bkup-list|<TCP_socket_address>
dbfile
identifies the name of the database file that RESTORE uses as a starting point.For more information on the -NETTIMEOUT qualifier, refer to a??-NETtimeouta?? in the MUPIP BACKUP section of this chapter.
The format of the EXTEND qualifier is:
-[NO]E[XTEND]
By default, RESTORE automatically extends the database file.
$ mupip restore backup.dat $backup_dir/backup.bk1, $backup_dir/backup.bk2, $backup_dir/backup.bk3
$ mupip restore gtm.dat '"gzip -d -c online5pipe.inc.gz |"'
$ mupip backup -bytestream region1,region2 tcp://hostname1:port1,tcp://hostname1:port2 -nettimeout=420
$ mupip restore region1.dat tcp://hostname1:port1 -nettimeout=420
$ mupip restore region2.dat tcp://hostname1:port2 -nettimeout=420
The format of the MUPIP RUNDOWN command is:
RU[NDOWN] {-FILE file-name|-REGION region-list|-RELINKCTL [dir]|-OVERRIDE}
A successful MUPIP RUNDOWN of a database region removes any current MUPIP FREEZE.
The RUNDOWN command may include one of the following qualifiers:
-F[ile] -R[egion]=region-list -RELinkctl [dir1] -Override
Reports the details of a space delimited list of semaphores IDs.
The format of the MUPIP SEMAPHORE command is:
MUPIP SEMAPHORE <sem-ids-list>
Use MUPIP SET for performance tuning and/or modifying certain database and journal file attributes.
The format of the SET command is:
SET {-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
Specifies that the argument is a journal-file-name. The format of the JNLFILE qualifier is:
-JNLF[ILE] journal-file-name
Specifies whether replication is on or off. The format of the REPLICATION qualifier is:
-REP[LICATION]={ON|OFF}
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.
-AC[CESS_METHOD]=code
For more information on specifying the ACCESS_METHOD, refer to a??Segment Qualifiersa??.
Performs some basic encryption checks and marks the database as encryptable. Note that marking a database as encryptable does not encrypt the database.For more information on encrypting a database, refer to a??-Encrypta??. The format of the ENCRYPTABLE qualifier is:
-[NO]ENCRYPTA[BLE]
Checks whether a prior MUPIP REORG -ENCRYPT completed successfully and marks encryption as complete. For usage scenarios of MUPIP SET -ENCRYPTIONCOMPLETE, refer to a??-Encrypta??. The format of the ENCRYPTIONCOMPLETE qualifier is:
-ENCRYPTI[ONCOMPELTE]
-EX[TENSION_COUNT]=integer
For more information on specifying the EXTENSION_COUNT, refer to a??Segment Qualifiersa??.
-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 |
---|---|
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. |
-[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.
![]() | Note |
---|---|
In regions that have journaling enabled and on, users can switch journal files without either requiring standalone access or freezing updates. |
The format of the JOURNAL qualifier is:
-[NO]J[OURNAL][=journal-option-list]
For detailed description of the all JOURNAL qualifiers and its keywords, refer to a??SET -JOURNAL Options a??.
-[NO]LC[K_SHARES_DB_CRIT]
The default is Sep(arate)/FALSE.
For more information, refer to the -[NO]L[OCK_CRIT] section of GDE a??Region Qualifiersa??.
-PRO[BLKSPLIT]=integer
-PA[RTIAL_RECOV_BYPASS]
For more information, refer to the CORRUPT_FILE qualifier in a??CHANGE -FIleheader Qualifiersa??.
-[NO]REA[D_ONLY]
fuser <db-filename> | awk -F: '{if(length($NF))exit(1)}' && $gtm_dist/mupip set -noread_only -file <db-filename>
![]() | Note |
---|---|
When the first process connects to a database, it creates a access-control semaphore as part of management of the shared resource. However, when a process connects to a -READ_ONLY database, each create a private copy of the in-memory structures for the database and thus a private semaphore. |
$ mupip set -journal=on,nobefore -region "*"
This example enables NOBEFORE image journaling and turns on journaling for all regions.
$ mupip set -version=V5 -file mumps.dat Database file mumps.dat now has desired DB format V5
This example disables the V6 extensions for database file mumps.dat.
mupip set -flush_time=01:00:00:00 -region DEFAULT
$ mupip set -region REPTILES -inst_freeze_on_error
This example enables custom errors in region REPTILES to cause an Instance Freeze.
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
-h[euristic]={sc[an][,level=<lvl>] | a[rsample][,samples=<smpls>] | i[mpsample][,samples=<smpls>]}
estimation-technique is one of the following:
![]() | 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. |
The format of the SELECT qualifier is:
-s[elect]=global-name-list
-R[EGION]=region-list
$ mupip size -heuristic="impsample,samples=2000" -select='^y*' -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'
The format of the SUBSCRIPT qualifier is:
-su[bscript]=global-list
![]() | 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. |
The format of the STOP command is:
MUPIP ST[OP] process-id
![]() | 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 forgtm_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 |
---|---|
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. |
-SELE[CT][=name-list*][ <select-output-file>]
MUPIP TRIGGER -SELECT displays all output including errors on STDOUT.
MUPIP TRIGGER -SELECT works even if a multi-line XECUTE string does not terminate with a newline character. For more information on multi-line XECUTE strings, refer to the -xecute="|<<strlit1"|>> section under Trigger Definition File in the Triggers chapter and the $ZTRIGGER() section in the Functions chapter of the GT.M Programmer's Guide.
in the Programmers Guide.
![]() | 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 |
---|---|
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). |
Upgrades older trigger definitions into current format.
The format of the UPGRADE qualifier is:
-UPGRADE
To create a new trigger for global node ^Acct("ID"):
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!"""
Execute a command like the following:
$ mupip trigger -triggerfile=triggers.trg
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.
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"):
Begin by executing the following command:
$ mupip trigger -select="^Acct*"Output file:
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!"""
;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!"""
Execute a command like the following:
$ mupip trigger -triggerfile=trigger_mod.trg
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 =========================================
To delete an existing trigger for global node ^Acct("ID"):
Begin by executing the following command:
$ mupip trigger -select="^Acct*"Output file:
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!"""
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"):
+^Acct("ID") -name=ValidateAcct -commands=S -xecute="Write ""Hello Mars!"""
Verify that the
ValidateAccount
trigger exists by executing the following command:$ mupip trigger -select="^Acct*"Output file:
;trigger name: ValidateAccount# cycle: 3 +^Acct("ID") -name=ValidateAccount -commands=S -xecute="Write ""Hello Mars!"""
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
toValidateAcct
.
The format of the MUPIP UPGRADE command is:
UP[GRADE] [-FILE file-name | [-REGION] region-list]