
\chapter{Schnittstellenmoduln}

\label{interface}
\thispagestyle{empty}

Dieses Kapitel beschreibt einige Besonderheiten in
Zusammenhang mit den {\bf Schnittstellenmoduln}. 
Mit Schnittstellenmoduln sind diejenigen Moduln
bezeichnet, die eine Betriebssystem-Schnittstelle
in der \mtwo-Syntax definieren. Folglich liegen diese
Schnittstellen als Definitionsmoduln vor.

\section{Aufbau der Schnittstellen}

Schnittstellen von {\bf Libraries} sind dabei in zwei
Definitionsmoduln folgender Namensgebung zu finden:

\begin{enumerate}
\item
  Der Libraryname erweitert um den Buchstaben "`{\tt D}"'
  enth"alt alle Datendefinitionen --- also Typen und
  Konstanten --- der Library. Dieses
  Definitionsmodul enth"alt {\em keine\/} Implementation.
\item
  Der Libraryname erweitert um den Buchstaben "`{\tt L}"'
  enth"alt alle {\tt CODE}-Prozeduren der Library-Aufrufe. 
  Dabei sind alle aktuell vorhandenen Prozeduren der Library
  enthalten. 
\end{enumerate}

In beiden Moduln sind alle Objekte bis zur aktuellen
Version 37 deklariert, ab Version 36, der Entwickler-Version,
jedoch besonders gekennzeichnet.

Damit l"asst sich die bisherige umst"andliche Verwendung
von Schnittstellenmoduln verschiedener Library-Versionen,
also beispielsweise {\tt Intuition}, {\tt Intuition34},
{\tt Intuition36} und so fort, vermeiden. 

Allerdings wird die bisherige Anforderung an
die vorhandene Mindest-Version einer Library fallengelassen.
Der Programmierer ist nun selbst verantwortlich, die
Version und den damit vorhandenen Prozeduren-Umfang
zu pr"ufen!

Daf"ur existiert in jedem Schnittstellenmodul mit den
Library-Routinen eine Variable
mit dem Namen {\cmsltt library\/\tt Version}, 
mit dem vollem Namen also {\tt IntuitionL.intuitionVersion}.
Diese enth"alt die Versionsnummer der ge"offneten Library.
Nach Abfrage dieser Versionsnummer hat der Programmierer
folgende Reaktionsm"oglichkeiten:
\begin{itemize}
\item
  Er kann das Programm abbrechen, wenn die Library nicht
  seinen Mindestanforderungen gen"ugt, er also Prozeduren
  braucht, die nur in h"oheren Library-Version vorhanden sind.
\item
  Er kann das Programm so schreiben, dass im Falle einer
  niedrigeren Version nur eine eingeschr"ankte Funktionalit"at
  angeboten wird, indem etwa Menupunkte ausgeblendet werden.

  Dies ist das "ahnliche Verhalten wie bei optionalen
  Libraries, die ebenfalls durch Mehraufwand des Programmierers
  abgefangen werden k"on"-nen, und das fertige Programm unabh"angig
  der vorhanden Libraries ablauf"|f"ahig erh"alt.
\end{itemize}

Dieses Abpr"ufen widerspricht etwas der \mtwo-Philosophie,
erleichtert aber die flexible Programmierung ungemein. Ein
Beispiel daf"ur findet sich im Modul {\tt WbClone} auf der
Demo-Diskette.

F"ur Libraries, die erst ab Version 36 existieren,
gibt es ein zus"atzliches, drittes Modul {\tt Opt\cmsltt library\tt L},
beispielsweise {\tt OptWorkbenchL}, das eine optionale
Library {\em ohne\/} Implementation darstellt (siehe 
\ref{optLibWithout}). Beim Import solcher Moduln ist das
Programm auch ohne diese Library lauf"|f"ahig, allerdings
muss vor Benutzung der Prozeduren die {\cmsltt library\/\tt Base}
auf Ungleichheit mit {\tt NIL} pr"ufen.

Jede Library ist also durch die soeben beschriebenen Moduln
zu verwenden. Eine feinere Unterteilung --- in der Programmiersprache
C sind Library-Schnittstellen durch mehrere Header-Dateien
beschrieben --- existiert nicht.

Ausserdem existieren implementationlose Moduln,
die nur Typen- und Konstantendeklarationen enthalten.
Dazu geh"oren beispielsweise alle De\-vice-Schnitt\-stel\-len.

Im Gegensatz zu fr"uheren Versionen verzichten wir von nun
an, alle Definitionen der Schnittstellenmoduln abzudrucken.
Hauptargument daf"ur ist der m"ogliche Einsatz von
{\tt M2Ohm}, das dem Programmierer jederzeit die
n"otige Information sehr schnell verschafft.

Durch die einfache Handhabung von {\tt M2Ohm} (siehe \ref{m2ohm}) finden
wir es nicht mehr angebracht,
alle Definitionen abzudrucken. Diese haben in der
Zwischenzeit einen riesigen Umfang 
erreicht. Ausserdem wird
meistens nur gerade eine Definition bzw.\ ein Eintrag 
nachgeschaut. Und gerade dann ist ein Werkzeug wie
{\tt M2Ohm} schneller und einfacher als ein endloses
Bl"attern in Handb"uchern.

\section{Unterschiede zu C-Schnittstellen}

F"ur die Verwendung der Betriebssystem-Schnittstellen ist oft
die Kenntnis der Programmiersprache C notwendig.
Auch scheinen die Deklarationen vom \mtwoamiga\ nicht
immer einleuchtend. Darum sind hier einige Unterschiede
dargestellt.

\subsection{Aufz\protect"ahlungen und Mengen}

In C finden sich oft Deklarationen wie die folgenden:

\begin{verbatim}
  SERB_parityOn  = 0;
  SERB_parityOdd = 1;
  SERB_sevenWire = 2;
  SERB_queuedBrk = 3;
\end{verbatim}

\begin{alltt}
  SERF_parityOn  = 0x0001;  {\rm( oder auch \tt 1<<SERB_parityOn\rm)}
  SERF_parityOdd = 0x0002;  {\rm( oder auch \tt 1<<SERB_parityOdd\rm)}
  SERF_sevenWire = 0x0004;  {\rm( oder auch \tt 1<<SERB_sevenWire\rm)}
  SERF_queuedBrk = 0x0008;  {\rm( oder auch \tt 1<<SERB_queuedBrk\rm)}
\end{alltt}

Im Programm steht dann die Anweisung:
\begin{verbatim}
  flags = SERF_parityOn | SERF_queuedBrk;
\end{verbatim}

Dies heisst in \mtwo\ viel eleganter:
\begin{verbatim}
  SerFlags = (parityOn, parityOdd, sevenWire, queedBrk);
\end{verbatim}

\begin{verbatim}
  SerFlagSet = SET OF SerFlags;
\end{verbatim}

Und schliesslich in der Anwendung:
\begin{verbatim}
  flags := SerFlagSet(parityOn, queuedBrk);
\end{verbatim}

Ein Aufz"ahlungstyp in \mtwo\ ist gleichbedeutend mit einer
Deklaration von Konstanten, die von 0 an durchnumeriert
sind. Deshalb kann die C-Deklaration in einen Aufz"ahlungstyp
umgewandelt werden.

Zu beachten ist, dass nun mit der Syntaxerweiterung bei
den Auf"-z"ah\-lungs\-ty\-pen, beschrieben in \ref{newEnum},
auch weitaus kompliziertere Konstantendeklarationen
aus der Sprache C "ubernommen werden k"onnen.

Eine Menge wird so dargestellt, dass jedes Element ein
Bit belegt. Das erste Element belegt Bitposition 0,
das zweite Element die Bitposition 1, und so fort. Deshalb kann
die zweite C-Deklaration in einen Mengentyp umgewandelt werden.

Daraus ergibt sich die Anweisung als logische Folge der
Definition.
Nebst der "uberschaubareren Schreibweise erm"oglicht diese
"Ubersetzung dem Compiler eine strengere Typenkontrolle.
Die Elemente der Aufz"ahlungs- und Mengentypen sind an
ihren Typ gebunden. So sind etwa Elemente von {\tt IntuitionD.ScreenFlags}
und {\tt IntuitionD.WindowFlags} nur an Variablen ihres Typs zuweisbar.
Eine Verletzung dieser Regel wird schon vom Compiler beanstandet
und nicht erst zur Laufzeit durch "`Guru"'-Meldungen.

\subsection{Variablen-Parameter}

Ein weiterer Vorteil vom \mtwo\ gegen"uber der Sprache
C sind die Va\-ria\-blen-Pa\-ra\-me\-ter. C kennt ausschliesslich
Werteparameter, d.h.\ die Prozedur kann den ihr "ubergebenen
Wert nur lokal ver"andern. Soll der Inhalt eines Parameters
in der Prozedur bleibend ver"andert werden, dann muss
man einige Kunstgriffe anwenden. Was in \mtwo\ so einfach
aussieht:

\begin{verbatim}
MODULE m;

PROCEDURE P(i: INTEGER; VAR j:INTEGER);
BEGIN j:=2*i END P;

VAR
 k: INTEGER;
BEGIN
 P(2,k)
END m.
\end{verbatim}

wird in C folgendermassen geschrieben:

\begin{alltt}
void p(int i, int *j)
/* j wird als Zeiger auf int deklariert */
{ (*j)=2*i; }

main()
{
  int k;

  p(2, &k);
  /* F"ur Parameter j muss Adresse "ubergeben werden */
}
\end{alltt}


Das bedeutet, dass man bei der R"uck"ubersetzung aufpassen
muss. Eine "`w"ortliche"' "Ubersetzung wird funktionieren,
aber seine "`C-Vergangenheit"' nicht verbergen k"onnen:

\begin{verbatim}
MODULE m;

FROM SYSTEM IMPORT ADR;

TYPE
  IntegerPtr = POINTER TO INTEGER;

PROCEDURE P(i: INTEGER; j:IntegerPtr);
BEGIN j^:=2*i END P;

VAR
 k: INTEGER;
BEGIN
 P(2,ADR(k))
END m.
\end{verbatim}

Beispiele f"ur eine elegante "Ubersetzung in \mtwo\ findet
man im Modul {\tt GraphicsL}. Die Prozedur {\tt InitBitmap}
erwartet als ersten Parameter die Adresse einer	{\tt BitMap}.
In \mtwo\ ist dies ein {\tt VAR}-Parameter des Typs {\tt BitMap}.
Die "Ubergabe mit Hilfe von {\tt VAR}-Parametern wurde
"uberall dort verwendet, wo es nicht n"otig ist, einen Zeiger
zu "ubergeben.

\subsection{Varianten-{\tt RECORD}s}

Unions in C und Varianten-{\tt RECORD}s in \mtwo\ dienen
dem selben Zweck, sind aber nicht identisch.
In beiden F"allen geht es darum, verschiedene Felder
eines {\tt RECORD}s auf die gleiche Speicherstelle abzubilden.
Wesentlicher Unterschied der beiden Methoden: in C
umfasst ein {\tt union} die verschiedenen Darstellungen
eines einzelnes Feldes, w"ahrend in \mtwo\ mehrer Felder
angegeben werden k"onnen.

\begin{verbatim}
struct example {
  LONG first;
  union {
  WORD a;
  BYTE b;
  char c;
  } second;
};
\end{verbatim}

Dies sieht in \mtwo\ folgendermassen aus:

\begin{verbatim}
example = RECORD
  first: LONGINT;
  CASE :INTEGER OF
  | 0: a: CARDINAL;
  | 1: b: BYTE;
  | 2: c: CHAR;
  END
END;
\end{verbatim}

Daraus ergibt sich auch der Unterschied, dass man in C einen Namen
f"ur die {\tt union} und einzelne Namen f"ur die verschiedenen
Varianten angibt. In \mtwo\ ist dies nicht der Fall, so sind
die beiden folgenden Zugriffe identisch:
\begin{itemize}
\item
  {\tt example.second.b} in C
\item
  {\tt example.b} in \mtwo
\end{itemize}

Allerdings k"onnen in \mtwo\ die Varianten nur auf {\tt RECORD}s
angewendet werden, w"ahrend in C auch einfache Variablen
als {\tt union} deklariert werden k"onnen.


