--------------------------------------------------------------------------- A m o k E d =================== Version 1.02 01 Okt 1991 AEd_Appl.dok --------------------------------------------------------------------------- Dokumentation zu AmokEd-Applikations-Programmierung --------------------------------------------------- Eine Applikation für AmokEd zu programmieren ist ganz leicht: · Schreiben Sie Ihr Programm, daß es alle Funktionen beinhaltet, die Sie haben möchten. Wenn das Programm befehlsgesteuert ist, tun Sie sich bei der nun folgenden Arbeit leicht. · Ergänzen Sie Ihr Programm um eine ARexx-Schnittstelle. Sie können nun testen, ob das Programm mit dem Rexx-Host zusammen- arbeitet (am einfachsten über die Arexx-Funtion `trace'). · Das Programm sollte beim CLI-Aufruf als ersten Parameter den Namen des AmokEd-Ports, mit dem es kommunizieren soll, erwarten. Wenn das Programm einen eigenen öffentlichen Port hat, so können sie erreichen, daß Ihr Applikation nur einmal im Speicher ist, auch wenn sie von mehreren AmokEds genutzt wird. Wie das im Einzelnen abläuft, ist aus dem Programm ApplDemo ersichtlich. · Setzen Sie das Feld RexxMessage.node.node.name auf den Typ. Sie finden die Typen in EdApplDefs.mod bereits vordefiniert. Anhand des Typs erkennt AmokEd, daß die Nachricht von einer Applikation kommt und welches Format sie hat. · Die erste Nachricht die von der Applikation an AmokEd geschickt wird, sollte die Anmeldung mit dem `APPLADD'-Befehl sein. Überprüfen Sie den Return-Code!! Nur wenn RexxMsg.result1 = 0, können Sie Sicher sein, daß alles ordnungsgemäß abgelaufen ist. · Der Befehl "CloseDown" signalisiert Ihrem Programm, das es für AmokEd "gestorben" ist. Dieser Befehl wird beim Beenden des letzten Textes von AmokEd an alle registrierten Applikationen geschickt; oder auf Befehl des Anwenders an einzelne. Befehlsübersicht ---------------- Von der Applikation aus können Sie alle Befehle benutzen, die Ihnen für ARexx-Scripts und innerhalb von AmokEd zur Verfügung stehen. Zusätzlich gibt es einige Befehle, die nur für Applikationen erlaubt sind. Eine genaue Beschreibung finden sie weiter unten. ApplAdd - meldet eine neue Applikation bei AmokEd an (siehe oben) XPing - setzt XPing-Feld XPong - springt an Position n des XPing-Feldes XClrPing - löscht das XPing-Feld Message-Typen ------------- Die Parameter einer Applikation können an AmokEd auf zwei verschiedene Weisen übergeben werden. Um unterscheiden zu können, welches der beiden Formate vorliegt, muß das Feld RexxMsg.nod.node.name den entsprechenden Typbezeichner enthalten. Diese beiden Typen sind in EdApplDefs vordefiniert. AEd0: RexxMsg.args[0] enthält Pointer auf einen String, der von AEd wie ein gewöhnlicher Kommando-String von ARexx behandelt wird. D.h. er wird ganz normal durch den Parser geschickt. Wenn der übergebene String nicht nur aus alphanumerischen Zeichen und Underscores '_' besteht, sollten Sie nicht den String selbst übergeben, sondern einen ARexx-Argstring. (Siehe hierzu auch Programm ApplDemo.) AEd1: Dieser Typ erleichter die Kommunikation zwischen der Applikation und AmokEd erheblich, da nicht extra ein String zusammengesetzt werden muß, den AmokEd dann wieder parset. Die Argumente werden gleich einzeln übergeben. Das macht nicht nur die Applikationen kürzer, sondern beschleunigt auch die Abarbeitung. Mit diesem Typ können alle Befehle benutzt werden, die AmokEd versteht. Sie müssen nur beachten, daß die Argumente der normalen und der Rexx-Befehle IMMER als StringPtr interpretiert werden. RexxMsg.arg[0] enthält einen StringPtr. Der referenzierte String, der wird darf jedoch nur und genau ein gültiges Kommando enthalten (ohne Argumente), da dieser String als unverändertes Ganzes zum Vergleich mit der Liste der gülitgen Kommandos benutzt wird Die folgenden RexxMsg.args[]-Felder enthalten die Argumente des auszuführende Befehls. Bei den normalen und den Rexx-Befehlen sind das immer StringPtr. Sie können im Anschluß daran noch weitere Befehle mit Argumenten übergeben, sofern alle Argumente in die noch zur Verfügung stehenden RexxMsg.args[]-Felder passen. Bedenken Sie jedoch, daß in args[eAD.TextSlot] der Bezugs-Text eingetragen wird. Es stehen daher eAD.numAMArgs args[]-Felder zur Verfügung. WICHTIG: Das erste, nicht mehr benutzte args[]-Feld MUSS auf NIL gesetzt werden! Dies trifft natürlich nicht zu, wenn Sie alle eAD.numAMArgs Felder benutzen. Ein kleines Beispiel: Wir haben 3 Befehle (Anzahl der Agumente in Klammern): foo (2), bar (0) und foobar (1). Dann könnten wir folgende RexxMsg schicken: args[0] := ADR("foo"); args[1] := fooarg1; args[2] := fooarg2; args[3] := ADR("bar"); args[4] := ADR("foobar"); args[5] := foobar_arg; args[6] := NIL; args[eAD.TextSlot] := Text; (* Text wurde übergeben *) Die Applikations-Befehle ------------------------ ADDAPPL Meldet eine Applikation bei AmokEd an. Sie ist anschließend für den Benutzen unter anprechbar. ist der Name des öffentlichen Ports, unter dem die Applikation erreichbar ist. StringPtr StringPtr XPING Teilt AmokEd mit, an welcher Adresse sich die Struktur eAD.XPingPong befindet, die die Marken für XPong enthält. Zur Zeit kann AmokEd je Text nur ein XPingPong- Feld verwalten. Aus Gründen der Aufwärtskompatibilität sollte der Speicher dieser Struktur PUBLIC sein. eAD.XPingPongPtr XPong Veranlaßt AmokEd, an die Position und in die Zeile zu springen, die an in die Struktur XPingPong eingetragen ist. Sollte diese Position nicht mehr gültig sein, erhalten die einen entsprechenden Fehler-Code. LONGINT ClrXPing Veranlaßt AmokEd, den Verweis auf die Struktur XPingPong des Textes zu entfernen. Jetzt kann der Inhalt der Struktur geändert oder der zugehörige Speicher freigegeben werden. "Besitzt" Ihre Applikation eine Message von dem AmokEd (es können ja mehrere gleichzeitg laufen), zu dem der Text gehört, so kann die Applikation sie Struktur auch ändern, ohne vorher ClrXPing aufzurufen. Sobald die Message repleied wurde, darf die Struktur nicht mehr verändert werden!