Sinn des SE-Protokolls ist die Kommunikation zwischen Shells zur Programmentwicklung und Editoren, daher auch der Name: Shell-Editor-Protokoll.
Dieses Protokoll dient dazu, unter Multitasking-Systemen die Shell vom Editor aus zur Compilierung und ähnlichen Aktionen zu veranlassen, und um von der Shell Fehlermeldungen und/oder Fehlerdateien an den Editor zurückzugeben.
Kommandos bzw. Nachrichten von der Shell an den Editor beginnen mit SE_, Nachrichten vom Editor an die Shell beginnen mit ES_.
Die aktuelle Versionsnummer des Protokolls ist 1.05.
Die Kontaktaufnahme läuft wie folgt ab:
Die Shell verschickt nach dem Start die Nachricht SE_INIT. Als Antwort erhält sie darauf die Nachricht ES_OK. Aus den Bitfeldern in den beiden Nachrichten kann die Shell nun ableiten, welche Kommandos sie an den Editor schicken kann und welche Kommandos vom Editor zu erwarten sind. Wenn die Shell nicht mehr am SE-Protokoll teilnehmen will (z.B. weil sie beendet wird), dann schickt sie die Nachricht SE_QUIT an den Editor.
Der Editor verschickt nach dem Start die Nachricht ES_INIT. Als Antwort erhält sie darauf die Nachricht SE_OK. Aus den Bitfeldern in den beiden Nachrichten kann der Editor nun ableiten, welche Kommandos er an die Shell schicken kann und welche Kommandos von der Shell zu erwarten sind. Wenn der Editor nicht mehr am SE-Protokoll teilnehmen will (z.B. weil er beendet wird), dann schickt er die Nachricht ES_QUIT an die Shell.
Bleibt die Frage, an wen Shell und Editor diese Nachrichten schicken sollen. Das SE-Protokoll ist sinnvoll am ehesten unter einem Multitasking-System einsetzbar, dort wird normalerweise die AES-Funktion appl_search() zur Verfügung stehen. Shell und Editor sollten also einfach ihre jeweilige Init-Nachricht an alle Prozesse (außer an Systemprozesse) schicken.
Andere Möglichkeiten:
Wenn die Shell den Namen ihres Editors kennt, kann sie sich
natürlich auch darauf beschränken, SE_INIT nur an diesen zu
schicken.
Wenn die Funktion appl_search() nicht zur Verfügung steht,
bietet sich das XAcc-Protokoll zur Kontaktaufnahme an: Shell und
Editor sollten ihre Init-Nachrichten dann einfach an jeden Prozeß
schicken, der sich per XAcc anmeldet. Das XAcc-Protokoll sieht
außerdem noch eine maschinenlesbare Kennung des Programmtyps (XDSC)
vor, so daß man u.U. sogar erkennen kann, ob es sich bei dem
Kommunikationspartner um eine Shell (Kennung `PE' für Programming
Environment
) oder um einen Editor (Kennung `ED' für Text
Editor
) handelt.
Wenn im folgenden von einer Nachricht
die Rede ist, dann
ist damit eine AES-Nachricht gemeint, die aus 8 Worten (Integers)
besteht und mit der AES-Funktion appl_write() verschickt
wird. Das erste Wort enthält jeweils die Nummer der Nachricht, das
zweite die Applikations-ID des Absenders, das dritte ist immer Null.
Die Belegung der anderen Worte ist von der jeweiligen Nachricht
abhängig. Worte, für die keine Belegung angegeben wird, sind auf
Null zu setzen.
Bitte beachten: Da die Zählung bei 0 beginnt, ist mit
Wort 3
im folgenden das vierte Wort gemeint!
Zur Verdeutlichung nochmals in C:
int msg[8]; msg[0] = SE_ACK; /* Nachricht */ msg[1] = gl_apid; /* ID des Absenders */ msg[2] = 0; /* 0, d.h. keine Überlänge */ msg[3] = TRUE; /* dies ist "Wort 3" */ msg[4] = msg[5] = msg[6] = msg[7] = 0; /* Rest auf Null */ appl_write (editor, 16, msg); /* abschicken */
Wenn in einer Nachricht ein Zeiger (d.h. eine Adresse) enthalten ist, dann wird das obere Wort der Adresse im ersten und das untere Wort im zweiten der angegebenen Worte übergeben.
Bei den Zeigern auf Speicherbereiche ist vom jeweiligen Absender
der Nachricht darauf zu achten, daß diese Speicherbereiche vom
Empfänger auch lesbar sind (Memory Protection!). Dafür sind diese
als Readable
zu allozieren! Das geschieht über den
Gemdos-Aufruf Mxalloc().
Bei einigen Nachrichten können Zeilen- und Spaltennummern für eine Cursorposition übergeben werden. Da es unterschiedliche Auffassungen darüber gibt, ob Zeilen und/oder Spalten ab Null oder ab Eins gezählt werden, wird empfohlen, diese Angaben vor der Übernahme zu überprüfen und ggfs. zu korrigieren. Wenn der Editor seine Zeilen also ab Eins zählt, dann sollte ihn die Zeilennummer Null nicht aus der Fassung bringen, sondern er sollte sie wie Zeile Eins behandeln.
Die Shell kann folgende Nachrichten bzw. Kommandos an den Editor senden:
Nachricht | Nummer |
SE_INIT | 0x4200 |
SE_OK | 0x4201 |
SE_ACK | 0x4202 |
SE_OPEN | 0x4203 |
SE_ERROR | 0x4204 |
SE_ERRFILE | 0x4205 |
SE_PROJECT | 0x4206 |
SE_QUIT | 0x4207 |
SE_TERMINATE | 0x4208 |
SE_CLOSE | 0x4209 |
SE_MENU | 0x420A |
Die Shell fragt an, ob ein Editor das SE-Protokoll versteht.
Aufbau der Nachricht
Wort 3: | Ein Bitset, welche Nachrichten die Shell versendet:
| |||||||||||||||||||||||||||||||||||||||
Wort 4+5: | Ein Bitset, welche Editorkommandos verstanden werden
Hinweis: Wort 4 und 5 bilden zusammen ein Langwort. Da für die bisher definierten Nachrichten aber nur 12 Bits benötigt werden, ist Wort 4 normalerweise Null. | |||||||||||||||||||||||||||||||||||||||
Wort 6: | Unterstützte Versionsnummer des Protokolls als BCD-Zahl, also
0x0105 (hexadezimal) für Version 1.05
|
Antwort
Der Editor antwortet mit der Nachricht ES_OK.
Die Shell sagt dem Editor, daß sie das Protokoll versteht.
Aufbau der Nachricht
Wort 3: | Ein Bitset, welche Nachrichten die Shell versendet:
| |||||||||||||||||||||||||||||||||||||||
Wort 4+5: | Ein Bitset, welche Editorkommandos verstanden werden:
Hinweis: Wort 4 und 5 bilden zusammen ein Langwort. Da für die bisher definierten Nachrichten aber nur 12 Bits benötigt werden, ist Wort 4 normalerweise Null. | |||||||||||||||||||||||||||||||||||||||
Wort 6: | Unterstützte Versionsnummer des Protokolls als BCD-Zahl, also
0x0105 (hexadezimal) für Version 1.05
| |||||||||||||||||||||||||||||||||||||||
Wort 7: | Die ApId des Programmes, dessen Nachricht beantwortet wird
|
Antwort
Keine. SE_OK ist bereits die Antwort der Shell auf die Nachricht ES_INIT.
Die Shell bestätigt den Empfang eines Editorkommandos und gibt zurück, ob das Kommando ausgeführt wird.
Aufbau der Nachricht
Wort 3: | TRUE : Kommando wird verstanden und ausgeführt,
FALSE: Das Kommando wird nicht verstanden Ein SE_ACK mit TRUE sagt nichts darüber aus, ob das Kommando erfolgreich ausgeführt wurde. Es sagt nur, daß die Shell das Kommando versteht und ausführen wird! |
Antwort
Keine (SE_ACK ist bereits die Antwort auf eine Nachricht).
Die Shell sagt dem Editor, daß er einen Text öffnen soll.
Aufbau der Nachricht
Wort 3+4: | Ein Zeiger auf den Filenamen des zu öffnenden Files
|
Wort 5+6: | Zeile, in die der Cursor positioniert werden soll
|
Wort 7: | Spalte, in die der Cursor positioniert werden soll
|
Antwort
Als Antwort erhält die Shell ein ES_ACK.
Hinweise: Die Angabe einer Zeilen- und Spaltennummer ist erst ab Protokollversion 1.02 vorgesehen. Programme, die noch ältere Protokollversionen verwenden, sollten aber eigentlich die Worte 5-7 auf Null gesetzt haben. Will man ganz sicher gehen, muß man ggfs. die bei SE_INIT bzw. SE_OK übergebene Versionsnummer der Shell abfragen.
Wenn die Shell keine Positionsangabe machen kann oder will, sollte sie Zeile und Spalte auf Null setzen.
Es ist ein Fehler beim Compilieren aufgetreten.
Aufbau der Nachricht
Wort 3+4: | Ein Zeiger auf eine Infostruktur, die wie folgt aufgebaut ist:
|
typedef struct { char *errFile; /* Zeiger auf den Namen der compilierten Datei */ char *errMess; /* Zeiger auf die Fehlermeldung */ int errNum; /* Die Fehlernummer */ long errLine; /* Die fehlerhafte Zeile */ int errRow; /* Die Spalte mit dem Fehler (oder 0) */ } ERRINFO;
Antwort
Mit ES_ACK bestätigt der Editor die Meldung.
Hinweis: Wenn die Shell keine Positionsangabe machen kann oder will, sollte sie Zeile und Spalte auf Null setzen.
Es sind Fehler aufgetreten. Die Fehlermeldungen stehen in einem Errorfile, welches in der Message spezifiziert wird.
Aufbau der Nachricht
Wort 3+4: | Ein Zeiger auf den Filenamen des Errorfiles mit den
Fehlermeldungen
|
Wort 5+6: | Ein Zeiger auf den Namen des compilierten Textes
|
Antwort
Mit ES_ACK bestätigt der Editor die Meldung.
Die Shell teilt dem Editor mit, daß das Projekt geändert wurde. Der Filename des aktuellen Projektfiles wird als Parameter übergeben. Wird NULL übergeben, sollte das aktuelle Projekt abgemeldet werden.
Eine vernünftige Reaktion des Editors wäre es in dem Fall, ebenfalls das Projekt zu wechseln, sofern er dies unterstützt.
Aufbau der Nachricht
Wort 3+4: | Ein Zeiger auf den Namen des Projektfiles oder NULL.
|
Antwort
Der Editor bestätigt mit ES_ACK.
Hinweis: Den Namen des Projektfiles auf NULL zu setzen, ist erst ab Protokollversion 1.01 vorgesehen. Die Shell sollte daher vorher überprüfen, ob der Editor mindestens Protokollversion 1.01 unterstützt.
Die Shell teilt dem Editor mit, daß sie jetzt beendet wird. Der Editor sollte in dem Fall die Shell als Kommunikationspartner vergessen.
Aufbau der Nachricht
Antwort
Es wird keine Antwort erwartet!
Die Shell teilt dem Editor mit, daß dieser sich beenden soll. Der Editor sollte in dem Fall sich selbst beenden und seinen ganz normalen Terminierungsprozeß durchlaufen (und dabei auch ein ES_QUIT verschicken!). Der Grund für so eine Meldung der Shell könnte zum Beispiel zu wenig Speicher zum Compilieren sein.
Aufbau der Nachricht
Antwort
Mit ES_ACK bestätigt der Editor die Meldung.
Die Shell teilt dem Editor mit, daß dieser bestimmte Texte sichern bzw. schließen soll. Beim Schließen von geänderten Texten sollte der Editor vorher nachfragen.
Aufbau der Nachricht
Wort 3+4: | Ein Zeiger auf den Namen einer Datei oder eine Dateimaske.
*.*steht für alle Textfenster (entspricht also dem SE_CLOSE der Protokollversion 1.00). |
Wort 5: | 0 = nur sichern
1 = sichern und schließen 2 = schließen ohne Sichern (ab Version 1.04) |
Antwort
Mit ES_ACK bestätigt der Editor die Meldung.
Hinweis: In der Protokollversion 1.00 waren für SE_CLOSE noch keine Parameter vorgesehen. Editoren, die nur Version 1.00 unterstützen, werden daher die Dateimasken und das Flag ignorieren und alle Texte sichern.
Die Shell teilt dem Editor mit, was er für die einzelnen Programme in sein Menü eintragen soll. Der Editor kann somit für die Menüpunkte, die eine Aktion in der Shell auslösen, die gleichen Texte wie die Shell verwenden.
Aufbau der Nachricht
Wort 3+4: | Ein Zeiger auf eine Infostruktur, die wie folgt aufgebaut ist:
|
typedef struct { char *compStr; /* Text für den Menüpunkt "Compiler" */ char *makeStr; /* Text für den Menüpunkt "Makefile" */ char *makeAllStr; /* Text für den Menüpunkt "Make all" */ char *linkStr; /* Text für den Menüpunkt "Linker" */ char *execStr; /* Text für den Menüpunkt "Execute" */ char *makeExecStr; /* Text für den Menüpunkt "Make & Execute" */ char *progName; /* Name der Shell (ab Version 1.04) */ char *shellCtrlStr; /* Text für den Menüpunkt "Shell Control" */ /* (ab Version 1.05) */ } SEMENUINFO;
Antwort
Mit ES_ACK bestätigt der Editor die Meldung.
Hinweise: Die Texte sind allesamt optional und können auch NULL sein, wenn die Shell keinen entsprechenden Menüpunkt hat. Dies bedeutet jedoch nicht, daß die Shell nicht über diese Funktionalität verfügt. Der Editor sollte daher für alle Texte ggfs. Defaulttexte einsetzen.
Diese Nachricht existiert erst ab Protokollversion 1.02. Es genügt aber der Test, ob das entsprechende Bit in ES_INIT bzw. ES_OK gesetzt ist.
Beim Zugriff auf progName und shellCtrlStr muß darauf geachtet werden, daß der Kommunikationspartner diese auch schon unterstützt (Protokollversion testen)!
Der Editor kann folgende Nachrichten bzw. Kommandos an die Shell senden:
Nachricht Nummer ES_INIT 0x4240 ES_OK 0x4241 ES_ACK 0x4242 ES_COMPILE 0x4243 ES_MAKE 0x4244 ES_MAKEALL 0x4245 ES_LINK 0x4246 ES_EXEC 0x4247 ES_MAKEEXEC 0x4248 ES_PROJECT 0x4249 ES_QUIT 0x424A ES_SHLCTRL 0x424B
Ein Editor fragt an, ob eine Shell das SE-Protokoll versteht.
Aufbau der Nachricht
Wort 3: | Ein Bitset, welche Shellnachrichten verstanden werden:
| |||||||||||||||||||||||||||||||||||||||
Wort 4+5: | Ein Bitset, welche Editorkommandos versendet werden:
Hinweis: Wort 4 und 5 bilden zusammen ein Langwort. Da für die bisher definierten Nachrichten aber nur 12 Bits benötigt werden, ist Wort 4 normalerweise Null. | |||||||||||||||||||||||||||||||||||||||
Wort 6: | Unterstützte Versionsnummer des Protokolls als BCD-Zahl, also
0x0105 (hexadezimal) für Version 1.05
|
Antwort
Als Antwort erhält der Editor SE_OK von der Shell.
Der Editor beantwortet die Anfrage der Shell nach dem Protokoll.
Aufbau der Nachricht
Wort 3: | Ein Bitset, welche Shellnachrichten verstanden werden:
| |||||||||||||||||||||||||||||||||||||||
Wort 4+5: | Ein Bitset, welche Editorkommandos versendet werden:
Hinweis: Wort 4 und 5 bilden zusammen ein Langwort. Da für die bisher definierten Nachrichten aber nur 12 Bits benötigt werden, ist Wort 4 normalerweise Null. | |||||||||||||||||||||||||||||||||||||||
Wort 6: | Unterstützte Versionsnummer des Protokolls als BCD-Zahl, also
0x0105 (hexadezimal) für Version 1.05
| |||||||||||||||||||||||||||||||||||||||
Wort 7: | Die ApId des Programmes, dessen Nachricht beantwortet wird
|
Antwort
Keine. ES_OK ist bereits die Antwort des Editors auf die Nachricht SE_INIT.
Der Editor bestätigt den Empfang des Kommandos.
Aufbau der Nachricht
Wort 3: | TRUE : Kommando wird verstanden und ausgeführt,
FALSE: Das Kommando wird nicht verstanden Ein ES_ACK mit TRUE sagt nichts darüber aus, ob das Kommando erfolgreich ausgeführt wurde. Es sagt nur, daß der Editor das Kommando versteht und ausführen wird! |
Antwort
Keine (ES_ACK ist bereits die Antwort auf eine Nachricht).
Der Editor sagt der Shell, daß sie ein File übersetzen soll. Ein Zeiger auf den Dateinamen kann in der Nachricht übergeben werden.
Aufbau der Nachricht
Wort 3+4: | Zeiger auf den Namen der zu compilierenden Datei oder
NULL.
|
Antwort
Diese Nachricht muß mit SE_ACK bestätigt werden.
Hinweis: Den Namen der zu compilierenden Datei auf NULL zu setzen, ist erst ab Protokollversion 1.03 vorgesehen. Der Editor sollte daher vorher überprüfen, ob die Shell mindestens Protokollversion 1.03 unterstützt.
Der Editor sagt der Shell, daß sie ein Make ausführen soll. Ein Filename kann in der Nachricht übergeben werden, muß aber nicht gesetzt sein und muß von der Shell auch nicht beachtet werden!
Aufbau der Nachricht
Wort 3+4: | Zeiger auf den Namen des Makefiles (oder NULL)
|
Antwort
Die Shell bestätigt mit SE_ACK.
Der Editor sagt der Shell, daß ein komplettes Make All
ausgeführt werden soll. Ein Filename für das Makefile kann (muß
aber nicht) in der Nachricht übergeben werden.
Aufbau der Nachricht
Wort 3+4: | Zeiger auf den Namen des Makefiles (oder NULL)
|
Antwort
Die Shell bestätigt mit SE_ACK.
Der Editor sagt der Shell, daß das Programm gelinkt werden soll. Ein Filename kann in der Nachricht übergeben werden, muß aber nicht unbedingt von der Shell beachtet werden!
Aufbau der Nachricht
Wort 3+4: | Zeiger auf den Namen der Source, die gelinkt werden soll (oder
NULL)
|
Antwort
Die Shell bestätigt mit SE_ACK.
Der Editor sagt der Shell, daß das Programm zu der Source ausgeführt werden soll. Ein Filename kann übergeben werden, muß von der Shell aber nicht beachtet werden.
Aufbau der Nachricht
Wort 3+4: | Zeiger auf den Namen des auszuführenden Files (oder NULL).
Bei einer Sourcedatei ist diese ggf. noch zu compilieren und/oder zu linken |
Antwort
Die Shell bestätigt mit SE_ACK.
Die Shell soll ein Make ausführen und danach das Programm ausführen. Ein Filename für das Makefile kann (muß aber nicht) in der Nachricht übergeben werden.
Aufbau der Nachricht
Wort 3+4: | Zeiger auf den Namen des Makefiles (oder NULL)
|
Antwort
Die Shell bestätigt mit SE_ACK.
Der Editor teilt der Shell mit, daß das Projekt geändert/gewechselt wurde. Der Filename des Projektfiles wird als Parameter in der Nachricht übergeben. Wird NULL übergeben, sollte das aktuelle Projekt abgemeldet werden.
Eine vernünftige Reaktion der Shell wäre in dem Fall, ebenfalls das Projekt zu wechseln, sofern sie dies unterstützt.
Aufbau der Nachricht
Wort 3+4: | Zeiger auf den Namen des Projektfiles oder NULL
|
Antwort
Die Shell bestätigt mit SE_ACK.
Hinweis: Den Namen des Projektfiles auf NULL zu setzen, ist erst ab Protokollversion 1.01 vorgesehen. Der Editor sollte daher vorher überprüfen, ob die Shell mindestens Protokollversion 1.01 unterstützt.
Der Editor teilt der Shell mit, daß er jetzt beendet wird. Die Shell sollte in dem Fall den Editor als Kommunikationspartner vergessen.
Aufbau der Nachricht
Antwort
Es wird keine Antwort erwartet!
Nachricht des Editors zur Kontrolle der Shell.
Aufbau der Nachricht
Wort 3+4: | Zeiger auf den Namen des obersten Fensters des Editors oder
NULL
|
Wort 5: | Steuer-Flags:
Bit 0: Shell soll sich toppen (Menü/Fenster) |
Antwort
Die Shell bestätigt mit SE_ACK.
Hinweis: Diese Nachricht existiert erst ab Protokollversion 1.05. Die übrigen Bits von Wort 5 sind für zukünftige Erweiterungen reserviert.
Version 1.05 vom 23.12.1997
neue Nachricht ES_SHLCTRL
neuer Eintrag shellCtrlStr in der Struktur
SEMENUINFO bei SE_MENU
Version 1.04 vom 08.01.1997
Flag 2 (nur schließen
) bei SE_CLOSE
neuer Eintrag progName in der Struktur
SEMENUINFO bei SE_MENU
Version 1.03 vom 19.11.1996
bei ES_COMPILE kann der Zeiger auf den Dateinamen jetzt
auch NULL sein.
Version 1.02 vom 13.08.1996
Version 1.01 vom 30.01.1996
Angabe von Dateimasken und Close-Flag bei SE_CLOSE
Projektname bei SE_PROJECT und ES_PROJECT kann
auch NULL sein
Version 1.00 vom 17.01.1994
erste öffentliche Version
Das SE-Protokoll wurde von Dirk Steins und Frank Storm entwickelt, die Erweiterungen zu den neueren Protokollversionen stammen von Christian Felsch und Dirk Haun.
Die Zahl der Programme, die das SE-Protokoll unterstützen, ist leider noch nicht allzu groß:
Editoren:
Clix von Steffen Engels
Everest von Oliver Schmidt (ab Version 3.5)
Fred von Dirk Steins
qed von Christian Felsch (ab Version 3.3, ab Version 3.70 wird
zudem Protokollversion 1.01 unterstützt)
Shells:
Chatwin von Dirk Haun (ab Version 3.04 wird das SE-Protokoll
komplett unterstützt, ältere Versionen unterstützen nur die
wichtigsten Nachrichten)
Shell zum Megamax Modula-2 von Thomas Tempelmann und Dirk
Steins
PC-Shell von Frank Schramm (ab Version 3.01)
Sonstiges:
SE-Lib von Manfred Rosenboom und Dirk Haun
Dieser Bibliothek liegt auch der SE-Evaluator, eine Art Debugger
für das SE-Protokoll, bei.
Es bleibt zu hoffen, daß weitere Editoren und Shells dieses nützliche Protokoll unterstützen werden. Dieser Text trägt dabei hoffentlich etwas zur Verbreitung bei …
Dirk Haun, 30. September 2024