OLGA- Object Linking for GEM Applications
Was ist Object Linking?
Object Linking bezeichnet das, was es in der ach so schönen neuen Windows-Welt schon so lange gibt: Die Kommunikation zwischen zwei parallel laufenden Applikationen, die dasselbe Dokument (oder Teile davon) bearbeiten.
Und weil Object Linking ausnahmsweise eine wirklich gute Sache ist, wurde ein passendes Protokoll auch für unsere liebgewonnenen ATARIs entwickelt.
OLGA wurde für folgende Einsatzbereiche konzipiert: In einem Vektorgrafikprogramm beispielsweise kann eine Grafik dargestellt werden, die auch eine Rastergrafik (Bitmap) enthält. Wenn der Benutzer nun diese Bitmap bearbeiten möchte, kann das Vektorgrafikprogramm eventuell nicht die passenden Routinen dazu bereitstellen. Es kann aber ein Rastergrafikprogramm aufrufen bzw. nachladen und den Benutzer die Bitmap dort bearbeiten lassen. Nach dem Speichern der veränderten Bitmap wird die Grafik im Vektorgrafikprogramm dann automatisch aktualisiert - das nennt man Object Linking, mit der Bitmap als Objekt, dem Vektorgrafikprogramm als Client (Dienstnehmer, es benutzt die Dienste des Rastergrafikprogramms) und dem Rastergrafikprogramm als Server (Dienstgeber, es stellt anderen Programmen seine Dienste zur Verfügung). Die Verknüpfung (Link) zum Objekt wird über den Dateinamen der Bitmap hergestellt.
Ein solches Object Linking ist zwischen zwei bekannten Applikationen prinzipiell recht einfach zu bewerkstelligen. Damit aber beliebige Programme mit beliebigen Objekten kompatibel arbeiten können, wird ein etwas umfangreicheres Protokoll benötigt. Zur Verwaltung der wesentlichen Protokollaufgaben wird ein Manager eingesetzt, ein kleines Programm oder Accessory, das die Verknüpfungen (Links) zwischen Applikationen und Dateien speichert. Außerdem wird dieser OLGA-Manager dafür eingesetzt, passende Programme zur Bearbeitung von Dateien nachzuladen. OLGA ist dokumentenzentriert, d.h. das Protokoll ist dafür vorbereitet, dass eine Applikation mehrere Dokumente (auch mit komplett verschiedenen Datentypen) verwaltet.
Wie wird eine Applikation OLGA-tauglich?
Zunächst muss der Programmierer entscheiden, ob die Applikation ein OLGA-Server oder -Client sein soll. Eine Applikation, die Dateien speichert, kann sehr einfach zu einem OLGAServer gemacht werden. Und wenn eine Applikation fremde Dateien in eigene Dokumente einbindet (oder auch nur fremde Dateien verwaltet), bietet sie sich damit als OLGA-Client an. Oft ist es auch sinnvoll, dass eine Applikation sowohl Server als auch Client ist (Beispiel: ArtWorx). Die Initialisierung ist für beide Applikationstypen gleich.
Nachfolgend ist eine brauchbare Minimalversion des Protokolls vorgestellt, d.h. man kann seine Applikationen damit an OLGA anpassen und bereits viele Features nutzen. Wer alle Feinheiten ausreizen möchte, sollte sich allerdings das komplette OLGA-Archiv besorgen, das neben der ausführlichen Protokollbeschreibung auch eine Debugversion des Managers enthält. Die Verwendung des OLGA-Protokolls und die Weitergabe des Managers ist übrigens auch für kommerzielle Software kostenlos.
Wenn im weiteren Text von Zeichenketten die Rede ist, sind damit nullterminierte C-Strings gemeint, die von den meisten Programmiersprachen zur Verfügung gestellt werden. Die Zeichenketten müssen in global verfügbarem Speicher abgelegt sein, der mit Mxalloc() angefordert werden kann. apID bezeichnet die AES-ID der Applikation, manID die des OLGA-Managers. Mit _reserviert" gekennzeichnete Einträge brauchen beim derzeit verfügbaren OLGA-Manager nicht beachtet zu werden, sie sind in der OLGA-Dokumentation genauer beschrieben.
Initialisierung
Das OLGA-Protokoll besteht im wesentlichen aus der Kommunikation mit dem OLGA-Manager. Dazu muss man die AES-ID des Managers kennen, die wie folgt ermittelt wird:
- Wenn appl_find("OLGA ") erfolgreich ist, hat man den Manager
schon gefunden.
- Ansonsten wird nun die Environmentvariable OLGAMANAGER mit getenv()
ausgewertet. Dort kann ein kompletter Zugriffspfad stehen! Zunächst
extrahiert man aus diesem Pfad einen Programmnamen für appl_find()
und geht entsprechend wie unter a) vor.
Konnte auch dieser Name nicht gefunden werden, startet man das
Programm, das von OLGAMANAGER bezeichnet wird, mit shel_write()
nach.
- Wenn das bisherige nicht zum Erfolg geführt hat, gibt es offen-
sichtlich keinen OLGA-Manager, man muss nun nach einem OLE-Manager
suchen. Dazu macht man - analog zu a) - ein appl_find("OLEMANGR").
- Konnte auch dieses Programm nicht gefunden werden, wertet man nun
noch die Environmentvariable OLEMANAGER wie unter b) aus.
Hat man einen Manager gefunden, schickt man ihm mit appl_write() folgende Message:
OLE_INIT
(App -> Manager)
msg[0] $4950 (18768)
msg[1] apID
msg[2] 0
msg[3] Applikation ist Server (1), Client (2) oder beides (3)
msg[4] 0
msg[5] 0
msg[6] 0
msg[7] maschinenlesbarer XAcc-Programmtyp (oder 0):
"WP" ($5750) = Textverarbeitung
"DP" ($4450) = DTP
"ED" ($4544) = Texteditor
"DB" ($4442) = Datenbank
"SS" ($5353) = Tabellenkalkulation
"RG" ($5247) = Rastergrafikprogramm
"VG" ($5647) = Vektorgrafikprogramm
"GG" ($4747) = allgemeines Grafikprogramm
"MU" ($4d55) = Musikanwendung
"CD" ($4344) = CAD
"DC" ($4443) = Datenkommunikation
"DT" ($4454) = Desktop
"PE" ($5045) = Programmierumgebung
Der OLGA-Manager verschickt als Bestätigung die OLGA_INIT-Message. Applikationen sollten den OLGA-Mechanismus erst verwenden, nachdem sie folgende Message erhalten haben und diese keinen Fehler signalisiert hat. Für Applikationen, die während der Startphase Dokumente öffnen, kann es allerdings sinnvoll sein, auch ohne empfangene OLGA_INIT-Message die nötigen OLGA-Messages zu verschicken, nur sollten bei einer solchen Applikation keine Fehlfunktionen auftreten, falls sich der Manager doch nicht meldet.
OLGA_INIT
(Manager -> App)
msg[0] $1236 (4662)
msg[1] manID
msg[2] 0
msg[3] reserviert
msg[4] reserviert
msg[5] 0
msg[6] 0
msg[7] 0=Fehler, sonst: OLGA-Manager korrekt initialisiert
Beim Programmende wird dem Manager folgende Message geschickt. Wenn sich ein OLGA-Client abmeldet, werden automatisch alle zugehörigen Links und Documents gelöscht.
Außerdem verschickt der Manager diese Nachricht an alle angemeldeten Applikationen, wenn er vorzeitig beendet wird.
OLE_EXIT
(App -> Manager, Manager -> App)
msg[0] $4951 (18769)
msg[1] apID bzw. manID
msg[2] 0
msg[3] 0
msg[4] 0
msg[5] 0
msg[6] 0
msg[7] 0
Wenn ein Manager nachgestartet wird, verschickt er an alle erreichbaren Applikationen folgende Message:
OLE_NEW
(Manager -> App)
msg[0] $4952 (18770)
msg[1] manID
msg[2] 0
msg[3] reserviert
msg[4] reserviert
msg[5] reserviert
msg[6] reserviert
msg[7] reserviert
Eine OLGA-fähige Applikation muss daraufhin manID als AES-ID des OLGA-Managers übernehmen und diesem Manager eine OLE_INIT-Message senden. Bei der Programmierung muss man beachten, dass OLE_NEW, OLE_INIT und OLGA_INIT beliebig oft verschickt werden können, da sie auch zur Aktualisierung der Manager- bzw. Applikationsdaten benutzt werden.
Server-Messages
Bei einem OLGA-Server ist das komplizierteste die oben beschriebene OLE-Initialisierung. Damit er nun noch zu einem "echten" Server wird, muss nur noch nach dem Abspeichern einer Datei folgende Update-Message an den Manager geschickt werden (abgesehen von temporären Dateien und eigenen Konfigurationsdateien). Außerdem muss ein OLGA-Server die VA_START-Message (siehe Gemini- bzw. Thing-Dokumentation) unterstützen. Das war es dann auch schon!
OLGA_UPDATE
(Server -> Manager)
msg[0] $1238 (4664)
msg[1] apID
msg[2] 0
msg[3]
+ Pointer auf den kompletten Dateinamen inkl. (absolutem!) Pfad
msg[4]
msg[5] 0
msg[6] 0
msg[7] 0
Als Antwort erhält der Server folgende Message, worauf er z.B. allozierten Speicherplatz für den Dateinamen wieder freigeben kann.
OLGA_ACK
(Manager -> Server)
msg[0] $1239 (4665)
msg[1] manID
msg[2] 0
msg[3]
+ exakt dieselben Werte von OLGA_UPDATE
msg[4]
msg[5] 0
msg[6] 0
msg[7] OLGA_UPDATE
Client-Messages
Wenn ein OLGA-Client ein Dokument öffnet (z.B. mit "Datei - Neu" oder "Datei - öffnen..."), muss dem OLGA-Manager folgende Message geschickt werden. Die Gruppenkennung bezeichnet dabei eine beliebige, aber innerhalb des Clients eindeutige Zahl, mit der der Client und der Server das Dokument eindeutig identifizieren können - schließlich ist es möglich, dass eine Datei innerhalb eines Clients mehrfach, nur in verschiedenen Dokumenten, eingebunden ist. Falls ein Client nur ein Dokument gleichzeitig bearbeiten kann (IdeaList hat z.B. immer nur eine Datei geladen), kann man hier eine Null übergeben.
OLGA_OPENDOC
(Client -> Manager)
msg[0] $123b (4667)
msg[1] apID
msg[2] 0
msg[3] 0
msg[4] 0
msg[5] Gruppenkennung
msg[6] 0
msg[7] 0
Schließt ein Client ein Dokument, wird dem Manager folgende Message geschickt, die automatisch alle Links mit der entsprechenden Gruppenkennung gelöscht. Wichtig: Beim Programmende darf man diese Message nicht verschicken, da OLE_EXIT alle Gruppenkennungen freigibt!
OLGA_CLOSEDOC
(Client -> Manager)
msg[0] $123c (4668)
msg[1] apID
msg[2] 0
msg[3] 0
msg[4] 0
msg[5] Gruppenkennung
msg[6] 0
msg[7] 0
Das eigentliche "Object Linking" geschieht mit folgender Message. Wenn der Client eine fremde Datei in eines seiner Dokumente einbettet, muss er sich intern den Dateinamen mit absolutem Pfad merken und mit OLGA_LINK einen Link darauf setzen. Wird die Datei von einem OLGA-Server verändert, erhält der Client dann eine OLGA_UPDATED-Message.
Möchte der Client nicht nur ein Linking, sondern auch ein Embedding realisieren, muss er nicht nur den Dateinamen der eingebetteten Datei im Dokument speichern, sondern auch die gesamte Datei. Das bläht die Dokumente zwar ziemlich auf, hat aber den Vorteil, dass man solche Dateien sehr einfach weitergeben kann, da alle Daten im Dokument gespeichert sind.
Wird ein Dokument geladen, das eingebettete Dateien enthält, muss der Client nach dem Laden und öffnen des Dokuments (siehe OLGA_OPENDOC) auf alle eingebetteten Objekte, die ja mit ihrem Dateinamen gespeichert wurden, einen Link auf die zugehörige Datei setzen. Wird ein Dokument auf einem fremden System geöffnet, bei dem die eingebetteten Dateien nicht auf Platte vorhanden sind, kann ein Linking-Client diese Dateien auch nicht anzeigen - dem Anwender sollte dies z.B. durch ein leeres Rechteck o.ä. im Dokument angezeigt werden. Ein Embedding-Client hat alle notwendigen Daten im Dokument gespeichert und kann z.B. die Grafiken (allgemeiner: Objekte) trotzdem anzeigen.
Beim Doppelklick auf ein eingebettetes Objekt sollte die entsprechende Datei per OLGA_START (s.u.) geöffnet werden, damit der Anwender diese Datei im zugehörigen Server bearbeiten kann. Ein Embedding-Client sollte vorher noch prüfen, ob die zu öffnende Datei überhaupt vorhanden ist. Im negativen Fall sollte er die im Dokument gespeicherte Datei auf Platte ablegen (unter einem automatisch generierten temporären Namen), den alten Link mit OLGA_UNLINK löschen und einen neuen Link auf die temporäre Datei setzen.
OLGA_LINK
(Client -> Manager)
msg[0] $123d (4669)
msg[1] apID
msg[2] 0
msg[3]
+ Pointer auf den Dateinamen, der überwacht werden soll (inkl.
absolutem Pfad)
msg[4]
msg[5] Gruppenkennung (siehe OLGA_OPENDOC)
msg[6] 0
msg[7] 0
Als Bestätigung verschickt der Manager folgende Message:
OLGA_ACK
(Manager -> Client)
msg[0] $1239 (4665)
msg[1] manID
msg[2] 0
msg[3]
+ exakt dieselben Werte von OLGA_LINK
msg[4]
msg[5] Gruppenkennung
msg[6] 0=Fehler, sonst: Link eingerichtet
msg[7] OLGA_LINK
Soll die Überwachung für eine Datei beendet werden, muss der Client dem Manager folgende Message schicken. Beim Schließen eines Dokuments sollte stattdessen allerdings OLGA_CLOSEDOC verwendet werden, und beim Beenden der Client-Applikation werden die Links mit OLE_EXIT automatisch gelöscht.
OLGA_UNLINK
(Client -> Manager)
msg[0] $123e (4670)
msg[1] apID
msg[2] 0
msg[3] Pointer auf den Dateinamen (inkl. absolutem Pfad), der nicht mehr
+ überwacht werden soll (muss exakt mit der Zeichenkette aus OLGA_LINK
msg[4] übereinstimmen)
msg[5] Gruppenkennung
msg[6] 0
msg[7] 0
Als Bestätigung erhält der Client folgende Message:
OLGA_ACK
(Manager -> Client)
msg[0] $1239 (4665)
msg[1] manID
msg[2] 0
msg[3]
+ exakt dieselben Wert von OLGA_UNLINK
msg[4]
msg[5] Gruppenkennung
msg[6] 0=Fehler, sonst: Link entfernt
msg[7] OLGA_UNLINK
Mit der nächsten Message wird ein Client darüber informiert, dass eine seiner eingebetteten Dateien verändert wurde. Ein Linking-Client muss daraufhin die Datei neu anzeigen, ein Embedding-Client sollte die Datei zusätzlich komplett neu in sein Dokument laden.
OLGA_UPDATED
(Manager -> Client)
msg[0] $123f (4671)
msg[1] manID
msg[2] 0
msg[3]
+ Pointer auf den Dateinamen (inkl. absolutem Pfad) der Datei,
die verändert wurde
msg[4]
msg[5] reserviert
msg[6] reserviert
msg[7] Gruppenkennung
Wenn ein Server eine Datei umbenannt oder verschoben hat, erhält der Client folgende Message. Sie dient nur dazu, dass der Client seine interne Referenz aktualisiert, d.h. das Dokument muss nicht neu gezeichnet werden!
OLGA_RENAMELINK
(Manager -> Client)
msg[0] $1240 (4672)
msg[1] manID
msg[2] 0
msg[3]
+ Pointer auf den alten Dateinamen inkl. absolutem Pfad
msg[4]
msg[5]
+ Pointer auf den neuen Dateinamen inkl. absolutem Pfad
msg[6]
msg[7] Gruppenkennung
Als Antwort auf OLGA_RENAMELINK muss der Client an den Manager folgende Message schicken, damit letzterer seine Referenz aktualisiert und unnötigen Speicherplatz freigibt (der Client muss dazu einfach nur die Messagenummer austauschen und die erhaltene Message zurücksenden). Unterbleibt diese Antwort, ist der entsprechende Link "tot", kann also nicht mehr überwacht werden.
OLGA_LINKRENAMED
(Client -> Manager)
msg[0] $1241 (4673)
msg[1] apID
msg[2] 0
msg[3]
+ Pointer auf den alten Dateinamen inkl. absolutem Pfad
msg[4]
msg[5]
+ Pointer auf den neuen Dateinamen inkl. absolutem Pfad
msg[6]
msg[7] Gruppenkennung
Wenn eine Datei dem Client plötzlich nicht mehr zur Verfügung steht (weil sie z.B. vom Server gelöscht wurde), wird dies vom Manager mit folgender Message mitgeteilt. Der Client kann daraufhin z.B. den Benutzer informieren oder per Fileselectbox eine andere Datei auswählen lassen.
Außerdem muss der Client den jetzt ungültigen Link mit der normalen OLGA_UNLINK-Message auflösen, wobei als Pointer die Werte von OLGA_LINKBROKEN übergeben werden.
OLGA_LINKBROKEN
(Manager -> Client)
msg[0] $1245 (4677)
msg[1] manID
msg[2] 0
msg[3]
+ Pointer auf den Dateinamen inkl. absolutem Pfad
msg[4]
msg[5] Gruppenkennung
msg[6] 0
msg[7] 0
Für Clients bietet der Manager eine einfache Möglichkeit, passende Server nachzustarten bzw. aufzurufen. Dazu wird (bei OLS_TYPE und OLS_EXTENSION) die Datei OLGA.INF ausgewertet (siehe Beschreibung in der OLGA-Dokumentation). Zunächst wird der darin gefundene Server im Speicher gesucht und bei Erfolg mit VA_START (siehe Gemini- bzw. Thing-Dokumentation) aufgerufen. Ansonsten wird das Programm unter MultiTOS bzw. MagiC mit shel_write() nachgestartet.
OLGA_START
(Client -> Manager)
msg[0] $1246 (4678)
msg[1] apID
msg[2] 0
msg[3] eine der OLS-Konstanten (s.u.)
msg[4]
+ Angaben, welches Programm bzw. welcher Programmtyp gestartet
msg[5] werden soll (abhängig von [3], s.u.)
msg[6]
+ Pointer auf Kommandozeile (i.A. nur die zu ladende Datei) oder NULL
msg[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 Bestätigung erhält man folgende Message:
OLGA_ACK
(Manager -> Client)
msg[0] $1239 (4665)
msg[1] manID
msg[2] 0
msg[3] OLS-Konstante von OLGA_START
msg[4]
+ exakt dieselben Wert von OLGA_START
msg[5]
msg[6] 0=Fehler, sonst: Server gestartet
msg[7] OLGA_START
Um die Kommandozeile leichter freigeben zu können, erhält man außerdem noch eine zweite Message, falls für die Kommandozeile nicht NULL übergeben wurde.
OLGA_ACK
(Manager -> Client)
msg[0] $1239 (4665)
msg[1] manID
msg[2] 0
msg[3] 0 (im Unterschied zur obigen OLGA_ACK-Message!)
msg[4]
+ exakt dieselben Wert von OLGA_START [6]+[7]
msg[5]
msg[6] 0=Fehler, sonst: Server gestartet
msg[7] OLGA_START
Liste der OLGA-fähigen Applikationen
Programm ab Version
----------------------
ArtWorx 1.0
CAB 1.2
GEM-Look 27.12.95
IdeaList 3.71
Kandinsky 2.0
Papillon 2.3
PixArt 3.32
qed 3.90
STELLA 2.0
Texel 1.0
OLGA-Bezugsquelle
Das OLGA-Archiv liegt in der Maus KA (0721-358887) als OLGA.LZH und im WorldWideWeb auf http://www.uni-karlsruhe.de/~Thomas.Much/nbp.html
Thomas Much