VA FileMan V. 22.0 Programmer Manual Banner


 

Main Getting Started Manual Advanced User Manual

Orientation

Programming Conventions


NOTE: A knowledge of the M programming language is presumed throughout this manual. Unless otherwise noted, VA FileMan V. 22.0 is written following the 1995 ANSI MUMPS standard, with several Type A extensions.

Nonstandard M Features

Z-commands and Z-functions are avoided throughout VA FileMan routines. For certain purposes [such as allowing terminal breaking and spooling to a Standard Disk Processor (SDP) disk device], FileMan executes lines of nonstandard M code out of the MUMPS OPERATING SYSTEM file (#.7). The nonstandard code used (if any) depends on the answer to the prompt:

    TYPE OF MUMPS SYSTEM YOU ARE USING:

This prompt appears during the DINIT initialization routine. Answering OTHER to this question will ensure that VA FileMan uses only standard M code.

VA FileMan also makes use of nonstandard M code that is stored in the %ZOSF global. If FileMan is installed on a system that contains Kernel, it uses the %ZOSF global created by Kernel. If it is being used without Kernel (i.e., stand-alone), the necessary %ZOSF nodes are set for many operating systems by running DINZMGR in the manager account. See the "System Management" chapter of the "VA FileMan Advanced User Manual" for details.

String-valued subscripts (up to 30 characters long) are used extensively but only in the $ORDER collating sequence approved by the MUMPS Development Committee (MDC). Non-negative integer and fractional canonic numbers collate ahead of all other strings.

The $ORDER function is used at several points in VA FileMan's code. FileMan routines assume that reference to an undefined global subscript level sets the naked indicator to that level, rather than leaving it undefined. In all other respects, the FileMan code conforms to the 1995 ANSI Standard for the M language with Type A extensions.

Routine, Variable, and Global Names

In keeping with the convention that all programs which are a part of the same application or utility package should be namespaced, all VA FileMan routine names begin with DI or DD. (The "Device Handling for Standalone VA FileMan" section of the "VA FileMan Advanced User Manual" explains that some DI* routines are renamed in the management account.) The DINIT routine initializes FileMan. The DI routine itself is the main option reader (see the "^DI: Programmer Access" chapter.

Except in DI, the routines do not contain unargumented or exclusive KILL commands. All multi-character local variable names created by VA FileMan routines begin with % or the letter D, or consist of one uppercase letter followed by one numeral (except that IO(0), by convention, contains the $I value of the signon device). Since FileMan uses single character variable names extensively, do not use them in code that is executed from within FileMan programming hooks unless their use is documented in the hook's description or you New them. Also, do not expect single character variables to return unchanged after calling a FileMan entry point.

The following local variables are of special importance in the routines:

Variable Description
DT if defined, is assumed to be the current date. For example, June 1, 1987 is DT=2870601.
DTIME if defined, is the integer value of the number of seconds the user has to respond to a timed read.
DUZ if defined, is assumed to be the User Number, a positive number uniquely identifying the current user.
DUZ(0) if defined, is assumed to be the FileMan Access Code, a character string describing the user's security clearance with regard to files, to templates, and to data fields within a file. See the chapter on "Data Security" in the "VA FileMan Advanced User Manual." Setting DUZ(0) equal to the @-sign overrides all security checks and allows special programmer features which are described later. If the user's M implementation supports terminal break, a programmer is allowed to break execution at any point, whereas a user who does not have programmer access can only break during output routines.
U if defined, is equal to a single up-arrow (^) character.

If not defined, the default values set for these variables are:

Variable Default Value
DT today's date, derived from $H
DTIME 300
DUZ 0
DUZ(0) ""
U "^"

VA FileMan routines explicitly refer to the following globals:

Global Description
^DD All attribute dictionaries
^DDA Data dictionary audit trail
^DI Data types
^DIA Data audit trail
^DIAR Archival activity and filegrams
^DIBT Sort templates and the results of file searches
^DIC Dictionary of files
^DIE Input templates
^DIPT Print templates and filegram templates
^DIST ScreenMan forms and blocks and Alternate Editors
^DISV Most recent lookup value in any file or subfile (by DUZ)
^DIZ Default location for new data files as they are created
^DOPT Option lists
^DOSV Statistical results
^%ZOSF M vendor-specific executable code

The routines use the ^UTILITY and ^TMP globals for temporary scratch space. The ^XUTL global is also used if you are running some M implementations.

Delimiters within Strings

The up-arrow (^) character is conventionally used to delimit data elements which are strung together to be stored in a single global node. A corollary of this rule is that the routines almost never allow input data to contain up-arrows; the user types an up-arrow (^) to change or terminate the sequence of questions being asked. Within ^-pieces, semicolons are usually used as secondary delimiters and colons as tertiary delimiters.

VA FileMan routines use the local variable U as equal to the single up-arrow (^) character.

Canonic Numbers

VA FileMan recognizes only canonic numbers. A canonic number is a number that does not begin or end with meaningless zeroes. For example, 7 is a canonic number, whereas 007 and 7.0 are not.

 


Reviewed/Updated: March 10, 2007