Installation How To VistA GT.M Ubuntu Linux

From VistApedia
Revision as of 14:17, 22 February 2012 by NeilArmstrong (talk | contribs) (Added glossary link to Application~)
Jump to: navigation, search

VistA under GT.M for Linux (Ubuntu)

Note: This is now obsolete: Use Astronaut Installers instead which have a .deb package.

Contributed by Lloyd Milligan in March 2005

Chapter 1 – Ubuntu Installation Notes

[Version 5.10 "Breezy Badger"]

1) Ubuntu 5.10 auto-detects monitor attributes. No additional action was necessary. (Previous version 5.04 "Hoary Hedgehog" did not auto-detect monitor attributes.)

2) Mozilla Firefox: Enter about:config in address bar.

Locate the line that starts with:

	network.dns.disableIPv6

and change the value to true.

Reference: http://ubuntuforums.org/showthread.php?t=6841.


3) SSH server is not automatically installed.

	$ sudo apt-get install openssh-server

4) The Internet Superserver (inetd) is not automatically installed in Breezy Badger. This will be used to start the VistA RPC Broker Listener as an OS service (Chapter 4).

 
	$ sudo apt-get install netkit-inetd

Reference: http://www.ubuntuforums.org/archive/index.php/t-74072.html.


Chapter 2 - GT.M Installation Notes

1) From http://sourceforge.net/projects/sanchez-gtm find latest GT.M release version 5.0.000C (December 12, 2005)

2) Either:

2a) Download GT.M installation archive to a convenient temporary location on the Linux server

or: 2b) Download to a Windows folder and use WinSCP or another method to copy the archive to Ubuntu Linux.

3) Do the following as superuser:

   a) Uncompress archive to a temporary directory, e.g.

 $ sudo tar xovf /home/gtmuser/gtm-5p0p000c/gtm_V50000C_linux_i386_pro.tar.tar
./
./CHK2LEV.m
./CHK2LEV.o
./CHKOP.m
Etc.
   b) Install (configure) GT.M, answering questions as follow (← indicates “Enter” key):

lloydm@ubuntu:/tmp/gtm-tmp$ sudo sh configure
                     MUMPS Configuration Script
c. 1993-2005 Fidelity Information Services, Inc. Use of this software
is restricted by the provisions of your software license agreement.

What account should own the files? (bin) ←
In what directory should GT.M be installed? /usr/local/gtm

Directory /usr/local/gtm does not exist. Do you wish to create it as part of
this installation? (y or n) y

Enter the RC node ID of the GT.CM server, if desired (42): ←

Installing GT.M....


All of the GTC MUMPS routines are distributed with uppercase names.
You can create lowercase copies of these routines if you wish, but
to avoid problems with compatibility in the future, GTC suggests that
you keep only the uppercase versions of the files.

Do you want uppercase and lowercase versions of the MUMPS routines? (y or n)n

Compiling all of the MUMPS routines. This may take a moment.


GTM>
%GDE-I-GDUSEDEFS, Using defaults for Global Directory
        /usr/local/gtm/gtmhelp.gld

GDE>
%GDE-I-VERIFY, Verification OK

%GDE-I-GDCREATE, Creating Global Directory file
        /usr/local/gtm/gtmhelp.gld

GTM>
%GDE-I-GDUSEDEFS, Using defaults for Global Directory
        /usr/local/gtm/gdehelp.gld

GDE>
%GDE-I-VERIFY, Verification OK

%GDE-I-GDCREATE, Creating Global Directory file
        /usr/local/gtm/gdehelp.gld

Installation completed. Would you like all the temporary files
removed from this directory? (y or n) y

5) Define gtm_dist variable and PATH to MUMPS executable for all (bash) users.

lloydm@ubuntu:/tmp$ sudo vi /etc/profile

Insert near the end of /etc/profile and before the “export PATH” line -

  1. LM: For GT.M

gtm_dist=/usr/local/gtm export gtm_dist PATH=$PATH:$gtm_dist alias gtm='mumps -dir'

  1. LM: End insert

export PATH

6) Instructions for defining gtmroutines and gtmgbldir variables will be given in the next chapter.


Chapter 3 - VistA Installation Notes

1) Determine a suitable location for routine and global directories. For example,

	a. Create a VistA user (vista).
	b. Create subdirectories for current FOIA distribution.

vista@ubuntu:~$ mkdir jan06
vista@ubuntu:~$ cd jan06
vista@ubuntu:~/jan06$ mkdir g
vista@ubuntu:~/jan06$ mkdir r

2) Download or use WinSCP or another method to transfer archive containing VistA globals and routines (VistA-routines-globals-as-TXT.zip).

3) Unzip archive to g directory. For example,

vista@ubuntu:~/jan06$ ls
database  g  r  VistA-routines-globals-as-TXT.zip
vista@ubuntu:~/jan06$ cd g
vista@ubuntu:~/jan06/g$ unzip ../VistA-routines-globals-as-TXT.zip
Archive:  ../VistA-routines-globals-as-TXT.zip
  inflating: AFJ.zwr
  inflating: %Z.zwr
  inflating: %ZIS.zwr
Etc.

4) Move VistA.rtn to ../r directory.

vista@ubuntu:~/jan06/g$ mv VistA.rtn ../r/VistA.rtn

5) Set GT.M routine and global variables to VistA directory locations (all users default).

	Edit /etc/profile as superuser:

lloydm@ubuntu:~$ sudo vi /etc/profile
Password:

Insert the following near the end:

# LM: For VistA
gtmroutines="/home/vista/jan06/r $gtm_dist ."
export gtmroutines
gtmgbldir=/home/vista/jan06/database
export gtmgbldir
# LM: End insert

6) Logout and then log back in to acquire gtmroutines and gtmgbldir settings.

7) Define VistA database directory:

vista@ubuntu:~$ mumps -r GDE
%GDE-I-GDUSEDEFS, Using defaults for Global Directory
        /home/vista/jan06/database.gld

GDE> change -s DEFAULT -f=/home/vista/jan06/database
GDE> exit
%GDE-I-VERIFY, Verification OK

%GDE-I-GDCREATE, Creating Global Directory file
        /home/vista/jan06/database.gld

8) Create the database and adjust parameters:

vista@ubuntu:~$ mupip create && dse change -f -key_max=255 -rec=4096
Created file /home/vista/jan06/database.dat

File    /home/vista/jan06/database.dat
Region  DEFAULT

9) Change to ../g directory and load globals into the database:

vista@ubuntu:~/jan06/g$ for i in *.zwr ; do mupip load $i ; done
. . .
. . .  << Long list omitted >>
. . .
VISTA GLOBALS
Cache 13-Jan-2006 17:13:55 ZWR
LOAD TOTAL              Key Cnt: 152  Max Subsc Len: 14  Max Data Len: 226
Last LOAD record number: 154

vista@ubuntu:~/jan06/g$

10) Change to ../r directory and convert routine save file to Linux (Unix) format:

vista@ubuntu:~/jan06/r$ perl -pi -e 's/\r\n/\n/;' VistA.rtn

11) Import routines – Important: Include final ‘/’ in Output directory path.

vista@ubuntu:~$ gtm

GTM>D ^%RI

Routine Input Utility - Converts RO file to *.m files.

Formfeed delimited <No>? ←
Input device: <terminal>: /home/vista/jan06/r/VistA.rtn

Saved by %RO from ^^c\platinum\ on 13-Jan-2006  5:25 PM
Export of 23366 routines from namespace ^^c:\platinum\

Output directory : /home/vista/jan06/r/
. . .
. . .
ZUGTM     ZUMSM     ZUMSQ     ZUONT     ZUSET     ZUVXD

Restored 1945680 lines in 23366 routines.
GTM>

12) Do ^ZTMGRSET to configure VistA Kernel for Linux.

vista@ubuntu:~$ gtm

GTM>D ^ZTMGRSET


ZTMGRSET Version 8.0 **34,36,69,94,121,127,136,191,275**
HELLO! I exist to assist you in correctly initializing the current account.

THIS MAY NOT BE THE MANAGER UCI.
 I think it is VAH,ROU. Should I continue anyway? N//Y
I think you are using GT.M (Unix)
Which MUMPS system should I install?

1 = VAX DSM(V6), VAX DSM(V7)
2 = MSM-PC/PLUS, MSM for NT or UNIX
3 = OpenM for NT, Cache/NT, Cache/VMS
4 = Datatree, DTM-PC, DT-MAX
5 = MVX,ISM VAX
6 = ISM (UNIX, Open VMS)
7 = GT.M (VMS)
8 = GT.M (Unix)
System: 8

I will now rename a group of routines specific to your operating system.
Routine: ZOSVGUX      Loaded, Saved as %ZOSV
Routine: ZTBKCGUX     Missing
. . .
. . .  (Ignore numerous compile errors.  %-routines include non-GT.M code.)
. . .
Routine: ZTRDEL       Loaded, Saved as %ZTRDEL
Routine: ZTMOVE       Loaded, Saved as %ZTMOVE
Want to rename the FileMan routines: No//Y
Setting ^%ZIS('C')

Now, I will check your % globals...........
ALL DONE
GTM>

Chapter 4 - VistA Post-Install Steps

These notes describe GT.M-specific setup steps that may be required after completing the GT.M VistA installation.

1) HFS Device. The VistA DEVICE file has the following entry:

NAME: HFS                               $I: USER$:[TEMP]TMP.DAT
  ASK DEVICE: YES                       LOCATION OF TERMINAL: Host File Server
  ASK HOST FILE: YES                    OPEN PARAMETERS: "WNS"
  SUBTYPE: P-OTHER                      TYPE: HOST FILE SERVER

Note that this entry defines a Cache-for-VMS host file DEVICE.  
The corresponding entry for GT.M should resemble the following:

NAME: HFS                               $I: /tmp/temp.txt
  LOCATION OF TERMINAL: Host File Server
  ASK HOST FILE: YES
  OPEN PARAMETERS: (NEWVERSION:VARIABLE:NOREADONLY)
  SUBTYPE: P-OTHER                      TYPE: HOST FILE SERVER

2) The TASKMAN SITE PARAMETER entry refers to BOX-VOLUME pair VISTA:PLATINUM. However,

GTM>D GETENV^%ZOSV

GTM>W Y
VAH^ROU^localhost^ROU:localhost

Edit the File 14.7 entry to agree with the value in “^”-piece 4 of variable Y above.

BOX-VOLUME PAIR: ROU:localhost          LOG TASKS?: NO
  DEFAULT TASK PRIORITY: 7              SUBMANAGER RETENTION TIME: 0
  TASKMAN JOB LIMIT: 100                TASKMAN HANG BETWEEN NEW JOBS: 1
  MODE OF TASKMAN: GENERAL PROCESSOR    OUT OF SERVICE: NO
  MIN SUBMANAGER CNT: 1

3) Optionally kill the ^%ZTSCH global. Start TaskMan and verify that it is running.

GTM>K ^%ZTSCH

GTM>D START^ZTMB

Ignore numerous compile errors associated with code for other M platforms.  
To verify TaskMan status at this point, use the Monitor TaskMan option.

4) Start the traditional-style RPC Broker Listener. Again ignore compile errors.


GTM>D STRT^XWBTCP(9210)
Start TCP Listener...
. . .
Checking if TCP Listener has started...
TCP Listener started successfully.

5) Add self as user with appropriate keys, etc.

6) As of the January 2006 FOIA VistA release, routine ^%ZISF is not created by ^ZTMGRSET. Explicitly copy ZISFDTM.m to _ZISF.m.

vista@ubuntu:~/jan06/r$ cp ZISFGTM.m _ZISF.m

Note that step 6 is required in order to load KIDS files from the host file system.

6a)  Modify routine ^%ZOSV2 to translate “%” to “_” in percent file names, 
for consistency.  Note that modern Linux file systems support the “%” character 
in file names.  However, parts of GT.M and VistA assume the “_” substitution.

SAVE+2
        S $ETRAP="S $ECODE="""" Q",RN=$TR(RN,"%","_") ;SIS/LM %->_ 

DEL+3
        S %I=$I,%DIR=$$RTNDIR^%ZOSV,RN=$TR(RN,"%","_") ;SIS/LM %->_



The following steps pertain to installing Sea Island Systems RPC-Broker 
based GUI tools http://www.seaislandsystems.com/Downloads/index.html.  
These GUI tools facilitate performing subsequent steps in which VistA 
routines will be edited, and so forth.

7) Copy routine and global editor KIDS to a convenient location.

vista@ubuntu:~$ ls kids
vista_global_utilities_1p0.kid  ZMEDIT1p1.KID

     Convert these files to Unix (Linux) format:

vista@ubuntu:~$ perl -pi -e 's/\r\n/\n/;' ZMEDIT1p1.KID
vista@ubuntu:~$ perl -pi -e 's/\r\n/\n/;' vista_global_utilities_1p0.kid

8) Load and install these files. For example,

Select OPTION NAME: XPD MAIN       Kernel Installation & Distribution System

Select Kernel Installation & Distribution System Option: Installation

Select Installation Option: Load a Distribution
Enter a Host File: /home/vista/kids/ZMEDIT1p1.KID

KIDS Distribution saved on Feb 24, 2004@13:32:56
Comment: RPC Broker-based M Routine Editor RPC's with patch 1

This Distribution contains Transport Globals for the following Package(s):
   ZMEDIT 1.1
Distribution OK!

Want to Continue with Load? YES//←
Loading Distribution...

   ZMEDIT 1.1
Use INSTALL NAME: ZMEDIT 1.1 to install this Distribution.

Install file print follows:

PACKAGE: ZMEDIT 1.1     Mar 03, 2006 10:12 am                         PAGE 1
                                             COMPLETED           ELAPSED
-------------------------------------------------------------------------------
STATUS: Install Completed                 DATE LOADED: MAR 03, 2006@10:04:52
INSTALLED BY: MILLIGAN,LLOYD
NATIONAL PACKAGE:

INSTALL STARTED: MAR 03, 2006@10:05:27       10:05:27

ROUTINES:                                    10:05:27

REMOTE PROCEDURE                             10:05:27

INSTALL QUESTION PROMPT                                               ANSWER

XPI1   Want KIDS to INHIBIT LOGONs during the install                 NO
XPZ1   Want to DISABLE Scheduled Options, Menu Options, and Protocols NO
MESSAGES:

 Install Started for ZMEDIT 1.1 :
               Mar 03, 2006@10:05:27

Build Distribution Date: Feb 24, 2004

 Installing Routines:
               Mar 03, 2006@10:05:27

 Installing PACKAGE COMPONENTS:

 Installing REMOTE PROCEDURE
               Mar 03, 2006@10:05:27

 Updating Routine file...

 Updating KIDS files...

 ZMEDIT 1.1 Installed.
               Mar 03, 2006@10:05:27

 No link to PACKAGE file

 NO Install Message sent

9) Test (traditional-style callback) RPC Broker connectivity using Sea Island Systems GUI tools or any RPC Broker client that has been configured on the GT.M VistA server to accept client connections.

See example, next page.
 
Systems Status Installation

The following steps install and configure the “System Status for GT.M” 
[[application~|Application]].   If this [[application~|Application]] will not be installed, proceed to 
step 12 to configure the direct-connect RPC broker.

10) Copy the file siss0p3-gtm.kid or current version to a convenient location. Then load and install this Application.

Select OPTION NAME: XPD MAIN       Kernel Installation & Distribution System

Select Kernel Installation & Distribution System Option: Installation

Select Installation Option: Load a Distribution
Enter a Host File: /home/vista/kids/siss0p3-gtm.kid

KIDS Distribution saved on Apr 02, 2004@10:11:35
Comment: System Status for GT.M

This Distribution contains Transport Globals for the following Package(s):
   SISS SYSTEM STATUS 0.3
Distribution OK!

Want to Continue with Load? YES//←
Loading Distribution...

   SISS SYSTEM STATUS 0.3
Use INSTALL NAME: SISS SYSTEM STATUS 0.3 to install this Distribution.

(Install log omitted)

11) Follow the instructions in the document “System Status Installation Instructions.doc” to install calls to the System Status registration code in standard VistA routines. Note that it is convenient to use the GUI editor “M Edit 2000” to enter these changes.

Note that TaskMan and RPC Broker Listener will have to be restarted after installing registration hooks. Also, do not install hooks to VistALink Listener until the GT.M version has been installed and verified.

Save routine ^ZSS as ^%SS. The easiest way to do this is to load ZSS into M Edit 2000 and then “Save as” %SS. However, if the GUI routine editor is not installed copy the ZSS.m file to _SS.m and then zlink it.

Test the System Status Application.

Direct-connect RPC Broker installation

12) Perform the following steps: Note that some steps may vary slightly for other Linux distributions.

	A. Create a script named rpcb-in and place in the vista home directory.

#!/bin/bash
cd /home/vista
$gtm_dist/mumps -r GTMLNX^XWBTCPM
#

	Assign “execute” access permission to this script file and confirm setting.

vista@ubuntu:~$ chmod +x rpcb-in
vista@ubuntu:~$ ls -l rpcb-in
-rwxr-xr-x  1 vista vista 65 2006-03-03 13:38 rpcb-in

B. Create a service named gtmrpcb and place in /etc/services as follows:

bacula-sd       9103/tcp                        # Bacula Storage Daemon
bacula-sd       9103/udp
gtmrpcb         9250/tcp                        # GT.M VistA RPC Broker
amanda          10080/tcp                       # amanda backup services
amanda          10080/udp


C. Configure this service for automatic startup as follows:

lloydm@ubuntu:~$ sudo cp /etc/inetd.conf /etc/inetd.conf.backup 
lloydm@ubuntu:~$ sudo vi /etc/inetd.conf 
Password: 

#:RPC: RPC based services

# GTM - VistA RPC Broker
#
gtmrpcb stream tcp nowait vista /home/vista/rpcb-in
#
# End GTM VistA RPC Broker
#

D. Restart the inetd Internet Superserver.

lloydm@ubuntu:~$ sudo /etc/init.d/inetd restart
 * Restarting internet superserver...                                    [ ok ]

Confirm that the gtmrpcb service has started.  
From [[Application~|Application]]s, System Tools, select Network Tools.  
In the Devices tab select the appropriate network device 
from the dropdown list, e.g. “Ethernet Interface (eth0)”.  
In the Netstat tab select “Active Network Services” and click the Netstat button.


E. Modify routines ^XWBTCPM and ^%ZOSV as follows:

	Routine ^XWBTCPM –

GTMLNX	;From Linux xinetd script
	D ESET
	;GTM specific code
	S @("$ZINTERRUPT=""I $$JOBEXAM^ZU($ZPOSITION)""")
	;S XWBTDEV=$P U XWBTDEV:(NOWRAP:RECORDSIZE=512)
	S XWBTDEV=$P U XWBTDEV:(NOWRAP:NODELIMITER) ;SIS/LM - From Bhaskar
	G CONNTYPE
	;

Modify routine ^%ZOSV, adding the following SHARELIC subroutine to the end of the routine, provided it does not already exist.

SHARELIC(%)	;
	Q
	;

F. Test the direct connect RPC Broker using a client that supports the new-style connection, such as the CPRS GUI version 1.0.25.42.

13. [Optional] Install VPE for GT.M, i.e. VPE version 12 or higher.

14. [Optional] Install modified VistALink routines – (http://www.seaislandsystems.com/Downloads/VistALink/) VistALink connection via an operating system service listener is unsupported in the January 2006 FOIA version of routine ^XWBTCPM.

;I XWB["???" G VISTALINK

The above line is commented-out and tag VISTALINK does not exist in the routine. Similarly the VistALink (internal) listener ^XOBVTCPL has not been modified to run in the GT.M environment. In order to make VistALink work under GT.M it is necessary to use modified ^XOBV* routines such as those posted at the above link (file name xobv-gtm.ro). Instructions for backing up FOIA VistALink routines and installing the modified routines are provided in the file “VistALink ReadMe.txt” [aka ReadMe.txt].

The final step in installing VistALink modified routines is to start the listener and verify that it is running.

GTM>JOB LISTENER^XOBVTCPL(8001)

GTM>[ctrl-z pressed here]
[1]+  Stopped                 mumps -dir
vista@ubuntu:~$ lke show all

DEFAULT
^%ZIS(8994.171,RPCB Listener,ROU,VAH,ROU:localhost,9210)
                         Owned by PID= 8458 which is an existing process
^%ZTSCH(SUBLK,ROU:localhost,8408)
                         Owned by PID= 8408 which is an existing process
^XOB(18.01,VistALink Listener,ROU,VAH,ROU:localhost,8001)
                         Owned by PID= 30810 which is an existing process
vista@ubuntu:~$ fg

Once the VistALink listener is confirmed to be running by its 
entry in the lock table, the swing tester can be used.


If the VistALink Sign On form displays, the connection is sound. To test full functionality run the Test/Demo Application to retrieve word processing data from the GT.M VistA server.

Finally, add the system status hook for VistALink if it is not already present in the modified ^XOBVTCPL routine (see paragraph 11 in the current document).