EsiObjects

Coding Conventions

 

(c) Copyright 2008 – Stormwoods LLC, Eugene OR

1. Purpose of Document

The purpose of this document is to outline programming rules and style for the Open Source EsiObjects system an all packages developed using EsiObjects. Conventions described as rules are required programming conventions. Conventions described as style are optional. They typically apply to formatting and are assumed to be changeable by a Pretty function (when it exists).

 

1. Namespace Assignments

ESI has been assigned a namespace by the Veterans Administration – it is VES. This means we can use routines and globals within this namespace safely. Use of this namespace by any other organization will result in overwrite of code and data and will cause serious integrity problems. The namespace is reserved for ESI’s use only.

This namespace was originally assigned for ESI's courseware system. Since then, we have assigned sub-spaces to the EsiObjects system. All systems ESI implements will reside in the assigned namespace. Overlap of namespaces will cause problems when software is installed. If any Open Source contributor wants to contribute software to the EsiObjects Open Source kit, they should contact ESI for a namespace assignment.

There are 8 character positions in an M routine and global namespace. VES is constant and occupies the first three-character positions, leaving a 5-character namespace. Each position in the namespace can have 62 characters in it (26 Uppercase, 26 Lowercase and 10 digits). The table below lists the number of routines or globals that possible based on the number of positions assigned.

 

625	916,132,832
624	14,776,336
623	238,328
622	3,844
621	6

1.  Routines

   1. Namespace	Assignment	Status
      ESI*	Internal routines – Not for Distribution	Active
      VES0*	Introduction to File Manager Course	Active
      VES1*	Intermediate File Manager Course	Active
      VES2*	Introduction to MUMPS Programming Course	Active
      VES3*	Word Manager Course	Open
      VES4*	Intermediate MUMPS Programming Course	Active
      VES5*	Advanced MUMPS Programming Course	Active
      VES6*	Advanced File Manager Course	Active
      VES7*	DCL Programming Course	Active
      VES8*	DSM System Management Course	Active
      VES9*	VMS Concepts Course	Active
      VESa*	EsiBuilder - ACTSupportLibrary Class Library	Active
      VESAN*	ANTLR related	Active
      VESb*	EsiBuilder - EntityRepository Class Library	Active
      VESBR*	Business Rules	Active
      VESc*	EsiBuilder - Extractor Class Library	Active
      VESCA*	Common Methods	Active
      VESCD*	CommonDatabase Class Library	Active
      VESCM*	Courseware Delivery Driver	Active
      VESCnn	DataSharingCORBA Class Library where nn is a value incremented by the library creation logic. Theoretically it can overlap with other VESC* ranges but practically it will never will 	Active
      VESd*	EsiBuilder - Compiler Class Library	Active
      VESDB	EsiDB Project	Active
      VESDED*	Courseware Delivery Driver	Active
      VESDM*	Courseware Delivery M Parser	Active
      VESDAF*	Business Framework Library	Active
      VESDAO*	Business Object Library	Active
      VESDAA*	Business Apps Library	Active
      VESDS*	EsiBuilder - DatabaseSupport Class Library	Active
      VESe*	EsiObjects Extensions (Root)	Active
      VESE*	Authoring System	Active
      VESed*	ESIDOC	Active
      VESFM*	File Manager Wrapper	Active
      VESFrC*	EsiBuilder - EsiBuilderCompilers Class Library	Active
      VESFrE*	EsiBuilder - EsiBuilderExtractors Class Library	Active
      VESFrR*	EsiBuilder - EsiBuilderRepository Class Library	Active
      VESJAV	Java Libraries	Active
      VESM*	MSM System Management Course	Active
      VESo*	EsiObjects Library Generated Routines	Active
      VESO*	EsiObjects Core Routines	Active
      VESq*	Query related	Group
      VESQ*	Introduction to SQL Course	Active
      VESqE	EsiQuery	Active
      VESqO	OQL	Active
      VESqS	SQL	Reserved
      VESR*	Routine Editor for M Courses	Active
      VESTUT	EsiObjects Getting Started Tutorial	Active
      VESUTL	Utilities Library	Active
      VESUTT	RegressionTest Library
      VESVA*	DVAApplications Class Library	Active
      VESVB*	VistADatabase Class Library	Active
      VESVC*	VistA Object Broker (stand alone)	Active
      VESVD*	DVADatabase Class Library	Active
      VESVE*	DVAObjectBroker Library (integrated in VOS)	Active
      VESVF*	FullDVADatabase Library	Active
      VESxg*	EsiBuilder - ExtractorGeneratedClasses Class Library	?
      VESxo*	EsiBuilder - ObjectDataBaseModel Class Library	?
      VESZ*	Courseware Delivery Non-Standard M Routines	Active

   2. Globals

      Name	Assignment	Status
      ^VES	All courses assigned to first subscript.	Active
      ^VES2*	Introduction to MUMPS	Active
      ^VES4*	Intermediate MUMPS Programming	Active
      ^VES5*	Advanced MUMPS Programming	Active
      ^VESaC	EsiBuilder - ACTSupportLibrary Class Location	Active
      ^VESaD	EsiBuilder - ACTSupportLibrary Documentation Location	Active
      ^VESAN	ANTLR related	Active
      ^VESaS	EsiBuilder - ACTSupportLibrary Source Location	Active
      ^VESbC	EsiBuilder - EntityRepository Class Location	Active
      ^VESbD	EsiBuilder - EntityRepository Documentation Location	Active
      ^VESbS	EsiBuilder - EntityRepository Source Location	Active
      ^VESCBL(“DataSharing”)	DataSharingCORBA Integration Library	Active
      ^VEScC	EsiBuilder - Extractor Class Location	Active
      ^VEScD	EsiBuilder - Extractor Documentation Location	Active
      ^VESCOMAP	Common Methods	Active
      ^VESCOMDB	CommonDatabase Integration Library	Active
      ^VEScS	EsiBuilder - Extractor Source Location	Active
      ^VESDATA	Data storage and work area.	Active
      ^VESDBSUP	EsiBuilder - DatabaseSupport Integration Library	Active
      ^VESDBsup(“System”)	O%DBSupport	Active
      ^VESdC	EsiBuilder - Compile Class Location	Active
      ^VESdD	EsiBuilder - Compiler Documentation Location	Active
      ^VESdS	EsiBuilder - Compiler Source Location	Active
      ^VESDIR	Directory for Courses	Active
      ^VESDAF*	Business Framework Library	Active
      ^VESDAO*	Business Object Library	Active
      ^VESDAA*	Business Apps Library	Active
      ^VESDB	EsiDB Project – Database Layer	Active
      ^VESDF	EsiDB Project – Application Facade Layer	Active
      ^VESDVAAP	DVAApplications Library	Active
      ^VESDVADB	DVADatabase Library	Active
      ^VESDVADK	DVAObjectBroker Library	Active
      ^VESDVADF	FullDVADatabase	Active
      ^VESe*	EsiObjects Extensions	Active
      ^VESed*	ESIDOC	Active
      ^VESFM	File Manager Wrapper	Active
      ^VESFrC	EsiBuilderCompilers Library	Active
      ^VESFrE	EsiBuilderExtractors Library	Active
      ^VESFrR	EsiBuilderRepository Library	Active
      ^VESJAV	Java Support Library
      ^VESo	EsiObjects User Partition Globals	Active
      ^VESO	EsiObjects System Globals	Active
      ^VESOLINE	?	Active
      ^VESq*	EsiQuery Related	Group
      ^VESQ*	Introduction to SQL	Active
      ^VESqE	EsiQuery	Active
      ^VESqO	OQL	Active
      ^VESqS	SQL	Reserved
      ^VESR*	MUMPS Courses Routine Editor	Active
      ^VESTUTOR	EsiObjects Getting Started Tutorial	Active
      ^VESUTLS	Utilities Library	Active
      ^VESUTLT	RegressionTest Library	Active
      ^VESVC	VistA Object Broker (stand alone) Library	Active
      ^VESxcL	EsiBuilder - Compiler Library Location	Active
      ^VESxD	Dictaphone integration Class Library	Active
      ^VESxeL	EsiBuilder - Extractor Library Location	Active
      ^VESxgC	EsiBuilder - ExtractorGeneratedClasses Class Loc.	?
      ^VESxgD	EsiBuilder - ExtractorGeneratedClasses Doc. Loc.	?
      ^VESxgL	EsiBuilder - ExtractorGeneratedClasses Library Loc.	?
      ^VESxgS	EsiBuilder - ExtractorGeneratedClasses Source Loc.	?
      ^VESxodC	EsiBuilder - ObjectDataBaseModel Class Loc.	?
      ^VESxodD	EsiBuilder - ObjectDataBaseModel Doc. Loc.	?
      ^VESxodL	EsiBuilder - ObjectDataBaseModel Library Loc.	?
      ^VESxodS	EsiBuilder - ObjectDataBaseModel Source Loc.	?
      ^VESxrL	EsiBuilder - EntityRepository Library Location	Active
      ^VESxsL	EsiBuilder - ACTSupportLibrary Library Location	Active

   3. EsiObjects Routines Partitions

 

Namespace	Assignment	Status
VESOCEN*	Census	Active
VESOCES*	Common External Services	Active
VESOCM*	Common Services	Active
VESOD*	Debugging Support	Active
VESOE*	Call Executive	Active
VESOEN*	Environment	Active
VESOEP*	Exception Processing	Active
VESOER*	Error Support	Active
VESOEX*	External Interfaces	Active
VESOGT*	GTM Support	Active
VESOI*	Parser	Active
VESOIB*	Parser – Body	Active
VESOIC*	Parser – Commands	Active
VESOID*	Parser – Driver	Active
VESOIE*	Parser – Expressions	Active
VESOIM*	Parser – Main Structure	Active
VESOIT*	Parser – Tables	Active
VESOIU*	Parser – Utility	Active
VESOJ*	Job Support (Experimental)	Active
VESOL*	Lookup Support (Experimental)	Active
VESO(n)	Symbol Support	Active
VESONUL*	Null Object Support	Active
VESOOB*	Browsing Support	Active
VESOOP*	Runtime support	Active
VESOPEV*	Event Support	Active
VESOPM*	Inheritance Engines	Active
VESOR*	Runtime Support	Active
VESOS*	Sessions Support	Active
VESOTC*	TCP Support	Active
VESOU*	Utility	Active
VESOUF*	Utility – Input Driver	Active
VESOUXC*	Code Support	Active
VESOUXM*	XML Support	Active
VESOX*	Xecution Support	Active
VESOZ*	Primitive Class Browser	Active
VESDB*	EsiDB Project – Database Layer	Active
VESDF*	EsiDB Project – Application Facade Layer	Active
VESX*	Balboa, Easy-CHCS	Active
VEDXD*	Dictaphone integration

1. EsiObjects

   1. Use of Names

      1. Rules

1. EsiObjects names can be 32 characters in length.

2. They cannot have any embedded control or punctuation characters.

3. They consist of alphanumeric characters.

4. A name cannot begin with a numeric character.

1.  
   1.  

      1. Style

The recommended style to use for names is:

1. Use names that convey the meaning or purpose of the object being named.

2. Create a name by concatenating words together and capitalizing the words. For example: Patient, PatientName, AdmissionDate.

1.  

   1. Method and Property Code Bodies

This section outlines the style suggestions and rules for creating code bodies.

1.  
   1.  

      1. Header Information Rule

1. The first line of a code body is devoted to the copyright line if it is required (See the Copyright Format Rule section).

2. Code bodies should be initialized to include at a minimum the date and time it was created and who created it. The following macrocode provides a simple template to start with. EsiObjects lets you initialize different code bodies in different ways.

\t;;(c) Copyright 1994 - 2002, ESI Technology Corp, Natick MA

\t;; This source code contains the intellectual property of its copyright holder(s),

\t;; and is made available under a license. If you are not familiar with the terms

\t;; of the license, please refer to the license.txt file that is a part of the

\t;; distribution kit.

\t; %t

\t; Created: %c %p by %u

Input:\t(%4

\t)

\t; %3

\tQuit

1.  
   1.  

      1. Copyright Format Rule

Adding or not adding a copyright line to a method depends on where it is applied. You can use your personal preferences to generate the copyright automatically

 

1. If you are adding new methods or properties to Base, ESI or the VESO core routines of EsiObjects, the open source copyright applies. Make sure the following lines are inserted at the beginning of the new methods, properties or routines you create:

 

;;(c) Copyright 1994 - 2001, ESI Technology Corp, Natick MA

;; This source code contains the intellectual property of its copyright holder(s),

;; and is made available under a license. If you are not familiar with the terms

;; of the license, please refer to the license.txt file that is a part of the

;; distribution kit.

 

1. If you re creating a product specifically for ESI, simply insert the following line as the first line in the code body.

 

;;(c) Copyright 1994 - 2001, ESI Technology Corp, Natick MA

 

1. If you are creating new methods, properties or routines under contract to a government agency, do not put any copyright in the code body since it falls under the public domain laws UNLESS specifically instructed to do so.

1.  
   1.  

      1. Input Specification

         1. Style

1. It is recommended that the Input Specification be separated into lines and each line documented. The documentation should describe what is in the variable.

Input: (

Name:P%Name ;Contains the name of the patient: "Last name, First Initial"

Sex:P%Sex ;Contains the sex of the patient: "M" or "F"

)

1.  
   1.  
      1.  

         1. Rule

1. If there are more than one parameters use keywords so that the actual list parameters can be specified independently of position.

2. Always use the P% scope for parameter variables to identify them as such. Number 4 is an exception to this style convention.

3. If the value passed in on a parameter is to be bound to an instance or class variable directly, you may use that variable as the parameter.

Input: (

(In,Required)I%Name ;Passes patient name directly into the instance variable.

)

1. When a parameter variable is bound to an object, always use the Type= keyword to identify its type.

Input: (In,Required,Type=Demographics$Patient)Patient:I%Pat ;Patient object OID.

I%Name ;Passes patient name directly into the instance variable.

)

 

1. Always user the Required or Optional keywords on all parameters. This makes the Java proxy happy!

1.  
   1.  

      1. Options Specification

See the Options Specification Block section of the EsiObjects Language Guide for a list of all supported options.

1.  
   1.  
      1.  

         1. Style

1. It is recommended that the Options Specification be separated into lines and each line documented. The documentation should describe what is in the variable.

Options:(

Method,

Public,

Void,

Inheritable

)

1.  
   1.  
      1.  

         1. Rule

1. Always insert the Options block in every code body. The DocBuilder documentation generator to generate external documentation uses it.

1.  
   1.  

      1. Comment Line Rules

1. Code bodies should be commented liberally with meaningful comments, especially where code intentions are implied and not obvious.

2. Use a single semicolon (;) if you want the comment stripped out of the resultant compiled code.

3. Use a double semicolon if you want the comment line to remain in the compiled code. (Copyright lines should always start with contain the double semicolon to insure it getting in the M Intermediate and object code.)

1.  
   1.  

      1. Command, Functions and Special Variable Name Style

1. All command, function and special variable names should be spelled out in full.

2. Names should begin with a capital letter and the remaining letters should be lowercase.

Set T%OID=$Piece(T%String,"^",2)

1.  
   1.  

      1. Label Rules

1. When using line labels, make them meaningful.

2. Follow the label with a comment and description of what the subroutine or extrinsic function does.

Error(Message) ;Generates an error message using the Output pane.

1.  
   1.  

      1. Variable Rules

1. Always use T% for temporary variables, not A%. A% are obsolete.

2. For temporary variables, use P% for parameters and T% for variables created in the method body.

3. Use meaningful names to identify the variable content.

1.  

   1. Events

1. The Event editor is used for documentation only. Always document the event using this editor, especially the formal parameter structure used by the callback method.

2. Describe each variable in the parameter list within the event.

1.  

   1. Documentation

All levels of the EsiObjects hierarchy from libraries down to the individual services have documentation objects associated with them.

1.  
   1.  

      1. Rules

1. Document each level of a completed system appropriately.

2. Please use the following format (Template) when documenting items in EsiObjects (using the documentation panes). It is important to follow the style because the DocBuilder package uses the style when generating class documentation.

    

Description: Descriptive text here.

 

The description is the minimum documentation for an EsiObjects component. Additional sections should be added such as Responsibilities, etc.