![[skip navigation]](images/clr_pxl.gif){kind=small}
|
|
|
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.
The $VIEW function is used to directly examine memory. The use of $VIEW is restricted to Kernel and VA FileMan.
Structured System Variable Names (SSVNs) are a mechanism used to provide programmatic information to certain system information and are covered in Section 7.1.3 of the M language standard. The use of SSVNs is restricted to Kernel.
Common SSVNs include the following:
The BREAK command is prohibited except for Kernel.
If applications ever need to use BREAK, they should use ^%ZOSF("BRK") and ^%ZOSF("NBRK") instead.
In M, use extended references to refer to routines or globals outside the current environment (called a namespace in Caché). The use of extended references is restricted to Kernel.
Section 2.2.1 of the SAC specifies the format of the first line of a routine as follows:
2.2.1 The first line of a routine must be in the following format: routine name <ls>; site/programmer<space>-<space>brief description [optional space];date [time is optional].
ZZAA12 ;DALOI/XXX - Example Routine;2/13/07
NOTE: M editors frequently modify the first line of a routine.
In VistA, the second line of routines records the following information:
Section 2.2.2 of the SAC specifies the second line format as follows:
2.2.2 The second line of a routine must be in the following format: [LABEL-optional]<ls>;;version number; package name; **pm,...pn**; version date;Build n where:
;;1.0;PACKAGE;**pm,…pn**;Feb 1, 2007;Build 1
The list of patch numbers must fall between the set of asterisks (**) and be separated by commas as shown in Section 2.2.2 of the SAC.
The HALT command is used to cause a program to exit; this is not a common requirement in VistA. If for some reason a routine needs to halt, you must first perform certain housekeeping tasks. Kernel provides an API to cleanly halt a program. Application programs cannot use the HALT command.
This reported error message is out of date; applications should use H^XUS (see Section 2.4.3 of the SAC).
Kernel makes use of certain local variables to maintain a standard environment for processes. Applications cannot KILL the following variables:
The SAC specifies that unsubscripted globals shall be KILLed:
2.3.2.3 The KILLing of unsubscripted globals is prohibited and should be protected. (Special instruction to the site will be required to enable the KILLing of a unsubscripted global. Application developers must document when calls to EN^DIU2 are made to delete files stored in unsubscripted globals).
Kernel maintains a set of local variables that cannot be SET nor KILLed. The unargumented KILL is prohibited except for Kernel.
The use of the exclusive KILL is prohibited except for Kernel.
The exclusive NEW command is the same as the exclusive KILL and is restricted except for Kernel.
The only situation in which application routines are allowed to use the LABEL+OFFSET syntax to refer to lines of code is when using $TEXT to retrieve data lines. For example, it cannot be used in conjunction with a DO or GOTO command.
Lines of code cannot be longer than 245 bytes.
In M, a LOCK command may include a timeout. If the specified timeout period expires before obtaining the lock, the LOCK command fails. In VistA, application programs are required to specify a timeout when using this command. If for some reason it is necessary to use a LOCK with no timeout (e.g., to manage collaborating processes), an exemption is required.
NOTE: Kernel can use locks without a timeout. Kernel can also use non-incremental and unargumented locks.
The rules regarding variable case have been relaxed somewhat in the most recent revision of the SAC. The relevant sections are:
2.2.5 The line body must contain at least 1 printable character, must not exceed 245 characters in length, and must contain only the ASCII characters values 32-126. Line labels, global variable names, system variables, SSVNs, etc. must be uppercase.
2.3.1.1 Local variable names may not exceed sixteen characters. Namespaced variables may not contain lowercase characters. Variables local to a routine, subroutine or DoDot may be any case. Any variable containing lowercase characters must be NEWed at the beginning of the routine, subroutine or DoDot.
All M commands must be upper case. They can be spelled out or abbreviated to the first character.
M allows locks to be one of the following types:
AApplication programs are required to use the incremental form of the LOCK command.
NOTE: This restriction does not apply to Kernel.
M implementations may provide special functions with names beginning with $Z.. These are platform dependent. Application programs cannot use them.
NOTE: This restriction does not apply to Kernel.
M implementations may provide special variables with names beginning with $Z.. These are platform dependent. Application programs cannot use them.
NOTE: This restriction does not apply to Kernel.
Applications cannot directly use the OPEN and CLOSE commands. Instead, they must use the Kernel Device Handler.
NOTE: This restriction does not apply to Kernel, MailMan, and VA FileMan. See the noted exemptions in Section 2.4.8.1 of the SAC.
This error is a bit misleading, because there are now several APIs other than ^%ZIS that can be used. This includes:
Regardless, applications must use one of the ^%ZIS* APIs and cannot use OPEN directly.
REF: For more details of the CLOSE command, see the " S—'Close' command should be invoked through 'D ^%ZISC'" section.
Kernel's Device Handler encapsulates certain I/O-related commands (e.g., OPEN and CLOSE) and provides a common device abstraction used by VistA applications. Applications are required to use the Device Handler.
At one time, devices were always opened using D ^%ZIS and closed using D ^%ZISC, but that is no longer true. Kernel provides some additional APIs:
If a device is opened using OPEN^%ZISUTL, it must be closed with CLOSE^%ZISUTL. Do not close the device through the CLOSE command.
Application programs must provide a timeout (usually the variable DTIME) when using the READ command. In fact, it is good practice for applications to not use READ at all, but use the VA FileMan ^%DIR API (commonly known as the "Response Reader"); though, this is not a requirement. It is, however, a requirement to use a timeout.
In addition, if a timeout exceeds 300 seconds, you must document that fact in the package technical manual.
If for some reason this is inappropriate, an exemption is required.
The maximum routine size for M code and ;; comments (comments beginning with double semi-colons are considered code) is set to 15K characters in a routine.
NOTE: An additional 5K characters in a routine is available for regular comments (i.e., comments beginning with a single semi-colon).
The maximum routine size as determined by ^%ZOSF("SIZE") is set to 20K for all characters in a routine.
Application programs cannot modify globals with names beginning with %.
NOTE: This restriction does not apply to Kernel.
This is a requirement. Application programs cannot start background processes with the JOB command, but must use one of the APIs provided by TaskMan.
NOTE: This restriction does not apply to Kernel.
The VIEW command is used to modify memory or disk buffers. Use of this command is restricted to Kernel and VA FileMan.
REF: For more details about VIEW and $VIEW, see the "S—$View function used" section.
This is something of a catchall category and requires manual review for violations of VA programming standards.