path: root/support/db2tex/db2tex.tex

\documentstyle[prelim,german,11pt]{article}
\def\db2tex{db2\TeX}
%\input{/u1/tex/art_kopf.tex}         % lokale Din-A4-Anpassung
\addtolength{\textheight}{-1cm}      % damit "Entwurf" gedruckt werden kann
\sloppy

\title{Erstellung von Serienbriefen o.\"a.~mit Hilfe des Programms
\db2tex-1.3\footnote{Datei: {\tt db2tex.deu}, Satzprogramm: \TeX/\LaTeX,
Computer: Targon/35}}

\author{Dr.~Henning Astheimer}

\begin{document}

\maketitle
\input{/u1/tex/ag_edv.tex}
e-Mail: astheimer@imdm.uke.uni-hamburg.dbp.de
\tableofcontents
\listoffigures
\newpage

\section{Einleitung}
Das Programm \db2tex\ kann z.B.~zur Erstellung von Serienbriefen verwendet
werden. Es f\"ugt tabellierte Angaben -- Text und/oder Zahlen -- zeilenweise
an den gew\"unschten Stellen in ein Formular ein. Je Tabellenzeile entsteht
dabei ein Exemplar des Serienbriefes. Als Formulare verwenden wir
ein \LaTeX-Dokument, z.B.~einen Brief im hauseigenen "`UKE-Stil"', der den
f\"ur alle Empf\"anger gleichlautenden Text sowie die Platzhalter enth\"alt. Die
Tabelle kann per Hand erstellt werden oder eine Datenbank-Ergebnistabelle
sein, welche als Betriebssystemdatei gespeichert wurde.
Folgende Schritte werden durchlaufen:
\begin{enumerate}
\item Erstellen des \LaTeX-Formulars mit den Namen der einzuf\"ugenden
      Tabellenfelder (Beisp.~{\tt formular.tex}).
\item \"Andern des \LaTeX-Formulars zum Gebrauch mit \db2tex\
      (Beisp.~{\tt brief.tex}).
\item Erstellen der Tabelle (Beisp.~{\tt adressen.tab}) \dots
  \begin{itemize}
  \item als Datenbankextrakt oder
  \item im Editor
  \end{itemize}
\item \"Ubergabe des Formulars und der Tabelle an \db2tex
\item Anschauen oder Ausdrucken der Serientexte
\end{enumerate}
Diese Gebrauchsanleitung ist \"uberwiegend allgemeing\"ultig gehalten; einige
wenige lokale Randbemerkungen sind in Fu\ss{}noten untergebracht.


\section{Erstellen des \LaTeX-Formulars}
Anhand eines einfachen Beispiels (Rundschreiben an drei gute Bekannte) soll
im folgenden die Verwendung des Programms \db2tex\ demonstriert werden.
Das Verfahren ist nat\"urlich mit beliebigen \LaTeX-Dokumentstilen
verwendbar, wobei die jeweils dort g\"ultigen Regeln zu beachten sind.  Zur
Planung eines neuen Schreibens -- als Beispiel siehe Abb.~\ref{formular} --
empfieht es sich, die zu verwendenden
Tabellenfelder in Gro\ss{}buchstaben einzuf\"ugen.  Das ist sehr anschaulich und
auch zur Dokumentation der eigenen Arbeit n\"utzlich.  Der erstellte
Formbrief wird in gewohnter Weise\footnote{(bei uns mit dem \TeX-Men\"u
{\tt te\/})} solange
ver\"andert (editiert -- ausgedruckt -- angesehen), bis er gef\"allt.

%\_\hrulefill\ \\
\begin{figure}[h]
\caption{Beispielformular {\tt formular.tex}} \label{formular}
  \begin{verbatim}
  \documentstyle[german,11pt]{article}
  \begin{document}
  An           \\
  VORNAME NAME \\
  STRASSE      \\
  PLZ  ORT     \bigskip

  Wir laden Sie hiermit herzlich zu unserer Weihnachtsfeier ein! \\

  Mit freundlichen Gr\"u\ss{}en, ...
  \end{document}
  \end{verbatim}
\end{figure}
%\_\hrulefill\ \\

Danach schreibt man in die erste Zeile, d.h.~noch vor {\tt documentstyle ...}
die Namen der im Formular verwendeten Platzhalter -- in der Reihenfolge, wie
sie in der Tabelle erscheinen! -- beginnend mit {\tt \%\$}, z.B.
\begin{verbatim}
%$ NAME VORNAME STRASSE PLZ ORT
\end{verbatim}
Die Platzhalter selbst m\"ussen nun im restlichen Formular ebenfalls durch
vorangestellte {\tt \%\$} als
solche dem Programm \db2tex\ kenntlich gemacht werden (siehe Abb.~\ref{brief}).
Die Gro\ss{}- und Kleinschreibung der Spaltennamen sollte einheitlich sein;
"`{\tt Name}"' und "`{\tt NAME}"' sind f\"ur \db2tex\ zwei unterschiedliche W\"orter.

\begin{figure}[h]
\caption{Beispielbrief {\tt brief.tex}} \label{brief}
%\_\hrulefill\ \\
  \begin{verbatim}
  %$ NAME VORNAME STRASSE PLZ ORT
  \documentstyle[german,11pt]{article}
  \begin{document}
  An               \\
  %$VORNAME %$NAME \\
  %$STRASSE        \\
  %$PLZ  %$ORT     \bigskip

  Wir laden Sie hiermit herzlich zu unserer Weihnachtsfeier ein! \\

  Mit freundlichen Gr\"u\ss{}en, ...
  \end{document}
  \end{verbatim}
%\_\hrulefill\ \\
\end{figure}



\section{Erstellen der Tabelle}
Als \"Uberschrift stehen in der ersten Zeile die Spaltennamen; in der zweiten
Zeile folgen Gedankenstriche {\tt ---}, an deren L\"ange \db2tex\ die Feldbreiten
der Spalten erkennt; darunter folgen die Daten, je ein Datensatz pro Zeile.
Man kann die Tabelle entweder manuell mithilfe eines beliebigen Editors
erstellen oder als "`Datenbankextrakt"'; der beschriebene Aufbau mu\ss{} in beiden
F\"allen gegeben sein.

Falls Daten aus der Datenbank in den Formbrief eingesetzt werden sollen,
mu\ss{} man diese als Ergebnistabelle einer Datenbankanfrage in eine
Betriebssystemdatei
schreiben. Dies geht z.B.~mit Hilfe der Abfragesprache SQL folgenderma\ss{}en:
\begin{verbatim}
    SELECT name, vorname, strasse_hausnr, plz, ort
    FROM datenbanktabelle
    WHERE plz BETWEEN 2300 AND 8000
    REPORT; PUT 'adressen.tab'
\end{verbatim}
Dabei werden alle ausgew\"ahlten Namen, Vornamen, usw.~aus einer (richtig zu
benennenden) Datenbanktabelle in die Datei {\tt adressen.tab} geschrieben.

\begin{figure}[h]
 \caption{Beispieltabelle {\tt adressen.tab} f\"ur den Mahnbrief} \label{tabelle}
 %\fbox{
%\_\hrulefill\ \\
   \begin{verbatim}
     NAME       VORNAME     STRASSE-HAUSNR    PLZ    ORT
     --------   ---------   ---------------   ----   ------------
     Mueller    Jan         Neustr. 19        2300   Kiel 1
     Meier      Hannes      Altstr. 29        6000   Frankfurt 60
     Schulze    Alois       Mittelstr. 22     8000   Muenchen 44
   \end{verbatim}
%\_\hrulefill\ \\
% }
\end{figure}

In der {\tt SELECT}-Anweisung sollte man die genaue Reihenfolge der
Spaltennamen beachten, da sie mit der Reihenfolge der Spaltenvariablen in
der ersten Zeile des Formbriefes \"ubereinstimmen mu\ss{}.  Die Benennung mu\ss{}
nicht genau \"ubereinstimmen!  Der Abstand zwischen den
Spalten\footnote{Bitte im Setup des Programms {\tt QUERY} den "`Separator"'
ber\"ucksichtigen und in der {\tt ini.}-Datei definieren!} sollte mindestens
drei Leerzeichen betragen oder gem\"a\ss{} der Definition in der {\tt .ini}-Datei
(siehe Abb.~\ref{ini}) definiert sein.  Fehlende Werte sollten nach
Wunsch -- aber \TeX-kompatibel -- gekennzeichnet werden; die verwendete
Kennzeichnung wird nat\"urlich nicht nur in die Ergebnistabelle \"ubernommen,
sondern sp\"ater auch im Serienbrief genau so ausgedruckt!

Das Nichteinhalten dieser Regeln hat nach dem Aufruf des Programms \db2tex\
meist eine Flut von Warnungen und Fehlermeldungen zur Folge.  Dabei gilt,
da\ss{} grobe Formatverst\"o\ss{}e mit Fehlermeldungen und Programmabbruch
beantwortet werden, w\"ahrend leichtere Vergehen (wie z.B. bei Verwendung
unbekannter Spaltennamen im Formblatt) nur Warnungen ohne Programmabbruch
hervorrufen.



\section{\"Ubergabe des Formulars und der Tabelle an \db2tex }

\subsection{Programmaufruf ohne Parameter}
Wird \db2tex\ ohne Parameter aufgerufen, so werden die
Standard-Dateinamen (default file names) verwendet, d.h.~\db2tex\ erwartet, da\ss{}
es im aktuellen Verzeichnis die Tabelle in einer Datei namens {\tt db2tex.rep}
findet und das
\LaTeX-Formular in einer Datei namens {\tt db2tex.tex}.
\begin{verbatim}
Betriebssystem> db2tex
\end{verbatim}

\subsection{Aufruf mit Tabellen- und Formularname}
In den meisten F\"allen, z.B.~um in einem Verzeichnis mehrere Formulare und
Tabellen benennen zu k\"onnen, ist es sinnvoller, das Programm mit den Namen
der Tabelle und des Formbriefes aufzurufen:
\begin{verbatim}
Betriebssystem> db2tex adressen.tab brief.tex
\end{verbatim}

\subsection{Sonstiges}
Die allgemeine Form des Programmaufruf sieht folgenderma\ss{}en aus:
\begin{verbatim}
  Betriebssystem> db2tex [-chq] [-n rep-lines] [-o out-file] [TeX-file] [rep-file]
\end{verbatim}
Eine Kurzbeschreibung der Aufrufm\"oglichkeiten des Programms \db2tex\
erh\"alt man durch
\begin{verbatim}
Betriebssystem> db2tex -h
\end{verbatim}
Danach bekommt man auf dem Bildschirm folgende Auskunft:
%\fbox{
  \begin{verbatim}
  Options:
	   -c : compile only
	   -n : set max. report lines
	   -o : set output file name
	   -q : quiet running
	   -h : this help text

  Default file name: db2tex.tex
  \end{verbatim}
%}
{\bf Erl\"auterungen:}

\begin{description}
\item[-c] Bei Verwendung dieser Option ruft \db2tex\ das \TeX-System nicht auf.
  Aus diesem Grund bleiben alle Zwischendateien, die w\"ahrend des
  Programmlaufs erzeugt wurden, erhalten.
  Diese Option ist f\"ur Kontrollzwecke gedacht, um die Zwischenergebnisse
  noch einmal genau unter die Lupe nehmen zu k\"onnen, n\"amlich den bearbeiteten
  Formbrief mit der Endung {\tt .def}, in unserem Beispiel {\tt brief.def}
  und die Tabellendaten mit der Endeung {\tt .inp}, in unserem Beispiel
  {\tt brief.inp}.
\item[-n AnzahlZeilen]
   Mit dieser Option l\"a\ss{}t sich der Wert f\"ur die maximale Anzahl der
   aus der Report-Datei einzulesenden Zeilen festlegen. Dies ist ganz
   hilfreich, um sich kleine Probeausgaben zu erstellen; in der Testphase
   gen\"ugen sicher 2-3 Serienexemplare aus einer u.U.~recht langen Adre\ss{}liste.
\item[-o Ausgabedatei] Hiermit kann man den Namen der Ausgabedatei
  festlegen. Die interaktive Abfrage nach Bildschirm- oder Druckerausgabe
  entf\"allt.
\item[-q] Mit dieser Option l\"auft das Programm
   ohne jede Bildschirmausgabe und eignet sich z.B.~als Hintergrundproze\ss{}.
   Beispiel: {\tt db2tex -q brief.tex beispiel.tex \&; /usr/games/rogue}.
   Ergebnis: w\"ahrend \db2tex\ arbeitet, bleibt Zeit f\"ur ein kleines Spielchen.
   Warnungen und Fehlermeldungen werden werden allerdings nicht unterdr\"uckt.
   Auch hier entf\"allt die interaktive Abfrage nach Bildschirm- oder
   Druckerausgabe; das Ergebnis wird automatisch auf den Drucker geleitet.
\item[-h] Ausgabe des Hilfstextes (siehe oben).
\end{description}

W\"ahrend des Programmlaufs gibt \db2tex\ eine Liste der verarbeiteten Dateien
aus und erwartet (nach fehlerfreier Ausf\"uhrung) eine Eingabe des Benutzers
(e, b oder d) auf die Frage, ob abgebrochen oder das Ergebnis auf den
Bildschirm oder auf den Drucker geleitet werden soll.


\section{Die Datei {\tt db2tex.ini}}
Einige Grundeinstellungen sind im Programm \db2tex\ fest vorgegeben. Um etwas
flexibler zu sein, werden \"Anderungsm\"oglichkeiten auf zwei Ebenen angeboten:
\begin{enumerate}
\item Systemweit von den Vorgaben abweichende Einstellungen k\"onnen in einer
  Datei {\tt db2tex.ini} definiert werden, die im selben Verzeichnis wie das
  Programm selbst stehen mu\ss{}.
\item Benutzerbezogen kann eine zweite Datei {\tt db2tex.ini} im aktuellen
  Verzeichnis stehen, von wo aus das Programm aufgerufen wird und wo sich
  auch die Tabellen- und Formulardateien befinden.
\end{enumerate}
Ein Beispiel f\"ur die Datei {\tt db2tex.ini} befindet sich in der
Abb.~\ref{ini}; die Syntax ist angelehnt an die Konventionen von
UNIX-Shellskripten.


\section{Besonderheiten}

\subsection{Fehlende Werte in der Tabelle}
Fehlende Werte werden in einer Datenbank f\"ur gew\"ohnlich speziell behandelt
({\em NULL-Wert\/}).  Bei der Ausgabe (Bildschirm, Datei oder Drucker) mu\ss{}
f\"ur sie ein Symbol vereinbart werden, z.B.~`\dag'.  Zum Zweck der
Datensichtung ist dieses Verfahren gut brauchbar, da fehlende Werte
deutlich gekennzeichnet sind.  Nur in den seltensten F\"allen ist das Zeichen
`\dag' \ allerdings in einem Serientext sinnvoll.  Im einfachsten Fall
kann man -- falls die Tabelle noch nicht existiert -- in der Datenbank ein
Leerzeichen als Nullwert definieren, oder -- falls eine Tabelle schon
existiert -- ersetzt man die unerw\"unschten Nullwerte im Editor durch
Leerzeichen.  Schwieriger wird es, falls eine ganze Textpassage des
Formbriefes sinnvollerweise entfallen m\"usste, wenn einzusetzende Daten in
dieser Passage des Serientextes Nullwerte aufweisen.  Vielleicht ist es in
einzelnen F\"allen noch ertr\"aglich, dann fehlende Zahlen im Text als {\em `
\dots Nicht gemessen! \dots '\/} auszugeben; wenn jedoch Text fehlt, wird
es schon schwieriger, eine f\"ur alle Spalten passende Formulierung zu
finden.  Zudem ist es meist nicht m\"oglich, mehrere fehlende Werte f\"ur
verschiedene Spalten zu vereinbaren.

\subsection{Individuelle Anreden}
Falls man einen Rundbrief verschicken und einen Teil der Adressaten mit
{\em Du\/}, den anderen Teil mit {\em Sie\/} anreden m\"ochte, mu\ss{} man diese
Aufgabe in zwei Durchg\"angen erledigen.  In der Datenbank ben\"otigt man einen
Schalter, der anzeigt, wie man jede Person anredet.  Im ersten Durchgang
schreibt man dann einen Formbrief mit der {\em Du-\/}Anrede und extrahiert
nur die passenden {\em Du-\/}Adressen.  Im zweiten Durchgang ver\"andert man
die Anrede im Formbrief und f\"uttert \db2tex\ mit den {\em Sie-\/}Adressen.

Meines Erachtens gibt es f\"ur dieses Problem keine automatisierbare L\"osung,
da verschiedene Anreden auch grammatikalische \"Anderungen im Text des
Formularbriefes mit sich bringen.

\section{Hinweise f\"ur die Installation von \db2tex}
\subsection{Programmentwicklung}
Das Programm wurde von Dr.~Henning Astheimer konzipiert, von Bernd Paradies
programmiert und wird z.Zt.~von Klaus Rath betreut. Es ist in "`C"'
geschrieben und wurde unter dem Betriebssystem AT\&T-UNIX V mit einem
Kernighan/Ritchie-Compiler getestet. Es ist seit Ende 1990 bei uns in
Gebrauch.

Wir stellen das Programm im Sinne der Copyright-Bestimmungen der {\em Free
Software Foundation -- GNU\/} als "`public domain - Programm"' zur
Verf\"ugung und w\"urden uns freuen, wenn andere Personen dazu beitragen
wollten, durch geeignete Erg\"anzungen eine Lauff\"ahigkeit auf anderen
Computern zu erm\"oglichen.  Der Programmname, die Dokumentation und die
Quelltexte d\"urfen nur f\"ur den eigenen Gebrauch lokal ver\"andert werden; die
Herkunft mu\ss{} dennoch weiterhin ersichtlich sein.

\"Anderungen d\"urfen nicht direkt weitergegeben werden, sondern sollen an den
Autor r\"uckgemeldet werden.  Bitte protokollieren Sie die vorgenommenen
\"Anderungen, z.B.~Precompiler-defines oder Optionen im Makefile und schicken
Sie eine Kopie an die o.g.~Adresse, am besten per e-mail
(astheimer@imdm.uke.uni-hamburg.dbp.de).  Falls das Programm sich bew\"ahrt
und gen\"ugend Bedarf gegeben scheint, kann es in der Zukunft \"uber einen
Fileserver, z.B.~von DANTE e.V., anderen Interessenten zur Verf\"ugung
stehen.

\subsection{Ben\"otigte Dateien}

\begin{figure}[h]
 \caption{Beispiel f\"ur die Initialisierungsdatei {\tt db2tex.ini}} \label{ini}
 %\fbox{
%\_\hrulefill\ \\
   \begin{verbatim}
# -----------------------
# INI-File  fuer : db2tex
# -----------------------
# - Kommentare wie in Shell-Skripten oder auch ganz frei, solange nicht
#   ab der ersten Spalte eines der z.Zt. 15 Schluesselwoerter mit einem
#   folgenden Gleichheitszeichen steht. Kommentare auf derselben Zeile
#   wie Options-Setzungen muessen durch mindestens ein BLANK getrennt
#   werden.
#
# - Setzung der Optionen immer am Zeilenanfang in der ersten Spalte:
#   VAR=wert <<<---------------- ohne BLANKS, wie in Shellskripten
#
# - Die Schluesselwoerter PRINTER und TEXPOOL duerfen auch mit Umgebungs-
#   variablen belegt werden, z.B.:
#   PRINTER=$TEXDRUCKER <<------ siehe auch weiter unten

# DATEI-NAMEN
TEXT=dbwork.txt                     #
REPORT=dbwork.rep                   #
DEF=dbwork.def                      # Zwischendatei
INPUT=dbwork.inp                    # Zwischendatei
DVI=dbwork.dvi                      #
#OUTPUT=dbwork.out                   # optional

# OPTIONEN
QUIET=noe             # Einzig wirksame Belegung: yes
COMPILE_ONLY=nein     # Einzig wirksame Belegung: yes
SEP="   "
#OUTDEV=/dev/tty

# TEX                 !! TEXPOOL muss vor VIRTEX und DVIxxx definiert werden !!
#                     !! da diese relativ zu TEXPOOL angegeben werden       !!
TEXPOOL=/usr/local/lib/tex
VIRTEX=virtex "&"lplain
DVITPS=dvitps/dvitps -d forward -E 0 -H-16mm -V-30mm -q
#DVITPS=dvijep -b -eTEXFONTS=/u1/tex/fonts -q -x5mm -y9mm
DVITTY=dvitty -Fpg
#PRINTER=${TEXDRUCKER:-mdlraw}              # z.B. hpk5raw
UMLT2TEX=umlt2tex
   \end{verbatim}
%\_\hrulefill\ \\
% }
\end{figure}


\begin{figure}[h]
 \caption{Die ben\"otigten Dateien} \label{datei}
 \begin{center}
 \begin{tabular}{|l|l|} \hline
  Dateiname     &  Bedeutung  \\\hline\hline
  Makefile      & Kompilierdatei   \\
  adressen.tab  & Beispieladressen    \\
  brief.tex     & Beispielbrief    \\
  convent.h     & Precompilerdatei    \\
  db.bat        & Aufrufdatei         \\
  db2tex.c      & Hauptprogramm   \\
  db2tex.tex/deu& Dokumentation   \\
  db2tex.h      & Headerdatei \\
  db2tex.ini    & Initialisierungsdatei  \\
  db\_tex.c     & Funktionen f\"ur \TeX-Ausgabe \\
  formular.tex  & Beispielformular          \\ \hline
 \end{tabular}
 \end{center}
\end{figure}

\end{document}