Philosophic, User, and Technical

Compliance Checker Documentation

10 Oct 85

15:08:03

DIR = [U0139.RICHARDSO]

COMDOC.MEM

WRITTEN BY

CHRIS RICHARDSON

RICHARDSON COMPUTER RESEARCH

P. O. BOX 8744

LA JOLLA, CALIFORNIA

92038-8744

(619)-488-6193

FOR

THE NAVAL WEAPONS CENTER

AT CHINA LAKE

Compliance Checker Documentation

10 Oct 85

Compliance Checker Documentation

1.0 Compliance Checker Introduction ...... 1

2.0 MUMPS Compliance Checker Philosophy ...... 1

2.1 Automated Tools ...... 2

2.2 Configuration Management Approach ...... 3

3.0 Compliance Checker Design ...... 6

4.0 Environmental Constraints ...... 7

5.0 Loading Instructions for COMPLY ...... 9

6.0 Run Instructions for COMPLY ...... 10

6.1 Available Options ...... 10

6.2 The Execution ...... 10

6.3 Examples ...... 11

7.0 Programmer Module Breakdown ...... 12

7.1 COMARG - Command Argument Controller ...... 12

7.2 COMBLK - Block Structure Control ...... 19

7.3 COMERPT - Error Reporting Module ...... 22

7.4 COMERR - Error Logging Module ...... 25

7.5 COMFLIN - First Line Convention Handler . . . . 30

7.6 COMFUNC - Function Handler ...... 36

7.7 COMLAB - Label Definition Handler ...... 41

7.8 COMLINE - Command Line Parser ...... 44

7.9 COMLSTK - Routine Label Stack Report ...... 49

7.10 COMMAND - Command Handler ...... 60

7.11 COMPKGE - Package Parsing Control ...... 74

7.12 COMPLY - Compliance Checker Entry Point . . . . 81

7.13 COMPOST - Post-Conditional Handler ...... 87

7.14 COMRLAB - Label Reference Handler ...... 92

7.15 COMRPRT - Routine Report Summary ...... 96

7.16 COMRSEL - Routine Select Handler ...... 98

7.17 COMRTN - Routine Parsing Control ...... 102

7.18 COMSTK - Package Routine Stack Report . . . . . 106

7.19 COMSTORE - Loads and Stores Routines into COM . 113

7.20 COMSTRG - String Handler ...... 117

7.21 COMSYM - Symbol Handler ...... 119

7.22 COMTIME - Time and Date Utility ...... 125

7.23 COMTOK - Get Next Token and Delimiter . . . . . 126

8.0 WAIVERS TO COMPLIANCE CHECKER ...... 129

8.1 "1C1" - Non-%ROUTINE Creates "%" Variable . . . 129

8.2 "2A1" - Title Line Not a Single "DO" Command . . 129

8.3 "3D1" - Potentionally Recursive Block Found . . 130

8.4 "3D2.1:4" - Recursive Routine Found ...... 132

8.5 "3E" - Previously Defined Block Invoked . . . . 133

8.6 "3I" - Unreferenced Label ...... 133

8.7 "4D" - XECUTE Command Found ...... 135

9.0 ACKNOWLEDGMENT ...... 136

10.0 COMPLIANCE CHECKER OUTPUT ...... 136

11.0 SAMPLE SYMBOL TABLE ...... 147

12.0 Standards Document ...... 149

13.0 INDEX ...... 164

1.0 Compliance Checker Introduction

MUMPS is an incredibly easy language to write programs in. It

encourages quick development and easy maintainence

(microcosmically). Microcosmically maintainable in that an error

stop leaves the execution intact so that the problem may be

investigated separate from the whole package. The execution may

be continued once the problem has been corrected.

Programmers in this environment have a tendency to write "Quick

and Dirty" code with the promise to "clean it up later". All too

often, this "Quick and Dirty" code ends up as production code

with unregulated patches being applied as the production

environment evolves.

The Compliance Checker is a tool for the control of MUMPS

programming style. It is a training aid and a quality control

tool. It should be used as an insentive for the programmer to

moderate his own MUMPS coding style.

This document describes the Compliance Checker in all of its

current functionality. This document contains routine by routine

discussion of the package's execution and customization

suggestions. At the end of this document is a copy of the

standards document, "MUMPS Programming Standards or How I Stopped

Worrying and Learned to Love MUMPS", that this package is written

to.

As a matter of convenience to the analyst, this document contains

a section on the Compliance Checker Philosophy. For those who

want to get to the finer points of this package quickly, this

section may be passed for the time being. For those who want

additional back-ground to the package, read on.

2.0 MUMPS Compliance Checker Philosophy

The only cure for interpretation is more interpretation.

- Anonymous -

MUMPS is an enigmatic language. It provides a rich programming

environment that allows the programmer a great deal of

flexibility to express concepts and ideas. This same concise,

but rich notation may also appear as cryptic to the unfamiliar

reader.

The MUMPS language provides the ability to abbreviate most

commands to a single character. Presently, this is the heart of

the difficulty in modern information systems today. The computer

understands these symbols with ease and performs them well

(whether employed correctly or incorrectly). The human computer

does not accept these symbolic entities in the same pedantic and

dogmatic style. Instead, the human computer is highly

imaginative and associative, finding inference whether expressed

or unimplied.

The human computer constructs tools. This Compliance Checker is

one such tool. The Compliance Checker is a means of automating

the Quality Control Function. It must be recognized that this is

just a tool that reflects a specific set of standards. These

standards are an ideal and are not always practical. In the area

of tools and standards, a great deal of work remains. As such,

this tool should not be viewed as a culmination, but a beginning

of an on-going process towards the generation and development of

better tools.

2.1 Automated Tools

We human computers build what we call tools to support the

man-machine interface. The purpose of tools is to provide a

context for special work. This context is for the expressed

purpose of allowing the pedantic computer to provide special

documented representations for the human computer. By providing

this environment, the ideas reflected within MUMPS code become

familiar symbols. These symbols are a special re-iteration of

the application being modeled. This gives the human computer

another aspect from which to view the logical model, and derive a

more informed understanding of the application being modeled.

The meaning of the model becomes clearer from the other points of

view. Hopefully, the value of these tools will be reflected in

better control of the model building process.

Any project which reflects the workings of more than a single

mind, needs some form of configuration management. To simplify

this even further, every development project needs some form of

configuration management.

In theory, quality control in the software modeling environment

means the validation of the concepts and ideas reflected in the

software model. This has been a difficult if not humanly

impossible task, however, the task can be readily accomplished.

If humans are too slow and prone to overlook the details of

quality control, then a tool must be developed that identifies

the techniques and styles that confuse and obscure the concepts

employed in the model. Once we have such a tool, it is

meaningless until we establish the feed-back to the individuals

that are generating the questionable code. Here is the starting

point for the development of a consistent programming style for a

programming team.

Traditionally, programming style has been something programmers

acquires over a long period by trial and error or conditioning.

Like most behaviors, they are enforced by the response of the

environment upon the programmer. If the program failed to run

properly, who cares. The pay check still arrives like

clock-work. Further, with any luck, the programmer won't have to

support the package too long before he moves on to another

project. Programmers get ahead by changing jobs, don't they?

Given these attitudes, the programmer often feels that the

remainder of the DP community operates in the same manor. "Why

should I program in a supportable manor, nobody ever did that for

me."

The elements of programming style in MUMPS have not been well

discussed yet. Individual techniques have been anarchy thus far.

Each programmer has his own special approach to solving a

particular part of a problem. The programmer manipulates the

symbols at hand in a fashion which is meaningful at that time.

Their individual style prejudice is reflected with the symbols

and approaches used. The computer applies no such special

significance to these symbols. The computer is restricted to use

the limited confines provided by the model. The computer has no

problem conveying a meaning to these symbols.

2.2 Configuration Management Approach

To avoid the problems discussed above, Code 084 at the Naval

Weapons Center has developed this set of tools to provide a

conceptionally automated quality control program package. This

approach addresses three specific areas; programmer training,

documentation, and support.

The philosophy of this approach involves the following;

1. Establish a set of standards.

2. Develope a model which can rigorously test code against these

standards.

3. Make the tool available to the programming staff.

4. Establish of a mailbox system in which packages may be

delivered for analysis by the designated Quality Control

group.

5. Keep a copy of the routines away from the programmers. This

will be the configuration management copy that will verify

the presumptive production code.

2.2.1 Programmer Training

Exposing the programmer to a copy of the Compliance Checker will

provide an understanding of how the checker functions. The code

will provide pointers for how the standard can be complied with.

Actually running the code against the compliance checker, will

inform the programmer about the techniques the programmer may

need to defend. Basically the programmer will normally have the

option of rewriting the code to the standards or completing the

proper waivers.

2.2.1.1 Modifying the Code

Modifying the code helps the programmer to learn programming

techniques which are ultimately embraced by all of the other

programmers. This feed-back will help the programming staff to

learn to organize their thought processes into structured models.

Structured models are inherently easier to support and to modify.

They are also easier to bullet-proof. The structured modules

which make up the model may be rigorously tested in isolation,

apart from the other components or modules of the model.

2.2.1.2 Filling out the Waiver

The waiver reflects the concept being expressed in support of the

inconsistent code. The reconstruction of the programmer's

concept at the time of coding, is the single most difficult

problem.

This takes a significantly different type of work than most

programmers are willing to become involved in. Essentially, this

is the programmers incentive to modify the code to fit the

standard. However, if no standard method may be found, the

waiver maintains some conceptual integrity in reestablishing the

programmer's intent for the code.

2.2.2 Documentation

Documentation reflects more of an integrated approach which

results in a significant degree of standardization. The

programming staff is generating code in essentially the same

programming style. The consistent styles being applied provides

for easy analysis by the documentation specialists.

2.2.3 Support

When an assumption has entered into an application, the support

programmer (or any other programmer on the staff) will be able to

decipher the code quickly. The following advantages will be

readily available to the programmer.

1. The code is hierarchical in design.

2. The quality control staff should have the Compliance Checker

analysis available.

3. The code is written in a consistent and familiar style.

4. Waivers will be available for non-standard code.

5. Structured MUMPS models are easier to restart in place.

3.0 Compliance Checker Design

The Compliance Checker closely follows the syntax of the language

and attempts to compare the input code to the ideal of a

standard. It is not rigidly intended that everyone must write

code which will follow the standard explicitly. Instead, the

standard is an ideal, and is to be strived toward but not

necessarily attained in all cases. The catch is that the

shortcomings are to be documented with waivers.

There are a number of levels that the code uses to examine an

input routine. These are:

1. By Package - The first routine is identified and loaded into

the ^COM global (^COM("TEXT",RTN,N)). As each external

reference is identified, the routine name is stored to be

loaded and examined. The relationship of the current routine

and the called routine is maintained for package structure

analysis at the completion of the run (COMPKGE).

2. By Routine - As the routine is parsed, the labels and the

order that they are invoked is saved. The relationships are

maintained in the ^COM global for routine structure analysis

after each routine (COMLSTK).

3. By Block - A one label, one unconditional exit, block rule is

compared and adhered to where possible. The introduction of

a new label prior to the closure of the last block is flagged

as an error. Unreachable code or unreferenced labels are

also flagged as an error.

4. By Line - A line in MUMPS is a specific type of blocking that

is peculiar to the MUMPS language. There is a class of

commands which control access to the other commands situated

to the right on the current line. These are called control

commands; (i.e., FOR, IF, QUIT, GOTO, ELSE). There are

circumstances which make the execution of commands to the

right more or less critical. For example, an

unpostconditionalized GOTO that occurs after an IF command

does not signify the end of a block. An

unpostconditionalized GOTO without a control command

signifies the end of a block.

5. By Command - A Command level of evaluation provides some

interesting problems with the syntax of the language. There

is a series of commands that allow an incredible amount of

freedom (and potential danger). The XECUTE command provides

the opportunity to subvert every aspect of the standard. It

is important to keep track of these and other commands that

are potentially ambiguous, such as the ELSE command. The

problems with the GOTO are historical to the point of

becoming legend.

Certain commands are important by the features they impart as

well as the symbols they reference. The SET, the FOR, and

the READ commands are the only ways that local variables are

created or changed in the MUMPS Language. Use of the SET is

the only way to create global variable references. The KILL

command is used to eliminate both local and global

references. All other symbol usages are only references.

6. By Argument - The argument is the most complex of all of the

interfaces. Each command references the arguments

differently. Further, the richness of the language provides

a wide variety of symbol expression as arguments.

There are situations wherein a certain command can have a

dramatic effect upon symbols that were explicitly not

mentioned. The argumentless KILL command will destroy all

local symbols created to the present point. The exclusive

KILL will destroy all of the symbols not specified within the

exclusion list.

The postconditionalization of a command or argument is a

specialization of an expression. It resolves down to one of

two outcomes, TRUE or FALSE. Still each reference within the

structure of the postconditional must be recorded as a

reference.

4.0 Environmental Constraints

The Compliance Checker was designed to run DSM on a VAX. The

most significant limitation to note is that this package is a

hierarchical model. This model makes heavy use of the stack.

However, this allows for a special level of analysis in the form

of stack evaluation (on the VAX, DO ^%STACK).

In an effort to make this package as useful as possible on

multiple systems, many of the options are described in detail in

the module descriptions provided below. An effort has been made

to make the code easy to modify for other implementations.

Further, there are some 1984 Standards features installed, like

the two argument $LENGTH and the "left side of the equals sign"

functions ($PIECE only). As a result, these ultimately represent

a source of trouble for migration to some older implementations.

Solutions to these problems will be published in future editions

of this document. In the interim, these extention problems will

be considered as "an exercise for the student".

HINT: a relatively inelegant solution for the two argument

$LENGTH may be written as a $FIND function driven by a FOR loop.

The package does expect at least the first routine to be analyzed

to be resident and available as a routine. Also, it would

require very little modification to adapt the compliance checker

to accept input for routines by tape or other sequential source.

There is a symbol that may be set before a run. This symbol is

the default list device. The symbol LISDEV may be set to a file

or device ID prior to invoking the routine. In the event that

LISDEV does not exist, it will be set to 0 and the actual default

device will be used.

Little needs to be change for the Compliance Checker to run on a

PDP-11 using DSM-11 Version 3.0 or better. Also, attempts have

been made to flag these areas with special comments to describe

the activities the code is to perform.

5.0 Loading Instructions for COMPLY

The tape supplied is a 9-track, 1600 BPI tape in VAL4 format with

1024 characters per block (unless otherwise indicated). The

files are arranged as follows;

1. Routines - 23 Routines in %RR format

2. Globals - COMDEF and COMDOC in %GR format

LODOC D INIT,START ; LOADS DOCUMENT OFF OF TAPE ; 7-SEP-85 ; RCR

QUIT

INIT S LIST=3 ; OR THE LIST DEVICE YOU ARE USING

S N="" ; START THE ARRAY TRAVELER

O LIST U LIST ; OR THE LIST DEVICE YOU WISH TO USE

QUIT

START F LP00=1:1 S N=$O(^COMDOC(N)) Q:N="" W !,^COMDOC(N)

C LIST

QUIT

The document is in RUNOFF format which contains form-feeds,

line-feeds and carriage-returns imbedded within the text. Nearly

all printers should be able to handle these control characters.

6.0 Run Instructions for COMPLY

6.1 Available Options

In the previous discussion the LISDEV (LISt DEVice) variable was

mentioned to include setting up the Compliance Checker up to

generate a hardcopy listing. There is also a feature installed

that allows you to monitor the execution as it progresses.

Many of the Compliance Checker analyses run for an extended

period of time. Each undefined external reference called is

another routine which will be subjected to analysis. To allow

the user to monitor the progress of these runs without killing

the job or seriously impacting the run performance, a status

feature has been installed. The status feature provides that any