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!
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
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:
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.