Installation How To VistA GT.M Ubuntu Linux

= 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 -

gtm_dist=/usr/local/gtm export gtm_dist PATH=$PATH:$gtm_dist alias gtm='mumps -dir'
 * LM: For GT.M
 * 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:

gtmroutines="/home/vista/jan06/r $gtm_dist ." export gtmroutines gtmgbldir=/home/vista/jan06/database export gtmgbldir
 * LM: For VistA
 * 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 ? ← Input device: : /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. If this 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.

cd /home/vista $gtm_dist/mumps -r GTMLNX^XWBTCPM
 * 1) !/bin/bash

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

gtmrpcb stream tcp nowait vista /home/vista/rpcb-in
 * 1) GTM - VistA RPC Broker
 * 1) End GTM VistA RPC Broker
 * 1) 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 Applications, 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).