This document describes how to
implement a simple interrupt-driven System Status display for a single instance
of VistA under GT.M for Linux. By ‘simple’ is meant, 1) the System Status
code is contained in one self-contained routine (^ZSY), and 2) interrupt
completion requires only a single line to be inserted in one VistA routine
(^ZU).
The
^ZSY routine described below also includes the customary ‘Examine Job’ and
‘Kill Job’ utilities. The System Status
display utility (^ZSY) produces a listing of VistA/M processes.
Routine
ZSY may be downloaded in GT.M source file format (.m) here,
or in routine output/input format (%RO / %RI) here. Restore the routine to the GT.M VistA
environment where it will be used, and perform the following steps.
1. Insert one line after tag JOBEXAM in VistA
routine ZU. The line to be inserted is
highlighted in the illustration below.
2. Similarly add one or two lines to your
VistA/GT.M environment script. The exact
form of the insert depends on which Linux shell you are using. The example below is for bash.
After
performing the above steps, compile the ZSY routine and verify that everything
is okay by performing an environment check.
If the environment check detects a problem it will display a message. However, if no problems are found the check will return to the programmer prompt, without displaying anything. [The same check is run as an extrinsic function from within the routine, as part of its internal validation.]
System
Status: To generate a system status display,
such as the one illustrated in the introduction, run the ZSY routine from the
top. Do ^ZSY or Do SS^ZSY. Users familiar with Intersystems Caché may
remark that the display does not include CPU or Global statistics. Nor does it identify the environment. As stated at the beginning of this document,
the Simple System Status application is intended for use in a single database,
single Linux user environment.
Additional development would be required to adapt the program for more
complex situations.
Job
Examine: To examine details of a VistA process, run the ZSY routine from
tag JOBEXAM (Do JOBEXAM^ZSY). At the
‘Enter Process ID:’ prompt, enter either an active process ID or ‘SY’ to list
current processes. When you have entered
a valid process ID, the program will display the process’s invocation stack,
then the current line, followed by a list of process variables and their
values.
The
stack display order inverts the ZSHOW command “S” order, placing the topmost
level first and the process’s current position last, for example, number ‘6’ in
the illustration above. The line
beginning ‘>>’ immediately below the last stack line displays the
process’s M code at the interrupt position.
Some
processes may contain a great many defined variables. The above illustration has been
truncated. In some cases, variable
values may include escape sequences that affect the display in undesirable
ways.
In
production VistA deployments, local variables often contain Protected Health
Information (PHI). Therefore, it is
important to be aware that the ‘Job Examine’ option can display PHI from
another process’s symbol table. Access
to this option should be controlled accordingly.
Kill
Job: To kill a VistA process, run the ZSY routine from tag KILLJOB (Do KILLJOB^ZSY). At the prompt, enter either an active MUMPS
process ID or ‘SY’ to list current processes.
When a valid process ID has been entered, the program will present a
confirmation prompt before issuing a kill signal to the job.
In
the illustration above, PID 2523 is an active MUMPS / VistA job (and not the
current job, which is PID 3048).
Therefore, the utility considers it a valid target for the kill
signal. Re-running the System Status
after issuing the kill signal will confirm that the process was indeed
terminated. If you have access to the
target process, as when testing from terminal mode, you may also see a message
there, indicating that the target process was killed.
This
project was developed using GT.M V5.4-002B under Ubuntu 12.04 (Precise Pangolin) and is currently being
used with GT.M V6.0 under Ubuntu 14.04.
The original development database environment was based on the December
2011 FOIA release of VA VistA. The
application has also been tested with subsequent VistA releases through
December 2014.
Although
the primary purpose of the ‘Simple System Status for VistA’ project described
in the preceding paragraphs was to provide functionality that is not readily
available in the VistA/GT.M environment, some interest was expressed in having
an analogous database-specific and VistA-specific display for Caché VistA
implementations. Therefore we adapted
the ZSY routine to function also in the Caché VistA environment.
The
modified ZSY routine may be downloaded as a Caché ^%RO file here. This file
is in DOS/Windows format, i.e. has DOS/Windows end-of-lines. It may be loaded into Caché for Windows using
the ^%RI utility. An equivalent Caché
for UNIX compatible ZSY routine is here. This revision also works in the GT.M
environment, by automatically detecting whether the environment is Caché or
GT.M.
Only
the System Status display part of routine ^ZSY has been adapted for Caché. For ‘Job Examine’ or ‘Kill Job’ functions use
the Caché System Management Portal or equivalent command line utilities.
To
use routine ZSY in the Caché environment do not modify VistA routine ^ZU. In other words, do not perform step 1, as
described for the GT.M implementation above.
Of course, step 2 is also not relevant to using ZSY in Caché. Just run ^ZSY from the Cache command prompt
to produce a display resembling the following.
Note
the similarity of this display to the GT.M example presented at the top of this
page. Only processes associated with the
current namespace are displayed. For
each VistA process, the Package (or pseudo-package name) is identified, along
with the VistA user. [The unusual ‘Routine’ named in the listing for process 7224 in the
example above refers to a Caché Studio instance.]
VistA
user names are resolved by using the table in ^XUTL("XQ",PID,
"DUZ"). However, the ZSY routine also includes an
alternative mechanism that can be used to compute user IDs for processes that
are not registered in the Kernel-maintained ^XUTL("XQ")
table. To use this mechanism, insert the
following line to an appropriate location within a VistA routine that has an
associated VistA user, but is not registered through Kernel logon or etc.
Avoid
inserting the above line of code into any location where the naked reference
must be preserved. The illustrated code
will create an entry in a self-registration table maintained by the VistA
System Status routine. Routine ZSY will
automatically prune the table, so that it is not necessary for a VistA process
that registers itself in this way to delete its entry on exit.
The VistA System Status utility was
designed to run in a terminal window, however, its display component may be
readily adapted to return a formatted array for presentation in a web
browser. A recent enhancement to routine
^ZSY provides a callable entry point for use with the open source EWD.js framework. After downloading the revised
routine, use the routine import utility ^%RI to load it into MUMPS.
The subroutine at tag TA generates an array
suitable for display in a JavaScript text area, and stores the output to ^TMP("ewd",$J,"ZSS"). To implement VistA System Status
functionality from within an EWD.js application, configure the back end message
receiver to invoke ewd.mumps.function("TA^ZSY")
and, of course, to return the generated data.
In turn, code the application’s message reply handler (front end JavaScript)
to populate a text area with the received data.
Only the display component of the program has
been adapted in this way—Job Examine and Kill Job functions remain restricted to
terminal mode. It is recommended to
exercise ^ZSY in terminal mode before attempting to implement the new
functionality. Setup steps described in
the “Installation and Configuration” section near the top of this page also
apply to this adaptation.
The
author makes no claim as to the accuracy or completeness of information
contained in this document. In no event
will the author be liable for any damages, lost effort, inability to deploy the
application, or anything else relating to a decision to use the information in
this document.