Introduction

This chapter describes common database management operations such as creating database files, modifying database characteristics, database backup and restore, routine integrity checks, extracting or loading data, and optimizing performance.

GT.M uses M Peripheral Interchange Program (MUPIP) for GT.M database management, database journaling, and logical multisite replication (LMS). This chapter summarizes the MUPIP commands pertaining to GT.M database management and serves as a foundation for more advanced GT.M functionality described for Journaling and LMS.

For MUPIP commands pertaining to database journaling, refer to Chapter 6: “GT.M Journaling.

For MUPIP commands pertaining to multisite database replication, refer to Chapter 7: “Database Replication.

[Note] Note

Two MUPIP operations - INTRPT and STOP - perform process management functions. All other MUPIP operations relate to the operation of the database.

The GT.M installation procedure places the MUPIP utility program in a directory specified by $gtm_dist.

Invoke MUPIP by executing the mupip program at the shell prompt. If this does not work, consult your system manager (MUPIP requires that the $gtm_dist point to the directory containing the MUPIP executable image).

$gtm_dist/mupip
MUPIP>

MUPIP asks for commands, with the MUPIP> prompt. Enter the EXIT command at the MUPIP> prompt to stop the utility. MUPIP performs one operation at a time, and automatically terminates after most operations.

When additional information appears on the command line after the mupip program name, MUPIP processes the additional information as its command, for example:

$gtm_dist/mupip stop 1158 

This starts MUPIP and stops the process with Process ID (PID) 1158.

Some MUPIP commands require information contained in the global directory. Therefore, a process must have access to a valid global directory before using any MUPIP commands other than EXIT, INTRPT, JOURNAL, RESTORE, STOP and the -file option of any command that has that option.

The environment variable gtmgbldir specifies the active global directory.

A gtmgbldir value of mumps.gld tells MUPIP to look for a global directory file mumps.gld in the current directory. For more information on the global directory, refer to Global Directory Editor.

[Important] Important

FIS recommends against running GT.M components as root. When run as root, GT.M components use the owner and group of the database file as the owner and group of newly created journal files, backup files, snapshot files, shared memory, and semaphores. In addition, they set the permissions on the resulting files, shared memory, and semaphores, as if running as the owner of the database file and as a member of the database file group.

Operations - Standalone and Concurrent Access

While most MUPIP operations can be performed when GT.M processes are actively accessing database files, some operations require stand-alone access. When using standalone access, no other process can access the database file(s). When using concurrent access, other processes can read or update the database file(s) while MUPIP accesses them. A few operations permit concurrent access to read database files, but not to update them. All MUPIP operations can be performed with stand-alone access - there is never a requirement for another process to be accessing database files when MUPIP operates on them.

Most MUPIP operations require write access to the database files with which they interact. The exceptions are INTRPT and STOP, which do not require database access, but may require other privileges; EXTRACT, which requires read access; and INTEG, which may require write access, depending on the circumstances it encounters and the qualifiers with which it is invoked. The following table displays some of the MUPIP operations and their database access requirements.

Operations

MUPIP command

Database Access Requirements

Backup database files

MUPIP BACKUP

Backup never requires standalone access and concurrent write access is controlled by -[NO]ONLINE.

Create and initialize database files

MUPIP CREATE

Standalone access

Converts a database file from one endian format to the other (BIG to LITTLE or LITTLE to BIG)

MUPIP ENDIANCVT

Standalone access

Recover database files (for example, after a system crash) and extract journal records

MUPIP JOURNAL

Standalone access

Restore databases from bytestream backup files

MUPIP RESTORE

Standalone access

Properly close database files when processes terminate abnormally.

MUPIP RUNDOWN

Standalone access

Modify database and/or journal file characteristics

MUPIP SET

Standalone access is required if the MUPIP SET command specifies -ACCESS_METHOD, -GLOBAL_BUFFERS, -MUTEX_SLOTS, -LOCK_SPACE or -NOJOURNAL, or if any of the -JOURNAL options ENABLE, DISABLE, or BUFFER_SIZE are specified.

Backup database files

MUPIP BACKUP

Concurrent access.

Grow the size of BG database files

MUPIP EXTEND

Concurrent access.

Export data from database files into sequential (flat) or binary files

MUPIP EXTRACT

Although MUPIP EXTRACT command works with concurrent access, it implicitly freezes the database to prevent updates. Therefore, from an application standpoint, you might plan for a standalone access during a MUPIP EXTRACT operation.

Prevent updates to database files

MUPIP FREEZE

Standalone access.

Check the integrity of GDS databases

MUPIP INTEG

Concurrent access. However, standalone access is required if MUPIP INTEG specifies -FILE.

Import data into databases

MUPIP LOAD

Although MUPIP LOAD works with concurrent access, you should always assess the significance of performing a MUPIP LOAD operation when an application is running because it may result in an inconsistent application state for the database.

Defragment database files to improve performance

MUPIP REORG

Concurrent access.

Send an asynchronous signal to a GT.M process

MUPIP INTRPT

Non-database access.

Stop GT.M processes

MUPIP STOP

Non-database access.

MUPIP

The general format of MUPIP commands is:

mupip command [-qualifier[...]] [object[,...]] [destination] 

MUPIP allows the abbreviation of commands and qualifiers. In each section describing a command or qualifier, the abbreviation is also shown (for example, B[ACKUP]). The abbreviated version of the command you can use on the command line is B. To avoid future compatibility problems and improve the readability, specify at least four characters when using MUPIP commands in scripts.

Although you can enter commands in both upper and lower case (the mupip program name itself must be in lower case on UNIX/Linux), the typographical convention used in this chapter is all small letters for commands. Another convention is in the presentation of command syntax. If the full format of the command is too long for a single line of print, the presentation wraps around into additional lines.

$ mupip backup -bytestream -transaction=1 accounts,history,tables,miscellaneous /var/production/backup/

When you enter a MUPIP command, one of its variable arguments is the region-list. region-list identify the target of the command and may include the UNIX wildcards "?" and "*". Region-lists containing UNIX wildcard characters must always be quoted, for example, "*" to prevent inappropriate expansion by the UNIX shell. Similarly, for file and directory names you might want to avoid non-graphic characters and most punctuations except underbars (_), not because of GT.M conventions but because of inappropriate expansion by UNIX shells.

MUPIP qualifier values are restricted only by the maximum size of the command input line, which is 4KB on some systems and upto 64KB on others.