This document describes the utilities and programs that are supplied with the M21 system. Some of the programs described are those that run when the M21 system is started, whilst the utilities consist of those external shell scripts and programs that are used for tasks such as database verification and backup. Most of the utility programs are called by means of shell scripts, which are just a convenient front end to the program itself. The UNIX user's command interpreter is called a shell, and a shell script is a file that contains commands that are executed when the file name is entered as a command. A shell environment variable is like other programming language variables in that it is used to store information. The shell variable PATH is used by the shell to search directories for a command to be executed.
All programs located in the adbin subdirectory of where the M21 system was installed are considered administrative in nature. When an administrative user logs in, their UNIX profile should be set up to include the adbin directory in their PATH shell variable. All M users should have their profile set up to include the bin subdirectory of where the M21 system was installed in their PATH shell variable. Programs located in the prog subdirectory of where the M21 system was installed should not be directly executed, they should only be called by another program or shell script after validating various things. Therefore the prog subdirectory should not be in any user's PATH shell variable.
DATABASE BACKUP and RESTORE This program is used to backup or restore the M21 database. It can do FULL concurrent, INCREMENTAL and JOURNAL backup and restore. A database name must be supplied using the -d option. This program is normally called using shell scripts to perform a backup or restore operation.
DATABASE BACKUP This is a shell script front end to dbbkrs . It will take the default database name from the DBNAME shell environment variable and call dbbkrs with the correct parameters set to perform a backup. The type of backup must be supplied as a parameter.
DATABASE INITIALIZATION This program is used to create database volumes, before image log files, and journal files. It can also add volumes and journal files and expand before image log files, volumes and journal files.
dbinit can be used in immediate mode or batch mode. If batch mode is chosen then the commands can be either run in the foreground or background.
In immediate mode commands are executed as soon as they are entered. Commands can be abbreviated so long as enough characters are used to make them unique. The following commands are supported in immediate mode:
| Command | Description |
|---|---|
| add | Add a second journal file or a new Volume to an existing database |
| create | Create a new database |
| delete | Delete the last volume if empty |
| expand | Expand an existing BIL, Journal or Volume |
| initialise | Initialize an existing or missing BIL, Journal or Volume |
| merge | Merge volumes or journal file added off-line to an existing database |
| move | Move alternate file |
| quit | Quit |
In batch mode commands are remembered and execution is postponed until batch is chosen from the options. Batch mode is convenient for running commands without user interaction and to regain the terminal if the run in background option is chosen. The following commands are supported in batch mode:
| Command | Description |
|---|---|
| add | Add a new Volume to a database |
| batch | Run batched commands in background |
| create | Create a new database - only valid if the first command. After invocation run batch or quit |
| expand | Expand an existing Volume - the same volume cannot be expanded more than once |
| quit | Quit |
After choosing which command to run, it is necessary to enter the path of the directory where the database exists or where you want it to be created and the name of the database, which can be from 2 to 8 characters in length. If creating a database it will then be necessary to assign a database M system name. This name must be three upper case characters and is the name by which this database can be referred to when being accessed by M21 or DDP networking and is the second part of the reference returned by the $ZUCI function.
The database volume, BIL and journal files can be stored in the directory specified, or it is possible to store them anywhere else in the file system and store just a pointer in the directory specified. In order to achieve this, answer yes to the appropriate questions for ALTERNATE DATABASE FILE, BIL or JOURNAL. This capability allows the support of the M database on a raw file system.
It is then necessary to specify the size of the files to be created and initialised. The database volume files, BIL files and journal files can be between 500 kilobytes and 2 gigabytes in size. The block size for use in the M database volume can also be specified to be 4, 5, 6, 7 or 8 kilobytes. Volume, BIL and journal files that are created smaller than 2 gigabytes in size can be expanded at a later date using this utility.
DATABASE RESTORE This is a shell script front end to dbbkrs . It will take the default database name from the DBNAME shell environment variable and call dbbkrs with the correct parameters set to perform a restore. The type of restore must be supplied as a parameter.
DATABASE TAPE TEST This is a shell script front end to dbbkrs . It will take the default database name from the DBNAME shell environment variable and call dbbkrs with the correct parameters set to test reading a backup tape as if it was doing a restore. The type of restore must be supplied as a parameter.
DATABASE UCI UTILITY This program is used to add, change and delete UCIs. A database name must be supplied using the -d option.
DATABASE VERIFICATION This program is used to check database integrity. It will check for pointer problems in M(UMPS) globals and routines and look for orphan blocks. It can be run for a single UCI or for the whole database. A database name must be supplied using the -d option.
M(UMPS) SYTEM ENVIRONMENT This is a shell script front end to mpmse . It will take the default database name from the DBNAME shell environment variable and call mpmse in programmer mode invoking the M(UMPS) programmer shell utility.
M(UMPS) SYTEM ENVIRONMENT This is a shell script front end to mpmse . It will take the default database name from the DBNAME shell environment variable and call mpmse in application mode invoking the M(UMPS) programmer shell utility.
M21 INFORMATION UTILITY This is a shell script front end to mpinfo . It will take the default database name from the DBNAME shell environment variable and call mpinfo .
M21 INSTALL UTILITY This is a shell script front end to mpmse . It will take the default database name from the DBNAME shell environment variable and call mpmse with options -INSTALL and -iminstall.mumps . This will install the M(UMPS) utility routines into the MGR UCI in the M database.
M(UMPS) SYTEM ENVIRONMENT INITIAL PROGRAM LOAD UTILITY This is a shell script front end to mpmse . It will take the default database name from the DBNAME shell environment variable and call mpmse with the options -IPL and - MANAGER options. This will perform all of the system start up task when bring up the M21 system and should be run after m21up has completed.
M21 LOG FILE UTILITY This is a shell script front end to the UNIX tail and pg commands. It will take the default database name from the DBNAME shell environment variable and determine the current log file and then interactively display it.
M(UMPS) SYTEM ENVIRONMENT This is a shell script front end to mpmse . It will take the default database name from the DBNAME shell environment variable and call mpmse in programmer mode invoking the M(UMPS) programmer shell utility. If an option of -notie is specified then the M(UMPS) programmer shell is not invoked.
M21 SYSTEM ACTIVITY REPORT UTILITY This is a shell script front end to mpsar . It will take the default database name from the DBNAME shell environment variable and then call mpsar .
M21 STATUS UTILITY This is a shell script program used to get the current status of the M21 system.
M21 UCI UTILITY This is a shell script front end to dbuci . It will take the default database name from the DBNAME shell environment variable and then call dbuci .
M21 STARTUP UTILITY This is a shell script front end to mpctl . It will take the default database name from the DBNAME shell environment variable and then call mpctl with the correct parameters. After starting mpctl it calls m21look to watch the log file for the start up to be finished.
DATABASE VERIFICATION UTILITY This is a shell script front end to dbverify . It will take the default database name from the DBNAME shell environment variable and then call dbverify .
Used to enter the licence parameters for the M21 software. The information to enter will be supplied when a licence is purchased.
JOURNAL BACKUP FREQUENCY AUDIT This shell script is used to check the M21 log files to determine how often journal backups are being done. The program will give warnings if journal data is being overwritten and make recommendation for the backup frequency.
JOURNAL FILE DUMP This program is used to print the contents of the after image journal file. It is possible to select the starting and ending block number and type of data to dump by means of parameters. A database name must be supplied using the -d option.
BEFORE IMAGE LOGGING PROCESS This program is part of the running M21 system and carries out the task of logging the before image states to the BIL file. When a disk block is modified for the first time since a quiesce (quiet point) it will be written to the before image log file prior to modification. This program is started by mpctl at start up time. The loss of this process will cause M21 to shut down.
MASTER CONTROL PROCESS This program is part of the running M21 system and is the main program that starts all the other running programs that make up the M21 system. The loss of this process will have serious effects upon the running M21 system, and will include the time stopping from updating and no new background jobs being started. M21 will not shutdown normally if this process is not running.
DISK WRITER PROCESS This program is part of the running M21 system and is the only process that can write to the database volumes. Each volume will have at least 1, but can have as many as 3 mpdsk processes dependent on configuration parameters. When a disk buffer in shared memory is marked as modified then it will be written to the correct volume by the mpdsk process assigned to that volume. This program is started by mpctl at start up time. The loss of this process will cause M21 to shut down.
INFORMATION UTILITY This program is used to display information about an active M21 system. It can display things such as the status of disk buffers, jobs, general locks, etc. It can also clear ports and kill running M(UMPS) jobs. A database name must be supplied using the -d option.
JOURNAL WRITER PROCESS This program is part of the running M21 system and is the process that writes the after image journal log files. This program is started by mpctl at start up time. The loss of this process will cause M21 to shut down.
M(UMPS) SYTEM ENVIRONMENT This program is part of the running M21 system and is the M(UMPS) system and interpreter. Each user who logs onto the M21 system will be running an mpmse process as will each background job. This process is not normally called direct, but via shell scripts which supply the necessary parameters. A database name must be supplied using the -d option.
CROSS-SYSTEM REQUEST SERVER PROCESS This program is part of the running M21 system and is the process that is used to communicate with other M21 systems using TCP/IP networking. It is also used to communicate with other M(UMPS) systems using the DDP protocol. This program is started by mpctl at start up time if the use of cross-system networking is configured. The loss of this process will cause networking between M21 systems to stop working.
M(UMPS) SYSTEM ACTIVITY REPORT UTILITY This program is used to display the number of logical reads and writes, physical reads and writes, lock operations, commands and functions, etc. Normally the data is retrieved from the shared memory, but it can also be obtained from a file. A database name must be supplied using the -d option.
SOCKET PASSING SERVER PROCESS This program is part of the running M21 system and is the process that is used to pass open sockets between M(UMPS) processes by means of the ATTACH and DETACH parameters to the USE command for a socket device. This program is started by mpctl at start up time. The loss of this process will cause the passing of sockets between M processes to stop working.
SYSTEM WATCH DOG PROCESS This program is part of the running M21 system and is the process, which wakes up at set intervals and does checks on the status of the M21 system. It also updates the ports information within the M(UMPS) environment from the database.ports configuration file. This program is started by mpctl at start up time. The loss of this process will cause M21 to shut down.
KILL A JOB This program is called by mpctl when an error trying to kill an M job occurs. It will try to release any resources that the job may have left locked.
RUN DATABASE BACKUP This is a shell script front end to dbbkrs . It is put into the UNIX crontab to run the database backup in unattended mode.