\documentstyle[12pt,a4]{article}
\newcommand{\eb}{{\sc EasyBase }}
\newcommand{\Eb}{{\sc EasyBase}}
\title{EasyBase\\A simple database package}
\author{Mark H. Overmars\thanks{Department of Computer Science,
        	Utrecht University, P.O.Box 80.089, 3508 TB Utrecht,
		the Netherlands. Email: {\tt markov@cs.ruu.nl}.}}
\date{Version 1.0\\Sept. 25, 1992}
\begin{document}
\maketitle

\section{Introduction}

\eb is a very simple to use database package for Silicon Graphics workstation.
Is is partially related to a similar program (called Sbase) I wrote for the
Atari computer but it is in no way compatible. The main goal in creating \eb
was simplicity of use. Much emphasis was put on the user interface. This
document describes the possibilities of \Eb. But probably you don't need to
read much of this. Most things are quite straightforward.

As said, \eb is meant to be simple. It is not general in any way. It can only
deal with a limited number of fields per record (20), it only has single line
fields, it does not have relational capabilities, etc. But is does make it
extremely easy to maintain a list of addresses, references, users,
submissions, etc. It has powerful selection mechanism that, e.g., make it
trivial to select all article written by Tarjan that are published after 1988
but do not contain the word ``tree'' in the title. It is possible to make
subselections, extend selections, etc. It also has very fast sorting
possibilities. Finally it can print the database or selections in a format
that can easily be used with \LaTeX.

\subsection*{Notice}
{\sc
This software is public domain. It may freely be copied and used,
assuming proper credit to the author is given, but it should not be resold.

This software is provided ``as is'' without warranty of any kind,
either expressed or implied. The entire risk as to the quality and
performance of the software is with you. Should the software prove
defective, you assume the cost of all necessary servicing, repair or
correction.
}

\section{Defining a new database}

To create a new database simply type a non-existing file name when ask
for a file to load.  (Give it the extension \verb+.dat+.) You will be
informed that the database does not exist and are asked whether you
want to create a new one. You will now be presented with a small form
in which at the left you find the list of fields in the database (empty
at the beginning). Press the button labeled {\bf Add Field} to add a
field.  You will be asked for the field name which you should type
in.  The field will now appear in the list. In this way you can
indicate all fields to add. (Note that you cannot create more than 20
fields in the current implementation.) If you are ready press the
button {\bf Ready}.  The database is now created. (For the meaning of
the other buttons, see below in section \ref{se:change}.) You are shown
the first (empty) record in the database which you can now change. (A
database in \eb can never be empty. It will always contain at least one
record. So even if you delete this one empty record a new one will
appear.)

\section{Viewing records}

There are two viewing modes in \eb called Record View and List View. In
List View mode you will see 20 records all the time, each on a single
line. In Record View mode you will see one record at a time with its
fields on different lines. You can move through the set of records using
the slider at the right of the records. The up and down arrow move you
one record forwards or backwards; the slider lets you move to any place
you want. You can also use the uparrow and downarrow key to move among
the records. When you hold the left or right $<$Shift$>$ key will
pressing the up or down button you will move to the first or last
record.

You can switch between the two modes by pressing the button labeled
{\bf View} at the bottom or by pressing $<$Ctrl-V$>$ on the keyboard.
In List View mode a number of buttons disappear. This is because in this
mode you cannot change records. This can only be done in Record View
mode.

\section{Editing records}

To edit records, make sure you are in Record View mode. In this mode
you can always edit the visible record.  The colored field is the field
you are editing; the blue line indicates the cursor. You can simply type
in the value of the field. Use $<$Return$>$ to move to the next field.
All usual editing keys work like $<$Backspace$>$, $<$Delete$>$, the
left and right arrow keys, etc. $<$Esc$>$ clears the field. You can
also make selection with the mouse which will be replaces with the next
keystroke (or deleted with $<$Backspace$>$). If you ruined the contents
of the record you can restore it using the button {\bf Restore} or by
typing $<$Ctrl-R$>$. To Erase the whole record press the button {\bf
Erase} or use $<$Ctrl-E$>$.

To add a new record after the current one, press the button {\bf New}
or use $<$Ctrl-N$>$. Similar, to insert a record before the current one
use the button {\bf Insert} or $<$Ctrl-I$>$. In both cases you are
shown the empty new record. When you hold a $<$Shift$>$ key while
pressing the button, the record is added as the last or first record to
the database.  Realize that \eb works a bit different from most
databases. In most databases you first fill in a record which you can
then add to the database. In \eb you first add an empty record to the
database which you can then fill in.

You can delete the current record by pressing the button {\bf Delete}.
Remember that a database can never be empty. Hence, when you delete the
last record a new, empty one will be inserted. When you are on a
selection level (see below) and you delete the last record on that level
\eb will automatically go to the next selection level.

\eb keeps track of all deleted records. (Nothing is really thrown away.)
Hence, you can always get a record back by pressing the button {\bf
Undel.}. This can be done repeatedly until all deleted records are
back. (Of course this only works during one session with a file. If you
save and reload the file the deleted records are gone.)

\section{Selecting}

One of the most powerful features of \eb is the selection mechanism. A
main design goal of \eb was to have a simple to use, powerful selection
method. Selections are made in the bottom part of the form.

The selection mechanism is based on the following notion. At any moment
you are working on a selection level. Level 0 is the whole database.
Any next level is a subset of the previous level. In the window you
will find at the top the selection level and the number of records in
this selection level. Whenever you make a selection you determine a
subset of the records which form the next selection level.  With the
button {\bf Level Up} you can go back one level in the selection (e.g.,
to make a new subselection). With the button {\bf Show All} you can go
back to level 0, containing all records.

The selection can be indicated as follows: At the left you indicate the
field involved (cycle through the choices with the left or middle mouse
button or pick your choice from a menu with the right mouse button).
(One special choice is SOME FIELD. In this case a record is selected
when at least one filed satisfies the query.) Next you can say whether
the field should or should not satisfy the query. The next box indicate
the type of query. Here you indicate whether the field should contain a
string, be equal to it, be smaller or be smaller or equal to the
string. This string can be typed in the next box. (You can also do
numeric compares. In this case both the field and the string are
transformed to reals.) Next press the button {\bf Restrict} (or press
$<$Return$>$) to select the records satisfying the query you created.

You can also extend the current selection by pressing the button
labeled {\bf Extend}. In this case all records in the previous
selection level that satisfy the query are added to the current
selection.

For example, assume you have a database of books and you want to find
out those books that were written in 1985 by Paterson or Johnson. This
can be accomplished as follows. First make a selection of all books
with the year equal to 1985. Next, further restrict the
selection by choosing the books whose author list contains ``Paterson''.
Finally, extend this selection with the books whose author list contains
``Johnson''. (Of course, books written by Paterson and Johnson will
appear only once.)

\section{Sorting}

It is often important to order (sort) a set of records, e.g. addresses
by city, books by author, etc. To sort simply press the button labeled
{\bf Order} (or type $<$Ctrl-O$>$).  A small form will appear in which
you can indicate the field on which to sort, whether to sort in
increasing or decreasing order and whether sorting should be case
sensitive or not (or numeric). Next press the button {\bf OK} (or press
$<$Return$>$) and the database will be sorted. Always the whole
database will be sorted, not just the selection (although of course
only the selection is shown).

\eb uses a simple stable merge sort to sort records on a particular
field. The nice thing of a stable sort is that records with the same
value in the field stay in the same order. This allows for sorting on
multiple fields in an easy way. For example, assume you want to sort a
set of addresses on country and per country on city. This can easily be
accomplished in \eb as follows: first sort on city. Next sort on
country. Because addresses with the same country stay in the original
order they will stay ordered by city.

\section{Loading and Saving}

To load a different database press the button labeled {\bf Load}. (If
the current database was changed and not saved you will be warned and
asked whether you want to save it.) You can choose the file name using
a file selector. Here you will see the contents of the current
directory. You can switch directory by pressing the mouse on the
directory name. You can select a file by double clicking on it or by
typing in the name.  Only files ending in \verb+.dat+ are shown because
this is the default extension. You can change this by changing the
selection pattern (simply press the mouse on it). Also you can change
the current directory by pressing the mouse on it.

To save the database press the button labeled {\bf Save} or use
$<$Ctrl-S$>$. The file is saved under its current name. If a file with
that name already exists a copy is made with the extension \verb+.bak+
added. In this way you always have a back-up version to rely on. Save
always saves the whole database. When you are in a selection \eb first
goes back to selection level 0 before saving. When you want to save the
database under a different name, hold the $<$Shift$>$ key while
pressing the button. This time a file selector is shown in which you
can indicate the file name. Again a back-up will be made of the an old
version of the file.

You can also save the current selection as a database using the button
{\bf Save Sel.}. The procedure is the same.

Sometimes you might want to merge the contents of a second database with
the current one. Take care that in the second database there are the
same fields in the same order. Press the button {\bf Merge} to achieve
this. Using a file selector you can indicate the file you want to merge
with the current one.

Finally, when you exit the program, using the button {\bf Exit}, and
the current database has been changed \eb will ask you whether you want
to save it.

\section{Printing}

You will often want to print a database. \eb does not offer you a nice
report generation facility. It simply lets you print the records in
three different ways and assumes you will pass them through some further
filter to actually print them. Actually, the records are written
to a file. They are not directly send to the printer. To print the
current selection press the button labeled {\bf Print}. Next you are
asked what format to use. You can choose from LaTeX, List, and Record (See
below for their meaning.) Next you are asked to indicate the file in
which to place the output.

In the {\bf LaTeX} format each record is written in the form 

\begin{verbatim}
\record
{field1}
{field2}
  ...
\end{verbatim}

You can now make a \LaTeX\ document in which you define to command
\verb+\record+ and include the file with the selection. This works
perfectly for e.g. making standard letters, etc. There is though one
problem here. \LaTeX\ can only handle commands with at most 9 arguments.
If you have more fields in the database you have to use a trick to
circumvent this. The following example will demonstrate this. Assume you
have a database with 12 fields and assume you simply want to print them
with a space in between. Now you can use the following piece of \LaTeX
code:

\begin{verbatim}
\documentstyle{article}
\newcommand{\therest}[3]{#1 #2 #3.\\}
\newcommand{\record}[9]{#1 #2 #3 #4 #5 #6 #7 #8 #9 \therest}
\begin{document}
\input{select}
\end{document}
\end{verbatim}

Here the command \verb+\record+ takes the first nine arguments, prints
them and next calls \verb+\therest+ to take the remaining three arguments
and print them. The only problem with this approach is that the first 9
and the remaining fields cannot be interleaved in the output.

The second printing possibility is {\bf List} format. Here each record
is printed on a single line with all fields separated by ``\verb+|+''.
This will normally serve as input for another program (e.g. awk or nawk)
to convert it into something more useful.

Finally, in the {\bf Record} format each field is printed on a separate
line with the field name in front of it. This is just meant to get a
quick look of the contents of the database.

\section{Changing the database layout}
\label{se:change}

It sometimes happens that you want to change the database layout. For
example, you want to add a field, delete a field or change the order of
the fields. Before you start doing this make sure you make a copy of
your database (simply save it under a different name) because the changes
you are about to make are permanent. Next press the
button {\bf Change}. You are presented with a form with, at the left, a
list of all fields in the database. One field is selected (yellow). You
can change the selected field with the mouse. You have the following
option: {\bf Add Field} will add a field after the selected one. You have to
type in the name of the field. Similar {\bf Insert Field} will insert a
new field before the current one. A database can, in the current
implementation, have a maximum of 20 fields. The button {\bf Change
Field} can be used to change the name of the selected field.
To change the order of the fields you can use the buttons
{\bf Move Field Up} and {\bf Move Field Down}. They move the current
selected field up or down through the list of fields. Finally with the
button {\bf Delete Field} you can delete the field from the database.

If you are happy with the new layout, press the button labeled {\bf
Ready} and your database will be adapted to the new layout with new
empty fields added where required. If you have destroyed the layout
(e.g., deleted the wrong fields) press {\bf Cancel} and the database will
remain unchanged. If you were so stupid to press {\bf Ready} while you
made a mistake and also did not make a copy first, there is still no
problem. Simply press {\bf Exit} in the main form and DON'T save the
changes.

\appendix

\section{File format}

The file format is rather simple. It can easily be edited by a text
editor or generated or used by a different program. Each record is on a
separate line. Fields in the record are separate by a \verb+:+. When a
\verb+:+ appears in a field it is written as \verb+!:+. A \verb+!+ in a
field is written as \verb+!!+. A special first record is added to the
database that contains the names of the fields as fields. Also the
number of fields is derived from this special record. Other records can
has less fields (empty ones will be added) or more (extra fields will be
discarded). So, for example, assume we have a trivial dictionary
database from Dutch to English with two fields named Dutch and English
and three records, the file will look as follows:

\begin{verbatim}
Dutch:English
Huis:House
Stad:City
Land:Country
\end{verbatim}

\end{document}

