Kernel Toolkit XINDEX: Introduction

XINDEX Introduction

Overview

Kernel Toolkit's XINDEX utility (formerly known as %INDEX utility) is a static analysis tool that plays the dual role of a VistA-aware cross-referencing tool and a code checker (or recognizer). As of Kernel Toolkit patches XT*7.3*132 and XT*7.3*133, XINDEX creates a cross-referenced list of global references and routines invoked by selecting any of the following:

Routines—XINDEX checks the specified routines (e.g., XU*).
Builds—XINDEX checks the contents of the specified build defined in the BUILD (#9.6) file. XINDEX checks all components of the build on the current system, which includes, routines, options, templates, data dictionaries, etc.
Installs—XINDEX checks the contents of the specified install defined in the INSTALL (#9.7) file. XINDEX checks all components of the install that have temporarily been loaded into ^XTEMP global, which includes, routines, options, templates, data dictionaries, etc.
Packages—XINDEX checks the contents of the specified package defined in the PACKAGE (#9.4) file. XINDEX checks all components of the package on the current system, which includes, routines, options, templates, data dictionaries, etc.

Use XINDEX to verify parts of a software application in the VistA environment that contain M code, including the following:

Routines
Options
Compiled Templates
Functions

XINDEX provides greater analysis capability than other syntax analysis tools that operate at the routine level only. As a static analysis tool, however, XINDEX has a fundamental limitation of the types of errors that it is able to catch and report. XINDEX is only able to look at the written structure of M code. It cannot look at dynamic aspects, such as the run-time symbol table or flow of control when it is modified by conditional branching (e.g., through post-conditionals or argument indirection). XINDEX is also generally conservative, at times preferring to report false positives rather than ignore potential problems. When analyzing XINDEX output, you must take all of this into consideration.

VistA applications are required to follow a set of Standards and Conventions (SAC) as set by the VA's Standards and Conventions Committee (SACC), which are defined as follows:

Standard—Requirement that must be adhered to.
Convention—Rule that should be followed.

VistA protects many of its abstractions via convention, even when those conventions are requirements. XINDEX checks that the MUMPS (M) routine code conforms to the 1995 ANSI M Standard and VA Programming Standards and Conventions (SAC). XINDEX considers all SAC prohibitions as an error. XINDEX checks SAC requirements, because conformance to the SAC is essential to the proper function of VistA.

VistA is comprised of a number of software packages (defined by namespace), which can be further divided into the following two basic groups:

Applications—VistA client applications or application modules (e.g., Pharmacy, Laboratory, Patient Care Encounter [PCE]).
Infrastructure Applications—Collection of Infrastructure packages that implement the basic programming and runtime VistA framework. For example:
- Kernel/Kernel Toolkit—Provides a portable system interface, a common execution environment, and essential services such as signon and security.
- MailMan—Provides VistA email functionality.
- VA FileMan—Provides database functionality built on top of the M global subsystem integrated with the VistA security model.

It is important to recognize that the rules for VistA infrastructure packages (particularly Kernel and VA FileMan) are different from other VistA applications. Code used in infrastructure packages to implement a system interface must be able to use implementation-specific code. Accordingly, Kernel (and sometimes VA FileMan) has standing exemptions from many of the requirements of the SAC. Thus, XINDEX sometimes reports errors and standards violations for allowed constructs.

REF: For more information on the Standards and Conventions Committee (SACC) and Standards and Conventions (SAC) documentation, visit the following VA Intranet website: http://vista.med.va.gov/sacc/

Types of XINDEX Findings

XINDEX reports its findings under the following general categories of codes (error flags):

Category Code/Other	Description
F	Fatal M Errors (Hard MUMPS Error)—These are unrecoverable errors that cause a program to fail if the commands are executed. It is possible, however, that these types of errors might exist in routines that run correctly. The error occurs (or may occur, depending on the underlying implementation) only when the errant commands are executed.
W	Warning Violation Errors (According to VA Conventions)—These are potential problems that are not necessarily fatal errors but most likely indicate an error. They require careful implementation.
S	Standards Violation Errors (According to VA Standards)—These are issues that do not pertain to the M language per se, but rather the requirements of the VA Standards and Conventions (SAC). Issues flagged as Standards Violations can still be syntactically correct M code that follows the portability guidelines, but does not follow the more stringent requirements set forth in the SAC.
I	Informational Messages—These issues are not necessarily errors but still require attention, because they could indicate potential problems.
Manual Check	Marked Items Errors (Manual Check)—These issues only apply if a line contains $TEXT ($T). XINDEX records the location and prints it out under the "Marked Items" sub-header on the XINDEX report.

NOTE: XINDEX retrieves and displays the current error conditions (messages) from the XINDX1 routine.

Any updates (e.g., add, modify, or delete messages) to the list of XINDEX messages are based on changes to the XINDEX utility via subsequent Kernel Toolkit patches.

Running the XINDEX Utility

CAUTION: When running XINDEX to review an entire software application, it is best to queue the report for an off-peak time, since processing is intensive.

Use either of the following methods to call the XINDEX utility:

Direct Mode Utility:
```
    >D ^XINDEX
```
REF: For examples using the Direct Mode Utility, see Examples 1, 2, and 3 below.
Option—Use the %Index of Routines option [XUINDEX] located on the on the Routine Tools menu [XUPR-ROUTINE-TOOLS] located on the Programmer Options menu [XUPROG], which is locked with the XUPROG security key.

REF: For more information on the %Index of Routines option, see the "%Index of Routines Option—XINDEX" section in Kernel Developer's Guide.

For an example using the %Index of Routines option [XUINDEX], see Example 4 below.

Examples

Example 1: Direct Mode Utility

XINDEX—Direct mode utilities sample user entries: Specifying a routine name only (1 of 3):

KRN>D ^XINDEX


                   V. A.  C R O S S  R E F E R E N C E R  7.3
                       [2008 VA Standards & Conventions]
                   UCI: KRN CPU: KRN    Jan 12, 2012@14:47:16

All Routines? No => <Enter> No

Routine: XDRMAIN
Routine: <Enter>
1 routine

Select BUILD NAME: <Enter>
Select INSTALL NAME: <Enter>
Select PACKAGE NAME: <Enter>

Print more than compiled errors and warnings? YES// <Enter>

Print summary only? NO// <Enter>

Print routines? YES// <Enter>

Print (R)egular,(S)tructured or (B)oth?  R// <Enter>

Print errors and warnings with each routine? YES// <Enter>


Save parameters in ROUTINE file? NO// <Enter>

Index all called routines? NO// 
DEVICE: ;P-OTHER <Enter>   Telnet Terminal    Right Margin: 255// 80


                   V. A.  C R O S S  R E F E R E N C E R  7.3
                       [2008 VA Standards & Conventions]
                   UCI: KRN CPU: KRN    Jan 12, 2012@14:47:16
Routines: 1  Faux Routines: 0

XDRMAIN   

--- CROSS REFERENCING ---


Compiled list of Errors and Warnings              Jan 12, 2012@14:47:16 page 1
No errors or warnings to report


--- Routine Detail   --- with REGULAR ROUTINE LISTING ---


XDRMAIN  * *  80 Lines,  3431 Bytes, Checksum: B16902409
                                                  Jan 12, 2012@14:47:16 page 2
              104 bytes in comments
XDRMAIN  ;SF-IRMFO/IHS/OHPRD/JCM - MAIN DRIVER FOR DUPLICATE MERGE SOFTWARE;    
          [ 08/13/92  09:50 AM ]
         ;;7.3;TOOLKIT;**23**;Apr 25, 1995
         ;;
START    ;
         S XDRMAINI="MERGE" D ^XDRMAINI G:XDRQFLG END
         F XDRMI1=0:0 S XDRMPAIR=$O(@XDRM("GL")) Q:'XDRMPAIR!(XDRQFLG)  S XDRMPD
          A="^VA(15,""APOT"","_""""_$P(XDRGL,U,2)_""""_",XDRMPAIR,0)" S XDRMPDA=
          $O(@XDRMPDA) D MAIN D:'$D(XDRM("NOTALK")) ASK
END      D EOJ
         Q
         ;
MAIN     ;
         S XDRMCD=$P(XDRMPAIR,U,1),XDRMCD2=$P(XDRMPAIR,U,2)
         S XDRMRG("LCK")="+" D LOCK^XDRU1 K XDRMRG("LCK") I $D(XDRMLOCK) G MAINX
         I '$D(XDRM("NOVERIFY")) S XDRMRG=0 D ^XDRMVFY G:'XDRMRG!(XDRQFLG) MAINX
         S (XDRMRG("FR"),XDRMAIN("FR"))=$S($P(^VA(15,XDRMPDA,0),U,4)=2:XDRMCD2,1
          :XDRMCD)

.
.
.

Example 2: Direct Mode Utility

XINDEX—Direct mode utilities sample user entries: Specifying a build name (2 of 3)

>D ^XINDEX


                   V. A.  C R O S S  R E F E R E N C E R  7.3
                       [2008 VA Standards & Conventions]
                   UCI: KRN CPU: KRN    Jan 12, 2012@14:47:16

All Routines? No => <Enter> No

Routine: <Enter>
0 routines

Select BUILD NAME: XT*7.3*102 <Enter>  TOOLKIT
Include the compiled template routines: N// <Enter>
 
Print more than compiled errors and warnings? YES// <Enter>
 
Print summary only? NO// <Enter>
 
Print routines? YES// <Enter>
 
Print (R)egular,(S)tructured or (B)oth?  R// <Enter>
Print the DDs, Functions, and Options? YES// <Enter>
 
Print errors and warnings with each routine? YES// <Enter>
 
Save parameters in ROUTINE file? NO// <Enter>
Index all called routines? NO// <Enter>
DEVICE: ;P-OTHER <Enter>  Telnet Terminal    Right Margin: 255// 80


                   V. A.  C R O S S  R E F E R E N C E R  7.3
                       [2008 VA Standards & Conventions]
                   UCI: KRN CPU: KRN    Jan 12, 2012@14:43:02

The BUILD file Data Dictionaries are being processed.

The option and function files are being processed.


Routines are being processed.
Routines: 1  Faux Routines: 0

XTPOST    

--- CROSS REFERENCING ---


Compiled list of Errors and Warnings              Jan 12, 2012@14:59:51 page 1

XTPOST   * *  106 Lines,  3234 Bytes, Checksum: B14328994
         ;;8.0;KERNEL;**102**;Jul 10, 1995
   XTPOST+1     S - 2nd line of routine violates the SAC.
         .S $P(^%ZRTL(3.091,0),U)="RESPONSE TIME"
   CHECK+34     S - Set to a '%' global.
         .S $P(^%ZRTL(3.091,0),U,2)="3.091P"
   CHECK+35     S - Set to a '%' global.
         .S $P(^%ZRTL(3.092,0),U)="RT DATE_UCI,VOL"
   CHECK+38     S - Set to a '%' global.
         .S $P(^%ZRTL(3.092,0),U,2)="3.092"
   CHECK+39     S - Set to a '%' global.
         .S $P(^%ZRTL(3.094,0),U)="RT RAWDATA"
   CHECK+42     S - Set to a '%' global.
         .S $P(^%ZRTL(3.094,0),U,2)="3.094D"
   CHECK+43     S - Set to a '%' global.

--- Routine Detail   --- with REGULAR ROUTINE LISTING ---
.
.
.

Example 3: Direct Mode Utility

XINDEX—Direct mode utilities sample user entries: Specifying a package name (3 of 3)

KRN>D ^XINDEX


                   V. A.  C R O S S  R E F E R E N C E R  7.3
                       [2008 VA Standards & Conventions]
                   UCI: KRN CPU: KRN    Jan 12, 2012@15:01:53

All Routines? No => <Enter> No

Routine: XDRMAIN
Routine: <Enter>
1 routine

Select BUILD NAME: <Enter>
Select INSTALL NAME: <Enter>
Select PACKAGE NAME: KERNEL <Enter> XU

Include the compiled template routines: N// <Enter>

Print more than compiled errors and warnings? YES// <Enter>

Print summary only? NO// <Enter>

Print routines? YES// <Enter>

Print (R)egular,(S)tructured or (B)oth?  R// <Enter>

Print the DDs, Functions, and Options? YES// <Enter>

Print errors and warnings with each routine? YES// <Enter>

Save parameters in ROUTINE file? NO// <Enter>

Index all called routines? NO// <Enter>
DEVICE: ;P-OTHER <Enter>  Telnet Terminal    Right Margin: 255// 80


                   V. A.  C R O S S  R E F E R E N C E R  7.3
                       [2008 VA Standards & Conventions]
                   UCI: KRN CPU: KRN    Jan 12, 2012@15:01:53

The package file Data Dictionaries are being processed.

The option and function files are being processed.


Routines are being processed.
Routines: 1  Faux Routines: 2

XDRMAIN   

          Data Dictionaries
|func          |opt           

--- CROSS REFERENCING ---


Compiled list of Errors and Warnings              Jan 12, 2012@15:01:53 page 1

|opt     * *  974 Lines,  35949 Bytes, Checksum: 
         I '$P(^VA(200,D0,0),U,11),$P(^(0),U,4)="@"!($N(^("FOF",0))>0)
   161+4        F - Undefined Function.
   589+2        F - Reference to routine '^XUCSPRG'. That isn't in this UCI.

--- Routine Detail   --- with REGULAR ROUTINE LISTING ---
.
.
.

Example 4: %Index of Routines Option

Select Routine Tools Option: %Index <Enter> of Routines


                   V. A.  C R O S S  R E F E R E N C E R  7.3
                       [2008 VA Standards & Conventions]
                   UCI: KRN CPU: KRN    Dec 13, 2011@07:40:44

All Routines? No => No

Routine: HLUOPT
Routine: <Enter>
1 routine

Select BUILD NAME: <Enter>
Select INSTALL NAME: <Enter>
Select PACKAGE NAME: <Enter>

Print more than compiled errors and warnings? YES// <Enter>

Print summary only? NO// <Enter>

Print routines? YES// <Enter>

Print (R)egular,(S)tructured or (B)oth?  R// <Enter>

Print errors and warnings with each routine? YES// <Enter>



Save parameters in ROUTINE file? NO// <Enter>

Index all called routines? NO// <Enter>
DEVICE: <Enter>  Telnet Terminal    Right Margin: 80// <Enter>


                   V. A.  C R O S S  R E F E R E N C E R  7.3
                       [2008 VA Standards & Conventions]
                   UCI: KRN CPU: KRN    Dec 13, 2011@07:40:44
Routines: 1  Faux Routines: 0

HLUOPT    

--- CROSS REFERENCING ---

   Press return to continue: <Enter>


Compiled list of Errors and Warnings              Dec 13, 2011@07:40:44 page 1

HLUOPT   * *  69 Lines,  3758 Bytes, Checksum: B18177059
         
   HOLD+4       W - Null line (no commands or comment).

--- Routine Detail   --- with REGULAR ROUTINE LISTING ---
   Press return to continue:
<Enter>

HLUOPT   * *  69 Lines,  3758 Bytes, Checksum: B18177059
                                                  Dec 13, 2011@07:40:44 page 2
              548 bytes in comments
HLUOPT   ;AISC/SAW-Main Menu for HL7 Module ;07/26/99  08:47
         ;;1.6;HEALTH LEVEL SEVEN;**57**;Oct 13, 1995