                 Object Linking for GEM Applications

                             OLGA Rev 1.3

                          30. November 1997

                                 von

                             Thomas Much


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

 1  Einleitung

 2  Was ist Object Linking?
    2.1  Die OLGA-Architektur

 3  Installation des OLGA-Managers
    3.1  OLGA-Tools

 4  Das OLGA-Protokoll...
    4.1  ...als Minimalversion
         4.1.1  Server
         4.1.2  Client
    4.2  ...fr Server und Client
         4.2.1  Nachstarten des OLGA-Managers
         4.2.2  OLE_INIT
         4.2.3  OLGA_INIT
         4.2.4  OLE_EXIT
         4.2.5  OLE_NEW
    4.3  ...aus der Sicht des Servers
         4.3.1  OLGA_UPDATE
         4.3.2  OLGA_GETINFO
         4.3.3  OLGA_INFO
         4.3.4  OLGA_RENAME
         4.3.5  OLGA_BREAKLINK
         4.3.6  OLGA_CLIENTTERMINATED
    4.4  ...aus der Sicht des Clients
         4.4.1  OLGA_OPENDOC
         4.4.2  OLGA_CLOSEDOC
         4.4.3  OLGA_LINK
         4.4.4  OLGA_UNLINK
         4.4.5  OLGA_UPDATED
         4.4.6  OLGA_RENAMELINK
         4.4.7  OLGA_LINKRENAMED
         4.4.8  OLGA_LINKBROKEN
         4.4.9  OLGA_START
         4.4.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.1.4  OLGA_ID4UPDATE
         5.1.5  cbColorTable
         5.1.6  cbClientID
    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
         5.2.6  CBXDraw
         5.2.7  cbServerID

 6  Notification
    6.1  OLGA_REQUESTNOTIFICATION
    6.2  OLGA_RELEASENOTIFICATION
    6.3  OLGA_NOTIFY

 7  Idle-Test

 8  Konfigurationsabfrage
    8.1  OLGA_GETSETTINGS
    8.2  OLGA_GETSERVERPATH
    8.3  OLGA_GETEXTENSION

 9  Das OLGA-Info-Dateiformat

10  Abschlieende Hinweise


Anhang
======

 A  FAQ

 B  Glossar

 C  Liste der OLGA-Applikationen

 D  Extensions

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

 F  History

 G  Knftige Weiterentwicklungen

 H  Kontakt

 I  Rechtliches

 J  Dank



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

Dies ist die Anleitung zu OLGA 1.3, d.h. zum OLGA-Protokoll Revision
1.3 und zum OLGA-Manager Version 1.30 (beides vom 30.11.97).

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 mit dem
OLE- (wird fr die Initialisierung verwendet) und OLGA-Protokoll (ist
fr das eigentliche Object Linking zustndig) nun zur Verfgung steht.

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 (Minimalprotokoll).


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. Starten Sie Ihren Rechner
neu und berprfen Sie mit den OLGA-Tools, ob die Installation
erfolgreich war.


3.1  OLGA-Tools
===============

Mit dem Programm "OLGA-Tools" knnen Sie eine bestehende OLGA-
Installation komfortabel und einfach bearbeiten. Auerdem kann man per
Knopfdruck berprfen lassen, ob alle Programmangaben etc. in OLGA.INF
korrekt sind.

Dieser Abschnitt beschreibt das Arbeiten mit den OLGA-Tools in der
Version 1.00 vom 30.11.1997. Derzeit ist "nur" das berprfen der
Installation, nicht aber das Einrichten des OLGA-Managers mglich -
dazu wird immer noch ein externer Editor bentigt.

----------------------------------------------------------------------

Um OLGA.INF zu berprfen, starten Sie die OLGA-Tools und rufen den
Dialog "Optionen - berprfen..." auf. Derzeit knnen Sie nur OLGA.INF
auf fehlerhafte Eintrge berprfen lassen, weitere Optionen werden in
einer spteren Version folgen.

Wenn Sie das Ergebnis der berprfung als Bugreport verwenden wollen,
schalten Sie bitte auch "Systeminformationen ausgeben" ein. Dadurch
werden die wichtigsten Eigenschaften und Versionsnummern Ihres Systems
nach dem Prfbericht ausgegeben.

Durch Anwhlen von "OK" wird die berprfung gestartet. Es erscheint
ein Ausgabefenster, in dem eventuelle Fehlermeldungen (mit der
Zeilenangabe in OLGA.INF) ausgegeben werden. Wenn Sie diese Liste
durcharbeiten, knnen Sie Ihre OLGA.INF nach und nach korrigieren.
Wenn als Anzahl der Fehler und Warnungen jeweils Null ausgegeben
wurde, ist Ihre OLGA.INF korrekt.

Sollten Sie zu Beginn der berprfung mit einer Dateiauswahlbox nach
Ihrer OLGA.INF gefragt werden, ist dies kein gutes Zeichen... In
diesem Fall ist nicht garantiert, da der OLGA-Manager die von Ihnen
gewnschte Datei auch wirklich findet und auswertet. Optimale Orte fr
OLGA.INF sind $HOME oder das Boot-Wurzelverzeichnis.



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


4.1  ...als Minimalversion
==========================

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


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


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


4.2  ...fr Server und Client
=============================

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

  1. Wenn appl_find("OLGA    ") erfolgreich ist, hat man den Manager
     schon gefunden.

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

  3. Wenn das bisherige nicht zum Erfolg gefhrt hat, kann man die
     ersten beiden Punkte nochmal mit einem appl_find("OLEMANGR") bzw.
     der Environmentvariablen OLEMANAGER durchfhren. Dieser Punkt ist
     aber mittlerweile obsolet und kann daher auch problemlos
     ignoriert werden.

Hat man die AES-ID des OLGA-Managers gefunden, wird dieser zunchst
mit dem OLE-Protokoll initialisiert.


4.2.1  Nachstarten des OLGA-Managers
------------------------------------

In diesem Abschnitt gibt es einen Algorithmus zum Finden bzw.
Nachstarten des OLGA-Manager als Pseudo-Pascal-Code, der mit MagiC,
MultiTOS etc. funktioniert.

----------------------------------------------------------------------


OLGAManager:=appl_find('OLGA    ');

if (OLGAManager < 0) then
  begin
    envstr:=GetEnv('OLGAMANAGER');

    if (length(envstr) > 0) then
      begin
        // Dateinamen in Grobuchstaben und ohne Extension
        // aus envstr extrahieren
        datei:=StrPUpper(GetFilename(envstr,false));

        // Dateinamen evtl. mit Leerzeichen auffllen, damit
        // der Name exakt acht Zeichen lang ist
        datei:=datei+StrPSpace(8-length(datei));

        OLGAManager:=appl_find(datei);

        if (OLGAManager < 0) then
          begin
            // der Manager luft noch nicht, wir mssen
            // ihn also nachstarten

            OLGAManager:=StartApp(datei);
          end
      end
  end;

if (OLGAManager >= 0) then
  begin
    // OLE_INIT an OLGAManager schicken
  end;


----------------------------------------------------------------------


function StartApp(prg: string): integer;

  begin
    ret:=-1;

    if (MultiTOS or MagiC) then
      if (Exist(prg)) then
        begin
          if MagiC then ret:=shel_write(1,100,@prg,NULL)
          else
            ret:=shel_write(0,1,@prg,NULL);
        end;

    StartApp:=ret;
  end;


----------------------------------------------------------------------


4.2.2  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] Bitmap, OL_SERVER und/oder OL_CLIENT gesetzt, OL_PIPES
msg[4] max. von der App. verstandene Stufe des Protokolls
       (z.Z. immer 0)
msg[5] reserviert (auf 0 setzen)
msg[6] reserviert (auf 0 setzen)
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 Verfahren wird z.Z. noch nicht unter-
                    sttzt, eine genauere Definition folgt spter


Daraufhin erhlt man vom Manager eine OLGA_INIT-Message.


4.2.3  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.2.4  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.2.5  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] Bitmap (OL_MANAGER, OL_START, OL_PIPES, OL_IDLE)
msg[4] max. Manager-Stufe des OLGA-Protokolls
msg[5] reserviert (auf 0 setzen)
msg[6] reserviert (auf 0 setzen)
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 OLGA_INIT, sie dienen nur zu Informationszwecken!


4.3  ...aus der Sicht des Servers
=================================


4.3.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.3.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.3.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.3.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 nach der OLGA_RENAME-Message 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.3.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.3.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] 1, wenn der Server bei OLGA_START schon lief; 0 sonst



4.4  ...aus der Sicht des Clients
=================================


4.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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(r) Programm(typ) gestartet werden soll
[5] (abhngig von [3], s.u.)
[6]
 +  Pointer auf Kommandozeile (i.A. 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.4.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);
                void   cdecl (*CBXDraw)   (ObjectInfo *objectinfo,
                                           int    outScreen,
                                           int    outHandle,
                                           int    outDevID,
                                           GRECT *Size,
                                           GRECT *Clip,
                                           long   Width_mm1000,
                                           long   Height_mm1000,
                                           long   Scale);
                OLGAColorTable *cbColorTable;
                int    cbClientID;
                int    cbServerID;
        } 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; die Datei mu nicht existieren, der Server
sollte in diesem Fall ein neues Dokument anlegen), ClientGEMPB (ein
Pointer auf die Struktur, die Pointer zu den GEM-Arrays global[] etc.
enthlt), ClientData (beliebige Client-Daten), CBLock (konstant auf
-16000), CBCount (Anzahl der folgenden 32bit-Langworte; derzeit 5),
cbClientID (auf die eigene AES-ID) sowie cbServerID (-1) und nullt
alle anderen Felder aus. Danach schickt der Client dem Manager
folgende Message:


OLGA_EMBED
(Client->Manager)
msg[0] $124b (4683)
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 (4684)
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.1.4  OLGA_ID4UPDATE
---------------------

Nachdem ein Client CBUnembed() aufgerufen hat, sollte er dem Server
auch folgende Nachricht schicken, damit dieser auch auf AES-Ebene
Aktualisierungen von z.B. Client-Listen durchfhren kann (was
innerhalb des Callbacks schlecht bzw. nur umstndlich mglich ist).


OLGA_ID4UPDATE
(Client->Server)
msg[0] $1257 (4695)
msg[1] clientID
msg[2] 0
msg[3] 0
msg[4] 0
msg[5] 0
msg[6] 0
msg[7] 0



5.1.5  cbColorTable
-------------------

Wenn der ID4-Client eine eigene Farbpalette zum Zeichnen seines
Dokuments verwendet, kann er diese Palette an den ID4-Server
bergeben, indem er in cbColorTable einen Zeiger auf folgende Struktur
eintrgt:


        typedef struct
        {
                int Count;
                RGB Colors[];
        } OLGAColorTable;

        typedef struct
        {
                int Red;
                int Green;
                int Blue;
        } RGB;


Zulssige Werte fr Count sind 16 und 256.

Wenn der Server die jeweils aktuelle (d.h. beim Aufruf von CBDraw oder
CBXDraw eingestellte) Farbpalette verwenden soll, nullt der Client
cbColorTable einfach aus (Standardwert).

Wichtig: Ein ID4-Server darf cbColorTable nur auswerten, wenn
CBCount>=4 ist!


5.1.6  cbClientID
-----------------

Wird vom Client vor dem Verschicken von OLGA_EMBED auf die eigene
AES-ID gesetzt. Dadurch mu der Server diesen Wert nicht umstndlich
ermitteln.


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 (er kann aber seine
Ausgabe an die Farbpalette des Clients anpassen, wenn diese in
cbColorTable bergeben wird). 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 (wenn
diese Datei nicht existiert, sollte ein neues Dokument mit diesem
Namen geffnet werden), setzt CBLock auf Null und trgt in CBDraw den
Pointer auf seine Zeichenroutine ein (nach Mglichkeit auch in
CBXDraw, falls CBCount>=3). In CBUnembed kann der Server eine Routine
eintragen, die vom Client beim Auflsen der ID4-Verknpfung aufgerufen
wird. Falls CBCount>=5 ist, sollte der Server schlielich auch noch
cbServerID auf seine AES-ID setzen.

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


5.2.6  CBXDraw
--------------

C-Notation:

        void cdecl (*CBXDraw) (ObjectInfo *objectinfo,
                               int    outScreen,
                               int    outHandle,
                               int    outDevID,
                               GRECT *Size,
                               GRECT *Clip,
                               long   Width_mm1000,
                               long   Height_mm1000,
                               long   Scale);

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

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


CBXDraw entspricht im wesentlichen CBDraw, allerdings ist mit den
folgenden Parametern eine genauere Ausgabe mglich:

    Width_mm1000 enthlt die in 1/1000 mm umgerechnete Breite des
     Objekts aus Size.w

    Height_mm1000 enthlt die in 1/1000 mm umgerechnete Hhe des
     Objekts aus Size.h

    Scale gibt an, welchen Skalierungsfaktor der Client bei der
     Ausgabe verwendet (10000L=100%). Dies kann der Server z.B. zur
     korrekten Fontgrenberechnung verwenden.

Ein ID4-Server darf seinen CBXDraw()-callback nur dann in ObjectInfo
eintragen, wenn CBCount>=3 ist. Ein ID4-Client darf CBXDraw()
natrlich nur dann aufrufen, wenn dort kein NULL-Pointer eingetragen
ist.

Wichtig: Ein ID4-Server, der CBXDraw() untersttzt, mu auch CBDraw()
untersttzen!


5.2.7  cbServerID
-----------------

Wird vom Client vor dem Verschicken von OLGA_EMBED auf -1 gesetzt. Der
Server trgt hier vor dem Verschicken von OLGA_EMBEDDED seine AES-ID
ein.



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


8.1  OLGA_GETSETTINGS
=====================

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!


8.2  OLGA_GETSERVERPATH
=======================

Falls man doch einmal eine OLGA-Server-Applikation direkt ansprechen
mchte (aus welchem Grund auch immer...), kann man mit dieser
Nachricht den Server fr eine gegebene Extension erfragen:


OLGA_GETSERVERPATH
(Client -> Manager)
msg[0] $125a (4698)
msg[1] clientID
msg[2] 0
msg[3]
    +  Extension (z.B. ".TIF")
msg[4]
msg[5] 0
msg[6] 0
msg[7] 0


Als Antwort erhlt der Client die Nachricht OLGA_SERVERPATH. Falls zu
der gewnschten Extension ein Server definiert ist, wird dessen
Pfad+Dateiname in msg[5/6] zurckgeliefert, ansonsten sind diese
beiden Eintrge ausgenullt. Wenn ein Server existiert, wird durch Bit
0 von msg[7] angezeigt, ob der Server gleichzeitig auch ID4-Server
ist.


OLGA_SERVERPATH
(Manager -> Client)
msg[0] $125b (4699)
msg[1] manID
msg[2] 0
msg[3]
    +  gleiche Extension wie in OLGA_GETSERVERPATH
msg[4]
msg[5]
    +  Pointer auf den Dateinamen des Servers (incl. Pfad) oder NULL
msg[6]
msg[7] Bitmap aus OL_SRV_xxx-Konstanten

OL_SRV_ID4 = $0001   Server ist auch ID4-Server


Wenn in msg[5/6] ein Serverpfad geliefert wurde, mu der Client dem
Manager abschlieend noch folgende Message schicken, damit der Manager
den reservierten Speicher wieder freigeben kann.


OLGA_ACK
(Client -> Manager)
msg[0] $1239 (4665)
msg[1] clientID
msg[2] 0
msg[3] 0
msg[4] 0
msg[5]
    +  exakt dieselben Werte aus OLGA_SERVERPATH
msg[6]
msg[7] OLGA_SERVERPATH



8.3  OLGA_GETEXTENSION
======================

OLGA bietet die Mglichkeit, aus einem gegebenen Dateinamen eine
korrekte Extension im Format ".???" (d.h. maximal drei Zeichen und in
Grobuchstaben) zu extrahieren. Dazu schickt man dem Manager folgende
Nachricht:


OLGA_GETEXTENSION
(App -> Manager)
msg[0] $1258 (4696)
msg[1] apID
msg[2] 0
msg[3]
    +  Pointer auf den Dateinamen (optional incl. Pfadangabe)
msg[4]
msg[5] 0
msg[6] 0
msg[7] 0


Als Antwort erhlt die Applikation folgende Nachricht:


OLGA_EXTENSION
(Manager -> App)
msg[0] $1259 (4697)
msg[1] manID
msg[2] 0
msg[3]
    +  gleiche Werte wie in OLGA_GETEXTENSION
msg[4]
msg[5]
    +  Extension (z.B. ".JPG"), evtl. mit Nullbytes aufgefllt
msg[6]
msg[7] 1: a) Datei hat keine Extension (msg[5/6] sind dann
             ausgenullt)
          b) Extension ist zu lang, und es gibt keine bekannte
             Kurzform; in msg[5/6] sind dann die ersten vier
             Zeichen (incl. Punkt) der Extension eingetragen
       0: Extension konnte korrekt gekrzt werden (falls ntig)


Derzeit werden die Extensions ".jpeg", ".mpeg", ".aiff", ".html",
".class" und ".tiff" korrekt gekrzt.



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  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-Distribution ist (auch fr kommerzielle Software) Freeware!

Diese Dokumentation wurde mit UDO6 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: 30. November 1997


+--------------+-------+-----------------+-----+------+---------+----------+
| Programm     |  ab   | Autor           | Cl. | Srv. | ID4-Cl. | ID4-Srv. |
+--------------+-------+-----------------+-----+------+---------+----------+
| Alert Help   |  1.2  | Matthias Jaap   |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| Alta Lista   |  1.3  | Matthias Jaap   |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| ArtWorx      |  1.0  | Christian Witt  |  *  |  *   |   1.4   |   1.14   |
+--------------+-------+-----------------+-----+------+---------+----------+
| Bellini      | 01/97 | Ingo Dehne      |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| CAB          |  1.2  | A. Clauss       |  *  | 2.5  |   2.0   |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| E.C.I.       |  1.2  | Matthias Jaap   |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| Everest      | 12/96 | Oliver Schmidt  |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| Focus 3D     | 1.50  | Ralf Trinler    |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| GEMJing      | 1.03  | Gtz Hoffart    |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| GEM-Look     | 12/95 | Rolf Kotzian    |  *  |      |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| Gleichungen  |  1.2  | Matthias Jaap   |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| HP-Pinguin   | 1.65  | Matthias Jaap   | 2.0 |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| IdeaList     | 3.71  | Chr. Bartholme  |  *  |      |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| JAnE         | 1.50  | Harald Becker   |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| JingleFALCON | 1.41  | Erik Hall       |  *  |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| Kandinsky    |  2.0  | U. Rogoderer   |  *  |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| Papillon     |  2.3  | Dirk Sabiwalsky |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| Papyrus      |  5.5  | R.O.M.          |  *  |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| Phoenix      |  5.0  | D.+J. Gei      |  *  |      |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| PixArt       | 3.32  | Mario Meiner   |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| qed          | 3.90  | Chr. Felsch     |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| Roman        |  1.2  | Matthias Jaap   |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| STELLA       |  2.0  | Thomas Knneth  |  *  |  *   |         |   2.61   |
+--------------+-------+-----------------+-----+------+---------+----------+
| Texel        |  1.0  | Thomas Much     | 1.5 |  *   |   1.5   |          |
+--------------+-------+-----------------+-----+------+---------+----------+
| XURL         | 2.40  | Gary Priest     |     |  *   |         |          |
+--------------+-------+-----------------+-----+------+---------+----------+

             Tabelle 2: Diese Programme untersttzen OLGA



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

             Tabelle 3: Diese Libraries untersttzen OLGA




D  Extensions
*************


 +----------+----------+-------------------------+------------------+
 | Kurzform | Langform | Beschreibung            | Server/Client    |
 +----------+----------+-------------------------+------------------+
 | .AI      |          | Adobe Illustrator       | ArtWorx          |
 +----------+----------+-------------------------+------------------+
 | .AIF     | .aiff    |                         |                  |
 +----------+----------+-------------------------+------------------+
 | .ASC     |          | ASCII-Text              | Everest, qed     |
 +----------+----------+-------------------------+------------------+
 | .AU      |          |                         | GEMJing          |
 +----------+----------+-------------------------+------------------+
 | .CLA     | .class   | Java-Klasse             |                  |
 +----------+----------+-------------------------+------------------+
 | .CSV     |          |                         | Texel            |
 +----------+----------+-------------------------+------------------+
 | .CVG     |          | Calamus-Vektorgrafik    | ArtWorx          |
 +----------+----------+-------------------------+------------------+
 | .CWG     |          | ArtWorx-Dokument        | ArtWorx          |
 +----------+----------+-------------------------+------------------+
 | .DIF     |          |                         | Texel            |
 +----------+----------+-------------------------+------------------+
 | .GEM     |          | GEM-Metafile            | ArtWorx          |
 +----------+----------+-------------------------+------------------+
 | .GIF     |          |                         | Papillon         |
 +----------+----------+-------------------------+------------------+
 | .HDU     |          | Hard Disk Utility       |                  |
 +----------+----------+-------------------------+------------------+
 | .HTM     | .html    |                         | CAB              |
 +----------+----------+-------------------------+------------------+
 | .IMG     |          | GEM-(X)IMG-Rastergrafik | STELLA           |
 +----------+----------+-------------------------+------------------+
 | .INC     |          | Pascal-Include          |                  |
 +----------+----------+-------------------------+------------------+
 | .JPG     | .jpeg    |                         | Papillon, STELLA |
 +----------+----------+-------------------------+------------------+
 | .MOV     |          |                         |                  |
 +----------+----------+-------------------------+------------------+
 | .MPG     | .mpeg    |                         |                  |
 +----------+----------+-------------------------+------------------+
 | .PAS     |          | Pascal-Source           |                  |
 +----------+----------+-------------------------+------------------+
 | .PS      |          | PostScript-Dokument     |                  |
 +----------+----------+-------------------------+------------------+
 | .SDB     |          | STELLA-Datenbank        | STELLA           |
 +----------+----------+-------------------------+------------------+
 | .TAD     |          | Diagrammdatei           | ArtWorx, Texel   |
 +----------+----------+-------------------------+------------------+
 | .TIF     | .tiff    |                         | Papillon, STELLA |
 +----------+----------+-------------------------+------------------+
 | .TXL     |          | Texel-Rechenblatt       | Texel            |
 +----------+----------+-------------------------+------------------+
 | .TXT     |          | ASCII-Text              | Everest, qed     |
 +----------+----------+-------------------------+------------------+
 | .WAV     |          |                         | GEMJing          |
 +----------+----------+-------------------------+------------------+
 | .WRL     |          | VRML                    |                  |
 +----------+----------+-------------------------+------------------+
 | .XBM     |          | X-Bitmap-Grafik         |                  |
 +----------+----------+-------------------------+------------------+
 | .XLS     |          | Excel-Rechenblatt       | Texel            |
 +----------+----------+-------------------------+------------------+



E  Dateien
**********


E.1  OLGA.H
===========


/* OLGA Rev 1.3 (97-11-30)                       */
/* 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 OLGA_ID4UPDATE           0x1257
#define OLGA_GETEXTENSION        0x1258
#define OLGA_EXTENSION           0x1259
#define OLGA_GETSERVERPATH       0x125a
#define OLGA_SERVERPATH          0x125b


#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

#define OL_SRV_ID4               0x0001


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


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


typedef struct
{
        long id;
        long length;
} OLGABlockHeader;


typedef struct
{
        int Red;
        int Green;
        int Blue;
} RGB;


typedef struct
{
        int Count;
        RGB Colors[];
} OLGAColorTable;


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


#endif



E.2  OLGA.INC
=============


{* OLGA Rev 1.3 (97-11-30)                       *
 * 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;
        OLGA_ID4UPDATE           = $1257;
        OLGA_GETEXTENSION        = $1258;
        OLGA_EXTENSION           = $1259;
        OLGA_GETSERVERPATH       = $125a;
        OLGA_SERVERPATH          = $125b;

        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;

        OL_SRV_ID4               = $0001;


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;

        PRGB = ^TRGB;
        TRGB = record
                Red,
                Green,
                Blue : integer
        end;

        POLGAColorTable = ^TOLGAColorTable;
        TOLGAColorTable = record
                Count : integer;
                Colors: array [0..255] of TRGB
        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);
                CBXDraw     : procedure(d1,d2: pointer; d3,d4,d5: longint;
                                        objectinfo: POLGAObjectInfo;
                                        outScreen,
                                        outHandle,
                                        outDevID  : integer;
                                        Size,
                                        Clip      : GRECTPtr;
                                        Width_mm1000,
                                        Height_mm1000,
                                        Scale     : longint);
                cbColorTable: POLGAColorTable;
                cbClientID,
                cbServerID  : integer
        end;



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




F  History
**********

 Rev 1.3 (30.11.97)

         OLGA_CLIENTTERMINATED erweitert (msg[7])

         OLGA_GETSERVERPATH, OLGA_SERVERPATH

         OLGA_GETEXTENSION, OLGA_EXTENSION

         OLGA_ID4UPDATE

         CBXDraw, cbColorTable, cbClientID, cbServerID

         dokumentiert, da Dateien bei OLGA_EMBED nicht existieren
          mssen

         Manager: Erkennung von MultiTOS, N.AES und MagiC verbessert

         Manager: fehlertoleranter beim Einlesen von OLGA.INF

 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.



G  Knftige Weiterentwicklungen
*******************************

Zwei groe Aufgaben sind 1998 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.

Im Zusammenhang mit GEMScript drfte auch die Entwicklung von GDBC
("GEM Database Connectivity") wichtig und ntzlich sein.

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").



H  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
           http://thmuch.home.pages.de

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



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



J  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)

    Alexander Lorenz fr die Zusammenarbeit beim OLE-Protokoll

    Mickael Cousin fr die franzsische bersetzung der OLGA-Homepage

    Mille Babic fr die schwedische OLGA-Seite im Web

    Dirk "U." Hagedorn fr UDO6.




