15.9 SE-Protokoll

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.

15.9.1 Kontaktaufnahme
15.9.2 Anmerkungen
15.9.3 Nachrichten der Shell an den Editor
15.9.4 Nachrichten des Editors an die Shell
15.9.5 History
15.9.6 Autoren und Programme

15.9.1 Kontaktaufnahme

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.

15.9.2 Anmerkungen

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.

15.9.3 Nachrichten der Shell an den Editor

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

15.9.3.1 SE_INIT

Die Shell fragt an, ob ein Editor das SE-Protokoll versteht.

Aufbau der Nachricht

Wort 3:

Ein Bitset, welche Nachrichten die Shell versendet:

Nachricht	Bit	Hex-Wert
SE_INIT	0	0x0001
SE_OK	1	0x0002
SE_ACK	2	0x0004
SE_OPEN	3	0x0008
SE_ERROR	4	0x0010
SE_ERRFILE	5	0x0020
SE_PROJECT	6	0x0040
SE_QUIT	7	0x0080
SE_TERMINATE	8	0x0100
SE_CLOSE	9	0x0200
SE_MENU	10	0x0400

Wort 4+5:

Ein Bitset, welche Editorkommandos verstanden werden

Nachricht	Bit	Hex-Wert
ES_INIT	0	0x0001
ES_OK	1	0x0002
ES_ACK	2	0x0004
ES_COMPILE	3	0x0008
ES_MAKE	4	0x0010
ES_MAKEALL	5	0x0020
ES_LINK	6	0x0040
ES_EXEC	7	0x0080
ES_MAKEEXEC	8	0x0100
ES_PROJECT	9	0x0200
ES_QUIT	10	0x0400
ES_SHLCTRL	11	0x0800

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.

siehe auch: ES_OK, SE_QUIT

15.9.3.2 SE_OK

Die Shell sagt dem Editor, daß sie das Protokoll versteht.

Aufbau der Nachricht

Wort 3:

Ein Bitset, welche Nachrichten die Shell versendet:

Nachricht	Bit	Hex-Wert
SE_INIT	0	0x0001
SE_OK	1	0x0002
SE_ACK	2	0x0004
SE_OPEN	3	0x0008
SE_ERROR	4	0x0010
SE_ERRFILE	5	0x0020
SE_PROJECT	6	0x0040
SE_QUIT	7	0x0080
SE_TERMINATE	8	0x0100
SE_CLOSE	9	0x0200
SE_MENU	10	0x0400

Wort 4+5:

Ein Bitset, welche Editorkommandos verstanden werden:

Nachricht	Bit	Hex-Wert
ES_INIT	0	0x0001
ES_OK	1	0x0002
ES_ACK	2	0x0004
ES_COMPILE	3	0x0008
ES_MAKE	4	0x0010
ES_MAKEALL	5	0x0020
ES_LINK	6	0x0040
ES_EXEC	7	0x0080
ES_MAKEEXEC	8	0x0100
ES_PROJECT	9	0x0200
ES_QUIT	10	0x0400
ES_SHLCTRL	11	0x0800

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.

15.9.3.3 SE_ACK

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

15.9.3.4 SE_OPEN

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.

15.9.3.5 SE_ERROR

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.

15.9.3.6 SE_ERRFILE

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.

15.9.3.7 SE_PROJECT

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.

15.9.3.8 SE_QUIT

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

keine Parameter

Antwort

Es wird keine Antwort erwartet!

15.9.3.9 SE_TERMINATE

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

keine Parameter

Antwort

Mit ES_ACK bestätigt der Editor die Meldung.

15.9.3.10 SE_CLOSE

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.

15.9.3.11 SE_MENU

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

15.9.4 Nachrichten des Editors an die Shell

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

15.9.4.1 ES_INIT

Ein Editor fragt an, ob eine Shell das SE-Protokoll versteht.

Aufbau der Nachricht

Wort 3:

Ein Bitset, welche Shellnachrichten verstanden werden:

Nachricht	Bit	Hex-Wert
SE_INIT	0	0x0001
SE_OK	1	0x0002
SE_ACK	2	0x0004
SE_OPEN	3	0x0008
SE_ERROR	4	0x0010
SE_ERRFILE	5	0x0020
SE_PROJECT	6	0x0040
SE_QUIT	7	0x0080
SE_TERMINATE	8	0x0100
SE_CLOSE	9	0x0200
SE_MENU	10	0x0400

Wort 4+5:

Ein Bitset, welche Editorkommandos versendet werden:

Nachricht	Bit	Hex-Wert
ES_INIT	0	0x0001
ES_OK	1	0x0002
ES_ACK	2	0x0004
ES_COMPILE	3	0x0008
ES_MAKE	4	0x0010
ES_MAKEALL	5	0x0020
ES_LINK	6	0x0040
ES_EXEC	7	0x0080
ES_MAKEEXEC	8	0x0100
ES_PROJECT	9	0x0200
ES_QUIT	10	0x0400
ES_SHLCTRL	11	0x0800

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.

15.9.4.2 ES_OK

Der Editor beantwortet die Anfrage der Shell nach dem Protokoll.

Aufbau der Nachricht

Wort 3:

Ein Bitset, welche Shellnachrichten verstanden werden:

Nachricht	Bit	Hex-Wert
SE_INIT	0	0x0001
SE_OK	1	0x0002
SE_ACK	2	0x0004
SE_OPEN	3	0x0008
SE_ERROR	4	0x0010
SE_ERRFILE	5	0x0020
SE_PROJECT	6	0x0040
SE_QUIT	7	0x0080
SE_TERMINATE	8	0x0100
SE_CLOSE	9	0x0200
SE_MENU	10	0x0400

Wort 4+5:

Ein Bitset, welche Editorkommandos versendet werden:

Nachricht	Bit	Hex-Wert
ES_INIT	0	0x0001
ES_OK	1	0x0002
ES_ACK	2	0x0004
ES_COMPILE	3	0x0008
ES_MAKE	4	0x0010
ES_MAKEALL	5	0x0020
ES_LINK	6	0x0040
ES_EXEC	7	0x0080
ES_MAKEEXEC	8	0x0100
ES_PROJECT	9	0x0200
ES_QUIT	10	0x0400
ES_SHLCTRL	11	0x0800

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

15.9.4.11 ES_QUIT

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

keine Parameter

Antwort

Es wird keine Antwort erwartet!

15.9.4.12 ES_SHLCTRL

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.

15.9.5 History

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

neue Nachricht SE_MENU
bei SE_OPEN kann nun auch eine Zeile und eine Spalte angegeben werden

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

15.9.6 Autoren und Programme

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, 19. Oktober 2024

Protokolle

OLGA-Protokoll

System Services Protocol (SSP)