The BACKUP command allows you to save the contents of the database. Unless used with the /ONLINE qualifier, BACKUP suspends updates to all regions specified by the BACKUP command from the time it starts the first region until it finishes the last region. BACKUP ensures a consistent application state across all database regions involved in the backup. Even with the /NOONLINE qualifier, BACKUP does not suspend processes that only read from the database.

BACKUP ONLINE creates a backup of the database at the time the backup command is issued. If the running processes subsequently update the database, the backup does not reflect those updates. Since the state of the database at the start of the backup is well defined, (whereas the state of the database at the backup completion is not well defined when the backup command is issued), a MUPIP BACKUP /ONLINE has the advantage that a meaningful name such as "beginning of processing day" can be associated with the backup.

The format of the BACKUP command is:

B[ACKUP] [/qualifier[...]] region-name[,...] FILE-SPECIFICATION

Example:

$ BACKUP /BYTESTREAM ACN,HIST [.BKUP]

The optional qualifiers are:

By default, BACKUP is /DATABASE/ONLINE.

If any region name does not map to an existing accessible file, or if any element of the destination list is invalid, BACKUP rejects the command.

The BACKUP command may specify more than one region of the current Global Directory in a list. Regions are separated by commas. Any region-name may include the DCL wildcard characters * and %.

To BACKUP only one region, the output-specification can resolve to either an RMS file or directory name. To BACKUP several regions, the output-specification can either resolve to one of the following:

If the output-specification is a directory, MUPIP assigns each backup file the same name as the file associated with the segment of the corresponding region. Therefore, the target directory must not contain any of the database files to be backed up, and all regions to be backed up must have unique database file names (violating either requirement implies two or more files with the same name in the same directory).

When BACKUP is /BYTESTREAM, and output-specification is not a directory, output is not limited to VMS files. A TCP socket can also be specified as a destination for the backup of a region. The syntax is: TCP://<machine-name>:<port>. There must be an active listener at the specified destination. Note that since MUPIP RESTORE can listen at a TCP socket and the combination of BACKUP on one machine with a RESTORE on another may well be the most efficient way to create remote backups.

When individual file names or TCP sockets are specified for backup (as opposed to specifying a directory), there is a one-to-one, left-to-right mapping of region names to the output-specification names. Any wild card in the region names or the backup file names is expanded in the same order in which VMS expands that wild card. The number of regions must match the number of files, and the regions are mapped to the files from left to right in each list. For example, if the Global Directory has regions ACN, HIST, UBG1 and UBG2:

MUPIP BACK /BYTE * FILE1.BCK,FILE2,BCK,
TCP://file3.offsite.com:5986,FILE4.BCK

Region ACN maps to FILE1.BCK, HIST maps to
FILE2.BCK, UBG1 maps to a listener at port
5986 at file3.offsite.com, and UBG2 maps
to FILE4.BCK.

MUPIP BACK /BYTE ACN,UBG*,HIST
FILE1.BCK,FILE2,BCK,TCP://FILE3.OFFSITE.COM:5986,FILE4 .BCK

Region ACN maps to FILE1.BCK, UBG1 maps to
FILE2.BCK, UBG2 maps to a listener at port
5986 at file3.offsite.com, and HIST maps to
FILE4.BCK.

MUPIP BACK /BYTE "*" FILE1.BCK,FILE2,BCK,
TCP://file3.offsite.com:5986,FILE4.BCK

Region ACN maps to FILE1.BCK, HIST maps to
FILE2.BCK, UBG1 maps to a listener at port
5986 at file3.offsite.com, and UBG2 maps to
FILE4.BCK.

MUPIP BACK /BYTE "ACN,UBG*,HIST" FILE1.BCK,FILE2,BCK,
TCP://FILE3.OFFSITE.COM:5986,FILE4.BCK

Region ACN maps to FILE1.BCK, UBG1 maps to
FILE2.BCK, UBG2 maps to a listener at port
5986 at file3.offsite.com, and HIST maps to
FILE4.BCK.

	BACKUP protects against overwriting an existing file. If a file with the name exists already, BACKUP will complete successfully to a file with a higher version number.

<CTRL-C> or <CTRL-Y> terminates BACKUP. If a BACKUP terminates due to operator intervention or an error, the backup of the region in process at the time of the termination is not valid. If the termination was due to operator intervention, BACKUP attempts to delete any partially complete files. With both types of backups, previously processed regions are structurally valid, but may be of limited usefulness since some regions are backed up and others are not. This implies that the overall backup lacks application consistency; therefore, only trust backups that complete normally.

When BACKUP /BYTESTREAM delivers its output to a magnetic tape or across DECnet, DCL commands preceding the BACKUP must establish an appropriate blocksize. When the output is a magnetic tape, the MOUNT command should specify /BLOCKSIZE= as a multiple of the GDS database blocksize + 12 bytes for overhead. When the output file is on a different DECnet node, SET RMS should specify NET= as at least the GDS database blocksize + 12 bytes for overhead. BACKUP uses the overhead for /BYTESTREAM operations, but not for /DATABASE operations. When directing the output file to a magnetic tape, use DCL to MOUNT the tape /INITIALIZE=CONTINUATION. This causes automatic handling of multiple volumes. If the block size is too small, the BACKUP fails when it encounters a full block.

/B[YTESTREAM]

The /B[YTESTREAM] qualifier specifies that BACKUP only include blocks from the databases that have changed since a prior point specified by the /SINCE or /TRANSACTION qualifiers. BACKUP may output to a file on any device that supports files, including magnetic tapes. MUPIP RESTORE integrates the results of a BACKUP /BYTESTREAM into a database.

When the /BYTESTREAM qualifier is used with the /ONLINE qualifier, you may send the output to a TCP/IP connection.

Example:

$MUPIP BACKUP /BYTESTREAM /REG REGA
TCP://192.168.109.81:2453

The /BYTESTREAM qualifier is not compatible with the /COMPREHENSIVE or /DATABASE qualifiers.

/C[OMPREHENSIVE]

The /COMPREHENSIVE qualifier has been replaced by the /DATABASE qualifier. For upward compatibility, MUPIP temporarily continues to support the COMPREHENSIVE qualifier. The function of the COMPREHENSIVE qualifier is the same as the /DATABASE qualifier. Refer to the description of the /DATABASE qualifier for details.

/DATABASE

Instructs the BACKUP utility to copy the files of all selected regions from disk to disk. When complete, the backup copy is ready for use as a GT.M database. This option does not support backup to magnetic tape or TCP sockets (the target device must support random access to files).

The /DATABASE qualifier ensures all the information buffered in cache is first flushed to the disk. The /DATABASE qualifier is only compatible with the /JOURNAL, /[NO]NEW[JNLFILES], /ONLINE, and /RECORD qualifiers.

BACKUP /DATABASE produces a result similar to the result produced by a DCL COPY command or some variations of the DCL BACKUP command, except that consistency of the database is ensured with MUPIP, but must be separately implemented (e.g., with a FREEZE and a FLUSH) if the DCL commands are used.

By default, BACKUP is /DATABASE/ONLINE.

/I[NCREMENTAL]

The /INCREMENTAL qualifier has been replaced by the /BYTESTREAM qualifier. For upward compatibility, MUPIP temporarily continues to support the /INCREMENTAL qualifier. The function of the /INCREMENTAL qualifier is the same as the /BYTESTREAM qualifier. Refer to the description of the /BYTESTREAM qualifier for details.

/[NO]J[OURNAL][=options...]

When used in conjunction with /DATABASE /NEWJNLFILES, this qualifier specifies journaling information to be recorded into the file header of the backup of the database file(s).

The database file header stores the journaling options for the current database, including the journal file name. The default behavior, if this qualifier is not specified, is for the journaling options in the backup to be identical to those of the database. This is appropriate behavior if the backup is to be restored and used as a replacement for the database, (e.g., in the event of failure of the I/O subsystem on which the database is stored). However, if the backup copy of the database is used on the same machine for other purposes, such as report generation or for development and testing of new software, the journaling information in the database file header could lead to a corrupt journal file since updates to the original database and the copy would write over each other. Using this qualifier can protect against this outcome.

Also, when new journal files are created for the database files being backed up, the new journal files have a "backchain" pointer to the previous journal file. MUPIP RECOVER and ROLLBACK will automatically follow these backchain pointers as needed to perform their tasks. This qualifier can also be used to create new journal files with no backchain pointer.

/NOJOURNAL creates a backup with all journaling options cleared.

/JOURNAL=OFF creates a backup with journaling turned OFF (equivalent to executing a MUPIP SET /JOURNAL=OFF on the backup database)

/JOURNAL=DISABLE creates a backup with journaling disabled (equivalent to executing MUPIP SET /JOURNAL=DISABLE on the backup database. /NOJOURNAL is equivalent to /JOURNAL=DISABLE. Both clear journaling options in a backup database.

/[NO]JOURNAL=NOPREVJNLFILES to create new journal files with no backchain pointer. /NOJOURNAL cannot have a value.

Multiple options can be specified by including them in a parenthesized list, e.g., /JOURNAL=(DISABLE, NOPREVJNLFILES).

/NET[TIMEOUT]=seconds

Specifies the timeout period when BACKUP data is sent over a TCP/IP connection. This qualifier is meaningful only with the /ONLINE and /BYTESTREAM qualifiers, otherwise GT.M ignores the command. The default value is 30 seconds.

The /NET[TIMEOUT] qualifier is not compatible with the /DATABASE and /COMPREHENSIVE qualifiers.

/[NO]NEW[JNLFILES]

Specifies whether or not GT.M switches journal files for updates occurring after the start of the backup.

/[NO]O[NLINE]

Specifies that while the backup is active, other processes can read from, and update, the database without affecting the result of the backup. By default, BACKUP is /ONLINE.

BACKUP -ONLINE allows continued operation of the application using the database. The -BYTESTREAM form is able to transfer to output to a TCP/IP connection or a pipe.

/R[ECORD]

Instructs the BACKUP utility to record this backup as a reference point for subsequent /BYTESTREAM backups. For more information about using the /RECORD qualifier with the /SINCE qualifier, refer to the /SINCE qualifier section below.

Each time a BACKUP specifies /RECORD, that backup, relative to the time stamp or transaction number, replaces the previously recorded backup timestamp as the /RECORD reference point for the file.

/S[INCE]=keyword

A BACKUP /BYTESTREAM backs up those blocks that have changed since a specified point in the state of the database.

/SINCE accepts the following keywords:

The SINCE qualifier is incompatible with the /COMPREHENSIVE, /DATABASE, and /TRANSACTION qualifiers.

By default, BACKUP /BYTESTREAM operates as /S[INCE]=DATABASE.

/T[RANSACTION]=transaction-number

Specifies a starting transaction that causes BACKUP /BYTESTREAM to copy all blocks that have been changed by the specified transaction and all subsequent transactions. Transaction numbers are hexadecimal. They appear in a DSE DUMP /FILEHEADER with a "Current TN" label. If the transaction number is invalid, BACKUP reports an error and rejects the command.

BACKUP /BYTESTREAM /TRANSACTION=1 copies all in-use blocks, and produces a result similar to the result produced by BACKUP /DATABASE. However:

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 backup involving multiple regions, or where a previous /BYTESTREAM backup file is inadvertently deleted and a new backup is required to replace it.

The /TRANSACTION qualifier is incompatible with the /COMPREHENSIVE, /DATABASE, and /SINCE qualifiers.

BACKUP Examples

$ MUPIP BACKUP * [GTM.BKUP]

Assuming that [GTM.BKUP] exists and that the current Global Directory, as specified by the environment variable $GTMGBLDIR, has regions that map database files to [GTM.PROD]TBLS.DAT and [GTM.PROD]UBG.DAT, this command creates ready-to-run database backup files [GTM.BKUP]TBLS.DAT and [GTM.BKUP]UBG.DAT.

Example:

$ MUPIP BACKUP /BYTESTREAM ACN,HIST [.BKUP]

This command creates bytestream backup files [.BKUP]ACN.DAT and [.BKUP]HIST.DAT, assuming that [.BKUP] is an existing subdirectory and that the current Global Directory has regions ACN and HIST that map to files ACN.DAT and HIST.DAT.

Example:

$ MUPIP BACKUP * [.backup]

Example:

$ INIT MSA0: FULL
$ MOUNT /INIT=CONT BLOCK=2060 MSA0: FULL
$ MUPIP BACK /BYTE /TRAN=1 MAIN_REG FULL:MAIN

In this example, the first command initializes a magnetic tape with the label FULL. The second command mounts the tape with OpenVMS automatic volume initialization and a block size of 2060. The magnetic tape block size of 2060 handles a database block of 2048 bytes. The MUPIP command backs up the dynamic segment associated with MAIN_REG to the tape. Because of the /TRANSACTION=1, BACKUP copies all blocks in use to the tape.

Example:

$ MUPIP BACKUP MAIN*,%XREF USR$BCK:[TUESDAY]

This comprehensively backs up all regions that have a name starting with "MAIN," and all regions that have names starting with any single character and ending with "XREF" to the directory USR$BCK:[TUESDAY].

Example:

$ MUPIP BACKUP /INCREMENTAL *[19990505]

This backs up all changes made since the last BACKUP /FDATABASE for all regions of the database defined by the current Global Directory into the RMS directory [19990505]. BACKUP creates files in the directory, with names corresponding to each dynamic segment's file name.

	GT.M allows multiple regions to have the same database file name. This occurs because different regions can have the same file names as long as they reside in different directories. However, FIS does not recommend this practice. If this happens, you should specify explicit file names for each region, and do not use the command in the above example.

CONVERT transforms M routines in the sequential format, described by the MDC, into individual RMS source files for use by GT.M. Use CONVERT to make MRO format files accessible as GT.M routines.

The format of the CONVERT command is:

CO[NVERT] [/qualifier] file-spec directory-spec

CONVERT takes its input from the file defined by the file-specification. CONVERT places the output files in the directory defined by the directory-specification. CONVERT uses the routine name and an ".M" extension as the output file name for each routine.

Because OpenVMS uses the percent (%) character as a wildcard, CONVERT places any routine name starting with % to a file-name starting with the under-bar (_) character. CONVERT transforms all white space at the beginning of a routine line into a single tab character.

<CTRL-C> or <CTRL-Y> terminates CONVERT. Files converted before the termination are usable.

CONVERT takes only one qualifier:

/F[ORMAT]=RO

Specifies the format of the input file. The RO (Routine Output) format code is the default and the only code CONVERT recognizes.

CREATE creates and initializes database files using the information in a Global Directory file.

Use the MUPIP CREATE command to create new database files. If a file already exists for any segment, CREATE takes no action for that segment.

The format of the CREATE command is:

CR[EATE] [/qualifier]

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

	To access a large database, a process may need a higher OpenVMS BYTLM. If you exceed a quota, contact your system manager.

/R[EGION]=region-name

CREATE /region=reg1 accepts non-alphabetic characters for region names.

Specifies a single region for creation of a database file. By default, the CREATE command creates database files for all regions in the current Global Directory that do not have files.

Exit or <CTRL Z> stops MUPIP, and returns control to the process from which MUPIP was invoked.

The format of the EXIT command is:

EXI[T]

The EXIT command does not accept any qualifiers.

EXTEND expands a GDS database file. Databases with a BG access method generally extend automatically when they become full. MM databases must be MUPIP EXTENDed. For MM segments, EXTEND requires exclusive or stand-alone access to the file. When EXTEND requires exclusive database access and cannot obtain it, MUPIP rejects the command.

When the journal file is unable to extend (e.g., if the disk is full), GT.M turns off journaling and no longer generates a GTMASSERT.

EXTEND increases the size of a database file. A database file will automatically extend under normal use. There is usually no need to extend a file with MUPIP.

The format of the EXTEND command is:

EXTE[ND] /qualifier] region-name

The required region-name parameter specifies the name of the region you want to expand. EXTEND uses the Global Directory to map the region to the dynamic segment and the segment to the file.

EXTEND takes one optional qualifier:

/B[LOCKS]=blocks

Specifies the number of GDS database blocks by which MUPIP should extend the file. GDS files use additional blocks for bitmaps. EXTEND adds the specified number of blocks plus the bitmap blocks required as overhead. For more information about bitmaps, refer to the "Greystone Database Structure" chapter.

By default, EXTEND uses the extension value in the file header as the number of GDS blocks by which to extend the database file.

EXTRACT copies globals from the current database to a sequential output file in one of three formats–GO, BINARY, or ZWR. Use EXTRACT to backup specific globals or to extract data from the database for use by another system. EXTRACT uses the Global Directory to determine which database files to use. In addition, EXTRACT supports user collation routines. EXTRACT may operate concurrently with normal GT.M database access.

To ensure that an EXTRACT reflects a consistent application state, you must:

The format of the EXTRACT command is:

EXTR[ACT] [/qualifier[...]] file-specification

The optional qualifiers are:

EXTRACT places its output in the file defined by the file-specification . EXTRACT may output to an RMS file on any device that supports such files, including magnetic tapes.

	Magnetic tapes may have a smaller maximum file size than disks.When directing the output file to a magnetic tape, use DCL to MOUNT the tape /INITIALIZE=CONTINUATION. This causes automatic handling of multiple volumes. When mounting a volume to tape for an EXTRACT, specify a blocksize that is eight (8) bytes larger than the size of the blocks in the database to accommodate RMS overhead.

For information on extracting globals with the %GO utility, refer to the "M Utility Routines" chapter of the GT.M Programmer's Guide. EXTRACT is typically faster, but %GO can be customized.

<CTRL-Y> or <CTRL-C> produces a status message from EXTRACT. Entering <CTRL-C> twice in quick succession terminates EXTRACT. An EXTRACT terminated abnormally by operator action or error produces incomplete output.

/FO[RMAT]=GO|B[INARY] | Z[WR]

Specifies the format of the output file.

The format codes are:

/FORMAT=GO stores the data in record pairs. Each global node produces one record for the key and one for the data. /FORMAT=GO has two header records.

EXTRACT /FORMAT=BINARY works much faster than EXTRACT /FORMAT=GO and EXTRACT /FORMAT=ZWR. However, it cannot be used to transport binary data from one computer architecture to another. EXTRACT /FORMAT=ZWR can be used to transport text (binary data from GT.M on one platform to GT.M on another platform.) EXTRACT /FORMAT=GO can be used to transport text and data from one M implementation to another.

	There is no defined standard to transport binary data from one GT.M implementation to another.

By default, EXTRACT uses /FORMAT=ZWR.

/FR[EEZE]

Prevents database updates to all database files from which the EXTRACT is copying records. /FREEZE ensures that the EXTRACT captures a "sharp" image of the globals, rather than one "blurred" by updates occurring while the copy is in progress.

By default, EXTRACT does not freeze regions during operation.

/LA[BEL]=text

Specifies the text string that becomes the first record in the output file. Enclose labels containing punctuation marks or lowercase characters in quotation marks (" "). EXTRACT /FORMAT=BINARY truncates the label text to 32 characters.

By default, EXTRACT uses the label "GT.M MUPIP EXTRACT."

For more detailed information about the /FORMAT=BINARY header label, refer to the description of EXTRACT /FORMAT=BINARY.

/[NO]LO[G]

For each global extracted, this qualifier specifies whether or not to display a message on SYS$OUTPUT . The message displays the number of global nodes, the maximum subscript length and maximum data length for each global.

By default, EXTRACT operates /LOG.

/S[ELECT]=global-name

Global specification can be a parenthetical list, such as (a,B,C). In this case, EXTRACT selects all globals except ^A, ^B, and ^C.

/S[ELECT]=global-name-list

Specifies the global(s) to extract. The caret symbol (^) in the specification of the global name is optional. Enclose lowercase global names in quotation marks (" ").

The global-specification can be:

By default, EXTRACT selects all globals, as if it had the qualifier /SELECT=*

	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 is not permissible if the database file is part of a replicated instance. If this is the case, work with a backup of the database.

$ MUPIP EXTRACT /NOLOG FL.GLO

$ INIT MSA0: SPECIAL
$ MOUNT/INIT=CONT/BLOCK=4104 MSA0: SPECIAL
$ MUPIP EXTR/FO=BIN/SEL=("a2",M:Z)/LAB="SPSAVE" MSA0:SP.SVX

$ MUPIP EXTRACT/SELECT=DRG TT

FREEZE redirects updates to the database. Use FREEZE to coordinate database activity with the invocation of an operating system utility that accesses the database file.

	MUPIP FREEZE /ON prevents updates to one or more database files. Processes that are attempting updates "hang" until the FREEZE is removed by the MUPIP FREEZE /OFF command or DSE. Make sure that procedures for using MUPIP FREEZE, whether manual or automated, include provisions for removing the FREEZE in all appropriate cases, including when errors disrupt the normal flow.

To ensure that a copy or reorganized version of a database file contains a consistent set of records, concurrent MUPIP utilities, such as BACKUP (without the ONLINE qualifier) and EXTRACT, include mechanisms to ensure that the database does not change while the MUPIP utility is performing an action. FIS recommends the use of the /ONLINE qualifier with BACKUP, followed by an extract from the backup.

If you want to use a non-GT.M utility to perform a backup or reorganization, you may give that utility stand-alone access to the file.

Common uses of the FREEZE command are:

The format of the FREEZE command is:

F[REEZE] /ON[/RECORD] | /OFF[/OVERRIDE] region-list

The region-list identifies the target of the FREEZE. Region-lists may include the DCL wildcards % and *.

FREEZE must include one of the qualifiers:

The optional qualifiers are:

/OF[F]

Stops a current FREEZE, unless used with /OVERRIDE. /OFF must be issued by the process that initiated the FREEZE. The /OFF qualifier is incompatible with the /ON and /RECORD qualifiers.

/ON

Specifies the start of a FREEZE. The /ON qualifier is incompatible with the /OFF and /OVERRIDE qualifiers.

/OV[ERRIDE]

Enables another process to end a freeze. /OVERRIDE should not be necessary (and may even be dangerous) in most schemes. /OVERRIDE is provided to allow error recovery in case a procedure with a freeze fails to release. The /OVERRIDE qualifier is incompatible with the /ON and /RECORD qualifiers.

/R[ECORD]

Specifies that the FREEZE utility should record an event as a reference point for subsequent backups. When a FREEZE specifies /RECORD, the current transaction identifier replaces the previously RECORDed transaction identifier for the database file. /RECORD is useful for integrating MUPIP BACKUP /BYTESTREAM with an external backup mechanism. The /RECORD qualifier is incompatible with the /OFF and /OVERRIDE qualifiers.

$ MUPIP FREEZE MUMPS.DAT

$ MUPIP FREEZE /OFF /OVERRIDE MUMPS.DAT

$ SET NOON
$ MUPIP FREEZE /ON /RECORD *
$ BACKUP PROD:[APP1.DATA]*.DAT TAPE:WEEKLY.SAV
/SAVE /REWIND
$ MUPIP FREEZE /OFF *
$ SET ON

HELP provides online information about MUPIP commands and qualifiers. HELP uses conventions similar to the OpenVMS help facility.

The format of the HELP command is:

H[ELP] [help topic]

The HELP command does not accept any qualifiers. Enter the MUPIP command for which you want information at the TOPIC prompt. Press <RETURN> or <CTRL-Z> to exit the help facility.

The INTEG command performs an integrity check on a GT.M database file. INTEG operates on one or more regions in the current Global Directory, and suspends concurrent updates to those regions during its operation. INTEG of a single file database, without a Global Directory, requires exclusive (standalone) access to that file. The order in which INTEG selects database regions is a function of file system layout and may vary as files are moved or created. If you want to generate an integ where the output always lists database files in a predictable sequence, run the integs one at a time. For example, to compare output with a reference file, run INTEG on one file at a time.

Use INTEG at the following times:

The format of the INTEG command is:

I[NTEG] [/qualifier[...]] [/FILE] file-specification | /REGION region-name

INTEG requires the specification of either file(s) or region(s).

The available qualifiers are:

The file-specification directly identifies the database file to INTEG. The region-list identifies one or more regions that, in turn, identify database files through the current Global Directory.

Analyze errors reported by INTEG immediately, to prevent further corruption. FIS strongly recommends fixing the following errors as soon as they are discovered:

INTEG /FAST and the "regular" INTEG both report these errors. Other database errors do not pose the threat of rapidly spreading problems in GDS files. However, if operations continue, the errors may cause the following problems:

When you repair the GT.M database you must 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 the "Maintaining Database Integrity" chapter. Contact your regular GT.M support for help assessing INTEG errors.

<CTRL-C> or <CTRL-Y> stops INTEG before the process completes.

/A[DJACENCY]=integer

Specifies the range of blocks that INTEG considers a block adjacent to another database block on the same level. The adjacency report from INTEG gives an approximation of physical data density which directly affects efficient database access. In effect, this measures how well a database is organized. Implementing a high degree of adjacency improves system response time. Use the /ADJACENCY qualifier to adjust the reporting to reflect characteristics of your disks. For example, select a factor that matches the number of sectors on a drive. To improve the adjacency, use MUPIP REORG.

-By default, INTEG uses /ADJACENCY=10.

/BL[OCK]=block-number

Specifies the block at which to start checking a sub-tree of the database. /BLOCK cannot detect "incorrectly marked busy errors." Block numbers are displayed in an INTEG error report or by using DSE.

The /BLOCK qualifier is incompatible with the /SUBSCRIPT and /TN_RESET qualifiers.

/BR[IEF]

Specifies an INTEG summary report which displays the total number of directory, index and data blocks. The /BRIEF qualifier is incompatible with the /FULL qualifier.

By default, INTEG reports are /BRIEF.

/FA[ST]

Specifies that INTEG checks only index blocks. INTEG /FAST does not check data blocks. INTEG /FAST produces results significantly faster than a full INTEG because the majority of blocks in a typical database are data blocks. While INTEG /FAST is not a replacement for a full INTEG, it very quickly detects those errors that must be repaired immediately to prevent accelerated database damage.

The /FAST qualifier is incompatible with the /TN_RESET qualifier.

By default, INTEG checks all active index and data blocks in the database.

/FI[LE]

Specifies that the parameter to the INTEG command is a file-specification . INTEG FILE requires exclusive (stand-alone) access to a database file and does not require a Global Directory. Because it has stand-alone access to the file, INTEG /FILE is able to check whether the reference count is zero. A non-zero reference count is indicative of the prior abnormal termination of the database.

The /FILE qualifier is incompatible with the /REGION qualifier.

By default, INTEG operates /FILE.

/FU[LL]

Specifies an expanded INTEG report which displays the number of index and data blocks in the directory tree and in each global variable tree as well as the total number of directory, index and data blocks. The /FULL qualifier is incompatible with the /BRIEF qualifier.

By default, INTEG reports are /BRIEF.

/[NO]K[EYRANGES]

Specifies whether or not the INTEG report includes key ranges that identify the data suspected of problems detected by INTEG.

By default, INTEG displays /KEYRANGES

/[NO]MAP[=integer]

Specifies the maximum number of "incorrectly marked busy errors" that INTEG reports.

/NOMAP removes limits on incorrectly marked busy reporting so that INTEG reports all map errors. /NOMAP does not accept assignment of an argument.

	Because incorrectly marked free errors are very dangerous, INTEG always reports them, and /MAP does not affect them.

An error in an index block prevents INTEG from processing potentially large areas of the database. A single "primary" error may cause large numbers of "secondary" incorrectly marked busy errors. Because "real" or primary incorrectly marked busy errors only make "empty" blocks unavailable to the system, they are low impact and do not require immediate repair.

	After a system crash and a database recovery with MUPIP recover or rollback, the database can legitimately have benign, incorrectly marked busy errors. These errors do not require immediate repair. Schedule repairs for the next convenient opportunity.

By default, INTEG reports a maximum of 10 map errors (/MAP=10).

/[NO]MAX[KEYSIZE][=integer]

Specifies the maximum number of "key size too large" errors that INTEG reports.

/NOMAXKEYSIZE removes limits on key size reporting so that INTEG reports all key size too large errors. /NOMAXKEYSIZE does not accept assignment of an argument.

"Key size too large" errors should normally only occur after you use DSE CHANGE /FILEHEADER /KEY_MAX_SIZE to reduce the maximum key size.

By default, INTEG reports a maximum of 10 key size errors (/MAXKEYSIZE=10).

/[NO]TR[ANSACTION][=integer]

Specifies the maximum number of block transaction- number-too-large errors that INTEG reports.

/NOTRANSACTION removes limits on transaction reporting so INTEG reports all transaction number errors. /NOTRANSACTION does not accept assignment of an argument.

A system crash may generate many "block transaction number too large" errors. These errors can cause problems for BACKUP /INCREMENTAL and for transaction processing. Normally, the automatic increment of 1000 blocks that GT.M adds when a database is reopened averts these errors. If a problem still exists after the database is reopened, you can use a value in the DSE CHANGE /FILEHEADER /CURRENT_TN= command to quickly fix "block transaction number too large number" errors.

By default, INTEG reports a maximum of 10 block transaction errors (/TRANSACTION=10).

/R[EGION]

Specifies that the INTEG parameter identifies one or more regions rather than a database file.

INTEG /REGION does not require sole access to databases. Instead, it freezes updates to the database during the check. The region-name argument may specify more than one region of the current Global Directory in a list separated with commas. Any region name may include the DCL wildcard characters * and %. INTEG /REGION requires the logical name GTM$GBLDIR to specify a valid Global Directory. For more information on defining GTM$GBLDIR, refer to the "Global Directory Editor" chapter.

	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.

THe /REGION qualifier is incompatible with the /FILE and /TN_RESET qualifiers.

By default, INTEG operates /FILE.

/S[UBSCRIPT]=subscript

Specifies a global or a range of keys to INTEG. The global key may be enclosed in quotation marks (" "). Identify a range by separating two subscripts with a colon (:). /SUBSCRIPT cannot detect incorrectly marked busy errors.

Use /SUBSCRIPT only if you know the path to the keys in the subscript, and have reason to believe the path is not damaged. If the path is questionable or known to be damaged, use DSE to find the block(s) and INTEG /BLOCK.

The /SUBSCRIPT qualifier is incompatible with the /BLOCK and /TN_RESET qualifiers.

Use /FULL to have INTEG report all global names in a region or list of regions.

Example:

MUPIP> INTEG /SUBSCRIPT="^a(100)":"^b(""c"")" /REGION $DEFAULT

This INTEGs all global variables greater than or equal to ^a (100) and less than or equal to ^b("c") in the default region(s).

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

/TN[_RESET]

Instructs an INTEG /FILE to reset the transaction number to one (1) in every database block currently holding valid data.

The /TN_RESET qualifier rewrites all blocks holding data. If the transaction overflow resets to zero (0) database operation is disrupted. The /TN_RESET qualifier is a protective mechanism that prevents the transaction overflow from resetting to 0.

Transaction numbers can go up to 4,294,967,295 (2**32-1). When the current transaction number exceeds four billion, INTEG displays a message warning that the transaction number is approaching the limit of the database. Because the warning appears when the transaction number reaches four billion, INTEG provides a margin of nearly 300 million updates before failure to perform the INTEG /TN_RESET causes the database to fail. This should give you adequate time to schedule an INTEG /TN_RESET. If you use MUPIP EXTRACT, delete the file and then MUPIP CREATE and MUPIP LOAD, the procedures have the same effect as a /TN_RESET.

	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 it should be considered in your operational procedures. The rate at which GT.M "uses up" transaction numbers is a function of operational procedures and real database updates.

The /TN_RESET qualifier is incompatible with the /FAST, /BLOCK, /REGION, and /SUBSCRIPT qualifiers.

By default, INTEG does not modify the block transaction numbers.

MUPIP> integ simple.dat
No errors detected by integ.
Type    Blocks  Records     %Used    Adjacent
Directory   2       11      6.835          NA
Index      10       10      1.367           1
Data       10       10      2.109           2
Free       78       NA         NA          NA
Total     100       31         NA           3

MUPIP> integ /region $DEFAULT
Integ of region $DEFAULT
No errors detected by integ.

Type      Blocks      Records     % Used      Adjacent
Directory   2           11          6.835       NA
Index      10           10          1.367        1
Data       10           10          2.109        2
Free       78           NA            NA        NA
Total     100           31            NA         3

MUPIP> integ /fast simple.dat
No errors detected by fast integ.

Type        Blocks      Records     % Used      Adjacent
Directory       2           11       6.835          NA
Index          10           10       1.367           0
Data           10           NA          NA          NA
Free           78           NA          NA          NA
Total         100           NA          NA           0

Block:Offset Level
%GTM-E-DBKEYORD,
2:1E 0 Keys not in order
Directory Path: 1:8, 2:1E
Keys from ^c to the end are suspect.
%GTM-I-DBTNTOOLG,
8:0 1 Block transaction number too large
Directory Path: 1:8, 2:13
Path: 8:0
Keys from ^A to the end are suspect.
%GTM-I-DBTN, Block TN is C
%GTM-I-DBTNTOOLG,
7:0 0 Block transaction number too large
Directory Path: 1:8, 2:13
Path: 8:8, 7:0
Keys from ^A to the end are suspect.
%GTM-I-DBTN, Block TN is 15
%GTM-I-DBMBTNSIZMX,
0:0 FF Map block transaction number too large
%GTM-W-DBLOCMBINC,
0:0 FF Local bitmap incorrect

MUPIP> integ /region $DEFAULT
Integ of region $DEFAULT
Block:Offset level
10:7        1        Keys out of order.
Directory Path: 1:7, 2:30
Path: 11:7, 10:7
Total error count from integ:
Type    Blocks      Records     % Used      Adjacent
Directory   2           11       6.835          NA
Index      10           10       1.367           1
Data       10           10       2.109           2
Free       78           NA          NA          NA
Total     100           31          NA           3
%GTM-E-INTEGERS, Database integrity errors
$

The JOURNAL command analyzes, extracts, reports, and recovers data using journal files. For a description of the JOURNAL command, refer to the "GT.M Journaling" chapter.

The LOAD command:

From an application perspective, loading data while an application is running may result in an inconsistent database.

The format of the LOAD command is:

The optional qualifiers are:

LOAD takes its input from the file defined by the file-specification

LOAD FORMAT=GO, =BINARY, or =ZWR may take its input from an RMS file on any device that supports such files, including magnetic tapes. However, the non-GT.M utility that produces GOQ format files only produces non-RMS magnetic tape files. When using an input file on a magnetic tape, use DCL to MOUNT the tape, and ensure the block size for the tape corresponds to the size that was used to make the tape.

For information on loading with an M "percent utility," refer to the %GI section of the "M Utility Routines" chapter in the GT.M Programmer's Guide. LOAD is typically faster, but the %GI utility can be customized.

<CTRL-C> produces a status message from LOAD. <CTRL-Y> 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 .

/FO[RMAT]=GO | B[INARY] | ZWR | GOQ

Specifies the format of the input file. The format must match the actual format of the input file for LOAD to operate.

The format codes are:

By default, LOAD uses FORMAT=ZWR, and starts at the beginning of the input file.

/FORMAT=GO stores the data in record pairs. Each global node produces one record for the key and one for the data. For /FORMAT=GO input, the value is usually an odd number.

/FORMAT=BINARY only applies to Greystone Database Structure (GDS) files. A BINARY format file loads significantly faster than a GO or ZWR format file. /FORMAT=BINARY stores the data in a proprietary format. /FORMAT=BINARY has one header record, therefore LOAD /FORMAT=BINARY starts active work with record number two (2). Since /FORMAT=BINARY requires important information from the header, this type of load requires an intact file header regardless of the /BEGIN value.

For /FORMAT = ZWR input, each record contains a complete set of reference and data information. The beginning values are not restricted, except to allow two records for the header.

/FORMAT=GO and /FORMAT=ZWR have two header records, therefore LOAD /FORMAT=GO and /FORMAT=ZWR start active work with record number three (3).

/FORMAT=GOQ loads files prepared by certain M implementations, and is significantly faster than a GO format file. Use the GOQ format as a conversion aid. /FORMAT=GOQ stores the data in fixed length 2048 byte blocks which contain a variable number of keys and data. /FORMAT=GOQ has one or more header records depending on the number of globals in the tape.

/BE[GIN]=integer

Specifies the record number of the input file with which LOAD should begin. Directing LOAD to begin at a point other than the beginning of a valid key causes an error.

Each format has some number of header records to consider when choosing a /BEGIN point. For more information, refer to the section on /FORMAT.

/E[ND]=integer

Specifies the record number of the input file at which LOAD should stop. /END=integer must be greater than the /BEGIN=integer for LOAD to operate. LOAD terminates after processing the record of the number specified by /END or reaching the end of the input file.

The value of /FORMAT=GO input should normally be an even number. By default, LOAD continues to the end of the input file.

/FI[LL_FACTOR]=integer

Specifies the quantity of data stored in a database block. Updates to the block fill the remaining available space. Blocks that receive subsequent updates and avoid block splits operate more efficiently.

If you have database performance issues or a high rate of database updates, you should examine the defined FILL_FACTORs. Unless the application only uses uniform records, which is not typical for most applications, FILL_FACTORs do not work precisely.

The FILL_FACTOR for data that is relatively static, or grows by the addition of new nodes that collate before or after pre-existing nodes, should be 100 percent. The FILL_FACTOR for data that is growing by additions to existing nodes may be chosen to leave room in the typical node for the forecast growth for some period of time. Generally, this is the time between the LOAD and first REORG, or between two REORGs. This is also true for additions of nodes that are internal to the existing collating sequence.

For example, if a global is expected to grow by five percent each month (from relatively uniformly distributed updates), and REORGs are scheduled once every quarter, the FILL_FACTOR for both the original LOAD and subsequent REORGs might be 20 percent ((3 months + 1 month "safety" margin) * five percent per month).

By default, LOAD uses /FILL_FACTOR=100 for maximum data density. If you are unsure about your data, this is a reasonable value.

MUPIP REORG is a tool used to improve performance by defragmenting and compacting database files. 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. If you use REORG concurrently with normal database access and you notice an impact on the performance of normal operation, you can lower the priority of the process performing the REORG.

Note that while REORG optimizes the GDS structure of database files, it does not handle native file system file fragmentation. In our experience, fragmentation at the native file system level is more likely than fragmentation at the GDS structure level. Always create files with appropriate allocations and extensions, on disks with large amounts of contiguous free space. Use native utilities and, depending on your procedures, MUPIP utilities to eliminate file fragmentation when database files have been extended more than a dozen times.

MUPIP REORG does not change the logical contents of the database, and can run on either the primary or secondary of a logical dual site application. In such cases, resuming REORGs in process should be part of the batch restart. For more information about running REORG on a dual site application, see Chapter 7: “Database Replication”.

The format of the REORG command is:

REO[RG] [/qualifier...] specification

The optional qualifiers are:

Entering <CTRL-C> twice in quick succession terminates REORG. A REORG terminated abnormally by operator action or error is incomplete but does not adversely affect the database structure.

/E[XCLUDE]=global-name-list

Restricts REORG from swapping blocks used by the specified globals. For example, a single MUPIP command might organize a subset of the globals in a database or region. If a second MUPIP REORG command were to SELECT the remaining globals, it would tend to disrupt the results of the first REORG by de-optimizing the previously organized blocks because no information is passed from the previous MUPIP REORG command. The EXCLUDE qualifier allows users to list the name of the previously REORGed globals, so that the MUPIP REORG bypasses the GDS blocks containing these globals.

If you enter the REORG /EXCLUDE=global-name-list command and the specified globals do not exist, REORG issues a message to the screen and continues to process any specified globals that exist. If REORG is unable to process any globals, it terminates with an error.

Arguments for this qualifier may be an individual global name, a range of global names, or a list of names and prefixes followed by the wildcard symbol. Enclose wildcards in double-quotes ("") to prevent inappropriate expansion by the shell. The caret symbol (^) in the specification of the global is optional.

The global name can be:

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 and fourth case, REORG excludes A, B, and C. In the last case, REORG excludes all globals prefixed with TMP.

By default, REORG does not EXCLUDE any globals.

In case any global appears in the argument lists of both /SELECT and /EXCLUDE, REORG terminates with an error.

/F[ILL_FACTOR]=percent-qualifier

Specifies how full you want each database block to be. This is a target number. Individual blocks may be more or less full than the fill factor.

If you have database performance issues or a high rate of database updates, you should examine the defined FILL_FACTORs. Unless the application uses entirely uniform records, which is not typical for most applications, FILL_FACTORs do not work precisely.

The FILL_FACTOR for data that is relatively static, or grows by the addition of new nodes that collate before or after pre-existing nodes, should be 100 percent. The FILL_FACTOR for data that is growing by additions to existing nodes may be chosen to leave room in the typical node for the forecast growth for some period of time. Generally, this is the time between the LOAD and first REORG, or between two REORGs. This is also true for additions of nodes that are internal to the existing collating sequence.

For example, if a global is expected to grow by five percent 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 20 percent ((3 months + 1 month "safety" margin) * five percent per month).

The arguments for the FILL_FACTOR qualifier must be integers from 30 to 100. These integers represent the percentage of the data block that REORG can fill. By default, the FILL_FACTOR value is 100 for maximum data density. For that case, REORG never performs a block split.

/I[NDEX_FILL_FACTOR]=percent-qualifier

Directs REORG to leave free space within index blocks for future updates. Arguments to this qualifier must be integers from 30 to 100 that represent the percentage of the index block that REORG can fill. REORG uses this number to decide whether to place more information in an index block, or create space by moving data to another block.

Under certain conditions, especially with large database block sizes, it may be possible to achieve faster throughput by using a smaller fill factor for index blocks than for data blocks. By default the INDEX_FILL_FACTOR is the value of FILL_FACTOR regardless of whether that value is explicitly specified or implicitly obtained by default.

/R[ESUME]

If you interrupt REORG, the RESUME qualifier allows you to restart the REORG operation from the point where the operation stopped. REORG stores the last key value in the database file header. If you enter the RESUME qualifier, the program retrieves the last key value, from the database file header, and restarts operations from that key.

/S[ELECT]=global-name-list

Restricts REORG operation to a subset of specified globals. By default, REORG operates on all globals in all database files identified by the current Global Directory for the process executing the MUPIP command. One of the functions performed by REORG is to logically order the globals on which it operates within the file. Unless the EXCLUDE qualifier is properly used, repeating the command with different selections in the same file wastes work and leaves only the last selection well organized.

If you enter the REORG /SELECT=global-name-list command and the specified globals do not exist, REORG issues a message to the screen and continues to process any specified globals that exist. If REORG is unable to process any globals, it terminates with an error.

Arguments for this qualifier may be an individual global name, a range of global names, or a list of names and prefixes followed by the wildcard symbol. The caret symbol (^) in the specification of the global is optional.

The global name can be:

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 and fourth case, REORG excludes A, B, and C. In the last case, REORG excludes all globals prefixed with TMP.

By default, REORG selects all globals.

The REPLICATE command controls the logical dual-site operation of GT.M. For a description of the REPLICATE command, see Chapter 7: “Database Replication”. chapter.

RESTORE integrates one or more BACKUP /INCREMENTAL files into a corresponding database. The transaction number in the first incremental backup must be one more than the current transaction number of the database. Otherwise, MUPIP RESTORE will terminate with an error and refuse to perform the restore.

The format of the RESTORE command is:

RE[STORE] [/qualifier] file-spec file-list

The file-specification identifies the name of the database file that RESTORE uses as a starting point. The transaction number in the database must match the starting transaction number of each successive input to the RESTORE. If the BACKUP /INCREMENTAL was created using /TRANSACTION=1, create a new database with MUPIP CREATE and do not access it, except the standalone MUPIP commands INTEG /FILE, EXTEND, and SET before initiating the RESTORE.

The file-list specifies one or more files produced by BACKUP /INCREMENTAL to RESTORE into the database. The file-specification are separated by commas (,) and must be in sequential order, from the oldest transaction number to the most recent transaction number. RESTORE may take its input from an RMS , including magnetic tape devices. When using an input file on a magnetic tape, use DCL to MOUNT specifying the same /BLOCKSIZE= as the one used to make the tape.

/[NO]E[XTEND]

Specifies whether RESTORE should extend the database file automatically if it is smaller than the size required to load the data. M activity between backups may automatically extend a database file. Therefore, the database file specified as the starting point for a RESTORE may require an extension before the RESTORE. If the database needs an extension and the command specifies /NOEXTEND, MUPIP displays a message. The message provides the sizes of the input and output database files and the number of blocks by which to extend the database. If the RESTORE specifies more than one incremental backup with a file list, the database file may require more than one extension.

By default, RESTORE automatically extends the database file.

When database access has not been properly terminated, RUNDOWN properly closes currently inactive databases 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. In 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.

MUPIP RUNDOWN reports "RMS-%-FLK-file locked by another user" errors when it cannot get exclusive access.

The only errors considered terminal (i.e., cannot be trapped by the application program are %GTM-F- errors, and a few severe OpenVMS errors such as ACCVIO.

The format of the RUNDOWN command is:

RU[NDOWN] [/FILE file-specification |/REGION region-list]

The file-specification or region-list identifies the target of the RUNDOWN. If RUNDOWN has no parameter, it flushes the memory associated with all database files opened by the corresonding version of GT.M that currently have associated memory and no active users.

The RUNDOWN command must include one of the following qualifiers:

MUPIP RUNDOWN /FILE or /REGION clears certain fields in a file that is already closed. This facilitates recovery from a system crash or other operational anomaly.

Use RUNDOWN after a system crash or after the last process accessing a database terminates abnormally. RUNDOWN ensures that open databases are properly closed and ready for subsequent use. RUNDOWN has no effect on any database that is actively being accessed at the time the RUNDOWN is issued.

To ensure database integrity, all system shutdown algorithms should include scripts that stop at GT.M processes and perform RUNDOWN on all database files.

/F[ILE]

Specifies that the argument is a file-specification for a single database file. The /FILE qualifier is incompatible with the REGION qualifier. If the rundown parameter consists of a list of files, the command only operates on the first item in the list.

/R[EGION]

Specifies that the argument contains one or more region-names that identify database files mapped by the current Global Directory. Region-names may include the DCL wildcards % and *. The /REGION qualifier is incompatible with the /FILE qualifier.

SET modifies certain database characteristics. SET operates on either regions or files.

	In regions that have journaling enabled and on, you can switch journal files without either requiring standalone access or freezing updates.

Example:

MUPIP SET /REGION * /JOURNAL=(ON,NOBEFORE)

The format of the SET command is:

SE[T] [/qualifier,...] /FILE file-specification | /REGION region-name

The file-specification (or region-list) identifies the target of the SET.

Region-names may be lists and may include the DCL wildcards % and *.

The SET command must include one of the following qualifiers which determine whether the argument to the SET is a file-specification or a region-list

/F[ILE]

Specifies that the argument is a file-specification for a single database file. The /FILE qualifier is incompatible with the /REGION qualifier.

/R[EGION]

Specifies that the argument is a region-list which identifies database file(s) mapped by the current Global Directory. SET /REGION changes multiple files when the parameter contains a list and/or wildcards. The /REGION qualifier is incompatible with the /FILE qualifier.

The optional qualifiers which determine the action(s) for the SET are:

/A[CCESS_METHOD]=BG | MM

Specifies the access method for a GDS database file. This qualifier requires stand-alone database access. For information on ACCESS_METHOD, refer to the "Greystone Database Structure" chapter.

By default, ACCESS_METHOD is established by MUPIP CREATE from information entered in the Global Directory.

/E[XTENSION_COUNT]=integer

Specifies the number of GDS blocks by which an existing database file extends. A file or region name is required. This qualifier requires standalone access. The format of the EXTENSION_COUNT qualifier is:

MUPIP SET /E=INTEGER

/F[LUSH_TIME]=integer

Specifies the amount of time between deferred writes of stale cache buffers. This time is specified as an integer number of delta-time format. This qualifier requires standalone access. The format of the FLUSH_TIME qualifier is:

MUPIP SET /F=TIME

/G[LOBAL_BUFFERS]=integer

Specifies the number of cache buffers for a BG database. This qualifier requires standalone access. For information on determining good working sizes for GLOBAL_BUFFERS, refer to the "Global Directory Editor" chapter.

In general, increasing the number of global buffers improves performance by smoothing the peaks of I/O load on the system. However, increasing the number of global buffers also increases the memory requirements of the system, and a larger number of global buffers can increase the probability of the buffers getting swapped out. If global buffers are swapped out, any performance gain from increasing the number of global buffers will be more than offset by the performance impact of swapping global buffers. Most applications use from 1,000 to 4,000 global buffers for database regions that are heavily used. FIS does not recommend using fewer than 256 buffers except under special circumstances.

The minimum is 64 buffers and the maximum is 65536 buffers. By default, MUPIP CREATE establishes GLOBAL_BUFFERS using information entered in the Global Directory.

/L[OCK]_SPACE=integer

Specifies the number of pages allocated to the management of M locks associated with the database. For more information on LOCK_SPACE, refer to the "Global Directory Editor" chapter. A file or region name is required. This qualifier requires standalone access. The format of the LOCK_SPACE qualifier is:

MUPIP SET /L=integer

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

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

/NOJOURNAL specifies that the database does not allow journaling. And also it does not accept an argument assignment.

/JOURNAL specifies journaling is allowed. It takes one or more arguments in a journal-option-list. For a full description of the /JOURNAL qualifier and its keywords, refer the "GT.M Journaling" chapter.

/RES[ERVED_BYTES]=size

Specifies the size to be reserved in each database block. RESERVED_BYTES is generally used to reserve room for compatibility with other implementations of M or to observe communications protocol restrictions. RESERVED_BYTES may also be used as a user-managed fill factor.

The minimum RESERVED_BYTES is 0 bytes. The maximum RESERVED_BYTES is the block size minus the size of the block header which is 7 or 8 depending on your platform. Realistic determinations of this amount should leave room for at least one record of maximum size.

STOP terminates a GT.M image. The image executes an orderly rundown of all databases that are currently open, and then exits. A MUPIP STOP performs an OpenVMS FORCEX system service and therefore may also be used to stop non-GT.M images

The format of the STOP command is:

ST[OP] /N[AME]=process-name | /ID=process-id

At least one of the qualifiers must appear. If both qualifiers appear, they must refer to the same process or STOP rejects the command.

Use the DCL command SHOW SYSTEM to display a list of active process names and process identifiers (PIDs). PIDs appear as hexadecimal numbers on a SHOW SYSTEM display, which is how they are specified to MUPIP STOP.

To STOP a process belonging to its own account, a process requires no privileges. To STOP a process belonging to another account in the same group, a process requires GROUP privilege. To stop a process belonging to an account in a different group, a process requires WORLD privilege and must use /ID=.

/I[D]=process-id

STOP interprets the /ID qualifier as a hexadecimal number that corresponds to the form displayed by the DCL command SHOW SYSTEM.

/N[AME]=process-name

Specifies the name of the process to stop. The maximum length of the name is 15 characters. Use the /ID qualifier if the process belongs to an owner in a different group.

/UP[GRADE] /N[AME] = file-name

Upgrades a GT.M version 3.x database file to the GT.M version 4 format. Ensure that there is a backup copy of any file that is being upgraded, and that mupip integ with GT.M 3.x reports that the file is clean. Files must be upgraded one at a time. Pressing <CTRL-C> or experiencing a system crash while a file upgrade is in progress can leave the file damaged, and require that it be restored from the backup.