From b4d4dc236c8a48f713a7b43b5ade0b6d35c75fb6 Mon Sep 17 00:00:00 2001 From: Christopher Edwards Date: Wed, 15 Jan 2014 11:12:13 -0500 Subject: [PATCH] Update GT.M installation instructions following best practices Update the user and group used for GT.M installation. Change the directory to follow GT.M debian packaging defaults. Create VistA instance using an instance owner user. Instruct users howto create a profile script for VistA using sane defaults. Instruct users how to create a db.gde script for VistA using sane defaults. Adjust line length to about 80 characters. Ensure consistency between other documents. Change-Id: Ibd8cddc03d6d54762e7bd2361db23ae7dc955d35 Suggested-by: sam.habiel@gmail.com --- Documentation/ImportGTM.rst | 130 ++++++++++------ Documentation/InstallGTM.rst | 279 ++++++++++++++++++++++------------- 2 files changed, 263 insertions(+), 146 deletions(-) diff --git a/Documentation/ImportGTM.rst b/Documentation/ImportGTM.rst index 2b1a634c3..dbc8c4ffd 100644 --- a/Documentation/ImportGTM.rst +++ b/Documentation/ImportGTM.rst @@ -10,37 +10,58 @@ instance, follow the steps found in the PrepareMComponents_ document. .. _PrepareMComponents: PrepareMComponents.rst -Import the Routines -------------------- -Importing the routines is done using the MUMPS routine named %RI. This is the MUMPS standard routine to import routines from a .RO file like what was created when the Python scripts were run. To start the GT.M instance in the terminal, simply enter the command: gtm. +Setup Environment Variables +--------------------------- +If you followed the instructions in the `Install GTM`_ document you will need to +perform the following: .. parsed-literal:: - ~/Downloads$ :usertype:`gtm` + $ :usertype:`sudo su - vista` + $ :usertype:`source etc/profile` - GTM> +This will change you to the vista user that was created during the `Install GTM`_ +steps and add all of the required GT.M environment variables into your current +session. You will have to do this every time you want to use VistA. + +Import the Routines +------------------- +Importing the routines is done using the MUMPS routine named %RI. This is the +M standard routine to import routines from a .RO file like what was created +when the Python scripts were run. To start the GT.M instance in the terminal, +simply enter the command: ``mumps -dir``. + +.. parsed-literal:: + $ :usertype:`mumps -dir` -When the \"GTM>\" prompt is there, you are in the GT.M environment and can execute the %RI routine using the command D ^%RI. + VISTA> +When the \"VISTA>\" prompt is there, you are in the M environment and you can +now execute the %RI routine using the command ``D ^%RI``, which will import the +VistA routines into the M environment. + .. parsed-literal:: - GTM> :usertype:`D ^%RI` + VISTA> :usertype:`D ^%RI` Routine Input Utility - Converts RO files to \*.m files. Formfeed delimited ? -The routines.ro file that was created earlier is not formfeed delimited, so the default option for the first prompt is the correct one to choose. When the prompt asks for an \"Input Device,\" enter the path to the routines.ro that was created in the earlier step. Our path to the routines.ro is shown entered below. +The routines.ro file that was created earlier is not formfeed delimited, so the +default option for the first prompt is the correct one to choose. When the +prompt asks for an \"Input Device,\" enter the path to the routines.ro that was +created in the earlier step. Our path to the routines.ro is shown entered below. .. parsed-literal:: Formfeed delimited ? :usertype:`` - Input Device: : :usertype:`/home/osehra/Downloads/VistA/routines.ro` + Input Device: : :usertype:`/home/osehra/VistA/routines.ro` Routines @@ -48,18 +69,24 @@ The routines.ro file that was created earlier is not formfeed delimited, so the Output directory: -This brings the prompt asking for the output directory. The path entered here should point to the r folder that was used to set the gtmroutines environment variable in the previous step. In our case, the directory was::: - - /home/osehra/Downloads/VistA/r/ +This brings the prompt asking for the output directory. The path entered here +should point to the r folder that was used in the gtmroutines environment +variable in the previous step. In our case, the directory is: -This is the location where the %RI routine will store the routines that it imports from routines.ro. + /home/vista/r/ -The "Output directory" must include the "r" subdirectory string and must finish with a slash "/". -After entering the path, the names of the routines that are imported are shown on the terminal window as they are processed. When the routine is finished, it will display the amount of lines restored and the number of routines processed, then show the GT.M prompt. +This is the location where the %RI routine will store the routines that it +extracts from routines.ro. +The "Output directory" must include the "r" subdirectory string and must finish +with a slash "/". After entering the path, the names of the routines that are +imported are shown on the terminal window as they are processed. When the +routine is finished, it will display the amount of lines restored and the +number of routines processed, then show the GT.M prompt. .. parsed-literal:: - Output directory: :usertype:`/home/osehra/Downloads/VistA/r/` + + Output directory: :usertype:`/home/vista/r/` PRCA219P PRCAACC PRCAAPI PRCAAPR PRCAAPR1 PRCAATR PRCABD PRCABIL PRCABIL1 PRCABIL2 PRCABIL3 PRCABIL4 PRCABJ PRCABJ1 PRCABJV PRCABP1 @@ -71,51 +98,60 @@ After entering the path, the names of the routines that are imported are shown o Restored 2349289 lines in 26037 routines -Once the import process finishes, you can verify if it was succesful by visiting the "Output directory" from a terminal and using the "ls" command. This command should show a large collection of "\*.m" files that were created during the import process. +Once the import process finishes, you can verify if it was succesful by +changing to the "Output directory" from a terminal and using the ``ls`` command. +This command should show a large collection of "\*.m" files that were created +during the import process. -If you expect to use this testing beyond the XINDEX capacity, there is another .ro file -that you should import. It is found in the Testing/Setup directory called \"ZTLOAD1.ro\". -It contains a new copy of the ZTLOAD1.m file which contains modifications that remove some -transaction processing code that fails only on the GT.M platform. +If you expect to use this environment beyond just using the XINDEX testing +capability, there is another .ro file that you should import. It is found in +the Testing/Setup directory called \"ZTLOAD1.ro\". It contains a new copy of +the ZTLOAD1.m file which contains modifications that improve compatibility with +the GT.M platform. .. parsed-literal:: Formfeed delimited ? :usertype:`` - Input Device: : :usertype:`/home/osehra/Downloads/VistA/Testing/Setup/ZTLOAD1.ro` + Input Device: : :usertype:`/home/osehra/VistA/Testing/Setup/ZTLOAD1.ro` Routines - Output directory: :usertype:`/home/osehra/Downloads/VistA/r/` + Output directory: :usertype:`/home/vista/r/` ZTLOAD1 Restored ... -Then, import these two routines from using the ^%RI utility. The next step is to use the newly imported ZGI routine -to import the VistA globals from the repository +Then, import these two routines from using the ^%RI utility. The next step is +to import the VistA globals from the repository: .. parsed-literal:: - GTM> :usertype:`W $$LIST^ZGI("/path-to/VistA/globals.lst")` + VISTA> H + $ :usertype:`while read global; do mupip load \"$global\"; done < /home/osehra/VistA/globals.lst` -This will take the globals.lst file and use the entries in it to tell GT.M to import that .zwr file. +This will take the globals.lst file and use the entries in it to tell GT.M to +import each .zwr file. -While the routine is running, the names of the .zwr files will be printed to the screen as they are being processed. -This is going through the OSEHRA Code base and importing all of the .zwr files from each package. The final package -imported is the \"Wounded Injured and Ill Warriors". After the last global is imported, the program will return to -the GT.M prompt. +While the import is running, the names of the .zwr files will be printed to +the screen as they are being processed. This is going through the OSEHRA Code +base and importing all of the .zwr files from each package. After the last +global is imported, the program will return to the shell prompt. Configure the VistA Environment --------------------------------- -Some configuration within the VistA environment is necessary before you have a full VistA instance. - -The text below shows the routine that need to be run to configure the VistA instance. The ZTMGRSET routine will configure the VistA instance by -renaming some system-specific routines. This is done using the command: +Some configuration within the VistA environment is necessary before you have a +full VistA instance. +The text below shows the routine that need to be run to configure the VistA +instance. The ZTMGRSET routine will configure the VistA instance by renaming +some system-specific routines. This is done using the command: .. parsed-literal:: - GTM> :usertype:`D ^ZTMGRSET` + $ :usertype:`mumps -dir` + + VISTA> :usertype:`D ^ZTMGRSET` ZTMGRSET Version 8.0 Patch level **34,36,69,94,121,127,136,191,275,355,446** @@ -207,14 +243,24 @@ renaming some system-specific routines. This is done using the command: Now, I will check your % globals........... ALL DONE - GTM> - -After loading a few routines, the configuration will ask you for the names of the box/volume pair of the system, the name of the manager\'s namespace, and the temp directory. shows the default answers being accepted for these prompts. They can be set if you need a specific name, but we used the defaults of PLA for all names and the /tmp/ directory for the system. + VISTA> -Note: The NAME OF MANAGER'S UCI, VOLUME SET and PRODUCTION (SIGN-ON) UCI,VOLUME SET prompts should be set to PLA,PLA if more than XINDEX functionality is desired. +After loading a few routines, the configuration will ask you for the names of +the box/volume pair of the system, the name of the manager\'s namespace, and +the temp directory. The screen capture above shows the default answers being +accepted for these prompts. They can be set if you need a specific name, but we +used the defaults of ``PLA,PLA`` for all names and the ``/tmp/`` directory for +the system. -It will load and save some other routines, then ask if you \"Want to rename the FileMan routines:.\" We answer this option with a YES. The routine then loads three more routines, checks the % globals, and exits. Now you are ready to start testing the OSEHRA Code base. +It will load and save some other routines, then ask if you +\"Want to rename the FileMan routines:.\" We answer this option with a YES. +The routine then loads three more routines, checks the % globals, and exits. +Now you are ready to start testing the OSEHRA Code base. -Some developers have encountered errors being displayed during the configuation process. See the second entry on the Troubleshooting Page to see if the errors are the same and find any solutions. +Some developers have encountered errors being displayed during the configuation +process. See the second entry on the `Troubleshooting Page`_ to see if the errors +are the same and find any solutions. .. _`ObtainingVistAMCode`: ObtainingVistAMCode.rst +.. _`Troubleshooting Page`: http://www.osehra.org/wiki/troubleshooting-installation-and-testing +.. _`Install GTM`: InstallGTM.rst diff --git a/Documentation/InstallGTM.rst b/Documentation/InstallGTM.rst index fe243d2a2..59707cc2a 100644 --- a/Documentation/InstallGTM.rst +++ b/Documentation/InstallGTM.rst @@ -4,52 +4,84 @@ .. role:: usertype :class: usertype -The GT.M system is available for download from SourceForge_. This will download a compressed package which will need to be extracted before proceeding. The extraction can be in a location of your choice, as during the installation process you will be able to set where the installed files will be placed. To have a common place where the GT.M files will be placed, we first create a folder within the /opt/ directory which will hold the files. The command used to create the folder is shown below. +The GT.M binary and source code are available for download from SourceForge_. +This tutorial will use the binary package for GT.M for Linux systems. There +isn't much difference between the amd64 package and the x86 package as far as +installation goes. + +Typically GT.M binary distributions follow the following convention: +gtm_V{versionid}_{platform}_{arch}_pro.tar.gz. An example using the latest +version of GT.M as of this writing is: ``gtm_V61000_linux_i686_pro.tar.gz``. + +The downloaded file is a compressed package which will need to be extracted +before proceeding. The extraction can be in a location of your choice, +as during the installation process you will be able to set where the installed +files will be placed. We will follow the following convention for where to +install GT.M: /usr/lib/fis-gtm/{Version}_{Platform}. We will use the example: +``/usr/lib/fis-gtm/V61000_i686`` + +To create this folder structure .. parsed-literal:: - $ :usertype:`sudo mkdir /opt/gtm` + $ :usertype:`sudo mkdir -p /usr/lib/fis-gtm/V61000_i686` -The next step is to unzip and untar the downloaded files, which is assumed to be in the Downloads directory. +We now need to decompress the downloaded file. The directions below assume that +the downloaded GT.M distribution is in the current folder. .. parsed-literal:: - $ :usertype:`gunzip gtm_V54002B_linus_i686_pro.tar.gz` - $ :usertype:`tar -xf gtm_V54002B_linus_i686_pro.tar` - $ :usertype:`ls` - arch.gtc GENOUT.m Libgtmshr.so - bin GENOUT.o lke - CHK2LEV.m geteuid lke.hlp + $ :usertype:`tar xzf gtm_V61000_linux_i686_pro.tar.gz` -To install GT.M, run the configure.sh file from what was just extracted. Since there will be changes made to the system, this step must be run as root or using sudo privileges. This will start an interactive series of questions which will set up the GT.M installation for the system. See below for an example of the start of the configuration script and the first prompt for the user to enter information. +To install GT.M, run the ``configure.sh`` file from what was just extracted. +Since there will be changes made to the system, this step must be run as root or +using sudo privileges. This will start an interactive series of questions +which will set up the GT.M installation for the system. See below for an +example of the start of the configuration script and the first prompt for the +user to enter information. .. parsed-literal:: - ~/Downloads$ :usertype:`sudo ./configure` + $ :usertype:`sudo ./configure` GT.M Configuration Script - Copyright 2009, 2011 Fidelity National Information Services, Inc. Use of this + Copyright 2009, 2013 Fidelity National Information Services, Inc. Use of this software is restricted by the provisions of your license agreement. What user account should own the files? (bin) -For the first two options of the configuration, the account and group that would own the GT.M files, accept the default values. At the prompt that asks \"Should execution of GT.M be restricted to this group?\" enter n, which will let all users access the GT.M environment. See below for the entries that should be set at this point in the configuration script. +For the first two options of the configuration, the account and group that +should own the GT.M files, type 'root'. At the prompt that asks +\"Should execution of GT.M be restricted to this group?\" type 'n' for no, +which will let all users access the GT.M environment. See below for the entries +that should be set at this point in the configuration script. .. parsed-literal:: - What user account should own the files? (bin) :usertype:`` - What group should own the files? (bin) :usertype:`` - Should execution of GT.M be restricted to this group? (y or n) :usertype:`N` + What user account should own the files? (bin) :usertype:`root` + What group should own the files? (bin) :usertype:`root` + Should execution of GT.M be restricted to this group? (y or n) :usertype:`n` In what directory should GT.M be installed? -The next prompt asks \"In what directory should GT.M be installed?\". Here enter a directory that will be used to hold all of the GT.M files, these instructions will put them into /opt/gtm. If the folder that you specify does not exist, you will get a message asking if you want to create it as part of the installation, you should answer yes. If you give it a path to an existing folder, it will warn you that some files may be overwritten during the installation process. Be sure to back up important files in the case that something is lost. +The next prompt asks \"In what directory should GT.M be installed?\". Here +enter a directory that will be used to hold all of the GT.M files, these +instructions will put them into ``/usr/lib/fis-gtm/V61000_i686`` as described +above. If the folder that you specify does not exist, you will get a message +asking if you want to create it as part of the installation, you should answer +'y' for yes. If you give it a path to an existing folder, it will warn you that +some files may be overwritten during the installation process. Be sure to back +up important files in the specified directory in the case that something is lost +or select a different folder. If you created the directory earlier according to +these directions you should answer 'y'. .. parsed-literal:: - In what directory should GT.M be installed? :usertype:`/opt/gtm` - Directory /opt/gtm exists. If you proceed with this intallation then - some files will be over-written. Is it okay to proceed? (y or n) :usertype:`Y` + In what directory should GT.M be installed? :usertype:`/usr/lib/fis-gtm/V61000_i686` + Directory /usr/lib/fis-gtm/V61000_i686 exists. If you proceed with this installation then + some files will be over-written. Is it okay to proceed? (y or n) :usertype:`y` -The next prompt asks the user if they want to install Unicode support. If you feel it will be necessary, it can be installed, but we will not do it in these instructions. Enter your answer to proceed. +The next prompt asks the user if they want to install UTF-8 (Unicode) support. +For VistA installations answer this question with 'n' for no. VistA doesn't +support running in a 100% UTF-8 environment. .. parsed-literal:: @@ -57,147 +89,186 @@ The next prompt asks the user if they want to install Unicode support. If you fe Should unicode support be installed? (y or n) :usertype:`n` +The next question asks if the user would like to create lowercase versions of +the utility M routines distributed with GT.M. We will answer 'n' for no to +ensure consistency in the M environment. + +.. parsed-literal:: + All of the GT.M 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, consider keeping only the uppercase versions of the files. - Do you want uppercase and lowercase version of the MUMPS routines? (y or n) - -Now that files are being installed, it asks if the user would like to keep both uppercase and lowercase versions of the MUMPS routines. We will answer no to maintain consistency between MUMPS and VistA. This will ensure that routine names for both environments are kept entirely in uppercase. - -.. parsed-literal:: - Do you want uppercase and lowercase version of the MUMPS routines? (y or n) :usertype:`n` Compiling all of the MUMPS routines. This may take a moment. - GTM> - %GDE-I-GDUSEDEFS, Using defaults for Global Directory - /opt/gtm/gtmhelp.gld - GDE> - GDE> - GDE> - %GDE-I-VERIFY, Verification OK - - %GDE-I-GDCREATE, Creating Global Directory file - /opt/gtm/gtmhelp.gld - - GDE> - GDE> - GDE> - %GDE-I-VERIFY, Verification OK - - %GDE-I-GDCREATE, Creating Global Directory file - /opt/gtm/gtmhelp.gld - -When installing GT.M in a 64 bit environment, an additional prompt will be shown that asks if you -want to remove the object files of the installed M Routines. Removing these object files will make it necessary -to add the mentioned shared library to the gtmroutines environment variable in lieu of the path to the GT.M distribution. +When installing GT.M in a 64 bit environment (amd64), an additional prompt will +be shown that asks if you want to remove the object files of the installed M +routines. Removing these object files will make it necessary to add the +mentioned shared library to the gtmroutines environment variable instead of the +path to the GT.M distribution. Using the shared library is preferred in 64 bit +environments, so we recommend answering this question with 'n' for no. .. parsed-literal:: - Object files of M routines placed in shared library /opt/gtm/libgtmutil.so - Keep original .o object files (y or n)? :usertype:`N` + Object files of M routines placed in shared library /usr/lib/fis-gtm/V61000_amd64/libgtmutil.so + Keep original .o object files (y or n)? :usertype:`n` -Now the installation of GT.M is complete. The last prompt asks if the user would like to remove the files in the current directory now that the installation is finished. Answer the prompt with a y or n with your preference. The script will then exit returning to the standard terminal prompt. +The installation of GT.M is nearly complete. The last prompt asks if the user +would like to remove the files in the current directory now that the +installation is finished. Answer the prompt with a 'y' for yes. The script will +then exit returning to the standard terminal prompt. .. parsed-literal:: Installation completed. Would you like all the temporary files removed from this directory? (y or n) :usertype:`y` - ~/Downloads$ + $ Creation of Folder Structure ---------------------------- -The next step is to create a directory that contains the folders and files needed to hold the VistA routines and globals that GT.M will use. -We will create this folder in the /Downloads directory, but this is not the only location. This location will be used as the database -directory for VistA. Make a folder called VistA. Inside of that VistA folder, create another folder named 'r' and one named 'o'. The -'r' folder will hold the routines for VistA while the 'o' folder will contain the compiled version of these routine files in a '.o' -extension. These steps are shown below. +The next step is to create a directory that will contain the folders and files +necessary for VistA. We will roughly follow the process the +`createVistaInstance.sh`_ installation script uses to create a VistA instance. -.. parsed-literal:: +We will create an instance owner user named 'vista' and create a home directory +for it: - ~/Downloads$ :usertype:`mkdir VistA` - ~/Downloads$ :usertype:`cd VistA` - ~/Downloads/VistA$ :usertype:`mkdir r` - ~/Downloads/VistA$ :usertype:`mkdir o` - ~/Downloads/VistA$ +.. parsed-literal:: -The next step is to define and create the database that will be used to hold the information needed in the VistA instance. The first step is to source the gtmprofile that was created in the installation of GT.M: source /opt/gtm/gtmprofile + $ :usertype:`sudo useradd -c "vista instance owner" -m -U vista -s /bin/bash` -Once this is done we need to alter two environment variables that were just created to point the routines and globals to where the OSEHRA code base will reside. This will set up the environment variables needed to utilize GT.M from the command line. We will be changing the gtmgbldir entry and the gtmroutines entry. These control where the GT.M instance will look for globals and routines when it is running. These entries are set using the export command from the Linux terminal. The gtmgbldir should be set to the path to the VistA folder that was created above followed by 'database'. The gtmroutines will contain a series of paths that lead to the routine and the object files. The first is the path to the 'o' and 'r' folders within the VistA folder in a special format:: +You should add yourself into the vista group by using the following command: - /path/to/o(/path/to/r) +.. parsed-literal:: -The next path points to a specific path which depends on the type of system you are using. In a 64 bit GT.M install, the path should point to the libgtmutil.so file. On a 32 bit environment, the final entry should be the path to the GT.M installation, in our case in the directory /opt/gtm/. + $ :usertype:`sudo adduser YourUserName vista` -An example usage of these commands is found below: +NOTE: you will need to logout and login again for this change to take effect. +You will need to do this before going any further. -For 32 bit: +Now we can create the required directory structure: .. parsed-literal:: - ~/Downloads$ :usertype:`source /opt/gtm/gtmprofile` - ~/Downloads$ :usertype:`export gtmgbldir=/home/osehra/Downloads/VistA/database` - ~/Downloads$ :usertype:`export gtmroutines="/home/osehra/Downloads/VistA/o(/home/osehra/Downloads/VistA/r) /opt/gtm/"` - ~/Downloads$ + $ :usertype:`sudo su vista -c "mkdir -p /home/vista/{r,r/V61000-i686,g,j,etc,etc/xinetd.d,log,tmp,bin,lib,www}"` + +The directory structure follows community developed best practices by creating +directories for the following: -And 64 bit: + * r - contains the M source code otherwise known as routines + * r/V61000-i686 - contains the compiled object files \(\*.o\) for the routines + * g - contains the M database otherwise known as globals + * j - contains the M database journal files + * etc - contains configuration files + * etc/xinetd.d - contains the configuration files for xinetd.d + * log - contains the GT.M logs + * tmp - contains temporary files created by GT.M or VistA + * bin - contains scripts used for running VistA + * lib - contains symbolic links to GT.M and other libraries + * www - contains any web applications developed for VistA + +GT.M relies upon a collection of environment variables to tell it where the +routines and globals reside and other configuration information. We will define +a profile script which will contain the correct information so you won't have +to type it every time you want to use VistA. + +We now have to create the symbolic link to the GT.M version we installed: .. parsed-literal:: - ~/Downloads$ :usertype:`source /opt/gtm/gtmprofile` - ~/Downloads$ :usertype:`export gtmgbldir=/home/osehra/Downloads/VistA/database` - ~/Downloads$ :usertype:`export gtmroutines="/home/osehra/Downloads/VistA/o(/home/osehra/Downloads/VistA/r) /opt/gtm/libgtmutil.so"` - ~/Downloads$ + $ :usertype:`sudo ln -s /usr/lib/fis-gtm/V61000_i686 /home/vista/lib/gtm` -The next step is to run the GT.M Global Directory Editor (GDE), accessed via the command: +In your favorite editor create the ``/home/vista/etc/profile`` file with the +following information: .. parsed-literal:: - ~/Downloads$ :usertype:`mumps -r GDE` - %GED-I-LOADGD, Loading Global Directory file - /home/osehra/Downloads/VistA/database.gld - %GDE-I-VERIFY, Verification OK + #!/bin/bash + export gtm_dist=/home/vista/lib/gtm + export gtm_log=/home/vista/log + export gtm_tmp=/tmp + export gtm_prompt=\"VISTA>\" + export gtmgbldir=/home/vista/g/vista.gld + export gtmroutines=\"/home/vista/r/V61000-i686(/home/vista/r) /home/vista/lib/gtm\" + export gtm_zinterrupt='I \$\$JOBEXAM^ZU(\$ZPOSITION)' + export gtm_lvnullsubs=2 + export PATH=$PATH:$gtm_dist + +NOTE: If you installed a 64 bit GT.M and answered 'n' to this question during +GT.M installation: "Keep original .o object files" you will need to substitute +``/home/vista/lib/gtm`` with ``/home/vista/lib/gtm/libgtmutil.so`` - GDE> +The important bits of the above file are: -This command starts the GDE and will change the prompt from the standard terminal one to \"GDE>\". Within the GDE environment, the default database location needs to be changed. Enter the command:: + * gtm_dist - the path to the GT.M installation + * gtmgbldir - the path to the GT.M database + * gtmroutines - the search path for routines (includes compiled object directories) + * gtm_lvnullsubs - Don't allow null subscripts (follow the M standard) - change -s DEFAULT -f=/home/$user/Downloads/VistA/database +All of the gtm variables are explained in the +`GT.M Administration and Operations Guide - Environment Variables`_ -replacing $user with your user name. After that command type exit and the changes will be applied. +We now need to change the permissions of the above file to allow for execution, +and change the owner to the vista user and group.: .. parsed-literal:: - GDE> :usertype:`change \-s DEFAULT \-f=/home/osehra/Downloads/VistA/database` - GDE> :usertype:`exit` - %GDE-I-VERIFY, Verification OK + $ :usertype:`chmod ug+x /home/vista/etc/profile` + $ :usertype:`sudo chown vista:vista /home/vista/etc/profile` - %GDE-I-GDCREATE, Creating Global Directory file - /home/osehra/Downloads/VistA/database.gld - ~/Downloads$ +We can now create a file that will create the initial database. This file +should be created at ``/home/vista/etc/db.gde`` with the following information: -The next step is to create the database that is used from within the VistA folder. This is done using the mupip command. Mupip stands for MUMPS Peripheral Interchange Program. It is used to manage the database and the global directories. We will use mupip to create a database and the Database Structure Editor (DSE) to configure the database in one command.:: +.. parsed-literal:: + + change -s DEFAULT -ACCESS_METHOD=BG -BLOCK_SIZE=4096 -ALLOCATION=200000 -EXTENSION_COUNT=1024 -GLOBAL_BUFFER_COUNT=4096 -LOCK_SPACE=400 -FILE=/home/vista/g/vista.dat + add -s TEMP -ACCESS_METHOD=MM -BLOCK_SIZE=4096 -ALLOCATION=10000 -EXTENSION_COUNT=1024 -GLOBAL_BUFFER_COUNT=4096 -LOCK_SPACE=400 -FILE=/home/vista/g/TEMP.dat + change -r DEFAULT -RECORD_SIZE=16368 -KEY_SIZE=1019 -JOURNAL=(BEFORE_IMAGE,FILE_NAME="/home/vista/j/vista.mjl") -DYNAMIC_SEGMENT=DEFAULT + add -r TEMP -RECORD_SIZE=16368 -KEY_SIZE=1019 -NOJOURNAL -DYNAMIC_SEGMENT=TEMP + add -n TMP -r=TEMP + add -n TEMP -r=TEMP + add -n UTILITY -r=TEMP + add -n XTMP -r=TEMP + add -n CacheTemp* -r=TEMP + show -a + +This file controls where the DEFAULT database is created. Creates another +database called 'TEMP' and maps TEMP, TMP, UTILITY, XTMP, and CacheTemp* to the +TEMP database. At the very end it will show the configuration for the databases. +All of these commands and options are explained in the +`GT.M Administration and Operations Guide - Global Directory Editor Commands`_. + +We need to make sure ownership of the ``/home/vista/etc/db.gde`` file is +correct: + +.. parsed-literal:: - mupip create && dse change -f -key_max=2046 -rec=4096 + $ :usertype:`sudo chown vista:vista /home/vista/etc/db.gde` -The \"mupip create\" is what actually creates the database while the \"dse change -f -key_max=1023 -rec=4096\" changes the maximum size of a key which contains a global reference. If this is left at the default value of 255, certain globals will not be able to be imported. +We can now use the ``db.gde`` file we just created to create the database definition +for us: .. parsed-literal:: - ~/Downloads$ :usertype:`cd VistA` - ~/Downloads/VistA$ :usertype:`mupip create && dse change -f -key_max=1023 -rec=4096` - Created file /home/osehra/Downloads/VistA/database.dat + $ :usertype:`sudo su vista -c "source /home/vista/etc/profile && /home/vista/lib/gtm/mumps -run GDE < /home/vista/etc/db.gde &> /home/vista/log/db.gde.log"` + +This command will run as the vista user (``sudo su vista``), source the profile +we created earlier (to setup the required environment variables) and run the GDE +routine with ``/home/vista/etc/db.gde`` as its input +(``/home/vista/lib/gtm/mumps -run GDE < /home/vista/etc/db.gde``). - File /home/osehra/Downloads/VistA/database.dat - Region DEFAULT +Now we can create the physical database files on disk with the following command: - ~/Downloads/VistA$ +.. parsed-literal:: -Now, the environment is set up to import the routines and globals from the OSEHRA code base. + $ :usertype:`sudo su vista -c "source /home/vista/etc/profile && /home/vista/lib/gtm/mupip create"` .. _SourceForge: http://sourceforge.net/projects/fis-gtm/ +.. _`createVistaInstance.sh`: https://github.com/OSEHRA/VistA/blob/master/Scripts/Install/GTM/createVistaInstance.sh +.. _`GT.M Administration and Operations Guide - Environment Variables`: http://tinco.pair.com/bhaskar/gtm/doc/books/ao/UNIX_manual/ch03s02.html +.. _`GT.M Administration and Operations Guide - Global Directory Editor Commands`: http://tinco.pair.com/bhaskar/gtm/doc/books/ao/UNIX_manual/gdecmds.html