.ps 58,80
.lm 8.rm 72
.p 0,1,4.ap
.sp 1
.fl bold ~.ebo
.sthl 5,0,6,7,7,2,1,7,2
.display number RL
.figure 20
.c;VAX-11 Modula-2
.c;User's Guide
.b 4
.lm +16
.s.i -12;Abstract:###This document describes how to compile,
link and execute Modula-2 programs on a VAX-11 under the VMS
operating system. The VAX-11 Modula-2 Compiler is based on an
implementation of Modula-2 for the PDP-11 developed by a group
under the direction of Prof. N. Wirth at the ETH Zuerich.
.lm -12
.page
.c;Table of Contents
.require "MODULA.RNT"
.page
.c;^~PREFACE\~

^&Use of This Document:\&

The VAX-11 Modula-2 User's Guide has been designed to support the
development and execution of Modula-2 programs in the VAX/VMS
environment. The programming language itself is described in
N.Wirth, "Programming in Modula-2".

It is assumed that the reader has a general knowledge of the
VAX/VMS Command Language and the Modula-2 programming language.
In some sections, a more detailed understanding of the operating
system is required. The reader should consult the corresponding
manuals for the information needed.

^&Related Documents:\&

N. Wirth, "Modula-2 Report", in N. Wirth "Programming in
Modula-2", Springer Verlag, Heidelberg, New York, 1982.
.b
VAX-11 Symbolic Debugger Reference Manual.
.b
VAX-11 Linker Reference Manual.
.b
VAX Architecture Handbook.
.b
VAX-11 PASCAL User's Guide.
.b
VAX-11 Run-Time Library Reference Manual.
.b
VAX/VMS System Services Reference Manual.

^&Notational Conventions:\&

Within command language descriptions
.lm +8
.s.i-4;^~[#]\~#bold square brackets indicate that the enclosed sequence
of bold symbols is optional,
.s.i-4;{#}#braces indicate that the enclosed sequence of symbols
may be repeated zero or more times.
.lm -8

Descriptions of Modula-2 components follow the notational
conventions of the Modula-2 Report.
.display number D
.chapter ^~Using Modula-1 Under VAX/VMS\~
.lm 8
.rm 72
.hl 1 Creating and Executing a Program (Overview)
In general, Modula-2 programs are composed of separate modules.
The first step in creating an executable program is to edit the
different source files containing the compilation units (main
module, definition modules, implementation modules).
.note
The Modula-2 compiler distinguishes upper and lower case
characters. Hence, all identifiers must be spelled
exactly as they are defined. All reserved words and
standard names must be capitalized.
.end note

Source files are compiled separately. The order in which this
has to be done depends on the import/export relationships between
the modules. In particular, definition modules must be compiled
prior to the corresponding implementation modules.

Two kinds of output files are produced (besides an optional
listing file):

Processing a definition file results in a symbol file, containing
a coded module description readable by the compiler. This file
is needed when the implementation module or a compilation unit
importing the module is compiled.

The result of processing an implementation or main module is an
object file readable by the linker.

Finally, the separate object files have to be linked together to
form an executable image file. Execution of this file can be
started by the RUN command.
.hl 1 File Specifications and Defaults
.x file spec
A full VAX/VMS file specification has the following form:

####node::device:[directory]filename.filetype;version

Node, device, directory, and version are optional items;
their default values are:
.lm +16
.s.i -12;node:#######applicable only to systems supporting DECnet-VAX,
.s.i -12;device:#####user's current device,
.s.i -12;directory:##user's current default directory,
.s.i -12;version:####highest version on input,
highest version+1 on output.
.lm -16

The filetype specification may be omitted in certain cases. The
default type depends on usage:
.x file spec>defaults
.x defaults>file types
.b
.nf
.lm +4
MOD  input to Modula-2 compiler
SYM  input to and output from Modula-2 compiler
OBJ  output from Modula-2 compiler
LIS  source file listing
.b
OBJ  input to linker
EXE  output from linker
MAP  linker map file
.lm -4
.f
.chapter ^~COMPILING A MODULE\~
.lm 8
.rm 72
.x compiling modules
Each Modula-2 compilation unit has to be compiled separately.
In the case of a definition module a symbol file is
created, an object file otherwise. Optionally a source file
listing may be produced. The compiler also searches for
and reads the symbol files belonging to imported modules. If
not specified otherwise, a standard search strategy is
applied (see 2.3). The Modula-2 compiler is invoked by the
MODULA command which has the following form:

####$ MODULA {/qualifier} file-spec {/qualifier}

^&file-spec\&
.lm +4

determines the source file containing the module to be
compiled. Only one file is accepted. The default file type
is MOD. Type DEF is recommended for definition modules.
.lm -4

In interactive mode, you can also enter the file specification on
a separate line by typing a carriage return after you type
MODULA. The system responds with a prompt for the file
specification:

####$ MODULA <return>
.br
####$__File:

Processing of a source file comprises several passes. Temporary
work files named INTERFILE.MVC serve for interpass
communication. The normal succession of passes is for definition
modules
.b
.lm +4
.list 0
.le;syntax analysis
.le;declaration analysis
.le;symbol file generation
.le;listing generation (optional)
.els
.lm -4

and for implementation and main modules
.b
.lm +4
.list 0
.le;syntax analysis
.le;declaration analysis
.le;body analysis
.le;code generation
.le;listing generation (optional).
.els
.lm -4
.hl 1 Modula-2 Compiler Qualifiers
.x compiler qualifiers
MODULA command qualifiers control optional compiler settings.
For every qualifier there is a negative form to suppress the
respective effect. The negative form is indicated by a leading
"NO", e.g., "NOLIST" is the negative form of "LIST". The
meanings of the qualifiers and their default values are listed
below.
.lm +4
.tp 5
.x compiler qualifiers><CHECK
.s.i -4;^~CHECK\~

Code is generated to perform run-time checks for out-of-range
array bounds and case labels.

By default, CHECK is enabled.
.tp 6
.x compiler qualifiers><CROSS__REFERENCE
.s.i -4;^~CROSS__REFERENCE\~

A cross reference table is included in the source listing.
This qualifier is effective only when used in conjunction with
LIST.

By default, CROSS__REFERENCE is disabled.
.tp 6
.x compiler qualifiers
.s.i -4;^~DEBUG\~

The DEBUG qualifier produces information to be used by the
VAX-11 Symbolic Debugger and the run-time error reporting
mechanism.

By default, DEBUG is disabled and only traceback information
is generated.
.tp 5
.x compiler qualifiers><LIST
.s.i -4;^~LIST\~

A listing file is written. The qualifier has the general
form:

####/LIST~[=file-spec-list~]

You may include a file specification for the listing file. If
no specification is given a file of type LIS with the name of
the source file is created. The file contains at least the
source text and the error messages, but further listings are
added by applying CROSS__REFERENCE and/or MACHINE__CODE.

By default, LIST is disabled for interactive mode and enabled
for batch mode (but note that even in batch mode the listing
file is not automatically printed!).
.tp 5
.x compiler qualifiers><TERMINAL
.s.i -4;^~TERMINAL\~

If the TERMINAL option is enabled, the following information is
displayed:
.b
.nf
.lm +4
compiler version,
succession of the compiler passes, and
the names of the symbol files read.
.lm -4
.f

By default, TERMINAL is disabled for interactive mode and enabled
for batch mode.
.tp 6
.x compiler qualifiers><MACHINE__CODE
.s.i -4;^~MACHINE__CODE\~

A readable representation of the generated code is included in
the source listing. This qualifier is effective only in
conjunction with the LIST qualifier.

By default, MACHINE__CODE is disabled.
.tp 5
.x compiler qualifiers><OBJECT
.s.i -4;^~OBJECT\~

An object file for the linker is produced. The qualifier has
the form:

####/OBJECT~[=file-spec~]

You may specify a file for the object module. The default is
a file of type OBJ which takes the name of the source file.
If the source file contains a definition module this qualifier
has no effect.

By default, OBJECT is enabled for main and implementation
modules, disabled otherwise.
.tp 5
.x compiler qualifiers><QUERY
.s.i -4;^~QUERY\~

The QUERY qualifier forces the compiler to ask explicitly for
the symbol files to be read.

By default, QUERY is disabled and the compiler uses a standard
strategy to search for the symbol files (see 2.3).

The standard search strategy is also effective when QUERY is
enabled but no file specification is given.
.tp 5
.x compiler qualifiers><SYMBOL__FILE
.s.i -4;^~SYMBOL__FILE\~

A symbol file is created if the source contains a definition
module. It has the form:

####/SYMBOL__FILE~[=file-spec~]

You may supply an optional file specification for the symbol
file. The default is a file of type SYM with the name of the
source file.

By default, SYMBOL__FILE is enabled for definition modules,
disabled otherwise.
.lm -4
.test page 22
.figure 2
.c;Summary
.c;MODULA Command Qualifiers
.literal
+--------------------------+--------------------+------------------------+
| Qualifier                | Negative Form      | Default                |
+--------------------------+--------------------+------------------------+
| /CHECK                   | /NOCHECK           | /CHECK                 |
| /CROSS_REFERENCE         | /NOCROSS_REFERENCE | /NOCROSS_REFERENCE     |
| /DEBUG                   | /NODEBUG           | /NODEBUG               |
| /LIST[=file-spec]        | /NOLIST            | /NOLIST (interact)     |
|                          |                    | /LIST (batch)          |
| /TERMINAL                | /NOTERMINAL        | /NOTERMINAL (interact) |
|                          |                    | /TERMINAL (batch)      |
| /MACHINE_CODE            | /NOMACHINE_CODE    | /NOMACHINE_CODE        |
| /OBJECT[=file-spec]      | /NOOBJECT          | /OBJECT                |
| /QUERY                   | /NOQUERY           | /NOQUERY               |
| /SYMBOL_FILE[=file-spec] | /NOSYMBOL_FILE     | /SYMBOL_FILE           |
+--------------------------+--------------------+------------------------+
.end literal
.hl 1 Local Control of Run-Time Checks
.x run-time checks
The insertion of run-time checks into the generated code can
additionally be controlled during compilation by using the
T-option. The T-option must be entered into the source text at
the beginning of a comment clause; it has the general form:

####TOption = "$T" Switch
.br
####Switch = "+"|"-"|"="

where the associated switch

####+###enables run-time checks,
.br
####-###disables run-time checks,
.br
####=###resets the option to the previous value.

Examples:

####(* $T+ to generate test code *)
.br
####(* $T- to turn off test code generation *)
.hl 1 Search Strategies
.x search strategies
In the default case (i.e., when no file name is specified in
query mode) the compiler applies a standard strategy to search
for the symbol files needed: The default file name is
constructed out of the first 9 characters of the module's name
and a file type SYM is assumed.

The file is first searched in the user's default directory. If
the search fails, directories with the logical names MOD$LIBRARY,
MOD$LIBRARY__1 up to MOD$LIBRARY__9 are searched (in this order).
This search is repeated for all three logical name tables
(process, group, system). Each search terminates when the first
undefined logical name is encountered. If the file has not yet
been found, the directory with the logical name MOD$SYSTEM is
searched.

The result of the searching process is displayed to the user when
the SYMBOL__FILE option is enabled.
.hl 1 Compiler Listing
.x compiler listing
The contents of the listing is controlled by the command
qualifiers LIST, CROSS__REFERENCE, and MACHINE__CODE. The
application of LIST is necessary to obtain a listing at all.

Each listing page has a two line heading. The first line
contains (from left to right):
.lm +8
.s.i -4;o###the name of the compilation unit,
.i -4;o###the date of compilation,
.i -4;o###the compiler version, and
.i -4;o###a running page number.
.lm -8

In the second line you will find
.lm +8
.s.i -4;o###the listing subject,
.i -4;o###the creation date, and
.i -4;o###the name of the source file.
.lm -8

The listing terminates with a compilation summary, informing
about the active compiler options and giving some performance
information.
.hl 2 Source Listing
.x compiler listing
Initiated by LIST.

The source list contains a copy of the source file preceded by
the compiler-generated line numbers. Error messages are inserted
after the erroneous lines. The position where an error has been
detected is marked by an arrow.
.hl 2 Cross Reference Table
.x cross reference
Initiated by CROSS__REFERENCE, presupposes LIST.

The cross reference table presents all identifiers defined or
accessed in the compilation unit in alphabetical order. Standard
names are not tabulated.

Each table entry consists of at least two items: the identifier
and its declaration class. The latter distinguishes constants,
types, variables, parameters (value and variable), fields,
procedures, functions, and modules.

Further specifications which may follow are:
.lm +4

A short type characterization enclosed in angle brackets. For
subranges the base type is denoted; if the type has been
denoted by a synonym, the original type name is given. This
item is omitted for hidden types, predefined types,
procedures, and modules.

The name of the scope in which the identifier is defined,
preceded by "in" or "from". The prefix "from" indicates that
the defining scope is external. Alternatively, the word
"imported" may appear if the name designates an external
module. This item is omitted when the name is defined at
global level.

The word "exported", which means that the identifier is
exported from the enclosing module.

A list of numbers of the lines where the name is referenced.
A definition line is marked by an asterisk.
.lm -4

Included in the table are also identifiers imported indirectly
(as part of another imported identifier), although they are not
referenced in the source text. There is, of course, no list of
line numbers in this case.
.hl 2 Machine Code Listing
.x machine code listing
Initiated by MACHINE__CODE, presupposes LIST.

The generated code is represented as a VAX-11 MACRO program
source listing. Correspondence with the source text is
established via the line numbers inserted as comments on the
right hand side.
.chapter ^~LINKING A PROGRAM\~
.lm 8
.rm 72
.x linking a program
After compilation, the separate object modules are linked
together to produce an executable image file.
.hl 1 The Link Command

To link the modules, use the LINK command in the following form:

####$ LINK{/command qualifier} file-spec-list
.lm +4
.s.i -4;^&command qualifiers\&

Specify output file options.
.s.i -4;^&file-spec-list\&

Specifies the input files to be linked. File specifications
can be separated by commas or plus signs.
.lm -4

To create executable code you must specify all your object files
to be linked, except the ones stored in the default link
libraries. The first file named should contain the main program
(module).

By default, object files are assumed to be of type OBJ.

If no other specification is given, the executable image file
takes the name of the first object file and is of type EXE.

In interactive mode you may enter the file specifications on a
separate line by typing a carriage return after the command name.
The system responds with a prompt for the file specification.
.hl 1 Linker Command Qualifiers
.x linker qualifiers
Below, a few qualifiers are listed which may be of interest to
the Modula-2 programmer. For some qualifiers there are also
negative fodetailed information.
.hl 2 Map File Qualifiers
.x linker qualifiers><MAP
The MAP qualifier directs the linker to generate a map file
containing a summary of the image's characteristics, a list of
contributing modules, and a list of global symbols and values.
The qualifier has the form:

####/MAP~[=file-spec~]

where the optional file specification designates the map file.
The default is a file of type MAP with the name of the first
object file.

By default, MAP is disabled for interactive mode and enabled for
batch mode.

In conjunction with /MAP the modifying qualifiers BRIEF or FULL
and CROSS__REFERENCE may be used.

/BRIEF and /FULL define the amount of information included in the
map file, as follows:
.lm +4

/BRIEF produces a summary of the image's characteristics and a
.x linker qualifiers><MAP></BRIEF
list of contributing modules.

/FULL adds a summary of characteristics of image sections in
.x linker qualifiers><MAP></FULL
the linked image to the normal map file.
.lm -4

/CROSS__REFERENCE can be used with /MAP or /MAP/FULL to include
.x linker qualifiers><MAP></CROSS__REFERENCE
cross-reference information for global symbols in the map file.

By default, CROSS__REFERENCE is disabled
.hl 2 Debugging and Traceback Qualifiers
.x linker qualifiers><DEBUG
If the DEBUG qualifier is used, the program will always be
executed under the control of the debugger. (You may suppress
this by issuing /NODEBUG with the RUN command.)

By default, DEBUG is disabled.

The TRACEBACK qualifier is used to have error messages
.x linker qualifiers><TRACEBACK
accompanied by symbolic traceback information.

By default, TRACEBACK is enabled.
/DEBUG implies /TRACEBACK.
.test page 16
.figure 2
.c;Summary
.c;Link Command Qualifiers
.b
.c;+----------------------+-----------------+---------------------+
.c;| Qualifier            | Negative Form   | Default             |
.c;+----------------------+-----------------+---------------------+
.c;| /BRIEF               | None            | Not applicable      |
.c;| /CROSS__REFERENCE     | /NOCROSS__...    | /NOCROSS__REFERENCE  |
.c;| /DEBUG               | /NODEBUG        | /NODEBUG            |
.c;| /FULL                | None            | Not applicable      |
.c;| /MAP~[=file-spec~]     | /NOMAP          | /NOMAP (interact.)  |
.c;|                      |                 | /MAP (batch)        |
.c;| /TRACEBACK           | /NOTRACEBACK    | /TRACEBACK          |
.c;+----------------------+-----------------+---------------------+
.hl 1 Identification Checking
.x indentification checking
The VAX-11 Modula-2 compiler provides identification information
for describing the relationship between symbol files and object
files belonging to the same module. This identification is in
fact the compilation date and time of the corresponding
definition module and it is passed to the linker in the form of
an Entity Ident Consistency Check subrecord.

The linker checks the Entity Ident Consistency Check subrecord of
each object module before it links them together. If object
files of two modules importing different versions of the same
definition module are encountered the linker issues a warning
message. In such a case, the object files giving rise to the
message should be replaced by newly compiled ones.

For more information about the Entity Ident Consistency Check
subrecords, see the ^&VAX-11 Linker Reference Manual\&.
.chapter ^~EXECUTING A PROGRAM\~
.lm 8
.rm 72
.x executing programs
The RUN command starts the execution of an executable image file.
It has the form:


####$ RUN~[/~[NO~]DEBUG~] file-spec

The file name must be specified; the file type may be omitted,
EXE is assumed in this case.

The DEBUG qualifier allows to run the program under control of
the debugger, even if you have issued the MODULA and LINK
commands without this qualifier. /NODEBUG will override a /DEBUG
given at link time.

In interactive mode, the file specification is entered on a
separate line by typing a carriage return after the command name.
The system responds with a prompt for the file specification.
.hl 1 Debugging the Program
.x debugging
Currently, the VAX-11 Symbolic Debugger runs Modula-2 programs
with the language mode set to PASCAL. See the corresponding
chapter of the ^&VAX-11 PASCAL User's Guide\& (or the ^&VAX-11 Symbolic
Debugger Reference Manual\&) for a description. Because of the
differences between the two languages, some features work
differently, as there are:
.lm +8
.s.i -4;o###No distinction is made between lower and upper case letters in
identifiers.
.s.i -4;o###Nested modules are not recognized; all variables and
procedures declared inside a nested module are made global to
the compilation unit.
.s.i -4;o###Module bodies are treated as parameterless procedures with the
names of the modules.
.note
The differences mentioned above may lead to name
conflicts inside the debugger, which are not always
handled properly.
.end note
.s.i -4;o###Type CARDINAL is treated as INTEGER.
.s.i -4;o###All variables and procedures can only be accessed in the
context of the module they are defined in (see the debugger
commands SET MODULE, SET SCOPE).
.s.i -4;o###In addition to PASCAL, the source file information is present
for Modula-2 programs. Thus, the debugger commands related to
source files can be used (e.g. TYPE, SET STEP SOURCE,
EXAMINE/SOURCE, and SET SOURCE).
.s.i -4;o###Sets are displayed and must be entered in PASCAL notation,
using square brackets ("[", "]").
.s.i -4;o###Open array parameters are known to the debugger as fixed size
arrays with a lower bound of 0 and an upper bound of 2**16-1.
.s.i -4;o###Constant and type identifiers are not known to the debugger.
.s.i -4;o###All tagfields and fields in record variants are known as
ordinary record fields to the debugger, i.e., the tagfield and
variant information is not present.
.lm -8
.hl 1 Sample Terminal Session
Suppose you have edited three source files:

a definition module EXAMPLE1.DEF,
.b
.lm +8
.nf
DEFINITION MODULE Example1;
EXPORT QUALIFIED ...
...
END Example1.
.lm -8
.f

the corresponding implementation module EXAMPLE1.MOD,
.b
.lm +8
.nf
IMPLEMENTATION MODULE Example1;
FROM InOut IMPORT ...
FROM Storage IMPORT ...
...
END Example1.
.lm -8
.f

and a main module MAIN.MOD.
.b
.lm +8
.nf
MODULE Main;
FROM Example1 IMPORT ...
FROM Example2 IMPORT ...
...
END Main.
.lm -8
.f

The dialog to run the complete program might now appear as
follows (user input underlined):
.b
.nf
$ ^&MODULA EXAMPLE1.DEF <return>\&
                              ! the definition module must
                              ! be compiled prior to the
                              ! implementation module
.b
$ ^&MODULA/TERMINAL/LIST EXAMPLE1 <return>\&
                              ! compiles EXAMPLE1.MOD and
                              ! produces a source listing.
                              ! TERMINAL is enabled:
VAX-11 Modula-2 V3.1 compiling DSK1:[301100]EXAMPLE1.MOD;2/LIST
Syntax analysis
 Example1: DSK1:[301100]EXAMPLE1.SYM;1
 InOut: DSK1:[301100]INOUT.SYM;1
 Storage: DSK1:[301100]STORAGE.SYM;2
Declaration analysis
Body analysis
Code generation
Listing generation
$ ^&MODULA/QUERY MAIN <return>\&
                              ! in query mode, the compiler will
                              ! prompt for the symbol files
                              ! needed
 Example1> ^&<return>\&
                              ! standard search strategy
DSK1:[301100]EXAMPLE1.SYM;1
 Example2> ^&INSTANCE2 <return>\&
DSK1:[301100]INSTANCE2.SYM;3
                              ! INSTANCE2.SYM will be read
$ ^&LINK MAIN,EXAMPLE1,EXAMPLE2 <return>\&
                              ! links MAIN.OBJ, EXAMPLE1.OBJ and
                              ! EXAMPLE2.OBJ, InOut and Storage
                              ! will usually be contained in a
                              ! link library;
                              ! note that the first name must
                              ! designate the main module
.b
$ ^&RUN MAIN <return>\&
                              ! executes MAIN.EXE
.f
.chapter ^~INPUT AND OUTPUT\~
.lm 8
.rm 72
.x I/O
Since I/O operations are not part of the language itself,
together with the compiler a collection of probably useful
functions is provided by means of external modules

Among the modules distributed are (source files in parantheses):
.b
.lm +8
.nf
InOut                   (INOUT.DEF)
Terminal                (TERMINAL.DEF)
FileSystem              (FILESYSTE.DEF)
Conversions             (CONVERSIO.DEF)
FileNames               (FILENAMES.DEF)
FileLookup              (FILELOOKU.DEF)
TextIO                  (TEXTIO.DEF)
TTIO                    (TTIO.DEF)
.lm -8
.f

InOut, Terminal, FileSystem are also described in the appendix.
.chapter ^~PROCEDURE CALLING CONVENTIONS\~
.lm 8
.rm 72
.x calling conventions
In the context of the VAX/VMS operating system, a procedure is a
routine entered by a CALL instruction. In a Modula-2 program,
such a routine can be a function or a procedure written in
Modula-2, a VAX/VMS system service, or a VAX-11 Run-Time Library
procedure.

This chapter provides information on the calling conventions used
by the VAX-11 Modula-2 compiler and on calling VAX/VMS system
services and VAX-11 Run-Time Library procedures. A basic
knowledge of the VAX-11 procedure calling and argument passing
mechanisms is assumed. For more information see the ^&VAX-11
Run-Time Library Reference Manual\& and the ^&VAX-11 Architecture
Handbook\&.

VAX-11 Modula-2 uses the VAX-11 CALLS instruction to call
procedures. Each time a procedure is called, the Modula-2
compiler constructs an argument list on the stack. The arguments
in the list are based on the parameter type and the parameter
kind (value or reference) specified in the formal parameter list
and the values in the actual parameter list.
.hl 1 Parameter Passing Mechanisms
.x calling conventions>parameter passing
.x parameters
The VAX-11 procedure calling standard defines three mechanisms by
which arguments are passed to procedures:
.b
.lm +4
.list 0
.le;by-reference
.le;by-immediate-value
.le;by-descriptor
.els
.lm -4
The following table describes the mechanisms that are used by the
VAX-11 Modula-2 compiler, depending on the type and the kind of
the formal parameter:
.test page 30
.figure 2
.c;+--------------+---------------------+---------------------+
.c;| type         | value parameter     | reference parameter |
.c;+--------------+---------------------+---------------------+
.c;| BOOLEAN      |                     |                     |
.c;| CHAR         |                     |                     |
.c;| INTEGER      |                     |                     |
.c;| CARDINAL     |                     |                     |
.c;| POINTER      |                     |                     |
.c;| SET          |                     |                     |
.c;| Enumeration  |                     |                     |
.c;| Subrange     |                     |                     |
.c;| BYTE         |  by-reference       |  by-reference       |
.c;| SHORTWORD    |                     |                     |
.c;| WORD         |                     |                     |
.c;| ADDRESS      |                     |                     |
.c;| REAL         |                     |                     |
.c;| D__FLOATING   |                     |                     |
.c;| G__FLOATING   |                     |                     |
.c;| H__FLOATING   |                     |                     |
.c;| QUADWORD     |                     |                     |
.c;| OCTAWORD     |                     |                     |
.c;+--------------+---------------------+---------------------+
.c;| RECORD       |  by-reference       |  by-reference       |
.c;| ARRAY        |                     |                     |
.c;+--------------+---------------------+---------------------+
.c;| PROCEDURE    |               by-reference                |
.c;+--------------+---------------------+---------------------+

An open array parameter is passed by two arguments.

The parameter list created by the compiler for an open array
parameter definition

####(...;##a:##ARRAY#OF#type;##...)

is equivalent to the following foreign parameter definition (see
below)

####(...;#%IMMED#higha:#CARDINAL;#%IMMED#adra#:#ADDRESS;#...)

with adra = ADR(a) and higha = HIGH(a).
.hl 1 Function Return Values
.x calling conventions>function return
.x function return values
A function returns a value to the calling program. The method by
which a value is returned depends on its type as listed below:
.test page 27
.figure 2
.c;+--------------+-------------------------------------+
.c;| type         |     return method                   |
.c;+--------------+-------------------------------------+
.c;| BOOLEAN      |                                     |
.c;| CHAR         |                                     |
.c;| INTEGER      |                                     |
.c;| CARDINAL     |                                     |
.c;| POINTER      |                                     |
.c;| Enumeration  |     Register R0                     |
.c;| Subrange     |                                     |
.c;| BYTE         |                                     |
.c;| SHORTWORD    |                                     |
.c;| WORD         |                                     |
.c;| ADDRESS      |                                     |
.c;| REAL         |                                     |
.c;+--------------+-------------------------------------+
.c;| D__FLOATING   |                                     |
.c;| G__FLOATING   |     Registers R0,R1                 |
.c;| QUADWORD     |                                     |
.c;+--------------+-------------------------------------+
.c;| H__FLOATING   |     by reference as the first       |
.c;| OCTAWORD     |     parameter in the function's     |
.c;|              |     parameter list                  |
.c;+--------------+-------------------------------------+
.hl 1 Foreign Procedures
.x calling conventions>foreign procedures
.x foreign procedures
Access to procedures and variables written in other VAX-11
programming languages, especially to the VAX/VMS system services
and Run-Time Library procedures, is provided through special
definition modules, so-called foreign definition modules. They
serve only to export the descriptions of the respective
procedures and have no corresponding Modula-2 implementation
modules.

A foreign definition module is syntactically indicated by the
prefix "%FOREIGN":
.b
.nf
.lm +4
ForeignDefinitionModule =
  "%FOREIGN" DEFINITION MODULE ident ";"
  { import } [ export ] { foreigndefinition } END ident ".".
.lm -4
.f

This section contains the formal definitions of the procedures
and variables to be linked. Procedure and variable names must be
known to the linker and the calling convention must match at the
linker level.

To allow full utilization of the VAX/VMS procedure calling
standard, additional parameter qualifiers have been introduced,
applicable only within foreign definition modules:
.b
.nf
.lm +4
ForeignFormalParameters =
  "(" [ ForeignFPSection {";" ForeignFPSection }] ")"
  [":" qualident ].
ForeignFPSection   =
  [ VAR ][ "%REF" | "%IMMED" | "%STDESCR"]
  IdentList ":" FormalType.
.s.i -4;where
.b
%IMMED   denotes passing by immediate value,
%REF     denotes passing by reference, and
%STDESCR denotes passing by string descriptor.
.lm -4
.f

As an example, we give a definition module which allows access to
some screen handling procedures:
.b
.lm +4
.rm +4
.nf
%FOREIGN DEFINITION MODULE ScreenIO;
.b
EXPORT QUALIFIED ..., SCR$GET__SCREEN, SCR$PUT__SCREEN, ...;
  ...
  (* Perform I/O to and from the Screen *)
  PROCEDURE SCR$GET__SCREEN
    (VAR %STDESCR input:  ARRAY OF CHAR;
         %STDESCR prompt: ARRAY OF CHAR;
     VAR          outlen: CARDINAL): CARDINAL;
.b
  PROCEDURE SCR$PUT__SCREEN
    (    %STDESCR text:   ARRAY OF CHAR;
         %IMMED   lineno: CARDINAL;
         %IMMED   colno:  CARDINAL;
         %IMMED   flags:  BITSET): CARDINAL;
  ...
.b
END ScreenIO.
.lm -4
.f

Foreign definition modules should not be written without
knowledge about the parameter passing mechanisms involved.
.chapter ^~SYSTEM DEPENDENT FACILITIES\~
.lm 8
.rm 72
.x system dependent facilities>low level
.hl 1 Low Level Facilities
There are applications (e.g., system programming) for which the
language rules may turn out to be too restrictive. For this
reason, Modula-2 provides some means for "low level programming";
most of them are implementation dependent.

The programmer is urged to use these low level facilities very
carefully and only if it seems unavoidable. He will be much less
protected against errors because low level facilities are not
checked for consistency with language rules.
.hl 2 Type Transfer Functions
.x system dependent facilities>type transfer functions
.x type transfer functions
Type transfer functions, denoted by type identifiers used as
function identifiers, serve to breach Modula's type system. They
do not involve any actual computation but modify the compiler's
type checking. For instance, if c is an expression of type
CARDINAL then BITSET(c) is interpreted as the corresponding value
of type BITSET. This is a correspondance determined by the
underlying system and not by the programming language itself.
Therefore, using type transfer functions requires familiarity
with the internal representation and storage allocation scheme of
the corresponding data types.
.hl 2 Absolute Addresses
.x system dependent facilities>absolute addresses
.x absolute addresses
The assignment of absolute addresses is still allowed in VAX-11
Modula-2 but this feature should be used with utmost care because
all addresses are usually relocated by the linker!
.hl 2 The Module SYSTEM
.x <SYSTEM module
.x system dependent facilities>module <SYSTEM
The module SYSTEM offers some further facilities of the Modula-2
language. Most of them are implementation dependent and/or refer
to the given processor. Facilities of that kind are sometimes
necessary for the so called "low level programming". SYSTEM
contains also types and procedures which allow a very basic
coroutine handling.

The module SYSTEM is known to the compiler because its exported
objects obey special rules, that must be checked by the compiler.
If a compilation unit imports objects from module SYSTEM, no
symbol file has to be supplied for this module.

Objects exported from module SYSTEM:
.lm +4
.s.i -4;^&Types\&
.x system dependent facilities>data types
.x <SYSTEM module>data types
.tp 16.s;^~BYTE, SHORTWORD, WORD, QUADWORD, OCTAWORD\~

Objects of these types represent individually accessible
storage units (BYTE = one byte, SHORTWORD = two bytes, WORD =
four bytes, QUADWORD = eight bytes, OCTAWORD = sixteen bytes).
Only assignment is allowed for variables of these types. A
parameter of type BYTE, SHORTWORD, WORD, QUADWORD or OCTAWORD
may be substituted by an actual parameter of any type that
uses the same number of bytes in storage. If the parameter is
a value parameter of type BYTE, SHORTWORD or WORD, then values
of types using up to four bytes are also allowed for
substitution. The same holds for the substitution of an open
array parameter with elements of type SHORTWORD, WORD,
QUADWORD or OCTAWORD by a value of a type which size is not an
integral multiple of the open array element size.

For compatibility with the VAX/VMS data type names the
identifier LONGWORD is also exported from the module SYSTEM as
a synonym for the identifier WORD.
.tp 7.s;^~ADDRESS\~
.x <SYSTEM module><ADDRESS
.x system dependent facilities>addresses

Objects of type ADDRESS represent the byte address of a
storage location. The type ADDRESS is compatible with all
pointer types and is itself defined as POINTER TO WORD. All
integer arithmetic operators apply to this type.
.tp 4.s;^~PROCESS\~
.x <SYSTEM module><PROCESS
.x system dependent facilities>processes

Objects of type PROCESS are used for process handling.
.tp 14.s;^~F__FLOATING, D__FLOATING, G__FLOATING, H__FLOATING\~
.x <SYSTEM module>floating point
.x floating point
.x system dependent facilities>floating point

The Modula-2 standard type REAL is implemented using the
VAX-11 F__FLOATING data type. The other VAX-11 floating point
data types are made available in the VAX-11 Modula-2 compiler
through export from module SYSTEM. All operators defined in
Modula-2 for the type REAL are also defined for the types
D__FLOATING, G__FLOATING and H__FLOATING. The type F__FLOATING is
only a synonym for the type REAL. Different floating point
types cannot be mixed in expressions (i.e., there is no
implicit conversion). However the module Conversions exports
procedures for the conversion of the different floating point
data types into each other.

The standard procedure TRUNC is applicable to all floating
point data types.
.note
If your VAX-11 processor is not equipped with the
extended instruction set option and you are using
variables of type G__FLOATING, H__FLOATING or OCTAWORD,
the VAX-11 extended instruction set emulator,
LIB$EMULATE, should be established as a condition
handler. See the ^&VAX-11 Run-Time Library Reference
Manual\& for more information.
.end note
.s.i -4;^&Procedures\&
.tp 6.s;^~NEWPROCESS(p#:#PROC; a#:#ADDRESS;
.br;###########n#:#CARDINAL; VAR p1#:#PROCESS)\~
.x <NEWPROCESS

A new process with P as program and A as workspace of size N is 
assigned to P1. This process is allocated, but not activated. P 
must be a parameterless procedure decalred at level 0. At least
50 words are needed for the workspace of a process. 
.tp 5.s;^~TRANSFER(VAR p1, p2: PROCESS)\~
.x <TRANSFER

Suspends the current process, assigns it to P1 and resumes the 
process designated by P2.
.s.i -4;^&Functions\&
.tp 5.s;^~ADR(variable): ADDRESS\~
.x absolute addresses

Returns the storage address of the variable.
.tp 7.s;^~SIZE(variable): CARDINAL\~
.x <SIZE

Returns the number of bytes allocated for the variable. If
the variable is of a record type with variants, then the
variant with maximal size is assumed.
.tp 11.s;^~TSIZE(type): CARDINAL\~
.br
^~TSIZE(type, tag1const, tag2const, ... ): CARDINAL\~
.x <TSIZE

Returns the number of bytes allocated for a variable of the
type. If the type is a record with variants, then tag
constants of the last FieldList (see Modula-2 syntax) may be
substituted in their nesting order. If no or not all tag
constants are specified, then the remaining variant with
maximal size is assumed.
.tp 5.s;^~REGISTER(num: CARDINAL): CARDINAL\~
.x <REGISTER

Returns the content of the specified register.
.lm -4
.hl 1 Storage Management
.hl 2 The Module Storage
The storage management procedures ALLOCATE and DEALLOCATE which
serve to dynamically obtain and return storage space can be
imported from the standard module Storage:
.b
.nf
.lm +4
DEFINITION MODULE Storage;
.b
  FROM SYSTEM IMPORT ADDRESS;
.b
  EXPORT QUALIFIED ALLOCATE, DEALLOCATE;
.b
  PROCEDURE ALLOCATE (VAR p: ADDRESS; size: CARDINAL);
.b
  PROCEDURE DEALLOCATE (VAR p: ADDRESS; size: CARDINAL);
.b
END Storage.
.lm -4
.f

ALLOCATE signals an exception whenever there is not enough free
heap space.

When writing your own storage management procedures you should
care for an appropriate declaration. Since NEW and DISPOSE are
translated into calls to ALLOCATE and DEALLOCATE, these must be
compatible with the type

####PROCEDURE (VAR ADDRESS, CARDINAL)
.hl 2 Storage Allocation
The following table summarizes the storage allocation and
alignment for variables of unstructured and set type:
.test page 40
.figure 2
.c;+-------------+-----------------------+--------------------+
.c;| type        | storage allocation    | alignment boundary |
.c;+-------------+-----------------------+--------------------+
.c;| BOOLEAN     |                       |                    |
.c;| CHAR        |   8 bits (1 byte)     |   byte             |
.c;| BYTE        |                       |                    |
.c;+-------------+-----------------------+--------------------+
.c;| SHORTWORD   |  16 bits (1 word)     |   word             |
.c;+-------------+-----------------------+--------------------+
.c;| INTEGER     |                       |                    |
.c;| CARDINAL    |                       |                    |
.c;| REAL        |  32 bits (1 longword) |   longword         |
.c;| POINTER     |                       |                    |
.c;| WORD        |                       |                    |
.c;| ADDRESS     |                       |                    |
.c;+-------------+-----------------------+--------------------+
.c;| D__FLOATING  |                       |                    |
.c;| G__FLOATING  |  64 bits (1 quadword) |   longword         |
.c;| QUADWORD    |                       |                    |
.c;+-------------+-----------------------+--------------------+
.c;| H__FLOATING  | 128 bits (1 octaword) |   longword         |
.c;| OCTAWORD    |                       |                    |
.c;+-------------+-----------------------+--------------------+
.c;| Enumeration |  8 bits (1 byte) if   |   byte             |
.c;|             |  type contains 256 or |                    |
.c;|             |  less elements;       |                    |
.c;|             |  16 bits (1 word) if  |   word             |
.c;|             |  type contains more   |                    |
.c;|             |  then 256 elements    |                    |
.c;+-------------+-----------------------+--------------------+
.c;| SET         |   8 bits (1 byte),    |   byte             |
.c;|             |  16 bits (1 word), or |   word             |
.c;|             |  32 bits (1 longword),|   longword         |
.c;|             |  according to         |                    |
.c;|             |  cardinality of base  |                    |
.c;|             |  type                 |                    |
.c;+-------------+-----------------------+--------------------+

Variables of subrange type are allocated and aligned in the same
way as variables of their base type.

An array is stored and aligned according to the type of its
elements. Every element is also aligned according to its type.

Records are stored field by field. Each field is allocated
according to its type and aligned on a byte boundary.
.appendix ^~RESTRICTIONS AND EXTENSIONS\~
.lm 8
.rm 72
The implementation of Modula-2 on the VAX-11 differs in some
respect from the language definition; some restrictions have to
be considered.

^&Identifiers\&

Identifiers may contain the additional characters "$" and "__":

####ident = letter { letter | digit | "$" | "__" }.

Due to the naming conventions of the linker some restrictions
must be obeyed for module names and exported procedure
identifiers. An external name is, at the linker level, composed
of the module name and the exported name, both converted to
upper case and separated by a dot. If the composed name is
longer than 31 characters (including the dot) the individual
names are shortened to 15 characters. A conflict will occur if
the resulting name is not unique anymore.

It is also recommended to provide compilation unit identifiers
differing in the first 9 characters, because these determine the
default symbol file names. However, the user may circumvent this
restriction by applying the SYMBOL__FILE and QUERY qualifiers.
.tp 6.s;^&Real number constants\&

Expressions of constant real numbers are not evaluated by the
compiler (except sign inversion).
.tp 8.s;^&Real number conversion\&

The real number conversion routines are implemented according to
VAX-11 instructions, i.e. they work with type INTEGER instead of
type CARDINAL. The argument type of FLOAT(i) must be INTEGER.
The result type of TRUNC(r) is INTEGER.
.page
.tp 9.s;^&FOR statement\&

The step must not be greater than 7FFFFFFFH (MaxInt).
.tp 8.s;^&CASE statement\&

The labels of a case statement must not be greater than
7FFFFFFFH.
.tp 7.s;^&Priority specifications\&

Priority specifications are not implemented.
.tp 9.s;^&Standard function LEN\&

The additional standard function LEN returns the number of
characters in a string. It is defined as follows:
.b
.nf
.lm +8
TYPE intcar = [ 0 .. MaxInt ];
.b
PROCEDURE LEN ( s : ARRAY OF CHAR ) : intcar;
  VAR i : intcar;
BEGIN i := 0;
  WHILE (i <= HIGH(s)) AND (s[i] <> 0C) DO
    INC(i);
  END;
  RETURN i
END LEN;
.lm -8
.f
.tp 8.s;^&Type transfer functions\&

Additional type transfer functions have been defined for types of
different sizes, provided their sizes are less than or equal to 4
bytes. In extending the size of an entity the additional high
order bits are set to zero.
.appendix ^~VAX-11 MODULA-2 SYNTAX\~
.lm 8
.rm 80
.nf
  1              /***************************************/
  2              /                                       /
  3              /     MODULA-2 Multi-Pass Compiler      /
  4              /     ****************************      /
  5              /                                       /
  6              /        VAX/VMS Implementation         /
  7              /                                       /
  8              /          Modula-2 Syntax              /
  9              /                                       /
 10              /     Version 3.1 of  1-FEB-1983        /
 11              /                                       /
 12              /                                       /
 13              /                                       /
 14              /                                       /
 15              /                                       /
 16              /                                       /
 17              /***************************************/
 18 
 19 ident =      letter {letter | digit | "__" | "$"} .
 20 number =     integer | real .
 21 integer =    digit {digit} |
 22              octalDigit {octalDigit} ("B"|"C"|"b"|"c") |
 23              digit {hexDigit} ("H"|"h") .
 24 real =       digit {digit} "." {digit} [ScaleFactor] .
 25 ScaleFactor = ("E"|"e") ["+"|"-"] digit {digit} .
 26 hexDigit =   digit |
 27              "A"|"B"|"C"|"D"|"E"|"F"|"a"|"b"|"c"|"d"|"e"|"f" .
 28 digit =      octalDigit | "8" | "9" .
 29 octalDigit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" .
 30 string =     "'" {character} "'" | '"' {character} '"' .
 31 qualident =  ident {"." ident} .
 32 ConstantDeclaration = ident "=" ConstExpression .
 33 ConstExpression = SimpleConstExpr [relation SimpleConstExpr] .
 34 relation =   "=" | "#" | "<>" | "<" | "<=" | ">" | ">=" | IN .
 35 SimpleConstExpr = ["+"|"-"] ConstTerm {AddOperator ConstTerm} .
 36 AddOperator = "+" | "-" | OR .
 37 ConstTerm =  ConstFactor {MulOperator ConstFactor} .
 38 MulOperator = "*" | "/" | DIV | MOD | AND | "&" .
 39 ConstFactor = qualident | number | string | set |
 40             "(" ConstExpression ")" | NOT ConstFactor .
 41 set =        [qualident] "{" [element {"," element}] "}" .
 42 element =    ConstExpression [".." ConstExpression] .
 43 TypeDeclaration = ident "=" type .
 44 type =       SimpleType | ArrayType | RecordType | SetType |
 45              PointerType | ProcedureType .
 46 SimpleType = qualident | enumeration | SubrangeType .
 47 enumeration = "(" IdentList ")" .
 48 IdentList =  ident {"," ident} .
 49 SubrangeType = "[" ConstExpression ".." ConstExpression "]" .
 50 ArrayType =  ARRAY SimpleType {"," SimpleType} OF type .
 51 RecordType = RECORD FieldListSequence END .
 52 FieldListSequence = FieldList {";" FieldList} .
 53 FieldList =  [IdentList ":" type |
 54              CASE [ident ":"] qualident OF variant {"|" variant}
 55              [ELSE FieldListSequence] END] .
 56 variant =    CaseLabelList ":" FieldListSequence .
 57 CaseLabelList = CaseLabels {"," CaseLabels} .
 58 CaseLabels = ConstExpression [".." ConstExpression] .
 59 SetType =    SET OF SimpleType .
 60 PointerType = POINTER TO type .
 61 ProcedureType = PROCEDURE [FormalTypeList] .
 62 FormalTypeList = "(" [[VAR] FormalType
 63              {"," [VAR] FormalType}] ")" [":" qualident] .
 64 VariableDeclaration = IdentList ":" type .
 65 designator = qualident {"." ident | "[" ExpList "]" | "^"} .
 66 ExpList =    expression {"," expression} .
 67 expression = SimpleExpression [relation SimpleExpression] .
 68 SimpleExpression = ["+"|"-"] term {AddOperator term} .
 69 term =       factor {MulOperator factor} .
 70 factor =     number | string | set |
 71              designator [ActualParameters] |
 72              "(" expression ")" | NOT factor .
 73 ActualParameters = "(" [ExpList] ")" .
 74 statement =  [ assignment | ProcedureCall |
 75              IfStatement | CaseStatement | WhileStatement |
 76              RepeatStatement | LoopStatement | ForStatement |
 77              WithStatement | EXIT | RETURN [expression] ] .
 78 assignment = designator ":=" expression .
 79 ProcedureCall = designator [ActualParameters] .
 80 StatementSequence = statement {";" statement} .
 81 IfStatement = IF expression THEN StatementSequence
 82              {ELSIF expression THEN StatementSequence}
 83              [ELSE StatementSequence] END .
 84 CaseStatement = CASE expression OF case {"|" case}
 85              [ELSE StatementSequence] END .
 86 case =       CaseLabelList ":" StatementSequence .
 87 WhileStatement = WHILE expression DO StatementSequence END .
 88 RepeatStatement = REPEAT StatementSequence UNTIL expression .
 89 ForStatement = FOR ident ":=" expression TO expression
 90              [BY ConstExpression] DO StatementSequence END .
 91 LoopStatement= LOOP StatementSequence END .
 92 WithStatement= WITH designator DO StatementSequence END .
 93 ProcedureDeclaration= ProcedureHeading ";" block ident .
 94 ProcedureHeading = PROCEDURE ident [FormalParameters] .
 95 block =      {declaration} [BEGIN StatementSequence] END .
 96 declaration = CONST {ConstantDeclaration ";"} |
 97              TYPE {TypeDeclaration ";"} |
 98              VAR {VariableDeclaration ";"} |
 99              ProcedureDeclaration ";" |
100              ModuleDeclaration ";" .
101 FormalParameters = "(" [FPSection {";" FPSection}] ")"
102              [":" qualident] .
103 FPSection =  [VAR] IdentList ":" FormalType .
104 FormalType = [ARRAY OF] qualident .
105 ModuleDeclaration = MODULE ident [priority] ";"
106              {import} [export] block ident .
107 priority =   "[" ConstExpression "]" .
108 export =     EXPORT [QUALIFIED] IdentList ";" .
109 import =     [FROM ident] IMPORT IdentList ";" .
110 DefinitionModule = DEFINITION MODULE ident ";"
111              {import} [export] {definition} END ident "." .
112 definition = CONST {ConstantDeclaration ";"} |
113              TYPE {ident ["=" type] ";"} |
114              VAR {VariableDeclaration ";"} |
115              ProcedureHeading ";" .
116 ProgramModule = MODULE ident [priority] ";"
117              {import} block ident "." .
118 CompilationUnit = ForeignDefinitionModule |
119              DefinitionModule | [IMPLEMENTATION] ProgramModule .
120 ForeignDefinitionModule = "%FOREIGN" DEFINITION MODULE ident ";"
121              {import} [export] {Foreigndefinition} END ident "." .
122 Foreigndefinition = CONST {ConstantDeclaration ";"} |
123              TYPE {ident ["=" type] ";"} |
124              VAR {VariableDeclaration ";"} |
125              ForeignProcedureHeading ";" .
126 ForeignProcedureHeading = PROCEDURE ident
127              [ForeignFormalParameters] .
128 ForeignFormalParameters = "(" [ForeignFPSection
129              {";" ForeignFPSection}] ")" [":" qualident] .
130 ForeignFPSection =  [VAR]
131              ["%REF" | "%IMMED" | "%STDESCR"]
132              IdentList ":" FormalType .
.page
ActualParameters           79   -73    71
AddOperator                68   -36    35
ArrayType                 -50    44
assignment                -78    74
block                     117   106   -95    93
case                      -86    84    84
CaseLabelList              86   -57    56
CaseLabels                -58    57    57
CaseStatement             -84    75
character                  30    30
CompilationUnit          -118
ConstantDeclaration       122   112    96   -32
ConstExpression           107    90    58    58    49    49    42
                           42    40   -33    32
ConstFactor                40   -39    37    37
ConstTerm                 -37    35    35
declaration               -96    95
definition               -112   111
DefinitionModule          119  -110
designator                 92    79    78    71   -65
digit                     -28    26    25    25    24    24    24
                           23    21    21    19
element                   -42    41    41
enumeration               -47    46
ExpList                    73   -66    65
export                    121   111  -108   106
expression                 89    89    88    87    84    82    81
                           78    77    72   -67    66    66
factor                     72   -70    69    69
FieldList                 -53    52    52
FieldListSequence          56    55   -52    51
Foreigndefinition        -122   121
ForeignDefinitionModule  -120   118
ForeignFormalParameters  -128   127
ForeignFPSection         -130   129   128
ForeignProcedureHeading  -126   125
FormalParameters         -101    94
FormalType                132  -104   103    63    62
FormalTypeList            -62    61
ForStatement              -89    76
FPSection                -103   101   101
hexDigit                  -26    23
ident                     126   123   121   120   117   116   113
                          111   110   109   106   105    94    93
                           89    65    54    48    48    43    32
                           31    31   -19
IdentList                 132   109   108   103    64    53   -48
                           47
IfStatement               -81    75
import                    121   117   111  -109   106
integer                   -21    20
letter                     19    19
LoopStatement             -91    76
ModuleDeclaration        -105   100
MulOperator                69   -38    37
number                     70    39   -20
octalDigit                -29    28    22    22
PointerType               -60    45
priority                  116  -107   105
ProcedureCall             -79    74
ProcedureDeclaration       99   -93
ProcedureHeading          115   -94    93
ProcedureType             -61    45
ProgramModule             119  -116
qualident                 129   104   102    65    63    54    46
                           41    39   -31
real                      -24    20
RecordType                -51    44
relation                   67   -34    33
RepeatStatement           -88    76
ScaleFactor               -25    24
set                        70   -41    39
SetType                   -59    44
SimpleConstExpr           -35    33    33
SimpleExpression          -68    67    67
SimpleType                 59    50    50   -46    44
statement                  80    80   -74
StatementSequence          95    92    91    90    88    87    86
                           85    83    82    81   -80
string                     70    39   -30
SubrangeType              -49    46
term                      -69    68    68
type                      123   113    64    60    53    50   -44
                           43
TypeDeclaration            97   -43
VariableDeclaration        124   114    98   -64
variant                   -56    54    54
WhileStatement            -87    75
WithStatement             -92    77
.appendix ^~DIAGNOSTIC MESSAGES\~
.lm 8
.rm 72
.hl 1 Compiler Diagnostic Messages
.nf
  0   : illegal character
  1   : illegal symbol
  2   : constant out of range
  3   : open comment at end of file
  4   : string terminator not on this line
  5   : too many errors
  6   : string too long
  7   : too many identifiers (identifier table full)
  8   : too many identifiers (hash table full)
.b
 20   : identifier expected
 21   : integer constant expected
 22   : ']' expected
 23   : ';' expected
 24   : block name at the END does not match
 25   : error in block
 26   : ':=' expected
 27   : error in expression
 28   : THEN expected
 29   : error in LOOP statement
 30   : constant must not be CARDINAL
 31   : error in REPEAT statement
 32   : UNTIL expected
 33   : error in WHILE statement
 34   : DO expected
 35   : error in CASE statement
 36   : OF expected
 37   : ':' expected
 38   : BEGIN expected
 39   : error in WITH statement
 40   : END expected
 41   : ')' expected
 42   : error in constant
 43   : '=' expected
 44   : error in TYPE declaration
 45   : '(' expected
 46   : MODULE expected
 47   : QUALIFIED expected
 48   : error in factor
 49   : error in simple type
 50   : ',' expected
 51   : error in formal type
 52   : error in statement sequence
 53   : '.' expected
 54   : export at global level not allowed
 55   : body in definition module not allowed
 56   : TO expected
 57   : nested module in definition module not allowed
 58   : '}' expected
 59   : '..' expected
 60   : error in FOR statement
 61   : IMPORT expected
.b
 66   : DEFINITION expected
.b
 70   : identifier specified twice in importlist
 71   : identifier not exported from qualifying module
 72   : identifier declared twice
 73   : identifier not declared
 74   : type not declared
 75   : identifier already declared in module environment
 76   :
 77   :
 78   : value of absolute address must be of type CARDINAL
 79   : scope table overflow in compiler
 80   : illegal priority
 81   : definition module belonging to implementation not found
 82   : structure not allowed for implementation of hidden type
 83   : procedure implementation different from definition
 84   : not all defined procedures or hidden types implemented
 85   : illegal combination of parameter passing mechanisms
 86   : incompatible versions of symbolic modules
 87   : illegal parameter passing mechanism for this type
 88   : function type is not scalar or basic type
 89   :
 90   : pointer-referenced type not declared
 91   : tagfieldtype expected
 92   : incompatible type of variant-constant
 93   : constant used twice
 94   : arithmetic error in evaluation of constant expression
 95   : range not correct
 96   : range only with scalar types
 97   : type-incompatible constructor element
 98   : element value out of bounds
 99   : set-type identifier expected
100   : declaration needs too much space
101   : undeclared identifier in export-list of the module
102   :
103   : wrong class of identifier
104   : no such module name found
105   : module name expected
106   : scalar type expected
107   : set too large
108   : type must not be INTEGER or CARDINAL
109   : scalar or subrange type expected
110   : variant value out of bounds
111   : illegal export from program module
.b
120   : incompatible types in conversion
121   : this type is not expected
122   : variable expected
123   : incorrect constant
124   : no procedure found for substitution
125   : unsatisfying parameters of substituted procedure
126   : set constant out of range
127   : error in standard procedure parameters
128   : type incompatibility
129   : type identifier expected
130   : type impossible to index
131   : field not belonging to a record variable
132   : too many parameters
133   :
134   : reference not to a variable
135   : illegal parameter substitution
136   : constant expected
137   : expected parameters
138   : BOOLEAN type expected
139   : scalar types expected
140   : operation with incompatible type
141   : only global procedure or function allowed in
        expression
142   : incompatible element type
143   : type incompatible operands
144   : no selectors allowed for procedures
145   : only function call allowed in expression
146   : arrow not belonging to a pointer variable
147   : standard function or procedure must not be assigned
148   : constant not allowed as variant
149   : SET type expected
150   : illegal substitution to WORD parameter
151   : EXIT only in LOOP
152   : RETURN only in PROCEDURE
153   : expression expected
154   : expression not allowed
155   : type of function expected
156   : integer constant expected
157   : procedure call expected
158   : identifier not exported from qualifying module
.b
300   : index out of range
301   : division by zero
302   :
303   : case label defined twice
.b
400   : expression too complicated (register overflow)
401   :
402   : expression too complicated (branch too long)
403   : expression too complicated (jumptable overflow)
404   : too many globals, externals and calls
        (linkertable overflow)
405   : procedure too long (codetable overflow)
406   : compiler error (assertion failed)
407   : compiler error (internal confusion)
.b
994   : too many nested procedures
995   : FOR step too large ( > MaxInt )
996   : CASE label too large ( > MaxInt )
997   : illegal parameter substitution (implementation
        restriction on type transfer function)
.f
.hl 1 Run-Time Diagnostic Messages
.nf
1000  : HALT statement encountered
1001  : index or case expression out of range
1002  : illegal pointer value
1003  : function return without result
1004  : problem during "FileSystem" operation for file
        "filename"
.b
1009  : end of coroutine
1010  : process workspace overflow
.f
.appendix ^~INPUT AND OUTPUT PROCEDURES\~
.lm 8
.rm 72
.subttl InOut
.hl 1 The Module InOut
The procedures contained in the utility module InOut are used to
perform input from and output to standard input/output devices
or to sequential files. In particular, they perform the
necessary data representation conversions between the standard
data types and sequences of characters. The input procedures
read from the system's standard input device (SYS$INPUT). The
output procedures write on the system's standard output device
(SYS$OUTPUT). However, both input and output can instead be
assigned to files by calling OpenInput and OpenOutput. These
procedures request the specification of the names of files.
Input and output are reset to the default devices by calling
CloseInput and CloseOutput, which must be called in order to
close the associated files. 

Several output procedures contain a parameter n specifying the
number of characters to be written. If n is greater than the
number m of characters actually needed to represent the value x,
then n-m blanks precede that value. If n is less than m, the
specified n is ignored. 
.lm +4
.b
.i -4;^&MODULE Name\&
.b
InOut
.b
.tp 9.i -4;^&EXPORTed\&
.b
.nj
EOL, Done, in, out, termCH, OpenInput, OpenOutput,
CloseInput, CloseOutput, Read, ReadLn, ReadString, ReadInt,
ReadCard, ReadOct, ReadHex, ReadReal, ReadDFloat,
ReadGFloat, ReadHFloat, Write, WriteLn, WriteString,
WriteInt, WriteCard, WriteOct, WriteHex, WriteReal,
WriteDFloat, WriteGFloat, WriteHFloat
.j
.b
.tp 5.i -4;^&IMPORTed\&
.b
FROM SYSTEM IMPORT DFLOATING,GFLOATING,HFLOATING;
.br
IMPORT FileSystem;
.br
FROM FileSystem IMPORT File;
.b
.tp 20.i -4;^&Procedure Descriptions\&
.tp 10.s.i -4;PROCEDURE OpenInput(defnam#:#ARRAY OF CHAR);

Request a file name and open input file "in". If opened
successfully, subsequent input is read from this file. Name
is parsed with "defnam" as default name.
.tp 8.s.i -4;PROCEDURE OpenOutput(defnam#:#ARRAY OF CHAR);

Request a file name and open output file "out". If opened
successfully, subsequent output is written to this file.
File name is parsed with "defnam" as the default name.
.tp 8.s.i -4;PROCEDURE CloseInput;

Closes input file "in", returns input to terminal.
.tp 8.s.i -4;PROCEDURE CloseOutput;

Closes output file "out", and returns output to terminal.
.tp 8.s.i -4;PROCEDURE Read(VAR ch#:#CHAR);

Reads a single character from the file "in".
.tp 8.s.i -4;PROCEDURE ReadLn;

Skips to the beginning of the next input line.
.tp 8.s.i -4;PROCEDURE ReadString(VAR s#:#ARRAY OF CHAR);

Read an ASCII string, i.e. a sequence of characters not
containing blanks, tabs or control characters; leading
blanks are ignored. Input is terminated by any non-printing
ASCII character. The terminating character is assigned to
"termCH".
.tp 8.s.i -4;PROCEDURE ReadInt(VAR i#:#INTEGER);

Read an integer string from "in" and convert to integer.
Leading blanks are ignored.
.tp 8.s.i -4;PROCEDURE ReadCard(VAR c#:#CARDINAL);

Read ASCII numerical string an convert to CARDINAL. Leading
blanks are ignored.
.tp 8.s.i -4;PROCEDURE ReadOct(VAR c#:#CARDINAL);

Read ASCII octal string and convert to CARDINAL. Leading
blanks are ignored.
.tp 8.s.i -4;PROCEDURE ReadHex(VAR c#:#CARDINAL);
Read ASCII hexadecimal string and convert to CARDINAL.
Leading blanks are ignored.
.tp 8.s.i -4;PROCEDURE ReadReal(VAR r#:#REAL);

Read ASCII real (floating point) string and convert to
single precision floating point. Leading blanks are ignored.
.tp 8.s.i -4;PROCEDURE ReadDFloat(VAR d#:#DFLOATING);

Read ASCII real (floating point) string and convert to
D format floating point. Leading blanks are ignored.
.tp 8.s.i -4;PROCEDURE ReadGFloat(VAR g#:#GFLOATING);

Read ASCII real (floating point) string and convert to
G format floating point. Leading blanks are ignored.
.tp 8.s.i -4;PROCEDURE ReadHFloat(VAR h#:#HFLOATING);

Read ASCII real (floating point) string and convert to
H format floating point. Leading blanks are ignored.
.tp 8.s.i -4;PROCEDURE Write(ch#:#CHAR);

Write single ASCII character to output file "out".
.tp 8.s.i -4;PROCEDURE WriteLn;

Write end of line to output file "out". Terminates output
and forces line to terminal (if appropriate).
.tp 8.s.i -4;PROCEDURE WriteString(s#:#ARRAY OF CHAR);

Writes a string of ASCII characters to output file "out".
.tp 8.s.i -4;PROCEDURE WriteInt(i#:#INTEGER; n#:#CARDINAL);

Write integer "i" with (at least) "n" characters to file
"out". If n is greater than the number of digits needed,
blanks are added preceding the number
.tp 8.s.i -4;PROCEDURE WriteCard(c#:#CARDINAL; n#:#CARDINAL);

Write CARDINAL "c" with (at least) "n" characters to file
"out". If n is greater than the number of digits needed,
blanks are added preceding the number
.tp 8.s.i -4;PROCEDURE WriteOct(c#:#CARDINAL; n#:#CARDINAL);

Write CARDINAL "c" with (at least) "n" characters to file
"out" as an octal ASCII string. If n is greater than the
number of digits needed, blanks are added preceding the
number.
.tp 8.s.i -4;PROCEDURE WriteHex(c#:#CARDINAL; n#:#CARDINAL);

Write CARDINAL "c" with (at least) "n" characters to file
"out" as a hexadecimal ASCII string. If n is greater than
the number of digits needed, blanks are added preceding the
number.
.tp 8.s.i -4;PROCEDURE WriteReal(r#:#REAL; n#:#CARDINAL);

Write single precision floating point value "r" with (at
least) "n" characters to file "out". If n is greater than
the number of digits needed, blanks are added preceding the
number.
.tp 8.s.i -4;PROCEDURE WriteDFloat(d#:#DFLOATING; n#:#CARDINAL);

Write D format floating point value "r" with (at least) "n"
characters to file "out". If n is greater than the number of
digits needed, blanks are added preceding the number.
.tp 8.s.i -4;PROCEDURE WriteGFloat(g#:#GFLOATING; n#:#CARDINAL);

Write G format floating point value "r" with (at least) "n"
characters to file "out". If n is greater than the number of
digits needed, blanks are added preceding the number.
.tp 8.s.i -4;PROCEDURE WriteHFloat(h#:#HFLOATING; n#:#CARDINAL);

Write H format floating point value "r" with (at least) "n"
characters to file "out". If n is greater than the number of
digits needed, blanks are added preceding the number.
.lm -4
.subttl FileSystem
.page
.hl 1 The Module FileSystem
.x I/O>files
This module provides the programmer with high-level access to
files stored on disk. Evidently, these procedures depend to some
degree on the underlying file system which is usually an
integral part of the given operating system. The module shown
here is designed for the VAX-11 with the record-oriented file
system RMS. 
.lm +4
.b
.tp 5.i -4;^&MODULE Name\&
.b
FileSystem
.b
.tp 9.i -4;^&EXPORTed\&
.b
File, EOL, Done, Create, Open, Close, Release, Delete,
Rename, GetPos, SetPos, Reset, Eof, ReadWord, ReadShortWord,
ReadByte, WriteWord, WriteShortWord, WriteByte, ReadChar,
WriteChar, ReadRecord, WriteRecord, GetRecord, PutRecord,
Eor, Fab, Rab, Name, Parse, Status, ShowStatus
.b
.tp 4.i -4;^&IMPORTed\&
.b
FROM SYSTEM IMPORT ADDRESS, BYTE, SHORTWORD, WORD;
.b
.tp 35.i -4;^&Procedure Descriptions\&
.lm -4
.hl 2 General File Procedures
.lm +4
.tp 9.s.i -4;PROCEDURE Done#()#:#BOOLEAN;

Returns TRUE if the last call to FIleSystem was successful,
false otherwise.
.tp 15.s.i -4;PROCEDURE Create#(VAR f#:#File;
.i -4;##################filename#:#ARRAY OF CHAR;
.i -4;##################var,cr#:#BOOLEAN);

Create a new file and open it for read and write access. "var"
is TRUE if the file will contain variable length records
otherwise the records are of fixed length (512 bytes). "cr" is
TRUE if the file's record attribute is set to 'cr', otherwise it
is set to 'none'. 'Normal' text files should be created with
"var" and "cr" set to TRUE. The position is set to the beginning
of the file. 
.tp 9.s.i -4;PROCEDURE Open#(VAR f: File;
.i -4;################filename#:#ARRAY OF CHAR;
.i -4;################modify#:#BOOLEAN);

Opens an existing file. If "modify" is set TRUE write access
to the file is allowed. Position is set to the beginning of
the file.
.tp 9.s.i -4;PROCEDURE Close#(VAR f#:#File);

Closes file "f", any modifications become permanent.
.tp 9.s.i -4;PROCEDURE Release#(VAR f#:#File);

If write access was allowed on the file "f", it is deleted
otherwise it is closed .
.tp 9.s.i -4;PROCEDURE Rename#(old,new#:#ARRAY OF CHAR);

Renames the "old" file to the "new filename.
.tp 9.s.i -4;PROCEDURE Delete#(filename#:#ARRAY OF CHAR);

Deletes the file specified by "filename".
.tp 9.s.i -4;PROCEDURE GetPos#(VAR f#:#File; 
.i -4;##################VAR highpos,lowpos#:#CARDINAL);

Returns the current file position in "highpos" and "lowpos".
The record number is contained in "lowpos" and the lower 16 bits 
of "highpos", while the byte offset within the record is 
contained in the upper 16 bits of "highpos".
.tp 9.s.i -4;PROCEDURE SetPos#(VAR f#:#File;
.i -4;##################highpos,lowpos#:#CARDINAL);

Set file "f" to position specified by "highpos" and "lowpos",
which should be supplied by a previous GetPos call.
.tp 9.s.i -4;PROCEDURE Reset#(VAR f#:#File);

Set position of file "f" to beginning of file.
.tp 9.s.i -4;PROCEDURE Eof#(VAR f#:#File)#:#BOOLEAN;

Set position of file "f" to end of file.
.lm -4
.test page 30
.hl 2 Binary Access
.lm +4
.x I/O>binary access
.tp 9.s.i -4;PROCEDURE ReadWord#(VAR f#:#File; VAR w#:#WORD);

Read one word from file "f" at current position and advance
position.
.tp 9.s.i -4;PROCEDURE ReadShortWord#(VAR f#:#File; VAR s#:#SHORTWORD);

Read one shortword from file "f" at current position and advance
position.
.tp 9.s.i -4;PROCEDURE ReadByte#(VAR f#:#File; VAR b#:#BYTE);

Read one byte from file "f" at current position and advance
position.
.tp 9.s.i -4;PROCEDURE WriteWord#(VAR f#:#File; w#:#WORD);

Write one word to file "f" at current position and advance
position.
.tp 9.s.i -4;PROCEDURE WriteShortWord#(VAR f#:#File; s#:#SHORTWORD);

Write one shortword to file "f" at current position and advance
position.
.tp 9.s.i -4;PROCEDURE WriteByte#(VAR f#:#File; b#:#BYTE);

Write one byte to file "f" at current position and advance
position.
.lm -4
.test page 30
.hl 2 Text File Access
.lm +4
.x I/O>text file access
.tp 9.s.i -4;PROCEDURE ReadChar#(VAR f#:#File; VAR ch#:#CHAR);

Read one character from file "f" at current position and
advance position.
.tp 9.s.i -4;PROCEDURE WriteChar#(VAR f#:#File; ch#:#CHAR);

Write one character to file "f" at current position and
advance position.
.lm -4
.tp 40
.hl 2 RMS Specific Procedures
.lm +4
.x I/O>_R_M_S
.tp 9.s.i -4;PROCEDURE ReadRecord#(VAR f#:#File;
.i -4;######################VAR rec#:#ARRAY OF BYTE;
.i -4;######################VAR size#:#CARDINAL);

Read an entire record from file "f" into array "rec", the
size of the record will be returned in "size".
.tp 9.s.i -4;PROCEDURE WriteRecord#(VAR f#:#File;
.i -4;#######################VAR rec#:#ARRAY OF BYTE;
.i -4;#######################size#:#CARDINAL);

Write an entire record from "rec" to file "f". The record
size is determined by "size".
.tp 9.s.i -4;PROCEDURE GetRecord#(VAR f#:#File);

Read next record from file "f".
.tp 9.s.i -4;PROCEDURE PutRecord#(VAR f#:#File);

Put end of record to file "f".
.tp 9.s.i -4;PROCEDURE Eor#(VAR f#:#File)#:#BOOLEAN;

Returns TRUE if current position is at end of a record in
file "f".
.tp 9.s.i -4;PROCEDURE Fab#(VAR f#:#File)#:#ADDRESS;

Returns address of the FAB belonging to "f".
.tp 9.s.i -4;PROCEDURE Rab#(VAR f#:#File)#:#ADDRESS;

Returns address of the RAB belonging to file "f".
.tp 9.s.i -4;PROCEDURE Name#(VAR f#:#File;
.i -4;################VAR filename#:#ARRAY OF CHAR);

Returns the name of the file currently open on file "f".
.tp 9.s.i -4;PROCEDURE Parse#(filename, defaultname#:#ARRAY OF CHAR;
.i -4;#################VAR resultname#:#ARRAY OF CHAR;
.i -4;#################VAR fnstatus#:#BITSET);

Parses the file name "filename", using the default file
specification "defaultname" and returns the result in
"resultname".
.tp 9.s.i -4;PROCEDURE Status#()#:#CARDINAL;

Returns the VAX/VMS status code of the last RMS operation
called from FileSystem.
.tp 9.s.i -4;PROCEDURE ShowStatus;

Displays the error message on the terminal for any
FileSystem operation.
.lm -4
.subttl Terminal
.page
.hl 1 Terminal Input and Output
.x I/O>terminal
This module provides procedures that read a single character or a
character string from SYS$INPUT and write a single character or a
character strings to SYS$OUTPUT.
.lm +4
.b
.tp 5.i -4;^&MODULE Name\&
.b
Terminal
.b
.tp 5;.i -4;^&EXPORTed\&
.b
Read, ReadString, ReadLn, ReadAgain, Write, WriteString, WriteLn;
.b
.tp 30;.i -4;^&Procedure Description\&
.tp 7.s.i -4;PROCEDURE Read#(VAR ch#:#CHAR);

Reads a single character from the terminal and places it in
"ch", advances position to the next character.
.tp 7.s.i -4;PROCEDURE ReadString#(VAR s#:#ARRAY OF CHAR);

Reads a line of characters from the current position until a
line terminator is detected or the string is complete
filled.
.tp 7.s.i -4;PROCEDURE ReadLn;

Skips to the beginning of the next line.
.tp 7.s.i -4;PROCEDURE ReadAgain;

"Backs up" the terminal input 1 character, causing the previously read
character to be read again using the ReadCh procedure.
.tp 7.s.i -4;PROCEDURE Write#(ch#:#CHAR);

Writes a single character to the terminal.
.tp 7.s.i -4;PROCEDURE WriteString#(s#:#ARRAY OF CHAR);

Writes a string of characters to the terminal.
.tp 7.s.i -4;PROCEDURE WriteLn;

Writes an end of line to the terminal.
.lm -4
.subttl File Name Processing Procedures
.page
.hl 1 File Name Processing Procedures
These procedures permit VMS file name operations to be 
performed.
.lm +4
.b
.i -4;^&MODULE Name\&
.b
FileNames
.b
.i -4;^&EXPORTed\&
.b
ReadFileName, ReadOption, Termination, FileName
.b
.i -4;^&Procedure Description\&
.tp 13.s.i -4;PROCEDURE ReadFileName(Default#:#ARRAY OF CHAR;
.i -4;#######################AcceptOption#:#BOOLEAN;
.i -4;#######################VAR Name#:#ARRAY OF CHAR;
.i -4;#######################VAR TypedFields#:#BITSET;
.i -4;#######################VAR Term#:#Termination);

Read file name (and options) from terminal until a <cr>, blank,
<tab>, or <esc> is typed. "Default" specifies file defaults to 
be applied to the file name "Name". "AcceptOption", when true,
allows options preceded by "/" to entered along with the file name. 
"TypedFields" returns the components explicitly typed:
.tp 8
.lm +4
.s.i -4;17 IN typedfields <=> node was typed
.i -4;#7 IN typedfields <=> devicename was typed
.i -4;#6 IN typedfields <=> directory was typed
.i -4;#2 IN typedfields <=> filename was typed
.i -4;#1 IN typedfields <=> filetype was typed
.i -4;#0 IN typedfields <=> version was typed
.i -4;#8 IN typedfields <=> filespecification contains wildcard
.lm -4
.tp 10

Other bits in typedfields are reserved for FileNames. "Term"
returns the status of the input termination:
.lm +4
.s.i -4;normal##:#normally terminated
.i -4;empty###:#normally terminated, but name is empty
.i -4;escape##:#_^Z is typed, no file specified.
.i -4;error###:#name is syntactically illegal
.lm -4
.tp 7.s.i -4;PROCEDURE ReadOption(VAR option#:#ARRAY OF CHAR
.i -4;#####################VAR length#:#CARDINAL);

To be called repeatedly after FileName, until length = 0.
The characters of the next option are returned in "optstr"
(terminated with a 0C character if length <= HIGH(optstr) ).
.lm -4
.appendix ^~Miscellaneous Procedures\~
.lm 8
.rm 72
This appendix describes the MODULA-2 specific procedures available to
the programmer. Included are procedures to perform the following
functions:
.lm +8
.s.i -4;o###Numerical and ASCII conversion
.s.i -4;o###Process scheduling
.s.i -4;o###Mathematical, trigonometric and complex operations
.s.i -4;o###Date and time procedures
.lm -8
.subttl Conversions
.page
.hl 1 Numerical Conversion Procedures
This section describes the VAX/VMS MODULA-2 numerical conversion
procedures. The functions provided include
.lm +8
.s
.i -4;o###Number to ASCII string conversions
.i -4;o###ASCII string to number conversions
.i -4;o###Number to number conversions
.lm -8
.lm +4
.b
.i -4;^&MODULE Name\&
.b
Conversions
.b
.i -4;^&EXPORTed\&
.b
.nj
Done,
NumToString,
OctToString,  HexToString,    IntToString,    CardToString,
RealToString, DFloatToString, GFloatToString, HFloatToString,
.b
StringToOct,  StringToHex,    StringToInt,    StringToCard,
StringToReal, StringToDFloat, StringToGFloat, StringToHFloat,
.b
ByteToInt,
ShortToInt,
IntToReal,   IntToDFloat,  IntToGFloat,    IntToHFloat,
RealToInt,   RealToDFloat, RealToGFloat,   RealToHFloat,
DFloatToInt, DFloatToReal, DFloatToGFloat, DFloatToHFloat,
GFloatToInt, GFloatToReal, GFloatToDFloat, GFloatToHFloat,
HFloatToInt, HFloatToReal, HFloatToDFloat, HFloatToGFloat;
.j
.b
.i -4;^&IMPORTs\&
.b
.nj
FROM SYSTEM D__FLOATING, G__FLOATING, H__FLOATING, BYTE, SHORTWORD, WORD
.j
.b
.i -4;^&Procedure Descriptions\&
.lm -4
.hl 2 Output Conversion Procedures
.lm +4
.tp 6.s.i -4;PROCEDURE NumToString#(num#:#WORD;
.i -4;#######################len, base#:#CARDINAL;
.i -4;#######################VAR s#:#ARRAY OF CHAR);

Convert the WORD "num" to an ASCII text string "s" of length
"len" in radix "base".
.tp 6.s.i -4;PROCEDURE OctToString#(num#:#WORD; len#:#CARDINAL;
.i -4;#######################VAR s#:#ARRAY OF CHAR);

Convert the WORD "num" to an octal ASCII text string "s" of
length "len".
.tp 6.s.i -4;PROCEDURE HexToString#(num#:#WORD; len#:#CARDINAL;
.i -4;#######################VAR s#:#ARRAY OF CHAR);

Convert the WORD "num" to a hexadecimal ASCII text string "s" of
length "len".
.tp 6.s.i -4;PROCEDURE IntToString#(num#:#INTEGER; len#:#CARDINAL;
.i -4;#######################VAR s#:#ARRAY OF CHAR);

Convert the INTEGER "num" to an ASCII text string "s" of length
"len".
.tp 6.s.i -4;PROCEDURE CardToString#(num#:#CARDINAL; len#:#CARDINAL;
.i -4;#######################VAR s#:#ARRAY OF CHAR);

Convert the CARDINAL "num" to an ASCII text string "s" of
length "len".
.tp 6.s.i -4;PROCEDURE RealToString#(num#:#REAL; len#:#CARDINAL;
.i -4;########################VAR s#:#ARRAY OF CHAR);

Convert a single precision floating point value "num" into
an ASCII text string "s" of length "len".
.tp 6.s.i -4;PROCEDURE DFloatToString#(num#:#D__FLOATING; len#:#CARDINAL;
.i -4;##########################VAR s#:#ARRAY OF CHAR);

Convert a D format floating point value "num" into an ASCII
text string "s" of length "len".
.tp 6.s.i -4;PROCEDURE GFloatToString#(num#:#G__FLOATING; len#:#CARDINAL;
.i -4;##########################VAR s#:#ARRAY OF CHAR);

Convert a G format floating point value "num" to an ASCII
text string "s" of length "len".
.tp 6.s.i -4;PROCEDURE HFloatToString#(num#:#H__FLOATING; len#:#CARDINAL;
.i -4;##########################VAR s#:#ARRAY OF CHAR);

Convert an H format floating point value "num" to an ASCII
text string "s" of length "len".
.test page 36
.lm -4
.hl 2 Input Conversion Procedures
.lm +4
.tp 6.s.i -4;PROCEDURE StringToInt#(s#:#ARRAY OF CHAR)#:#INTEGER;

Convert a decimal ASCII text string "s" to an INTEGER
result.
.tp 6.s.i -4;PROCEDURE StringToOct#(s#:#ARRAY OF CHAR)#:#CARDINAL;

Convert an octal ASCII text string "s" to a CARDINAL result.
.tp 6.s.i -4;PROCEDURE StringToHex#(s#:#ARRAY OF CHAR)#:#CARDINAL;

Convert a hexadecimal ASCII text string "s" to a CARDINAL
result.
.tp 6.s.i -4;PROCEDURE StringToCard#(s#:#ARRAY OF CHAR)#:#CARDINAL;

Convert a decimal ASCII text string "s" to a CARDINAL
result.
.tp 6.s.i -4;PROCEDURE StringToReal#(s#:#ARRAY OF CHAR)#:#REAL;

Convert a real ASCII text string "s" to a single precision
floating point result.
.tp 6.s.i -4;PROCEDURE StringToDFloat#(s#:#ARRAY OF CHAR)#:#D__FLOATING;

Convert a real ASCII text string "s" to a D format floating
point result.
.tp 6.s.i -4;PROCEDURE StringToGFloat#(s#:#ARRAY OF CHAR)#:#G__FLOATING;

Convert a real ASCII text string "s" to a G format floating
point result.
.tp 6.s.i -4;PROCEDURE StringToHFloat#(s#:#ARRAY OF CHAR)#:#H__FLOATING;

Convert a real ASCII text string "s" to an H format floating
point result.
.test page 30
.lm -4
.hl 2 Numeric Conversion Procedures
.lm +4
.tp 6.s.i -4;PROCEDURE ByteToInt#(num#:#BYTE)#:#INTEGER;

Convert a BYTE "num" to an INTEGER result.
.tp 6.s.i -4;PROCEDURE ShortToInt#(num#:#SHORTWORD)#:#INTEGER;

Convert a SHORTWORD "num" to an INTEGER result.
.tp 6.s.i -4;PROCEDURE IntToReal#(num#:#INTEGER)#:#REAL;

Convert an INTEGER "num" to a single precision floating
point result.
.tp 6.s.i -4;PROCEDURE IntToDFloat#(num#:#INTEGER)#:#D__FLOATING;

Convert an INTEGER "num" to a D format floating point
result.
.tp 6.s.i -4;PROCEDURE IntToGFloat#(num#:#INTEGER)#:#G__FLOATING;

Convert an INTEGER "num" to a G format floating point
result.
.tp 6.s.i -4;PROCEDURE IntToHFloat#(num#:#INTEGER)#:#H__FLOATING;

Convert an INTEGER "num" to an H format floating point
result.
.tp 6.s.i -4;PROCEDURE RealToInt#(num#:#REAL)#:#INTEGER;

Convert a single precision floating point "num" to an
INTEGER result.
.tp 6.s.i -4;PROCEDURE RealToDFloat#(num#:#REAL)#:#D__FLOATING;

Convert a single precision floating point "num" to a D
format floating point result.
.tp 6.s.i -4;PROCEDURE RealToGFloat#(num#:#REAL)#:#G__FLOATING;

Convert a single precision floating point "num" to a G
format floating point result.
.tp 6.s.i -4;PROCEDURE RealToHFloat#(num#:#REAL)#:#H__FLOATING;

Convert a single precision floating point "num" to an H
format floating point result.
.tp 6.s.i -4;PROCEDURE DFloatToInt#(num#:#D__FLOATING)#:#INTEGER;

Convert a D format floating point "num" to an INTEGER
result.
.tp 6.s.i -4;PROCEDURE DFloatToReal#(num#:#D__FLOATING)#:#REAL;

Convert a D format floating point "num" to a single
precision floating point result.
.tp 6.s.i -4;PROCEDURE DFloatToGFloat#(num#:#D__FLOATING)#:#G__FLOATING;

Convert a D format floating point "num" to a G format
floating point result.
.tp 6.s.i -4;PROCEDURE DFloatToHFloat#(num#:#D__FLOATING)#:#H__FLOATING;

Convert a D format floating point "num" to an H format
floating point result.
.tp 6.s.i -4;PROCEDURE GFloatToInt#(num#:#G__FLOATING)#:#INTEGER;

Convert a G format floating point "num" to an INTEGER
result.
.tp 6.s.i -4;PROCEDURE GFloatToReal#(num#:#G__FLOATING)#:#REAL;

Convert a G format floating point "num" to a single
precision floating point result.
.tp 6.s.i -4;PROCEDURE GFloatToDFloat#(num#:#G__FLOATING)#:#D__FLOATING;

Convert a G format floating point "num" to a D format
floating point result.
.tp 6.s.i -4;PROCEDURE GFloatToHFloat#(num#:#G__FLOATING)#:#H__FLOATING;

Convert a G format floating point "num" to an H format
floating point result.
.tp 6.s.i -4;PROCEDURE HFloatToInt#(num#:#H__FLOATING)#:#INTEGER;

Convert an H format floating point "num" to an INTEGER
result.
.tp 6.s.i -4;PROCEDURE HFloatToReal#(num#:#H__FLOATING)#:#REAL;

Convert an H format floating point "num" to a single
precision floating point result.
.tp 6.s.i -4;PROCEDURE HFloatToDFloat#(num#:#H__FLOATING)#:#D__FLOATING;

Convert an H format floating point "num" to a D format
floating point result.
.tp 6.s.i -4;PROCEDURE HFloatToGFloat#(num#:#H__FLOATING)#:#G__FLOATING;

Convert an H format floating point "num" to a G format
floating point result.
.lm -4
.f
.subttl ProcessScheduler
.page
.hl 1 Process Scheduling
This section describes the VAX/VMS process scheduling procedures.
.lm +4
.s.i -4;^&MODULE Name\&
.b
####ProcessScheduler
.b
.i -4;^&EXPORTed\&
.b
SIGNAL, StartProcess, SEND, WAIT, Awaited, InitSignal;
.b
.i -4;^&IMPORTs\&
.b
ADDRESS
.b
.i -4;^&Procedure Descriptions\&
.s.i -4;PROCEDURE StartProcess#(p#:#PROC; a#:#ADDRESS; n#:#CARDINAL);

Starts process p with workspace at a of length n bytes
.s.i -4;PROCEDURE SEND#(VAR s#:#SIGNAL);

Resume first process waiting for SIGNAL s
.s.i -4;PROCEDURE WAIT#(VAR s#:#SIGNAL);

Insert process at end of queue waiting for SIGNAL s and resume
any process that is ready
.s.i -4;PROCEDURE Awaited#(s#:#SIGNAL)#:#BOOLEAN;
.s.i -4;PROCEDURE InitSignal#(VAR s#:#SIGNAL);
.lm -4
.subttl MathLibx
.page
.hl 1 Intrinsic Mathematical Procedures
This section describes the mathematical procedures available to MODULA-2
programmers:
.lm +8
.s
.i -4;o###Floating point trigonometric functions
.i -4;o###Complex functions
.i -4;o###Exponentiation
.i -4;o###Complex exponentiation
.i -4;o###Random number generator
.i -4;o###Miscellaneous functions
.lm -8

These routines support all floating point formats as follows:
.tp 12
.figure 4
.c;+--------------+---------------+
.c;|    FORMAT    |  MODULE NAME  |
.c;+--------------+---------------+
.c;|  F__FLOATING  |   MATHLIB0    |
.c;|  D__FLOATING  |   MATHLIB1    |
.c;|  G__FLOATING  |   MATHLIB2    |
.c;|  H__FLOATING  |   MATHLIB3    |
.c;+--------------+---------------+
.lm +4
.b
.i -4;^&MODULE Name\&
.b
MATHLIB0 (F__FLOATING)
.br
MATHLIB1 (D__FLOATING)
.br
MATHLIB2 (G__FLOATING)
.br
MATHLIB3 (H__FLOATING)
.b
.i -4;^&EXPORTed\&
.b
.nj
Real,
arccos, arcsin, arctan, arctan2, arctanh,
cosh, sinh, tanh, cos, sin, tan,
log, ln, log2, exp, sqrt,
.b
COMPLEX,
cabs, conjg, ccos, cmul, cdiv, cexp, imag, complex,
cln, real, csin, csqrt,
.b
power,
cpower,
.b
random,
.b
mod;
.j
.b
.i -4;^&IMPORTs\&
.b
FROM SYSTEM QUADWORD
.b
.page
.i -4;^&Procedure Descriptions\&
.lm -4.hl 2 Trigonometric Function
.lm +4
.tp 8.s.i -4;PROCEDURE sin#(arg#:#Real)#:#Real;

Returns the sine of the input argument "arg", expressed in
radians.
.tp 8.s.i -4;PROCEDURE cos#(arg#:#Real)#:#Real;

Returns the cosine of the input argument "arg", expressed in
radians.
.tp 8.s.i -4;PROCEDURE tan#(arg#:#Real)#:#Real;

Returns the tangent of the input argument "arg", expressed in
radians
.tp 8.s.i -4;PROCEDURE arcsin#(arg#:#Real)#:#Real;

Returns the arcsine in radians of the input argument "arg".
.tp 8.s.i -4;PROCEDURE arccos#(arg#:#Real)#:#Real;

Returns the arccosine in radians of the input argument "arg".
.tp 8.s.i -4;PROCEDURE arctan#(arg#:#Real)#:#Real;

Returns the arctangent in radians of the input argument "arg".
.tp 8.s.i -4;PROCEDURE arctan2#(arg1,#arg2#:#Real)#:#Real;

Returns the arctangent in radians of the ratio of the inut arguments,
"arg1/arg2".
.tp 8.s.i -4;PROCEDURE sinh#(arg#:#Real)#:#Real;

Returns the hyperbolic sine of the input argument "arg".
.tp 8.s.i -4;PROCEDURE cosh#(arg#:#Real)#:#Real;

Returns the hyperbolic cosine of the input argument "arg".
.tp 8.s.i -4;PROCEDURE tanh#(arg#:#Real)#:#Real;

Returns the hyperbolic tangent of the input argument "arg".
.tp 8.s.i -4;PROCEDURE arctanh#(arg#:#Real)#:#Real;

Returns the hyperbolic arctangent of the input argument "arg".
.test page 48
.lm -4
.hl 2 Logarithmic and Exponential Functions
.lm +4
.tp 8.s.i -4;PROCEDURE log#(arg#:#Real)#:#Real;

Returns the common logarithm (base 10) of the input argument "arg".
.tp 8.s.i -4;PROCEDURE ln#(arg#:#Real)#:#Real;

Returns the natural logarithm (base e) of the input argument "arg".
.tp 8.s.i -4;PROCEDURE exp#(arg#:#Real)#:#Real;

Returns e (2.71828) raised to the input argument "arg".
.tp 8.s.i -4;PROCEDURE log2#(arg#:#Real)#:#Real;

Returns the logarithm (base 2) of the input argument "arg".
.tp 8.s.i -4;PROCEDURE sqrt#(arg#:#Real)#:#Real;

Returns the square root of the input argument "arg".
.tp 8.s.i -4;PROCEDURE power#(b,#e#:#Real)#:#Real;

Returns the real result of the input argument "b" raised to the
"e" power.
.test page 50
.lm -4
.hl 2 Complex Functions
.lm +4
.tp 8.s.i -4;PROCEDURE cabs#(arg#:#COMPLEX)#:#Real;

Returns the complex absolute value of the complex input argument "arg".
.tp 8.s.i -4;PROCEDURE complex#(argreal#argimag#:#Real)#:#COMPLEX;

Returns the complex value of the real and imaginary inputs
"argreal" and "argimag".
.tp 8.s.i -4;PROCEDURE imag#(arg#:#COMPLEX)#:#Real;

Returns the imaginary part of the complex input argument "arg".
.tp 8.s.i -4;PROCEDURE real#(arg#:#COMPLEX)#:#Real;

Returns the real part of the complex input argument "arg".
.tp 8.s.i -4;PROCEDURE conjg#(arg#:#COMPLEX)#:#COMPLEX;

Returns the complex conjugate of the complex input argument
"arg" (r,i), as (r,-i).
.tp 8.s.i -4;PROCEDURE csin#(arg#:#COMPLEX)#:#COMPLEX;

Returns the complex sine of the complex input argument
"arg", expressed in radians.
.tp 8.s.i -4;PROCEDURE ccos#(arg#:#COMPLEX)#:#COMPLEX;

Returns the complex cosine of the complex input argument
"arg", expressed in radians.
.tp 8.s.i -4;PROCEDURE cln#(arg#:#COMPLEX)#:#COMPLEX;

Returns the complex natural logarithm of the complex input
argument "arg".
.tp 8.s.i -4;PROCEDURE cexp#(arg#:#COMPLEX)#:#COMPLEX;

Returns the complex exponential of the complex input argument "arg".
.tp 8.s.i -4;PROCEDURE csqrt#(arg#:#COMPLEX)#:#COMPLEX;

Returns the complex square root of the complex input argument
"arg".
.tp 8.s.i -4;PROCEDURE cpower#(b,#e#:#COMPLEX)#:#COMPLEX;

Returns the comlex result of the complex input arguments "b"
raised to the "e" power.
.tp 8.s.i -4;PROCEDURE cmul#(arg1,#arg2#:#COMPLEX)#:#COMPLEX;

Returns the complex product of the complex input arguments
"arg1" and "arg2".
.tp 8.s.i -4;PROCEDURE cdiv#(arg1,#arg2#:#COMPLEX)#:#COMPLEX;

Returns the complex quotient of the complex input arguments
"arg1" and "arg2".
.test page 30
.lm -4
.hl 2 Random Number Generator
.lm +4
.tp 12.s.i -4;PROCEDURE random#(VAR#s#:#INTEGER)#:#Real;

Returns a single precision floating point pseudorandom number
uniformly distributed between 0.0 and 1.0 inclusive. The
argument "s" is used as the seed for the generation of the
number, and is automatically updated. There are no
restrictions on the value of seed, although it should be
initialized to different values on separate runs in order to
obtain different random sequences.
.test page 15
.lm -4
.hl 2 Miscellaneous Functions
.lm +4
.tp 8.s.i -4;PROCEDURE mod#(arg1,#arg2#:#Real)#:#Real;

Returns "arg1" MODULO "arg2".
.tp 8.s.i -4;PROCEDURE done#:#BOOLEAN;

Returns TRUE if the last mathematical operation was
successful, FALSE otherwise.
.lm -4
.subttl Date and Time Procedures
.page
.hl 1 Date and Time Procedures
These procedures provide the means for getting the system time 
and date, and for conversion from internal binary format to 
ASCII text strings.
.lm +4
.s.i -4;^&MODULE Name\&
.b
DateTime
.b
.i -4;^&EXPORTed\&
.b
TimeType, Time, Date, ConvertTime, ConvertDate
.b
.i -4;^&IMPORTed\&
.b
FROM SYSTEM IMPORT QUADWORD;
.b
.i -4;^&Procedure Descriptions\&
.tp 8.s.i -4;PROCEDURE Time (VAR time#:#TimeType);

Returns current system time in system format
.tp 8.s.i -4;PROCEDURE Date (VAR date#:#ARRAY OF CHAR);

Returns current system time as string in the format 
"HH:MM:SS.DD".
.tp 8.s.i -4;PROCEDURE ConvertTime (time#:#TimeType; 
.i -4;#######################VAR date#:#ARRAY OF CHAR);

Converts time given as argument in internal format into text 
string.
.tp 8.s.i -4;PROCEDURE ConvertDate (date#:#ARRAY OF CHAR; 
.i -4;#######################VAR time#:#TimeType);

Converts text string given as argument into system time format
.lm -4 
