% dbpl_system2.tex

\chapter{DBPL Installation Guide}

\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.

The current implementation of the DBPL system is still incomplete, please
consult section \ref{Restrictions}) for details.

\section{First Installation of DBPL}

%The ``Arbeitsbereich DBIS, Universit\"at Hamburg'', subsequently called DBIS,
%grants the right to use the compiler for employees, customers, or students of
%your institution. You do not have the right to sell or give the compiler to
%third parties. DBIS makes no warranty, expressed or implied, regarding the
%correctnes of the system. DBIS has no obligation to ``maintain'' the system.

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

\begin{enumerate}
\item Mount the tapedrive by 

          {\tt \$ mount/foreign {\sl tape\_drive}} 

where {\sl tape\_drive} is the name of the used tape drive, e.g. {\tt mua0:}. 

\item Define the directory on which the top-directory of the DBPL system should
      reside, as the default directory.

\item  Copy the system from tape or TK-50 by

{\tt \$ backup/log {\sl tape\_drive} [\ldots]*.*.*}

      \item Go to {\tt [.dbpl]} and load the file {\sl
      install\_dbpl.com} with an editor. The first line of this file is

{\small 
\verb!$ define $dbpll  "''f$trnlnm("$your_disk")'[path_to.dbpl.]"/trans=(conc,term)!
}

On the first line of this file, change {\tt \$your\_disk} to the (logical) name
of your actual disc and {\tt path\_to} to the actual path of the installation
directory. 

\item Execute \verb$@install_dbpl.com$.

\item Dismount the tape:

          {\tt \$ dismount {\sl tape\_drive}} 


\end{enumerate} 


\section{User Access to DBPL}

\begin{enumerate} 

\item Every user of DBPL has to execute \verb$install_dbpl.com$ in the
directory \verb$[.dbpl]$(e.g. in his \verb$login.com$ file).

\item Make sure, that the file protection of the DBPL system files and system
directories allows read-access (respectively execute-access for {\tt *.exe}
files) for the designated users.

\item Every DBPL user needs an open file quota of at least 100. This is
necessary for the DBPL runtime system to handle persistent and temporary
relations. The standard settings for the open file quota will lead to problems
{\em even for small DBPL applications}!

\end{enumerate}

\section{Using DBPL}

A step-by step example is given in the next section.

\begin{enumerate} 

\item Create the DBPL source files.

\item 

Compile them with {\tt xdb/{\sl command\_qualifier file\_name}}. Look at
the file {\tt \$DBPL:xdb.cld} for allowed  command qualifiers. {\sl DATABASE
MODULE' s} have to be compiled with the qualifier {\tt /create} to create an
(uninitialized) database. The other command qualifiers are described in the
VAX-11 Modula-2 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 \$dbpl:mod.cld} for allowed command qualifiers. They are
explained in the VAX-11 Modula-2 User's Guide.

\section{An Example Application} 

\label{ex} Go to the directory \$DOC:

\begin{verbatim} 
$ set def $doc 
\end{verbatim} 

The example application consists of the following files 

\begin{enumerate} 

\item {\tt gtypes.def} and {\tt gtypes.dbp} 

\item {\tt gdisplay.def} and {\tt gdisplay.dbp} both importing from {\tt
gtypes.def}.

\item {\tt gdemo.dbp}, the main program module and the only database module,
importing from {\tt gtypes.def} and {\tt gdisplay.def}.

\end{enumerate} 

Compile these modules with
\begin{verbatim}
$ xdb/log/debug gtypes.def 
$ xdb/log/debug gdisplay.def 
$ xdb/log/debug gtypes.dbp 
$ xdb/log/debug gdisplay.dbp 
$ xdb/log/debug/create gdemo.dbp
\end{verbatim} 

Please note, that the order of these operations is significant, since the
compiler has to read the symbol files of all imported modules. 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 application with 

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

Note, that the main module {\tt gdemo} 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 
\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 gdemo.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/description=gdemo.mms
\end{verbatim} 

\section{IO-Facilities} 

\label{io} Many DBPL applications need heavy user-interactions. Therefore you
will find some predefined modules with simple facilities for menu-driven
selection and window-oriented in-/output in the installation directory \$IO.
These facilities are offered by the following modules: 

\begin{itemize} 
\item Form 
\item Selector
\item Window 
\end{itemize} 

For their functionality look at the corresponding definition module's in the
directory \mbox{\$IOSOURCES}. 

\section{Directory Structure}

The top level directory is {\bf \$DBPL}. It contains the DBPL-compiler  ({\tt
dvcpublic.exe}), the Modula-2 compiler ({\tt modula.exe}), the Modula-2 object
library ({\tt modula.olb}), the DBPL run time system object library ({\tt
dbplrts.olb}) and files necessary for the installation of DBPL. It contains
three subdirectories:

\begin{description} 

\item[\$DOC] 
\begin{sloppypar}
contains the DVI-files and the latex-files of the \LaTeX-Versions of the 
DBPL-Report ({\tt dbplreport.latex/dvi})and this installation guide  ({\tt
dbpl\_installation.latex/dvi}). Furthermore, it contains the example application
(see section \ref{ex}).
\end{sloppypar}

\item[\$SYM] 
\begin{sloppypar}
contains the symbolfile of the interface to the DBPL run time
system ({\tt dbplrts.sym}) (only for internal use by the DBPL compiler) and
some Modula-2 symbol files. Furthermore, it contains the subdirectory {\bf
\$MODSOURCES} with the definition modules for the standard modules.
\end{sloppypar}

\item[\$IO] contains the symbolfiles and the object library for the
IO-Facilities (see section \ref{io}). and a subdirectory {\bf \$IOSOURCES} with
the definition modules of the symbolfiles and the implementation modules of the
objectfiles in the IO object library. 

\end{description}


\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.

\item The Modula-2 standard functions ABS, CAP, CHR, etc. must not be used
within constant expressions. Their evaluation has to take place at runtime.

\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) in the default directory. Name
conflicts between multiple databases are therefore not avoided and can lead to
strange error messages. This problem can be avoided by giving unique variable
names within all database modules. A counter example would be

\begin{verbatim}
DATABASE MODULE A;
VAR
  x: RELATION OF INTEGER;
END A;

DATABASE MODULE B;
VAR
  x: RELATION OF CHAR;
END B;
\end{verbatim}

\end{itemize}

