ATOS - Around The Operating System Das ATOS-Magazin 2/96

# OLGA 6/7

Client-Messages

Wenn ein OLGA-Client ein Dokument öffnet (z.B. mit "Datei - Neu" oder "Datei - Öffnen..."), muß dem OLGA-Manager folgende Message geschickt werden. Die Gruppenkennung bezeichnet dabei eine beliebige, aber innerhalb des Clients eindeutige Zahl, mit der der Client und der Server das Dokument eindeutig identifizieren können - schließlich ist es möglich, daß eine Datei innerhalb eines Clients mehrfach, nur in verschiedenen Dokumenten, eingebunden ist. Falls ein Client nur ein Dokument gleichzeitig bearbeiten kann (IdeaList hat z.B. immer nur eine Datei geladen), kann man hier eine Null übergeben.

    OLGA_OPENDOC
    (Client -> Manager)
    msg[0] $123b (4667)
    msg[1] apID
    msg[2] 0
    msg[3] 0
    msg[4] 0
    msg[5] Gruppenkennung
    msg[6] 0
    msg[7] 0

Schließt ein Client ein Dokument, wird dem Manager folgende Message geschickt, die automatisch alle Links mit der entsprechenden Gruppenkennung gelöscht. Wichtig: Beim Programmende darf man diese Message nicht verschicken, da OLE_EXIT alle Gruppenkennungen freigibt!

    OLGA_CLOSEDOC
    (Client -> Manager)
    msg[0] $123c (4668)
    msg[1] apID
    msg[2] 0
    msg[3] 0
    msg[4] 0
    msg[5] Gruppenkennung
    msg[6] 0
    msg[7] 0

Das eigentliche "Object Linking" geschieht mit folgender Message. Wenn der Client eine fremde Datei in eines seiner Dokumente einbettet, muß er sich intern den Dateinamen mit absolutem Pfad merken und mit OLGA_LINK einen Link darauf setzen. Wird die Datei von einem OLGA-Server verändert, erhält der Client dann eine OLGA_UPDATED-Message.

Möchte der Client nicht nur ein Linking, sondern auch ein Embedding realisieren, muß er nicht nur den Dateinamen der eingebetteten Datei im Dokument speichern, sondern auch die gesamte Datei. Das bläht die Dokumente zwar ziemlich auf, hat aber den Vorteil, daß man solche Dateien sehr einfach weitergeben kann, da _alle_ Daten im Dokument gespeichert sind.

Wird ein Dokument geladen, das eingebettete Dateien enthält, muß der Client nach dem Laden und Öffnen des Dokuments (siehe OLGA_OPENDOC) auf alle eingebetteten Objekte, die ja mit ihrem Dateinamen gespeichert wurden, einen Link auf die zugehörige Datei setzen. Wird ein Dokument auf einem fremden System geöffnet, bei dem die eingebetteten Dateien nicht auf Platte vorhanden sind, kann ein Linking-Client diese Dateien auch nicht anzeigen - dem Anwender sollte dies z.B. durch ein leeres Rechteck o.ä. im Dokument angezeigt werden. Ein Embedding-Client hat alle notwendigen Daten im Dokument gespeichert und kann z.B. die Grafiken (allgemeiner: Objekte) trotzdem anzeigen.

Beim Doppelklick auf ein eingebettetes Objekt sollte die entsprechende Datei per OLGA_START (s.u.) geöffnet werden, damit der Anwender diese Datei im zugehörigen Server bearbeiten kann. Ein Embedding-Client sollte vorher noch prüfen, ob die zu öffnende Datei überhaupt vorhanden ist. Im negativen Fall sollte er die im Dokument gespeicherte Datei auf Platte ablegen (unter einem automatisch generierten temporären Namen), den alten Link mit OLGA_UNLINK löschen und einen neuen Link auf die temporäre Datei setzen.

    OLGA_LINK
    (Client -> Manager)
    msg[0] $123d (4669)
    msg[1] apID
    msg[2] 0
    msg[3]
        +  Pointer auf den Dateinamen, der überwacht werden soll (incl.
           absolutem Pfad)
    msg[4]
    msg[5] Gruppenkennung (siehe OLGA_OPENDOC)
    msg[6] 0
    msg[7] 0

Als Bestätigung verschickt der Manager folgende Message:

    OLGA_ACK
    (Manager -> Client)
    msg[0] $1239 (4665)
    msg[1] manID
    msg[2] 0
    msg[3]
        +  exakt dieselben Werte von OLGA_LINK
    msg[4]
    msg[5] Gruppenkennung
    msg[6] 0=Fehler, sonst: Link eingerichtet
    msg[7] OLGA_LINK

Soll die Überwachung für eine Datei beendet werden, muß der Client dem Manager folgende Message schicken. Beim Schließen eines Dokuments sollte stattdessen allerdings OLGA_CLOSEDOC verwendet werden, und beim Beenden der Client-Applikation werden die Links mit OLE_EXIT automatisch gelöscht.

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

Als Bestätigung erhält der Client folgende Message:

    OLGA_ACK
    (Manager -> Client)
    msg[0] $1239 (4665)
    msg[1] manID
    msg[2] 0
    msg[3]
        +  exakt dieselben Wert von OLGA_UNLINK
    msg[4]
    msg[5] Gruppenkennung
    msg[6] 0=Fehler, sonst: Link entfernt
    msg[7] OLGA_UNLINK

Mit der nächsten Message wird ein Client darüber informiert, daß eine seiner eingebetteten Dateien verändert wurde. Ein Linking-Client muß daraufhin die Datei neu anzeigen, ein Embedding-Client sollte die Datei zusätzlich komplett neu in sein Dokument laden.

    OLGA_UPDATED
    (Manager -> Client)
    msg[0] $123f (4671)
    msg[1] manID
    msg[2] 0
    msg[3]
        +  Pointer auf den Dateinamen (incl. absolutem Pfad) der Datei,
           die verändert wurde
    msg[4]
    msg[5] reserviert
    msg[6] reserviert
    msg[7] Gruppenkennung

Wenn ein Server eine Datei umbenannt oder verschoben hat, erhält der Client folgende Message. Sie dient nur dazu, daß der Client seine interne Referenz aktualisiert, d.h. das Dokument muß _nicht_ neu gezeichnet werden!

    OLGA_RENAMELINK
    (Manager -> Client)
    msg[0] $1240 (4672)
    msg[1] manID
    msg[2] 0
    msg[3]
        +  Pointer auf den alten Dateinamen incl. absolutem Pfad
    msg[4]
    msg[5]
        +  Pointer auf den neuen Dateinamen incl. absolutem Pfad
    msg[6]
    msg[7] Gruppenkennung

Als Antwort auf OLGA_RENAMELINK muß der Client an den Manager folgende Message schicken, damit letzterer seine Referenz aktualisiert und unnötigen Speicherplatz freigibt (der Client muß dazu einfach nur die Messagenummer austauschen und die erhaltene Message zurücksenden). Unterbleibt diese Antwort, ist der entsprechende Link "tot", kann also nicht mehr überwacht werden.

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

Wenn eine Datei dem Client plötzlich nicht mehr zur Verfügung steht (weil sie z.B. vom Server gelöscht wurde), wird dies vom Manager mit folgender Message mitgeteilt. Der Client kann daraufhin z.B. den Benutzer informieren oder per Fileselectbox eine andere Datei auswählen lassen.

Außerdem muß der Client den jetzt ungültigen Link mit der normalen OLGA_UNLINK-Message auflösen, wobei als Pointer die Werte von OLGA_LINKBROKEN übergeben werden.

    OLGA_LINKBROKEN
    (Manager -> Client)
    msg[0] $1245 (4677)
    msg[1] manID
    msg[2] 0
    msg[3]
        +  Pointer auf den Dateinamen incl. absolutem Pfad
    msg[4]
    msg[5] Gruppenkennung
    msg[6] 0
    msg[7] 0

Für Clients bietet der Manager eine einfache Möglichkeit, passende Server nachzustarten bzw. aufzurufen. Dazu wird (bei OLS_TYPE und OLS_EXTENSION) die Datei OLGA.INF ausgewertet (siehe Beschreibung in der OLGA-Dokumentation). Zunächst wird der darin gefundene Server im Speicher gesucht und bei Erfolg mit VA_START (siehe Gemini- bzw. Thing-Dokumentation) aufgerufen. Ansonsten wird das Programm unter MultiTOS bzw. MagiC mit shel_write() nachgestartet.

    OLGA_START
    (Client -> Manager)
    msg[0] $1246 (4678)
    msg[1] apID
    msg[2] 0
    msg[3] eine der OLS-Konstanten (s.u.)
    msg[4]
        +  Angaben, welches Programm bzw. welcher Programmtyp gestartet
    msg[5] werden soll (abhängig von [3], s.u.)
    msg[6]
        +  Pointer auf Kommandozeile (i.A. nur die zu ladende Datei) oder NULL
    msg[7]

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

Als Bestätigung erhält man folgende Message:

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

Um die Kommandozeile leichter freigeben zu können, erhält man außerdem noch eine zweite Message, falls für die Kommandozeile nicht NULL übergeben wurde.

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

Hier geht es weiter.