Vista Software

The Department of Veterans Affairs (DVA) Healthcare Information System called Vista is available to the public through the Freedom of Information Act (FOIA). For convenience, DVA has made Vista available for download as a pre-configured Caché dataset. However, the 130 MB zip file may be too large for practical download via telephone modem. For information on how to obtain Vista on CD see Hardhats.

To install and run the Vista software from the pre-configured dataset it is first necessary to install Caché. Other M environments also support Vista, but the downloadable dataset specifically requires Caché.

Installing Caché and Vista is the first step. To make Vista useful requires many more steps. Technical knowledge is needed to set up most Vista applications. While applications are well-documented, their scope and complexity challenge the most patient explorer.

On this page we offer assistance with some of the steps in configuring and customizing the infrastructure components of the Platinum Vista dataset. After completing the infrastructure configuration a modest additional effort is required to demonstrate selected Vista applications such as Patient Registration, Admissions, Transfers, Discharges, and the Clinical Patient Record System (CPRS). The latter provides a Graphical User Interface to Vista clinical applications.

Disclaimer: Giving and receiving advice is inherently hazardous. In these steps we describe what has worked for us. We do not claim that it will work for you. In fact, we make no claims whatsoever, and are not responsible for your success or lack of success in implementing and configuring Vista. Use these suggestions at your own risk. If you discover an error or have a question please Email your comment or question.

Before Starting to configure Vista it is well to anticipate some of the decisions you will need to make. For example, your installation should have an identifying name and number. The name can be a real name, such as the name of your organization, or a made-up name. The Department of Veterans Affairs assigns three digit site numbers to its medical centers. To avoid confusion with real VA sites it is recommended to select a 4-digit site number for your Vista installation.

The installation will also require a domain name, but not necessarily a real domain name. If your Vista installation is not connected to the Internet, it is okay to make up a domain name. You will need to create Access and Verify codes (like Username and Password), and probably an Electronic signature code as well. Make these codes simple and easy to remember, unless you are configuring a production installation, where security is a real concern.

Finally, aim to have fun. Unexpected problems are sure to arise. Configuring Vista is an adventure. You may experience frustration, but you will not be bored!

Step by Step

It is assumed that Caché 3.x or greater has been successfully installed, and that you are familiar with basic Caché operations, such as starting the Configuration Manager or Caché Terminal.

Create a folder for the cache.dat file under the ./cachesys/mgr path. Make the folder name the same as your planned Caché Vista namespace name. A good choice is Vista. Other suitable choices might include a project or organization name or abbreviation. It is best to keep the name short, say 3-6 characters. Unzip the Platinum cache.zip file to the folder you have just created. In the following steps we will assume the folder (and namespace) are called Vista. In the steps which follow, arbitrary names such as this one will be colored red/brown for easy identification. The color means another name may be consistently substituted.

After unzipping or copying the Platinum cache.dat, this file must be configured as a Caché dataset and namespace. If your Platinum install is to be self-contained, in the sense that Vista library routines and globals (e.g. the device selector and Taskman) occupy the same namespace as applications, then the steps for configuring the Diamond cache.dat may be followed. If, on the other hand, you plan to configure several Platinum namespaces to share a common "manager" account, the process is a little different. For simplicity, we will assume this is a self-contained Platinum demonstration namespace, and refer you to the Hardhats Diamond installation instructions for this step. Substitute your Vista namespace name (e.g. VISTA) for the name KERNEL in the Diamond instructions. Also, pay particular attention to the Global and Routine mapping steps, as not getting these right is often the source of trouble. Optionally, when finished, use the Caché Control Panel to adjust the database growth (Max # of MB) to an appropriate value. Expand Local Databases, right-click the Vista database and choose Edit.

If either the namespace or configuration name is not VISTA it will be necessary to run the routine ^ZTMGRSET after installing the Vista platinum database. There is no harm in running ^ZTMGRSET in any case. For the purpose of this demonstration installation we use the configuration name CACHE, and run routine ^ZTMGRSET to configure this name in Vista.

Caché 4.x uses CACHEWEB rather than CACHE as the default installation name. Unfortunately, the Kernel MGR setup routine^ZTMGRSETdoes not accept configuration names that are more than 5 characters in length (See VOL^%ZOSFONT). To circumvent this restriction it is necessary to set the volume name manually. From the programmer prompt,

                >S ^%ZOSF("VOL")="CACHEWEB"

Elsewhere in the instructions that follow substitute the name CACHEWEB for CACHE, e.g. in files #14.5, #14.7, the VOLUME SET multiple of the KERNEL SYSTEM PARAMETERS file, and the VOLUME SET(CPU) field of the DEVICE file.

In Caché 5 the extrinsic function $$AVJ^%ZOSV() causes an error. A simple workaround is to bypass this function's code and instead return a constant value for the number of available jobs. Caché Studio may be used to edit routine ^%ZOSV. Start Caché Studio from the cube. Then from the "File, Open" dialog, select the appropriate "Look In" namespace from the dropdown list--normally VISTA. Similarly select "Files of type" *.INT. Then supply the name %ZOSV to load the routine. Insert a new line after tag AVJ() as shown highlighted in the illustration below:


Next, compile and save the revised routine. Note that Caché Studio does not automatically compile .INT routines unless it has been set up to do so in the "Tools, Options, Saving" tabbed page.

Now that Platinum has been installed we are ready to address basic configuration issues. The order of performing some steps may be important. However, in general, order is not critical. Let's start with Fileman.

Fileman: Every Fileman installation has a SITE name and number. These values are established when initializing Fileman, and are stored in the ^DD("SITE") and ^DD("SITE",1) nodes. Although Fileman is already initialized in the Platinum database, reinitializing Fileman (on a quiescent system) causes no harm. Therefore, it is recommended to DO ^DINIT and substitute your SITE name and number for the defaults. If you do not have an "official" site number, pick an arbitrary 4-digit number, avoiding round numbers like 1000 or 5000, etc. This will reduce the chance of file-number collisions when you import and create your own Fileman files.

Device file: Now let's turn our attention to devices. Typical appropriate field values for the Caché Terminal device are shown below. CONSOLE is the primary logon device, and must have the correct volume set name. 

NAME: CONSOLE                           $I: |TRM|
  ASK DEVICE: YES                       ASK PARAMETERS: YES
  VOLUME SET(CPU): CACHE                SIGN-ON/SYSTEM DEVICE: YES
  LOCATION OF TERMINAL: CONSOLE         SUBTYPE: C-VT320
  TYPE: VIRTUAL TERMINAL

The volume set is named CACHE (if renamed following the Caché installation). For a single-volume Platinum install it makes sense to stuff the value CACHE into the VOLUME SET(CPU) field for all Vista devices.


To logon to Vista remotely via Telnet you will need a generic Telnet logon device with $I=|TNT|. Other important devices include the NULL device (used by the Remote Procedure Call Broker) and the Host File System (HFS) device used by by the Kernel Installation and Distribution System (KIDS) and other applications. To view an example device editing session click here.

Domain and system parameter files: The Platinum cache.dat has one pre-defined DOMAIN file entry VISTA.MED.VA.GOV. It is possible to use Vista as pre-configured for the VISTA.MED.VA.GOV domain. However, generally it is preferable to add a domain entry for your installation, and to repoint system parameter files to your domain. Here are the basic steps:

  1. Create a DOMAIN file entry. Substitute an appropriate value for MYDOMAIN.COM in the example.
  2. Repoint Kernel System Parameters. This involves 2 sub-steps, setting the DOMAIN NAME field to point to the appropriate DOMAIN, and then re-indexing the file.
  3. Rename VOLUME SET multiple to CACHE.
  4. Repoint Mailman Site Parameters. This step is analogous to repointing the Kernel System Parameters. First set the DOMAIN NAME field, and then re-index. When finished, the variables ^XMB("NAME") and ^XMB("NETNAME") should both equal your domain name.
  5. Enter a PARENT domain. The distributed Mailman Site Parameters entry points to a non-existent PARENT entry #4. Temporarily, change this to VISTA.MED.VA.GOV (as a place holder).

User entry: There's still lots to do. Taskman and Mailman will be addressed shortly, but at this point we are able to create a first user and attempt the first Vista logon. To create the first user follow these steps. User entry screens are difficult to capture, so we show only how to get there, and selected example field values. Be sure to enter an ACCESS CODE, and SERVICE/SECTION (required). PRIMARY MENU OPTION and FILE MANAGER ACCESS CODE fields may be skipped for now.

Before proceding further, verify that the first user has been created as entry number 1 in the NEW PERSON file. We will now assign programmer access and the system manager menu to the first user. 

VISTA>S $P(^VA(200,1,0),"^",4)="@"
VISTA>S ^VA(200,1,201)=9

And now the moment of truth. It is time to try a first logon. Success at this point is cause to celebrate!


The single-user (unlicensed) Caché 4.x free download may return 0 (zero) available jobs when you attempt to logon to Vista. To overcome this difficulty simply force a constant return from the AVJ() extrinsic function. Modify routine ^%ZOSV, inserting the line Q 20 immediately after the introductory comments at the AVJ() tag..

        %ZOSV    ;SFISC/AC - $View commands for Open M for NT.  ;02/04/2000  10:04
                 ;;8.0;KERNEL;**34,94,107,118,136**;Jul 03, 1995
        ACTJ()   ;# Active jobs
                 N Y,% S %=0 F Y=0:1 S %=$ZJ(%) Q:%=""
                 Q Y
        AVJ()    ;# available jobs
                 ;Return fixed value if version < 2.1.6 (e.i. not Cache)
                 Q 20
                 ...
If you use Caché studio to edit routine ^%ZOSV be sure to compile your changes before saving. Studio can be set to auto-compile changed routines.

Next.. Let's see if we can get rid of that annoying message:

WARNING -- TASK MANAGER DOESN'T SEEM TO BE RUNNING!!!!

Starting Taskman: First, if the volume set name has been changed from VISTA to CACHE (as shown in the above examples) it will be necessary to edit the VOLUME SET file and the TASKMAN SITE PARAMETERS file entries. After changing the volume set name (if appropriate) try to start Taskman from the programmer prompt as follows: 

VISTA>D START^ZTMB

To check whether Taskman is starting, list the system status using either the Caché system viewer or the routine ^%SS. Routine ^%ZTM0 should appear somewhere in the status listing, for example:

Process  Devices      KB Namespace      Routine     CPU,Glob  Pri  UIC  Location
  1076                34 VISTA          %ZTM0        94,54     0   0,0

Alternatively, use the Caché global lister to inspect the ^%ZTSCH global. The STATUS node should indicate that Taskman is in its "startup hang" state: 

^%ZTSCH("STATUS",1076)=58443,43914^RUN^CACHE:CACHE^Startup Hang

If routine ^%ZTM0 is not found in the Caché system status, the ^%ZTSCH listing should indicate what is wrong. If everything has progresses normally to this point, wait about 2 minutes. Then check the system status again. This time there should be an entry for routine ^%ZTM replacing the entry for ^%ZTM0:

Process  Devices      KB Namespace      Routine     CPU,Glob  Pri  UIC  Location
  1076                37 VISTA          %ZTM      44742,6846   0   0,0

Now when the system manager logs on, he or she will be greeted more politely: 

Good afternoon MANAGER,SYSTEM
     You last signed on today at 12:11
Select TERMINAL TYPE NAME: C-VT100//
          Digital Equipment Corporation VT-100 video
 
Select Systems Manager Menu Option:

Keys: Applications use keys and locks to manage access to various options within their menu trees. Keys are but one of many security features in Vista. It will be necessary from time to time to assign keys in order to test various options. To illustrate the process, as well as to prepare for subsequent steps, let's assign a few basic keys to the first user. One useful consequence of assigning the XUPROG and XUPROGMODE keys is the ability to return to the programmer prompt from the Systems Manager Menu in a more graceful way, without halting or generating an interrupt error.

Mailman: The Email application known as Mailman is an integral part of the Vista suite. In addition to ordinary user-to-user communication, Mailman assists other applications by providing a mechanism for automatically reporting important information. An exceptionally rich range of features are included with Mailman. Before testing Mailman, first edit the Mailman Site Parameters. Substitute the appropriate timezone for the one exported, and specify the UCI (namespace) and VOL for Mailman's filer to run. The example shows VISTA,CACHE. As previously noted, these names must be consistent throughout the installation. Use the volume set name that was specified when running ^ZTMGRSET, or the default name VISTA, if not changed.

To test Mailman, send a message from Postmaster to the first user. Allow a minute or so for delivery, then switch identity to the first user, and confirm that the message was delivered. Mailman is used so extensively in Vista that it is normally made an automatic application, that is an application that can be invoked from any menu prompt. To make Mailman an automatic option in your installation add the XMUSER option to the XUCOMMAND menu.

RPC Broker: The Vista infrastructure includes a Remote Procedure Call broker, to support client-server applications such as CPRS. As the Platinum Vista dataset is distributed, the RPC BROKER SITE PARAMETERS entry points to the PLATINUM.VISTA.MED.VA.GOV domain. Like the Kernel system parameters and Mailman site parameters this entry also should be repointed to the installation domain. However, as with other system files the Broker parameter's #.01 field is not editable. To repoint it first determine the internal entry number of your installation domain and then set the RPC Broker parameter's pointer to that number. Finally, re-index the file. Here is an example.

To test the RPC Broker it is necessary to install the client workstation software. Installing RPC Broker client components exceeds the scope of the present How-To document. However, if you have installed the client software, edit the RPC Broker site parameters to enter the TCP/IP port that you intend to use for the Platinum Vista Broker, and start a listener on that port. The rpctest.exe program can be used to verify that the broker is working properly. When the Vista logon screen appears, enter the access and verify codes previously established for the first user.

Home