GT.M Acculturation Live CD: Difference between revisions

From VistApedia
Jump to navigationJump to search
← Older editNewer edit →
Ivaldes1 (talk | contribs)
452 edits
No edit summary
Ivaldes1 (talk | contribs)
452 edits
No edit summary
Line 3: Line 3:
It has been used as the basis for several of the GT.M workshops at [[VistA Community Meeting]]s.
It has been used as the basis for several of the GT.M workshops at [[VistA Community Meeting]]s.


It is available for download from the {{WVSFPAGE}} and the document re-created here:
It is available for download from the {{WVSFPAGE}}.
 
<html>
</head><body dir="ltr" lang="en-US">
<h1 align="center"><img src="index_files/FNFIS_logo.jpg" name="graphics7" align="right" border="0" height="77" width="156"><img src="index_files/powered_by_gtm_wo.jpg" name="graphics9" align="left" border="0" height="58" width="95"><font face="Nimbus Sans L, sans-serif"><font size="5">Welcome
to the GT.M Acculturation Live CD!</font></font></h1>
<p><br><br>
</p>
<p><font color="#ff00ff"><font face="Nimbus Roman No9 L, serif"><font size="3">Although
you can read this document in your current environment, you will need
to boot this CD in order to get the most benefit from it. When you
boot it, please either:</font></font></font></p>
<ul>
<li><p><font color="#ff00ff"><font face="Nimbus Roman No9 L, serif"><font size="3">connect
a 512MB USB flash drive (also known as a jump drive or thumb drive),
or</font></font></font></p>
</li><li><p><font color="#ff00ff"><font face="Nimbus Roman No9 L, serif"><font size="3">ensure
that the hard disk has a partition with at least 300MB in size with
either</font></font></font></p>
<ul>
<li><p><font color="#ff00ff"><font face="Nimbus Roman No9 L, serif"><font size="3">a
FAT file system,</font></font></font></p>
 
</li><li><p><font color="#ff00ff"><font face="Nimbus Roman No9 L, serif"><font size="3">a
Linux file system, or</font></font></font></p>
</li><li><p><font color="#ff00ff"><font face="Nimbus Roman No9 L, serif"><font size="3">a
partition which can be over-written with a Linux file system &#8211;
tools to partition the disk drive and create a Linux file system
are included on the CD).</font></font></font></p>
</li></ul>
</li></ul>
<p><img src="index_files/penguin12.gif" name="graphics8" align="right" border="0" height="76" width="90"><font face="Nimbus Roman No9 L, serif"><font size="3"><u><b>Note:
there is no &#8220;Start&#8221; button. Clicking on the screen
background with the right mouse button pops up the menu.</b></u></font></font></p>
 
<h1><font face="Nimbus Sans L, sans-serif"><font size="5">Table of
Contents</font></font></h1>
<ul>
<li><p><a href="#2.Overview%7Coutline"><b><u><font face="Nimbus Roman No9 L, serif">Overview</font></u></b></a></p>
<ul>
<li><p><a href="#GT.M%7Coutline"><font face="Nimbus Roman No9 L, serif">GT.M</font></a></p>
</li><li><p><a href="#Acculturation%20Workshop%7Coutline"><font face="Nimbus Roman No9 L, serif">Acculturation
Workshop</font></a></p>
</li><li><p><a href="#VistA%7Coutline"><font face="Nimbus Roman No9 L, serif">VistA</font></a></p>
 
</li><li><p><a href="#Linux%20Live%20CD%7Coutline"><font face="Nimbus Roman No9 L, serif">Linux
Live CD</font></a></p>
</li><li><p><a href="#Hardware%20Requirements%7Coutline"><font face="Nimbus Roman No9 L, serif">Hardware
Requirements</font></a></p>
</li><li><p><a href="#Conventions%7Coutline"><font face="Nimbus Roman No9 L, serif">Conventions</font></a></p>
</li><li><p><a href="#Legal%20Stuff%7Coutline"><font face="Nimbus Roman No9 L, serif">Legal
Stuff</font></a></p>
</li></ul>
</li><li><p><a href="#3.Getting%20Started%7Coutline"><b><u><font face="Nimbus Roman No9 L, serif">Getting
Started</font></u></b></a></p>
 
<ul>
<li><p><a href="#FAT%20File%20System%7Coutline"><font face="Nimbus Roman No9 L, serif">FAT
File System</font></a></p>
<ul>
<li><p><a href="#Mounting%20a%20read/write%20partition%7Coutline"><font face="Nimbus Roman No9 L, serif">Mounting
a Read/Write Partition</font></a></p>
<ul>
<li><p><a href="#Graphical%20Mounting%20Tool%7Coutline"><font face="Nimbus Roman No9 L, serif">Graphical
Mounting Tool</font></a></p>
</li><li><p><a href="#Mounting%20With%20Shell%20Commands%7Coutline"><font face="Nimbus Roman No9 L, serif">Mounting
with Shell Commands</font></a></p>
 
</li></ul>
</li><li><p><a href="#First%20usage%7Coutline"><font face="Nimbus Roman No9 L, serif">First
Usage</font></a></p>
</li><li><p><a href="#First%20and%20subsequent%20usage%7Coutline"><font face="Nimbus Roman No9 L, serif">First
and Subsequent Usage</font></a></p>
</li></ul>
</li><li><p><a href="#Linux%20file%20system%7Coutline"><font face="Nimbus Roman No9 L, serif">Linux
File System</font></a></p>
<ul>
<li><p><a href="#First%20usage%7Coutline"><font face="Nimbus Roman No9 L, serif">First
Usage</font></a></p>
 
</li><li><p><a href="#Subsequent%20usage%7Coutline"><font face="Nimbus Roman No9 L, serif">Subsequent
Usage</font></a></p>
</li></ul>
</li></ul>
</li><li><p><a href="#4.Start+GT.M+%3F+ready+to+run+VistA%7Coutline"><b><u><font face="Nimbus Roman No9 L, serif">Start
GT.M &#8211; Ready to Run VistA</font></u></b></a></p>
</li><li><p><a href="#5.Excellent%20Documentation%7Coutline"><b><font face="Nimbus Roman No9 L, serif">Excellent
Documentation</font></b></a></p>
<ul>
 
<li><p><a href="#Manuals%7Coutline"><font face="Nimbus Roman No9 L, serif">Manuals</font></a></p>
</li><li><p><a href="#Technical%20Bulletins%7Coutline"><font face="Nimbus Roman No9 L, serif">Technical
Bulletins</font></a></p>
</li></ul>
</li><li><p><a href="#6.GT.M+%3F+a+MUMPS+unlike+any+other%7Coutline"><b><font face="Nimbus Roman No9 L, serif">GT.M
&#8211; a MUMPS Unlike Any Other</font></b></a></p>
<ul>
<li><p><a href="#GT.M%20is%20just%20like%20any%20other%20M%20implementation%7Coutline"><font face="Nimbus Roman No9 L, serif">GT.M
is Just Like Any Other M Implementation</font></a></p>
 
</li><li><p><a href="#Routines%20are%20in%20the%20file%20system%7Coutline"><font face="Nimbus Roman No9 L, serif">Routines
are in the File System</font></a></p>
<ul>
<li><p><a href="#Exercise%7Coutline"><font face="Nimbus Roman No9 L, serif">Exercise
&#8211; Compiling &amp; Linking</font></a></p>
</li></ul>
</li><li><p><a href="#Global%20directories%20point%20to%20global%20variables%7Coutline"><font face="Nimbus Roman No9 L, serif">Global
Directories Point to Global Variables</font></a></p>
 
</li><li><p><a href="#$ZROUTINES%20and%20$ZGBLDIR%20vs.%20UCI%20&amp;%20Volume%20set%7Coutline"><font face="Nimbus Roman No9 L, serif">$ZROUTINES
and $ZGBLDIR vs. UCI &amp; Volume set</font></a></p>
</li><li><p><a href="#Example:%20Development%20environments%7Coutline"><font face="Nimbus Roman No9 L, serif">Example:
Development Environments</font></a></p>
</li><li><p><a href="#Example:%20Application%20Service%20Provider%7Coutline"><font face="Nimbus Roman No9 L, serif">Example:
Application Service Provider</font></a></p>
<ul>
<li><p><a href="#Exercise+%3F+GDE+commands+for+ASP%7Coutline"><font face="Nimbus Roman No9 L, serif">Exercise
&#8211; GDE Commands for ASP</font></a></p>
 
</li></ul>
</li><li><p><a href="#GT.M%20leverages%20the%20operating%20system%7Coutline"><font face="Nimbus Roman No9 L, serif">GT.M
Leverages the Operating System</font></a></p>
</li><li><p><a href="#Security%7Coutline"><font face="Nimbus Roman No9 L, serif">Security</font></a></p>
<ul>
<li><p><a href="#Security%7Coutline"><font face="Nimbus Roman No9 L, serif">Exercise
&#8211; Security</font></a></p>
</li></ul>
 
</li><li><p><a href="#No%20special%20startup%20or%20shutdown%7Coutline"><font face="Nimbus Roman No9 L, serif">No
Special Startup or Shutdown</font></a></p>
</li><li><p><a href="#Journaling+%3F+the+key+to+database+integrity%7Coutline"><font face="Nimbus Roman No9 L, serif">Journaling
&#8211; the Key to Database Integrity</font></a></p>
</li><li><p><a href="#Exercise%20-%20journaling%7Coutline"><font face="Nimbus Roman No9 L, serif">Exercise
&#8211; Journaling</font></a></p>
</li><li><p><a href="#Database%20replication%7Coutline"><font face="Nimbus Roman No9 L, serif">Database
Replication</font></a></p>
</li><li><p><a href="#Replication%20and%20Backlogs%7Coutline"><font face="Nimbus Roman No9 L, serif">Replication
and Backlogs</font></a></p>
 
<ul>
<li><p><a href="#Exercise+%3F+replication+backlogs%7Coutline"><font face="Nimbus Roman No9 L, serif">Exercise
&#8211; Replication Backlogs</font></a></p>
</li></ul>
</li><li><p><a href="#Backup%7Coutline"><font face="Nimbus Roman No9 L, serif">Backup</font></a></p>
<ul>
<li><p><a href="#Exercise%20-%20backup%7Coutline"><font face="Nimbus Roman No9 L, serif">Exercise
&#8211; Backup</font></a></p>
 
</li></ul>
</li><li><p><a href="#Potential%20surprises%7Coutline"><font face="Nimbus Roman No9 L, serif">Potential
Surprises</font></a></p>
</li><li><p><a href="#Exploit%20integration%20with%20underlying%20operating%20system%7Coutline"><font face="Nimbus Roman No9 L, serif">Exploit
Integration with Underlying Operating System</font></a></p>
</li></ul>
</li><li><p><a href="#7.In%20conclusion%7Coutline"><b><font face="Nimbus Roman No9 L, serif">In
Conclusion</font></b></a></p>
</li></ul>
<h1><a name="2.Overview|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="5">Overview</font></font></h1>
<h2><a name="GT.M|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>GT.M</i></font></font></h2>
 
<p><font face="Nimbus Roman No9 L, serif"><a href="http://www.sanchez-gtm.com/">GT.M&#8482;</a>
is an implementation of the ISO standard scripting &amp; application
development language M, commonly known as MUMPS from <a href="http://fidelityinfoservices.com/">Fidelity
Information Services, Inc.</a> As the platform for the <a href="http://www.fidelityinfoservices.com/fnfis/markets/midtierlgbanking/corebanking/profile">Fidelity
Profile</a> application, GT.M is the most widely used M
implementation in banking and finance, including the <a href="http://www.sanchez-gtm.com/news/news.htm">largest
real time core processing system that is live at any bank anywhere in
the world</a>. GT.M is increasingly used in healthcare, and is likely
the most widely used M on Linux. The implementation of GT.M on the
GNU/Linux operating system on industry standard x86 architecture
hardware is available under the GNU General Public License, and is
the M implementation used for the FOSS stack for VistA.</font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">GT.M is
architected with the following objectives:</font></font></p>
<ul>
 
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Without
compromise, the robustness, security and integrity of the
information entrusted to it.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Open
architecture, with easy, standards based access to the information
in the database.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Continuity
of business &#8211; GT.M has unique functionality for the deployment
of mission-critical applications that must be available 24 hours a
day, 365 days a year, with no down time even for planned events.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Throughput,
performance and scalability to meet the needs of the largest
institutions in the world.</font></font></p>
</li></ul>
<p><font face="Nimbus Roman No9 L, serif">Free support for GT.M is
provided by the community on <a href="http://sourceforge.net/forum/?group_id=11026">various
mailing lists and electronic forums</a>, and 24x365 support is
available from Fidelity on a commercial basis.</font></p>
 
<p><font face="Nimbus Roman No9 L, serif"><font size="3">GT.M provides:</font></font></p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">full ACID
(Atomic, Consistent, Isolated, Durable) transaction semantics,</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">throughput
that scales to the needs of enterprise wide applications, and</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">unique
functionality for creating logical dual site configurations for
mission critical applications that must always be available;
including during upgrades, and even upgrades involving changes to
the database schema.</font></font></p>
</li></ul>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">This CD
includes GT.M V5.0-000C.</font></font></p>
<h2><a name="Acculturation Workshop|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Acculturation
Workshop</i></font></font></h2>
 
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The GT.M
acculturation workshop is a hands-on GT.M &#8220;boot camp&#8221; for
M professionals who are not familiar with GT.M, as well as for those
interested in GT.M configuration, administration and operations. This
file is the script, or workbook, for the workshop, and consists of
the exercises below. The exercises are designed to be carried out by
booting the GT.M Acculturation live CD. To do so, you should be
reading this in a browser window on your PC desktop after boot-up. If
that is not the route that brought you to your perusal of this
document, then please boot the GT.M Acculturation live CD and
continue.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The workshop
is not a course in M programming &#8211; familiarity with another M
implementation (or with GT.M for those using these exercises to
refine their skills) is assumed. Familiarity with Linux<sup>®</sup>
(or at least UNIX<sup>®</sup>) is highly desirable, but not
absolutely required.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">As the
differences between GT.M and other M implementations are more in the
area of configuration and systems administration rather than M
language features, the former topics are the major thrust of the
workshop.</font></font></p>
<h2><a name="VistA|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>VistA</i></font></font></h2>
 
<p><font face="Nimbus Roman No9 L, serif">The <a href="http://www.va.gov/">US
Department of Veterans Affairs</a> is one of the largest integrated
healthcare networks in the world. Delivering legally mandated high
quality care to veterans of the US armed forces, it has repeatedly
been recognized not only for the quality, but also for the
cost-effectiveness, of the care that it provides.</font></p>
<p><font face="Nimbus Roman No9 L, serif">VistA is an HIS developed
and maintained by the VA, based on the systems software architecture
and implementation methodology developed by the US Public Health
Service jointly with the National Bureau of Standards. VistA is used
throughout the VA system, and variants are used by the US Department
of Defense, the Indian Health Service (an agency of the US Department
of Health and Human Services), as well as at numerous institutions
around the world. VistA has a proven track record of supporting a
large variety of settings and medical delivery systems. The software
is in the public domain and freely available. Many providers support
VistA on a commercial basis, and there is an <a href="http://lists.sourceforge.net/lists/listinfo/hardhats-members">active
online VistA community</a>.</font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">For all
healthcare organizations, VistA can provide a cost-effective
enterprise resource planning (ERP) system. It is written in the
ANSI/ISO standard programming language M (also known as MUMPS), With
origins in the field of healthcare informatics, M is the de facto
standard for healthcare software.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif">The GT.M Acculturation live
CD uses the US Department of Veterans Affairs' acclaimed VistA
healthcare information system as a sample GT.M application, and is
itself a repackaged VistA live CD that can be downloaded from the
<a href="http://sourceforge.net/projects/worldvista">WorldVistA
project at Source Forge</a>.</font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3"><u>No
knowledge of VistA is assumed or required for the Acculturation
Workshop.</u></font></font></p>
 
<h2><a name="Linux Live CD|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Linux
Live CD</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Linux is the
common name for the GNU/Linux operating system, consisting of the GNU
utilities and libraries on the Linux kernel, available across the
broadest range of hardware of any operating system. It is most widely
used on industry standard architecture x86 hardware (i.e., based on
popular CPUs from Intel, AMD and others), and is increasingly popular
around the world for applications that include embedded computing
(appliances); personal desktops; file, print &amp; web servers;
supercomputing; and to deploy mission critical software. Linux is the
operating system for the VistA FOSS stack.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Free support
for Linux is available on numerous mailing lists and electronic
forums. Commercial support is widely available from multiple vendors.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif">A <a href="http://en.wikipedia.org/wiki/Live_cd">live
CD</a> (or DVD &#8211; the terms are interchangeable as far as this
document is concerned) is a CD that boots a PC and runs the GNU/Linux
operating system &#8211; more commonly referred to as just Linux &#8211;
 
from the CD, no matter what operating system is installed on the hard
drive. Indeed, there need not even be a hard drive on the PC.</font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Content on the
CD is compressed, and uncompressed on the fly as needed. This means
that there is a lot more on the CD than its nominal capacity. Note
that booting and running an operating system off a CD will be slower
than running the same operating system off a hard drive because (a)
CD-ROM drives are typically slower than hard drives and (b) content
must be uncompressed each time it is read from the CD.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif">This GT.M Acculturation
live CD is based on the <a href="http://damnsmalllinux.org/">Damn
Small Linux (DSL)</a> distribution version 2.1b.</font></p>
<h2><a name="Hardware Requirements|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Hardware
Requirements</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">This CD will
boot on an industry standard x86 architecture PC that can boot from a
CD-ROM. 500MHz or better CPU and 128MB or more RAM are recommended.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">GT.M is a
database application development platform. Although a snapshot of a
database can be placed on a CD, it is not possible for an operational
database to reside on a read-only medium such as a CD. Ergo, the
exercises require read/write storage, which can be provided by one of
the following:</font></font></p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">A 512MB
USB flash drive (also referred to as a thumb drive or jump drive; a
USB 2.x drive and a USB 2.x port on the host PC will be much faster
than a USB 1.x drive and port). A USB hard drive would also work, as
would a memory card or stick (e.g., from a digital camera) mounted
in a suitable reader. Such a device will probably have a name such
as <b><font size="2"><font face="Nimbus Mono L, monospace">/dev/sda1</font></font></b>
 
or <b><font size="2"><font face="Nimbus Mono L, monospace">/dev/sdb1</font></font></b>.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">A
partition on an IDE or SCSI hard drive that contains a Linux file
system (e.g., ext3, reiserfs) or a FAT file system (Windows 95/98/ME
file system), but not an NTFS file system (Windows NT/2000/XP file
system). A partition on an IDE drive will probably have a name such
as <b><font size="2"><font face="Nimbus Mono L, monospace">/dev/hda2</font></font></b>
or <b><font size="2"><font face="Nimbus Mono L, monospace">/dev/hdb3</font></font></b>;
a partition on a SCSI drive will have a name such as <b><font size="2"><font face="Nimbus Mono L, monospace">/dev/sda1</font></font></b>
or <b><font size="2"><font face="Nimbus Mono L, monospace">/dev/sda2</font></font></b>
 
(i.e., similar to a USB drive). If a partition with a FAT or Linux
file system does not exist, and the contents of an existing
partition can be over-written, you can create such a file system in
an existing partition with this CD.</font></font></p>
</li></ul>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">A minimum of
350MB of available space is required. More (400MB) is strongly
recommended. For the purpose of the examples in this document, a
read/write partition with a FAT file system is assumed to reside at
<b><font size="2"><font face="Nimbus Mono L, monospace">/dev/sda1</font></font></b>
(which corresponds to the first partition of the first USB flash
drive found); a read/write partition with a Linux file system is
assumed to reside at <b><font size="2"><font face="Nimbus Mono L, monospace">/dev/hda2</font></font></b>
(which corresponds to the second partition of the first IDE hard
drive). Adjust your commands as needed for partitions in other
locations.</font></font></p>
<h2><a name="Conventions|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Conventions</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">In the
following, text in a <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">blue
bold monospace font</font></font></font></b> is intended to be typed
in at a GT.M prompt (including the main <b><font size="2"><font face="Nimbus Mono L, monospace">GTM&gt;</font></font></b>
 
prompt as well as utility programs such as <b><font size="2"><font face="Nimbus Mono L, monospace">GDE&gt;</font></font></b>).
Text in a <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">red
bold monospace font</font></font></font></b> is intended to be typed
in at a bash shell prompt (or otherwise provided as input to a bash
shell), or elsewhere in Linux but not to GT.M.</font></font></p>
<h2><a name="Legal Stuff|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Legal
Stuff</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif">GT.M is owned and
copyrighted by <a href="http://fidelityinfoservices.com/">Fidelity
National Information Services, Inc.</a>, and is available for the x86
GNU/Linux platform under the terms of the <a href="http://www.fsf.org/licensing/licenses/gpl.txt">GNU
General Public License (GPL)</a>. Source and binary can be downloaded
from the <a href="http://sourceforge.net/projects/sanchez-gtm">GT.M
project page at Source Forge</a>.</font></p>
 
<p><font face="Nimbus Roman No9 L, serif">VistA is in the public
domain through the <a href="http://en.wikipedia.org/wiki/Freedom_of_information_act">US
Freedom of Information Act</a>. Source and object code are available
on the CD. As noted above, no understanding of VistA itself is
required or assumed for the workshop.</font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The Linux
kernel, GNU utilities, XFCE, and all other software on the CD are
open source free software, available under their respective open
source licenses.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Copyrights and
trademarks of all content on the CD are hereby acknowledged as being
held by their owners.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">This document
itself is placed in the public domain by the author with no warranty
of any kind, explicit or implicit. Follow any instructions herein at
your own risk.</font></font></p>
<h1><a name="3.Getting Started|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="5">Getting
Started</font></font></h1>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">As discussed
above, a read/write partition is required for the database. Choose
one of the following, depending on your hardware configuration:</font></font></p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><a href="#FAT%20File%20System%7Coutline">FAT
file system</a>, (USB drive, or a partition on an IDE or SCSI drive
with a FAT file system), or</font></p>
 
</li><li><p><font face="Nimbus Roman No9 L, serif"><a href="#Linux%20file%20system%7Coutline">Linux
file system</a> (partition on an IDE or SCSI hard drive with a Linux
file system, or a partition that can be formatted with a Linux file
system)</font></p>
</li></ul>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">In either
case, first:</font></font></p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Start a
bash shell: right click on the screen background, choose <b><font size="2"><font face="Nimbus Sans L, sans-serif">Xshells</font></font></b>
and then your choice of background for the terminal window
(<b><font size="2"><font face="Nimbus Sans L, sans-serif">Transparent</font></font></b>,
<b><font size="2"><font face="Nimbus Sans L, sans-serif">Light</font></font></b>
 
or <b><font size="2"><font face="Nimbus Sans L, sans-serif">Dark</font></font></b>).
The initial directory for the shell is <b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl</font></font></b>.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">All
exercises will be carried out in <b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA</font></font></b>
and its subdirectories. Create a mount point <b><font size="2"><font face="Nimbus Mono L, monospace">myVistA</font></font></b>
in <b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl</font></font></b>,
the home directory of the default user, dsl: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">mkdir
-p myVistA</font></font></font></b></font></font></p>
 
</li></ul>
<h2><a name="FAT File System|outline"></a><a name="FAT File System|outline"></a><a name="FAT File System|outline"></a>
<font face="Nimbus Sans L, sans-serif"><font size="4"><i>FAT File
System</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The exercises
require a GT.M database in a Linux file system. Although a GT.M
database can reside in a FAT file system (at least for demonstration
purposes &#8211; databases on FAT file systems are neither
recommended nor supported for production use), the exercises require
functionality that is not available with a FAT file system. Ergo a
Linux file system is required for the GT.M Acculturation Workshop.
So, the FAT file system must first be mounted, and the Linux file
system within mounted separately (i.e., there are two mount
operations performed).</font></font></p>
<h2><a name="Mounting a read/write partition|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Mounting
a read/write partition</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif">When you are asked to mount
an existing file system with a read/write partition using the
<a href="#Graphical%20Mounting%20Tool%7Coutline">graphical mounting tool</a>,
or <a href="#Mounting%20With%20Shell%20Commands%7Coutline">with shell
commands</a> and then choose either <a href="#FAT%20File%20System%7Coutline">FAT
file system</a> or <a href="#Linux%20file%20system%7Coutline">Linux file
system</a>. depending on the file system on the device partition.</font></p>
 
<h3><a name="Graphical Mounting Tool|outline"></a><a name="Graphical Mounting Tool|outline"></a>
<font face="Nimbus Sans L, sans-serif"><font size="4">Graphical
Mounting Tool</font></font></h3>
<p><img src="index_files/dsl_automounter_umounted.jpg" name="graphics1" align="left" border="0" height="86" hspace="16" width="77"><img src="index_files/dsl_automounter_mounted.jpg" name="graphics2" align="right" border="0" height="85" hspace="12" width="76"><font face="Nimbus Roman No9 L, serif"><font size="3">In
the lower right corner is a graphical mounting tool. Click on the
button that says &#8220;fd0&#8221; till till it has the name of the
device you wish to mount, e.g., &#8220;sda1&#8221; for a USB flash
drive or &#8220;hda2&#8221; for a hard drive partition. Then click
the red button labelled &#8220;umounted&#8221; to mount it. On a
successful mount, the red button will turn green and say &#8220;mounted&#8221;.
The device will be mounted under <b><font size="2"><font face="Nimbus Mono L, monospace">/mnt</font></font></b>
 
(e.g., <b><font size="2"><font face="Nimbus Mono L, monospace">/dev/hda2</font></font></b>
will be mounted as <b><font face="Nimbus Mono L, monospace">/mnt/hda2</font></b>).</font></font></p>
<h3><a name="Mounting With Shell Commands|outline"></a><a name="Mounting With Shell Commands|outline"></a>
<font face="Nimbus Sans L, sans-serif"><font size="4">Mounting With
Shell Commands</font></font></h3>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">To mount a USB
flash drive which is at <b><font size="2"><font face="Nimbus Mono L, monospace">/dev/sda1</font></font></b>
at <b><font size="2"><font face="Nimbus Mono L, monospace">/mnt/sda1</font></font></b>,
type: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">mount
/mnt/sda1</font></font></font></b> &#8211; if it is something else,
such as a hard drive partition, or a SCSI drive partition, e.g.,
 
<b><font size="2"><font face="Nimbus Mono L, monospace">/dev/sdb3</font></font></b>
or <b><font size="2"><font face="Nimbus Mono L, monospace">/dev/hda2</font></font></b>,
alter the command accordingly.</font></font></p>
<h3><a name="First usage|outline"></a><a name="First usage|outline"></a>
<font face="Nimbus Sans L, sans-serif"><font size="4">First usage</font></font></h3>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">It is possible
to create a Linux file system within a FAT file system with a two
stage process. We will use a Linux feature that treats an ordinary
file as a device (a so called &#8220;loop&#8221; file system). Within
the FAT file system, we will create a single large file called
<b><font size="2"><font face="Nimbus Mono L, monospace">LinuxFileSystem</font></font></b>
(the name does not really matter). By treating this file as a disk
drive, we will create a Linux file system within it, and mount this
file system as a loop file system.</font></font></p>
 
<p><font face="Nimbus Roman No9 L, serif"><font size="3">If this is the
first time that you are using that FAT file system, execute the
following commands (with a USB 1.x interface, each command could take
many minutes to tens of minutes; USB 2.x will be much faster):</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Create a 350MB
file called <b><font size="2"><font face="Nimbus Mono L, monospace">LinuxFileSystem</font></font></b>
on the FAT file system, adjust count as needed for a smaller or
larger file: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">dd
if=/dev/zero of=/mnt/sda1/LinuxFileSystem count=716800</font></font></font></b></font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Create a Linux
ext3 file system within <b><font size="2"><font face="Nimbus Mono L, monospace">LinuxFileSystem</font></font></b>:
<b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">mkfs
-t ext3 -F /mnt/sda1/LinuxFileSystem</font></font></font></b></font></font></p>
<h3><a name="First and subsequent usage|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4">First
and subsequent usage</font></font></h3>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Mount the
Linux file system within <b><font size="2"><font face="Nimbus Mono L, monospace">/mnt/sda1/LinuxFileSystem</font></font></b>
 
as <b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA</font></font></b>:
<b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">sudo
mount -o loop /mnt/sda1/LinuxFileSystem myVistA</font></font></font></b></font></font></p>
<h2><a name="Linux file system|outline"></a><a name="Linux file system|outline"></a><a name="Linux file system|outline"></a>
<font face="Nimbus Sans L, sans-serif"><font size="4"><i>Linux file
system</i></font></font></h2>
<h3><font face="Nimbus Sans L, sans-serif"><font size="4">First usage</font></font></h3>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">If a file
system does not exist in the read/write partition and one needs to be
created first (this will over-write any existing contents on the
partition): <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">sudo
mkfs -t ext3 /dev/hda2</font></font></font></b></font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Mount the
partition: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">sudo
mount /dev/hda2 myVistA</font></font></font></b></font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Change the
ownership of the mounted file system so that it is owned by user dsl:
 
<b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">sudo
chown -R dsl.staff myVistA</font></font></font></b></font></font></p>
<h3><a name="Subsequent usage|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4">Subsequent
usage</font></font></h3>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Simply mount
the partition: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">sudo
mount /dev/hda2 myVistA</font></font></font></b></font></font></p>
<h1><a name="4.Start GT.M &#8211; ready to run VistA|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="5">Start
GT.M &#8211; ready to run VistA</font></font></h1>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">You have
reached the real starting point of the GT.M Acculturation Workshop &#8211;
getting to the GT.M direct (i.e., interactive or immediate) mode
prompt (GTM&gt; in a terminal window) with the environment configured
to run VistA. At this point, you should have a Linux filesystem
mounted as <b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA</font></font></b>,
ready for a database to be loaded into it. The filesystem could be a
Linux filesystem on a a device, or residing in a file which itself
resides in a file on a FAT filesystem.</font></font></p>
 
<p><font face="Nimbus Roman No9 L, serif">The first time that you run
with the live CD, you will need create a VistA environment. The
underlying principles are on the <a href="http://openforum.worldvista.org/%7Eforum/index.php?title=Software_Development_%28WG1%29_Version_Control_%28T3%29">Setting
up a VistA Development page</a> of the <a href="http://openforum.worldvista.org/%7Eforum">WorldVistA
Wiki</a>. In case of limited internet access, a copy of relevant
material from which is cached locally <a href="file:///home/ivaldes/.gvfs/GT.MAcculturation0.4.iso/20060321WorldVistAWikiSWConfiguration.html">here</a>.
To create a VistA environment:</font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~$ <font color="#ff0000">/usr/local/FOIAVistA/install myVistA/FOIAVistA</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Creating environment in  myVistA/FOIAVistA  as child of environment in  /usr/local/FOIAVistA</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Unzipping from parent to create initial database</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-JNLCREATE, Journal file /ramdisk/home/dsl/myVistA/FOIAVistA/g/mumps.mjl created for database file /ramdisk/home/dsl/myVistA/FOIAVistA/g/mumps.dat with BEFORE_IMAGES</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-JNLSTATE, Journaling state for database file /ramdisk/home/dsl/myVistA/FOIAVistA/g/mumps.dat is now ON</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Default permission for development environment is for all to read and group to write - please alter as needed</b></font></font></pre><p>
<font face="Nimbus Roman No9 L">The above creates an environment for
GT.M, and uncompresses the database from the copy on the CD. This can
take from a few seconds to many minutes, depending on the type of
device (USB 2.x is slower than IDE / SCSI; USB 1.x is slower than USB
2.x), PC speed, etc.</font></p>
<p><font face="Nimbus Roman No9 L">On subsequent occasions, once the
database is uncompressed and copied, to run the application, execute
<b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">myVistA/FOIAVistA/run</font></font></font></b>
and get to the <b><font size="2"><font face="Nimbus Mono L, monospace">GTM&gt;</font></font></b>
prompt:</font></p>
<pre><font face="Nimbus Mono L"><font size="2"><b>dsl@box:~$ <font color="#ff0000">myVistA/FOIAVistA/run</font></b></font></font>
 
<font face="Nimbus Mono L"><font size="2"><b>GTM&gt;</b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">At this point,
you have a full character mode VistA, e.g.:</font></font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">set DUZ=1 do P^DI</font></b></font></font>
 
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>VA FileMan 22.0</b></font></font>
 
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>Select OPTION: <font color="#0000ff">?</font></b></font></font>
 
    <b><font face="Nimbus Mono L, monospace">Answer with OPTION NUMBER, or NAME</font></b>
  <b><font face="Nimbus Mono L, monospace">Choose from:</font></b>
  <b><font face="Nimbus Mono L, monospace">1            ENTER OR EDIT FILE ENTRIES</font></b>
  <b><font face="Nimbus Mono L, monospace">2            PRINT FILE ENTRIES</font></b>
  <b><font face="Nimbus Mono L, monospace">3            SEARCH FILE ENTRIES</font></b>
  <b><font face="Nimbus Mono L, monospace">4            MODIFY FILE ATTRIBUTES</font></b>
 
  <b><font face="Nimbus Mono L, monospace">5            INQUIRE TO FILE ENTRIES</font></b>
  <b><font face="Nimbus Mono L, monospace">6            UTILITY FUNCTIONS</font></b>
  <b><font face="Nimbus Mono L, monospace">7            OTHER OPTIONS</font></b>
  <b><font face="Nimbus Mono L, monospace">8            DATA DICTIONARY UTILITIES</font></b>
  <b><font face="Nimbus Mono L, monospace">9            TRANSFER ENTRIES</font></b>
   
<font face="Nimbus Mono L, monospace"><font size="2"><b>Select OPTION: <font color="#0000ff">&#8592; <i><font size="3"><font face="Nimbus Roman No9 L, serif">press Enter here</font></font></i></font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;</b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">Once you can
access the application, we can start to work with GT.M.</font></font></p>
<h1><a name="5.Excellent Documentation|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="5">Excellent
Documentation</font></font></h1>
<p><font face="Nimbus Roman No9 L, serif">GT.M user documentation
consists of manuals and technical bulletins. Manuals are updated
periodically, and technical bulletins serve as user documentation
updates that are available in a more timely manner. Current GT.M
documentation is available online at the <a href="http://www.sanchez-gtm.com/user_documentation/user_doc.htm">GT.M
documentation site</a> as well as a <a href="file:///usr/share/doc/gtm/index.html" target="_blank">local
copy</a> on this CD.</font></p>
<h2><a name="Manuals|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Manuals</i></font></font></h2>
<ul>
 
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Programmers
Guide</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Administration
and Operations Guide (caution: as of this writing, this is a draft
version of the Administration and Operations Guide in the new HTML
format generated from DocBook XML, and has a few rough edges).</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Messages
and Recovery Procedures</font></font></p>
</li></ul>
<h2><a name="Technical Bulletins|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Technical
Bulletins</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Sample
technical bulletins:</font></font></p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">V5.0-000C
Release Notes</font></font></p>
 
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">MUPIP Set
Journal</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Long
names</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Null
subscripts</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Supplementary
information</font></font></p>
</li></ul>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Onward to the
real GT.M acculturation workshop!</font></font></p>
<h1><a name="6.GT.M &#8211; a MUMPS unlike any other|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="5">GT.M
&#8211; a MUMPS unlike any other</font></font></h1>
 
<h2><a name="GT.M is just like any other M implementation|outline"></a>
<font face="Nimbus Sans L, sans-serif"><font size="4"><i>GT.M is just
like any other M implementation</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">You can type
lines of code and have them execute interactively, just like on any
other M implementation, e.g.:</font></font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Set ^X=1</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>1</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Kill ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Set S="S ^X=1 W ^X K ^X" Xecute S</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>1</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Halt</font></b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">You can edit
routines from the <b><font size="2"><font face="Nimbus Mono L, monospace">GTM&gt;</font></font></b>
prompt: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">ZEDit
"XUP"</font></font></font></b>. This starts the <b><font size="2"><font face="Nimbus Mono L, monospace">vi</font></font></b>
editor editing the source routine for <b><font size="2"><font face="Nimbus Mono L, monospace">^XUP</font></font></b>,
<b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA/FOIAVistA/r/XUP.m</font></font></b>.
Use the five key sequence <b><font size="2"><font color="#ff0000"><i><font face="Nimbus Sans L, sans-serif">Escape</font></i>
 
: q ! <i><font face="Nimbus Sans L, sans-serif">Enter</font></i></font></font></b>
to exit <b><font size="2"><font face="Nimbus Mono L, monospace">vi</font></font></b>
without changing the file.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">With the
exception of Structured System Variable Names (SSVNs), GT.M mostly
implements ISO standard M (ISO 11756&#8211;1999), including a full
implementation of transaction processing (TP) that provides ACID
(Atomic, Consistent, Isolated, Durable) transactions. As with any M
implementation, there are extensions, IO parameters are
implementation specific, as are the VIEW command, and commands &amp;
variables starting with the letter Z. </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Despite the
fact that the dialect of M implemented by GT.M shares so much in
common with other M implementations, operationally, GT.M is unlike
any other M implementation! </font></font>
</p>
 
<h2><a name="Routines are in the file system|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Routines
are in the file system</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Routines in
GT.M are simply files in the file system; they do not reside in
databases. To see the routines that make up VistA, try <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">ls
-l /usr/local/FOIAVistA/r</font></font></font></b> (this can take
several minutes the first time you try it, depending on the speed of
your PC). To count how many routines make up VistA, type <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">ls
-l /usr/local/FOIAVistA/r | wc</font></font></font></b> to get the
answer. The philosophy of GT.M is to focus on what it does well,
providing a robust, scalable, transaction processing database and a
compiler for the M language, and to leverage tools and capabilities
of the underlying operating system for the rest. This is powerful
because whenever there are enhancements to the underlying operating
environment, GT.M can benefit from them. This can also be a little
uncomfortable for the typical M programmer, because traditional M
implementations carry their environments with them, not unlike the
shell on a snail's back. </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">GT.M is a true
compiler that compiles source code routines into object code
routines. Source code is in files with a .m extension and object code
is in routines with a .o extension. On the GT.M acculturation
workshop live CD, the VistA routines have been pre-compiled. For
example, to see the source code routines on the CD for managing
Diagnostic Related Groups (DRG), type <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">ls
/usr/local/FOIAVistA/r/ICD*</font></font></font></b> and to see the
corresponding object code routines, type <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">ls
/usr/local/FOIAVistA/o/ICD*</font></font></font></b>. </font></font>
 
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">As you saw
when executing M commands interactively, the fact that GT.M is a true
compiler does not keep it from providing an interactive direct mode &#8211;
GT.M simply compiles and executes each line.</font></font></p>
<h3><a name="Exercise|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4">Exercise</font></font></h3>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The purpose of
this exercise is to understand compiling and linking routines. Since
not everyone is comfortable with the terse character-oriented
commands of vi, you can optionally use a mouse-and-menu based editor
called beaver before you enter GT.M:</font></font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~$ <font color="#ff0000">export EDITOR=`which beaver`</font></b></font></font>
<font color="#ff0000"><font face="Nimbus Mono L, monospace"><font size="2"><b><font color="#000000">dsl@box:~$ </font>myVistA/FOIAVistA/run</b></font></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;</b></font></font></pre><p>
 
<font face="Nimbus Roman No9 L, serif"><font size="3">Tell GT.M to run
the routine ^XYZ, and note that it reports an error that it cannot
find the routine: </font></font>
</p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Do ^XYZ</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-E-ZLINKFILE, Error while zlinking "XYZ"</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-E-FILENOTFND, File XYZ not found</b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">Note that the
directories <b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA/FOIAVistA/r</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA/FOIAVistA/o</font></font></b>
are empty:</font></font></p>
 
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">ZSYstem "ls -lR $vista_home"</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>/home/dsl/myVistA/FOIAVistA:</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-r-xr-xr-x    1 dsl      staff        278 Mar 22 03:18 cprs_direct</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-r--r--r--    1 dsl      staff        583 Mar 22 03:18 env</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>drwxrwxr-x    2 dsl      staff        4096 Mar 22 03:19 g</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>lrwxrwxrwx    1 dsl      staff          24 Mar 22 03:18 gtm -&gt; /usr/local/FOIAVistA/gtm</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-r-xr-xr-x    1 dsl      staff        2977 Mar 22 03:18 install</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>drwxrwxr-x    2 dsl      staff        4096 Mar 22 03:18 o</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>drwxrwxr-x    2 dsl      staff        4096 Mar 22 03:18 p</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>lrwxrwxrwx    1 dsl      staff          20 Mar 22 03:18 parent -&gt; /usr/local/FOIAVistA</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>drwxrwxr-x    2 dsl      staff        4096 Mar 22 03:18 r</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-r-xr-xr-x    1 dsl      staff        252 Mar 22 03:18 run</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>drwxrwxr-x    2 dsl      staff        4096 Mar 22 03:18 tmp</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-r-xr-xr-x    1 dsl      staff        4405 Mar 22 03:18 vista</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-r-xr-xr-x    1 dsl      staff        884 Mar 22 03:18 vista_cprs</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>/home/dsl/myVistA/FOIAVistA/g:</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-r--    1 dsl      staff  348910080 Mar 22 04:53 mumps.dat</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-r--r--r--    1 dsl      staff        1024 Mar 22 03:18 mumps.gld</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-r--    1 dsl      staff        7456 Mar 22 04:53 mumps.mjl</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>/home/dsl/myVistA/FOIAVistA/o:</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>/home/dsl/myVistA/FOIAVistA/p:</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>/home/dsl/myVistA/FOIAVistA/r:</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>/home/dsl/myVistA/FOIAVistA/tmp:</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;</b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">Type <font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">ZEDit
"XYZ"</font></font></font> then edit, create and save <b><font size="2"><font face="Nimbus Mono L, monospace">XYZ.m</font></font></b>
as a small M program, e.g., something that prints &#8220;Hello,
World!&#8221;. Remember to put a newline after the last line in your
routine. Save the file and exit the editor. </font></font>
</p>
 
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Execute <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">Do
^XYZ</font></font></font></b> (you can simply hit the up-arrow key
three times to recall the command) and note that your program runs as
expected. Now execute <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">ZSYstem
"ls -lR $vista_home"</font></font></font></b> again and
note that the directories <b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA/FOIAVistA/r</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA/FOIAVistA/o</font></font></b>
are no longer empty. There are two files,
<b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA/FOIAVistA/r/XYZ.m</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA/FOIAVistA/r/XYZ.o</font></font></b>.
The former is the source program that you just edited, and the latter
is the object code. GT.M dynamically, and automatically, recompiled
the source program into the object program when you typed <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">Do
^XYZ</font></font></font></b>. </font></font>
 
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Since GT.M is
a compiler, it can generate error messages at compile time as well as
at run time, and indeed when compiling VistA, there are hundreds of
lines of error messages triggered by lines of code that are legal for
other M implementations but not for GT.M. (These lines are protected
in VistA and are inside conditional statements that are executed only
on the appropriate M implementation, so they are nothing to be
concerned about.)</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Again edit the
program with <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">ZEDit
"XYZ"</font></font></font></b> then change it, e.g., make
it print &#8220;Aloha, World!&#8221; instead, save it. </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Again execute
<b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">Do
^XYZ</font></font></font></b> and note that GT.M still prints &#8220;Hello,
World!&#8221; This is because GT.M already has an XYZ module linked
in its address space, and does not go out every time to check if
there is a new version. This is &#8220;clobber protection&#8221; and
a GT.M feature. </font></font>
 
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Now execute
<b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">ZLink
"XYZ"</font></font></font></b> which tells GT.M to re-link
XYZ even if it already has one linked in its address space, followed
by <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">Do
^XYZ</font></font></font></b> and note that it now prints &#8220;Aloha,
World!&#8221; A <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">ZSYstem
"ls -lR $vista_home"</font></font></font></b> shows that
GT.M has recompiled the module to create a new object file (since
when it attempted the re-link, the source file was found to be newer
than the object file). </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The intrinsic
special variable <b><font size="2"><font face="Nimbus Mono L, monospace">$ZROutines</font></font></b>
 
tells GT.M where to find routines:</font></font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write $ZROutines</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>/home/dsl/myVistA/FOIAVistA/p /home/dsl/myVistA/FOIAVistA/o(/home/dsl/myVistA/FOIAVistA/r) /home/dsl/myVistA/FOIAVistA/parent/p /home/dsl/myVistA/FOIAVistA/parent/o(/</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>home/dsl/myVistA/FOIAVistA/parent/r) /usr/local/gtm_V5.0-000C</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;</b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">The Programmers
Guide explains in detail how <b><font size="2"><font face="Nimbus Mono L, monospace">$ZROutines</font></font></b>
is used. $ZROutines is initialized from the shell environment
variable <b><font size="2"><font face="Nimbus Mono L, monospace">$gtmroutines</font></font></b>
 
at:</font></font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write $ZTRNLNM("gtmroutines")</font> </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>/home/dsl/myVistA/FOIAVistA/p /home/dsl/myVistA/FOIAVistA/o(/home/dsl/myVistA/FOIAVistA/r) /home/dsl/myVistA/FOIAVistA/parent/p /home/dsl/myVistA/FOIAVistA/parent/o(/</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>home/dsl/myVistA/FOIAVistA/parent/r) /usr/local/gtm_V5.0-000C</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;</b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">The example uses
GT.M's <b><font size="2"><font face="Nimbus Mono L, monospace">$ZTRNLNM()</font></font></b>
function, which is used to get the value of environment variables.</font></font></p>
 
<h2><a name="Global directories point to global variables|outline"></a>
<font face="Nimbus Sans L, sans-serif"><font size="4"><i>Global
directories point to global variables</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Since routines
in GT.M reside in the file system rather than in the database,
whereas global variables reside in databases, routines are completely
independent of global variables. In this respect, GT.M is different
from other M implementations.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Given a
person's name, a telephone directory helps you find the person by
giving you the phone number and (usually) the address. Analogously,
given an M global variable name, a global directory helps a GT.M
process find the variable by giving it the database file where that
variable resides, as well as other pertinent information.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The global
directory is a binary file pointed to by the intrinsic special
variable <b><font size="2"><font face="Nimbus Mono L, monospace">$ZGbldir</font></font></b>.
The GDE utility program (invoked with <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">Do
^GDE</font></font></font></b> inside GT.M or <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">mumps
-run ^GDE</font></font></font></b> from the shell) is used to manage
global directories. [Note that the input to GDE can be a text file.
In a production environment, Fidelity recommends that text files be
used to define database configurations, and that these text files be
put under version control.] </font></font>
 
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">In GT.M, sets
of M global variables (Names or Name spaces) are mapped to Regions
that define properties relating to the M global. Each Region is
mapped to a Segment that defines properties relating to the file
system. Consider the example in the figure below: </font></font>
</p>
<p><img src="index_files/041014-2GlobalDirectory.gif" name="graphics3" align="left" border="0" height="552" width="828"><br clear="left"><br><br>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">In this
example, there are four M global variables that we would like to
separate from the rest (e.g, for purposes of sharing globals between
applications, or for reasons of protection &#8211; perhaps they
contain special information, so that only herpetologists are to have
access to globals <b><font size="2"><font face="Nimbus Mono L, monospace">^Gharial</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">^Jacare</font></font></b>,
and only ornithologists are to have access to globals <b><font size="2"><font face="Nimbus Mono L, monospace">^Hoopoe</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">^Trogon</font></font></b>).
This is accomplished by creating five name spaces (note that a name
space can contain a single variable, as in this example, or a range
of global variables, e.g., everything starting with <b><font size="2"><font face="Nimbus Mono L, monospace">^A</font></font></b>
 
through <b><font size="2"><font face="Nimbus Mono L, monospace">^Gharial</font></font></b>).
There is always a default (<font size="2"><font face="Nimbus Mono L, monospace">*</font></font>)
name space.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">One or more
name spaces are mapped to a <i>Region</i>. All global variables in a
region share a common set of M global variable properties, such as
the maximum record length, whether null subscripts are permitted,
etc. In this case <b><font size="2"><font face="Nimbus Mono L, monospace">^Gharial</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">^Jacare</font></font></b>
are mapped to the region <b><font size="2"><font face="Nimbus Mono L, monospace">REPTILES</font></font></b>,
whereas <b><font size="2"><font face="Nimbus Mono L, monospace">^Hoopoe</font></font></b>
 
and <b><font size="2"><font face="Nimbus Mono L, monospace">^Trogon</font></font></b>
are mapped to the region <b><font size="2"><font face="Nimbus Mono L, monospace">BIRDS</font></font></b>.
The default name space <font size="2"><font face="Nimbus Mono L, monospace">*</font></font>
is mapped to a region called <b><font size="2"><font face="Nimbus Mono L, monospace">DEFAULT</font></font></b>.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Each region is
mapped to a <i>Segment</i>. Just as a region defines properties
pertaining to M global variables, the segment defines properties
pertaining to the database file for that region, such as the file
name, the initial allocation, number of global buffers, etc. The
database file is just an ordinary file in the file system of the
underlying operating system.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Each database
file can have a single active journal file. A journal file can be
linked to a previous journal files to form a chain of journal files.</font></font></p>
 
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The intrinsic
special variable <b><font size="2"><font face="Nimbus Mono L, monospace">$ZGbldir</font></font></b>
points a GT.M process to the global directory. <b><font size="2"><font face="Nimbus Mono L, monospace">$ZGbldir</font></font></b>
is initialized from <b><font size="2"><font face="Nimbus Mono L, monospace">$gtmgbldir</font></font></b>
at process startup:</font></font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write $ZGbldir</font> </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>/home/dsl/myVistA/FOIAVistA/g/mumps.gld</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write $ZTRNLNM("gtmgbldir")</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>/home/dsl/myVistA/FOIAVistA/g/mumps.gld</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;</b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">Global
directories can have environment variables in database file names,
which is how one global directory can point to different database
files. </font></font>
</p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~$ <font color="#ff0000">myVistA/FOIAVistA/run ^GDE</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GDE-I-LOADGD, Loading Global Directory file </b></font></font>
        <b><font face="Nimbus Mono L, monospace">/home/dsl/myVistA/FOIAVistA/g/mumps.gld</font></b>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GDE-I-VERIFY, Verification OK</b></font></font>
 
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GDE&gt; <font color="#0000ff">show name</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GDE-E-VALUEBAD, name is not a valid Global qualifier</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GDE&gt; <font color="#0000ff">show -name</font></b></font></font>
 
        <b><font face="Nimbus Mono L, monospace">*** NAMES ***</font></b>
 
<b><font face="Nimbus Mono L, monospace">Global                            Region</font></b>
<b><font face="Nimbus Mono L, monospace">------------------------------------------------------------------------------</font></b>
<b><font face="Nimbus Mono L, monospace">*                                  DEFAULT</font></b>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GDE&gt; <font color="#0000ff">show -region</font></b></font></font>
 
                                <b><font face="Nimbus Mono L, monospace">*** REGIONS ***</font></b>
 
                                <b><font face="Nimbus Mono L, monospace">Dynamic                          Def    Rec  Key Null      Standard</font></b>
<b><font face="Nimbus Mono L, monospace">Region                          Segment                        Coll  Size  Size Subs      NullColl  Journaling</font></b>
<b><font face="Nimbus Mono L, monospace">------------------------------------------------------------------------------------------------------------------</font></b>
<b><font face="Nimbus Mono L, monospace">DEFAULT                        DEFAULT                            0  4080  255 NEVER      N        N</font></b>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GDE&gt; <font color="#0000ff">show -segment</font></b></font></font>
 
                                <b><font face="Nimbus Mono L, monospace">*** SEGMENTS ***</font></b>
<b><font face="Nimbus Mono L, monospace">Segment                        File (def ext: .dat)Acc Typ Block      Alloc Exten Options</font></b>
<b><font face="Nimbus Mono L, monospace">-------------------------------------------------------------------------------------------</font></b>
<b><font face="Nimbus Mono L, monospace">DEFAULT                        $vista_home/g/mumps.dat</font></b>
                                                    <b><font face="Nimbus Mono L, monospace">BG  DYN  4096      75000  2000 GLOB=2048</font></b>
                                                                                    <b><font face="Nimbus Mono L, monospace">LOCK=  40</font></b>
 
                                                                                    <b><font face="Nimbus Mono L, monospace">RES =  0</font></b>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GDE&gt; <font color="#0000ff">show -map</font></b></font></font>
 
                                  <b><font face="Nimbus Mono L, monospace">*** MAP ***</font></b>
  <b><font face="Nimbus Mono L, monospace">-  -  -  -  -  -  -  -  -  - Names -  -  - -  -  -  -  -  -  -</font></b>
<b><font face="Nimbus Mono L, monospace">From                            Up to                            Region / Segment / File(def ext: .dat)</font></b>
 
<b><font face="Nimbus Mono L, monospace">-----------------------------------------------------------------------------------------------------------------------------------</font></b>
<b><font face="Nimbus Mono L, monospace">%                              ...                              REG = DEFAULT</font></b>
                                                                  <b><font face="Nimbus Mono L, monospace">SEG = DEFAULT</font></b>
                                                                  <b><font face="Nimbus Mono L, monospace">FILE = $vista_home/g/mumps.dat</font></b>
<b><font face="Nimbus Mono L, monospace">LOCAL LOCKS                                                      REG = DEFAULT</font></b>
                                                                  <b><font face="Nimbus Mono L, monospace">SEG = DEFAULT</font></b>
 
                                                                  <b><font face="Nimbus Mono L, monospace">FILE = $vista_home/g/mumps.dat</font></b>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GDE&gt; <font color="#0000ff">quit</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GDE-I-NOACTION, Not updating Global Directory /home/dsl/myVistA/FOIAVistA/g/mumps.gld</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~$ </b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">In the example
above, notice how the database file is defined in terrms of the
environment variable $vista_home. This means that, as long as the
environment variable $vista_home is defined, a global directory on
the CD-ROM can serve to point to a database file wherever it happens
to be on the system. This can allow two processes to share a global
directory, but to have different database files. </font></font>
</p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write $ZTRNLNM(<font face="Nimbus Mono L">"vista_home")</font></font></b></font></font>
 
<font face="Nimbus Mono L"><font size="2"><b>/home/dsl/myVistA/FOIAVistA</b></font></font>
<font face="Nimbus Mono L"><font size="2"><b>GTM&gt;</b></font></font></pre><h2>
<a name="$ZROUTINES and $ZGBLDIR vs. UCI &amp; Volume set|outline"></a>
<font face="Nimbus Sans L, sans-serif"><font size="4"><i>$ZROUTINES and
$ZGBLDIR vs. UCI &amp; Volume set</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The GT.M
environment is defined by <b><font size="2"><font face="Nimbus Mono L, monospace">$ZROutines</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">$ZGbldir</font></font></b>.
Concepts from other M implementations such as UCI and volume set do
not exist on GT.M.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The GT.M
separation between routines and the database is very powerful,
especially in real-world environments. Apart from the flexibility
this offers, it enables the practice of &#8220;defensive
programming&#8221;, not unlike defensive driving. We are human beings
who are prone to err, and defensive practices reduce the probability
of errors.</font></font></p>
 
<h2><a name="Example: Development environments|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Example:
Development environments</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif">The example below is
adapted from a post I made on the <a href="http://lists.sourceforge.net/lists/listinfo/hardhats-members">Hardhats
mailing list</a>.</font></p>
<p><font face="Nimbus Roman No9 L, serif">Fil is <a href="http://hardhats.org/history/beza.html">Fil
Beza</a>, a key contributor to VistA for two decades who passed away
on February 3, 2005 (click on his name for tributes from those who
knew him). He gave me permission to use his name in the GT.M
Acculturation live CD, after I first developed this example in
response to one of his posts on the mailing list. </font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">If Fil and I
are developers and Fil's project is involves work on certain Lab
modules, he can create a <b><font size="2"><font face="Nimbus Mono L, monospace">/home/fil/lab</font></font></b>
subdirectory for his work and if my project is in Oncology, I can
create a <b><font size="2"><font face="Nimbus Mono L, monospace">/home/bhaskar/onc</font></font></b>
 
subdirectory for my work. If the reference (or production) routines
are in the directory /opt/vista_23.98/o for the object files and
/opt/vista_23.98/r for the source files, I can copy the files I wish
to work on from /opt/vista_23.98/r to <b><font size="2"><font face="Nimbus Mono L, monospace">/home/bhaskar/onc</font></font></b>
&#8211; I do not need to copy all 20,000+ routines to create my
private environment &#8211; and work on them in <b><font size="2"><font face="Nimbus Mono L, monospace">/home/bhaskar/onc</font></font></b>.
I can set <b><font size="2"><font face="Nimbus Mono L, monospace">$ZROUtines</font></font></b>
to <b><font size="2"><font face="Nimbus Mono L, monospace">"/home/bhaskar/onc
/opt/vista_23.98/o(/opt/vista_23.98/r)"</font></font></b>. As
long as I have read access to /opt/vista_23.98/ and its
subdirectories (e.g., by making them world read-only or setting up
ownership and permissions so that I do not have write access), I can
continue to use all routines there except those for which I have a
private copy, and I cannot possibly either deliberately or
inadvertently change the reference / production routines. Note that
while I technically do not need access to <b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/r</font></font></b>,
I nevertheless still include it in my <b><font size="2"><font face="Nimbus Mono L, monospace">$ZROUtines</font></font></b>
 
so that I can read the source code of any routine that need to
examine. </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Similarly, Fil
can set his <b><font size="2"><font face="Nimbus Mono L, monospace">$ZROUtines</font></font></b>
to <b><font size="2"><font face="Nimbus Mono L, monospace">"/home/fil/lab
/opt/vista_23.98/o(/opt/vista_23.98/r)"</font></font></b>. All
he needs to do is copy that set of routines that he wants to work on
from <b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/r</font></font></b>
to <b><font size="2"><font face="Nimbus Mono L, monospace">/home/fil/lab</font></font></b>
and change them. He doesn't need to copy all 20,000+ routines into
his private environment. We can also ensure that Fil cannot
deliberately or inadvertently change anything in the reference /
production environment, while continuing to use the routines therein.
This is shown in the diagram below (the link to <b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/o</font></font></b>
 
to find object code modules also includes a parenthetic reference to
<b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/r</font></font></b>
for the corresponding source code modules so that they can be
examined):</font></font></p>
<p><img src="index_files/041210-1EnvironmentExample1.jpg" name="graphics4" align="left" border="0" height="610" width="687"><br clear="left"><font face="Nimbus Roman No9 L, serif"><font size="3">Now
consider when Fil and I are done with our work. Since he and I have
been working in parallel, we will want to test our work for mutual
(in)compatibility. I can set my <b><font size="2"><font face="Nimbus Mono L, monospace">$ZROUtines</font></font></b>
to <b><font size="2"><font face="Nimbus Mono L, monospace">"/home/bhaskar/onc
/home/fil/lab /opt/vista_23.98/o(/opt/vista_23.98/r)"</font></font></b>
and Fil can set his <b><font size="2"><font face="Nimbus Mono L, monospace">$ZROUtines</font></font></b>
to <b><font size="2"><font face="Nimbus Mono L, monospace">"/home/fil/lab
/home/bhaskar/onc /opt/vista_23.98/o(/opt/vista_23.98/r)"</font></font></b>.
This allows us to use each other's routines in our own unit test
environments to see whether we have stepped on each other's toes. We
can find and address conflicts that go beyond both of us changing the
same code module. This is shown below.</font></font></p>
 
<p><img src="index_files/041210-1EnvironmentExample2.gif" name="graphics5" align="left" border="0" height="523" width="588"><br clear="left"><font face="Nimbus Roman No9 L, serif"><font size="3">GT.M
also simplifies version control, because it means that when I am
ready to check in my work, the only files we need to look at are in
<b><font size="2"><font face="Nimbus Mono L, monospace">/home/bhaskar/lab</font></font></b>,
since I could not possibly have changed anything in reference /
production, even inadvertently. </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">We can take
this example further. Suppose that Fil and I are doing our work with
a new GT.M version and part of what we are doing is to enhance the
application software to take advantage of a new feature in the new
release, say a <b><font size="2"><font face="Nimbus Mono L, monospace">$ZMAgic()</font></font></b>
function. He and I can set up a shared directory, say <b><font size="2"><font face="Nimbus Mono L, monospace">/var/newobj</font></font></b>
to which we both have read/write access. I can set up <b><font size="2"><font face="Nimbus Mono L, monospace">$ZROUtines</font></font></b>
to be <b><font size="2"><font face="Nimbus Mono L, monospace">"/home/bhaskar/onc
/var/newobj(/opt/vista_23.98/r)"</font></font></b> and Fil can
set up his <b><font size="2"><font face="Nimbus Mono L, monospace">$ZROUtines</font></font></b>
 
to be <b><font size="2"><font face="Nimbus Mono L, monospace">"/home/fil/lab
/var/newobj(/opt/vista_23.98/r)"</font></font></b>. Now,
whenever he or I reference a routine from the reference / production
environment, a new object module compiled by the new GT.M version
will be dynamically compiled and placed in <b><font size="2"><font face="Nimbus Mono L, monospace">/var/newobj</font></font></b>,
but the source routines in <b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/r</font></font></b>
are unaltered. </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">There are
similar things we can do with M globals using a global directory
pointed to by <b><font size="2"><font face="Nimbus Mono L, monospace">$ZGBLdir</font></font></b>.
For example, if the data dictionary is defined in <font size="2"><font face="Nimbus Mono L, monospace">^DIC</font></font>,
Fil and I can create global directories that refer to <b><font size="2"><font face="Nimbus Mono L, monospace">^DIC</font></font></b>
 
in the production / reference database. If we have read-only access
to that database file, we cannot possibly change it during the course
of our development, not even inadvertently, and we are assured that
our software is compatible with the production data dictionary.
Taking this one step further, if I know that my oncology work is only
supposed to affect globals <b><font size="2"><font face="Nimbus Mono L, monospace">^ABC</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">^DEF</font></font></b>,
I can set up a global directory and a sandbox database file that
allows me read/write access only to those two globals, and read-only
access to everything else. [Note, this slicing and dicing of globals
is done at the level of the global variable, and not at the level of
a subscript.] </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">GT.M also
simplifies version control, because it means that when I am ready to
check in my work, the only files we need to look at are in
/home/bhaskar/lab, since I could not possibly have changed anything
in reference / production, even inadvertently. </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">We can take
this example further. Suppose that Fil and I are doing our work with
a new GT.M version and part of what we are doing is to enhance the
application software to take advantage of a new feature in the new
release, say a $ZMAgic() function. He and I can set up a shared
directory, say /var/newobj to which we both have read/write access. I
can set up $ZROUtines to be "/home/bhaskar/onc
/var/newobj(/opt/vista_23.98/r)" and Fil can set up his
$ZROUtines to be "/home/fil/lab
/var/newobj(/opt/vista_23.98/r)". Now, whenever he or I
reference a routine from the reference / production environment, a
new object module compiled by the new GT.M version will be
dynamically compiled and placed in /var/newobj, but the source
routines in /opt/vista_23.98/r are unaltered. </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">There are
similar things we can do with M globals using a global directory
pointed to by $ZGBLdir. For example, if the data dictionary is
defined in ^DIC, Fil and I can create global directories that refer
to ^DIC in the production / reference database. If we have read-only
access to that database file, we cannot possibly change it during the
course of our development, not even inadvertently, and we are assured
that our software is compatible with the production data dictionary.
Taking this one step further, if I know that my oncology work is only
supposed to affect globals ^ABC and ^DEF, I can set up a global
directory and a sandbox database file that allows me read/write
access only to those two globals, and read-only access to everything
else. [Note, this slicing and dicing of globals can be done at the
level of the global variable, and not at the level of a subscript.] </font></font>
</p>
 
<h2><a name="Example: Application Service Provider|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Example:
Application Service Provider</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">In an
Application Service Provider (ASP) environment, the same application
code can be used for a number of customers, but each customer has its
own database. Sometimes parts of the database may also be common and
used on a read-only basis for normal operation, such as a data
dictionary, an approved drug formulary, or a table of sales tax rates
for each county or municipality. Each customer may also have a small
set of custom routines. In a &#8220;Harry Potter meets the magic of
VistA&#8221; example, let us consider an ASP serving St. Mungo's
Hospital as well as Azkaban Infirmary: </font></font>
</p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">The
majority of routines are shared with object files in
<b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/o</font></font></b>
and source files in <b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/r</font></font></b>.
</font></font>
 
</p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Custom
routines for St. Mungo's in <b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/o</font></font></b>
&amp; <b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/r</font></font></b>
for object &amp; source respectively. </font></font>
</p>
 
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Similarly,
custom routines for Azkaban are in <b><font size="2"><font face="Nimbus Mono L, monospace">/var/azkaban/o</font></font></b>
&amp; <b><font size="2"><font face="Nimbus Mono L, monospace">/var/azkaban/r</font></font></b>.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">The
National Drug File as approved by the Ministry of Magic in <b><font size="2"><font face="Nimbus Mono L, monospace">^PSNDF</font></font></b>
is shared by both institutions, but all other data is institution
specific. <b><font size="2"><font face="Nimbus Mono L, monospace">^PSNDF</font></font></b>
 
is in <b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/g/ndf.dat</font></font></b>.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">All other
globals for St. Mungo's are in <b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/g/mumps.dat</font></font></b>.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">All other
globals for Azkaban are in <b><font size="2"><font face="Nimbus Mono L, monospace">/var/azkaban/g/mumps.dat</font></font></b>.</font></font></p>
</li></ul>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">One way to
accomplish this is as follows: </font></font>
 
</p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">There
will be two Linux groups, <b><font size="2"><font face="Nimbus Mono L, monospace">stmungos</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">azkaban</font></font></b>.
All St. Mungo's users will belong to the former, and all Azkaban
users will belong to the latter.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3"><b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos</font></font></b>
will have subdirectory <b><font size="2"><font face="Nimbus Mono L, monospace">o</font></font></b>
 
for object files of M routines that are used only by St. Mungo's;
subdirectory <b><font size="2"><font face="Nimbus Mono L, monospace">r</font></font></b>
for source files of M routines specific to St. Mungo's; subdirectory
<b><font size="2"><font face="Nimbus Mono L, monospace">g</font></font></b>
for the database file <b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/g/mumps.dat</font></font></b>;
and subdirectory <b><font size="2"><font face="Nimbus Mono L, monospace">j</font></font></b>
for the journal files. Note that <b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/j</font></font></b>
 
will actually be a file system mounted on a different disk and a
different controller, either mounted at <b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/j</font></font></b>
or pointed to as a symbolic link by <b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/j</font></font></b>
&#8211; in a production environment, for reasons of recoverability
from a hardware failure, it is desirable for a database file and its
journal file to reside on different hard drives with different
controllers. <b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/g/mumps.dat</font></font></b>,
<b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/j</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/j/mumps.mjl</font></font></b>
 
will be read-writable only by members of the group stmungos. No one
else will even have read-only access. <b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/o</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">/var/stmungos/r</font></font></b>
will be read-only directories, since the only time to change a
routine (or its object code) will be when the application is being
updated. At all other times, we will use Linux file permissions to
ensure that routines cannot even inadvertently be altered. </font></font>
</p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3"><b><font size="2"><font face="Nimbus Mono L, monospace">/var/azkaban</font></font></b>
will be similarly configured to be accessible by Azkaban users and
no one else. </font></font>
 
</p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3"><b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98</font></font></b>
and all subdirectories and files are available to all users but on a
read-only basis. The subdirectories will be <b><font size="2"><font face="Nimbus Mono L, monospace">o</font></font></b>
for object files, <b><font size="2"><font face="Nimbus Mono L, monospace">r</font></font></b>
for routines, and <b><font size="2"><font face="Nimbus Mono L, monospace">g</font></font></b>
 
for a global directory, <b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/g/mumps.gld</font></font></b>
as well as for the national drug database file
<b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/g/ndf.dat</font></font></b>.
Note that <b><font size="2"><font face="Nimbus Mono L, monospace">ndf.dat</font></font></b>
is used read-only, and static files do not need to be journaled.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">The
global directory <b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/g/mumps.gld</font></font></b>
 
will have two name spaces, <b><font size="2"><font face="Nimbus Mono L, monospace">NDF</font></font></b>,
to which will be directed, and which will point to the database file
<b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/g/ndf.dat</font></font></b>
and <b><font face="Nimbus Mono L, monospace">DEFAULT</font></b>
which will point to <b><font size="2"><font face="Nimbus Mono L, monospace">/var/$GROUP/g/mumps.dat</font></font></b>.
The environment variable <b><font face="Nimbus Mono L, monospace">$GROUP</font></b>
will be set in the Linux shell when a user logs in, and used by the
sole global directory <b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/g/mumps.gld</font></font></b>
 
to point GT.M processes from each hospital to their appropriate
database. </font></font>
</p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">The
commands below in the file <b><font size="2"><font face="Nimbus Mono L, monospace">/etc/profile.local</font></font></b>
are used to set the environment variables for all users on the
system. Note the use of the environment variable <b><font face="Nimbus Mono L, monospace">$GROUP</font></b>
to again set the correct value of <b><font size="2"><font face="Nimbus Mono L, monospace">$gtmroutines</font></font></b>
 
appropriately for each user.</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>export GROUP=${GROUP:=`id -gn`}</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>export gtm_dist=/usr/local/gtm ; source $gtm_dist/gtmprofile</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>export gtmgbldir=/opt/vista_23.98/g/mumps.gld</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>export gtmroutines="/var/$GROUP/o(/var/$GROUP/r) /opt/vista_23.98/o(/opt/vista_23.98/r) $gtm_dist"</b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">It is worth
taking the time to review the above example, to see how with maximum
commonality and minimal customization, each user is directed to the
correct database and routines for his/her institution. Note that even
if a user were to manually change his environment variables and
attempt to access the database and routines of another institution,
the Linux file system permissions would prevent such unauthorized
access.</font></font></p>
<h3><a name="Exercise &#8211; GDE commands for ASP|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4">Exercise
&#8211; GDE commands for ASP</font></font></h3>
 
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Write the
commands to be used by GDE to create the global directory
<b><font size="2"><font face="Nimbus Mono L, monospace">/opt/vista_23.98/g/mumps.gld</font></font></b>.
Assume that maximum key size is 255 bytes, the maximum record size is
2000 bytes, the desired block size is 4096 bytes, and the number of
global buffers is 4000 for each institution's main database, and 1000
for the National Drug File database.</font></font></p>
<h2><a name="GT.M leverages the operating system|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>GT.M
leverages the operating system</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Wherever
possible, the GT.M philosophy is to leverage what is already there in
the underlying computer system, rather than reinventing it. For
example, you use the editor of your choice when editing M routines.
You used the beaver editor earlier; now try another, e.g., nano.</font></font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~$ <font color="#ff0000">export EDITOR=`which nano`</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~$ <font color="#ff0000">myVistA/FOIAVistA/run</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">ZEDit "XYZ"</font></b></font></font></pre><h2>
 
<a name="Security|outline"></a><a name="Security|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Security</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">In order to
meet the needs of financial applications, GT.M was designed from the
very beginning to be secure. [Caveat: absolute security does not
exist in this universe. For a discussion that bridges philosophy and
technology, I highly recommend Bruce Schneier's <i>Secrets and Lies</i>,
ISBN 0-471-25311-1.]</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">A GT.M process
can access a database file only if the file ownership and permissions
allow that access. Under normal operation, there is no component of
GT.M that operates as the super user (root). The GT.M security model
is simple, well understood and documented.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">It is
extremely straightforward to create a user id that can only login,
run VistA and log out.</font></font></p>
<h3><a name="Exercise &#8211; Security|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4">Exercise
&#8211; Security</font></font></h3>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">In the
following, notice how Linux file permissions are used to allow user
dsl full access to the database, and preventing another user from
updating a database, while allowing that user to read from it. Notice
how the commands source /usr/local/gtm/gtmprofile, mumps -run ^GDE
and mupip create are used to set up the GT.M environment, create a
global directory and create the database file(s). In subsequent
exercises, you will have to remember to do that yourself without
being told!</font></font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~$ <font color="#ff0000">mkdir myVistA/tmp ; cd myVistA/tmp</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">source /usr/local/gtm/gtmprofile</font> </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -run ^GDE</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GDE-I-GDUSEDEFS, Using defaults for Global Directory </b></font></font>
        <b><font face="Nimbus Mono L, monospace">/ramdisk/home/dsl/myVistA/tmp/mumps.gld</font></b>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GDE&gt; <font color="#0000ff">change -segment DEFAULT -file=/home/dsl/myVistA/tmp/mumps.dat</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GDE&gt; <font color="#0000ff">exit</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GDE-I-VERIFY, Verification OK</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GDE-I-GDCREATE, Creating Global Directory file </b></font></font>
        <b><font face="Nimbus Mono L, monospace">/ramdisk/home/dsl/myVistA/tmp/mumps.gld</font></b>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip create</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Created file /home/dsl/myVistA/tmp/mumps.dat</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">chmod o-w mumps.dat</font> </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">ls -l mumps.dat</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-r--    1 dsl      staff      169472 Mar 22 21:41 mumps.dat</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Set ^X=1</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>1</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Halt</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">sudo su - lp</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>lp@ttyp0[lpd]$ <font color="#ff0000">cd /home/dsl/myVistA/tmp</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>lp@ttyp0[tmp]$ <font color="#ff0000">source /usr/local/gtm/gtmprofile</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>lp@ttyp0[tmp]$ <font color="#0000ff">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>1</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Kill ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-E-DBPRIVERR, No privilege for attempted update operation for file: /home/dsl/myVistA/tmp/mumps.dat</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Halt</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>lp@ttyp0[tmp]$ <font color="#ff0000">exit</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>logout</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">cd ../..</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~$ <font color="#ff0000">rm -rf myVistA/tmp</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~$ </b></font></font></pre><h2>
<a name="No special startup or shutdown|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>No
special startup or shutdown</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The first
process to open a database file sets up all the shared memory control
structures needed. The last one out tears it down. There is no daemon
that must run as root that can be a single point of failure, a
performance bottleneck, or a potential security vulnerability.</font></font></p>
 
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Upon bringing
the system back up, if the system crashes, or is forcibly brought
down: if journaling is in use, <b><font size="2"><font face="Nimbus Mono L, monospace">mupip
journal -recover</font></font></b> (or <b><font size="2"><font face="Nimbus Mono L, monospace">mupip
journal -rollback</font></font></b> if replication is in use) will
recover the database. If journaling is not in use, <b><font size="2"><font face="Nimbus Mono L, monospace">mupip
rundown -region "*"</font></font></b> will clean up the
database, but cannot fix any integrity errors caused, for example,
but shutting down a computer without cleanly terminating GT.M
processes. [Note: do not use <b><font size="2"><font face="Nimbus Mono L, monospace">mupip
rundown</font></font></b> if journaling is in use and you plan to
recover the database after a crash with a <b><font size="2"><font face="Nimbus Mono L, monospace">mupip
journal</font></font></b> operation.]</font></font></p>
 
<h2><a name="Journaling &#8211; the key to database integrity|outline"></a>
<font face="Nimbus Sans L, sans-serif"><font size="4"><i>Journaling &#8211;
the key to database integrity</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">GT.M, like
virtually all high performance databases, uses journaling (called
&#8220;logging&#8221; by some databases) to restore data integrity
and provide continuity of business after an unplanned event such as a
system crash.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">There are two
switches to turn on journaling &#8211; <b><font size="2"><font face="Nimbus Mono L, monospace">ENable</font></font></b>
/ <b><font size="2"><font face="Nimbus Mono L, monospace">DISable</font></font></b>
 
and <b><font size="2"><font face="Nimbus Mono L, monospace">ON</font></font></b>/<b><font size="2"><font face="Nimbus Mono L, monospace">OFF</font></font></b>.
Enabling or disabling journaling requires stand alone access to the
database. Turning journaling on and off can be done when the database
is in use. </font></font>
</p>
<h3><a name="Exercise - journaling|outline"></a><a name="Exercise - journaling|outline"></a>
<font face="Nimbus Sans L, sans-serif"><font size="4">Exercise -
journaling</font></font></h3>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Here, we will
set up journaling for a database, simulate a crash, and recover the
database from the journal file. Since GT.M database administration
commands are normally issued from the Linux shell, outside GT.M, we
will manually set up the environment GT.M expects (which thus far has
been done in shell scripts). Also, note that the Linux command <b><font size="2"><font face="Nimbus Mono L, monospace">ipcs
-m</font></font></b> is used twice: first to report on shared memory
segments that exist before any database access; and again after the
database has been accessed &#8211; the additional shared memory
segment reported the second time is used by GT.M for the database
file. A system crash is simulated by deleting the shared memory
segment used for the database and terminating the GT.M process (do
not ever attempt the following on a real system except for testing
purposes; because of the possibility of human error, <b><u><i>do not
ever</i></u></b> do this on a machine where production applications
are operating, even for testing). </font></font>
 
</p>
<p><font face="Nimbus Roman No9 L, serif">Note that the numbers in
<font color="#ff00ff">fuchsia (light magenta)</font> are process ids,
and shared memory keys tht we will manipulate as part of the
exercise. They will vary from machine to machine and run to run. You
should use the values from your machine for your run. Create a
directory ~/myVistA/tmp, set up the GT.M environment, create a global
directory and an initial database (see <a href="#Exercise+%3F+Security%7Coutline">above</a>,
if you don't remember how to). We start by turning on journaling for
the newly created database.</font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip set -journal="enable,on,before" -region "*"</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-JNLCREATE, Journal file /ramdisk/home/dsl/myVistA/tmp/mumps.mjl created for region DEFAULT with BEFORE_IMAGES</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-JNLSTATE, Journaling state for region DEFAULT is now ON</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">ls -l</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-rw-    1 dsl      staff      169472 Mar 23 12:48 mumps.dat</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-r--    1 dsl      staff        1024 Mar 23 12:48 mumps.gld</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-rw-    1 dsl      staff        2368 Mar 23 12:48 mumps.mjl</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">ZSYstem "ps -ef | grep mumps"</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl        <font color="#ff00ff">671</font>  631  0 12:48 ttyp1    00:00:00 mumps -dir</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl        672  671  0 12:49 ttyp1    00:00:00 /bin/bash -c ps -ef | grep mumps</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl        674  672  0 12:49 ttyp1    00:00:00 /bin/bash -c ps -ef | grep mumps</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">ZSYstem "ipcs -m"</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>------ Shared Memory Segments --------</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>key        shmid      owner      perms      bytes      nattch    status      </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>0x00000000 0          dsl      777        393216    2          dest        </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>0x00000000 557057    dsl      777        393216    2          dest        </b></font></font>
 
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Kill ^X Set ^X=$Job</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">ZSYstem "ipcs -m"</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>------ Shared Memory Segments --------</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>key        shmid      owner      perms      bytes      nattch    status      </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>0x00000000 0          dsl      777        393216    2          dest        </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>0x00000000 557057    dsl      777        393216    2          dest        </b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>0x00000000 <font color="#ff00ff">655362</font>    dsl      777        2629632    1                      </b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font color="#ff00ff"><font face="Nimbus Mono L, monospace"><font size="2"><b>671</b></font></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">ZSYstem "sudo ipcrm -m <font color="#ff00ff">655362</font> ; kill -9 "_^X</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>Killed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">ipcs -m</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>------ Shared Memory Segments --------</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>key        shmid      owner      perms      bytes      nattch    status      </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>0x00000000 0          dsl      777        393216    2          dest        </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>0x00000000 557057    dsl      777        393216    2          dest        </b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">ps -ef | grep mumps</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip journal -recover -backward mumps.mjl</font> </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJNLSTAT, Initial processing started at Thu Mar 23 12:50:17 2006</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJNLSTAT, Backward processing started at Thu Mar 23 12:50:17 2006</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJNLSTAT, Before image applying started at Thu Mar 23 12:50:17 2006</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-FILERENAME, File /ramdisk/home/dsl/myVistA/tmp/mumps.mjl is renamed to /ramdisk/home/dsl/myVistA/tmp/mumps.mjl_2006082124931</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJNLSTAT, Forward processing started at Thu Mar 23 12:50:17 2006<font color="#0000ff">Halt</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-S-JNLSUCCESS, Show successful</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-S-JNLSUCCESS, Verify successful</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-S-JNLSUCCESS, Recover successful</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJNLSTAT, End processing at Thu Mar 23 12:50:17 2006</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>671</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Halt</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$</b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">Notice how the
journal file is used to recover the database.</font></font></p>
<h2><a name="Database replication|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Database
replication</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">When an
application must have the best possible continuity of business, use
database replication in addition to before image journaling to create
a logical dual site configuration. A major restriction of GT.M
replication today is that the primary and secondary must both be on
Planet Earth. We will simulate a logical dual site configuration
between a data center in Honolulu, Hawaii (21°N 157°W) and a
data center in Ghanzi, Botswana (21°S 21°E), the furthest
town from Honolulu big enough to have an airport, 12,400 miles away. </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Network
information: when Ghanzi is the secondary, it will listen to Honolulu
on localhost:4265 (IP:port); when Honolulu is the secondary, it will
listen to Ghanzi on localhost:3355. Configure replication as follows:</font></font></p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Create a
directory /home/dsl/dualsite for this exercise, with subdirectories
Honolulu and Ghanzi:</font></font></p>
</li></ul>
<pre style="margin-bottom: 0.2in;"><font color="#ff0000"><font face="Nimbus Mono L, monospace"><font size="2"><b>mkdir -p myVistA/dualsite/{Honolulu,Ghanzi}</b></font></font></font></pre>
 
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Create
two terminal windows, one simulating Honolulu and one simulating
Ghanzi. Use different backgrounds so that they look visually
different: right click on the screen background, choose <b><font size="2"><font face="Nimbus Sans L, sans-serif">Xshells</font></font></b>
and then your choice of background for the terminal window
(<b><font size="2"><font face="Nimbus Sans L, sans-serif">Transparent</font></font></b>,
<b><font size="2"><font face="Nimbus Sans L, sans-serif">Light</font></font></b>
or <b><font size="2"><font face="Nimbus Sans L, sans-serif">Dark</font></font></b>).</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">In the
Honolulu window, change to the Honolulu subdirectory (<b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">cd
myVistA/dualsite/Honolulu</font></font></font></b>). In the Ghanzi
window, change to the Ghanzi subdirectory (<b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">cd
myVistA/dualsite/Ghanzi</font></font></font></b>). </font></font>
 
</p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">In each
of Honolulu and Ghanzi (notice the use of the <b><font size="2"><font face="Nimbus Mono L, monospace">-replication=on</font></font></b>
switch to turn on replication): </font></font>
</p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">source /usr/local/gtm/gtmprofile</font></b></font></font>
<b><font face="Nimbus Mono L, monospace"><a href="mailto:dsl@box"><font color="#000000">dsl@box:~/myVistA/dualsite/Honolulu</font></a>$ <font color="#ff0000">export gtm_repl_instance=mumps.repl</font></font></b>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">mumps -run ^GDE</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GDE&gt; <font color="#0000ff">exit</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>...</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">mupip create</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">mupip set -journal="enable,before,on" -replication=on -region "*"</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">mupip replicate -instance_create</font></b></font></font></pre>
 
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">In
Honolulu (<b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA/dualsite/Honolulu</font></font></b>),
create four files as follows:</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>primary_start:</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>#!/bin/bash</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>mupip replicate -source -start -buf=1 -secondary=localhost:4265 -log=source.log</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>primary_stop:</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>#!/bin/bash</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>mupip replicate -source -shutdown -timeout=0</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>mupip rundown -region "*"</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>secondary_start:</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>#!/bin/bash</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>mupip replicate -source -start -passive -buf=1 -log=source.log</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>mupip replicate -receive -start -listenport=3355 -buf=1 -log=receive.log</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>secondary_stop:</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>#!/bin/bash</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>mupip replicate -receive -shutdown -timeout=0</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>mupip replicate -source -shutdown -timeout=0</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>mupip rundown -region "*"</b></font></font></pre>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Make the
files executable: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">chmod
a+x {primary,secondary}_{start,stop}</font></font></font></b></font></font></p>
 
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">In Ghanzi
(<b><font size="2"><font face="Nimbus Mono L, monospace">/home/dsl/myVistA/dualsite/Ghanzi</font></font></b>)
create files <b><font size="2"><font face="Nimbus Mono L, monospace">primary_start</font></font></b>,
<b><font size="2"><font face="Nimbus Mono L, monospace">primary_stop</font></font></b>,
<b><font size="2"><font face="Nimbus Mono L, monospace">secondary_start</font></font></b>,
<b><font size="2"><font face="Nimbus Mono L, monospace">secondary_stop</font></font></b>
which are identical to those in Honolulu, except that <b><font size="2"><font face="Nimbus Mono L, monospace">primary_start</font></font></b>
should specify the secondary as localhost:3355 and <b><font size="2"><font face="Nimbus Mono L, monospace">secondary_start</font></font></b>
 
should specify that the Receive Server should listen at port 4265.
Make these files also executable. (It will probably be easiest to
copy all four files and edit <b><font size="2"><font face="Nimbus Mono L, monospace">primary_start</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">secondary_start</font></font></b>
to make the changes.)</font></font></p>
</li></ul>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Operate the
logical dual site configuration with Honolulu as the primary and
Ghanzi as the secondary:</font></font></p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">In
Honolulu, start the primary: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">./primary_start</font></font></font></b></font></font></p>
 
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">In
Ghanzi, start the secondary: <font color="#ff0000">.<b><font size="2"><font face="Nimbus Mono L, monospace">/secondary_start</font></font></b></font></font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Set a
global variable in Honolulu, e.g., <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">Set
^X=1</font></font></font></b></font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Notice
how it is replicated in Ghanzi:</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>1</b></font></font></pre>
 
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Simulate
a broken network connection (or a down secondary) by executing in
Ghanzi: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">./secondary_stop</font></font></font></b></font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Make a
database change in Honolulu: e.g., <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#0000ff">Set
^X=2</font></font></font></b></font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Note how
the change is not replicated in Ghanzi:</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>1</b></font></font></pre>
 
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Simulate
restoring the network connection and/or bringing up the down
secondary by executing in Ghanzi: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">./secondary_start</font></font></font></b></font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Notice
how Ghanzi automatically catches up (since with GT.M replication,
the secondary listens at a TCP socket while the primary makes
periodic attempts to connect to the secondary, it may take a few
seconds for Honolulu to detect that Ghanzi is functional again and
to resume replication; once replication is resumed, any backlog of
data is rapidly streamed to the secondary):</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>2</b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">Execute a
failover for a planned outage at Honolulu:</font></font></p>
<ul>
 
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Check the
replication backlog in Honolulu to make sure that there is not a
replication backlog: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">mupip
replicate -source -showbacklog</font></font></font></b></font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Bring
Honolulu down: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">./primary_stop</font></font></font></b></font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Bring
Ghanzi down as the secondary, and bring it back up as the primary:</font></font></p>
</li></ul>
<pre><font color="#ff0000"><font face="Nimbus Mono L, monospace"><font size="2"><b>./secondary_stop</b></font></font></font>
<font color="#ff0000"><font face="Nimbus Mono L, monospace"><font size="2"><b>./primary_start</b></font></font></font></pre>
<ul>
 
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Make some
database updates to simulate Ghanzi operating as the primary. These
will of course not be replicated in Honolulu &#8211; verify that
Honolulu is indeed not being updated.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">After
simulated maintenance to Honolulu, bring it up as the secondary:
<b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">./secondary_start</font></font></font></b></font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Verify
that Honolulu automatically catches up, that data is now replicated
from Ghanzi to Honolulu and that Ghanzi reports no backlog.</font></font></p>
</li></ul>
<h3><a name="Replication and Backlogs|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4">Replication
and Backlogs</font></font></h3>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">In an ideal
world, a primary never goes down when there is a backlog. In the real
world, the primary may well go down with a backlog of updates that
have not been replicated on the secondary. In order to provide
continuity of business, the former secondary must come up as the new
primary to keep the application available. When the former primary
comes up as the new secondary, the updates that were part of the
backlog must be handled. GT.M provides the hooks needed to create
applications that are continuously available, but the application
must take advantage of these hooks. Consider the following example
(the notation P: 100 means that the site is operating as the primary
and has committed update number 100):</font></font></p>
 
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<col width="128">
<col width="128">
<thead>
<tr valign="top">
<td width="50%">
<p align="left"><font face="Nimbus Roman No9 L, serif">Honolulu</font>
</p>
</td>
 
<td width="50%">
<p align="left"><font face="Nimbus Roman No9 L, serif">Ghanzi</font>
</p>
</td>
</tr>
</thead>
<tbody>
<tr valign="top">
 
<td width="50%">
<p align="left"><font face="Nimbus Roman No9 L, serif">P: 100</font>
</p>
</td>
<td width="50%">
<p align="left"><font face="Nimbus Roman No9 L, serif">S: 95
(backlog of 5 updates)</font>
</p>
</td>
 
</tr>
<tr valign="top">
<td width="50%">
<p align="left"><font face="Nimbus Roman No9 L, serif">Crashes</font>
</p>
</td>
<td width="50%">
<p align="left"><font face="Nimbus Roman No9 L, serif">P: 95
(becomes the primary and starts processing)</font>
</p>
 
</td>
</tr>
<tr valign="top">
<td width="50%">
<p align="left"><font face="Nimbus Roman No9 L, serif">Repaired and
brought back up</font>
</p>
</td>
<td width="50%">
<p align="left"><font face="Nimbus Roman No9 L, serif">P: 120
(processing moves it ahead)</font>
</p>
 
</td>
</tr>
</tbody>
</table>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">This situation
would appear to be problematic, because updates 96-100 on Honolulu
are different from updates 96-100 on Ghanzi. The GT.M solution is to
rollback those transactions on the former primary / new secondary.
These rolled back updates (referred to as &#8220;lost transactions&#8221;)
are placed in a file by GT.M, and must be handled. The <b><font size="2"><font face="Nimbus Mono L, monospace">-fetchresync</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">-losttrans</font></font></b>
qualifiers to the <b><font size="2"><font face="Nimbus Mono L, monospace">mupip
journal -rollback</font></font></b> command deal with the situation
where a former primary comes up as the new secondary. The
 
<b><font size="2"><font face="Nimbus Mono L, monospace">-fetchresync</font></font></b>
qualifier causes <b><font size="2"><font face="Nimbus Mono L, monospace">mupip
journal -rollback</font></font></b> to ask the new primary for the
update number at which it became the primary, and rolls back the
database to that point. The updates that are rolled off are placed in
a &#8220;lost transaction file&#8221; from which the application can
determine what should be done with them (they are sent to the new
primary for reprocessing).</font></font></p>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<col width="128">
<col width="128">
<thead>
 
<tr valign="top">
<td width="50%">
<p align="left"><font face="Nimbus Roman No9 L, serif">Honolulu</font>
</p>
</td>
<td width="50%">
<p align="left"><font face="Nimbus Roman No9 L, serif">Ghanzi</font>
</p>
 
</td>
</tr>
</thead>
<tbody>
<tr valign="top">
<td width="50%">
<p><font face="Nimbus Roman No9 L, serif">S: 95 (database
recovered and rolled back from 100 to 95; lost transaction file
created sent to Ghanzi for reprocessing)</font>
</p>
</td>
 
<td width="50%">
<p><font face="Nimbus Roman No9 L, serif">P: 120</font>
</p>
</td>
</tr>
<tr valign="top">
<td width="50%">
<p><font face="Nimbus Roman No9 L, serif">S: 120 (catches up
shortly after coming back up and being reconnected)</font>
</p>
 
</td>
<td width="50%">
<p><font face="Nimbus Roman No9 L, serif">P: 120</font>
</p>
</td>
</tr>
<tr valign="top">
<td width="50%">
<p><font face="Nimbus Roman No9 L, serif">S: 125 (lost
transactions make it back after reprocessing)</font>
</p>
 
</td>
<td width="50%">
<p><font face="Nimbus Roman No9 L, serif">P: 125 (updates from
lost transaction file reprocessed)</font>
</p>
</td>
</tr>
</tbody>
</table>
<h3><a name="Exercise &#8211; replication backlogs|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4">Exercise
&#8211; replication backlogs</font></font></h3>
 
<p><font face="Nimbus Roman No9 L, serif"><font size="3">The exercise
below simulates the situation above (as before <font color="#ff00ff">fuchsia
/ light magenta</font> is used for process ids and memory keys that
will vary from run to run):</font></font></p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">In
Honolulu, start the primary, and simulate some updates (note that
when simulating a crash in a replicated environment, there are two
processes to be killed &#8211; the mumps process and the source
server, a mupip process; also the shared memory sections are created
by the source server even before the GT.M process attaches to them,
which it does when it updates the database):</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">ipcs -m</font>        </b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>------ Shared Memory Segments --------</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>key        shmid      owner      perms      bytes      nattch    status      </b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">./primary_start</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">ipcs -m</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>------ Shared Memory Segments --------</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>key        shmid      owner      perms      bytes      nattch    status      </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>0x00000000 <font color="#ff00ff">4653056</font>    dsl      777        1048576    1                      </b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>0x00000000 <font color="#ff00ff">4685825</font>    dsl      777        2629632    1                      </b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff3366">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Set ^X=$Job</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>926</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">ZSYstem "ps -ef | grep -E \(mumps\)\|\(mupip\) ; ipcs -m"</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl        <font color="#ff00ff">924</font>    1  0 14:28 ?        00:00:00 mupip replicate -source -start -buf=1 -secondary=localhost:4265 -log=source.log</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl        <font color="#ff00ff">926</font>  863  0 14:29 ttyp1    00:00:00 mumps -dir</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl        928  926  0 14:29 ttyp1    00:00:00 /bin/bash -c ps -ef | grep -E \(mumps\)\|\(mupip\) ; ipcs -m</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl        930  928  0 14:29 ttyp1    00:00:00 /bin/bash -c ps -ef | grep -E \(mumps\)\|\(mupip\) ; ipcs -m</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>------ Shared Memory Segments --------</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>key        shmid      owner      perms      bytes      nattch    status      </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>0x00000000 <font color="#ff00ff">4653056</font>    dsl      777        1048576    2                      </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>0x00000000 <font color="#ff00ff">4685825</font>    dsl      777        2629632    2                      </b></font></font>
 
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;</b></font></font></pre>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">In
Ghanzi, verify that replication is operating normally. Then bring
down the secondary so that a backlog can be built up on the primary
to simulate a crash with a backlog:</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Ghanzi$ <font color="#ff0000">./secondary_start</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Ghanzi$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>926</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Halt</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Ghanzi$ .<font color="#ff0000">/secondary_stop</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Thu Mar 23 14:32:39 2006 : Initiating shut down</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Signalling immediate shutdown</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Receive pool shared memory removed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Receive pool semaphore removed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Thu Mar 23 14:32:40 2006 : Initiating shut down</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>Signalling shutdown immediate</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Journal pool shared memory removed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Journal pool semaphore removed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUFILRNDWNSUC, File /ramdisk/home/dsl/myVistA/dualsite/Ghanzi/mumps.dat successfully rundown</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Ghanzi$ </b></font></font></pre>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">In
Honolulu, perform an update, which will become the backlog when
Honolulu crashes (after Honolulu recovers and becomes a new
secondary, this backlog will become the lost transaction(s)).
Simulate a crash (note that in a replicated environment, in addition
to the shared memory segment for the database region, there is also
one for the journal pool; also both the mumps and mupip processes
will need to be terminated):</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Set ^X=^X_" Backlog "_$H</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>926 Backlog 60347,52517</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">ZSYstem "mupip replicate -source -showbacklog"</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>1 : backlog number of transactions written to journal pool and yet to be sent by the source server</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>2 : sequence number of last transaction written to journal pool</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>1 : sequence number of last transaction sent by source server</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">ZSYstem "mupip replicate -source -checkhealth"</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>PID <font color="#ff00ff">924</font> Source server is alive</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">ZSYstem "ipcrm -m <font color="#ff00ff">4653056</font> -m <font color="#ff00ff">4685825</font> ; kill -9 <font color="#ff00ff">924</font> <font color="#ff00ff">926</font>"</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>Killed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ ipcs -m</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>------ Shared Memory Segments --------</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>key        shmid      owner      perms      bytes      nattch    status      </b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ ps -ef | grep -E \(mupip\)\|\(mumps\)</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ </b></font></font></pre>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Bring
Ghanzi up to take over as the new primary, keeping the application
available, and perform some updates to simulate activity. Also,
verify that the backlog in Honolulu really is a backlog, and was not
replicated to Ghanzi.</font></font></p>
 
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Ghanzi$ <font color="#ff0000">./primary_start</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Ghanzi$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>926</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Set ^X=$J_" Ghanzi "_$H</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>974 Ghanzi 60347,52928</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;</b></font></font></pre>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Now
simulate a recovery of the system in Honolulu. When it comes up, use
the <b><font size="2"><font face="Nimbus Mono L, monospace">-fetchresync</font></font></b>
qualifier to have Honolulu query Ghanzi so that it can roll back the
lost transactions.</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">mupip journal -rollback -backward -fetchresync=3355 -losttrans=Lost_Trans_Report_`date +%Y%m%d%H%M%S`.txt "*"</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJNLSTAT, Initial processing started at Thu Mar 23 14:44:16 2006</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJPOOLRNDWNSUC, Jnlpool section (id = 688129) belonging to the replication instance /ramdisk/home/dsl/myVistA/dualsite/Honolulu/mumps.repl successfully rundown</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-SEMREMOVED, Semaphore id 688129 removed from the system</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJNLSTAT, FETCHRESYNC processing started at Thu Mar 23 14:44:16 2006</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Thu Mar 23 14:44:16 2006 : Waiting for a connection...</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Thu Mar 23 14:44:20 2006 : Connection established</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Thu Mar 23 14:44:20 2006 : Received RESYNC SEQNO is 2</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJNLSTAT, Backward processing started at Thu Mar 23 14:44:20 2006</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-RESOLVESEQNO, Resolving until sequence number 0x0000000000000002</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJNLSTAT, Before image applying started at Thu Mar 23 14:44:20 2006</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-FILERENAME, File /ramdisk/home/dsl/myVistA/dualsite/Honolulu/mumps.mjl is renamed to /ramdisk/home/dsl/myVistA/dualsite/Honolulu/mumps.mjl_2006082143523</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJNLSTAT, Forward processing started at Thu Mar 23 14:44:20 2006</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-FILECREATE, Lost transactions extract file Lost_Trans_Report_20060323144416.txt created</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-RLBKJNSEQ, Journal seqno of the instance after rollback is 2 [0x0000000000000002]</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-S-JNLSUCCESS, Show successful</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-S-JNLSUCCESS, Verify successful</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-S-JNLSUCCESS, Rollback successful</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUJNLSTAT, End processing at Thu Mar 23 14:44:21 2006</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:<font color="#ff0000">~/myVistA/dualsite/Honolulu$ cat Lost_Trans_Report_20060323144416.txt</font> </b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GDSJEX01</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>05\60347,52517\2\926\0\2\^X="926 Backlog 60347,52517"</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ </b></font></font></pre>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Now start
Honolulu as the secondary, and note how it automatically catches up
with updates made in Ghanzi (with a possible lag of a few seconds
for Ghanzi to detect that Honolulu is up and ready to receive
updates):</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">./secondary_start</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>926</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>926</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write ^X</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>974 Ghanzi 60347,52928</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Halt</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$</b></font></font></pre>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Shut down
Honolulu and Ghanzi cleanly to end the exercise:</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Ghanzi$ .<font color="#ff0000">/primary_stop</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Thu Mar 23 14:47:17 2006 : Initiating shut down</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>Signalling shutdown immediate</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Journal pool shared memory removed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Journal pool semaphore removed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUFILRNDWNSUC, File /ramdisk/home/dsl/myVistA/dualsite/Ghanzi/mumps.dat successfully rundown</b></font></font>
<b><font face="Nimbus Mono L, monospace"><a href="mailto:dsl@box">dsl@box</a>:~/myVistA/dualsite/Ghanzi$</font></b>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>...</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$ <font color="#ff0000">./secondary_stop</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>Thu Mar 23 14:47:20 2006 : Initiating shut down</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Signalling immediate shutdown</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Receive pool shared memory removed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Receive pool semaphore removed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Thu Mar 23 14:47:21 2006 : Initiating shut down</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Signalling shutdown immediate</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Journal pool shared memory removed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Journal pool semaphore removed</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-MUFILRNDWNSUC, File /ramdisk/home/dsl/myVistA/dualsite/Honolulu/mumps.dat successfully rundown</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/dualsite/Honolulu$</b></font></font></pre><h2>
<a name="Backup|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Backup</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Backup when an
application is not running is straightforward &#8211; just copy the
database files.</font></font></p>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">Backup when an
application is operating normally, without impacting the application
(except of course for the additional IO load of the backup activity)
is easy with GT.M, and can be accomplished in two ways, one non-GT.M
and other GT.M: </font></font>
</p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">The
non-GT.M way is to use a disk mirror (e.g., RAID or SAN). Issue a
mupip freeze to momentarily freeze updates and flush updates to
disk, break the mirror; then release the freeze. After backing up
the mirror, remake it, and let it &#8220;catch up.&#8221;</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">The GT.M
way: a transaction-consistent backup of an entire multi-region
database can be accomplished with a single GT.M command: mupip
backup. There are numerous options to satisfy virtually every type
of backup need.</font></font></p>
 
</li></ul>
<h3><a name="Exercise - backup|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4">Exercise
- backup</font></font></h3>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif">Create a temporary
directory (if you don't have one already) and a subdirectory for the
backup database files, and change to the temporary directory. Create
a global directory &amp; database file, and turn journaling on (see
<a href="#Exercise%20-%20journaling%7Coutline">above</a> if you don't
remember how to do this).</font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Create a
GT.M program XYZ in file <b><font size="2"><font face="Nimbus Mono L, monospace">XYZ.m</font></font></b>
as follows (the <b><font size="2"><font face="Nimbus Mono L, monospace">Hang</font></font></b>
 
command is not strictly necessary, but is used simply to keep the
volume of data manageable in a demonstration environment that may be
operating in a &#8220;disk&#8221; with tight space constraints, such
as a USB flash drive): </font></font>
</p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>XYZ    Set (^x,^y)=0</b></font></font>
      <b><font face="Nimbus Mono L, monospace">For  Do</font></b>
      <b><font face="Nimbus Mono L, monospace">.Hang 0.1</font></b>
 
      <b><font face="Nimbus Mono L, monospace">.Tstart ()</font></b>
      <b><font face="Nimbus Mono L, monospace">.Set r=$Random(2147483646)</font></b>
      <b><font face="Nimbus Mono L, monospace">.Set ^x=^x-r</font></b>
      <b><font face="Nimbus Mono L, monospace">.Set ^y=^y+r</font></b>
      <b><font face="Nimbus Mono L, monospace">.Tcommit</font></b>
      <b><font face="Nimbus Mono L, monospace">Quit</font></b></pre>
 
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Start the
program as a background process from the shell: <b><font size="2"><font face="Nimbus Mono L, monospace"><font color="#ff0000">mumps
-run ^XYZ &lt;/dev/null &gt;&amp;/dev/null &amp;</font></font></font></b></font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Take a
backup of the entire database (a &#8220;comprehensive&#8221;
backup):</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip backup "*" backup/</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-FILERENAME, File /ramdisk/home/dsl/myVistA/tmp/mumps.mjl is renamed to /ramdisk/home/dsl/myVistA/tmp/mumps.mjl_2006083154324</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-JNLCREATE, Journal file /ramdisk/home/dsl/myVistA/tmp/mumps.mjl created for region DEFAULT with BEFORE_IMAGES</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>DB file /ramdisk/home/dsl/myVistA/tmp/mumps.dat backed up in file backup//mumps.dat</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Transactions up to 0x0000000000000287 are backed up.</b></font></font>
 
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>BACKUP COMPLETED.</b></font></font></pre>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Take a
backup of that part of the database that has changed (a &#8220;bytestream&#8221;
 
backup). Note the use of the -since=database qualifier to only
backup those database blocks that have changed since the last backup
of the entire database):</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip backup -bytestream -since=database "*" backup/mumps`date +%Y%m%d%H%M%S`.bck</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-FILERENAME, File /ramdisk/home/dsl/myVistA/tmp/mumps.mjl is renamed to /ramdisk/home/dsl/myVistA/tmp/mumps.mjl_2006083154420</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-JNLCREATE, Journal file /ramdisk/home/dsl/myVistA/tmp/mumps.mjl created for region DEFAULT with BEFORE_IMAGES</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>MUPIP backup of database file /ramdisk/home/dsl/myVistA/tmp/mumps.dat to backup/mumps20060324154420.bck</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>DB file /ramdisk/home/dsl/myVistA/tmp/mumps.dat incrementally backed up in file backup/mumps20060324154420.bck</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>5 blocks saved.</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>Transactions from 0x0000000000000287 to 0x000000000000047C are backed up.</b></font></font>
 
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>BACKUP COMPLETED.</b></font></font></pre>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Take
further bytestream backups of that part of the database that has
changed &#8211; as many as desired (note the use of the
-since=bytestream qualifier to backup only those blocjs that have
changed since the last bytestream backup):</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$  <font color="#ff0000">mupip backup -bytestream -since=bytestream "*" backup/mumps`date +%Y%m%d%H%M%S`.bck</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-FILERENAME, File /ramdisk/home/dsl/myVistA/tmp/mumps.mjl is renamed to /ramdisk/home/dsl/myVistA/tmp/mumps.mjl_2006083154449</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-JNLCREATE, Journal file /ramdisk/home/dsl/myVistA/tmp/mumps.mjl created for region DEFAULT with BEFORE_IMAGES</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>MUPIP backup of database file /ramdisk/home/dsl/myVistA/tmp/mumps.dat to backup/mumps20060324154449.bck</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>DB file /ramdisk/home/dsl/myVistA/tmp/mumps.dat incrementally backed up in file backup/mumps20060324154449.bck</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>5 blocks saved.</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Transactions from 0x000000000000047C to 0x0000000000000586 are backed up.</b></font></font>
 
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>BACKUP COMPLETED.</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip backup -bytestream -since=bytestream "*" backup/mumps`date +%Y%m%d%H%M%S`.bck</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-FILERENAME, File /ramdisk/home/dsl/myVistA/tmp/mumps.mjl is renamed to /ramdisk/home/dsl/myVistA/tmp/mumps.mjl_2006083154508</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-JNLCREATE, Journal file /ramdisk/home/dsl/myVistA/tmp/mumps.mjl created for region DEFAULT with BEFORE_IMAGES</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>MUPIP backup of database file /ramdisk/home/dsl/myVistA/tmp/mumps.dat to backup/mumps20060324154508.bck</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>DB file /ramdisk/home/dsl/myVistA/tmp/mumps.dat incrementally backed up in file backup/mumps20060324154508.bck</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>5 blocks saved.</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Transactions from 0x0000000000000586 to 0x000000000000062C are backed up.</b></font></font>
 
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>BACKUP COMPLETED.</b></font></font></pre>
<ul>
 
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Stop the
process updating the database, take a final backup, and note the
values of ^x and ^y (and verify that they still sum to zero). After
the final restore, we will verify that the values restored from the
backup is the same as these values. As before, note the use of
<font color="#ff00ff">fuschia</font> to idenfy process ids that will
change from machine to machine and run to run:</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">ps -ef | grep mumps</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl      <font color="#ff00ff">1183</font>  1180  0 15:42 ttyp1    00:00:01 mumps -run ^XYZ</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip stop</font> <font color="#ff00ff">1183</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>STOP issued to process <font color="#ff00ff">1183</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-F-FORCEDHALT, Image HALTed by MUPIP STOP</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>[1]+  Exit 241                mumps -run ^XYZ &lt;/dev/null &gt;/dev/null</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip backup -bytestream -since=bytestream "*" backup/mumps`date +%Y%m%d%H%M%S`.bck</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-FILERENAME, File /ramdisk/home/dsl/myVistA/tmp/mumps.mjl is renamed to /ramdisk/home/dsl/myVistA/tmp/mumps.mjl_2006083154529</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>%GTM-I-JNLCREATE, Journal file /ramdisk/home/dsl/myVistA/tmp/mumps.mjl created for region DEFAULT with BEFORE_IMAGES</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>MUPIP backup of database file /ramdisk/home/dsl/myVistA/tmp/mumps.dat to backup/mumps20060324154619.bck</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>DB file /ramdisk/home/dsl/myVistA/tmp/mumps.dat incrementally backed up in file backup/mumps20060324154619.bck</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>5 blocks saved.</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Transactions from 0x000000000000062C to 0x00000000000006EC are backed up.</b></font></font>
 
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>BACKUP COMPLETED.</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write "^x+^y=",^x,"+",^y,"=",^x+^y,! Halt</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>^x+^y=-1879255318702+1879255318702=0</b></font></font></pre>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Notice
that each backup create a new journal file generation, and there is
a chain of journal files. After a successful backup, older
generations of journal files are no longer needed in a single site
operating environment. In a dual site environment, primary journal
files could be needed until the completion of a successful backup on
the secondary.</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">ls -l</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-r--    1 dsl      staff        122 Mar 24 14:35 XYZ.m</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-r--    1 dsl      staff        825 Mar 24 15:42 XYZ.o</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>drwxrwxr-x    2 dsl      staff        4096 Mar 24 15:46 backup</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-rw-    1 dsl      staff      169472 Mar 24 15:47 mumps.dat</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-r--    1 dsl      staff        1024 Mar 24 14:32 mumps.gld</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-rw-    1 dsl      staff        2368 Mar 24 15:46 mumps.mjl</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-rw-    1 dsl      staff      116584 Mar 24 15:43 mumps.mjl_2006083154324</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-rw-    1 dsl      staff      91288 Mar 24 15:44 mumps.mjl_2006083154420</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-rw-    1 dsl      staff      49880 Mar 24 15:44 mumps.mjl_2006083154449</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-rw-    1 dsl      staff      32280 Mar 24 15:45 mumps.mjl_2006083154508</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-rw-    1 dsl      staff      36608 Mar 24 15:45 mumps.mjl_2006083154529</b></font></font></pre>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">To
simulate restoring and recovering the database, first delete the
database and journal files. Then &#8220;restore&#8221; the backup of
the entire database by copying it in. Check the values of <b><font size="2"><font face="Nimbus Mono L, monospace">^x</font></font></b>
 
and <b><font size="2"><font face="Nimbus Mono L, monospace">^y</font></font></b>
to ensure that they add to zero.</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">rm mumps.dat mumps.mjl*</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">ls -l</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-r--    1 dsl      staff        122 Mar 24 14:35 XYZ.m</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-r--    1 dsl      staff        825 Mar 24 15:42 XYZ.o</b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>drwxrwxr-x    2 dsl      staff        4096 Mar 24 15:46 backup</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>-rw-rw-r--    1 dsl      staff        1024 Mar 24 14:32 mmumps.gld</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">cp -p backup/mumps.dat .</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write "^x+^y=",^x,"+",^y,"=",^x+^y,! Halt</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>^x+^y=-725290066926+725290066926=0</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$</b></font></font></pre>
 
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Restore
the each bytestream backup, and verify that the absolute values of
<b><font size="2"><font face="Nimbus Mono L, monospace">^x</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">^y</font></font></b>
increase, but they always sum to zero (because of the use of
transaction processing). After the last backup is restored, note
that the values of <b><font size="2"><font face="Nimbus Mono L, monospace">^x</font></font></b>
and <b><font size="2"><font face="Nimbus Mono L, monospace">^y</font></font></b>
 
are the same as they were in the original database when the process
running routine <b><font size="2"><font face="Nimbus Mono L, monospace">XYZ</font></font></b>
was stopped.</font></font></p>
</li></ul>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip restore mumps.dat backup/mumps20060324154420.bck</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>RESTORE COMPLETED</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>7 blocks restored</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write "^x+^y=",^x,"+",^y,"=",^x+^y,! Halt</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>^x+^y=-1233626317102+1233626317102=0</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip restore mumps.dat backup/mumps20060324154449.bck</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>RESTORE COMPLETED</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>7 blocks restored</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write "^x+^y=",^x,"+",^y,"=",^x+^y,! Halt</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>^x+^y=-1502392564483+1502392564483=0</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip restore mumps.dat backup/mumps20060324154508.bck</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>RESTORE COMPLETED</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>7 blocks restored</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write "^x+^y=",^x,"+",^y,"=",^x+^y,! Halt</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>^x+^y=-1670563955262+1670563955262=0</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mupip restore mumps.dat backup/mumps20060324154619.bck</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>RESTORE COMPLETED</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>5 blocks restored</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write "^x+^y=",^x,"+",^y,"=",^x+^y,! Halt</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>^x+^y=-1879255318702+1879255318702=0</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ </b></font></font></pre><h2>
<a name="Potential surprises|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="4"><i>Potential
surprises</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">If you are
used to other M implementations, here are examples of things you may
be used to that you won't find in GT.M:</font></font></p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif">Job Examine &#8211;
there is not a built in function. But the functionality is easy to
set up if you need it, e.g., see <a href="http://sourceforge.net/docman/display_doc.php?docid=19563&amp;group_id=11026">GT.M
Job Examine / System Status How To</a> (or <a href="file:///home/ivaldes/.gvfs/GT.MAcculturation0.4.iso/20060324JobExamineSystemStatusHowTo.html">local
copy</a>).</font></p>
 
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Kill &#8211;
there is no setting to prevent a Kill in a process that has update
permission to a database file from killing an entire global
variable.</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">Break &#8211;
there is no concept of a &#8220;production&#8221; mode in which
Break can be turned off.</font></font></p>
</li></ul>
<h2><a name="Exploit integration with underlying operating system|outline"></a>
 
<font face="Nimbus Sans L, sans-serif"><font size="4"><i>Exploit
integration with underlying operating system</i></font></font></h2>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">If you need
functionality that is not in GT.M, use it from the underlying
operating system. For example, you can use <b><font size="2"><font face="Nimbus Mono L, monospace">Xdialog</font></font></b>
for dialog boxes for user interaction. In a temporary directory:</font></font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -dir</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Set file="/tmp/gtm"_$Job_".tmp"</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">ZSYstem "Xdialog --calendar ""Choose date"" 0 0 0 0 0 &gt;&amp;"_file</font></b></font></font><img src="index_files/20060324Xdialog.jpg" name="graphics6" align="right" border="0" height="246" width="280"></pre><p>
 
<font face="Nimbus Roman No9 L, serif"><font size="3">At this time, an
Xdialog calendar prompt pops up, and you can choose a date. You can
choose a date, press OK, and read that date into GT.M:</font></font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Open file Use file Read date</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Use $Principal Write date</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>13/03/2006</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Close file:Delete</font></b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">You can use
$ZCMdline to get command line parameters:</font></font></p>
<pre><font face="Nimbus Mono L, monospace"><font size="2"><b>dsl@box:~/myVistA/tmp$ <font color="#ff0000">mumps -dir Passing command lines to GT.M programs is really cool</font></b></font></font>
 
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;<font color="#0000ff">Write $ZCMdline</font></b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>Passing command lines to GT.M programs is really cool</b></font></font>
<font face="Nimbus Mono L, monospace"><font size="2"><b>GTM&gt;</b></font></font></pre><p>
<font face="Nimbus Roman No9 L, serif"><font size="3">You can freely
mix routines written in C with routines written in M (caveat: a few
restrictions apply because the GT.M runtime environment in each
process includes a high performance database engine; refer to the
documentation for details). </font></font>
</p>
<h1><a name="7.In conclusion|outline"></a><font face="Nimbus Sans L, sans-serif"><font size="5">In
conclusion</font></font></h1>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">I hope that
this write up has been useful to you. Please think about the
following and send me e-mail.. Thank you very much. </font></font>
</p>
<ul>
<li><p><font face="Nimbus Roman No9 L, serif"><font size="3">What did
you like about this GT.M Acculturation CD? What are some things that
it accomplished well for you? In what way(s), if any, did it exceed
your expectations?</font></font></p>
 
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">What are
some things that you did not care for? In what way(s) did it fall
short? How can it be improved?</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">What is
your background with M?</font></font></p>
</li><li><p><font face="Nimbus Roman No9 L, serif"><font size="3">What is
your background with GT.M?</font></font></p>
</li></ul>
<p><font face="Nimbus Roman No9 L, serif"><font size="3">If there is
anything that you would like to share to help make GT.M, or this
Acculturation CD more useful to you, please let me know. </font></font>
</p>
<p><font face="Nimbus Roman No9 L, serif">K.S. Bhaskar<br>VP, Product
Manager<br>Fidelity National Information Services,
Inc.<br><a href="mailto:ks.bhaskar@fnf.com">ks.bhaskar@fnf.com</a><br>+1
(610) 578-4265 </font>
 
</p>
<p><br><br>
</p>
</body></html>

Revision as of 15:05, 3 February 2010

The GT.M Acculturation live CD is a Linux live CD aimed at those who would like to learn about GT.M. It is a tutorial with examples and exercises focusing on the differences between GT.M and other implementations of M. In view of the fact that these differences are mostly in the area of administration and operations, reflecting GT.M's emphasis as a platform for secure, mission critical, production applications, that is the focus.

It has been used as the basis for several of the GT.M workshops at VistA Community Meetings.

It is available for download from the WorldVistA Sourceforge Project Page.

Retrieved from "https://vistapedia.com/index.php?title=GT.M_Acculturation_Live_CD&oldid=6720"