HOWTO: GT.M Production Instance on OpenVMS/AlphaPart 3: Defining the Global Directory and Creating the Data FileIn this installment, we will use the GT.M Global Directory Editor (GDE) and the MUMPS Peripheral Interchange Program (MUPIP) to define the global directory and database file for the instance.
For this instance, you will need to be logged into the <instance-user> account created in the prior installment. This is crucial.
Historical NoteThe MUPIP program's name has very deep roots. A Peripheral Interchange Program (PIP) was first used in the Digital Equipment Corporation PDP-6 series of computers in the early 1960's, and later made it into TOPS-10 on the PDP-10, RSTS/E on the PDP-11, and eventually into Gary Kildall's CP/M operating system, which is largely credited as an early and important foundation of the personal computer revolution. How it got into GT.M is a bit of trivia with which I am as yet unacquainted, but perhaps someone here can shed a little light on the subject. - JPWSo, without further ado, here are the commands used to set up your global directory:
Code:
$ RUN GTM$DIST:GDE
GDE> CHANGE /SEGMENT $DEFAULT /FILE=<data-device>:[<instance-user>.g]MUMPS.DAT /ALLOC=200000 /BLOCK_SIZE=4096 /LOCK_SPACE=1000 /EXTENSION_COUNT=0
GDE> CHANGE /REGION $DEFAULT /RECORD_SIZE=4080 /KEY_SIZE=255
The above commands bear further explanation.
The first line is the DCL command which will launch the GT.M Global Directory Editor, and should be familiar to anyone who has a passing familiarity with OpenVMS and DCL.
The second line sets the characteristics of the $DEFAULT database segment. The /FILE switch tells GDE to use <data-device>:[<instance-user>.g]MUMPS.DAT to store the data for the segment. The /ALLOC and /BLOCK_SIZE switches instruct GDE to allocate 200,000 blocks of 4,096 bytes each to the segment. The /LOCK_SPACE instructs GDE to allocate 1,000 pages for locking, which can prevent deadlocks under heavy load. The /EXTENSION_COUNT=0 switch instructs GT.M to disable its ability to automatically expand the database when storage grows short. Although you can set EXTENSION_COUNT to a rather arbitrary number of blocks, I do not recommend this practice, as the consequences of filling up your data drive at the OpenVMS level can be more catastrophic than filling up your database file, which will simply halt further writes to the database. A good solution is to employ a script to monitor database usage and notify you when a certain threshold is reached.
It is worth noting that you can calculate your database size by multiplying /BLOCK_SIZE by /ALLOC. In this case, the database will be slightly over 781MB (200,000 blocks * 4,096 bytes per block).
Next, we will set up journaling using the MUPIP program.
Journaling and MUPIPThe following commands will enable journaling to <journal-device>:[<instance-user>.j]<instance-user>.MJL:
Code:
$ RUN GTM$DIST:MUPIP
MUPIP> CREATE
Database file for region $DEFAULT created.
$ RUN GTM$DIST:MUPIP
MUPIP> SET /REGION $DEFAULT /JOURNAL=(ENABLE,ON,BEFORE,FILENAME=<journal-device>:[<instance-user>.j]<instance-user>.MJL)
%GTM-I-JNLCREATE, Journal file <journal-device>:[<instance-user>.j]<instance-user>.MJL created for region $DEFAULT
with BEFORE_IMAGES
%GTM-I-JNLSTATE, Journaling state for region $DEFAULT is now ON
CREATE tells MUPIP to create the .DAT file as specified by the global directory.
The command containing SET /REGION tells MUPIP to enable journaling for region $DEFAULT. ENABLE tells MUPIP that the specified region is ready to be journaled. ON tells MUPIP to create a new journal file (as specified by FILENAME) and begin using the newly-created file to record future journal entries. BEFORE instructs GT.M's journaling system to archive data blocks prior to modifying them, and enables the use of the rollback recovery facility on the specified region.
Now that the database is being journaled, we need only to set the ownership and permissions on MUMPS.DAT and MUMPS.GLD to prevent unauthorized access. This procedure is detailed in the DCL example below:
Code:
$ SET FILE/OWNER=<instance-user> <data-device>:[<instance-user>.g]MUMPS.GLD
$ SET FILE/OWNER=<instance-user> <data-device>:[<instance-user>.g]MUMPS.DAT
$ SET SECURITY /PROTECTION=(S:RWED,O:RWE,G:RWE,W:"") <data-device>:[<instance-user>.g]MUMPS.GLD
$ SET SECURITY /PROTECTION=(S:RWED,O:RWE,G:RWE,W:"") <data-device>:[<instance-user>.g]MUMPS.DAT
The instance is now created with journaling and security protections in place. You can now install any local MUMPS applications' routines into <home-device>:[<instance-user>.r].
I am considering writing another installment covering the configuration of GT.M replication, and possibly the configuration of WorldVistA, depending on feedback received here. I hope you find this guide useful, and wish you all the best!