# -*- indented-text -*- # # *************************************************************************** # $RCSfile: dok.txt,v $ # $Revision: 1.5 $ # $Date: 1995/04/04 09:01:44 $ # # $Log: dok.txt,v $ # Revision 1.5 1995/04/04 09:01:44 nix # New location for binaries created. This is done using the global # make-variable BIN defined in makefile.common. # # Revision 1.4 1995/04/03 14:21:13 nix # Ergänzungen für Release 1.4: # - fehlende Anfrageprädikate definiert, # - Dokumentation um Template-Behandlung ergänzt, # - Dokumentation um Einstellungsmöglichkeiten erweitert. # # Revision 1.3 1995/03/30 14:13:23 nix # Release information adapted. # # Revision 1.2 1995/03/29 14:47:31 nix # Funktion zum selektiven Löschen von Anfragen implementiert. # (Keine Änderungen der Dokumentationerforderlich.) # # Revision 1.1 1995/03/29 12:22:08 nix # Documentation for Genf Release 1.1 # # *************************************************************************** # Dokumentation zum Program Genf, Release 1.4 =========================================== Projekt WibQuS Informatik V, RWTH Aachen, Ahornstraße 55, 52056 Aachen Author: Reiner B. Nix EMail: nix@picasso.informatik.rwth-aachen.de Inhalt ------- Benutzerdokumentation Zielsetzung Voraussetzungen Bedienung Technische Dokumentation Lieferumfang Voraussetzungen Installation Portierung auf eine andere SQL-Datenbank Portierung auf ein anderes Teilsystem Implementierung Architektur Konventionen Templates Makefiles Einstellungen Benutzte Programme Anhang Benutzerdokumentation --------------------- Zielsetzung ----------- Das Programm Genf dient dazu Kurzanfragen zu parametrisieren und mittels des lokalen Datenbanksystems dem Qualitytrader zu übermitteln. Die Anfrageergebnisse werden dem Benutzer anschliessend angezeigt. Voraussetzungen --------------- Der Benutzer benötigt eine Kennung für das lokale Datenbanksystem des Teilsystems, das natürlich gestartet sein muß. Damit Anfragen auch bearbeitet werden können ist es notwendig, daß der Qualitytrader und die dazugehörigen Programme (Datenbanksystem und ConceptBase) ebenfalls laufen. Bedienung --------- Das Programm hat eine graphische Benutzerschnittstelle unter XWindows/Motif. Es öffnet mehrere Fenster und stellt darin Masken für den Verbindungsaufbau zum lokalen Datenbanksystem, die Parametrisierung einer Anfrage, die Überwachung aller Anfragen in der aktuellen Programmsitzung und der Ergebnisabfrage zur Verfügung. Verbindungsaufbau: direkt nach dem Start zeigt das Programm das Fenster 'Verbindungsaufbau' an. Dem Benutzer stehen zwei Eingabefelder für seine Benutzerkennung im Datenbanksystem und das zugehörige Paßwort zur Verfügung. Am unteren Bildschirmrand sind zwei Knöpfe. Nach Betätigen des Knopfes 'Starten' liest das Programm die Textfelder 'Benutzer' und 'Paßwort' aus und versucht eine Verbindung zum Datenbanksystem aufzubauen. Mit dem Knopf 'Abbrechen' kann das Programm beendet werden. Nachdem die Verbindung erfolreich aufgebaut ist, wird das Fenster 'Verbindungsaufbau' geschloßen und das Hauptfenster 'Genf' geöffnet. Das Hauptfenster 'Genf' erlaubt es über eine Maske Anfragen zusammenzustellen. über das Menü 'Programm' können die Fenster 'Anfragemonitor' und 'Anfrageergebnisse' geöffnet werden. Das Menü 'Einstellungen' bietet die Möglichkeit verschiedene Programmeinstellungen einzusehen und zu bearbeiten (zur Zeit noch nicht fertiggestellt). Schließlich können mit dem Menü 'Hilfe' noch Informationen über das Programm Genf selbst abgefragt werden. Parametrisierung einer Anfrage: die Parametrisierung einer Anfrage wird in zwei Schritten durchgeführt. Zuerst wird in der oberen Maske 'Anfrage' ein Anfrageprädikat bestimmt indem es mit der linken Maustaste aus der Liste selektiert wird. Nach der Auswahl des Prädikates werden dem Benutzer in der unteren Maske 'Argumente' die Namen und Werte aller Argumente zu der ausgewählten Anfrage dargestellt. Im zweiten Bearbeitungsschritt erfolgt die Belegung der Anfrageargumente. Nachdem ein Argument aus der Liste selektiert ist, kann der gewünschte Wert im Feld 'Wert' eingegeben werden. Die übermittlung einer Anfrage an den Qualitytrader wird mit dem Knopf 'Starte Anfrage' in Gang gesetzt. Durch die Betätigung des Knopfes werden ebenfalls die Fenster 'Anfragemonitor' und 'Anfrageergebnisse' automatisch geöffnet. Das Fenster 'Anfragemonitor' stellt in der Liste 'Anfragen' eine übersicht über alle Anfragen dar. Aus dieser Liste kann jeweils eine Anfrage selektiert werden und mit den darunter gelegenden Knöpfen 'Anzeigen', 'Löschen' und 'Wiederholen' manipuliert werden. Mit dem Knopf 'Anzeigen' wird die Anfrage und ihre Ergebnisse -- soweit schon vorhanden -- im Fenster 'Anfrageergebnisse' dargestellt. Der Knopf 'Löschen' entfernt die angewählte Anfrage aus den Austauschrelationen der lokalen Datenbank, im Programm wird die Anfrage allerdings bis zum Sitzungsende verwaltet und kann somit noch als Vorlage für eine neue Anfrage benutzt werden. Der Knopf 'Wiederholen' gestattet es eine zuvor ausgewählte Anfrage in kompletter Form (Prädikat und Argumente) in die Eingabemaske im Fenster 'Genf' zu übernehmen, so daß sie eventuell abgeändert noch einmal gestellt werden kann. Das Fenster 'Anfrageergebnisse' zeigt alle Daten zu einer Anfrage detailliert auf. Die Liste 'Ergebnisse' visualisiert sämtliche Ergebnistabellen -- soweit ein Ergebnis schon bekannt ist. In der darunter gelegenden Maske ist die Anfrage selbst und ihr aktueller Bearbeitungsstatus zu sehen. Das Programm Genf wird mit dem Menüpunkt 'Programm/Beenden' des Hauptfensters 'Genf' beendet. Technische Dokumentation ------------------------ Lieferumfang ------------ Das Programm Genf wird in einem Archiv, das allen Quelltexte enthält, zur Verfügung gestellt. Damit ist eine individuelle Anpassung des Programmes an die lokale Datenbank und das lokale Teilsystem möglich. Der Verzeichnisbaum des Archives ist wie folgt gegliedert: Genf bin doc source genf common xSupport sqlSupport Voraussetzungen --------------- * Ein C++ Compiler, der Templates beherrscht. Das Programm wurde unter Einsatz des GNU Compilers gcc, Version 2.5.8 bzw. 2.6.2 entwickelt und getestet. * XWindows mit dem Motif-Toolkit * Eine Datenbankschnittstelle zum lokalen Datenbanksystem. In der ausgelieferten Version unterstützt das Programm die OpenClient- Schnittstelle des DBMS OmniSQL von Sybase. Installation ------------ * Anpassung der Makefiles: (siehe auch Kapitel 'Implementierung/Makefiles') Genf/source/common/makefile.common Hier sind im Abschnitt 'program locations' die Pfade und eventuell besondere Aufrufparameter des benutzten Compilers u.ä. anzupassen. Eventuell können auch Einstellungen beeinflußt werden, siehe auch Kapitel Implementierung/Einstellungen. genf/source/xSupport/makefile.loc Hier sind im Abschnitt 'library locations' die Pfade für XWindow und Motif anzupassen: GUIINCLDIRS = -I/public/X11R5/include GUILIBDIRS = -L/public/X11R5/lib Genf/source/sqlSupport/makefile.loc Hier sind im Abschnitt 'library locations' Pfade und zu benutzende Bibliotheken bezüglich des lokalen Datenbanksystem anzupassen: SQLINCLDIRS = -I/DBMS/sybase/installation/100/include SQLLIBDIRS = -L/DBMS/sybase/installation/100/lib SQLLIBS = -lsybdb Genf/source/sqlSupport/makefile Im Abschnitt 'files' ist die Objektdatei, die den Zugriff auf das lokale Datenbanksystem kapselt anzugeben: OBJECTS1 = DBAccessSybase.o Genf/source/sqlSupport/makefile.dep Hier sind die Include-Abhängigkeiten anzupassen und bei der Portierung auf eine andere SQL-Datenbank entspechende zusätzliche Abhängigkeiten einzutragen (siehe auch Kapitel 'Implementierung/Portierung auf eine andere SQL-Datenbank'): DBAccessCurrent.hh =DBAccessCurrent.hh $(DBAccessSybase.hh) Genf/source/genf/makefile Im Abschnitt 'files' ist die Objektdatei, die den Zugriff auf das lokale Teilsystem kapselt anzugeben: OBJECTS1 = [...] SubsystemI5.o \ [...] Genf/source/genf/makefile.dep Hier sind die Include-Abhängigkeiten anzupassen und bei der Portierung auf ein anderes Teilsystem entspechende zusätzliche Abhängigkeiten einzutragen (siehe auch Kapitel 'Implementierung/Portierung auf ein anderes Teilsystem): SubsystemCurrent.hh =SubsystemCurrent.hh $(SubsystemI5.hh) * Portierung auf eine andere SQL-Datenbank * Portierung auf ein anderes Teilsystem Diese Schritte sind notwendig, wenn das lokale Datenbanksystem bzw. das lokale Teilsystem noch nicht unterstützt werden. Zur genauen Vorgehensweise gibt es weiter unten eigene Kapitel. * übersetzung des gesamten Programmes Das gesamte Programm mit allen Modulen kann mit dem Makefile Genf/source/makefile übersetzt werden. * Ausführbares Programm Das ausführbare Programm liegt nun in der Datei Genf/bin/genf vor. Damit auch das Login-Bild Genf/bin/GenfLogo.xbm vom Programm gefunden wird, sollte diese Datei im aktuellen Startverzeichnis zu finden sein. Portierung auf eine andere SQL-Datenbank ---------------------------------------- Die Anpassung des Programmes an eine andere SQL-Datenbank geschieht dadurch, daß für die gewünschte Datenbank, beispielsweise für das fiktive DBMS XXX, einige allgemeine Funktionen implementiert werden. Die folgenden Dateien sind alle im Verzeichnis Genf/source/sqlSupport zu finden. Auf Basis der abstrakten Klasse DBAccess (in der Datei DBAccess.hh) ist eine neue Klasse DBAccessXXX zu schreiben, die von der abstrakten Klasse DBAccess abgeleitet ist und deren abstrakten Methoden realisiert. Schließlich wird für das Programm ein allgemeingültiger Name 'DBAccessCurrent' für die zu benutzende Klasse benutzt, so daß in der Datei DBAccessCurrent.hh das entsprechende typedef zu ändern ist. Weitergehende Hinweise sind direkt in den Quelltexten enthalten. Bei Zweifeln und als Beispiel ist die bereits implementierte Klasse DBAccessSybase maßgeblich. Die notwendigen Änderungen der Makefiles sind im obigen Abschnitt 'Installation' beschrieben. Portierung auf ein anderes Teilsystem ------------------------------------- Die Anpassung des Programmes an das lokale Teilsystem wird ähnlich der Anpassung an eine andere SQL-Datenbank vorgenommen. Die entsprechenden Dateien sind im Verzeichnis Genf/source/genf zu finden. Angenommen das Programm soll an das Teilsystem YYY angepasst werden, dann ist eine Klasse SubsystemYYY zu implementieren. Diese soll die abstrakte Klasse Subsystem realisieren und auch in der Datei SubsystemCurrent eingetragen werden. Weitergehende Hinweise sind direkt in den Quelltexten enthalten. Bei Zweifeln und als Beispiel ist die bereits implementierte Klasse DBAccessI5 maßgeblich. Die notwendigen Änderungen der Makefiles sind im obigen Abschnitt 'Installation' beschrieben. Implementation -------------- Architektur ----------- Das Programm Genf besteht aus den cvs-Moduln Genf, das die Wurzel und den Hauptpfad des Verzeichnisbaum beinhaltet, sowie den separaten cvs-Moduln common, xSupport und sqlSupport. Diese cvs-Moduln sind innerhalb des Verzeichnis Genf/source angesiedelt. Graphische Architekturdiagramme sind in den Dateien Genf/doc/GrobArchitektur, Genf/doc/FeinArchitektur, Genf/doc/GUIArchitektur und Genf/doc/XSupportArchitektur enthalten. Das Programm Genf ist im Groben dreigeteilt: die Datenhaltung wird durch die Teilsysteme (Genf)Data, (Genf)Subsystem und SQLSupport vorgenommen. Die graphische Oberfläche wird in den Teilsystemen XSupport und (Genf)GUI realisiert. Schließlich gibt es die Steuerungsschicht (Genf)Control. Die Trennung zwischen den drei Bereichen ist nicht fließend sondern strikt. * Datenhaltung Das Teilsystem Common stellt einige Datentypen für den allgemeinen Gebrauch zur Verfügung. Davon sind insbesondere die Typen 'Text' und 'DynamicArray' im Programm an vielen Stellen benutzt. Der Datentyp 'Text' kapselt mittels einer Klasse einen Datentyp, der beliebig lange Zeichenketten speichern kann und auch eine sichere Verwaltung des benötigten Hauptspeicher vornimmt. Der generische Datentyp 'DynamicArray' ist als ein template realisiert und kapselt ein Feld, dessen Elemente inidziert angesprochen werden können. Die Größe des Feldes ist beliebig und passt sich automatisch an. Programmlokale Datenstrukturen sind im Teilsystem (Genf)Data zu Hause. In der Datei DataBlanks.hh ist die Struktur von Argument- und Anfrageformularen definiert. Als 'Formular' wird eine Anfrage bzw. ein Argumenttupel, daß noch keine Werte enthält, bezeichnet. Im Gegensatz dazu sind in der Datei DataVals.hh ausgefüllte Argumenttupel und Anfrageformulare beschrieben. Das Teilsystem SQLSupport kapselt datenbankabhängige Zugriffsroutinen und stellt sie über eine einheitliche Schnittstelle zur Verfügung. Es ist selbst in drei Schichten aufgebaut: zu unterst ist in der Datei DBAccess.hh die Schnittstelle als abstrakte C++ Klasse deklariert. In der zweiten Schicht ist diese Klasse dann für ein spezielles Datenbanksystem (z.B. XXX) realisiert in dem eine Unterklasse DBAccessXXX von der Basisklasse DBAccess definiert wird, die die bereits deklarierten Funktionen implementiert. In der dritten Schicht, die einzig aus der Datei DBAccessCurrent.hh besteht, wird den Benutzern dieses Teilsystems ein einheitlicher Zugriffspfad auf die gewünschte Klasse DBAccessXXX eingerichtet. Der Zugriffspfad ist unabhängig von der Klasse DBAccessXXX und wird durch ein typedef vorgenommen. Das Teilsystem Subsystem kapselt Informationen bezüglich des lokalen (WibQus-)Teilsystems. Der Aufbau entspricht dem Aufbau des Teilsystems SQLSupport. * GUI Die graphische Oberfläche ist in vier Schichten unterteilt. Davon sind die untersten zwei Schichten Programmunabhängig und deshalb im Teilsystem xSupport abgelegt. Die beiden obersten Schichten sind spezifisch für das Programm und deswegen im Verzeichnis Genf enthalten. Die unterste Schicht besteht aus der Datei xdclass.hh und definiert die unterste Ebene der Klassenhierachie, diese Datei wird mit dem GUI-Builder 'XDesigner' geliefert. In der zweiten Schicht sind die benutzten, interaktiven graphischen Elemente als Klassen gekapselt. Mittels dieser Schicht werden einige Funktionen des XToolkits bzw. Motif explizit den einzelnen Oberflächenobjekten zugeordnet und in ihrer Anwendung vereinfacht. Die dritte Schicht besteht aus der, mit dem Programm 'XDesigner', generierten Oberfläche des Programmes. In dieser Schicht werden konkrete GUI-Elemente als Objekte instantiert, im wesentlichen wird dabei das entsprechende Layout festgelegt. Letztendlich dient die vierte Schicht der Präsentation: die Oberflächenelemente werden um Methoden angereichert, die Datenstrukturen anzeigen können. * Steuerung In der Steuerung wird mit den Dateien Genf, die die Hauptfunktion enthält, DataStart und ControlStart das Programm initialisiert. Die Datei ControlGenf beinhaltet CallBack-Funktionen mit denen auf Ereignisse der Oberfläche reagiert und somit der Kontrollfluß bestimmt wird. Die Datei SQLQuery bearbeitet Anfragen dann im wesentlichen mit Hilfe der Bausteine (Genf)Data und SQLSupport. Konventionen ------------ Zur Vereinheitlichung und auch zur leichteren Verständlichkeit des Programmes sind folgende Konventionen weitgehend eingehalten: * Namensgebung: statische Programmkonstrukte, wie Datentypen und Funktionen, beginnen mit einem Großbuchstaben, dynamische Konstrukte, wie Variablen und Methoden (!), beginnen mit einem Kleinbuchstaben. Ist ein Namen aus mehreren Teilen aufgebaut, beginnen auch diese mit Großbuchstaben. Es werden keine Unterstriche benutzt. * Header-Dateien besitzen die Endung ".hh" und enthalten soweit als möglich keine Funktionsdefinitionen, diese sind den Implemetationsdateien, Endung ".cc" vorbehalten. * (XDesigner) Klassen sind mit der Endung "_c" und die dazugehörigen Zeiger mit "_p" bezeichnet. * Formale Funktionsparameter und Variablendeklarationen sind tabellarisch angeordnet. * Zählvariablen werden bei for-Schleifen lokal deklariert. Templates --------- In alten und aktuellen Versionen des gcc (2.5.8 und 2.6.x) sind zur Benutzung von Templates zusätzliche Anweisungen notwendig, da zwei Einschränkungen im Compiler momentan keine vollautomatische Instanzierung erlauben: a) es müssen nicht nur die Methoden- bzw. Funktionsdeklarationen sichtbar sein sondern auch deren vollständige Definitionen und b) der Compiler darf für Objekte -- auch bei mehrfacher Instanzierung mit dem gleichen Typ -- nur einmal Code generieren (expandieren). Deshalb sind hierfür besondere include und pragma-Anweisungen notwendig, die durch ein Beispiel beschrieben sind: * Template-Deklaration in Genf/source/common/DynamicArray.hh: #pragma interface // ... #include "DynamicArray.cc" * Template-Definition in Genf/source/common/DynamicArray.cc: #ifndef _DynamicArray_cc_ // ... #include "DynamicArray.hh" * Template-Instanzierung in Genf/source/common/TextArray.hh: #include "DynamicArray.hh" typedef DynamicArray TextArray; * Template-Expansion in Genf/source/common/TextArray.cc: #pragma implementation "DynamicArray.hh" #include "TextArray.hh" Die unübliche Anordnung der include-Anweisung in DynamicArray.hh und DynamicArray.cc bewirkt, daß Methodendefinitionen und -deklarationen sichtbar voneinander getrennt sind, die Deklarationen aber trotzdem noch gefunden werden. Die Pragmaanweisung interface hat zur Folge, daß nachfolgende Templates nicht expandiert werden, es wird also kein Code erzeugt. Damit aber mindestens einmal expandiert wird, muß das interface Pragma durch eine einzige, vorhergehende Pragmaanweisung implementation aufgehoben werden. Zusätzlich dazu muß der Compiler mit der Option external-templates aufgerufen werden, dies ist in der Datei Genf/source/common/makefile.common eigestellt: CC = [...] -fexternal-templates [...] Makefiles --------- Es gibt vier verschiedene Arten von Makefiles, die anhand ihrer Endung unterschieden werden: makefile.common (nur in Genf/source/common) Hier sind allgemeingültige Einstellungen vorgenommen. Das betrifft insbesondere die Auswahl des zu benutzenden Compilers und der Übersetzungsregeln. makefile.dep Hier sind die Abhängigkeiten zwischen den zu übersetzenden Dateien festgehalten. Die Notation entspricht inhaltlich den include-Anweisungen im Quelltext. Für Header-Dateien wird eine gleichnamige Make-Variable angelegt, die deren Namen und die Variablen aller direkt in der Header-Datei verwendeten Dateien zugewiesen bekommt. Für die Objekt-Dateien sind dann nur die Variablen aller direkt in der Header-Datei verwendeten Dateien aufgeführt. Durch die Verwendung von Make-Variablen anstatt der Dateinamen werden alle Abhängigkeiten mit wenig Schreibaufwand erfasst. makefile.loc Hier sind mittels Make-Variablen die Pfade und Namen für zu benutzende Bibliotheken aufgeführt. In anderen Makefiles kann dann durch die Make-Variablen darauf Bezug genommen ohne daß die konkreten Pfade bekannt sind. Dadurch sind eventuelle Anpassungen übersichtlich nur an einer Stelle notwendig. makefile Hier sind restlichen Einträge zu finden. Dabei werden die anderen Makefiles mittels include-Anweisung eingelesen. In jedem Makefile gibt es die Regeln 'all', 'clean' und 'cleanall'. Einstellungen ------------- Besondere Symbole für eine bedingte Übersetzung werden allgemein in der Datei Genf/source/common/makefile.common festgelegt. Zur Zeit gibt es nur eine Einstellung: _test_ Beim Programmablauf werden im Shellfenster (xterm) ergänzende Ausgaben über aufgerufene Funktionen und Parameter gemacht. CC = [...] -D_test_ [...] Benutzte Programme ------------------ * Die Oberfläche ist mit dem Programm XDesigner erstellt. Das Programm XDesigner speichert die Oberfläche in Dateien mit der Endung ".xd", hier: Genf/source/genf/genf.xd und kann dann Quelltexte generieren: Genf/source/genf/GenfGUI.cc, Genf/source/genf/GenfGUI.hh und Genf/source/genf/genfstub.cc. Die Datei genfstub.cc wird selbst nur als Vorlage für Programmteile gebraucht, die dann in GenfControl.hh realisiert sind. * Das Login-Bild und die Architekturdiagramme sind mit dem Programm IslandDraw gezeichnet worden. Die Dateien werden unter der Endung ".id" abgelegt. Anhang ------ Die Architektur des Programmes ist in den Dateien Genf/doc/GrobArchitektur, Genf/doc/FeinArchitektur, Genf/doc/GUIArchitektur und Genf/doc/XSupportArchitektur als Bild gespeichert.