% ------------------------------------------------------------------ %
%                                                                    %
% Datei:        anbindg.tex                                          %
% Autor:        Oliver Nietsch                                       %
%                                                                    %
% Universitaet Hamburg                                               %
% Fachbereich Informatik                                             %
% Arbeitsbereich DBIS                                                %
%                                                                    %
% Thema: Studienarbeit: "Gateway zwischen dem StP-Repository         %
%                        und Tycoon"                                 %
%                                                                    %
% Inhalt: LaTeX-Dokument: Studienarbeit,                             %
%                         Kapitel 5: Anbindung des Tycoon-Systems    %
%                                    an die StP Umgebung, Teil 1     %
%                                                                    %
% Version vom  22. 2.1996                                            %
% ------------------------------------------------------------------ %

\chapter{Anbindung des Tycoon-Systems an die StP Umgebung}
\label{Chap:Anbindung}

Die Anbindung des Tycoon-Systems an die {\sf StP} Umgebung erscheint dem Benutzer wie in der Abbildung~\ref{Fig:TycAnbindg} dargestellt.\\

\begin{figure}[hbt]
  \begin{center}
    \ 
    \epsfig{figure=anbindg.eps,width=12cm}  
  \end{center}    
  \caption{\label{Fig:TycAnbindg} Anbindung des Tycoon-Systems an die {\sf StP} Umgebung}
\end{figure}

Dabei verh"alt sich das Tycoon-System als integrierte Entwicklungsumgebung hinsichtlich seines Aufrufs und Repositoryzugriffs wie sonstige, in die {\sf StP} Umgebung integrierte {\sf StP} Werkzeuge. Der Aufruf des Tycoon-Systems erfolgt "uber das im Abschnitt~\ref{SubSec:Aufruf}  dargestellte Piktogramm innerhalb des {\sf StP} Desktops, der Zugriff des Tycoon-Systems auf die {\sf StP} Repositoryobjekte wird "uber die vom {\sf StP Application Program Interface} als einem generischen, externen Diensterbringer, zur Verf"ugung gestellten Funktionen realisiert. Somit kann das Tycoon-System f"ur den Zugriff auf Objekte des {\sf StP} Repositorys die Funktionalit"at des {\sf StP Object Management Systems} benutzen.

Als Resultat dieser Anbindung des Tycoon-Systems an die {\sf StP} Umgebung entsteht innerhalb des Tycoon-Systems die generische Bibliothek {\sl stpenv}, die dem Tycoon-Anwender innerhalb des unifizierenden sprachlichen Raums der Tycoon-Umgebung die gesamte, im Abschnitt~\ref{Sec:Umfang} dargestellte, {\sf StP} Funktionalit"at f"ur den Repositoryzugriff bietet.

\section{Das Tycoon-System als integrierte Entwicklungsumgebung}
\label{Sec:Umgebg}

Wird eine {\sf StP} CASE-Umgebung der Firma {\sf Interactive Development Environments} gestartet, erscheint der {\sf StP} Desktop, welcher das Aufrufen von Editoren, des {\sf Repository Browsers}, des {\sf Script Managers}, des {\sf Print Servers} und sonstiger Administrationswerkzeuge erm"oglicht.

Der {\sf StP} Desktop ist an die ben"otigte Funktionalit"at der installierten {\sf StP} Produkte anpa"sbar. Sogar {\sf StP} fremde Befehle, Startskripte oder Programme k"onnen in den {\sf StP} Desktop integriert und von dort aus aufgerufen werden -- so auch das Tycoon-System.

\subsection{Benutzeranpassung des StP Desktop}
\label{SubSec:Anpassung}

Das Aussehen und Verhalten des {\sf StP} Desktops kann auf verschiedene Weise modifiziert werden \cite{StPcust94}. Zur Vollst"andigkeit werden hier einige dieser M"oglichkeiten erw"ahnt, ohne da"s auf alle von ihnen detailliert eingegangen wird:

\begin{itemize}
  \item Ver"anderung der Men"uregeln
  \item Benutzung von {\tt ToolInfo}-Variablen
  \item Setzen von {\sf X}-Ressourcen
  \item Modifikation der Klassenregeln
\end{itemize}

Meine Vorgehensweise zur Desktopindividualisierung bezieht sich auf die den {\sf StP} Desktop beschreibenden Klassenregeln und einige ihrer Attribute. Diese Regeln der h"ochsten Ebene definieren alle vorhandenen Desktopklassen und ihr Verhalten. Jede Klasse mu"s durch eine Klassenregel spezifiziert werden. In der Abbildung~\ref{Fig:OMT} sind beispielsweise 26 Klassen im {\sf StP} Desktop enthalten. Jede aufrufbare Klasse wird dabei durch ein eigenes Piktogramm dargestellt. 

\begin{figure}[hbt]
  \begin{center}
    \ 
    \epsfig{figure=omt.eps,width=7cm}
    \end{center}    
  \caption{\label{Fig:OMT} {\sf Software through Pictures} Desktop}
\end{figure}

Die Spezifizierung der grundlegenden Klassen erfolgt durch Wertzuweisung ihrer Attribute in der Datei {\tt .../StP/templates/IDE/ct/rules/stp.rules}. Die entsprechenden Piktogrammdateien dieser Klassen sind im Verzeichnis {\tt .../StP/templates/IDE/ct/icon} aufzufinden.

Modifikationen des {\sf StP} Desktop k"onnen vom Anwender in der daf"ur vorgesehenen Spezifikationsdatei neuer Klassen vorgenommen werden. Die daf"ur vorgesehene Datei {\tt user\_stp.rules} befindet sich im Verzeichnis {\tt .../StP/templates/IDE/user/ct/rules}.

Die Piktogramme der hinzugef"ugten Klassen k"onnen unter einem beliebigen Pfad hinzugef"ugt werden. Der "Ubersichtlichkeit wegen sollten sie aber im Verzeichnis {\tt .../StP/templates/IDE/user/ct/icon} gespeichert werden. Dort befindet sich auch die das Piktogramm des Tycoon-Systemaufrufs spezifizierende Datei {\tt user\_tycoon\_32.xbm}.

\subsection{Voraussetzungen der Desktop-Individualisierung}
\label{SubSec:Voraus}

Um den {\sf StP} Desktop um das Piktogramm der Klasse {\sf DBIS-Tycoon} zu erg"anzen und somit den Aufruf des Tycoon-Systems zu realisieren, sind einige Voraussetzungen zu beachten:

\begin{enumerate}
  \item Die Datei des in der Abbildung~\ref{Fig:OMT} dargestellten Tycoon-Piktogramms mu"s in dem im Abschnitt~\ref{SubSec:Anpassung} wiedergegebenen Piktogrammverzeichnis enthalten bzw. "uber eine g"ultige Pfadangabe zugreifbar sein.
  \item Die Klasse {\sf DBIS-Tycoon} ist, wie im Abschnitt~\ref{SubSec:Umsetz} angegeben, in der Datei {\tt user\_stp.rules} spezifiziert.
  \item Das Tycoon-System ist "uber das Skript {\tt start $<$workspace\_name$>$} aufrufbar. Hierbei handelt es sich um ein Startskript, welches einen separaten Tycoon-Proze"s in einem eigenen {\tt cmdtool}-Fenster initiiert. {\tt start} basiert auf dem Startskript {\tt tw $<$workspace\_name$>$}. Das komplette Skript {\tt start} wird an dieser Stelle nicht detailliert behandelt, ist aber im Anhang~\ref{Ann:Start} wiedergegeben.
\end{enumerate}

Grundvoraussetzung f"ur den Aufruf von {\sf StP/OMT} und des Tycoon-Systems sind g"ultige Zugriffsrechte auf die ben"otigten Dateien, g"ultige Pfadangaben und die sonstigen allgemeinen Zugriffsbedingungen (Gruppenzugeh"origkeiten etc.) in Mehrbenutzersystemen.
  
\subsection{Umsetzung der Desktop-Modifikation}
\label{SubSec:Umsetz}

Um die Klasse {\sf DBIS-Tycoon} dem {\sf StP} Desktop hinzuzuf"ugen, wurden die folgenden Anweisungen in der im Abschnitt~\ref{SubSec:Anpassung} erw"ahnten Klassen-Spezifikationsdatei eingef"ugt:

% \newpage

{\tt Class Tycoon\\
\{
\begin{quote}
    \{ Label "{}DBIS-Tycoon"{} \}\\
    \{ Image "{}user/ct/icon/user\_tycoon\_32.xbm"{} \}\\
    \{ ShowOnDesktop True \}\\
    \{ ClassCommand
\begin{quote}
        \{ SpaceAfter True \}\\
        \{ Name "{}tycoon"{} \}\\
        \{ Label "{}Start Tycoon..."{} \}\\
        \{ Command "{}/local/dbis11/software/StP/scripts/start tycoon"{} \}\\
        \{ Type Nowin \}
\end{quote}
    \}
\end{quote}
\}}\\

Der Effekt dieser Anweisungen ist der, da"s der {\sf StP} Desktop um das spezifizierte Tycoon-Piktogramm erg"anzt wird und ein Aufruf von Tycoon so erm"oglicht wird. Eine tiefgreifende Erkl"arung aller dargestellten Klassenattribute ist in \cite{StPcust94} enthalten.

\subsection{Aufruf des Tycoon-Systems}
\label{SubSec:Aufruf}

Das Tycoon-System wird auf der {\sf StP} Desktopebene durch Anklicken des in der Abbildung~\ref{Fig:TYCOON} dargestellten Piktogramms erreicht.\\

\begin{figure}[hbt]
  \begin{center}
    \ 
    \epsfig{figure=tycoon.eps,width=3cm}  
  \end{center}    
  \caption{\label{Fig:TYCOON} {\sf DBIS-Tycoon} Piktogramm {\tt user\_tycoon\_32.xbm}}
\end{figure}

Das so ge"offnete Tycoon-Fenster kann auf der Tycoon-Ebene zum Beispiel mit dem Befehl {\sl do exit} wieder terminiert werden.

\section{Abzubildende Funktionalit"at der StP Umgebung}
\label{Sec:Umfang}

Die Tycoon-Bibliothek f"ur den {\sf StP} Repositoryzugriff mu"s mindestens die folgenden an sie gestellten Anforderungen befriedigen, welche sich an der Funktionalit"at des {\sf StP Application Program Interface} orientieren \cite{StPoms94}:

\begin{itemize}
  \item Generieren und Auffinden von Repositoryobjekten
  \item Auffinden, Manipulieren und Ausgeben von Attributwerten der spezifizierten Repositoryobjekte
  \item Verwalten des Hauptspeichers
  \item Repositorymanagement
  \item Durchf"uhren von Operationen auf zu einer Einheit zusammengefa"sten Objekten innerhalb des {\sf StP Repositorys} im Rahmen von \engl{Collection} und \engl{Big Collection} Typen
  \item Interpretieren von {\sf OMS} Anfragen
  \item Verwalten und Manipulieren von Datums- und Zeitrepr"asentationen
  \item Initiieren, "Uberwachen und Abschlie"sen von {\sf StP} Repositorytransaktionen
  \item Generieren und Verwalten von ID-Listen
  \item Durchf"uhren der Fehlerbehandlung bei nicht erfolgreich abgeschlossenen Repositoryoperationen
\end{itemize}

Diese Anforderungen an den Funktionsumfang der {\sf StP} Tycoon-Bibliothek werden ihre Ber"ucksichtigung in der Abbildung der Operationen des {\sf StP API} auf die entsprechenden Tycoon-Funktionen und Module finden.

\section{Abbildung der StP Repositoryfunktionalit"at auf die Tycoon-Ebene}
\label{Sec:Transfer}

Die gesamte Funktionalit"at f"ur den Repositoryzugriff wird vom {\sf StP Application Program Interface} zur Verf"ugung gestellt, welches eine C-basierte Bibliothek von Funktionen und Datentypen darstellt. Auf der Tycoon-Ebene sollen beim Zugriff auf Repositoryobjekte im Rahmen der im Abschnitt~\ref{Sec:Modellierg} vorgestellten {\sf StP} Umgebung, der Tycoon-Bibliothek {\sl stpenv}, ausschlie"slich Funktionen und Datentypen auf der Basis von TL, der Programmiersprache des Tycoon-Systems, benutzt werden. Somit kann der Tycoon-Anwender unabh"angig von {\sf StP API} C-Funktionsaufrufen auf das {\sf StP Repository} zugreifen. Diese Vorgehensweise macht es erforderlich, da"s innerhalb der Tycoon-Umgebung eine geeignete Abbildung der C-basierten {\sf API} Funktionen auf ad"aquate TL-Funktionsdeklarationen erfolgt.

In diesem Abschnitt wird die Abbildung der {\sf StP API} Funktionalit"at auf Tycoon-Funktionalit"at exemplarisch am Beispiel einiger Funktionen des PDM-Typen {\tt node} dargestellt. Diese Vorgehensweise ist auch f"ur alle "ubrigen PDM-Typen und sonstige innerhalb des {\sf Application Program Interface} verwendeten Datentypen und Funktionen g"ultig.

Au"ser einer einfachen Abbildung der {\sf StP API} Funktionalit"at wird die M"achtigkeit der {\sf StP} Umgebung auf der Tycoon-Seite durch zus"atzliche, den Umfang der eigentlichen {\sf API} Funktionalit"at erweiternde n"utzliche Charakteristika erg"anzt (siehe Abschnitt~\ref{Sec:Modellierg}). 

\subsection{Tycoon C-Calls f"ur den StP API-Funktionsaufruf}
\label{SubSec:CCall}

Das Tycoon-System bietet einen generischen Mechanismus, um auf in externen Programmiersprachen implementierte Funktionalit"at zugreifen zu k"onnen \cite{MMM93}. Eine aufzurufende externe C-Funktion kann mit Hilfe der Tycoon-Funktion {\sl bind} an einen Tycoon-Bezeichner gebunden werden:

\begin{xple}
\k{let} bspFkt = 
  \k{bind}(:Fun(:Int) :Int "{}bsp\_bibliothek.so"{} "{}bsp\_funktion"{} "{}ii"{})
\end{xple}

Hierbei wird die in der dynamischen C-Bibliothek {\tt bsp\_bibliothek.so} vorhandene C-Funktion {\tt bsp\_funktion} an den Tycoon-Bezeichner {\sl bspFkt} statisch gebunden. Der Wert dieses Bezeichners ist vom Typ {\sl \k{Fun}(:Int) :Int}. Innerhalb der Tycoon-Umgebung kann die C-Funktion {\tt bsp\_funktion} daraufhin wie folgt indirekt aufgerufen werden:

\begin{xple}
\k{let} ergebnis :Int = bspFkt(20)
\end{xple}

Welche C-Funktion sich hinter der Tycoon-Funktion {\sl bspFkt} verbirgt, ist f"ur den Tycoon-Benutzer nicht mehr ersichtlich. Diese Vorgehensweise wird im Rahmen des Aufrufs der {\sf StP Application Program Interface} Funktionen von der Tycoon-Ebene aus im weiteren Verlauf dieser Arbeit verfolgt. Weitere Informationen "uber die Benutzung externer C-Bibliotheken aus dem Tycoon-System heraus sind in \cite{MMM93} enthalten.

\subsection{Abbildung von StP API-Funktionen auf Tycoon-Funktionen}
\label{SubSec:APIFunk}

Die Abbildung der StP API-Funktionen auf Tycoon-Funktionen erfolgt unter Verwendung der im Abschnitt~\ref{SubSec:CCall} dargestellten Vorgehensweise in f"unf Schritten:

\begin{enumerate}
  \item Auf der Systemebene mu"s als Grundlage f"ur die Tycoon-Funktion {\sl bind} aus den vorhandenen dynamischen {\sf StP} Bibliotheken eine einzige dynamische Bibliothek erstellt werden, welche die gesamte, ben"otigte {\sf StP} Funktionalit"at des {\sf StP API} zur Verf"ugung stellt. Der Name dieser Bibliothek wird beim Anbinden einer {\sf StP API} Funktion der Tycoon-Funktion {\sl bind} als Parameter "ubergeben.

Eine Begr"undung erf"ahrt das Generieren einer einzigen dynanischen Bibliothek dadurch, da"s beim Aufruf einer gebundenen {\sf API} Funktion eventuell weitere Operationen oder Datentypen aus anderen dynamischen {\sf StP} Bibliotheken referenziert werden. Um Fehler basierend auf nicht bekanntgegebenen Funktionen oder Datentypen zu vermeiden, werden s"amtliche dynamischen Bibliotheken miteinander verbunden. Ein entsprechendes Generierungsskript zum Erstellen der Bibliothek {\tt libstp.so} umfa"st:
\begin{verbatim}
ld -G -o ${TYCOON_ROOT}/lib/${TYCOON_HOST}/libstp.so 
.../StP/libsparc/libideoms.so .../StP/libsparc/libideparse.so 
.../StP/libsparc/libideeditor.so .../StP/libsparc/libidetools.so 
.../StP/libsparc/libsybdb.so /usr/lib/libm.so
.../StP/libsparc/libidestub.so /usr/lib/libnsl.so
\end{verbatim}
  \item Eine Voraussetzung f"ur eine erfolgreiche Ausf"uhrung der {\sf StP API} C-Funktionen bzw. einen erfolgreichen Entwicklungsdatenbankzugriff ist ein Eintrag {\tt stp\_file\_path} mit den entsprechenden Pfaden zu den {\sf StP} Dateien innerhalb der Datei {\tt ToolInfo}, in welcher grundlegende Initialisierungen einiger {\sf StP} Systemvariablen und Pfade zu den ben"otigten Dateien der einzelnen {\sf StP} Produkte anzugeben sind. Die Datei {\tt ToolInfo} mu"s f"ur die Benutzung des {\sf StP Application Program Interface} aus dem Tycoon-System heraus um den folgenden Eintrag erg"anzt werden:
\begin{verbatim}
stp_file_path=.../StP/templates/IDE/omt_booch:
.../StP/templates/IDE/booch:.../StP/templates/IDE/oo:
.../StP/templates/IDE/omtcc:.../StP/templates/IDE/t:
.../StP/templates/IDE/ct:.../StP/templates/IDE
\end{verbatim}
  \item Auf der Tycoon-Ebene m"ussen die im Abschnitt~\ref{SubSec:API} wiedergegebenen Systemumgebungsvariablen innerhalb jedes neu gestarteten Tycoon-Subprozesses gesetzt werden. Nur so kann ein erfolgreicher Repositoryzugriff vom Tycoon-System aus erreicht werden.

Zu diesem Zweck gibt es in der Tycoon-Bibliothek {\sl machineenv} das Modul {\sl uxEnvironment}, mit dessen Funktion {\sl set(name, value :String) :\k{Ok}} die entsprechenden {\sf StP} Systemvariablen zu Beginn eines Tycoon-Subprozesses initialisiert werden k"onnen. Innerhalb der {\sf StP} Tycoon-Bibliothek {\sl stpenv} "ubernimmt die Funktion {\sl omsRepository.init()} diese Aufgabe.
  \item Daraufhin k"onnen auf der Tycoon-Ebene die {\sl bind}-Funktionen an die entsprechenden Bezeichner gebunden  und anschlie"send wie Tycoon-Funktionen benutzt werden (hier ein Beispiel aus dem Tycoon-Modul {\sl omsNode} der Bibliothek {\sl stpenv}):
\begin{xple}
        \k{Let} T = omsRep.NodeHandle
        \k{let} lib = runtimeCore.dynamicLibraryName("{}stpenv"{} "{}libstp"{})
        \k{let} handleNil = word.HandleNil(:omsRep.Node)
        \k{let} error = \k{exception} "{}OMS\_ERROR"{} \k{end}

        \k{let} findCall = \k{bind}(:Fun(:String :omsApplicationType.T :omsObjectId.T :String)
                                   :T lib "{}oms\_node\_find"{} "{}siwsw"{})

        \k{let} find(rep :omsRepository.T  name :String  type :omsApplicationType.T
                   scopeNodeId :omsObjectId.T(T)  signature :String) :T =
          \k{begin}
            omsRepository.check(rep)
            \k{let} omsNodeTp = findCall(rep name type scopeNodeId signature)
            \k{if} word.handleEqual(omsNodeTp handleNil) \k{then}
              \k{raise} error \k{end}
            \k{else}
              omsNodeTp
            \k{end}
          \k{end}
\end{xple}

Als R�ckgabewert des Aufrufs der C-Funktion {\tt oms\_node\_find} erh"alt die Tycoon-Funktion {\sl find} ein 32-Bit Wort, dessen Inhalt dem Zeiger auf die entsprechende C-Struktur {\tt oms\_node\_tp} entspricht.
  \item Der Tycoon-Anwender kann den Zugriff auf das StP Repository nach erfolgter Initialisierung der {\sf StP} Systemvariablen und einem Import der entsprechenden Module der im Abschnitt~\ref{Sec:Modellierg} wiedergegebenen {\sf StP} Umgebung {\sl stpenv} "uber die dort deklarierten Tycoon-Funktionen nach dem folgenden Muster durchf"uhren:

\newpage

\begin{xple}
        \k{import} omsRepository omsNode

        \k{let} projdir = "{}/local/dbis11/software/StP/project"{}
        \k{let} system = "{}tutor"{}

        omsRepository.init()

        \k{let} rep = omsRepository.connectSystem(projdir system)

        \k{let} node = omsNode.find(rep "{}Nodename"{} omsApplicationType.type 
                                          omsObjectId.optional() "{}Signatur"{})
        ...

        omsRepository.disconnect(rep)
\end{xple}

Nach Initialisierung der {\sf StP} Systemvariablen wird eine Anzahl von Repositoryoperationen stets durch das "Offnen des Repositorys ({\sl omsRepository.connectSystem} oder {\sl omsRepository.connectRep}) und sp"ateres Schlie"sen ({\sl omsRepository.disconnect}) eingerahmt. Zu beachten ist dabei, da"s zur Zeit maximal ein Repository ge"offnet werden darf.

Ein Beispiel f"ur Tycoon-Anweisungen zum Ausf"uhren der gesamten {\sf StP} Funktionalit"at im Kontext mit Repositoryobjekten der {\sf StP API} Datenstruktur {\tt oms\_node\_tp} ist im Anhang~\ref{Ann:Bsp1} wiedergegeben.
\end{enumerate}

\input{anbindg2.tex}
