% File:    DBPLVAXGuide.tex
% Date:    13.12.1991
% Author:  Florian Matthes, Gerald Schr\"oder
% Purpose: VAX DBPL / Modula-2 User's Guide
%
\documentstyle[a4]{report}

\parskip=5pt plus 2pt

%\makeindex

\newenvironment{syntax}{\sf\begin{tabbing}
space\= \kill}{\end{tabbing}}

\newenvironment{command}{\tt\begin{tabbing}
space\= \kill}{\end{tabbing}}

%
%  sections concerning only DBPL are marked by ...
%
\newcommand{\bdbpl}{\marginpar{$\top$}}
\newcommand{\edbpl}{\marginpar{$\bot$}}

\begin{document}

\begin{titlepage}
%------------------------------------------------------------------
 {\noindent\large DBPL Memo 121-91
 \vskip 2.5cm
 {\noindent\huge VAX Modula-2 User's Guide\\[0.5\baselineskip]
                 VAX DBPL User's Guide}
 \vskip 2.0cm
 \noindent F.~Matthes \\
 \noindent J.~W.~Schmidt \\
 \noindent G.~Schr\"oder \\
 \vskip 2cm
\noindent This document describes how to compile, link and execute 
Modula-2 programs on a VAX under the VMS operating system.
The VAX 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 Z\"urich.

\noindent This document also describes how to compile, link and execute
DBPL programs on a VAX under the VMS operating system. DBPL is a
relational database programming language that has Modula-2 as its
algorithmic kernel. The DBPL Compiler is a fully upward compatible
extension of the VAX Modula-2 Compiler.

 \noindent 
 \vskip 2cm
 \noindent Software Version 2.0, December 1991
 \vskip 2cm
 \noindent Arbeitsbereich DBIS\\
  Fachbereich Informatik\\
  Universit\"at Hamburg\\
  Schl\"uterstra{\ss}e 70\\
  D-2000 Hamburg 13\\
  Federal Republic of Germany
  }
 \end{titlepage}
% -------------------------------------------------------------------

\tableofcontents

% -------------------------------------------------------------------
\newpage

\section*{PREFACE}


\subsection*{Manual Objectives}

The VAX Modula-2 User's Guide has been designed to support the
development and execution of Modula-2 programs in the VAX/VMS
environment.  The Modula-2 language constructs are described in the
Modula-2 Report, 3rd Edition, by N.~Wirth \cite{Wirt85b}. The compiler
also incorporates some extensions proposed in the emerging ISO Modula-2
standard \cite{MODISO}.

\bdbpl
Note for DBPL users: The VAX DBPL User's Guide describes the extensions
to the VAX Modula-2 compiler that support the development and execution
of DBPL database applications in the VAX/VMS environment.  The DBPL
language constructs are described in the ``Report on the Database
Programming Language DBPL'' \cite{SEM88}. Further documentation and
publications on DBPL are available through Hamburg University (see also
references in the bibliography).
\edbpl

\subsection*{Intended Audience}

This manual is intended for programmers who have a general knowledge of
the VAX/VMS Command Language and the DBPL 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. 

\subsection*{Related Documents}

\noindent VAX-11 Symbolic Debugger Reference Manual.

\noindent VAX-11 Linker Reference Manual.

\noindent VAX-11 Architecture Handbook.

\noindent VAX-11 PASCAL User's Guide.

\noindent VAX-11 Run-Time Library Reference Manual.

\noindent VAX/VMS System Services Reference Manual.


\subsection*{Notational Conventions}

Within command language descriptions

\begin{description}
\item [] {\Large [ ]} large square brackets indicate that the enclosed
sequence of symbols is optional,
\item [] \{ \} braces indicate that the enclosed sequence of symbols may be
repeated zero or more times.
\end{description}

Parts of the text which apply to extensions of the compiler that are
needed to use it as a DBPL rather than a Modula-2 compiler are marked by
$\top$ and $\bot$.


\subsection*{DBPL and Modula-2}

DBPL is an extended version (true superset) of Modula-2.
The VAX DBPL compiler accepts both DBPL and Modula-2 modules. 
So you can replace the term ``DBPL'' by ``Modula-2'' in the following text. 
Parts that apply only to DBPL modules are marked by $\top$ and $\bot$.

% -------------------------------------------------------------------------
\newpage

\chapter{Preliminaries}

% --------

\section{Files}
\index{compilation unit}%
\index{definition module}%
\index{implementation module}%
\index{main module}%

In general, a application is composed of a number of separate
{\em modules}. 

The first step in creating an application program is to edit the different
source files containing the compilation units (main modules, definition
modules and implementation modules). 
\begin{quote}
\begin{center}
{\bf NOTE}
\end{center}
The DBPL compiler distinguishes upper and lower case characters.
All reserved words and standard names must be capitalized.
\end{quote}

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

Six kinds of output files may be produced:
\index{symbol file}%
\index{object file}%
\index{image file}%
\index{dictionary file}%
\index{data file}%
\index{index file}%
\index{listing file}%

\begin{itemize}

\item
Compilation of a definition module yields in a {\bf symbol file},
containing a module description readable by the compiler.
This file is needed when the implementation module or a compilation unit
importing the module is compiled.

\item
The result of processing an implementation or main module is an 
{\bf object file} readable by the linker. 

\item
\bdbpl
Compilation of a database definition, implementation or main module
additionally generates a {\bf database dictionary file} and (several)
{\bf data files} and {\bf index files} for persistent database
variables.
\edbpl

\item
Optionally, a {\bf listing file} can be produced. It contains a listing of
the module with error messages. A machine code listing and
a cross reference table can be included.

\item
Finally, the separate object files have to be linked together to form an
executable {\bf image file}, which can be executed by the {\tt RUN} command.

\end{itemize}

% -----------

\section{File Specifications and Defaults}

A full VAX/VMS file specification has the following form:
                
\begin{center}
{\tt node::device:[directory]filename.filetype;version}
\end{center}

Node, device, directory, and version are optional items;
their default values are:

\begin{center}
\begin{tabular}{l l}
{\tt node}:      & applicable only to systems supporting DECnet-VAX,\\
{\tt device}:	 & user's current device,\\
{\tt directory}: & user's current default directory,\\
{\tt version}:   & highest version on input,\\
                 & highest version+1 on output.\\
\end{tabular}
\end{center}

The filetype specification may be omitted in certain cases.
The default type depends on usage:
\index{filetype specifications}%

\begin{center}
\begin{tabular}{l l}
\tt DEF,MOD,DBP  & source files, input to DBPL compiler \\
\tt SYM          & symbol file, input to and  \\
                 & output from DBPL compiler \\
 \\
\tt DIC,DAT,I00  & database files, output from DBPL compiler\\
                 & (when creating a database)\\
\tt OBJ          & object code file, output from DBPL compiler\\
\tt LIS          & source file listing, output from DBPL compiler\\
 \\
\tt OBJ          & object code file, input to linker\\
\tt EXE          & executable file, output from linker\\
\end{tabular}
\end{center}

% -----------------------------------------------------------------------

\chapter{Compiling}
\label{compiling}
\index{definition module}%
\index{implementation module}%
\index{application program}%
\index{compilation unit}%
\index{symbol file}%

Each DBPL 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 \ref{qualifier}).
\bdbpl
The DBPL compiler is invoked by the {\tt DBPLC} or {\tt MODULA} command 
which has the following form:
\index{{\tt DBPLC} command}%
 
\begin{command}
\>\$ DBPLC \{/qualifier\} file-spec \{/qualifier\}
\end{command}

respectively

\begin{command}
\>\$ MODULA \{/qualifier\} file-spec \{/qualifier\}
\end{command}

\begin{description}
\item [file-spec] ~\\
determines the source file containing the compilation unit.
Only one file is accepted.
The default file type is {\tt MOD} for Modula-2 files 
(command {\tt MODULA} or qualifier {\tt /NODBPL})
and {\tt DBP} for DBPL files 
(command {\tt DBPLC} or qualifier {\tt /DBPL}). 
\edbpl
Type {\tt DEF} is recommended for definition modules.
\end{description}

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

\begin{command}
\>\$ DBPLC \fbox{RETURN}\\
\>\$\_File:
\end{command}

On termination the DBPL compiler returns a status code in the reserved 
global symbols \$STATUS and \$SEVERITY which indicates either a success or a 
severe error during compilation.
This information can be used for controlling the execution of VMS command
procedures (see {\em VAX/VMS Guide to Using Command Procedures\/} for details).
\index{status return}\index{[\$STATUS]STATUS}\index{[\$SEVERITY]SEVERITY}%

Processing of a source file comprises several passes.
Temporary work files named {\tt INTERFILE.DVC} serve for interpass communication.
\index{{\tt INTERFILE.DVC}}%
The normal succession of passes is for definition modules 

\begin{enumerate}
\item syntax analysis
\item declaration analysis
\item symbol file generation
\item listing generation (optional)
\item
\bdbpl
database creation (for database definition modules)
\edbpl
\end{enumerate}

\noindent and for implementation and main modules

\begin{enumerate}
\item syntax analysis
\item declaration analysis
\item body analysis
\item code generation
\item listing generation (optional)
\item
\bdbpl
database creation (for database modules).
\edbpl
\end{enumerate}

If the compiler option {\tt /LOG} is specified, the succesion of passes mentioned
above is displayed. A more detailed information about compiler options 
is given in section~\ref{qualifier}.

\index{compatibility DBPL / Modula-2}%
VAX/VMS Modula-2 symbol files are compatible with DBPL symbol files,
hence modules written in Modula-2 may also be imported to DBPL 
programs.


\section{Compiler Command Qualifiers}
\label{qualifier}

{\tt DBPLC} resp. {\tt 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 ``{\tt NO}'', e.g., ``{\tt NOLIST}'' 
is the negative form of ``{\tt LIST}''. 
If you want to change the default values of the qualifiers, edit the file 
{\tt DBPLC.CLD} resp. {\tt MODULA.CLD}. 
A default value is marked by the keyword ``{\tt DEFAULT}''.
All other values are set by default to ``{\tt NO}\dots''. 
The meaning of the qualifiers and their default values is listed below.

\begin{description}

\item [{\tt\bf CHECK}] ~\\
\index{{\tt DBPLC} command}%
\index{{\tt MODULA} command}%
\index{command qualifiers~{\tt /CHECK}}%
\index{run-time checks}%
Code is generated to perform run-time checks for out-of-range array bounds
and case labels.

By default, {\tt CHECK} is enabled.


\item [{\tt\bf CREATE}] ~\\
\index{command qualifiers~{\tt /CREATE}}%
A new database is created when compiling a database definition module.

By default, {\tt CREATE} is disabled. 

\item [{\tt\bf CROSS\_REFERENCE}] ~\\
\index{command qualifiers~{\tt /CROSS\_REFERENCE}}%
A cross reference table is included in the source listing.
This qualifier is effective only when used in conjunction with {\tt LIST}.

 By default, {\tt CROSS\_REFERENCE} is disabled.

\item [{\tt\bf DBPL}] ~\\
\index{command qualifiers~{\tt /DBPL}}%
A DBPL module will be compiled. All DBPL enhancements of Modula-2 are available.

By default, {\tt DBPL} is enabled when using command {\tt DBPLC} 
and disabled when using command {\tt MODULA}.

\item [{\tt\bf DEBUG}] ~\\
\index{command qualifiers~{\tt /DEBUG}}%
The {\tt DEBUG} qualifier produces information to be used by the VAX Symbolic 
Debugger and the run-time error reporting mechanism.

By default, {\tt DEBUG} is disabled and only traceback information is generated.

\item [{\tt\bf LIST}] ~\\
\index{command qualifiers~{\tt /LIST}}%
A listing file is written.
\index{listing file}%
The qualifier has the general form:

\begin{center}
{\tt /LIST{\Large [}=file-spec-list{\Large ]}}
\end{center}

You may include a file specification for the listing file.
If no specification is given a file of type {\tt 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 {\tt CROSS\_REFERENCE} and/or
{\tt MACHINE\_CODE}.

By default, {\tt 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!).

\item [{\tt\bf LOG}] ~\\
\index{command qualifiers~{\tt /LOG}}%
If the {\tt LOG} option is enabled, the following information is displayed:

   \begin{itemize}
   \item compiler version,
   \item qualifiers applied,
   \item succession of the compiler passes, and
   \item the names of the symbol files read.
   \end{itemize}

 By default, {\tt LOG} is disabled for interactive mode and enabled for batch mode.

\item [{\tt\bf MACHINE\_CODE}] ~\\
\index{command qualifiers~{\tt /MACHINE\_CODE}}%
 A readable representation of the generated code is included in the source 
listing.
This qualifier is effective only in conjunction with the {\tt LIST} qualifier.
\index{command qualifiers~{\tt /LIST}}%

 By default, {\tt MACHINE\_CODE} is disabled.

\item [{\tt\bf OBJECT}] ~\\
\index{command qualifiers~{\tt /OBJECT}}%
 An object file for the linker is produced.
\index{object file}%
The qualifier has the form:

\begin{center}
{\tt /OBJECT{\Large [}=file-spec{\Large ]}}
\end{center}
\index{object file}%

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

By default, {\tt OBJECT} is enabled for main and implementation modules,
disabled otherwise.

\item [{\tt\bf QUERY}] ~\\
\index{command qualifiers~{\tt /QUERY}}%
The {\tt QUERY} qualifier forces the compiler to ask explicitly for the symbol
files to be read.
\index{symbol file}%

By default, {\tt QUERY} is disabled and the compiler uses a standard strategy to
search for the symbol files (see section~\ref{search}).
\index{symbol file~search strategy}%

The standard search strategy is also effective when {\tt QUERY} is enabled but no
file specification is given.

\item [{\tt\bf SYMFILE}] ~\\
\index{command qualifiers~{\tt /SYMFILE}}%
 A symbol file is created if the source contains a definition module.
It has the form:
\index{symbol file}%

\begin{center}
{\tt /SYMFILE{\Large [}=file-spec{\Large ]}}
\end{center}

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

By default, {\tt SYMFILE} is enabled for definition modules,
disabled otherwise.

\end{description}

\begin{center}
\begin{tabular}{l l l}
\multicolumn{3}{c}{Summary:}\\
\multicolumn{3}{c}{DBPL Command Qualifiers}\\
\\
{\em Qualifier} & {\em Negative Form} & {\em Default}\\
\\
\tt /CHECK            & \tt /NOCHECK            & \tt /CHECK \\
\tt /CREATE           & \tt /NOCREATE           & \tt /NOCREATE \\
\tt /CROSS\_REFERENCE & \tt /NOCROSS\_REFERENCE & \tt /NOCROSS\_REFERENCE \\
\tt /DBPL             & \tt /NODBPL             & \tt /DBPL \\
\tt /DEBUG            & \tt /NODEBUG            & \tt /NODEBUG \\
\tt /LIST{\Large [}=file-spec{\Large ]}
                      & \tt /NOLIST             & \tt /NOLIST (interact.) \\
                      &                         & \tt /LIST (batch) \\
\tt /LOG              & \tt /NOLOG              & \tt /NOLOG (interactive) \\
                      &                         & \tt /LOG (batch) \\
\tt /MACHINE\_CODE    & \tt /NOMACHINE\_CODE    & \tt /NOMACHINE\_CODE \\
\tt /OBJECT{\Large [}=file-spec{\Large ]}
                      & \tt /NOOBJECT           & \tt /OBJECT \\
\tt /QUERY            & \tt /NOQUERY            & \tt /NOQUERY \\
\tt /SYMFILE{\Large [}=file-spec{\Large ]}
                      & \tt /NOSYMFILE          & \tt /SYMFILE \\
\end{tabular}
\end{center}

% ----------

\section{Local Control of Run-Time Checks}
\index{run-time checks}%

The insertion of run-time checks into the generated code can additionally be
controlled during compilation by using the S- and T-options. An option must be
entered into the source text at the beginning of a comment clause; it has the
general form: 

\begin{syntax}
   Option  = "\$" Name Switch.\\
   Name    = "S"$|$"T".\\
   Switch  = "+"$|$"-"$|$"=".
\end{syntax}

where the associated switch

\begin{tabular}{c l}
   + &  enables run-time checks,\\
   - &  disables run-time checks,\\
   = &  resets the option to the previous value.\\
\end{tabular}

The S-option controls subrange checks, e.g. when assigning a value to a 
variable of a subrange type. The T-options controls index checks when 
accessing arrays.

Examples:
\begin{verbatim}
   (* $T+ to generate test code when accessing arrays *)

   (* $T- to turn off test code generation *)
   
   (*$S-*) i:=j; (*$S=*) (* no subrange checks *)
\end{verbatim}

% ----------

\section{Search Strategies}
\label{search}
\index{symbol file~search strategy}%

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
module's name and the file extension {\tt SYM}. 
\index{symbol file~libraries}%

\index{{\tt MOD\$LIBRARY}}\index{{\tt MOD\$LIBRARY\_n}}%
The file is first searched in the user's default directory. If the search
fails, directories with the logical names {\tt MOD\$LIBRARY, MOD\$LIBRARY\_1} up to
{\tt MOD\$\-LI\-BRARY\_9} are searched (in this order). The entire process is performed 
first in the process logical name table, second in the job logical name table,
then in the group logical name table, and finally in the system logical name 
table. 
\index{{\tt MOD\$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 
{\tt MOD\$SYSTEM} is searched. 

The result of the searching process is displayed to the user when the {\tt LOG}
option is enabled.

% ---------

\section{Compiler Listing}
\index{listing file}%
\index{DBPL command qualifiers~{\tt /LIST}}%
\index{DBPL command qualifiers~{\tt /CROSS\_REFERENCE}}%
\index{DBPL command qualifiers~{\tt /MACHINE\_CODE}}%

The contents of the listing is controlled by the command qualifiers {\tt LIST},
{\tt CROSS\_REF\-ER\-ENCE}, and {\tt MACHINE\_CODE}.
The application of {\tt 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):

\begin{itemize}
\item the name of the compilation unit,
\item the date of compilation,
\item the compiler version, and
\item a running page number.
\end{itemize}

In the second line you will find

\begin{itemize}
\item the listing subject,
\item the creation date, and
\item the name of the source file.
\end{itemize}

The listing terminates with a compilation summary,
informing about the active compiler options and giving some performance
data.

\subsection{Source Listing}
\index{listing file~source listing}%
\index{DBPL command qualifiers~{\tt /LIST}}%

Initiated by {\tt 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. 

\subsection{Cross Reference Table}
\index{listing file~cross reference listing}%
\index{DBPL command qualifiers~{\tt /CROSS\_REFERENCE}}%

Initiated by {\tt CROSS\_REFERENCE}, presupposes {\tt 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:

\begin{itemize}
\item 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. 
\item The name of the scope in which the identifier is defined, preceded by ``in''
or ``from''. This item is omitted when the name is defined at global level.
The prefix ``from'' indicates that the defining scope is external.
Alternatively, the word ``imported'' may appear if the name designates an
external module;
in this case the full symbol file name is also given.
\item The word ``exported'',
which means that the identifier is exported from the enclosing module.
\item A list of numbers of the lines where the name is referenced.
A definition line is marked by an asterisk.
\end{itemize}

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.

\subsection{Machine Code Listing}
\index{listing file~machine code listing}%
\index{DBPL command qualifiers~{\tt /MACHINE\_CODE}}%

Initiated by {\tt MACHINE\_CODE}, presupposes {\tt LIST}.

The generated code is represented as a VAX 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}

After compilation, the separate object modules of the application 
program are linked together to produce an executable image
file.

\section{The Link Command}
\index{{\tt LINK} command}%

The modules of an application program are linked with the normal {\tt LINK}
command:

\begin{command}
\>\$ LINK{/command-qualifiers} file-spec-list
\end{command}

\begin{description}
\item [command-qualifiers] ~\\
Specify output file options. 

\item [file-spec-list] ~\\
Specifies the input files to be linked.
File specifications can be separated by commas or plus signs.
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 {\tt OBJ}.

If some or all of the object files reside in a library, you can specify
this library with the qualifier {\tt /LIB}, e.g. {\tt MYLIB/LIB}.
The linker will automatically search these libraries for the needed files.
The default file type for object libraries is {\tt OLB}. 
\index{{\tt LINK}~object~libraries}%
\index{{\tt LINK} command qualifiers~{\tt /LIB}}%

\end{description}

If no other specification is given, the executable image file takes the name
of the first object file and is of type {\tt EXE}.
\index{image file}%

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. 

% ---------------------

\section{Linker Command Qualifiers}
\index{{\tt LINK} command}%

Below, a few qualifiers are listed which may be of interest to the DBPL
programmer. For some qualifiers there are also negative forms. Refer to the
{\em VAX-11 Linker Reference Manual\/} for detailed information. 


\subsection{Map File Qualifiers}

The {\tt 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: 

\begin{center}
{\tt /MAP{\Large [}=file-spec{\Large ]}}
\end{center}

where the optional file specification designates the map file.
\index{LINK command qualifiers~/MAP}\index{map file}%
The default is a file of type MAP with the name of the first object file.

By default, {\tt MAP} is disabled for interactive mode and enabled for batch mode.

In conjunction with {\tt /MAP} the modifying qualifiers {\tt BRIEF} or
{\tt FULL} and {\tt CROSS\_\-REF\-ER\-ENCE} may be used.
{\tt /BRIEF} and {\tt /FULL} define the amount of information included in the map file, as
follows: 

\begin{description}
\item [{\tt\bf BRIEF}] produces a summary of the image's characteristics and a list of
contributing modules.
\index{{\tt LINK} command qualifiers~{\tt /BRIEF}}%

\item [{\tt\bf FULL}] adds a summary of characteristics of image sections in the
linked image to the normal map file. 
\index{{\tt LINK} command qualifiers~{\tt /FULL}}%

\item [{\tt\bf CROSS\_REFERENCE}] can be used with {\tt /MAP} or {\tt /MAP/FULL} to include
cross-reference information for global symbols in the map file. 
\index{{\tt LINK} command qualifiers~{\tt /CROSS\_REFERENCE}}%

By default, {\tt CROSS\_REFERENCE} is disabled
\end{description}


\subsection{Debugging and Traceback Qualifiers}
\index{debugging a program}%

If the {\tt DEBUG} qualifier is used, the program will always be executed under the
control of the debugger. (You may suppress this by issuing {\tt /NODEBUG} with the
{\tt RUN} command.) 
\index{{\tt LINK} command qualifiers~{\tt /DEBUG}}%

By default, {\tt DEBUG} is disabled.

The {\tt TRACEBACK} qualifier is used to have error messages accompanied by symbolic
traceback information.
\index{{\tt LINK} command qualifiers~{\tt /TRACEBACK}}%

By default, {\tt TRACEBACK} is enabled.
{\tt /DEBUG} implies {\tt /TRACEBACK}.

\begin{center}
\begin{tabular}{l l l}
\multicolumn{3}{c}{Summary:}\\
\multicolumn{3}{c}{Link Command Qualifiers}\\
\\
{\em Qualifier} & {\em Negative Form} & {\em Default}\\
\\
\tt /BRIEF            & none                    & not applicable\\
\tt /CROSS\_REFERENCE & \tt /NOCROSS\_REFERENCE & \tt /NOCROSS\_REFERENCE\\
\tt /DEBUG            & \tt /NODEBUG            & \tt /NODEBUG\\
\tt /FULL             & none                    & not applicable\\
\tt /MAP{\Large [}=file-spec{\Large ]} 
                      & \tt /NOMAP              & \tt /NOMAP (interactive)\\
                      &                         & \tt /MAP (batch)\\
\tt /TRACEBACK        & \tt /NOTRACEBACK        & \tt /TRACEBACK\\
\end {tabular}
\end{center}

% ----------------

\section{Identification Checking}

The VAX DBPL compiler provides identification information for describing
the relationship between symbol files and object files belonging to the same
module.
\index{symbol file}%
\index{object file}%
\index{Entity Ident Consistency Check}%
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 {\em VAX-11 Linker Reference Manual}.

% ------------------------------------------------------------------------

\chapter{Executing}

The application program can be started by the {\tt RUN} command:

\begin{command}
\>\$ RUN{\Large [}/{\Large [}NO{\Large ]}DEBUG{\Large ]} file-spec
\end{command}

\index{{\tt RUN} command}%

The {\tt DEBUG} qualifier allows to run the program under control of the
debugger, even if you have issued the {\tt DBPLC} and {\tt LINK} commands without
this qualifier. {\tt /NODEBUG} will override a {\tt /DEBUG} given at link time.
\index{{\tt RUN} command qualifiers~{\tt /DEBUG}}%

In interactive mode, the file specification may be entered on a
separate line by typing a carriage return after the command name.
The system responds with a prompt for the file specification. 


% -----------

\section{Debugging the Program}
\index{debugging a program}%

Currently, the VAX Symbolic Debugger runs DBPL programs with the
language mode set to PASCAL. See the corresponding chapter of the
{\em PASCAL User's Guide\/}
(or the {\em VAX-11 Symbolic Debugger Reference Manual\/}) for a description.
Because of the differences between the two languages, some features work
differently, as there are: 

\begin{itemize}
\item No distinction is made between lower and upper case letters in
identifiers. 
\item Nested modules are not recognized; all variables and procedures
declared inside a nested module are made global to the compilation unit. 
\item Module bodies are treated as parameterless procedures with the names
of the modules. 

\begin{quote}
\begin{center}
{\bf NOTE}
\end{center}
The differences mentioned above may lead to name conflicts inside the debugger,
which are not always handled properly.
\end{quote}

\item Type {\tt CARDINAL} is treated as {\tt INTEGER}.
\item All variables and procedures can only be accessed in the context of
the module they are defined in (see the debugger commands {\tt SET MODULE, SET
SCOPE}). 
\item Sets are displayed and must be entered in PASCAL notation, using
square brackets (``['', ``]''). 
\item 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$.
\item Constant and type identifiers are not known to the debugger.
\item 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.
\index{debugging a program}%
\end{itemize}

\bdbpl
DBPL transactions are provided with a special condition handler which
enforces an abort of the current transaction if a severe runtime
condition is signalled. As a result, the debugger usually does not
catch transaction failures. You may direct the debugger to treat
transaction failures also by issuing the {\tt SET BREAK/EXCEPTION} command.

\begin{quote}
\begin{center}
{\bf NOTE}
\end{center}
Debugging a transaction may cause the {\bf delay of concurrent
transactions} started by other users.
\end{quote}
\edbpl

% ---------------------------------------------------------------------

\chapter{Procedure Calling Conventions}
\index{procedures}%

In the context of the VAX/VMS operating system, a procedure is a routine
entered by a CALL instruction. In a DBPL program, such a routine
can be a function or a procedure written in DBPL, a VAX/VMS system service,
or a VAX Run-Time Library procedure.

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

VAX DBPL uses the VAX CALLS instruction to call procedures. Each
time a procedure is called, the DBPL 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.

% -------------

\section{Parameter Passing Mechanisms}
\index{parameter passing mechanisms}%
\index{procedures~parameter passing}%

The VAX procedure calling standard defines three mechanisms by which
arguments are passed to procedures:

\begin{enumerate}
\item by-reference
\item by-immediate-value
\item by-descriptor
\end{enumerate}

Table \ref{parpass} describes the mechanisms that are used by the VAX 
DBPL compiler, depending on the type and the kind of the formal parameter:

\begin{table}[hbt]
\begin{center}
\begin{tabular}{| l | l | l |}\hline
type & value parameter & reference parameter \\ \hline\hline
\tt BOOLEAN       &                       &\\
\tt CHAR          &                       &\\
\tt INTEGER       &                       &\\
\tt CARDINAL      &                       &\\
\tt POINTER       &                       &\\
\tt SET           &                       &\\
    Enumeration   &                       &\\
    Subrange      &                       &\\
\tt BYTE          &  by-reference         &  by-reference\\
\tt SHORTWORD     &                       &\\
\tt WORD          &                       &\\
\tt ADDRESS       &                       &\\
\tt REAL          &                       &\\
\tt LONGREAL      &                       &\\
\tt F\_FLOATING   &                       &\\
\tt D\_FLOATING   &                       &\\
\tt G\_FLOATING   &                       &  \\
\tt H\_FLOATING   &                       &\\
\tt QUADWORD      &                       &\\
\tt OCTAWORD      &                       &\\
\hline
\tt RECORD        &                       &\\
\tt ARRAY         &                       &\\
\tt RELATION      &  by-reference         & by-reference\\
\tt SELECTOR      &                       &\\
\tt CONSTRUCTOR   &                       &\\
\hline
\tt PROCEDURE     & \multicolumn{2}{c|}{by-reference}\\
\tt TRANSACTION   & \multicolumn{2}{c|}{}\\
\hline
\end{tabular}
\caption{\label{parpass} Parameter passing mechanisms}
\end{center}
\end{table}

An open array parameter is passed by two arguments.
The parameter list created by the compiler for an open array 
parameter definition

\begin{center}
{\tt   (...; a: ARRAY OF type; ...)}
\end{center}

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

\begin{center}
{\tt   (...; \%IMMED higha: CARDINAL; \%IMMED adra : ADDRESS; ...)}
\end{center}

\noindent with {\tt adra = ADR(a)} and {\tt higha = HIGH(a)}.

% ---------------------

\section{Function Return Values}
\index{procedures~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 in table \ref{freturn}.

\begin{table}[hbt]
\begin{center}
\begin{tabular}{| l | l |}\hline
 type         &     return method\\ \hline\hline
\tt BOOLEAN       &\\
\tt CHAR          &\\
\tt INTEGER       &\\
\tt CARDINAL      &\\
\tt POINTER       &\\
    Enumeration   &     Register R0\\
    Subrange      &\\
\tt BYTE          &\\
\tt SHORTWORD     &\\
\tt WORD          &\\
\tt ADDRESS       &\\
\tt REAL          &\\ 
\tt F\_FLOATING   &\\ \hline
\tt LONGREAL      &\\ 
\tt D\_FLOATING   &\\
\tt G\_FLOATING   &     Registers R0,R1\\
\tt QUADWORD      &\\ \hline
\tt H\_FLOATING   &     by reference as the first\\
\tt OCTAWORD      &     parameter in the function's\\
                  &     parameter list\\ \hline
\end{tabular}
\caption{\label{freturn} Function value return methods}
\end{center}
\end{table}

% -----------------------

\section{Foreign Procedures}
\index{foreign definition modules}%
\index{procedures~foreign}%

Access to procedures and variables written in other VAX 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 DBPL implementation modules. 

A foreign definition module is syntactically indicated by the prefix 
``{\tt \%FOREIGN}'':

\begin{syntax}
\$ ForeignDefinitionModule =\\
\$\>"\%FOREIGN" DEFINITION MODULE ident ";"\\
\$\>\{ import \} \{ foreigndefinition \} END ident ".".
\end{syntax}

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: 
\index{parameter passing mechanisms}%
\index{procedures~parameter passing}%

\begin{syntax}
\$ ForeignFormalParameters =\\
\$\>"(" [ ForeignFPSection \{";" ForeignFPSection \}] ")"\\
\$\>[":" qualident ].\\
\$ ForeignFPSection   =\\
\$\>[ VAR ][ "\%REF" $|$ "\%IMMED" $|$ "\%STDESCR"]\\
\$\>IdentList ":" FormalType.\\
\end{syntax}

\noindent where

\index{foreign definition modules~\%IMMED}%
\index{foreign definition modules~\%REF}%
\index{foreign definition modules~\%STDESCR}%
\begin{tabular}{l l}
{\tt \%IMMED} & denotes passing by immediate value,\\
{\tt \%REF} & denotes passing by reference, and\\
{\tt \%STDESCR} & denotes passing by string descriptor.\\
\end{tabular}

As an example, we give a definition module which allows access to some 
screen handling procedures:

\begin{verbatim}
   %FOREIGN DEFINITION MODULE CommandLanguageInterface;
     ...
     PROCEDURE CLI$PRESENT
         (    %STDESCR entityDesc:ARRAY OF CHAR):CARDINAL; 

     PROCEDURE CLI$GET_VALUE
         (     %STDESCR entityDesc: ARRAY OF CHAR;
          VAR  %STDESCR retdesc:    ARRAY OF CHAR;
          VAR           retlength: CARDINAL):CARDINAL;
     ...

   END CommandLanguageInterface.
\end{verbatim}

 Foreign definition modules should not be written without knowledge about
the parameter passing mechanisms involved. 
\index{foreign definition modules}%

% -------------------------------------------------

\chapter{System Dependent Facilities}

\section{Low Level Facilities}
\index{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, DBPL 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 {\em not} checked for consistency with
language rules. 


\subsection{Type Transfer Function}
\index{low level facilities~type transfer function}%

The type transfer function {\tt SYSTEM.CAST}
serves to breach DBPL's type system. It does not involve any
actual computation but modifies the compiler's type checking. For instance, if {\tt c}
is an expression of type {\tt CARDINAL} then 
\begin{verbatim}
SYSTEM.CAST(BITSET,c)
\end{verbatim}
is interpreted as the
corresponding value of type {\tt BITSET}. This is a correspondence determined by the
underlying system and not by the programming language itself. Therefore, using 
the type transfer function requires familiarity with the internal
representation and storage allocation scheme of the corresponding data types. 

Note: The original type transfer of Modula-2 is provided by the type
name as function, e.g. {\tt BITSET(c)}. This will be changed by the
Modula-2 Standard.  The DBPL compiler supports both forms, but it is
recommended to use {\tt SYSTEM.CAST}.


\subsection{Absolute Addresses}
\index{low level facilities~absolute addresses}%

The assignment of absolute addresses is still allowed in DBPL but
this feature should be used with utmost care because all addresses are usually
relocated by the linker! The Modula-2 Standard will change this feature.

 
\subsection{The Module SYSTEM}
\index{{\tt SYSTEM} module}%

The module {\tt SYSTEM} offers some further facilities of the DBPL 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''. {\tt SYSTEM} contains also types and procedures which allow
a very basic coroutine handling. 

The module {\tt 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
{\tt SYSTEM}, no symbol file has to be supplied for this module.

Objects exported from module {\tt SYSTEM}:

\begin{description}
\item [Types]~\\
\index{{\tt SYSTEM} module~types}%
%
\begin{description}
\item []{\tt BYTE, SHORTWORD, WORD, QUADWORD, OCTAWORD}\\
\index{{\tt SYSTEM} module~types~{\tt BYTE}}%
\index{{\tt SYSTEM} module~types~{\tt SHORTWORD}}%
\index{{\tt SYSTEM} module~types~{\tt WORD}}%
\index{{\tt SYSTEM} module~types~{\tt QUADWORD}}%
\index{{\tt SYSTEM} module~types~{\tt OCTAWORD}}%
%
Objects of these types represent individually  accessible  storage units 
({\tt BYTE} = one byte, {\tt SHORTWORD} = two bytes, {\tt WORD} = four bytes,
{\tt QUADWORD} = eight bytes, {\tt OCTAWORD} = sixteen bytes).
Only assignment is allowed for  variables  of  these types.
A  parameter of type {\tt BYTE, SHORTWORD, WORD, QUADWORD} or {\tt 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 {\tt BYTE, SHORTWORD} or {\tt 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 {\tt SHORTWORD, WORD, QUADWORD}
or {\tt OCTAWORD} by a value of a type which size is not an integral multiple
of the open array element size.

\index{{\tt SYSTEM} module~types~{\tt LONGWORD}}%
For compatibility with the VAX/VMS data type names the identifier {\tt LONGWORD} is
also exported from the module {\tt SYSTEM} as a synonym for the identifier {\tt WORD}.

The Modula-2 Standard will support only {\tt BYTE} and {\tt WORD}.

\item []{\tt ADDRESS}\\
\index{{\tt SYSTEM} module~types~{\tt ADDRESS}}%
%
Objects of type {\tt ADDRESS} represent the byte address of a storage location.
\index{{\tt SYSTEM} module~types~{\tt ADDRESS}}%
The  type {\tt ADDRESS} is compatible with all pointer types and is itself
defined as {\tt POINTER TO WORD}.

All integer arithmetic operators apply to this type.
This will be changed by the Modula-2 Standard. It is recommended to use
no arithmetic with pointers.

\item []{\tt PROCESS}\\
\index{{\tt SYSTEM} module~types~{\tt PROCESS}}%
%
Objects of type {\tt PROCESS} are used for process handling.
\index{{\tt SYSTEM} module~types~{\tt PROCESS}}%
Upon termination of 
a process other than the main process an exception condition is signaled.

This type and the corresponding procedures will be separated in another system
module called {\tt COROUTINES} by the Modula-2 Standard.

\item []{\tt F\_FLOATING, D\_FLOATING, G\_FLOATING, H\_FLOATING}\\
\index{{\tt SYSTEM} module~types~{\tt F\_FLOATING}}%
\index{{\tt SYSTEM} module~types~{\tt D\_FLOATING}}%
\index{{\tt SYSTEM} module~types~{\tt G\_FLOATING}}%
\index{{\tt SYSTEM} module~types~{\tt H\_FLOATING}}%
%
The DBPL standard type {\tt REAL} is implemented using the VAX {\tt F\_FLOATING}
data type; the type {\tt LONGREAL} is implemented by {\tt D\_FLOATING}.
The other VAX floating point data types are made available
in the VAX DBPL compiler through export from module {\tt SYSTEM}. All 
operators defined in DBPL for the types {\tt REAL} and {\tt LONGREAL} are also defined 
for the types {\tt F\_FLOATING, D\_FLOATING, G\_FLOATING} and {\tt H\_FLOATING}.
Different floating point types cannot 
be mixed in expressions (i.e., there is no implicit conversion).
However the module {\tt Conversions} exports procedures for the conversion of
the different floating point data types into each other.

The standard functions {\tt TRUNC} and {\tt INT} are applicable to all floating point data
types.
\end{description}

\begin{quote}
\begin{center}
{\bf NOTE}
\end{center}
If your VAX processor is not equipped with the extended instruction
set option and you are using variables of type {\tt G\_FLOATING, H\_FLOATING} or
{\tt OCTAWORD}, the VAX extended instruction set emulator,
LIB\$EMULATE, should
be established as a condition handler. See the {\em VAX-11 Run-Time Library
Reference Manual\/} for more information.
\end{quote}


\item [Procedures]~\\
\index{{\tt SYSTEM} module~procedures}%
%
\begin{description}
\item []{\tt NEWPROCESS(p:PROC; a: ADDRESS; n: CARDINAL; VAR p1: PROCESS)}\\
\index{{\tt SYSTEM} module~procedures~{\tt NEWPROCESS}}%
%
Instantiates a new process. At least 160 bytes
are needed for the workspace of a process.
This procedure will be put to a new module {\tt COROUTINES} when the
Modula-2 Standard is published.

\item []{\tt TRANSFER(VAR p1, p2: PROCESS)}\\
\index{{\tt SYSTEM} module~procedures~{\tt TRANSFER}}%
%
Transfers control between two processes.
This procedure will be put to a new module {\tt COROUTINES} when the
Modula-2 Standard is published.

\end{description}

\item [Functions]~\\
\index{{\tt SYSTEM} module~functions}%
%
\begin{description}
\item []{\tt CAST(type, expression): type}\\
\index{{\tt SYSTEM} module~functions~{\tt CAST}}%
%
The bit representation of {\tt expression} is interpreted as a value of 
{\tt typename}.

\item []{\tt ADR(variable): ADDRESS}\\
\index{{\tt SYSTEM} module~functions~{\tt ADR}}%
%
Returns the storage address of the variable.

\item []{\tt TSIZE(type): CARDINAL}\\
See below.

\item []{\tt TSIZE(type, tag1const, tag2const, ... ): CARDINAL}\\
\index{{\tt SYSTEM} module~functions~{\tt 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 DBPL 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. Be careful when using this option, because the
compiler is not checking if you are using the correct variants!

\item []{\tt REGISTER(num: CARDINAL): CARDINAL}\\
\index{{\tt SYSTEM} module~functions~{\tt REGISTER}}%
%
Returns the content of the specified register. This function applies only
to the VAX hardware.

\end{description}
\end{description}

% ------------------

\section{Storage Management}

\subsection{The Module Storage}
\index{storage module}\index{{\tt ALLOCATE}}\index{{\tt DEALLOCATE}}%

The storage management procedures {\tt ALLOCATE} and {\tt DEALLOCATE} which serve to 
dynamically obtain and return storage space can be imported from the standard 
module {\tt Storage}:
%
\begin{verbatim}
     DEFINITION MODULE Storage;

       FROM SYSTEM IMPORT ADDRESS;

       PROCEDURE ALLOCATE (VAR p: ADDRESS; size: CARDINAL);
       PROCEDURE DEALLOCATE (VAR p: ADDRESS; size: CARDINAL);

     END Storage.
\end{verbatim}

 {\tt ALLOCATE} signals an exception whenever there is not enough free heap space.
 This will be changed by the Modula-2 Standard: {\tt ALLOCATE} will return {\tt NIL}
 if there is not enough heap space.

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

\begin{center}
{\tt PROCEDURE (VAR ADDRESS, CARDINAL)}
\end{center}


\subsection{Storage Allocation}
\index{storage allocation}%

Table \ref{storage} summarizes the storage allocation and alignment for
variables of unstructured and set type (note that ``word'', ``longword'', 
``quadword'', and ``octaword'' are DEC-terms!):

\begin{table}[hbt]
\index{{\tt SYSTEM} module~types~{\tt BYTE}}%
\index{{\tt SYSTEM} module~types~{\tt SHORTWORD}}%
\index{{\tt SYSTEM} module~types~{\tt WORD}}%
\index{{\tt SYSTEM} module~types~{\tt QUADWORD}}%
\index{{\tt SYSTEM} module~types~{\tt OCTAWORD}}%
\index{{\tt SYSTEM} module~types~{\tt ADDRESS}}%
\index{{\tt SYSTEM} module~types~{\tt F\_FLOATING}}%
\index{{\tt SYSTEM} module~types~{\tt D\_FLOATING}}%
\index{{\tt SYSTEM} module~types~{\tt G\_FLOATING}}%
\index{{\tt SYSTEM} module~types~{\tt H\_FLOATING}}%
\begin{center}
\begin{tabular}{| l | l | l |}\hline
type               & storage allocation    & alignment boundary\\
\hline\hline
\tt BOOLEAN        &                       &\\
\tt CHAR           &   8 bits (1 byte)     &   byte\\
\tt BYTE           &                       &\\
\hline
\tt SHORTWORD      &  16 bits (1 word)     &   word\\
\hline
\tt BITSET         &                       &\\
\tt INTEGER        &                       &\\
\tt CARDINAL       &                       &\\
\tt F\_FLOATING    &                       &\\
\tt REAL           &  32 bits (1 longword) &   longword\\
\tt POINTER        &                       &\\
\tt WORD           &                       &\\
\tt ADDRESS        &                       &\\
\tt RELATION       &                       &\\
\tt SELECTOR       &                       &\\
\tt CONSTRUCTOR    &                       &\\
\hline
\tt LONGREAL       &                       &\\
\tt D\_FLOATING    &                       &\\
\tt G\_FLOATING    &  64 bits (1 quadword) &   longword\\
\tt QUADWORD       &                       &\\ \hline
\tt H\_FLOATING    & 128 bits (1 octaword) &   longword\\
\tt OCTAWORD       &                       & \\
\hline
    Enumeration    &  8 bits (1 byte) if   &   byte\\
                   &  type contains 256 or &\\
                   &  less elements;       &\\
                   &  16 bits (1 word)     &   word\\
                   &  if type contains 256 &\\
                   &   or more elements    &\\
\hline
\tt SET            &   8 bits (1 byte),    &   byte\\
                   &  16 bits (1 word), or &   word\\
                   &  32 bits (1 longword),&   longword\\
                   &  according to         &\\
                   &  cardinality of base  &\\
                   &  type                 &\\
\hline
\end{tabular}
\caption{\label{storage} Storage allocation and alignment}
\end{center}
\end{table}

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.

\bdbpl
Variables of Type {\tt RELATION}, {\tt SELECTOR} and {\tt CONSTRUCTOR} 
are allocated to one longword and aligned on a longword boundary.
\edbpl

% ----------------------------------------------------------------------
\appendix

\chapter{Restrictions and Extensions}
\label{restrict}

The implementation of DBPL on the VAX differs in some respect from the
language definition \cite{SEM88}; some restrictions have to be
considered.  Most parts of the language follow Wirth's 3rd edition of
the language report on Modula-2 \cite{Wirt85b}.  Some are taken
from the 4th draft proposal of the Modula-2 Standard \cite{MODISO}.

\begin{description}
\item [Identifiers]~\\
\index{identifiers}%
Identifiers may contain the additional characters ``\$'' and ``\_'':

\begin{syntax}
\$ ident = letter \{ letter $|$ digit $|$ "\$" $|$ "\_" \}.
\end{syntax}

Note: The Modula-2 Standard will also allow the underline character
``\_'' in identifiers.  Due to the naming conventions of the linker some
additional 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.

The module name of a compilation unit should not contain the additional
characters ``\$'' and ``\_''.

\item [Qualified export]~\\
\index{Qualified~export}%
Is is possible to restrict exports of a definition module with the 
statement {\tt EXPORT QUALIFIED}. This language element is obsolete and 
may be missing in future versions of the DBPL compiler.

\item [Opaque types]~\\
\index{Opaque types}%
According to the Modula-2 standard opaque types should be implemented 
as pointers. The DBPL compiler allows all types of size {\tt WORD} as 
implementations of opque types. Suspect this feature to be changed.

\item [String constants]~\\
\index{string constants}%
The length of string constants is restricted to a maximum of 10000 characters.
String constants can be concatenated with the operator +.
This will also be in the Modula-2 Standard.

\item[Aggregates]~\\
\index{aggregates}%
Even in the Modula-2 subset it is possible to use aggregates 
as value constructors for arrays and records. This has been adopted by
the \mbox{Modula-2} standard.

Example:
\begin{verbatim}
TYPE Rec = RECORD x,y: CARDINAL; s: ARRAY [0..10] OF CHAR END;
VAR r: Rec;
...
r := Rec{0,100,'Hello'};
\end{verbatim}
In the case of nested records or structured array elements only the 
outmost type has to be mentioned, e.g.
\begin{verbatim}
TYPE Arr: ARRAY [0..1] OF Rec;
VAR a: Arr;
...
a := Arr{{0,1,'a'},{0,2,'b'}};
\end{verbatim}
\bdbpl
Aggregates can also be used to construct relation values, e.g.
\begin{verbatim}
TYPE Rel = RELATION x,y OF Rec;
VAR r: Rel;
...
r := Rel{{0,1,'a'},{0,2,'b'}}
\end{verbatim}
\edbpl

\item [Alternative character set]~\\
\index{alternative character set}%
The Modula-2 Standard states that an alternative character set has to be
supported, because the american character set is not always available. 
The following table shows the alternative constructs. 
\begin{center}
\begin{tabular}{|c|c|}
\hline
ASCII & alternative\\
\hline
[ & (!\\
] & !)\\
\{ & (:\\
\} & :)\\
$|$ & !\\
{\^~} & @\\
\hline
\end{tabular}
\end{center}
%

\item [Real number conversion]~\\
\index{real number conversion}%
The real number conversion routines are implemented according to
VAX instructions, i.e. they work with type {\tt INTEGER} instead of
type {\tt CARDINAL}. The results of {\tt FLOAT(x)} and {\tt LFLOAT(x)} will be wrong if 
{\tt x} is a cardinal number outside the range of {\tt INTEGER}.
The result of {\tt TRUNC(x)} will be wrong if {\tt x} is a negative number or a 
positive number outside the {\tt INTEGER} range.

\item [Open arrays]~\\
\index{open arrays}%
The maximal length of open arrays is 65536 bytes. Only one dimension is allowed.

\item [FOR statement]~\\
\index{FOR statement}%
The step must not be greater than 7FFFFFFFH ({\tt MAX(INTEGER)}).

\item [CASE statement]~\\
\index{CASE statement}%
The labels of a case statement must not be greater than 7FFFFFFFH.

\item [Priority specifications]~\\
\index{priority specifications}%
Priority specifications are not implemented.

\item [Standard procedures]~\\
\index{standard procedures}%
\index{{\tt NEW}}%
\index{{\tt DISPOSE}}%
In contrast to Wirth's 3rd edition of the language report, but in accordance 
with the Modula-2 standard this compiler implements the standard procedures 
{\tt NEW} and {\tt DISPOSE}. They are translated into calls to {\tt ALLOCATE} 
and {\tt DEALLOCATE}, so these procedures have to defined in the context, 
e.g. by import from the module {\tt Storage}.

\item [Elementary data types]~\\
As numerical types {\tt INTEGER}, {\tt CARDINAL}, {\tt REAL} and {\tt LONGREAL} 
have been implemented. There are no types {\tt LONGINT} or {\tt LONGCARD}, 
because {\tt INTEGER} and {\tt CARDINAL} are already 32 bit long. It is recommended 
to use subrange types of {\tt INTEGER} and {\tt CARDINAL} to support portability.

\item [Standard functions]~\\
\index{standard functions}%
\index{conversion functions}%
The following standard functions are provided by the current
implementation:
%
  \begin{description}
%
    \item[Conversion functions]~\\
     Conversions are only allowed between elementary data types.
     All possible conversions can be done with the function {\tt VAL};
     see table~\ref{val-table}:
     \begin{verbatim}
       VAL(typename,expression)
     \end{verbatim}
     Example:
     \begin{verbatim}
       intvar := VAL(INTEGER,realvar)
     \end{verbatim}

\begin{table}[htb]
\begin{center}
\begin{minipage}{20cm}
\begin{tabular}{|c|c|c|c|c|c|c|c|}
\hline
              & \multicolumn{7}{|c|}{typename (or subrange)}\\
expr.  & \tt CARDINAL & \tt INTEGER & \tt REAL & \tt LONGREAL & \tt CHAR & \tt BOOLEAN &
enum.\\
\hline
\tt CARDINAL      & $\surd$        & $\surd$       & $\surd$    & $\surd$
       & $\surd$    & $\surd$       & $\surd$\\
\tt INTEGER       & $\surd$        & $\surd$       & $\surd$    & $\surd$
       & $\surd$    & $\surd$       & $\surd$\\
\tt ZZ\footnote{ZZ is the type for literal {\tt INTEGER/CARDINAL} constants.}
            & $\surd$        & $\surd$       & $\surd$    & $\surd$
       & $\surd$    & $\surd$       & $\surd$\\
\tt REAL          & $\surd$        & $\surd$       & $\surd$    & $\surd$
       &      &         &  \\
\tt LONGREAL      & $\surd$        & $\surd$       & $\surd$    & $\surd$
       &      &         &  \\
\tt RR\footnote{RR is the type for literal {\tt REAL/LONGREAL} constants.}
            & $\surd$        & $\surd$       & $\surd$    & $\surd$
       &      &         &  \\
\tt CHAR/SS1\footnote{SS is the type for literal {\tt CHAR/ARRAY OF CHAR} constants.}
      & $\surd$        & $\surd$       &      &          & $\surd$
   &         &  \\
\tt BOOLEAN       & $\surd$        & $\surd$       &      &          &      &
$\surd$       &  \\
enum.         & $\surd$        & $\surd$       &      &          &      &
        & $\surd$\\
\hline
\end{tabular}
\end{minipage}
\end{center}
\caption{\label{val-table} Possible conversions with {\tt
VAL(typename,expr)}}
\end{table}
     Some common conversions are available in a shorter form, as explained below:
     \begin{description}
       \item[\tt CHR(whole):CHAR]~\\
        whole number 
        $\rightarrow$ character.
       \item[\tt FLOAT(numeric):REAL]~\\
        whole or floating point number 
        $\rightarrow$ real number (short floating point)
       \item[\tt LFLOAT(numeric):LONGREAL]~\\
        whole or floating point number 
        $\rightarrow$ longreal number (long floating point)
       \item[\tt INT(all):INTEGER]~\\
        whole or floating point number, character, enumeration or boolean value 
        $\rightarrow$ signed number
       \item[\tt ORD(ordinal):CARDINAL]~\\
        whole number, character, enumeration or boolean value 
        $\rightarrow$ unsigned number
       \item[\tt TRUNC(real):CARDINAL]~\\
        floating point number $\rightarrow$ unsigned number
     \end{description}

   \item[Other standard functions]~\\
%
     \begin{description}
       \item[\tt CAP(CHAR):CHAR]~\\
        letter to capital
       \item[\tt ABS(numeric):numeric]~\\
        absolute value of a whole or floating point number
       \item[\tt ODD(whole):BOOLEAN]~\\
        is the whole number odd?
       \item[\tt SIZE(var/typename):whole]~\\
Returns the number of bytes allocated 
for the variable or a variable of the specified type.
\index{standard~function~SIZE}%
If the variable is of a record type with variants, 
then the variant with maximal size is assumed.
Neither dynamic variables of type ARRAY~OF~\dots nor 
dereferenced pointers or elements of records or fields 
are allowed as arguments. Use {\tt HIGH} or {\tt TSIZE} instead.
       \item[\tt HIGH(dynvar):whole]~\\
        highest index of a dynamic variable
        (type ARRAY OF\dots); only one dimension is possible.
       \item[\tt LENGTH(string):whole]~\\
        length of a string, which is terminated by the character 0C.
       \item[\tt MAX(typename):type]~\\
        maximum value of this type.
       \item[\tt MIN(typename):type]~\\
        minimum value of this type.
     \end{description}

  \end{description}
\end{description}


% -----------------------------------------------------------------------


\chapter{Modula-2 / DBPL Compiler Installation}

\label{Installation}

The DBPL distribution tape contains the DBPL system (a compiler and a runtime
system) as well as a Modula-2 compiler, both running under VAX/VMS and
developed at the University of Hamburg. Both compilers are based on the
Modula-2 compiler M2RT11 developed at the ``Institut f\"ur Informatik,
Eidgen\"ossische Technische Hochschule Z\"urich''.

The DBPL compiler is able to utilize the symbolfiles produced by the Modula-2
compiler. Using Foreign-Definition modules (see the Modula-2 User's Guide on
tape), it is furthermore possible to develop arbitrary mixed language systems
with the DBPL compiler.

Before proceeding with the installation process, make sure that you have
enough disk space available. Approximately 9000 disc blocks are needed
to install both compilers and their libraries.

\begin{enumerate}
\item Create a directory where the compiler should reside:
\begin{verbatim}
   $ create/dir [.modula]
\end{verbatim}

\item Step into this directory:
\begin{verbatim}
   $ set default [.modula]
\end{verbatim}

\item Mount the tape:
\begin{verbatim}
   $ mount/foreign mua0:
\end{verbatim}

\item Copy the files to your directory:
\begin{verbatim}
   $ backup mua0:dbpl.bck [...]/log
\end{verbatim}

\item Dismount the tape:
\begin{verbatim}
   $ dismount mua0:
\end{verbatim}

\item Now you find two sub-directories in the directory \verb$[.modula]$:
\begin{description}
\item[[.system]] the compiler and all files needed for runtime (including
            symbol and object files of library modules);
\item[[.lib]] sources of the library definition modules;
\item[[.demo]] sources of a tiny DBPL application.
\end{description}

\item Step to the directory [.system]:
\begin{verbatim}
   $ set default [.system]
\end{verbatim}

\item Installation of path names. You have two possibilites to install the compiler:
\begin{enumerate}
\item {\em INSTALL:} The compiler resides in this directory and each user has to 
set some path names to use it:
\begin{verbatim}
   $ @install
\end{verbatim}
A command procedure \verb$STARTUP.COM$ is created which every user has to
execute before using the compiler.

\item{\em SYSTEM\_INSTALL:} The compiler and all stuff from \verb$[.system]$ is copied
to a system directory and some system path variables are set so that all
users can use the compiler without setting own path variables:
\begin{verbatim}
   $ @system_install
\end{verbatim}
All files are copied so that you can then delete all files from \verb$[.system]$.
\end{enumerate}
\end{enumerate}

\chapter{A Sample DBPL Program}

The distribution kit of the Modula-2 compiler includes a small DBPL
demonstration program. This chapter describes how to compile and execute
this program. Further information on the language DBPL and its use is
available on request from Hamburg University.

These are the general steps required for the development of database
applications:
\begin{enumerate} 

\item Create the DBPL source files.

\item Compile them with {\tt dbplc/{\sl command\_qualifier file\_name}}.
Look at the file {\tt MOD\$SYSTEM:dbpl.cld} for allowed command
qualifiers. {\sl DATABASE MODULE' s} have to be compiled with the
qualifier {\tt /create} to create an (uninitialized) database. Details
of the command qualifiers can be found in the VAX DBPL User's Guide. The
first application program accessing that database will execute the
user-definable database initialization code for that database.

\item Link your objectfiles with {\tt link {\sl file$_{1}$.obj, $\ldots$,
file$_{n}$.obj}}. File$_{1}$ should be the main program module. It is
not necessary to name the object libraries of the Modula-2 and DBPL
system explicitely.

\item Start your application with {\tt run {\sl file$_{1}$.exe}}. 

\end{enumerate}.

For Modula-2 programs you can use the Modula-2 compiler in the same way
by compiling this files with {\tt mod/{\sl command\_qualifier
file\_name}}. Look at the file {\tt MOD\$SYSTEM:modula.cld} for allowed
command qualifiers. They are also explained in the VAX DBPL User's
Guide.

\section{An Example Application} 

\label{ex} Go to the directory \verb$[.demo]$
\begin{verbatim} 
$ set def [.demo]
\end{verbatim} 

The example application consists of the following files 

\begin{enumerate} 

\item {\tt gtypes.def} and {\tt gtypes.dbp} 
\item {\tt gdb.def}, a database module and {\tt gdb.dbp} 
\item {\tt gdoc.def} and {\tt gdoc.dbp} 
\item {\tt gdisplay.def} and {\tt gdisplay.dbp} 
\item {\tt gdemo.dbp} and {\tt gdemo2.dbp} the main program modules
importing the other modules.

\end{enumerate} 

Compile these modules with
\begin{verbatim}
$ dbplc/log/debug gtypes.def 
$ dbplc/log/debug/create gdb.def
$ dbplc/log/debug gdoc.def
$ dbplc/log/debug gdisplay.def 
$ dbplc/log/debug gtypes.mod
$ dbplc/log/debug gdb.mod
$ dbplc/log/debug gdisplay.mod
$ dbplc/log/debug gdoc.mod
$ dbplc/log/debug gdemo.mod
$ dbplc/log/debug gdemo2.mod
\end{verbatim} 

Please note that the order of these operations is significant since the
compiler has to read the symbol files of imported modules during
compilation. By using the qualifier {\tt /create} the persistent
database variables will be created. You will therefore find some new
files with extensions {\tt .dat, .i00, .dic} in the current default
directory. These files are needed during subsequent executions of the
DBPL application. Now link your applications with

\begin{verbatim}
$ link/debug gdemo.obj,gtypes.obj,gdisplay.obj,gdb.obj,gdoc.obj
$ link/debug gdemo2.obj,gtypes.obj,gdisplay.obj,gdb.obj,gdoc.obj
\end{verbatim} 

Note that the main module {\tt gdemo} ({\tt gdemo2}, respectively) is at
the first position. If you use this link command, the VAX-Debugger will
be automatically activated when you start your application. If you do
not need this feature, omit the {\tt /debug} qualifier in the
link-command. Now you can start the application with

\begin{verbatim} 
$ run gdemo 
$ run gdemo2
\end{verbatim} 

If you have used the ``debug version'' you should type
{\tt go} after the debugger prompt or start your application simply with

\begin{verbatim} 
$ run/nodebug gdemo 
\end{verbatim} 

This avoids the activation of the debugger, too.  

You can use the module-management facilites (MMS) of the VAX operating
system to keep track of your module dependencies and simplify the
generation of an executable image (see MMS user's guide for further
informations). There is a description file {\tt descrip.mms} for the
module dependencies of the demo application and the default rules for
the generation of DBPL code and DBPL symbol files. Using MMS it is
sufficient to type

\begin{verbatim} 
$ mms
\end{verbatim} 


%\section{System Restrictions}
%
%\label{Restrictions}
%Restrictions of the current release of the DBPL-compiler:
%
%\begin{itemize}
%\item Access expressions must not contain function calls (detected during body
%analysis).
%
%\item Aggregates must not contain relations or predicates (detected during code
%generation).
%
%\item The {\tt USING} list within transactions is not implemented (detected
%during code generation, HALT statement during compilation).
%
%\item The assembler listing (selected with the command qualifier /LIST/MACHINE) 
%contains minor syntactic errors, if DBPL specific language constructs are used.
%
%\item The internal codetable during code generation may overflow if there are
%many constructor or selector declarations within a single module (detected
%during code generation). This problem can be avoided by introducing additional
%local modules and distributing the selectors and constructors among them.
%
%\end{itemize}
%                     
%Restrictions of the current release of the DBPL run time system:
%\begin{itemize}
%\item Updates on selected relation variables are not implemented, i.e. the
%following program would abort at run time:
%
%\begin{verbatim}
%SELECTOR sp ON ... WITH ...
%...
%
%BEGIN
%   Rel[sp] := ...
%END;
%\end{verbatim}
%
%\item All files representing database variables are created (during
%compilation) and looked up (during execution) by default in the current
%directory. Name conflicts between multiple database files are not
%avoided and can lead to strange error situations, e.g. :
%
%\begin{verbatim}
%DATABASE MODULE A;
%VAR
%  x: RELATION OF INTEGER;
%END A;
%
%DATABASE DEFINITION MODULE B;
%VAR
%  x: RELATION OF CHAR;
%END B;
%\end{verbatim}
%
%This problem can be avoided by assigning different directories to
%individual databases. This assignment is defined by parameters in the
%file \verb$DBPL.PAR$ or \verb!MOD$SYSTEM:DBPL.DEFPAR!, e.g.:
%
%\begin{verbatim}
%I_A  $DISK1:[DATABASE_A]
%D_B  $DISK2:[DATABASE_B]
%\end{verbatim}
%The dictionary and database files for the (implementation) module A are
%placed in the directory \verb!$DISK1:[DATABASE_A]! whereas the
%dictionary and database files for the (definition) module B are placed
%in the directory \verb!$DISK2:[DATABASE_B]!.
%\end{itemize}
%

\newcommand{\etalchar}[1]{$^{#1}$}
\begin{thebibliography}{ERMS91}

\bibitem[ERMS91]{ERMS91}
J.~Eder, A.~Rudloff, F.~Matthes, and J.W. Schmidt.
\newblock Data Construction with Recursive Set Expressions in DBPL.
\newblock In {\em Proceedings of the Kiev East/West Workshop on Next Generation
  Database Technology}, volume 504 of {\em Lecture Notes in Computer Science},
  April 1991.

\bibitem[JLS85]{JLS85}
M.~Jarke, V.~Linnemann, and J.W. Schmidt.
\newblock Data Constructors: On the Integration of Rules and Relations.
\newblock In {\em 11th Intern. Conference on Very Large Data Bases, Stockholm},
  August 1985.

\bibitem[KMP82]{KMP82}
J.~Koch, J.~Mall, and P.~Putfarken.
\newblock Modula-2 for the VAX: Description of a System Portation.
\newblock In H.~Langmaack, B.~Schlender, and J.W. Schmidt, editors, {\em
  Tagungsband Implementierung Pascal-artiger Programmiersprachen}. Teubner
  Verlag, 1982.
\newblock (in German).

\bibitem[Mod91]{MODISO}
ISO/IEC JTC1/SC22/WG13.
\newblock {\em Interim Version of the 4th Working Draft Modula-2 Standard},
  1991.

\bibitem[MRS84]{MRS84}
M.~Mall, M.~Reimer, and J.W. Schmidt.
\newblock Data Selection, Sharing and Access Control in a Relational Scenario.
\newblock In M.L. Brodie, J.L. Myopoulos, and J.W. Schmidt, editors, {\em On
  Conceptual Modelling}. Springer-Verlag, 1984.

\bibitem[MRS89]{DAIDA4}
F.~Matthes, A.~Rudloff, and J.W. Schmidt.
\newblock Data- and Rule-Based Database Programming in {DBPL}.
\newblock Esprit Project 892 WP/IMP 3.b, Fachbereich Informatik, Johann
  Wolfgang Goethe-Universit\"at, Frankfurt, West Germany, March 1989.

\bibitem[MS89]{MaSc89}
F.~Matthes and J.W. Schmidt.
\newblock The Type System of {DBPL}.
\newblock In {\em Proceedings of the Second International Workshop on Database
  Programming Languages, Salishan, Oregon}, pages 255--260, June 1989.

\bibitem[SBK{\etalchar{+}}88]{DAIDA2}
J.W. Schmidt, M.~Bittner, H.~Klein, H.~Eckhardt, and F.~Matthes.
\newblock {DBPL} System: The Prototype and its Architecture.
\newblock Esprit Project 892 WP/IMP 3.2, Fachbereich Informatik, Johann
  Wolfgang Goethe-Universit\"at, Frankfurt, West Germany, November 1988.

\bibitem[SEM88a]{SEM88}
J.W. Schmidt, H.~Eckhardt, and F.~Matthes.
\newblock {DBPL Report}.
\newblock DBPL-Memo 112-88, Fachbereich Informatik, Johann Wolfgang
  Goethe-Universit\"at, Frankfurt, West Germany, 1988.

\bibitem[SEM88b]{DAIDA1}
J.W. Schmidt, H.~Eckhardt, and F.~Matthes.
\newblock Extensions to {DBPL}: Towards A Type-Complete Database Programming
  Language.
\newblock Esprit Project 892 WP/IMP 3.1, Fachbereich Informatik, Johann
  Wolfgang Goethe-Universit\"at, Frankfurt, West Germany, April 1988.

\bibitem[SGLJ89]{SGLJ89}
J.W Schmidt, L.~Ge, V.~Linnemann, and M.~Jarke.
\newblock Integrated Fact and Rule Management Based on Database Technology.
\newblock In J.W. Schmidt and C.~Thanos, editors, {\em Foundations of Knowledge
  Base Management}, Topics in Information Systems. Springer-Verlag, 1989.

\bibitem[SL85]{ScLi85}
J.W. Schmidt and V.~Linnemann.
\newblock Higher Level Relational Objects.
\newblock In {\em Proc. 4th British National Conference on Databases (BNCOD
  4)}. Cambridge University Press, July 1985.

\bibitem[SM90]{ScMa90a}
J.W. Schmidt and F.~Matthes.
\newblock Language Technology for Post-Relational Data Systems.
\newblock In A.~Blaser, editor, {\em Database Systems of the 90s}, volume 466
  of {\em Lecture Notes in Computer Science}, pages 81--114, November 1990.

\bibitem[SM91a]{ScMa90b}
J.W. Schmidt and F.~Matthes.
\newblock Naming Schemes and Name Space Management in the DBPL Persistent
  Storage System.
\newblock In {\em Proceedings of the Fourth International Workshop on
  Persistent Object Systems, Martha's Vineyard, Massachusetts}. Morgan Kaufmann
  Publishers, January 1991.

\bibitem[SM91b]{ScMa91d}
J.W. Schmidt and F.~Matthes.
\newblock The Rationale behind DBPL.
\newblock In {\em 3rd Symposium on Mathematical Fundamentals of Database and
  Knowledge Base Systems}, volume 495 of {\em Lecture Notes in Computer
  Science}. Springer-Verlag, May 1991.

\bibitem[Wir85]{Wirt85b}
N.~Wirth.
\newblock Report on the Programming Language Modula-2.
\newblock Springer-Verlag, 3rd edition, 1985.


\end{thebibliography}

% -----------------------------------------------------------------------
\end{document}

