                                 OLGA

             Object Linking for GEM Applications Rev. 1.2

                          05. Dezember 1996

                                 von

                             Thomas Much


Inhaltsverzeichnis
==================

 1  Einleitung

 2  Was ist Object Linking?
    2.1  Die OLGA-Architektur

 3  Installation des OLGA-Managers

 4  Das OLGA-Protokoll...
    4.1  ...fr Server und Client
         4.1.1  OLE_INIT
         4.1.2  OLGA_INIT
         4.1.3  OLE_EXIT
         4.1.4  OLE_NEW
    4.2  ...aus der Sicht des Servers
         4.2.1  OLGA_UPDATE
         4.2.2  OLGA_GETINFO
         4.2.3  OLGA_INFO
         4.2.4  OLGA_RENAME
         4.2.5  OLGA_BREAKLINK
         4.2.6  OLGA_CLIENTTERMINATED
    4.3  ...aus der Sicht des Clients
         4.3.1  OLGA_OPENDOC
         4.3.2  OLGA_CLOSEDOC
         4.3.3  OLGA_LINK
         4.3.4  OLGA_UNLINK
         4.3.5  OLGA_UPDATED
         4.3.6  OLGA_RENAMELINK
         4.3.7  OLGA_LINKRENAMED
         4.3.8  OLGA_LINKBROKEN
         4.3.9  OLGA_START
         4.3.10  OLGA_SERVERTERMINATED

 5  InplaceDrawing
    5.1  ID4-Client
         5.1.1  OLGA_GETOBJECTS
         5.1.2  OLGA_ACTIVATE
         5.1.3  OLGA_EMBED
    5.2  ID4-Server
         5.2.1  OLGA_EMBEDDED
         5.2.2  OLGA_UNEMBED
         5.2.3  OLGA_INPLACEUPDATE
         5.2.4  CBDraw
         5.2.5  CBUnembed

 6  Notification
    6.1  OLGA_REQUESTNOTIFICATION
    6.2  OLGA_RELEASENOTIFICATION
    6.3  OLGA_NOTIFY

 7  Idle-Test

 8  Konfigurationsabfrage

 9  Das OLGA-Info-Dateiformat

10  Down to the minimum
   10.1  Server
   10.2  Client

11  Abschlieende Hinweise

Anhang
======

 A  FAQ

 B  Glossar

 C  Liste der OLGA-Applikationen

 D  Dateien
    D.1  OLGA.H
    D.2  OLGA.INC
    D.3  OLGA.INF

 E  History

 F  Knftige Weiterentwicklungen

 G  Kontakt

 H  Rechtliches

 I  Dank



1  Einleitung
*************

Dies ist die Anleitung zu OLGA 1.2, d.h. zum OLGA-Protokoll Revision
1.2 und zum OLGA-Manager Version 1.20 (beides vom 20.11.96).

Anwender werden sich vermutlich hauptschlich fr "Was ist Object
Linking?" (siehe "Was ist Object Linking?") und die Installation des
OLGA-Managers interessieren, aber auch im Anhang gibt es ein paar
ntzliche Informationen.

Programmierer sollten daneben auch einen Blick auf "Die OLGA-
Architektur" (siehe "Die OLGA-Architektur") werfen, um einen berblick
ber die Mglichkeiten zu bekommen. Auerdem ist der Rest dieser
Dokumentation ganz speziell fr sie bestimmt.

Bitte beachten Sie auch "Rechtliches".



2  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, Bestandteil
des neuen OLE-Protokolls zu sein, das OEP und OLGA umfat.

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
Kommunikation bzgl. OL zwischen den Applikationen wird komplett ber
diesen Manager abgewickelt. Es kann immer nur einen Manager im System
geben! Die Installation des OLGA-Managers ist im nchsten Abschnitt
beschrieben.

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.

Und jetzt bitte nicht gleich von dem langen Text abschrecken lassen,
das meiste sind nur Informations- bzw. Besttigungsmessages, die fr
das einfache Funktionieren des Protokolls gar nicht ausgewertet werden
mssen. Weiter unten befindet sich eine Liste der Funktionen, die
minimal untersttzt werden mssen ("Down to the minimum").


2.1  Die OLGA-Architektur
=========================

Das OLGA-Architekturmodell zeigt die Verteilung der Dienste zwischen
OLGA-Manager und der nutzenden Applikation (d.h. Client oder Server).
Whrend Linking, InplaceDrawing und Notification auf einer recht
ausgewogenen Kommunikation zwischen Manager und Applikation beruhen,
obliegt das Embedding vollstndig der Client-Applikation. Die Info-
Dateien schlielich werden durch den Manager koordiniert, laufen aber
dann direkt zwischen Server- und Client-Applikation ab. Schematisch
sieht die Kommunikation in etwa wie folgt aus:



3  Installation des OLGA-Managers
*********************************

Zunchst sei noch einmal darauf hingewiesen, da das OLGA-Protokoll
zwingend ein Multitasking-Betriebssystem voraussetzt (MultiTOS, N.AES,
MagiC etc.).

Man mu sich nun berlegen, ob man den OLGA-Manager stndig im
Speicher haben mchte oder ob dieser bei Bedarf nachgeladen werden
soll. Der erste Fall ist sehr einfach, man kopiert den Manager
OLGA.APP einfach in das Wurzelverzeichnis der Bootpartition und
benennt die Datei in OLGA.ACC um. Nach einem Neustart des Rechners
steht OLGA nun permanent zur Verfgung.

Der andere Fall ist ein klein wenig komplizierter, hat aber den
Vorteil, da sich der OLGA-Manager nur dann im Speicher befindet, wenn
auch eine OLGA-fhige Applikation geladen ist. Dazu kopiert man
OLGA.APP an eine beliebige Stelle (z.B. C:\GEMSYS\OLGA\OLGA.APP) und
setzt dann die Environmentvariable OLGAMANAGER auf diese Pfadangabe.
Fr MultiTOS trgt man dafr in GEM.CNF folgendes ein:


  setenv OLGAMANAGER=C:\GEMSYS\OLGA\OLGA.APP


MagiC erwartet in MAGX.INF folgende Zeile:


  #_ENV OLGAMANAGER=C:\GEMSYS\OLGA\OLGA.APP


Wird nun eine OLGA-fhige Applikation gestartet, wird der Manager
automatisch nachgeladen. Auerdem entfernt sich ein so gestarteter
Manager selber wieder aus dem System, sobald die letzte OLGA-fhige
Applikation beendet wurde.

Wie sich OLGA in einer Applikation bemerkbar macht, hngt nur von
dieser selbst ab. Um bei dem Beispiel des Vektorgrafikprogramms zu
bleiben, knnte z.B. beim Doppelklick auf die Rastergrafik ein
entsprechendes Rastergrafikprogramm nachgeladen werden. Damit sich ein
Programm auch darum nicht selbst zu kmmern braucht, gibt es im OLGA-
Protokoll die Mglichkeit, den Manager nach einer passenden
Applikation suchen und diese dann starten zu lassen. Dazu mu
allerdings der Anwender einmalig seine Lieblingskonfiguration
festlegen, was in der Datei OLGA.INF geschieht. Diese Datei wird in
das Verzeichnis von OLGA.APP bzw. OLGA.ACC kopiert (oder nach C:\ -
allgemeiner: ins Wurzelverzeichnis des Bootlaufwerks - oder nach
$HOME) und ist wie folgt aufgebaut:


[Extensions]
.EXT=Dateipfad+Programmname oder ein Alias
   ...

[Types]
XY=Dateipfad+Programmname oder ein Alias
 ...

[Objects]
.EXT=Klartextbeschreibung des Dateityps
   ...

[Applications]
Alias=Dateipfad+Programmname
    ...


Ein ausfhrliches, konkretes Beispiel findet sich im Abschnitt
"OLGA.INF".

Im Block [Extensions] werden also die Programme eingetragen, die
bestimmte Dateitypen besonders gut bearbeiten knnen. Dieses Verfahren
ist von der Desktop-Funktion "Anwendung anmelden" bekannt. Pro
Extension kann zur Zeit nur eine Applikation angegeben werden, was
aber reichen sollte, schlielich kann der Benutzer hier sein
"Lieblingsprogramm" eintragen.

Im Block [Typen] ist es dann noch mglich, bestimmten Programmtypen
eine Applikation zuzuweisen. Z.B. kann man unter "ED" einen Editor
eintragen, mit dem alle mglichen Textformate bearbeitet werden
knnen. Folgende Typen sind bis jetzt definiert:


                 +----+----------------------------+
                 | 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        |
                 +----+----------------------------+

Wem die Typen bekannt vorkommen: Es sind die beim XAcc-Protokoll
verwendeten maschinenlesbaren Programmtypen.

[Objects] ist fr InplaceDrawing (ID4-OLGA) interessant. Damit ID4
funktioniert, mssen hier die von den vorhandenen ID4-Servern
untersttzten Extensions eingetragen werden. Diese Extensions mssen
auch in [Extensions] der entsprechenden Applikation zugeordnet sein.

[Applications] schlielich dient dazu, die bersicht in OLGA.INF zu
verbessern. Dieser Block ist optional und mu nicht verwendet werden.

Damit ist die Installation abgeschlossen.



4  Das OLGA-Protokoll...
************************


4.1  ...fr Server und Client
=============================

...entspricht dem OLE-Protokoll, da Object Embedding mit OEP (Object
Exchange Protocol) und Object Linking mit OLGA ermglicht. Beide
Protokolle (d.h. OEP und OLGA) werden mit denselben Messages evtl.
gleichzeitig (!) initialisiert. Die genaue OEP-Dokumentation findet
sich in der OEP-Distribution.

Das OLGA-Protokoll besteht im wensentlich aus dem Kommunikation mit
dem OLGA- (bzw. OLE-) Manager. Dazu mu man die AES-ID des Managers
kennen, die wie folgt ermittelt wird:

  1. Die Applikation bentigt OLE (=OEP+OLGA):

      (a) Wenn appl_find("OLEMANGR") erfolgreich ist, hat man den
          Manager schon gefunden.

      (b) Ansonsten wird nun die Environmentvariable OLEMANAGER
          ausgewertet. Dort kann ein kompletter Zugriffspfad stehen!
          Zunchst extrahiert man aus diesem Pfad einen Programmnamen
          fr appl_find() und geht entsprechend wie unter a) vor.
          Konnte auch dieser Name nicht gefunden werden, startet man
          das Programm, das von OLEMANAGER bezeichnet wird, mit
          shel_write() nach.

      (c) Wenn das bisherige nicht zum Erfolg gefhrt hat, gibt es
          offensichtlich keinen OLE-Manager, man mu sich evtl. mit
          dem OLGA-Protokoll begngen. Dazu macht man - analog zu a) -
          ein appl_find("OLGA ") und ein appl_find("OEP_SERV"). Evtl.
          mu man nmlich nun zwei Manager untersttzen!

      (d) Konnte auch dieses Programm nicht gefunden werden, wertet
          man nun noch die Environmentvariablen OLGAMANAGER und
          OEPSERVER wie unter b) aus.

  2. Die Applikation bentigt nur OLGA:

     Das Verfahren entspricht dem von 1), nur die Reihenfolge ndert
     sich zu c), d), a), b). Auerdem braucht man natrlich OEP_SERV
     und OEPSERVER nicht abfragen, da es unwahrscheinlich ist, da ein
     OEP-Server das OLGA-Protokoll versteht.


4.1.1  OLE_INIT
---------------

Hat man einen (bzw. zwei, s.o.) Manager gefunden, schickt man ihm
folgende Message:


OLE_INIT
(Client/Server -> Manager)
msg[0] $4950 (18768)
msg[1] apID
msg[2] 0
msg[3] OLGA: Bitmap, OL_SERVER und/oder OL_CLIENT gesetzt, OL_PIPES
msg[4] OLGA: max. von der App. verstandene Stufe des Protokolls
             (z.Z. immer 0)
msg[5] OEP:  Bitmap, OL_OEP gesetzt
msg[6] OEP:  reserviert (0)
msg[7] maschinenlesbarer XAcc-Programmtyp (oder 0):
             "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 OLGA-Server
OL_CLIENT = $0002   Applikation ist OLGA-Client
OL_PEER   = $0003   Applikation ist Client und Server
OL_IDLE   = $0800   Applikation untersttzt den Idle-Test
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 Ver-
                    fahren wird z.Z. noch nicht untersttzt, eine
                    genauere Definition folgt spter
OL_OEP    = $0001   Applikation versteht OEP


Wenn ein Protokoll von der Applikation nicht untersttzt wird, sind
msg[3]/msg[4] bzw. msg[5]/msg[6] auszunullen!

Daraufhin erhlt man vom Manager je nach Protokollauswahl eine
OEP_CONFIG- und/oder eine OLGA_INIT-Message. Es wird dann nach den
Beschreibungen des jeweiligen Protokolls fortgefahren.


4.1.2  OLGA_INIT
----------------

Der OLGA-Manager verschickt als Besttigung die OLGA_INIT-Message.
Wichtig: Applikationen sollten den OLGA-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 Fehlfunktionen auftreten, falls sich
der Manager doch nicht meldet).


OLGA_INIT
(Manager -> Client/Server)
[0] $1236 (4662)
[1] apID
[2] 0
[3] Bitmap, OL_MANAGER gesetzt
[4] Stufe des verwendeten (!) Protokolls (z.Z. immer 0)
[5] 0
[6] 0
[7] 0=Fehler, sonst: OL-Mechanismus verfgbar

OL_IDLE    = $0800   Manager untersttzt den Idle-Test
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



4.1.3  OLE_EXIT
---------------

Beim Programmende wird dem Manager folgende Message geschickt (die
Nachricht wird auerdem von Manager an die Applikationen verschickt,
sollte dieser terminieren). Wenn sich ein OLGA-Client abmeldet, werden
automatisch alle zugehrigen Links und Documents gelscht.


OLE_EXIT
(Client/Server -> Manager, Manager -> Client/Server)
msg[0] $4951 (18769)
msg[1] apID
msg[2] 0
msg[3] 0
msg[4] 0
msg[5] 0
msg[6] 0
msg[7] 0



4.1.4  OLE_NEW
--------------

Wenn ein Manager nachgestartet wird, verschickt er an alle
erreichbaren Applikationen folgende Message:


OLE_NEW
(Manager -> Client/Server)
msg[0] $4952 (18770)
msg[1] apID
msg[2] 0
msg[3] OLGA: Bitmap (OL_MANAGER, OL_START, OL_PIPES, OL_IDLE)
msg[4] OLGA: max. Manager-Stufe des OLGA-Protokolls
msg[5] OEP:  OL_OEP ($0001) gesetzt, falls der Manager OEP beherrscht
msg[6] OEP:  0, reserviert
msg[7] Versionsnummer des Managers, z.B. $0114 fr 1.14


Nach Empfang und Auswertung dieser Message sollte eine Applikation
OLE_INIT verschicken. Die Werte in OLE_NEW ersetzen nicht die Rckgabe
von OEP_CONFIG bzw. OLGA_INIT, sie dienen nur zu Informationszwecken!
(wenn z.B. ein neuer Manager nur ein Protokoll untersttzt, kann evtl.
der alte Manager weiterverwendet werden)


4.2  ...aus der Sicht des Servers
=================================


4.2.1  OLGA_UPDATE
------------------

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 Benutzereingaben scheitert; auf erweiterten
Filesystemen wird das spter allerdings nicht mehr so sein.)


OLGA_UPDATE
(Server -> Manager)
[0] $1238 (4664)
[1] apID
[2] 0
[3]
 +  Pointer auf den kompletten Dateinamen incl. (absolutem!) Pfad
[4]
[5] 0 bzw. Server-interne (eindeutige) Index-Nummer, falls eine Info-Datei
    zur Verfgung steht oder erzeugt werden kann (s. OLGA_GETINFO)
[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
(Manager -> Server)
[0] $1239 (4665)
[1] apID
[2] 0
[3]
 +  exakt dieselben Wert von OLGA_UPDATE
[4]
[5] 0
[6] 0
[7] OLGA_UPDATE



4.2.2  OLGA_GETINFO
-------------------

Wenn der Server bei OLGA_UPDATE eine Index-Nummer fr eine Info-Datei
bekanntgegeben hat, kann ein Client (!) letztere nun direkt beim
Server abfragen. Nach dem Empfangen von OLGA_GETINFO kann der Server
eine solche Datei erzeugen (Aufbau s.u.), falls sie noch nicht
existiert. Zu beachten ist, da die bergebene Index-Nummer nicht
gltig sein mu, die OLGA_GETINFO-Message mu dann vom Server
ignoriert werden!


OLGA_GETINFO
(Client -> Server)
[0] $1247 (4679)
[1] apID
[2] 0
[3] 0
[4] 0
[5] Index-Nummer der gewnschten Info-Datei
[6] 0
[7] 0



4.2.3  OLGA_INFO
----------------

Als Antwort auf OLGA_GETINFO verschickt der Server direkt an den
Client (!) folgende Message (nachdem die Info-Datei erzeugt wurde -
falls sie nicht sogar stndig vorhanden ist).


OLGA_INFO
(Server -> Client)
[0] $1248 (4680)
[1] apID
[2] 0
[3]
 +  Pointer auf den kompletten Info-Dateinamen incl. (absolutem!) Pfad
[4]
[5] Index-Nummer der gewnschten Info-Datei
[6] 0
[7] 0


Der Client darf sich allerdings nicht auf eine solche Antwort
verlassen, der Server knnte ja mittlerweile terminiert haben.
Auerdem darf der Client nur lesend auf die Datei zugreifen.

Sobald der Client die Datei wieder geschlossen hat, teilt er dies dem
Server direkt (!) mit, damit dieser die Datei evtl. wieder lschen
kann.


OLGA_ACK
(Client -> Server)
[0] $1239 (4665)
[1] apID
[2] 0
[3]
 +  exakt dieselben Werte von OLGA_INFO
[4]
[5] Index-Nummer der gewnschten Info-Datei
[6] 0
[7] OLGA_INFO



4.2.4  OLGA_RENAME
------------------

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
(Server -> Manager)
[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
(Manager -> Server)
[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



4.2.5  OLGA_BREAKLINK
---------------------

Sollte der Server eine Datei lschen (oder anderweitig fr den Client
unbrauchbar 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
(Server -> Manager)
[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
(Manager -> Server)
[0] $1239 (4665)
[1] apID
[2] 0
[3]
 +  exakt dieselben Wert von OLGA_BREAKLINK
[4]
[5] 0
[6] 0
[7] OLGA_BREAKLINK



4.2.6  OLGA_CLIENTTERMINATED
----------------------------

Wenn ein Client terminiert, der einen Server per OLGA_START aufgerufen
hat, erhlt dieser Server folgende Message:


OLGA_CLIENTTERMINATED
(Manager -> Server)
[0] $1255 (4693)
[1] manID
[2] 0
[3] AES-ID des terminierten Clients
[4] Anzahl der Clients, die den Server noch benutzen (>=0)
[5] 0
[6] 0
[7] 0



4.3  ...aus der Sicht des Clients
=================================


4.3.1  OLGA_OPENDOC
-------------------

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
(Client -> Manager)
[0] $123b (4667)
[1] apID
[2] 0
[3] 0
[4] 0
[5] Gruppenkennung (eine innerhalb des Clients eindeutige, vom Client
    frei whlbare Zahl, mit der die Links innerhalb des Clients den
    Dokumenten zugeordnet werden knnen)
[6] 0
[7] 0


Als Antwort erhlt der Client folgende Message:


OLGA_ACK
(Manager -> Client)
[0] $1239 (4665)
[1] apID
[2] 0
[3] 0
[4] 0
[5] Gruppenkennung des Dokuments
[6] 0
[7] OLGA_OPENDOC



4.3.2  OLGA_CLOSEDOC
--------------------

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 Programmende nicht verwendet werden,
da OLE_EXIT alle Documents lscht.


OLGA_CLOSEDOC
(Client -> Manager)
[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
(Manager -> Client)
[0] $1239 (4665)
[1] apID
[2] 0
[3] 0
[4] 0
[5] Gruppenkennung des Dokuments
[6] 0
[7] OLGA_CLOSEDOC



4.3.3  OLGA_LINK
----------------

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
(Client -> Manager)
[0] $123d (4669)
[1] apID
[2] 0
[3]
 +  Pointer auf den Dateinamen, der berwacht werden soll
[4] (incl. absolutem Pfad)
[5] Gruppenkennung des Dokuments (s. OLGA_OPENDOC)
[6] 0
[7] 0


Als Besttigung verschickt der Manager folgende Message:


OLGA_ACK
(Manager -> Client)
[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



4.3.4  OLGA_UNLINK
------------------

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 OLE_EXIT
automatisch gelscht.


OLGA_UNLINK
(Client -> Manager)
[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
(Manager -> Client)
[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



4.3.5  OLGA_UPDATED
-------------------

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
(Manager -> Client)
[0] $123f (4671)
[1] apID
[2] 0
[3]
 +  Pointer auf den Dateinamen (incl. absolutem Pfad) der Datei,
[4] die verndert wurde
[5] 0 bzw. Index-Nummer, falls eine Info-Datei angefordert werden kann
[6] apID des Updaters (Server); garantiert gesetzt, wenn [5] ungleich null;
    an diese ID kann eine OLGA_GETINFO-Message geschickt werden
[7] Gruppenkennung des Dokuments


Wenn dem Client bei dieser Message das Vorhandensein einer Info-Datei
(Aufbau s.u.) gemeldet wird und der Client diese anfordern mchte,
sollte er so schnell wie mglich dem Server direkt (!) eine
OLGA_GETINFO-Message schicken. Dieses Vorgehen ist bereits weiter oben
("...aus der Sicht des Servers") beschrieben.


4.3.6  OLGA_RENAMELINK
----------------------

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
(Manager -> Client)
[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



4.3.7  OLGA_LINKRENAMED
-----------------------

Als Antwort auf OLGA_RENAMELINK mu der Client an den Manager folgende
Message schicken, damit letzterer seine Referenz aktualisiert und
unntigen Speicherplatz freigibt (der Client mu dazu nur die
Messagenummer 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
(Client -> Manager)
[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



4.3.8  OLGA_LINKBROKEN
----------------------

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
(Manager -> Client)
[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
(Client -> Manager)
[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



4.3.9  OLGA_START
-----------------

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
(Client -> Manager)
[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 NULL
[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
(Manager -> Client)
[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 NULL
bergeben wurde).


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



4.3.10  OLGA_SERVERTERMINATED
-----------------------------

Wenn ein Server terminiert, erhalten alle Clients, die diesen Server
per OLGA_START aufgerufen haben, folgende Message:


OLGA_SERVERTERMINATED
(Manager -> Client)
[0] $1254 (4692)
[1] manID
[2] 0
[3] AES-ID des terminierten Servers
[4]
 +  Extension oder (0,XAcc-Typ) oder NULL
[5]
[6] reserviert
[7] 0


Je nachdem, in welchem Modus der Server nachgestartet wurde, enthalten
die Felder [4..5] unterschiedliche Werte. Beim Start mit OLS_EXTENSION
steht dort eben diese Extension, beim Start mit OLS_TYPE ist [4]=0 und
[5] enthlt den XAcc-Programmtyp. Beim Start mit OLS_NAME sind beide
Felder ausgenullt.



5  InplaceDrawing
*****************

Damit InplaceDrawing (ID4-OLGA, ID4) funktionieren kann, mu der
OLGA-Manager korrekt installiert (siehe "Installation des OLGA-
Managers") und OLGA.INF entsprechend angepat sein (Abschnitte
[Extensions] und [Objects]). ID4-Server und -Clients sind ganz normale
OLGA-Server und -Clients, die sich zustzlich an das im folgenden
vorgestellte Protokoll halten.


5.1  ID4-Client
===============

ID4-Clients betten Objekte in ihre Dokumente ein (man nennt diese
Clients deshalb auch "Containerapplikationen"). Ein Client ermittelt
mit OLGA_GETOBJECTS alle in OLGA.INF eingetragenen ID4-Objekte, um dem
Anwender z.B. den folgenden Dialog anbieten zu knnen:

Pro Objekt, das eingebettet werden soll, mu ein ID4-Client folgende
Struktur im globalen Speicher anlegen (siehe auch OLGA.H und
OLGA.INC):


        typedef struct ObjectInfo
        {
                char  *Filename;
                AESPB *ClientGEMPB;
                long   ClientData,
                       ServerData;
                int    CBLock,
                       CBCount;
                void   cdecl (*CBDraw)    (ObjectInfo *objectinfo,
                                           int outScreen,
                                           int outHandle,
                                           int outDevID,
                                           GRECT *Size,
                                           GRECT *Clip);
                void   cdecl (*CBUnembed) (ObjectInfo *objectinfo);
        } OLGAObjectInfo;


Danach werden die ntigen ID4-Server mit OLGA_ACTIVATE nachgestartet
und alle Objekte einzeln mit OLGA_EMBED eingebunden.

Zum Zeichnen eines Objekts geht ein Client folgendermaen vor:
Zunchst wird OLGAObjectInfo.CBLock des zugehrigen Objekts um eins
erhht. Direkt danach testet der Client, ob in CBLock ein Wert grer
Null eingetragen ist. Ist dies nicht der Fall, darf der Client die
Callback-Routinen nicht aufrufen! Ansonsten testet der Client, ob
CBDraw ungleich NULL ist - wenn ja, ruft er denn Callback auf. Zum
Schlu wird CBLock wieder um eins erniedrigt.

Clients sollten beim Empfang von OLGA_INPLACEUPDATE das in dieser
Message angegebene Objekt neu zeichnen lassen.

Beim Lschen eines Objekts (oder Schlieen eines Dokuments bzw.
Terminieren des Clients) mu fr jedes Objekt CBUnembed() aufgerufen
werden, sofern der Callback ungleich NULL ist. Die Absicherung mit
CBLock erfolgt wie oben beschrieben. Der Server wei dann, das fr
dieses Objekt keine ID4-Verknpfung mehr besteht (bzw. eine weniger).

Umgekehrt schickt ein Server dem Client OLGA_UNEMBED, wenn der Server
ein eingebettetes Objekt nicht mehr zur Verfgung stellen (d.h.
zeichnen) kann. Der Client kann dann das Objekt ungltig machen (z.B.
als weies, rot durchgestrichenes Rechteck darstellen). In hnlicher
Weise sollte ein Client auf OLGA_SERVERTERMINATED reagieren.


5.1.1  OLGA_GETOBJECTS
----------------------

Mit dieser Message kann ein ID4-Client den Manager abfragen, welche
Dateitypen per ID4-OLGA eingebettet werden knnen.


OLGA_GETOBJECTS
(Client -> Manager)
msg[0] $1242 (4674)
msg[1] apID
msg[2] 0
msg[3] erstes (0) oder weiteres (1) Objekt
msg[4] 0
msg[5] 0
msg[6] 0
msg[7] 0


Als Antwort erhlt der Client die Message OLGA_OBJECTS, die ihm neben
der Extension auch die Klartextbeschreibung des Dateityps fr die
Benutzerauswahl (siehe "ID4-Client") liefert.


OLGA_OBJECTS
(Manager -> Client)
msg[0] $1243 (4675)
msg[1] manID
msg[2] 0
msg[3] Anzahl der noch abrufbaren Objekte (0=dies ist das letzte Objekt)
msg[4]
    +  Extension des Dateiformats, z.B. ".GEM"
msg[5]
msg[6]
    +  Pointer auf Klartext-Objektbeschreibung
msg[7] (gltig bis zum Terminieren des Managers)


Die Message OLGA_GETOBJECTS mu nun so lange an den Manager geschickt
werden, bis OLGA_OBJECTS in msg[3] eine Null zurckgibt.


5.1.2  OLGA_ACTIVATE
--------------------

Irgendwann vor dem Zeichnen, am besten auch vor dem Einbetten des
ersten Objekts, auerhalb (!) einer wind_update()-Blockierung, schickt
der ID4-Client dem Manager folgende Message. Falls der Client vor dem
nchsten wind_update() nicht mehr in seine Eventschleife geht, mu er
danach einen evnt_timer() (mind. 1000ms) machen.


OLGA_ACTIVATE
(Client->Manager)
msg[0] $124a
msg[1] apID
msg[2] 0
msg[3]
    +  Pointer auf 4-Zeichen Extensions (z.B. ".GEM.CWG"),
msg[4]  evtl. krzen oder mit Nullbytes (!) auffllen
msg[5] Anzahl der Extensions (>=1)
msg[6] 0
msg[7] 0


In dieser Message sollten alle verschiedenen Extensions aller
eingebetteten Objekte angegeben werden, damit der Manager die
passenden Server starten kann.

Der Manager verschickt daraufhin als Besttigung folgende Message:


OLGA_ACK
(Manager -> Client)
[0] $1239 (4665)
[1] manID
[2] 0
[3] derselbe Wert wie in empfangener OLGA_ACTIVATE-Message
[4] derselbe Wert wie in empfangener OLGA_ACTIVATE-Message
[5] derselbe Wert wie in empfangener OLGA_ACTIVATE-Message
[6] 0
[7] OLGA_ACTIVATE



5.1.3  OLGA_EMBED
-----------------

Zum Einbetten eines Objekts legt ein Client eine OLGAObjectInfo-
Struktur im globalen Speicher an, setzt die Felder Filename (absoluter
Dateiname, nullterminiert), ClientGEMPB (ein Pointer auf die Struktur,
die Pointer zu den GEM-Arrays global[] etc. enthlt), ClientData
(beliebige Client-Daten), CBLock (konstant auf -16000) sowie CBCount
(z.Z. immer auf 2) und nullt alle anderen Felder aus. Danach schickt
der Client dem Manager folgende Message:


OLGA_EMBED
(Client->Manager)
msg[0] $124b
msg[1] clientID
msg[2] 0
msg[3] Client-Flag
msg[4]
    +  Pointer auf OLGAObjectInfo des Objekts
msg[5]
msg[6]
    +  Extension
msg[7]


Das Client-Flag kann vom Client beliebig gesetzt werden und wird auch
spter wieder an den Client zurckgegeben. Die Extension beschreibt
den Dateityp des Filenames aus OLGAObjectInfo (z.B. ".GEM"). Anhand
dieser Extension wird der ID4-Server angesprochen, der bereits laufen
mu (siehe OLGA_ACTIVATE).

Das eigentliche Einbetten darf der Client erst vornehmen, wenn er
folgende Message (direkt vom Server) erhlt:


OLGA_EMBEDDED
(Server->Client)
msg[0] $124c
msg[1] serverID
msg[2] 0
msg[3] Client-Flag
msg[4]
    +  Pointer auf OLGAObjectInfo
msg[5]
msg[6] Breite des Objekts in 1/100mm (vorzeichenlos), 0 bei Fehler
msg[7] Hhe des Objekts in 1/100mm (vorzeichenlos), 0 bei Fehler


Client-Flag und der OLGAObjectInfo-Pointer sind unverndert zu
OLGA_EMBED. ServerData kann vom Server verndert worden sein (wie der
Name schon sagt, gehrt dieses Feld dem Server und darf vom Client
nicht verndert werden), und in CBDraw sollte der Server einen Pointer
auf seine Zeichenroutine eingetragen haben.

Mit msg[6]/msg[7] teilt der Server dem Client die optimale Objektgre
mit. Der Client mu sich nicht an diese Gre halten, kennt durch das
Breite/Hhe-Verhltnis aber auf jeden Fall die Proportionen des
Objekts.

Wichtig: Wenn msg[6]/msg[7] ausgenullt sind, ist ein Fehler
aufgetreten (OLGA_EMBEDDED kann in diesem Fall auch schon vom Manager
verschickt worden sein). Der Client darf das Objekt dann nicht
einbetten!


5.2  ID4-Server
===============

Wichtig: Wenn ID4 mit MemoryProtection funktionieren soll, mu das
GLOBAL-Flag im Programmheader des ID4-Servers gesetzt sein!

Wenn ein Client ein Objekt einbetten mchte, erhlt der Server vom
Manager eine OLGA_EMBED-Message, die er mit OLGA_EMBEDDED beantworten
mu.

Zum Zeichnen wird vom Client der CBDraw()-Callback aufgerufen. Whrend
der Abarbeitung des Callsbacks drfen vom Server i.d.R. keine AES-
Aufrufe gemacht werden (das schliet wind_update() mit ein!). Auerdem
darf der Server die Farbpalette nicht verstellen. Wenn im Server
Vernderungen an einem Objekt vorgenommen werden, kann dem Client zum
sofortigen Update die Message OLGA_INPLACEUPDATE geschickt werden.

Damit es beim Terminieren des Servers oder Schlieen eines Dokuments
keine undefinierten Zeiger gibt, mu der Server folgendermaen
vorgehen:

Fr jedes Objekt testet der Server, ob OLGAObjectInfo.CBLock<=0 ist.
Ist dies der Fall, setzt der Server erst CBLock auf -16000, dann
CBDraw auf NULL.

Das ganze mu in einer evnt_timer()-Schleife solange wiederholt
werden, bis keine Objekte mehr belegt sind. Erst dann darf der Server
terminieren oder das Dokumentfenster schlieen.

Hat der Server alle entsprechenden CBDraw()-Pointer auf NULL gesetzt
mu er dem Client OLGA_UNEMBED schicken. Der Client kann beim Empfang
dieser Message das so "ungltig" gewordene Objekt als z.B. weies, rot
durchgestrichenes Rechteck neu zeichnen.

Damit der Server feststellen kann, ob ein eingebettetes Objekt noch
von einem Client benutzt wird, wird von den Clients zum Auflsen der
Verbindung der CBUnembed()-Callback aufgerufen. In hnlicher Weise
sollte ein ID4-Server auf den Empfang von OLGA_CLIENTTERMINATED
reagieren.

Damit es beim evtl. Absturz eines Servers keine Probleme gibt, sollte
der Server etv_critic() berschreiben und beim Durchlaufen durch diese
Routine CBDraw in allen Objekten auf NULL und CBLock auf -16000
setzen.


5.2.1  OLGA_EMBEDDED
--------------------

Wenn ein Client ein Objekt einbetten mchte, erhlt der Server vom
Manager folgende Message:


OLGA_EMBED
(Manager->Server)
msg[0] $124b
msg[1] manID
msg[2] 0
msg[3] Client-Flag
msg[4]
    +  Pointer auf OLGAObjectInfo
msg[5]
msg[6] 0
msg[7] clientID


msg[3..5] drfen vom Server nicht verndert werden und mssen bei
OLGA_EMBEDDED zurckgegeben werden. Das Feld ServerData in
OLGAObjectInfo kann vom Server beliebig verwendet werden.

Der Server kann nun die in OLGAObjectInfo angegebene Datei laden,
setzt CBLock auf Null und trgt in CBDraw den Pointer auf seine
Zeichenroutine ein. In CBUnembed kann der Server eine Routine
eintragen, die vom Client beim Auflsen der ID4-Verknpfung aufgerufen
wird.

Dann mu der Server dem Client direkt (!) folgende Antwort schicken
(die Client-ID bekommt der Server in msg[7] mitgeteilt):


OLGA_EMBEDDED
(Server->Client)
msg[0] $124c
msg[1] serverID
msg[2] 0
msg[3] Client-Flag
msg[4]
    +  Pointer auf OLGAObjectInfo
msg[5]
msg[6] Breite des Objekts in 1/100mm (vorzeichenlos), 0 bei Fehler
msg[7] Hhe des Objekts in 1/100mm (vorzeichenlos), 0 bei Fehler


Wenn der Server in msg[6..7] einen Fehler signalisiert, wird der
Client das Objekt nicht einbetten.

Wichtig: Falls der Server vom Manager nachgestartet wird, knnen
OLGA_EMBED-Messages eintreffen, noch bevor der Server seine OLGA-
Anmeldung beendet hat! Es ist dann Sache des Servers, ob er die
OLGA_EMBEDDED-Antworten sofort bearbeitet oder erst nach Abschlu
seiner Initialisierung.


5.2.2  OLGA_UNEMBED
-------------------

Damit es beim Terminieren des Servers oder Schlieen eines Dokuments
keine undefinierten Zeiger gibt, mu der Server folgendermaen
vorgehen:

Fr jedes Objekt testet der Server, ob CBLock<=0 ist. Ist dies der
Fall, setzt der Server erst CBLock auf -16000, dann CBDraw auf NULL.

Das ganze mu in einer evnt_timer()-Schleife solange wiederholt
werden, bis keine Objekte mehr belegt sind. Erst dann darf der Server
terminieren oder das Dokumentfenster schlieen.

Hat der Server alle entsprechenden CBDraw's auf NULL gesetzt etc. mu
er dem Client direkt (!) fr jedes Objekt folgende Message schicken
(bzw. stattdessen eine einzige Message mit msg[3..4]=NULL beim
Terminieren):


OLGA_UNEMBED
(Server->Client)
msg[0] $124d
msg[1] serverID
msg[2] 0
msg[3] 0
msg[4]
    +  Pointer auf OLGAObjectInfo oder NULL (s.o.)
msg[5]
msg[6] 0
msg[7] 0


Der Client kann beim Empfang dieser Message das so "ungltig"
gewordene Objekt als z.B. weies, rot durchgestrichenes Rechteck neu
zeichnen.


5.2.3  OLGA_INPLACEUPDATE
-------------------------

Wenn an einem Dokument nderungen vorgenommen werden, kann der Server
dem Client folgende Message schicken, damit letzterer eingebettete
Objekt sofort neu zeichnen lt (ohne da vorher ein Speichern ntig
ist). Der Server darf diese Message erst dann verschicken, nachdem er
OLGA_EMBEDDED an den Client geschickt hat!


OLGA_INPLACEUPDATE
(Server->Client)
msg[0] $1256
msg[1] serverID
msg[2] 0
msg[3] 0
msg[4]
    +  Pointer auf OLGAObjectInfo
msg[5]
msg[6] 0
msg[7] 0



5.2.4  CBDraw
-------------

C-Notation:

        void cdecl (*CBDraw) (ObjectInfo *objectinfo,
                              int outScreen,
                              int outHandle,
                              int outDevID,
                              GRECT *Size,
                              GRECT *Clip);

PurePascal-Notation:
(d1..d5 sind Dummy-Werte, hier sollte nil bzw. 0 bergeben werden.)

        CBDraw: procedure(d1,d2: pointer; d3,d4,d5: longint;
                          objectinfo: POLGAObjectInfo;
                          outScreen,
                          outHandle,
                          outDevID: integer;
                          Size,
                          Clip: GRECTPtr);


Wenn CBDraw() vom Client aufgerufen wird, sollte der Server
berprfen, ob er die Datei OLGAObjectInfo.Filename (der
OLGAObjectInfo-Pointer wird bei CBDraw() bergeben) schon geladen hat
- wenn nicht, sollte dies nun erfolgen. Da das Laden aber eigentlich
durch OLGA_EMBED sichergestellt sein sollte, kann in einem solchen
Fall alternativ auch ein Fehler angezeigt werden, beispielsweise durch
einfaches Durchstreichen des Objektbereichs mit zwei roten Linien
(evtl. kann der eigentliche Fehler auch noch im Klartext in den
Objektbereich ausgegeben werden).

Dann kann der Server die Grafik anhand der bergebenen Werte (s.u.)
zeichnen. Der Server darf innerhalb dieses Zeichnens keinerlei
wind_update()-Aufrufe machen! Die Parameter von CBDraw() haben
folgende Bedeutung:

    outScreen gibt an, ob die Ausgabe auf den Bildschirm erfolgt
     (<>0) oder nicht (=0). Auch eine Preview ist eine
     Bildschirmausgabe!

    outHandle ist das Handle der geffneten Workstation (Bildschirm,
     Drucker etc.), auf die der Server direkt ausgeben kann. Wenn
     outScreen<>0 ist, kann der Server alternativ auch auf seine
     eigene Screen-Workstation ausgeben.

    outDevID gibt die Gertenummer (aus ASSIGN.SYS) des Treibers an,
     auf den ausgegeben wird. Wenn es sich um eine reine
     Bildschirmausgabe handelt, steht in diesem Feld eine Null. Bei
     einer Preview wird zwar auf den Bildschirm ausgegeben, outDevID
     gibt dann z.B. aber den Treiber an, auf den spter beim
     eigentlichen Druck ausgegeben wird. Der Server kann in diesem
     Fall versuchen, den Treiber zu ffnen, um die Bildschirmausgabe
     besser an die sptere Druckausgabe anzupassen.

    Size ist das Rechteck, in das die Grafik exakt eingepat werden
     mu, auch wenn es dabei zu Verzerrungen kommt. Clip ist das (vor
     dem Aufruf gesetzte) Clipping-Rechteck.

Wichtig: Ein Server darf whrend CBDraw() keine AES-Aufrufe machen!
(Es sei denn, das AESPB-Zeigerfeld wurde mittels ClientGEMPB angepat;
wind_update() bleibt fr ID4-Server aber trotzdem tabu.) Auerdem darf
die Farbpalette im Callback nicht verstellt werden.


5.2.5  CBUnembed
----------------

C-Notation:

        void cdecl (*CBUnembed) (ObjectInfo *objectinfo);

PurePascal-Notation:
(d1..d5 sind Dummy-Werte, hier sollte nil bzw. 0 bergeben werden.)

        CBUnembed: procedure(d1,d2: pointer; d3,d4,d5: longint;
                             objectinfo: POLGAObjectInfo);


Beim Lschen eines Objekts (oder Schlieen eines Dokuments bzw.
Terminieren) ruft ein Client fr jedes Objekt CBUnembed() auf. Der
ID4-Server kann auf diese Weise feststellen, da fr das angegebene
Objekt keine ID4-Verknpfung mehr besteht (bzw. eine weniger).



6  Notification
***************

Es kann Applikationen geben, denen das bisher vorgestellte
ObjectLinking nicht ausreicht, weil damit nur bekannte (oder vom
Anwender ausgewhlte) Dateien berwacht werden knnen. Mit der
Notification-Erweiterung kann sich eine Applikation nun vom Manager
ber alle Updates bzw. solche eines bestimmten Dateityps informieren
lassen.

Wie immer mssen bei den folgenden Messages die Extensions immer gro
geschrieben werden. Sie sind (mit Punkt) exakt vier Zeichen lang, zur
Not mu man die Extension krzen bzw. mit Nullbytes (!) auffllen.


6.1  OLGA_REQUESTNOTIFICATION
=============================

Wenn eine Applikation vom Manager bei nderungen aller Dateien eines
bestimmten Typs benachrichtigt werden mchte, schickt sie ihm folgende
Message. Werden vier Nullbytes bergeben, wird die Applikation bei
jedem Update jeder Datei benachrichtig.


OLGA_REQUESTNOTIFICATION
(App -> Manager)
msg[0] $1250 (4688)
msg[1] apID
msg[2] 0
msg[3]
    +  Extension (z.B. ".TIF") oder NULL (="*.*")
msg[4]
msg[5] 0
msg[6] 0
msg[7] 0



6.2  OLGA_RELEASENOTIFICATION
=============================

Eine Applikation kann die Benachrichtigung bei bestimmten (vorher per
OLGA_REQUESTNOTIFICATION angeforderten) Dateitypen (bzw. bei allen,
falls vier Nullbytes bergeben werden) mit folgender Message wieder
ausschalten.


OLGA_RELEASENOTIFICATION
(App -> Manager)
msg[0] $1251 (4689)
msg[1] apID
msg[2] 0
msg[3]
    +  Extension (z.B. ".TIF") oder NULL (="*.*")
msg[4]
msg[5] 0
msg[6] 0
msg[7] 0



6.3  OLGA_NOTIFY
================


OLGA_NOTIFY
(Manager -> App)
msg[0] $1252 (4690)
msg[1] manID
msg[2] 0
msg[3]
    +  Pointer auf Dateinamen mit absolutem Pfad
msg[4]
msg[5] 0
msg[6] 0
msg[7] 0


Mit dieser Message teilt der Manager der Applikation mit, da eine
Datei verndert wurde. Falls die Applikation einen Link auf diese
Datei gesetzt hat, erhlt sie vorher auch noch eine OLGA_UPDATED-
Message!

Nach dem Empfang dieser Message mu die Applikation dem Manager
folgende Nachricht schicken:


OLGA_NOTIFIED
(App -> Manager)
msg[0] $1253 (4691)
msg[1] apID
msg[2] 0
msg[3] gleicher Wert wie in empfangener OLGA_NOTIFY-Message
msg[4] gleicher Wert wie in empfangener OLGA_NOTIFY-Message
msg[5] gleicher Wert wie in empfangener OLGA_NOTIFY-Message
msg[6] gleicher Wert wie in empfangener OLGA_NOTIFY-Message
msg[7] gleicher Wert wie in empfangener OLGA_NOTIFY-Message




7  Idle-Test
************

Mit dem Idle-Test knnen Server bzw. Clients und der Manager
gegenseitig feststellen, ob alle vorhergehenden OLGA-Messages
abgearbeitet wurden. Dazu wird folgende Message verschickt:


OLGA_IDLE
(Manager -> App, App -> Manager)
msg[0] $1249 (4681)
msg[1] manID
msg[2] 0
msg[3] 1
msg[4] reserviert
msg[5] reserviert
msg[6] reserviert
msg[7] reserviert


Als Antwort bekommt man (bzw. mu vom Client/Server an den Manager
geschickt werden) folgende Message:


OLGA_IDLE
(App -> Manager, Manager -> App)
msg[0] $1249 (4681)
msg[1] apID
msg[2] 0
msg[3] 0
msg[4] gleicher Wert wie in empfangener OLGA_IDLE-Message
msg[5] gleicher Wert wie in empfangener OLGA_IDLE-Message
msg[6] gleicher Wert wie in empfangener OLGA_IDLE-Message
msg[7] gleicher Wert wie in empfangener OLGA_IDLE-Message


Wenn eine Applikation den Idle-Test untersttzt, mu sie bei OLE_INIT
das passende Bit (OL_IDLE) setzen. Umgekehrt zeigt der OLGA-Manager
diese Fhigkeit bei OLGA_INIT und OLE_NEW an.



8  Konfigurationsabfrage
************************

Wenn eine Applikation globale Werte des OLGA-Managers abfragen mchte,
schickt sie ihm folgende Message:


OLGA_GETSETTINGS
(App -> Manager)
msg[0] $124e (4686)
msg[1] apID
msg[2] 0
msg[3] 0
msg[4] 0
msg[5] 0
msg[6] 0
msg[7] 0


Als Antwort bekommt man folgende Message. Die Felder msg[4..7] darf
man nur auswerten, wenn in msg[3] eine 1 eingetragen ist!


OLGA_SETTINGS
(Manager -> App)
msg[0] $124f (4687)
msg[1] manID
msg[2] 0
msg[3] 1=OK, 0=Fehler
msg[4] reserviert (z.Z. 0)
msg[5] reserviert (z.Z. 0)
msg[6] reserviert (z.Z. 0)
msg[7] reserviert (z.Z. 0)


Derzeit werden noch keine Manager-internen Daten zurckgeliefert!



9  Das OLGA-Info-Dateiformat
****************************

Info-Dateien erlauben den Austausch von spezielleren Informationen
zwischen Client und Server. Solche Dateien bestehen aus zwei Arten von
Datenstrukturen:


  OLGAInfHeader = record
    magic  : longint;  { 'OLGA' }
    version,           { z.Z. $0100 }
    skip   : word      { Anzahl der folgenden Headerbytes, die
                         berlesen werden mssen; z.Z. 0       }
  end;

  OLGABlockHeader = record
    id,              { Block-ID }
    length: longint  { Anzahl der folgenden Datenbytes }
  end;


Die Dateien sind folgendermaen aufgebaut:


  InfHeader
  BlockHeader 1
  Daten 1
  BlockHeader 2
  Daten 2
  ...
  BlockHeader n-1
  Daten n-1
  BlockHeader n (id=0)


Das Dateiende (und damit Block n) wird durch die ID 0 gekennzeichnet.
Folgende Block-IDs sind bereits definiert (es ist damit allerdings
nicht festgelegt, welche Blcke berhaupt bzw. in welcher Reihenfolge
gespeichert werden):

 $00000000 Dateiende (length sollte n.M. auch 0 sein)

 'REM ' Kommentar; die einzelnen Zeilen sind 0-terminiert, das Ende
     wird ber die Lnge erkannt (damit man auch Leerzeilen
     verschicken kann)

 'AUTH' Autor; Codierung siehe 'REM ', allerdings sollte man sich auf
     eine (0-terminierte) Zeile beschrnken

 'KEYW' Stichworte; Codierung s. 'REM '; innerhalb der Zeilen liegen
     die Stichworte durch Komma getrennt vor

 'DATE' Datum der letzten nderung als DOSTIME-Struktur

 'ICON' Ein mit der Datei bzw. derem Inhalt verknpftes Icon vom Typ
     G_ICON (nicht G_CICON!). Die Lnge des Blocks berechnet sich aus
     sizeof(ICONBLK) + 2*((ib_wicon+7) >> 3)*ib_hicon + (Lnge des
     Icontextes ohne Nullbyte) + 1. Der Block ist folgendermaen
     aufgebaut:

       1. ein kompletter ICONBLK; die Felder ib_pmask, ib_pdata und
          ib_ptext sollten vom Server auf NULL gesetzt werden und
          mssen vom Client ignoriert werden

       2. Maskendaten

       3. Bilddaten

       4. ein Byte, das die Lnge des Icontextes angibt (kann auch
          Null sein)

       5. der Icontext (falls Lngenbyte>0)

Unbekannte Blcke mssen ignoriert (d.h. berlesen) werden. D.h.
natrlich auch, da neue Block-IDs ohne Probleme angelegt werden
knnen - damit es nicht zu Kollisionen kommt, wre es nett, wenn ich
(Adresse s. "Kontakt") verstndigt wrde, dann kann ich die Block-ID
in obige Liste aufnehmen.



10  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.


10.1  Server
============

    OLE_INIT verschicken

    OLE_NEW auswerten

    OLGA_INIT empfangen

    OLE_EXIT verschicken

    VA_START untersttzen (s. Gemini-Doku, AV-Protokoll)

Damit der Server auch wirklich als solcher fungiert, mu natrlich
noch die Message OLGA_UPDATE verschickt werden.


10.2  Client
============

    OLE_INIT verschicken

    OLE_NEW auswerten

    OLGA_INIT empfangen

    OLE_EXIT verschicken

    auf OLGA_RENAMELINK mit OLGA_LINKRENAMED antworten

    auf OLGA_LINKBROKEN mit OLGA_UNLINK antworten

Ein Client sollte sinnvollerweise auch auf OLGA_UPDATED reagieren.



11  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 implementieren 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 (0721-358887) liegt das Archiv OLGA.LZH mit einem
OLGA-Manager. Mitgeliefert wird auch eine Debugversion, die alle
eingehenden (und auch einige der verschickten) Nachrichten mit ihren
Parametern direkt auf CON: schreibt, so da man recht einfach die
Kommunikation zwischen den beteiligten Applikationen berprfen kann.

Die OLGA-Disribution ist (auch fr kommerzielle Software) Freeware!

Diese Dokumentation wurde mit UDO5 geschrieben.

Alle Angaben ohne Gewhr, nderungen vorbehalten.




A  FAQ
******

  1. Wo bekomme ich die aktuellsten Informationen ber OLGA?

     Im WorldWideWeb. Adresse siehe "Kontakt".

  2. Ich besitze kein Multitaskingbetriebssystem wie MultiTOS, MagiC
     oder N.AES. Wie kann ich OLGA einsetzen?

     Leider gar nicht. Ohne Multitasking macht OLGA aber auch keinen
     Sinn, da nicht mehrere Hauptapplikationen gleichzeitig laufen
     knnen.

  3. Was mu ich tun, damit OLGA auf meinem 1MB Atari luft?

     Eine Speichererweiterung kaufen.

  4. Mein Programm kommt mit langen Dateinamen zurecht, die auch
     Kleinschreibung enthalten drfen. Drfen die Extensions in
     OLGA.INF ebenfalls klein geschrieben werden?

     Nein, alle Extensions (egal ob in OLGA.INF oder bei einer
     Message) mssen immer in Grobuchstaben angegeben werden.

  5. Wenn ich OLGA unter MiNT einsetze, bekomme ich eine
     Speicherschutzverletzung.

     Wie auch z.B. beim AV- und SE-Protokoll mssen in Pointern
     bergebene Speicherbereiche global lesbar sein, also mit
     Mxalloc() angefordert werden.

...wird bei Gelegenheit fortgesetzt.



B  Glossar
**********

 ActiveX

     Microsofts Objekt-Modell mit Internet-Technologien. Hie mal
     OLE/COM.

 Client

     Dienstenehmer

 ID4

     ID4-OLGA, "InplaceDrawing for OLGA"

 NULL

     Null-Pointer

 OLE

     Microsofts "Object Linking & Embedding"

 OLE/COM

     Microsofts "Component Object Model" samt einiger darauf
     aufbauender Technologien. Heit jetzt ActiveX.

 OLGA

     "Object Linking for GEM Applications"

 Server

     Dienstegeber

...wird ausgebaut.



C  Liste der OLGA-Applikationen
*******************************

Stand: 05. Dezember 1996


+-----------+-------+---------------------+--------+------+---------+----------+
| Programm  |  ab   | Autor               |  Cl.   | Srv. | ID4-Cl. | ID4-Srv. |
+-----------+-------+---------------------+--------+------+---------+----------+
| ArtWorx   |  1.0  | Christian Witt      |   *    |  *   |         | ab 1.14  |
+-----------+-------+---------------------+--------+------+---------+----------+
| CAB       |  1.2  | Alexander Clauss    |   *    |      |         |          |
+-----------+-------+---------------------+--------+------+---------+----------+
| Focus 3D  | 1.50  | Ralf Trinler        |        |  *   |         |          |
+-----------+-------+---------------------+--------+------+---------+----------+
| GEM-Look  | 12/95 | Rolf Kotzian        |   *    |      |         |          |
+-----------+-------+---------------------+--------+------+---------+----------+
| IdeaList  | 3.71  | Christoph Bartholme |   *    |      |         |          |
+-----------+-------+---------------------+--------+------+---------+----------+
| Kandinsky |  2.0  | Ulrich Rogoderer   |   *    |  *   |         |          |
+-----------+-------+---------------------+--------+------+---------+----------+
| Papillon  |  2.3  | Dirk Sabiwalsky     |        |  *   |         |          |
+-----------+-------+---------------------+--------+------+---------+----------+
| PixArt    | 3.32  | Mario Meiner       |        |  *   |         |          |
+-----------+-------+---------------------+--------+------+---------+----------+
| qed       | 3.90  | Christian Felsch    |        |  *   |         |          |
+-----------+-------+---------------------+--------+------+---------+----------+
| STELLA    |  2.0  | Thomas Knneth      |   *    |  *   |         |          |
+-----------+-------+---------------------+--------+------+---------+----------+
| Texel     |  1.0  | Thomas Much         | ab 1.5 |  *   | ab 1.5  |          |
+-----------+-------+---------------------+--------+------+---------+----------+

           Tabelle 2: Folgende Programme untersttzen OLGA



             +------------+------------+----------------+
             | Library    | ab Version | Autor          |
             +------------+------------+----------------+
             | OLGA-C-Lib |            | Thomas Knneth |
             +------------+------------+----------------+
             | ObjectGEM  | 1.21-beta  | Thomas Much    |
             +------------+------------+----------------+
             +------------+------------+----------------+

           Tabelle 3: Folgende Libraries untersttzen OLGA



                 +------------+------------+-------+
                 | Programm   | ab Version | Autor |
                 +------------+------------+-------+
                 | TempusWord |            | CCD   |
                 +------------+------------+-------+

Tabelle 4: Fr folgende Programme ist eine OLGA-Anpassung angekndigt




D  Dateien
**********


D.1  OLGA.H
===========


/* OLGA Rev 1.2 (11/20/96)                       */
/* Thomas_Much@ka2.maus.de                       */
/* http://www.uni-karlsruhe.de/~Thomas.Much/OLGA */

#ifndef OLGA_H
#define OLGA_H


#define OLE_INIT                 0x4950
#define OLE_EXIT                 0x4951
#define OLE_NEW                  0x4952

#define OLGA_INIT                0x1236
#define OLGA_UPDATE              0x1238
#define OLGA_ACK                 0x1239
#define OLGA_RENAME              0x123a
#define OLGA_OPENDOC             0x123b
#define OLGA_CLOSEDOC            0x123c
#define OLGA_LINK                0x123d
#define OLGA_UNLINK              0x123e
#define OLGA_UPDATED             0x123f
#define OLGA_RENAMELINK          0x1240
#define OLGA_LINKRENAMED         0x1241
#define OLGA_GETOBJECTS          0x1242
#define OLGA_OBJECTS             0x1243
#define OLGA_BREAKLINK           0x1244
#define OLGA_LINKBROKEN          0x1245
#define OLGA_START               0x1246
#define OLGA_GETINFO             0x1247
#define OLGA_INFO                0x1248
#define OLGA_IDLE                0x1249
#define OLGA_ACTIVATE            0x124a
#define OLGA_EMBED               0x124b
#define OLGA_EMBEDDED            0x124c
#define OLGA_UNEMBED             0x124d
#define OLGA_GETSETTINGS         0x124e
#define OLGA_SETTINGS            0x124f
#define OLGA_REQUESTNOTIFICATION 0x1250
#define OLGA_RELEASENOTIFICATION 0x1251
#define OLGA_NOTIFY              0x1252
#define OLGA_NOTIFIED            0x1253
#define OLGA_SERVERTERMINATED    0x1254
#define OLGA_CLIENTTERMINATED    0x1255
#define OLGA_INPLACEUPDATE       0x1256


#define OL_SERVER                0x0001
#define OL_CLIENT                0x0002
#define OL_PEER                  (OL_SERVER | OL_CLIENT)
#define OL_IDLE                  0x0800
#define OL_PIPES                 0x1000
#define OL_START                 0x2000
#define OL_MANAGER               0x4000
#define OL_OEP                   0x0001

#define OLS_TYPE                      1
#define OLS_EXTENSION                 2
#define OLS_NAME                      3


typedef struct
{
        int x,y,w,h,
            x1,y1,x2,y2;
} GRECT;


typedef struct
{
        long         magic;
        unsigned int version,
                     skip;
} OLGAInfHeader;


typedef struct
{
        long id,
             length;
} OLGABlockHeader;


typedef struct ObjectInfo
{
        char  *Filename;
        AESPB *ClientGEMPB;
        long   ClientData,
               ServerData;
        int    CBLock,
               CBCount;
        void   cdecl (*CBDraw)    (ObjectInfo *objectinfo,
                                   int outScreen,
                                   int outHandle,
                                   int outDevID,
                                   GRECT *Size,
                                   GRECT *Clip);
        void   cdecl (*CBUnembed) (ObjectInfo *objectinfo);
} OLGAObjectInfo;


#endif



D.2  OLGA.INC
=============


{* OLGA Rev 1.2 (11/20/96)                       *
 * Thomas_Much@ka2.maus.de                       *
 * http://www.uni-karlsruhe.de/~Thomas.Much/OLGA *}

const

        OLE_INIT                 = $4950;
        OLE_EXIT                 = $4951;
        OLE_NEW                  = $4952;

        OLGA_INIT                = $1236;
        OLGA_UPDATE              = $1238;
        OLGA_ACK                 = $1239;
        OLGA_RENAME              = $123a;
        OLGA_OPENDOC             = $123b;
        OLGA_CLOSEDOC            = $123c;
        OLGA_LINK                = $123d;
        OLGA_UNLINK              = $123e;
        OLGA_UPDATED             = $123f;
        OLGA_RENAMELINK          = $1240;
        OLGA_LINKRENAMED         = $1241;
        OLGA_GETOBJECTS          = $1242;
        OLGA_OBJECTS             = $1243;
        OLGA_BREAKLINK           = $1244;
        OLGA_LINKBROKEN          = $1245;
        OLGA_START               = $1246;
        OLGA_GETINFO             = $1247;
        OLGA_INFO                = $1248;
        OLGA_IDLE                = $1249;
        OLGA_ACTIVATE            = $124a;
        OLGA_EMBED               = $124b;
        OLGA_EMBEDDED            = $124c;
        OLGA_UNEMBED             = $124d;
        OLGA_GETSETTINGS         = $124e;
        OLGA_SETTINGS            = $124f;
        OLGA_REQUESTNOTIFICATION = $1250;
        OLGA_RELEASENOTIFICATION = $1251;
        OLGA_NOTIFY              = $1252;
        OLGA_NOTIFIED            = $1253;
        OLGA_SERVERTERMINATED    = $1254;
        OLGA_CLIENTTERMINATED    = $1255;
        OLGA_INPLACEUPDATE       = $1256;

        OL_SERVER                = $0001;
        OL_CLIENT                = $0002;
        OL_PEER                  = OL_SERVER or OL_CLIENT;
        OL_IDLE                  = $0800;
        OL_PIPES                 = $1000;
        OL_START                 = $2000;
        OL_MANAGER               = $4000;
        OL_OEP                   = $0001;

        OLS_TYPE                 =     1;
        OLS_EXTENSION            =     2;
        OLS_NAME                 =     3;


type

        GRECTPtr = ^GRECT;
        GRECT    = record
                X,Y,W,H,
                X1,Y1,X2,Y2: integer
        end;

        POLGAInfHeader = ^TOLGAInfHeader;
        TOLGAInfHeader = record
                Magic  : array [0..3] of char;
                Version,
                Skip   : word
        end;

        POLGABlockHeader = ^TOLGABlockHeader;
        TOLGABlockHeader = record
                ID    : array [0..3] of char;
                Length: longint
        end;

        POLGAObjectInfo = ^TOLGAObjectInfo;
        TOLGAObjectInfo = record
                Filename   : PChar;
                ClientGEMPB: AESPBPtr;
                ClientData,
                ServerData : longint;
                CBLock,
                CBCount    : integer;
                CBDraw     : procedure(d1,d2: pointer; d3,d4,d5: longint;
                                       objectinfo: POLGAObjectInfo;
                                       outScreen,
                                       outHandle,
                                       outDevID: integer;
                                       Size,
                                       Clip: GRECTPtr);
                CBUnembed  : procedure(d1,d2: pointer; d3,d4,d5: longint;
                                       objectinfo: POLGAObjectInfo);
        end;



D.3  OLGA.INF
=============


;Dies ist die OLGA-Manager-Konfigurationsdatei.
;Sie mu im Wurzelverzeichnis des Bootlaufwerks,
;in $HOME/defaults oder in $HOME stehen.

;ACHTUNG: Der Minimalmanager reagiert allergisch auf einen
;falschen Aufbau dieser Datei!!! Kommentare beginnen mit
;einem Semikolon am Zeilenanfang, Leerzeilen drfen nur
;aus CR/LF bestehen. Alle Eintrge mssen am Zeilenanfang
;stehen, zustzliche Leerzeichen o.. sind _nicht_ erlaubt.
;Programmnamen sind immer absolut, d.h. mit Pfad und Lauf-
;werk.

[Extensions]
;Wildcards sind nicht erlaubt!
;Extensions sind (mit Punkt) maximal vier Zeichen lang
.TAD=$ARTWORX
.CWG=$ARTWORX
.GEM=$ARTWORX
.CVG=$ARTWORX
.AI=$ARTWORX
.SDB=$STELLA
.TXL=$TEXEL
.DIF=$TEXEL
.CSV=$TEXEL
.XLS=$TEXEL
.HTM=$CAB
.TXT=$QED
.ASC=$QED
.IMG=$PAPILLON
.TIF=$PAPILLON
.JPG=$PAPILLON
.GIF=$PAPILLON

[Objects]
;zu den folgenden Extensions existieren ID4-Server
;die Extensions mssen auch im vorigen Abschnitt definiert sein!
.CWG=ArtWorx-Dokument
.CVG=Calamus-Dokument
.GEM=GEM Metafile
.AI=Adobe Illustrator-Dokument
.TAD=Texel-Diagramm

[Types]
;XAcc-Typen, siehe OLGAPROT.TXT; sie sind _exakt_ zwei
;Zeichen lang (Gro-/Kleinschreibung beachten!)
SS=$TEXEL
VG=$ARTWORX
RG=$PAPILLON
GG=$STELLA
ED=$QED

[Applications]
;hier werden Aliase festgelegt, die als Abkrzungen (mit einem
;fhrenden $, s.o.) verwendet werden /knnen/ (nicht mssen).
;Verschachtelungen sind erlaubt, aber man mu selbst darauf
;achten, keine Endlosschleifen zu erzeugen.
;Gro-/Kleinschreibung wird beachtet!
TEXEL=C:\Programm\PP\PRGS\texel.app
STELLA=C:\Programm\STELLA\STELLA.APP
ARTWORX=C:\Programm\ArtWorx\ARTWORX.PRG
IDEALIST=C:\Tools\IdeaList\IDEALIST.PRG
CAB=C:\Programm\WWW\CAB\CAB.APP
QED=C:\Diverses\qed\qed.app
PAPILLON=C:\Programm\PAPILLON\PAPILLON.PRG




E  History
**********

 Rev 1.2 (20.11.96)

         OLGA_CLIENTTERMINATED, OLGA_SERVERTERMINATED

         Idle-Test (OLGA_IDLE)

         Notification-Erweiterung (OLGA_REQUESTNOTIFICATION,
          OLGA_RELEASENOTIFICATION, OLGA_NOTIFY, OLGA_NOTIFIED)

         InplaceDrawing: "ID4-OLGA" (OLGA_GETOBJECTS, OLGA_OBJECTS,
          OLGA_ACTIVATE, OLGA_EMBED, OLGA_EMBEDDED, OLGA_UNEMBED,
          OLGA_INPLACEUPDATE, OLGAObjectInfo, CBDraw, CBUnembed)

         Konfigurationsabfrage (OLGA_GETSETTINGS, OLGA_SETTINGS)

 Rev 1.1 (24.07.96)

         neuer Block 'ICON' bei OLGA-Info-Dateien

         nach OLGA_OPENDOC wird OLGA_ACK verschickt

         OL_PEER

 Rev 1.0 (24.01.96)

         msg[6] des Kommandozeilen-OLGA_ACK nach OLGA_START angepat

         ab sofort wird Multitasking vorausgesetzt, die Messages
          OLGA_BLOCK und OLGA_UNBLOCK entfallen damit

 Rev 0.9 (10.11.95)

         die OLE-Messages haben neue Nummern bekommen

 Rev 0.8 (05.11.95)

         Konzept fr Info-Dateien, Dateiformat s.o.

         dafr Erweiterung von OLGA_UPDATE und OLGA_UPDATED

         neue Messages OLGA_GETINFO und OLGA_INFO

 Rev 0.7 (09.04.95)

         OLE-Initialisierung (OEP/OLGA)

         die OLGA_INIT-Message von der Applikation an den Manager
          wird durch OLE_INIT ersetzt

         der Manager bergibt in OLGA_INIT nicht mehr seinen Namen

         OLGA_EXIT heit nun OLE_EXIT, OLGA_NEW heit OLE_NEW

         bei OLGA_OPENDOC wird kein Dokumentname mehr bergeben

 Rev 0.6 (nicht ffentlich)

         Nachstarten des Managers (siehe OLGA_INIT) mit shel_write

         automatisches Terminieren

         OLGA_EXIT beim Manager-Shutdown

         OLGA_NEW

 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

 Davor...

     ...stand ein Erlebnis auf der ProTOS '94 in Hennef. Ulrich
     Rogoderer, Thomas Knneth und ich zeigten auf dem Stand von
     Delta Labs unsere Shareware, die zu dieser Zeit in der
     Whiteline-Serie verkauft wurde. Uli und Tommi hatten zwischen
     Kandinsky und STELLA einen Update- Mechanismus eingerichtet, der
     dasselbe Ergebnis wie OLGA_UPDATE erzielte. Dieser Mechanismus
     hatte allerdings den Nachteil, da der Server irgendwie bekannt
     sein mute und nicht automatisch von einem Manager gesucht wurde.

     Da ich damals gerade einen ObjectLinking-Mechanismus fr
     ObjectGEM plante (GOLEM), um ihn als Grundlage fr Texel (das
     damals in einer ganz frhen Alpha-Version vorlag) verwenden zu
     knnen, bot es sich an, beide Ideen zu kombinieren. So entstand
     OLGA.



F  Knftige Weiterentwicklungen
*******************************

Zwei groe Aufgaben sind 1997 zu lsen. Zum einen sollte das
InplaceDrawing zu InplaceActivation ausgebaut werden, d.h. der
Benutzer sollte fremde Dokumente in einer Applikation nicht nur
angezeigt bekommen, sondern sie auch dort direkt bearbeiten knnen -
mit den Routinen des ID4-Servers.

Zum anderen ist es berlegenswert, GEM ein Objekt-Modell zur Verfgung
zu stellen, um solche Aktionen wie ID4 und InplaceActivation zu
verallgemeinern. Denkbar wre so ein "GEM Component Object Model"
(GCOM) beispielsweise auf der Grundlage von OLE/COM bzw. ActiveX.
Weitere Informationen dazu liegen im Web auf http://www.activex.org.

Fr Programmierer gibt es eine OLGA-Mailingliste, um diese
Erweiterungen diskutieren (und allgemeine Fragen zu OLGA beantworten)
zu knnen. Wer daran teilnehmen mchte, meldet sich bitte bei mir
(siehe "Kontakt").



G  Kontakt
**********


Thomas Much, Gerwigstrae 46, D-76131 Karlsruhe, Germany

Fax:       +49 / (0)721 / 62 28 21

EMail:     Thomas Much @ KA2                 (MausNet)
           Thomas_Much@ka2.maus.de
           Thomas.Much@stud.uni-karlsruhe.de (Internet)

WWW:       http://www.uni-karlsruhe.de/~Thomas.Much/OLGA

Newsgroup: OLGA @ ASH (+49 / (0)6221 / 30 36 71)



H  Rechtliches
**************

Der OLGA-Manager ist mit allen zugehrigen Dateien Freeware - dies
wird auch in Zukunft so bleiben. Er darf auch einzeln und auch mit
kommerziellen Programmen ohne Zahlung von Lizenzgebhren weitergegeben
werden! Gegen einen Hinweis in der Distribution auf den Autor und die
OLGA-Homepage bzw. eine Benachrichtigung an mich (s. "Kontakt") im
Falle einer solchen Nutzung htte ich allerdings nichts einzuwenden.

Da OLGA ein Standard sein soll, wre es schn, wenn niemand das
Protokoll eigenmchtig verndert, sondern alle Erweiterungswnsche mit
mir abspricht.

Die Haftung fr Schden, die sich mittelbar oder unmittelbar aus der
Nutzung dieser Dokumentation und des OLGA-Paketes ergeben, ist
ausgeschlossen.

Alle Angaben ohne Gewhr, nderungen vorbehalten.



I  Dank
*******

Ein besonderer Dank geht an

    Ulrich "Kandinsky" Rogoderer fr die Untersttzung bei der
     Definition von OLGA

    Thomas "STELLA" Knneth fr die Untersttzung bei der Definition
     von OLGA, fr seinen "OLGAnisator", seine OLGA-C-Library sowie
     fr sein Drngeln bei der Notification-Erweiterung

    Christian "ArtWorx" Witt fr die Mitarbeit bei InplaceDrawing
     (ID4-OLGA)

    Dirk "U." Hagedorn fr UDO5.




