Simple System Status for VistA / GT.M

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.

Installation and Configuration

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.]

Usage Examples

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.

Miscellaneous Notes

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.

Caché Port

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.

EWD.js Adaptation

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.