OLGA - Object Linking for GEM Applications Rev. 0.5 (08.03.1995)
================================================================

Was ist Object Linking?
-----------------------

Object Linking (OL) dient zur besseren (automatischen) Interaktion zwischen
verschiedenen Programmen. Wenn z.B. bei einem Vektorgrafikprogramm in einem
Dokument (Vektorgrafik) ein beliebiges Objekt (hier z.B. eine Rastergrafik)
dargestellt wird und dieses - eine Multitasking-Umgebung vorausgesetzt -
von einem anderen Programm (hier also ein Rastergrafikprogramm) gendert
wird, whrend beide Programme laufen, wrde die Rastergrafik nach der
nderung (d.h. dem Speichern) in der Vektorgrafik automatisch neu angezeigt.

Ein solches OL ist recht einfach zu bewerkstelligen, damit aber beliebige
Programme mit beliebigen Objekten kompatibel arbeiten knnen, wird ein
etwas umfangreicheres Protokoll bentigt. Das OLGA-Protokoll leistet das
gewnschte OL und hat den Vorteil, fr sptere Erweiterungen (DDE, Object
Embedding) offen zu sein. OLGA ist dokumentenzentriert, d.h. das Protokoll
ist dafr vorbereitet, da eine Applikation mehrere Dokumente (evtl. sogar
mit komplett verschiedenen Datentypen) verwaltet.

Zur Verwaltung des OL wird ein OLGA-Manager (Manager) eingesetzt. Die Kommu-
nikation bzgl. OL zwischen den Applikationen wird komplett ber diesen Manager
abgewickelt. Es kann immer nur einen Manager im System geben!

Drei wichtige Begriffe sind noch zu klren: Ein OLGA-Client (Client) ist
eine Applikation, mit der Dokumente bearbeitet werden knnen, in denen Objekte
anderer Applikationen benutzt werden. Ein OLGA-Server (Server) ist eine
Applikation, die die Bearbeitung dieser Objekte ermglicht. Und wer das jetzt
zu schnell durchgelesen hat und meint, da beides identisch ist, hat nur ein
kleines bichen Unrecht: In der Tat ist es ohne Probleme mglich, da eine
Applikation gleichzeitig Server und Client ist - in den meisten Fllen ist
dies sogar sehr sinnvoll. Die Programmierung eines Clients ist allerdings
aufwendiger, das Erweitern einer bestehenden Applikation zu einem Server
sollte dagegen nur wenige Minuten in Anspruch nehmen!
Die Verbindung zwischen Client und Server wird mit sog. Links hergestellt.
Ein Link ist eine Referenz des Clients auf ein Objekt. Diese Referenz (bei
OLGA ist das nur ein Dateiname mit absolutem Pfad) mu vom Client im Dokument
gespeichert werden. Wenn nun ein Server ein Objekt ndert, auf das ein Link
besteht, wird der Client davon unterrichtet und kann das genderte Objekt
neu darstellen.

Das Protokoll ist im Moment noch sehr einfach gehalten, damit mglichst viele
Applikationen OLGA untersttzen knnen. Sptere Erweiterungen (Embedding,
In-Place-Activation) drften dagegen etwas aufwendiger werden. Trotzdem ist
knnen mit dem Protokoll schon jetzt erstaunliche Ergebnisse erzielt werden.

Und jetzt bitte nicht gleich von dem langen Text abschrecken lassen, das meiste
sind nur Informations- bzw. Besttigungsmessages, die fr das einfache Funktio-
nieren des Protokolls gar nicht ausgewertet werden mssen.



Das OLGA-Protokoll...
=====================

...fr Server und Client
------------------------

Beim Programmstart sucht jede Applikation, die OLGA benutzen mchte, mit
appl_find nach "OLGA    ". Schlgt die Suche fehl, sollte noch die Environment-
Variable OLGAMANAGER ausgewertet werden, die den Namen des OLGA-Managers enthlt
(z.B. "OLGAMANAGER=MYSHELL"). Damit wre es dann auch mglich, da OLGA in einen
Desktop integriert wird. Wenn auch die letzte Methode fehlschlgt, knnen
Accessories (und nur die!) unter Singletask(!)-TOSsen noch versuchen, der
Hauptapplikation (apID=0) die OLGA_INIT-Message zu schicken.
Ist ein OLGA-Manager vorhanden, schickt die Applikation ihm folgende Message,
damit der Manager interne Datenstrukturen initialisieren kann (wichtig fr
zuknftige Erweiterungen!):

OLGA_INIT
[0] $1236 (4662)
[1] apID
[2] 0
[3] Bitmap, ob die Applikation Client und/oder Server ist (OL_SERVER, OL_CLIENT)
[4] max. von der Applikation verstandene Stufe des Protokolls (z.Z. immer 0)
[5]
 +  Pointer auf den Namen der Applikation (oder nil)
[6]
[7] maschinenlesbarer XAcc-Programmtyp bzw. 0, wenn der Typ nicht in folgender
    Liste zu finden ist:

	    "WP" = Textverarbeitung
	    "DP" = DTP
	    "ED" = Texteditor
	    "DB" = Datenbank
	    "SS" = Tabellenkalkulation
	    "RG" = Rastergrafikprogramm
	    "VG" = Vektorgrafikprogramm
	    "GG" = allgemeines Grafikprogramm
	    "MU" = Musikanwendung
	    "CD" = CAD
	    "DC" = Datenkommunikation
	    "DT" = Desktop
	    "PE" = Programmierumgebung

OL_SERVER = $0001   Applikation ist OL-Server
OL_CLIENT = $0002   Applikation ist OL-Client
OL_PIPES  = $1000   Applikation mchte nicht ber Pointer, sondern ber
                    MTOS-D&D-Pipes kommunizieren; der Manager meldet dann,
                    ob er diese Kommunikation beherrscht bzw. ob sie auf dem
                    aktuellen System mglich ist (s.u.); das Verfahren wird
                    z.Z. noch nicht untersttzt, eine genauere Definition
                    folgt spter


Der OLGA-Manager verschickt daraufhin an die Applikation eine Besttigung,
spter knnen hier dann bestimmte Konfigurationsdaten angezeigt werden.
Wichtig: Applikationen sollten den OL-Mechanismus erst verwenden, nachdem
sie folgende Message erhalten haben und diese keinen Fehler signalisiert hat
(fr Applikationen, die whrend der Startphase Dokumente ffnen, kann es
sinnvoll sein, auch ohne empfangene OLGA_INIT-Message die ntigen OLGA-
Messages zu verschicken, nur sollten bei der Applikation keine Fehl-
funktionen auftreten, falls sich der Manager doch nicht meldet).

OLGA_INIT
[0] $1236 (4662)
[1] apID
[2] 0
[3] Bitmap, OL_MANAGER gesetzt
[4] Stufe des verwendeten (!) Protokolls (z.Z. immer 0)
[5]
 +  Pointer auf den Namen des Managers (oder nil)
[6]
[7] 0=Fehler, sonst: OL-Mechanismus verfgbar

OL_PIPES   = $1000   Manager verwendet zur Kommunikation MTOS-D&D-Pipes
                     (nur nach Anforderung, s.o., wird z.Z. noch nicht
                     untersttzt und ist daher nie gesetzt!)
OL_START   = $2000   Manager kann OLGA_START ausfhren
OL_MANAGER = $4000   Applikation ist der OLGA-Manager


Beim Beenden eines Programms wird dem OLGA-Manager folgende Message geschickt
(wenn sich ein Client abmeldet, werden automatisch alle zugehrigen Links und
Documents gelscht):

OLGA_EXIT
[0] $1237 (4663)
[1] apID
[2] 0
[3] 0
[4] 0
[5] 0
[6] 0
[7] 0



...aus der Sicht des Servers
----------------------------

Wenn der Server irgend eine Datei abgespeichert hat, wird an den OLGA-Manager
folgende Message geschickt: (Die Gro-/Kleinschreibung des Dateinamens wird
im Moment ignoriert, damit das Linking nicht an unterschiedlichen Benutzer-
eingaben scheitert; auf erweiterten Filesystemen wird das spter allerdings
nicht mehr so sein.)

OLGA_UPDATE
[0] $1238 (4664)
[1] apID
[2] 0
[3]
 +  Pointer auf den kompletten Dateinamen incl. (absolutem!) Pfad
[4]
[5] 0
[6] 0
[7] 0


Als Antwort erhlt der Server folgende Message, worauf er z.B. allozierten
Speicherplatz fr den Dateinamen wieder freigeben kann:

OLGA_ACK
[0] $1239 (4665)
[1] apID
[2] 0
[3]
 +  exakt dieselben Wert von OLGA_UPDATE
[4]
[5] 0
[6] 0
[7] OLGA_UPDATE


Wenn der Benutzer eine Datei im Server umbenennt (oder verschiebt!), schickt
der Server dem Manager die OLGA_RENAME-Message. Es liegt im Ermessen des
Servers, ob er nach "Speichern als..." eine solche Message verschickt (das
hngt z.B. auch davon ab, ob der Server selbst die neue Pfadangabe bzw. den
neuen Dateinamen fr das bestehende Dokument bernimmt); nach Mglichkeit
sollten Links aber immer nur fr Dateien auf nicht wechselbaren Medien
bestehen (A: und B: sind also denkbar schlechte Kandidaten). Wenn zustzlich
der Dateiinhalt verndert wurde, mu auerdem noch eine OLGA_UPDATE-Message
verschickt werden!

OLGA_RENAME
[0] $123a (4666)
[1] apID
[2] 0
[3]
 +  Pointer auf den alten Dateinamen incl. absolutem Pfad
[4]
[5]
 +  Pointer auf den neuen Dateinamen incl. absolutem Pfad
[6]
[7] 0


Als Antwort erhlt der Server wiederum eine Message, die er z.B. zum Freigeben
des alten Speicherplatzes verwenden kann. Diese Besttigung bedeutet allerdings
nur, da der Manager das Umbenennen weitergemeldet hat, wenn ein Client nicht
darauf reagiert, ist der entsprechende Link dann "tot".

OLGA_ACK
[0] $1239 (4665)
[1] apID
[2] 0
[3]
 +  exakt dieselben Wert von OLGA_RENAME
[4]
[5]
 +  exakt dieselben Wert von OLGA_RENAME
[6]
[7] OLGA_RENAME


Sollte der Server eine Datei lschen (oder anderweitig fr den Client un-
brauchbar machen), mu er dies dem Manager mit folgender Message mitteilen.
Der Manager verstndigt dann alle Clients, die einen Link auf diese Datei
gesetzt hatten.

OLGA_BREAKLINK
[0] $1244 (4676)
[1] apID
[2] 0
[3]
 +  Pointer auf den Dateinamen incl. absolutem Pfad
[4]
[5] 0
[6] 0
[7] 0


Auch hierauf verschickt der Manager eine Antwort an den Server:

OLGA_ACK
[0] $1239 (4665)
[1] apID
[2] 0
[3]
 +  exakt dieselben Wert von OLGA_BREAKLINK
[4]
[5] 0
[6] 0
[7] OLGA_BREAKLINK



...aus der Sicht des Clients
----------------------------

Wenn ein OLGA-Client ein Dokument ffnet (egal ob schon bestehend oder neu),
kann (!) dem OLGA-Manager folgende Message geschickt werden. Sie dient z.Z.
nur zu Informationszwecken, die bentigten internen Strukturen werden vom
Manager ansonsten beim Empfangen der ersten OLGA_LINK-Message angelegt.
Die Gruppenkennung sollte allerdings trotzdem (wenn auch nur Client-intern)
festgelegt werden, da sie fr die Links bentigt wird.

OLGA_OPENDOC
[0] $123b (4667)
[1] apID
[2] 0
[3] Pointer auf den Dateinamen des Dokuments (der Manager mu darauf zugreifen
 +  knnen, bis er OLGA_CLOSEDOC empfangen hat!); kann auch auf z.B. "Ohne Namen"
[4] zeigen, wenn noch kein Pfad existiert; alternativ bergibt man einfach nil (!)
[5] Gruppenkennung (eine innerhalb des Clients eindeutige, vom Client frei whl-
    bare Zahl, mit der die Links innerhalb des Clients den Dokumenten zugeordnet
    werden knnen)
[6] 0
[7] 0


Schliet ein Client ein Dokument, das Links enthlt, sollte dem OLGA-Manager
folgende Message geschickt werden, die alle Links mit der entsprechenden
Gruppenkennung lscht. Das kann zwar auch mit einzelnen OLGA_UNLINK-Aufrufen
geschehen, aber so knnen Manager-interne Strukturen einfacher freigegeben
werden (auerdem ist es einfacher fr den Programmierer :-). Darf beim Programm-
ende _nicht_ verwendet werden, da OLGA_EXIT alle Documents lscht.

OLGA_CLOSEDOC
[0] $123c (4668)
[1] apID
[2] 0
[3] 0
[4] 0
[5] Gruppenkennung des Dokuments
[6] 0
[7] 0


Als Antwort erhlt der Client folgende Message:

OLGA_ACK
[0] $1239 (4665)
[1] apID
[2] 0
[3] 0
[4] 0
[5] Gruppenkennung des Dokuments
[6] 0
[7] OLGA_CLOSEDOC


Mit der folgendes Message teilt ein Client dem Manager mit, da eine Datei in
eines seiner Dokumente eingebunden wurde - allerdings in der Form, da nur eine
Referenz (hier der Dateiname mit absolutem Pfad) gespeichert wird. Wenn diese
Datei von einem OLGA-Server verndert wird (oder eine AV_PATH_UPDATE-Message
von einem Programm empfangen wird, das kein Server ist), erhlt der Client
dann eine OLGA_UPDATED Message.

OLGA_LINK
[0] $123d (4669)
[1] apID
[2] 0
[3]
 +  Pointer auf den Dateinamen, der berwacht werden soll (incl. absolutem Pfad)
[4]
[5] Gruppenkennung des Dokuments (s. OLGA_OPENDOC)
[6] 0
[7] 0


Als Besttigung verschickt der Manager folgende Message:

OLGA_ACK
[0] $1239 (4665)
[1] apID
[2] 0
[3]
 +  exakt dieselben Wert von OLGA_LINK
[4]
[5] Gruppenkennung des Dokuments
[6] 0=Fehler, sonst: Link eingerichtet
[7] OLGA_LINK


Soll die berwachung fr eine Datei beendet werden, mu der Client dem Manager
folgende Message schicken. Beim Schlieen eines Dokuments sollte stattdessen
allerdings OLGA_CLOSEDOC verwendet werden, beim Beenden der Client-Applikation
werden die Links mit OLGA_EXIT automatisch gelscht.

OLGA_UNLINK
[0] $123e (4670)
[1] apID
[2] 0
[3] Pointer auf den Dateinamen (incl. absolutem Pfad), der nicht mehr
 +  berwacht werden soll (mu exakt mit der Zeichenkette aus OLGA_LINK
[4] bereinstimmen)
[5] Gruppenkennung des Dokuments
[6] 0
[7] 0


Als Besttigung erhlt der Client folgende Message:

OLGA_ACK
[0] $1239 (4665)
[1] apID
[2] 0
[3]
 +  exakt dieselben Wert von OLGA_UNLINK
[4]
[5] Gruppenkennung des Dokuments
[6] 0=Fehler, sonst: Link entfernt
[7] OLGA_UNLINK


Und mit der nchsten Message werden dem Client nderungen an einer Datei
vom Manager mitgeteilt! Wenn der Client also eine solche Message empfngt,
sollte das zugehrige Dokument neu angezeigt werden. Der Pointer ist solange
gltig, wie der Link besteht.

OLGA_UPDATED
[0] $123f (4671)
[1] apID
[2] 0
[3]
 +  Pointer auf den Dateinamen (incl. absolutem Pfad) der Datei, die verndert wurde
[4]
[5] 0
[6] 0
[7] Gruppenkennung des Dokuments


Wenn ein Server eine Datei umbenannt oder verschoben hat, erhlt der
Client folgende Message. Sie dient nur dazu, da der Client seine interne
Referenz aktualisiert, d.h. das Dokument mu nicht neu gezeichnet werden!
Der Pointer auf den neuen Namen ist solange gltig, wie der Link besteht.

OLGA_RENAMELINK
[0] $1240 (4672)
[1] apID
[2] 0
[3]
 +  Pointer auf den alten Dateinamen incl. absolutem Pfad
[4]
[5]
 +  Pointer auf den neuen Dateinamen incl. absolutem Pfad
[6]
[7] Gruppenkennung des Dokuments


Als Antwort auf OLGA_RENAMELINK mu der Client an den Manager folgende
Message schicken, damit letzterer seine Referenz aktualisiert und un-
ntigen Speicherplatz freigibt (der Client mu dazu nur die Message-
nummer austauschen). Unterbleibt diese Antwort, ist der entsprechende
Link "tot", kann also nicht mehr berwacht werden (da ja im Manager
dann noch der alte Name gespeichert ist).

OLGA_LINKRENAMED
[0] $1241 (4673)
[1] apID
[2] 0
[3]
 +  Pointer auf den alten Dateinamen incl. absolutem Pfad
[4]
[5]
 +  Pointer auf den neuen Dateinamen incl. absolutem Pfad
[6]
[7] Gruppenkennung des Dokuments


Die beiden folgenden Messages werden noch genauer definiert, damit der
OL-Mechanismus auch unter SingleTOS eingesetzt werden kann. Sie dienen im
wesentlichen dazu, das Versenden von OLGA_UPDATED-Messages durch das Manager-
Accessory solange zu unterdrcken, bis die Client-Applikation, die ja nach
dem Start eines Servers nicht mehr vorhanden ist, wieder aktiv ist.

OLGA_BLOCK
[0] $1242 (4674)
OLGA_UNBLOCK
[0] $1243 (4675)


Wenn eine Datei dem Client pltzlich nicht mehr zur Verfgung steht
(z.B. weil sie gelscht wurde), wird dies vom Manager mit folgender
Message mitgeteilt. Der Client kann daraufhin z.B. den Benutzer
informieren oder per Fileselectbox eine andere Datei auswhlen
lassen.

OLGA_LINKBROKEN
[0] $1245 (4677)
[1] apID
[2] 0
[3]
 +  Pointer auf den Dateinamen incl. absolutem Pfad
[4]
[5] Gruppenkennung des Dokuments
[6] 0
[7] 0


Auerdem sollte der Client den jetzt ungltigen Link mit der
normalen Unlink-Message auflsen:

OLGA_UNLINK
[0] $123e (4670)
[1] apID
[2] 0
[3] Pointer auf den Dateinamen (incl. absolutem Pfad), der nicht mehr
 +  berwacht werden kann (es knnen auch exakt die Werte aus
[4] OLGA_LINKBROKEN bergeben werden!)
[5] Gruppenkennung des Dokuments
[6] 0
[7] 0


Fr Clients bietet der Manager eine einfache Mglichkeit, passende
Server nachzustarten bzw. aufzurufen. Dazu wird (bei OLS_TYPE und
OLS_EXTENSION) die Datei OLGA.INF ausgewertet. Zunchst wird der
darin gefundene Server im Speicher gesucht und bei Erfolg mit
VA_START (s. Gemini-Doku) aufgerufen. Ansonsten wird das Programm
unter MultiTOS bzw. MagiC mit shel_write nachgestartet.

OLGA_START
[0] $1246 (4678)
[1] apID
[2] 0
[3] eine der OLS-Konstanten (s.u.)
[4]
 +  Angaben, welches Programm / welcher Programmtyp gestartet werden soll
[5] (abhngig von [3], s.u.)
[6]
 +  Pointer auf Kommandozeile (i.A. nur die zu ladende Datei) oder nil
[7]

OLS_TYPE      = $0001  [4]=0, in [5] steht ein XAcc-Programmtyp
OLS_EXTENSION = $0002  in [4]+[5] steht eine Extension (z.B. ".GEM")
OLS_NAME      = $0003  in [4]+[5] steht ein Pointer auf den absoluten
                       Dateinamen der zu startenden Applikation


Als Besttigung erhlt man folgende Message:

OLGA_ACK
[0] $1239 (4665)
[1] apID
[2] 0
[3] OLS-Konstante von OLGA_START
[4]
 +  exakt dieselben Wert von OLGA_START
[5]
[6] 0=Fehler, sonst: Server gestartet
[7] OLGA_START


Um die Kommandozeile leichter freigeben zu knnen, erhlt man auerdem
noch eine zweite Message (wenn fr die Kommandozeile nicht nil bergeben
wurde).

OLGA_ACK
[0] $1239 (4665)
[1] apID
[2] 0
[3] 0 (!)
[4]
 +  exakt dieselben Wert von OLGA_START [6]+[7]
[5]
[6] 0
[7] OLGA_START



Down to the minimum
===================

Im folgenden sind noch einmal die Messages aufgelistet, die Server bzw.
Client minimal untersttzen mssen, um eine korrekte Protokollbehandlung
zu gewhrleisten.

Server
------

- OLGA_INIT verschicken und empfangen
- OLGA_EXIT verschicken

Client
------

- OLGA_INIT verschicken und empfangen
- OLGA_EXIT verschicken
- auf OLGA_RENAMELINK mit OLGA_LINKRENAMED antworten
- auf OLGA_LINKBROKEN mit OLGA_UNLINK antworten



Abschlieende Hinweise
----------------------

Alle Zeichenketten sind nullterminiert. Wenn Mxalloc vorhanden ist und die
MemoryProtection-Bits gesetzt werden knnen, mssen die Pointer auf global
gesetzt werden!!! Ich wei, da die bergabe von Pointern in AES-Messages
nicht das absolut Beste ist, es ist aber sicher sehr einfach zu implemen-
tieren und funktioniert bei anderen Protokollen in der Praxis auch ohne
Probleme. Wer ganz sicher gehen will, kann spter mit OL_PIPES auf MTOS-
D&D-Pipes umschalten (pro Applikation, der Manager kmmert sich dann um die
korrekte Kommunikation).

Wichtig: Dieser Mechanismus ersetzt nicht die AV_PATH_UPDATE-, SH_WDRAW-
oder SC_CHANGED-Message!

In der Maus KA liegt das Archiv OLGA.ZIP mit einem OLGA-Manager.
Im Moment ist der frhere Test-Manager (mit der Klartextanzeige der
Links) nicht mehr verfgbar, es gibt nur noch den speicheroptimierten
Manager (bei Gelegenheit passe ich den Test-Manager aber noch an).
Die OLGA-Disribution ist FREEWARE!


Rev 0.5 (01.03.95)
- OL_START, OLGA_START
- OL_PIPES
- beim Programmende drfen OLGA_CLOSEDOC, OLGA_UNLINK nicht verwendet
  werden, OLGA_EXIT kmmert sich um alles
- OLGA_ACK wird nach OLGA_CLOSEDOC verschickt
- Applikationen sollten bei OLGA_INIT einen XAcc-Programmtyp angeben
Rev 0.4 (07.01.95)
- OLGA_BREAKLINK, OLGA_LINKBROKEN sind neu
Rev 0.3 (04.01.95)
- OLGA_RENAMED heit nun OLGA_RENAMELINK
- OLGA_LINKRENAMED ist dazugekommen, dadurch haben sich die Nummern von
  OLGA_BLOCK/OLGA_UNBLOCK verschoben
Rev 0.2
- komplette berarbeitung gegenber dem GOLEM-Vorschlag



Alle Angaben ohne Gewhr, nderungen vorbehalten.

Thomas Much, Gerwigstrae 46, 76131 Karlsruhe
Tel. (0721) 62 28 41, EMail: Thomas Much @ KA2
