% ------------------------------------------------------------------ %
%                                                                    %
% Datei:        zugriff2.tex                                         %
% Autor:        Oliver Nietsch                                       %
%                                                                    %
% Universitaet Hamburg                                               %
% Fachbereich Informatik                                             %
% Arbeitsbereich DBIS                                                %
%                                                                    %
% Thema: Studienarbeit: "Gateway zwischen dem StP-Repository         %
%                        und Tycoon"                                 %
%                                                                    %
% Inhalt: LaTeX-Dokument: Studienarbeit,                             %
%                         Kapitel 4: Zugriffsmoeglichkeiten auf      %
%                                    StP Repositoryobjekte, Teil2    %
%                                                                    %
% Version vom  19. 3.1996                                            %
% ------------------------------------------------------------------ %
Desweiteren bietet das {\sf StP API} noch andere Funktionen f"ur den direkten Zugriff auf Repositoryobjekte.

\subsection{StP Application Program Interface}
\label{SubSec:API}

Das {\sf StP Application Program Interface} bildet eine Schnittstelle zwischen C-Anwendungsprogrammen und dem {\sf StP Repository}. Es stellt dem Anwender eine Reihe von in C-Programme integrierbare Funktionen und Datentypen zur Verf"ugung, um auf Repositoryobjekte zugreifen bzw. das Repository selbst verwalten zu k"onnen. Zu den f"ur diese Arbeit relevanten Aufgaben der {\sf API} Funktionen geh"oren \cite{StPoms94}:

\begin{itemize}
  \item Erstellen, Auffinden und L"oschen von Repositoryobjekten
  \item Verwalten des Hauptspeichers und des Repositorys
  \item Interpretieren von {\sf OMS} Anfragen
  \item Manipulieren von Attributwerten der Repositoryobjekte
  \item Durchf"uhren von {\sf StP} Repositorytransaktionen
\end{itemize}

In der Tabelle~\ref{Tab:TypsProcs} sind exemplarisch einige wichtige {\sf StP API} Funktionen zum Erf"ullen der oben genannten Aufgaben wiedergegeben. Weitere Funktionen sind in \cite{StPoms94} aufgef"uhrt.\\

{\bf {\sf StP API Funktionen und Typen}}

Tabelle~\ref{Tab:TypsProcs} stellt die im Abschnitt~\ref{SubSec:Api3} verwendeten Funktionen dar. Die konkrete Typisierung der {\sf API} Funktionen ist f"ur alle Datentypen des \engl{Persistent Data Models} in \cite{StPoms94} wiedergegeben. Eine Interpretation der im Abschnitt~\ref{SubSec:Api3} verwendeten Datentypen erfolgt an dieser Stelle nicht.

\begin{table}
\begin{center}
\begin{tabular}{|l|l|}
\hline
{\bf Funktion} & {\bf Beschreibung}\\
\hline\hline
{\tt oms\_$<$pdm\_typ$>$\_create} & Erzeugt ein neues Repositoryobjekt\\
  & im Hauptspeicher und gibt einen darauf \\
  & weisenden Zeiger zur"uck.\\
\hline
{\tt oms\_$<$pdm\_typ$>$\_find} & Sucht im aktuellen Repository nach dem mit\\
  & den Funktionsparametern spezifizierten\\
  & Objekt. Dieses wird in eine neue\\
  & {\tt oms\_$<$pdm\_typ$>$\_tp} Struktur kopiert. Ein darauf\\
  & weisender Zeiger wird zur"uckgegeben.\\
  & Ansonsten wird der {\tt NULL}-Zeiger zur"uckgegeben.\\
\hline
{\tt oms\_$<$pdm\_typ$>$\_find\_by\_id} & Sucht im aktuellen Repository nach dem mit\\
  & den Funktionsparametern spezifizierten\\
  & Objekt. Dieses wird in eine neue\\
  & {\tt oms\_$<$pdm\_typ$>$\_tp} Struktur kopiert. Ein darauf\\
  & weisender Zeiger wird zur"uckgegeben.\\
  & Ansonsten wird der {\tt NULL}-Zeiger zur"uckgegeben.\\
\hline
{\tt oms\_$<$pdm\_typ$>$\_find\_by\_query} & Sucht im aktuellen Repository nach dem\\     
  & mit den "`{\sf OMS} Anfragebedingungen"'\\
  & "ubereinstimmenden Objekt. Dieses wird in eine\\
  & {\tt oms\_$<$pdm\_typ$>$\_tp} Struktur kopiert. Ein darauf\\
  & weisender Zeiger wird zur"uckgegeben.\\
  & Ansonsten wird der {\tt NULL}-Zeiger zur"uckgegeben.\\
\hline
{\tt oms\_$<$pdm\_typ$>$\_free} & Nimmt die Adresse des "ubergebenen Zeigers\\
  & auf die {\tt oms\_$<$pdm\_typ$>$\_tp} Struktur und gibt den\\
  & damit assoziierten Hauptspeicherbereich frei.\\
\hline
{\tt oms\_$<$pdm\_typ$>$\_print} & Nimmt die Adresse des "ubergebenen Zeigers\\ 
  & auf die {\tt oms\_$<$pdm\_typ$>$\_tp} Struktur und gibt\\
  & alle Attributnamen und deren Werte in\\
  & einer zu spezifizierenden Datei aus.\\
\hline
{\tt oms\_$<$pdm\_typ$>$\_} & Weist einem Repositoryobjekt-\\
{\tt $<$attribut$>$\_asgn} & Attribut einen neuen Wert zu.\\
\hline
{\tt oms\_$<$pdm\_typ$>$\_update} & Aktualisiert oder f"ugt im Hauptspeicher\\
  & angelegte Strukturen im {\sf StP Repository} als\\
  & Objekte ein. Tritt ein Fehler auf oder sind \\
  & referentielle Integrit"atsbedingungen nicht erf"ullt, \\
  & gibt die Funktion {\tt OMS\_FAIL} zur"uck,\\
  & ansonsten {\tt OMS\_SUCCEED}.\\
\hline
{\tt oms\_sys\_repos\_open} & "Offnet das spezifizierte Repository\\
  & f"ur den Zugriff.\\
\hline
{\tt oms\_repos\_close} & Schlie"st das aktuelle Repository nach\\
  & dem Abschlu"s der Zugriffsoperationen.\\
\hline
\end{tabular}
\end{center}
\caption{Ausgew"ahlte {\sf StP Application Program Interface} Funktionen}
\label{Tab:TypsProcs}
\end{table}

Au"ser den erw"ahnten und im Abschnitt~\ref{SubSec:Api3} benutzten Funktionen stellt das {\sf StP API} auch noch weitere Funktionen im Rahmen von \engl{Collection-}, \engl{Big Collection-}, Transaktionstypen und ID-Listen bereit \cite{StPoms94}.

Bei diesen Typen handelt es sich um "`Hilfstypen"', welche nicht im Repository abgelegt werden k"onnen. Der \engl{Collection} Typ wird ben"otigt, um eine Mehrzahl von Objekten in eine einzelne Einheit zusammenzufassen. Sollte eine {\sf OMS} Anfrage ein Resultat liefern, bei dem die Anzahl gefundener Repositoryobjekte zu gro"s ist, um sie in den Hauptspeicher zu laden, wird der \engl{Big Collection} Typ verwendet. Der Transaktionstyp stellt dem Anwendungsentwickler einen Mechanismus zur Verf"ugung, mit dessen Hilfe eine feste Anzahl von Repositoryoperationen kontrolliert werden kann. ID-Listen sind kurzfristige "`Aufbewahrungsorte"' f"ur das Resultat einer {\sf OMS} Anfrage, um es als Anfrageargument weiter benutzen zu k"onnen.

Desweiteren ist eine individuelle Fehlerbehandlung realisiert. Standardm"a"sig gibt das {\sf OMS} beim Auftreten eines Fehlers eine Fehlernummer und eine Fehlermeldung aus. Innerhalb des {\sf API} existiert eine Funktion {\tt oms\_set\_oms\_err\_handler}, mit deren Hilfe Standardfehlermeldungen abgefangen werden k"onnen.\\

{\bf {\sf Systemvoraussetzungen}}

Um auf die einzelnen Funktionen des {\sf StP Application Program Interface} auch tats"achlich zugreifen zu k"onnen, ist es erforderlich, gewisse Systemvoraussetzungen zu beachten:

\begin{enumerate}
  \item Innerhalb des C-Anwendungsprogramms m"ussen die einzubeziehenden \engl{Header}-Dateien eingebunden werden:\\
\\
{\tt \#include "{}oms\_stdinc.h"{},}\\
{\tt \#include $<$stdio.h$>$}

  \item Aufgrund einiger Fehlermeldungen m"ussen in der Datei {\tt libtools.h} im Verzeichnis {\tt .../StP/templates/ct/include/} die Zeilen 13, 206, 499, 500, 501, 504, 510, 514, 515, 516 auskommentiert werden. Eine nachteilige Wirkung auf die Funktionalit"at des im Abschnitt~\ref{SubSec:Api3} dargestellten C-Programms kann nicht festgestellt werden. Welche Konsequenzen sich aber f"ur andere Anwendungsprogramme, welche {\sf API} Funktionen aufrufen, ergeben, kann nicht vorhergesagt werden.
  \item Der Repositoryzugriff erfordert das Vorhandensein einiger Systemumgebungsvariablen. Im einzelnen handelt es sich um die Variablen (mit "`{\tt ...}"' beginnende Angaben bezeichnen relative Pfadangaben):

  \begin{verbatim}
LD_LIBRARY_PATH=.../StP/libsparc:/usr/openwin/lib:/opt/sv/lib
PATH=.../StP/binsparc:.../StP/sybase_10.0.1/sparc/bin:
     /usr/ccs/bin:/opt/SUNWspro/SW3.0.1/bin
SHLVL=3
IDE_PRODUCT=omt
ToolInfo=.../StP/ToolInfo/IDE
SYBASE=.../StP/sybase_10.0.1/sparc
DSQUERY=STP_SERVER
SYS_TEN=true
STP_SERVER_PASSWD=welcome
  \end{verbatim}
\end{enumerate}
Sind diese Systemvoraussetzungen erf"ullt, kann mit den im Abschnitt~\ref{SubSec:Api3} erl"auterten Schritten zur Programmausf"uhrung fortgesetzt werden. Fehlermeldungen aufgrund nicht vorhandener oder auffindbarer Systemkomponenten sollten nicht auftreten.

\subsection{Das C-Programm api3.c}
\label{SubSec:Api3}

Um den Zugriff auf Repositoryobjekte mit Hilfe von in C-Programmen integrierten {\sf StP Application Program Interface} Funktionen exemplarisch darzustellen, wurde das im Anhang~\ref{Ann:Programm} wiedergegebene  C-Programm {\tt api3.c} entwickelt. Dabei wurde auf komplizierte Schleifen und Verzweigungen innerhalb des Aufbaus zugunsten der "Ubersichtlichkeit verzichtet. Die im Abschnitt~\ref{SubSec:API} aufgef"uhrten {\sf API} Funktionen stehen im Vordergrund der Betrachtung und werden exemplarisch ausgef"uhrt.\\

{\bf {\sf Vorgehen zur Programmausf"uhrung}}

Sind die im Abschnitt~\ref{SubSec:API} beschriebenen Systemvoraussetzungen f"ur die Ausf"uhrung der {\sf StP Application Program} Funktionsaufrufe realisiert, kann innerhalb der DBIS {\sf StP} Umgebung wie folgt vorgegangen werden, um auf {\sf StP} Repositoryobjekte zuzugreifen:

\begin{enumerate}
  \item Erstellen des C-Quellprogramms, hier: {\tt api3.c}.
  \item "Ubersetzen des C-Quellprogramms:

{\tt cc -c api3.c -I .../StP/templates/IDE/include}
  \item Verbinden des Objektkodes der Datei {\tt api3.o} mit dem Kode der {\sf OMS} Objektdateien:

{\tt cc api3.o -o api3}\\
{\tt -L .../StP/libsparc -L .../StP/sybase\_10.0.1/sparc/lib}\\
{\tt -L /usr/lib -lideoms -lideparse -lideeditor -lideoms -lidetools}\\
{\tt -lsybdb -lm -lidestub -lnsl}
  \item Aufruf des ausf"uhrbaren Programms, hier: {\tt api3}.
\end{enumerate}

{\bf {\sf Programminhalt und -interpretation}}

Das C-Programm {\tt api3.c} hat zusammengefa"st die Aufgabe, ein Repositoryobjekt mit den im Deklarationsteil initialisierten Attributwerten zu generieren, mehrmals auf verschiedene Arten nach diesem Objekt im entsprechenden {\sf StP Repository} zu suchen und schlie"slich das Repository zu aktualisieren. Zu diesem Zweck werden die im Abschnitt~\ref{SubSec:API} erl"auterten {\sf API} Funktionen verwendet. Das Programm {\tt api3.c} wurde zweimal hintereinander aufgerufen: Beim ersten Mal war das entsprechende Objekt schon im Repository vorhanden, beim zweiten Mal sollte ein neues Objekt generiert werden.

In diesem Abschnitt sind nur einige wesentliche Ausschnitte des gesamten Programms {\tt api3.c} wiedergegeben, die zum Verst"andnis der Vorgehensweise bei {\sf API} Funktionsaufrufen erforderlich sind. Desweiteren wird an dieser Stelle nur die Initialisierung der Attributwerte des ersten Programmlaufs dargestellt.\\

{\sf Variablendeklaration und -initialisierung (erster Programmaufruf):}

\begin{quote}
  \begin{verbatim}
char *name1, *name2, *name3;
char *name = "ausgedachter Node";
oms_app_type_tp type = 701576;
oms_object_id_tp scope = 0;
char *sig = "hallo";
oms_object_id_tp annot = 5;
FILE *fp;

oms_node_tp *node1, *node2, *node3, *node4;
char buf[1024];
oms_status_tp status;
  \end{verbatim}
\end{quote}        

Die hier initialisierte Struktur entspricht einem PDM-Objekt {\tt node} mit dem Namen {\tt ausgedachter Node} vom Typ {\tt OMTEvent}, mit der {\tt scope\_node\_id = 0}, der Signatur {\tt hallo} und der {\tt annot\_file\_id = 5}.\\

\newpage

{\sf API Anweisungen f"ur den Repositoryzugriff:}

\begin{quote}
\underline{Spezifikation des zu "offnenden Repositorys:}

{\tt oms\_sys\_repos\_open("{}.../StP/project"{}, "{}tutor"{});}

Der {\sf StP} Repositoryzugriff erfolgt auf das System {\tt tutor} innerhalb des angegebenen Verzeichnisses.\\
\\
\underline{Generierung einer Repositoryobjekt "aquivalenten Struktur im Hauptspeicher:}

{\tt node1 = oms\_node\_create(name, type, scope, sig);}

Der Zeiger {\tt node1} weist auf die erzeugte {\tt node} Struktur im Hauptspeicher, welche die "ubergebenen Attributwerte enth"alt.\\
\\
\underline{Auffinden des spezifizierten {\tt node} Objekts im {\sf StP Repository}:}

{\tt node2 = oms\_node\_find(name, type, scope, sig);}

Der Zeiger {\tt node2} weist auf die erzeugte {\tt node} Struktur im Hauptspeicher, nachdem das spezifizierte Objekt im Repository aufgefunden wurde. Ein weiterer Zeiger {\tt node3} weist sp"ater genau wie {\tt node4} auf eine Kopie dieser Struktur.\\
\\
\underline{Auffinden des {\tt node} Objekts im {\sf StP Repository} mit Hilfe einer {\sf OMS} Anfrage:}

{\tt sprintf(buf, "{}node$[$name='\%s' \&\& type=\%d \&\& scope\_node\_id=\%ld \&\& sig='\%s'$]$"{}, name, type, scope, sig);}
\\
{\tt node4 = oms\_node\_find\_by\_query(buf);}

{\sf OMS Query and Reporting Language} Anweisungen k"onnen als {\tt String} an die {\sf API} Funktion {\tt oms\_node\_find\_by\_query} "ubergeben werden. Zu beachten ist dabei, da"s die {\sf OMS} Anfrage das Repository abfragt und nicht den Hauptspeicher. Einzelheiten "uber {\sf OMS} Anfragen auf der Basis von {\sf StP Query and Reporting Language} Anweisungen sind in \cite{StPqrs94} enthalten.\\
\\
\underline{Ausgabe aller Attributnamen und -werte:}

{\tt oms\_node\_print(node1, fp);}

Die Attributnamen und -werte der Struktur, auf die der Zeiger {\tt node1} zeigt, werden ausgegeben.\\
\\
\underline{Freigabe des mit einer Struktur assoziierten Hauptspeicherbereichs:}

{\tt oms\_node\_free(\&node4);}

Der mit der Struktur, auf die der Zeiger {\tt node4} weist, assoziierte Hauptspeicherbereich wird freigegeben.\\
\\
\newpage
\underline{Aktualisierung des Repositorys:}

{\tt oms\_node\_update(node1);}

Die im Hauptspeicher abgelegte Struktur, auf die der Zeiger {\tt node1} weist, wird im {\sf StP Repository} persistent abgelegt.\\
\\
\underline{Attributwert"anderung bei einem persistenten Repositoryobjekt:}

{\tt oms\_node\_annot\_file\_id\_asgn(node1, 0);}
\\
{\tt oms\_node\_update(node1);}

Dem Strukturattribut {\tt annot\_file\_id} wird der Wert "`0"' zugewiesen. Anschlie"send wird das {\sf StP Repository} um den Inhalt der gesamten Struktur, auf die der Zeiger {\tt node1} im Hauptspeicher weist, aktualisiert.\\
\\
\underline{Schlie"sung des aktuellen Repositorys:}

{\tt oms\_repos\_close();}\\
\end{quote}

Zum Studium der vollst"andigen, aufbereiteten Ausgabe der Datei {\tt api3.c} (nach zweimaligem Aufruf) verweise ich auf die Datei {\tt api3\_Output.txt} im Anhang~\ref{Ann:Programmausg}.

\section{Bewertung}
\label{Sec:Bewert}

Die {\sf OMS} Schnittstellenfunktionen und das {\sf StP API} bilden die Schnittstelle zwischen dem Anwender und dem {\sf StP Object Management System}, welches f"ur die Verwaltung des Repositorys zust"andig ist.

Der Repositoryzugriff kann im Rahmen des {\sf StP Query and Reporting Systems} realisiert werden. Hierzu werden die in {\sf QRL} Skripten enthaltenen {\sf OMS} Schnittstellen-Funktionsaufrufe in {\sf OMS} Anfragen umgewandelt und daraufhin vom {\sf OMS} bearbeitet.

Die {\sf OMS} Schnittstellenfunktionen k"onnen problemlos in {\sf StP QRL} Skripte integriert werden. Desweiteren stellt die Skriptsprache s"amtliche, zur Erstellung von Applikationen ben"otigten Sprachkonstrukte, zur Verf"ugung. Somit ist ein Zugriff auf die Repositoryobjekte relativ unkompliziert mit der Hilfe eines {\sf StP QRL} Skripts zu erreichen. Auf alle im {\sf StP} Repository gespeicherten Attributwerte aller PDM-Typen kann auf diese Art zugegriffen werden.

F"ur den Umgang mit {\sf QRL} Skripten gibt es zwei M"oglichkeiten, den {\sf Script Manager} oder die {\sf qrp} Umgebung auf der Kommandooberfl"ache. Zwar ist der {\sf Script Manager} aufgrund seiner fensterorientierten Darstellungsform angenehmer zu benutzen als der zeilenorientierte {\sf qrp} Befehl. Daf"ur verf"ugt der zeilenorientierte Skriptinterpretationsbefehl {\sf qrp} aber "uber eine im Zusammenhang mit den dargestellten Optionen -- im Hinblick auf die Aufgabenstellung dieser Arbeit -- angemessene Funktionalit"at.

Wie im Abschnitt~\ref{SubSec:API} gezeigt, stellen die {\sf Application Program Interface} Funktionen neben den {\sf OMS} Schnittstellenfunktionen eine geeignete Schnittstelle zwischen dem Anwender und dem {\sf StP Repository} dar.

Das {\sf StP API} stellt dem Anwender in C-Programme integrierbare Funktionen zum Erstellen und Auffinden von Repositoryobjekten, zum Verwalten des Hauptspeichers und des {\sf StP Repositorys} selbst, zum Manipulieren von Repositoryobjekt-Attributwerten, zum Handhaben von \engl{Collection-}, \engl{Big Collection-}, Transaktionstypen und ID-Listen und zur Fehlerbehandlung bei fehlerhaften Repositoryaktionen, zur Verf"ugung. Desweiteren ist es dem Anwender m"oglich, eine {\sf OMS} Anfrage in {\tt String}-Repr"asentation der {\sf API} Funktion {\tt oms\_$<$pdm\_typ$>$\_find\_by\_query} als Parameter zu "ubergeben.

Die {\sf StP Application Program Interface} Funktionen k"onnen problemlos aus C-Programmen aufgerufen werden. Allerdings sind dabei die Systemvoraussetzungen, siehe Abschnitt~\ref{SubSec:API}, zu ber"ucksichtigen. Das "Ubersetzen und Binden der entsprechenden Dateien, wie im Abschnitt~\ref{SubSec:Api3} beschrieben, stellt beim Vorhandensein s"amtlicher Bibliotheksdateien ebenfalls kein Problem dar. Somit ist der Zugriff auf die Repositoryobjekte relativ einfach mit der Hilfe eines C-Programms und der entsprechenden {\sf API} Funktionen zu erreichen. Auf alle im {\sf StP Repository} "`gespeicherten"' Attributwerte aller PDM-Typen kann auf diese Art zugegriffen werden.

Verglichen mit dem Repositoryzugriff auf der Basis von {\sf StP QRL} Skripten stellt das {\sf StP API} ein wesentlich gr"o"seres Ma"s an Funktionalit"at f"ur den eigentlichen Zugriff zur Verf"ugung. Die M"achtigkeit von {\sf QRL} Skripten ist eindeutig in den M"oglichkeiten zur formatierten Ausgabe von {\sf StP Repository} Anfragen zu begr"unden. Im Hinblick auf die zu realisierende Anbindung des Tycoon-Systems an die {\sf StP} Umgebung ist die Benutzung des {\sf Application Program Interface} der von {\sf StP QRL} Skripten vorzuziehen.

Wie der Zugriff auf {\sf StP} Repositorydaten aus dem Tycoon-System heraus im Rahmen von {\sf StP API} Funktionsaufrufen endg"ultig realisiert werden kann, wird zu einem sp"ateren Zeitpunkt im Rahmen dieser Arbeit untersucht werden.

\clearemptydoublepage
