home *** CD-ROM | disk | FTP | other *** search
/ ST-Computer Leser 1998 October / STC_CD_10_1998.iso / BASE / SEPROTO / SEPROTO.TXT < prev    next >
Text File  |  1998-09-26  |  28KB  |  978 lines
  1.                           Dokumentation zum
  2.  
  3.                              SE-Protokoll
  4.  
  5.                              Version 1.05
  6.                               04.01.1998
  7.  
  8.                                  von
  9.  
  10.                               Dirk Haun
  11.                              Europastr. 8
  12.                            D-64569 Nauheim
  13.                                    
  14.                            Dirk Haun @ WI2
  15.  
  16.  
  17.  
  18. Inhaltsverzeichnis
  19. ==================
  20.  
  21.  1  Einleitung
  22.     1.1  Kontaktaufnahme
  23.     1.2  Anmerkungen
  24.  
  25.  2  Nachrichten der Shell an den Editor
  26.     2.1  SE_INIT
  27.     2.2  SE_OK
  28.     2.3  SE_ACK
  29.     2.4  SE_OPEN
  30.     2.5  SE_ERROR
  31.     2.6  SE_ERRFILE
  32.     2.7  SE_PROJECT
  33.     2.8  SE_QUIT
  34.     2.9  SE_TERMINATE
  35.     2.10  SE_CLOSE
  36.     2.11  SE_MENU
  37.  
  38.  3  Nachrichten des Editors an die Shell
  39.     3.1  ES_INIT
  40.     3.2  ES_OK
  41.     3.3  ES_ACK
  42.     3.4  ES_COMPILE
  43.     3.5  ES_MAKE
  44.     3.6  ES_MAKEALL
  45.     3.7  ES_LINK
  46.     3.8  ES_EXEC
  47.     3.9  ES_MAKEEXEC
  48.     3.10  ES_PROJECT
  49.     3.11  ES_QUIT
  50.     3.12  ES_SHLCTRL
  51.  
  52.  4  History
  53.  
  54.  5  Autoren und Programme
  55.  
  56.  
  57.  
  58. 1  Einleitung
  59. *************
  60.  
  61. Sinn des SE-Protokolls ist die Kommunikation zwischen Shells zur Pro-
  62. grammentwicklung und Editoren, daher auch der Name: Shell-Editor-Pro-
  63. tokoll.
  64.  
  65. Dieses Protokoll dient dazu, unter Multitasking-Systemen die Shell vom
  66. Editor aus zur Compilierung und ähnlichen Aktionen zu veranlassen, und
  67. um von der Shell Fehlermeldungen und/oder Fehlerdateien an den Editor
  68. zurückzugeben.
  69.  
  70. Kommandos bzw. Nachrichten von der Shell an den Editor beginnen mit
  71. SE_, Nachrichten vom Editor an die Shell beginnen mit ES_.
  72.  
  73. Die aktuelle Versionsnummer des Protokolls ist 1.05.
  74.  
  75.  
  76. 1.1  Kontaktaufnahme
  77. ====================
  78.  
  79. Die Kontaktaufnahme läuft wie folgt ab:
  80.  
  81. Die Shell verschickt nach dem Start die Nachricht SE_INIT. Als Antwort
  82. erhält sie darauf die Nachricht ES_OK. Aus den Bitfeldern in den bei-
  83. den Nachrichten kann die Shell nun ableiten, welche Kommandos sie an
  84. den Editor schicken kann und welche Kommandos vom Editor zu erwarten
  85. sind. Wenn die Shell nicht mehr am SE-Protokoll teilnehmen will (z.B.
  86. weil sie beendet wird), dann schickt sie die Nachricht SE_QUIT an den
  87. Editor.
  88.  
  89. Der Editor verschickt nach dem Start die Nachricht ES_INIT. Als Ant-
  90. wort erhält sie darauf die Nachricht SE_OK. Aus den Bitfeldern in den
  91. beiden Nachrichten kann der Editor nun ableiten, welche Kommandos er
  92. an die Shell schicken kann und welche Kommandos von der Shell zu er-
  93. warten sind. Wenn der Editor nicht mehr am SE-Protokoll teilnehmen
  94. will (z.B. weil er beendet wird), dann schickt er die Nachricht
  95. ES_QUIT an die Shell.
  96.  
  97. Bleibt die Frage, an wen Shell und Editor diese Nachrichten schicken
  98. sollen. Das SE-Protokoll ist sinnvoll am ehesten unter einem Multi-
  99. tasking-System einsetzbar, dort wird normalerweise die AES-Funktion
  100. appl_search() zur Verfügung stehen. Shell und Editor sollten also ein-
  101. fach ihre jeweilige Init-Nachricht an alle Prozesse (au₧er an System-
  102. prozesse) schicken.
  103.  
  104. Andere Möglichkeiten:
  105.  
  106.    ∙ Wenn die Shell den Namen ihres Editors kennt, kann sie sich na-
  107.      türlich auch darauf beschränken, SE_INIT nur an diesen zu schik-
  108.      ken.
  109.  
  110.    ∙ Wenn die Funktion appl_search() nicht zur Verfügung steht, bietet
  111.      sich das XAcc-Protokoll zur Kontaktaufnahme an: Shell und Editor
  112.      sollten ihre Init-Nachrichten dann einfach an jeden Proze₧ schik-
  113.      ken, der sich per XAcc anmeldet. Das XAcc-Protokoll sieht au₧er-
  114.      dem noch eine maschinenlesbare Kennung des Programmtyps (XDSC)
  115.      vor, so da₧ man u.U. sogar erkennen kann, ob es sich bei dem Kom-
  116.      munikationspartner um eine Shell (Kennung `PE' für "Programming
  117.      Environment") oder um einen Editor (Kennung `ED' für "Text Edi-
  118.      tor") handelt.
  119.  
  120.  
  121. 1.2  Anmerkungen
  122. ================
  123.  
  124. Wenn im folgenden von einer "Nachricht" die Rede ist, dann ist damit
  125. eine AES-Nachricht gemeint, die aus 8 Worten (Integers) besteht und
  126. mit der AES-Funktion appl_write() verschickt wird. Das erste Wort ent-
  127. hält jeweils die Nummer der Nachricht, das zweite die Applikations-ID
  128. des Absenders, das dritte ist immer Null. Die Belegung der anderen
  129. Worte ist von der jeweiligen Nachricht abhängig. Worte, für die keine
  130. Belegung angegeben wird, sind auf Null zu setzen.
  131.  
  132. Bitte beachten: Da die Zählung bei 0 beginnt, ist mit "Wort 3" im fol-
  133. genden das vierte Wort gemeint!
  134.  
  135. Zur Verdeutlichung nochmals in C:
  136.  
  137.       int msg[8];
  138.      
  139.       msg[0] = SE_ACK;   /* Nachricht                         */
  140.       msg[1] = gl_apid;  /* ID des Absenders                  */
  141.       msg[2] = 0;        /* 0, d.h. keine Überlänge           */
  142.       msg[3] = TRUE;     /* dies ist "Wort 3"                 */
  143.       msg[4] = msg[5] = msg[6] = msg[7] = 0; /* Rest auf Null */
  144.       appl_write (editor, 16, msg);          /* abschicken    */
  145.  
  146.  
  147. Wenn in einer Nachricht ein Zeiger (d.h. eine Adresse) enthalten ist,
  148. dann wird das obere Wort der Adresse im ersten und das untere Wort im
  149. zweiten der angegebenen Worte übergeben.
  150.  
  151. Bei den Zeigern auf Speicherbereiche ist vom jeweiligen Absender der
  152. Nachricht darauf zu achten, da₧ diese Speicherbereiche vom Empfänger
  153. auch lesbar sind (Memory Protection!). Dafür sind diese als "Readable"
  154. zu allozieren! Das geschieht über den Gemdos-Aufruf Mxalloc().
  155.  
  156.  
  157. Bei einigen Nachrichten können Zeilen- und Spaltennummern für eine
  158. Cursorposition übergeben werden. Da es unterschiedliche Auffassungen
  159. darüber gibt, ob Zeilen und/oder Spalten ab Null oder ab Eins gezählt
  160. werden, wird empfohlen, diese Angaben vor der Übernahme zu überprüfen
  161. und ggfs. zu korrigieren. Wenn der Editor seine Zeilen also ab Eins
  162. zählt, dann sollte ihn die Zeilennummer Null nicht aus der Fassung
  163. bringen, sondern er sollte sie wie Zeile Eins behandeln.
  164.  
  165.  
  166.  
  167. 2  Nachrichten der Shell an den Editor
  168. **************************************
  169.  
  170. Die Shell kann folgende Nachrichten bzw. Kommandos an den Editor sen-
  171. den:
  172.  
  173.       Nachricht     Nummer
  174.      ----------------------
  175.       SE_INIT       0x4200
  176.       SE_OK         0x4201
  177.       SE_ACK        0x4202
  178.       SE_OPEN       0x4203
  179.       SE_ERROR      0x4204
  180.       SE_ERRFILE    0x4205
  181.       SE_PROJECT    0x4206
  182.       SE_QUIT       0x4207
  183.       SE_TERMINATE  0x4208
  184.       SE_CLOSE      0x4209
  185.       SE_MENU       0x420A
  186.  
  187.  
  188. 2.1  SE_INIT
  189. ============
  190.  
  191. Die Shell fragt an, ob ein Editor das SE-Protokoll versteht.
  192.  
  193.  
  194. Aufbau der Nachricht
  195.  
  196.  Wort 3:     Ein Bitset, welche Nachrichten die Shell versendet:
  197.  
  198.                    Nachricht    Bit  Hex-Wert
  199.                   ----------------------------
  200.                    SE_INIT       0    0x0001
  201.                    SE_OK         1    0x0002
  202.                    SE_ACK        2    0x0004
  203.                    SE_OPEN       3    0x0008
  204.                    SE_ERROR      4    0x0010
  205.                    SE_ERRFILE    5    0x0020
  206.                    SE_PROJECT    6    0x0040
  207.                    SE_QUIT       7    0x0080
  208.                    SE_TERMINATE  8    0x0100
  209.                    SE_CLOSE      9    0x0200
  210.                    SE_MENU      10    0x0400
  211.  
  212.  Wort 4+5:   Ein Bitset, welche Editorkommandos verstanden werden
  213.  
  214.                    Nachricht   Bit  Hex-Wert
  215.                   ---------------------------
  216.                    ES_INIT      0    0x0001
  217.                    ES_OK        1    0x0002
  218.                    ES_ACK       2    0x0004
  219.                    ES_COMPILE   3    0x0008
  220.                    ES_MAKE      4    0x0010
  221.                    ES_MAKEALL   5    0x0020
  222.                    ES_LINK      6    0x0040
  223.                    ES_EXEC      7    0x0080
  224.                    ES_MAKEEXEC  8    0x0100
  225.                    ES_PROJECT   9    0x0200
  226.                    ES_QUIT     10    0x0400
  227.                    ES_SHLCTRL  11    0x0800
  228.  
  229.              Hinweis: Wort 4 und 5 bilden zusammen ein Langwort. Da
  230.              für die bisher definierten Nachrichten aber nur 12 Bits
  231.              benötigt werden, ist Wort 4 normalerweise Null.
  232.  
  233.  Wort 6:     Unterstützte Versionsnummer des Protokolls als BCD-Zahl,
  234.              also 0x0105 (hexadezimal) für Version 1.05
  235.  
  236.  
  237. Antwort
  238.  
  239. Der Editor antwortet mit der Nachricht ES_OK.
  240.  
  241.  
  242. siehe auch: ES_OK, SE_QUIT
  243.  
  244.  
  245. 2.2  SE_OK
  246. ==========
  247.  
  248. Die Shell sagt dem Editor, da₧ sie das Protokoll versteht.
  249.  
  250.  
  251. Aufbau der Nachricht
  252.  
  253.  Wort 3:     Ein Bitset, welche Nachrichten die Shell versendet:
  254.  
  255.                    Nachricht    Bit  Hex-Wert
  256.                   ----------------------------
  257.                    SE_INIT       0    0x0001
  258.                    SE_OK         1    0x0002
  259.                    SE_ACK        2    0x0004
  260.                    SE_OPEN       3    0x0008
  261.                    SE_ERROR      4    0x0010
  262.                    SE_ERRFILE    5    0x0020
  263.                    SE_PROJECT    6    0x0040
  264.                    SE_QUIT       7    0x0080
  265.                    SE_TERMINATE  8    0x0100
  266.                    SE_CLOSE      9    0x0200
  267.                    SE_MENU      10    0x0400
  268.  
  269.  Wort 4+5:   Ein Bitset, welche Editorkommandos verstanden werden:
  270.  
  271.                    Nachricht   Bit  Hex-Wert
  272.                   ---------------------------
  273.                    ES_INIT      0    0x0001
  274.                    ES_OK        1    0x0002
  275.                    ES_ACK       2    0x0004
  276.                    ES_COMPILE   3    0x0008
  277.                    ES_MAKE      4    0x0010
  278.                    ES_MAKEALL   5    0x0020
  279.                    ES_LINK      6    0x0040
  280.                    ES_EXEC      7    0x0080
  281.                    ES_MAKEEXEC  8    0x0100
  282.                    ES_PROJECT   9    0x0200
  283.                    ES_QUIT     10    0x0400
  284.                    ES_SHLCTRL  11    0x0800
  285.  
  286.              Hinweis: Wort 4 und 5 bilden zusammen ein Langwort. Da
  287.              für die bisher definierten Nachrichten aber nur 12 Bits
  288.              benötigt werden, ist Wort 4 normalerweise Null.
  289.  
  290.  Wort 6:     Unterstützte Versionsnummer des Protokolls als BCD-Zahl,
  291.              also 0x0105 (hexadezimal) für Version 1.05
  292.  
  293.  Wort 7:     Die ApId des Programmes, dessen Nachricht beantwortet
  294.              wird
  295.  
  296.  
  297. Antwort
  298.  
  299. Keine. SE_OK ist bereits die Antwort der Shell auf die Nachricht
  300. ES_INIT.
  301.  
  302.  
  303. 2.3  SE_ACK
  304. ===========
  305.  
  306. Die Shell bestätigt den Empfang eines Editorkommandos und gibt zurück,
  307. ob das Kommando ausgeführt wird.
  308.  
  309.  
  310. Aufbau der Nachricht
  311.  
  312.  Wort 3:     TRUE : Kommando wird verstanden und ausgeführt,
  313.              FALSE: Das Kommando wird nicht verstanden
  314.  
  315.              Ein SE_ACK mit TRUE sagt nichts darüber aus, ob das Kom-
  316.              mando erfolgreich ausgeführt wurde. Es sagt nur, da₧ die
  317.              Shell das Kommando versteht und ausführen wird!
  318.  
  319.  
  320. Antwort
  321.  
  322. Keine (SE_ACK ist bereits die Antwort auf eine Nachricht).
  323.  
  324.  
  325. 2.4  SE_OPEN
  326. ============
  327.  
  328. Die Shell sagt dem Editor, da₧ er einen Text öffnen soll.
  329.  
  330.  
  331. Aufbau der Nachricht
  332.  
  333.  Wort 3+4:   Ein Zeiger auf den Filenamen des zu öffnenden Files
  334.  
  335.  Wort 5+6:   Zeile, in die der Cursor positioniert werden soll
  336.  
  337.  Wort 7:     Spalte, in die der Cursor positioniert werden soll
  338.  
  339.  
  340. Antwort
  341.  
  342. Als Antwort erhält die Shell ein ES_ACK.
  343.  
  344.  
  345. Hinweise: Die Angabe einer Zeilen- und Spaltennummer ist erst ab Pro-
  346. tokollversion 1.02 vorgesehen. Programme, die noch ältere Protokoll-
  347. versionen verwenden, sollten aber eigentlich die Worte 5-7 auf Null
  348. gesetzt haben. Will man ganz sicher gehen, mu₧ man ggfs. die bei
  349. SE_INIT bzw. SE_OK übergebene Versionsnummer der Shell abfragen.
  350.  
  351. Wenn die Shell keine Positionsangabe machen kann oder will, sollte sie
  352. Zeile und Spalte auf Null setzen.
  353.  
  354.  
  355. 2.5  SE_ERROR
  356. =============
  357.  
  358. Es ist ein Fehler beim Compilieren aufgetreten.
  359.  
  360.  
  361. Aufbau der Nachricht
  362.  
  363.  Wort 3+4:   Ein Zeiger auf eine Infostruktur, die wie folgt aufgebaut
  364.              ist:
  365.  
  366.     typedef struct
  367.     {
  368.       char *errFile; /* Zeiger auf den Namen der compilierten Datei */
  369.       char *errMess; /* Zeiger auf die Fehlermeldung                */
  370.       int errNum;    /* Die Fehlernummer                            */
  371.       long errLine;  /* Die fehlerhafte Zeile                       */
  372.       int errRow;    /* Die Spalte mit dem Fehler (oder 0)          */
  373.     } ERRINFO;
  374.  
  375.  
  376. Antwort
  377.  
  378. Mit ES_ACK bestätigt der Editor die Meldung.
  379.  
  380.  
  381. Hinweis: Wenn die Shell keine Positionsangabe machen kann oder will,
  382. sollte sie Zeile und Spalte auf Null setzen.
  383.  
  384.  
  385. 2.6  SE_ERRFILE
  386. ===============
  387.  
  388. Es sind Fehler aufgetreten. Die Fehlermeldungen stehen in einem Error-
  389. file, welches in der Message spezifiziert wird.
  390.  
  391.  
  392. Aufbau der Nachricht
  393.  
  394.  Wort 3+4:   Ein Zeiger auf den Filenamen des Errorfiles mit den
  395.              Fehlermeldungen
  396.  
  397.  Wort 5+6:   Ein Zeiger auf den Namen des compilierten Textes
  398.  
  399.  
  400. Antwort
  401.  
  402. Mit ES_ACK bestätigt der Editor die Meldung.
  403.  
  404.  
  405. 2.7  SE_PROJECT
  406. ===============
  407.  
  408. Die Shell teilt dem Editor mit, da₧ das Projekt geändert wurde. Der
  409. Filename des aktuellen Projektfiles wird als Parameter übergeben. Wird
  410. NULL übergeben, sollte das aktuelle Projekt abgemeldet werden.
  411.  
  412. Eine vernünftige Reaktion des Editors wäre es in dem Fall, ebenfalls
  413. das Projekt zu wechseln, sofern er dies unterstützt.
  414.  
  415.  
  416. Aufbau der Nachricht
  417.  
  418.  Wort 3+4:   Ein Zeiger auf den Namen des Projektfiles oder NULL.
  419.  
  420.  
  421. Antwort
  422.  
  423. Der Editor bestätigt mit ES_ACK.
  424.  
  425.  
  426. Hinweis: Den Namen des Projektfiles auf NULL zu setzen, ist erst ab
  427. Protokollversion 1.01 vorgesehen. Die Shell sollte daher vorher über-
  428. prüfen, ob der Editor mindestens Protokollversion 1.01 unterstützt.
  429.  
  430.  
  431. 2.8  SE_QUIT
  432. ============
  433.  
  434. Die Shell teilt dem Editor mit, da₧ sie jetzt beendet wird. Der Editor
  435. sollte in dem Fall die Shell als Kommunikationspartner vergessen.
  436.  
  437.  
  438. Aufbau der Nachricht
  439.  
  440.  keine Parameter
  441.  
  442.  
  443. Antwort
  444.  
  445. Es wird keine Antwort erwartet!
  446.  
  447.  
  448. 2.9  SE_TERMINATE
  449. =================
  450.  
  451. Die Shell teilt dem Editor mit, da₧ dieser sich beenden soll. Der Edi-
  452. tor sollte in dem Fall sich selbst beenden und seinen ganz normalen
  453. Terminierungsproze₧ durchlaufen (und dabei auch ein ES_QUIT verschik-
  454. ken!). Der Grund für so eine Meldung der Shell könnte zum Beispiel zu
  455. wenig Speicher zum Compilieren sein.
  456.  
  457.  
  458. Aufbau der Nachricht
  459.  
  460.  keine Parameter
  461.  
  462.  
  463. Antwort
  464.  
  465. Mit ES_ACK bestätigt der Editor die Meldung.
  466.  
  467.  
  468. 2.10  SE_CLOSE
  469. ==============
  470.  
  471. Die Shell teilt dem Editor mit, da₧ dieser bestimmte Texte sichern
  472. bzw. schlie₧en soll. Beim Schlie₧en von geänderten Texten sollte der
  473. Editor vorher nachfragen.
  474.  
  475.  
  476. Aufbau der Nachricht
  477.  
  478.  Wort 3+4:   Ein Zeiger auf den Namen einer Datei oder eine Datei-
  479.              maske. "*.*" steht für alle Textfenster (entspricht also
  480.              dem SE_CLOSE der Protokollversion 1.00).
  481.  
  482.  Wort 5:     0 = nur sichern
  483.              1 = sichern und schlie₧en
  484.              2 = schlie₧en ohne Sichern (ab Version 1.04)
  485.  
  486.  
  487. Antwort
  488.  
  489. Mit ES_ACK bestätigt der Editor die Meldung.
  490.  
  491.  
  492. Hinweis: In der Protokollversion 1.00 waren für SE_CLOSE noch keine
  493. Parameter vorgesehen. Editoren, die nur Version 1.00 unterstützen,
  494. werden daher die Dateimasken und das Flag ignorieren und alle Texte
  495. sichern.
  496.  
  497.  
  498. 2.11  SE_MENU
  499. =============
  500.  
  501. Die Shell teilt dem Editor mit, was er für die einzelnen Programme in
  502. sein Menü eintragen soll. Der Editor kann somit für die Menüpunkte,
  503. die eine Aktion in der Shell auslösen, die gleichen Texte wie die
  504. Shell verwenden.
  505.  
  506.  
  507. Aufbau der Nachricht
  508.  
  509.  Wort 3+4:   Ein Zeiger auf eine Infostruktur, die wie folgt aufgebaut
  510.              ist:
  511.  
  512.   typedef struct
  513.   {
  514.     char *compStr;      /* Text für den Menüpunkt "Compiler"       */
  515.     char *makeStr;      /* Text für den Menüpunkt "Makefile"       */
  516.     char *makeAllStr;   /* Text für den Menüpunkt "Make all"       */
  517.     char *linkStr;      /* Text für den Menüpunkt "Linker"         */
  518.     char *execStr;      /* Text für den Menüpunkt "Execute"        */
  519.     char *makeExecStr;  /* Text für den Menüpunkt "Make & Execute" */
  520.     char *progName;     /* Name der Shell (ab Version 1.04)        */
  521.     char *shellCtrlStr; /* Text für den Menüpunkt "Shell Control"  */
  522.                         /* (ab Version 1.05)                       */
  523.   } SEMENUINFO;
  524.  
  525.  
  526. Antwort
  527.  
  528. Mit ES_ACK bestätigt der Editor die Meldung.
  529.  
  530.  
  531. Hinweise: Die Texte sind allesamt optional und können auch NULL sein,
  532. wenn die Shell keinen entsprechenden Menüpunkt hat. Dies bedeutet
  533. jedoch nicht, da₧ die Shell nicht über diese Funktionalität verfügt.
  534. Der Editor sollte daher für alle Texte ggfs. Defaulttexte einsetzen.
  535.  
  536. Diese Nachricht existiert erst ab Protokollversion 1.02. Es genügt
  537. aber der Test, ob das entsprechende Bit in ES_INIT bzw. ES_OK gesetzt
  538. ist.
  539.  
  540. Beim Zugriff auf progName und shellCtrlStr mu₧ darauf geachtet werden,
  541. da₧ der Kommunikationspartner diese auch schon unterstützt (Proto-
  542. kollversion testen)!
  543.  
  544.  
  545.  
  546. 3  Nachrichten des Editors an die Shell
  547. ***************************************
  548.  
  549. Der Editor kann folgende Nachrichten bzw. Kommandos an die Shell sen-
  550. den:
  551.  
  552.       Nachricht    Nummer
  553.      ---------------------
  554.       ES_INIT      0x4240
  555.       ES_OK        0x4241
  556.       ES_ACK       0x4242
  557.       ES_COMPILE   0x4243
  558.       ES_MAKE      0x4244
  559.       ES_MAKEALL   0x4245
  560.       ES_LINK      0x4246
  561.       ES_EXEC      0x4247
  562.       ES_MAKEEXEC  0x4248
  563.       ES_PROJECT   0x4249
  564.       ES_QUIT      0x424A
  565.       ES_SHLCTRL   0x424B
  566.  
  567.  
  568. 3.1  ES_INIT
  569. ============
  570.  
  571. Ein Editor fragt an, ob eine Shell das SE-Protokoll versteht.
  572.  
  573.  
  574. Aufbau der Nachricht
  575.  
  576.  Wort 3:     Ein Bitset, welche Shellnachrichten verstanden werden:
  577.  
  578.                    Nachricht    Bit  Hex-Wert
  579.                   ----------------------------
  580.                    SE_INIT       0    0x0001
  581.                    SE_OK         1    0x0002
  582.                    SE_ACK        2    0x0004
  583.                    SE_OPEN       3    0x0008
  584.                    SE_ERROR      4    0x0010
  585.                    SE_ERRFILE    5    0x0020
  586.                    SE_PROJECT    6    0x0040
  587.                    SE_QUIT       7    0x0080
  588.                    SE_TERMINATE  8    0x0100
  589.                    SE_CLOSE      9    0x0200
  590.                    SE_MENU      10    0x0400
  591.  
  592.  Wort 4+5:   Ein Bitset, welche Editorkommandos versendet werden:
  593.  
  594.                    Nachricht   Bit  Hex-Wert
  595.                   ---------------------------
  596.                    ES_INIT      0    0x0001
  597.                    ES_OK        1    0x0002
  598.                    ES_ACK       2    0x0004
  599.                    ES_COMPILE   3    0x0008
  600.                    ES_MAKE      4    0x0010
  601.                    ES_MAKEALL   5    0x0020
  602.                    ES_LINK      6    0x0040
  603.                    ES_EXEC      7    0x0080
  604.                    ES_MAKEEXEC  8    0x0100
  605.                    ES_PROJECT   9    0x0200
  606.                    ES_QUIT     10    0x0400
  607.                    ES_SHLCTRL  11    0x0800
  608.  
  609.              Hinweis: Wort 4 und 5 bilden zusammen ein Langwort. Da
  610.              für die bisher definierten Nachrichten aber nur 12 Bits
  611.              benötigt werden, ist Wort 4 normalerweise Null.
  612.  
  613.  Wort 6:     Unterstützte Versionsnummer des Protokolls als BCD-Zahl,
  614.              also 0x0105 (hexadezimal) für Version 1.05
  615.  
  616.  
  617. Antwort
  618.  
  619. Als Antwort erhält der Editor SE_OK von der Shell.
  620.  
  621.  
  622. 3.2  ES_OK
  623. ==========
  624.  
  625. Der Editor beantwortet die Anfrage der Shell nach dem Protokoll.
  626.  
  627.  
  628. Aufbau der Nachricht
  629.  
  630.  Wort 3:     Ein Bitset, welche Shellnachrichten verstanden werden:
  631.  
  632.                    Nachricht    Bit  Hex-Wert
  633.                   ----------------------------
  634.                    SE_INIT       0    0x0001
  635.                    SE_OK         1    0x0002
  636.                    SE_ACK        2    0x0004
  637.                    SE_OPEN       3    0x0008
  638.                    SE_ERROR      4    0x0010
  639.                    SE_ERRFILE    5    0x0020
  640.                    SE_PROJECT    6    0x0040
  641.                    SE_QUIT       7    0x0080
  642.                    SE_TERMINATE  8    0x0100
  643.                    SE_CLOSE      9    0x0200
  644.                    SE_MENU      10    0x0400
  645.  
  646.  Wort 4+5:   Ein Bitset, welche Editorkommandos versendet werden:
  647.  
  648.                    Nachricht   Bit  Hex-Wert
  649.                   ---------------------------
  650.                    ES_INIT      0    0x0001
  651.                    ES_OK        1    0x0002
  652.                    ES_ACK       2    0x0004
  653.                    ES_COMPILE   3    0x0008
  654.                    ES_MAKE      4    0x0010
  655.                    ES_MAKEALL   5    0x0020
  656.                    ES_LINK      6    0x0040
  657.                    ES_EXEC      7    0x0080
  658.                    ES_MAKEEXEC  8    0x0100
  659.                    ES_PROJECT   9    0x0200
  660.                    ES_QUIT     10    0x0400
  661.                    ES_SHLCTRL  11    0x0800
  662.  
  663.              Hinweis: Wort 4 und 5 bilden zusammen ein Langwort. Da
  664.              für die bisher definierten Nachrichten aber nur 12 Bits
  665.              benötigt werden, ist Wort 4 normalerweise Null.
  666.  
  667.  Wort 6:     Unterstützte Versionsnummer des Protokolls als BCD-Zahl,
  668.              also 0x0105 (hexadezimal) für Version 1.05
  669.  
  670.  Wort 7:     Die ApId des Programmes, dessen Nachricht beantwortet
  671.              wird
  672.  
  673.  
  674. Antwort
  675.  
  676. Keine. ES_OK ist bereits die Antwort des Editors auf die Nachricht
  677. SE_INIT.
  678.  
  679.  
  680. 3.3  ES_ACK
  681. ===========
  682.  
  683. Der Editor bestätigt den Empfang des Kommandos.
  684.  
  685.  
  686. Aufbau der Nachricht
  687.  
  688.  Wort 3:     TRUE : Kommando wird verstanden und ausgeführt,
  689.              FALSE: Das Kommando wird nicht verstanden
  690.  
  691.              Ein ES_ACK mit TRUE sagt nichts darüber aus, ob das Kom-
  692.              mando erfolgreich ausgeführt wurde. Es sagt nur, da₧ der
  693.              Editor das Kommando versteht und ausführen wird!
  694.  
  695.  
  696. Antwort
  697.  
  698. Keine (ES_ACK ist bereits die Antwort auf eine Nachricht).
  699.  
  700.  
  701. 3.4  ES_COMPILE
  702. ===============
  703.  
  704. Der Editor sagt der Shell, da₧ sie ein File übersetzen soll. Ein Zei-
  705. ger auf den Dateinamen kann in der Nachricht übergeben werden.
  706.  
  707.  
  708. Aufbau der Nachricht
  709.  
  710.  Wort 3+4:   Zeiger auf den Namen der zu compilierenden Datei oder
  711.              NULL.
  712.  
  713.  
  714. Antwort
  715.  
  716. Diese Nachricht mu₧ mit SE_ACK bestätigt werden.
  717.  
  718.  
  719. Hinweis: Den Namen der zu compilierenden Datei auf NULL zu setzen, ist
  720. erst ab Protokollversion 1.03 vorgesehen. Der Editor sollte daher
  721. vorher überprüfen, ob die Shell mindestens Protokollversion 1.03
  722. unterstützt.
  723.  
  724.  
  725. 3.5  ES_MAKE
  726. ============
  727.  
  728. Der Editor sagt der Shell, da₧ sie ein Make ausführen soll. Ein File-
  729. name kann in der Nachricht übergeben werden, mu₧ aber nicht gesetzt
  730. sein und mu₧ von der Shell auch nicht beachtet werden!
  731.  
  732.  
  733. Aufbau der Nachricht
  734.  
  735.  Wort 3+4:   Zeiger auf den Namen des Makefiles (oder NULL)
  736.  
  737.  
  738. Antwort
  739.  
  740. Die Shell bestätigt mit SE_ACK.
  741.  
  742.  
  743. 3.6  ES_MAKEALL
  744. ===============
  745.  
  746. Der Editor sagt der Shell, da₧ ein komplettes "Make All" ausgeführt
  747. werden soll. Ein Filename für das Makefile kann (mu₧ aber nicht) in
  748. der Nachricht übergeben werden.
  749.  
  750.  
  751. Aufbau der Nachricht
  752.  
  753.  Wort 3+4:   Zeiger auf den Namen des Makefiles (oder NULL)
  754.  
  755.  
  756. Antwort
  757.  
  758. Die Shell bestätigt mit SE_ACK.
  759.  
  760.  
  761. 3.7  ES_LINK
  762. ============
  763.  
  764. Der Editor sagt der Shell, da₧ das Programm gelinkt werden soll. Ein
  765. Filename kann in der Nachricht übergeben werden, mu₧ aber nicht unbe-
  766. dingt von der Shell beachtet werden!
  767.  
  768.  
  769. Aufbau der Nachricht
  770.  
  771.  Wort 3+4:   Zeiger auf den Namen der Source, die gelinkt werden soll
  772.              (oder NULL)
  773.  
  774.  
  775. Antwort
  776.  
  777. Die Shell bestätigt mit SE_ACK.
  778.  
  779.  
  780. 3.8  ES_EXEC
  781. ============
  782.  
  783. Der Editor sagt der Shell, da₧ das Programm zu der Source ausgeführt
  784. werden soll. Ein Filename kann übergeben werden, mu₧ von der Shell
  785. aber nicht beachtet werden.
  786.  
  787.  
  788. Aufbau der Nachricht
  789.  
  790.  Wort 3+4:   Zeiger auf den Namen des auszuführenden Files (oder
  791.              NULL).
  792.  
  793.              Bei einer Sourcedatei ist diese ggf. noch zu compilieren
  794.              und/oder zu linken
  795.  
  796.  
  797. Antwort
  798.  
  799. Die Shell bestätigt mit SE_ACK.
  800.  
  801.  
  802. 3.9  ES_MAKEEXEC
  803. ================
  804.  
  805. Die Shell soll ein Make ausführen und danach das Programm ausführen.
  806. Ein Filename für das Makefile kann (mu₧ aber nicht) in der Nachricht
  807. übergeben werden.
  808.  
  809.  
  810. Aufbau der Nachricht
  811.  
  812.  Wort 3+4:   Zeiger auf den Namen des Makefiles (oder NULL)
  813.  
  814.  
  815. Antwort
  816.  
  817. Die Shell bestätigt mit SE_ACK.
  818.  
  819.  
  820. 3.10  ES_PROJECT
  821. ================
  822.  
  823. Der Editor teilt der Shell mit, da₧ das Projekt geändert/gewechselt
  824. wurde. Der Filename des Projektfiles wird als Parameter in der Nach-
  825. richt übergeben. Wird NULL übergeben, sollte das aktuelle Projekt
  826. abgemeldet werden.
  827.  
  828. Eine vernünftige Reaktion der Shell wäre in dem Fall, ebenfalls das
  829. Projekt zu wechseln, sofern sie dies unterstützt.
  830.  
  831.  
  832. Aufbau der Nachricht
  833.  
  834.  Wort 3+4:   Zeiger auf den Namen des Projektfiles oder NULL
  835.  
  836.  
  837. Antwort
  838.  
  839. Die Shell bestätigt mit SE_ACK.
  840.  
  841.  
  842. Hinweis: Den Namen des Projektfiles auf NULL zu setzen, ist erst ab
  843. Protokollversion 1.01 vorgesehen. Der Editor sollte daher vorher über-
  844. prüfen, ob die Shell mindestens Protokollversion 1.01 unterstützt.
  845.  
  846.  
  847. 3.11  ES_QUIT
  848. =============
  849.  
  850. Der Editor teilt der Shell mit, da₧ er jetzt beendet wird. Die Shell
  851. sollte in dem Fall den Editor als Kommunikationspartner vergessen.
  852.  
  853.  
  854. Aufbau der Nachricht
  855.  
  856.  keine Parameter
  857.  
  858.  
  859. Antwort
  860.  
  861. Es wird keine Antwort erwartet!
  862.  
  863.  
  864. 3.12  ES_SHLCTRL
  865. ================
  866.  
  867. Nachricht des Editors zur Kontrolle der Shell.
  868.  
  869.  
  870. Aufbau der Nachricht
  871.  
  872.  Wort 3+4:   Zeiger auf den Namen des obersten Fensters des Editors
  873.              oder NULL
  874.  
  875.  Wort 5:     Steuer-Flags:
  876.              Bit 0: Shell soll sich toppen (Menü/Fenster)
  877.  
  878.  
  879. Antwort
  880.  
  881. Die Shell bestätigt mit SE_ACK.
  882.  
  883.  
  884. Hinweis: Diese Nachricht existiert erst ab Protokollversion 1.05. Die
  885. übrigen Bits von Wort 5 sind für zukünftige Erweiterungen reserviert.
  886.  
  887.  
  888.  
  889. 4  History
  890. **********
  891.  
  892. Version 1.05 vom 23.12.1997
  893.  
  894.    ∙ neue Nachricht ES_SHLCTRL
  895.  
  896.    ∙ neuer Eintrag shellCtrlStr in der Struktur SEMENUINFO bei SE_MENU
  897.  
  898.  
  899. Version 1.04 vom 08.01.1997
  900.  
  901.    ∙ Flag 2 ("nur schlie₧en") bei SE_CLOSE
  902.  
  903.    ∙ neuer Eintrag progName in der Struktur SEMENUINFO bei SE_MENU
  904.  
  905.  
  906. Version 1.03 vom 19.11.1996
  907.  
  908.    ∙ bei ES_COMPILE kann der Zeiger auf den Dateinamen jetzt auch NULL
  909.      sein.
  910.  
  911.  
  912. Version 1.02 vom 13.08.1996
  913.  
  914.    ∙ neue Nachricht SE_MENU
  915.  
  916.    ∙ bei SE_OPEN kann nun auch eine Zeile und eine Spalte angegeben
  917.      werden
  918.  
  919.  
  920. Version 1.01 vom 30.01.1996
  921.  
  922.    ∙ Angabe von Dateimasken und Close-Flag bei SE_CLOSE
  923.  
  924.    ∙ Projektname bei SE_PROJECT und ES_PROJECT kann auch NULL sein
  925.  
  926.  
  927. Version 1.00 vom 17.01.1994
  928.  
  929.    ∙ erste öffentliche Version
  930.  
  931.  
  932.  
  933. 5  Autoren und Programme
  934. ************************
  935.  
  936. Das SE-Protokoll wurde von Dirk Steins @ K2 und Frank Storm @ AC2 ent-
  937. wickelt, die Erweiterungen zu den neueren Protokollversionen stammen
  938. von Christian Felsch @ HH und Dirk Haun @ WI2.
  939.  
  940. Die Zahl der Programme, die das SE-Protokoll unterstützen, ist leider
  941. noch nicht allzu gro₧:
  942.  
  943.    ∙ Editoren:
  944.  
  945.         - Everest von Oliver Schmidt (ab Version 3.5)
  946.  
  947.         - Fred von Dirk Steins
  948.  
  949.         - qed von Christian Felsch (ab Version 3.3, ab Version 3.70
  950.           wird zudem Protokollversion 1.01 unterstützt)
  951.  
  952.    ∙ Shells:
  953.  
  954.         - Chatwin von Dirk Haun (ab Version 3.04 wird das SE-Protokoll
  955.           komplett unterstützt, ältere Versionen unterstützen nur die
  956.           wichtigsten Nachrichten)
  957.  
  958.         - Shell zum Megamax Modula-2 von Thomas Tempelmann
  959.  
  960.         - PC-Shell von Frank Schramm (ab Version 3.01)
  961.  
  962.    ∙ Sonstiges:
  963.  
  964.         - SE-Lib von Manfred Rosenboom und Dirk Haun
  965.  
  966.           Dieser Bibliothek liegt auch der SE-Evaluator, eine Art
  967.           Debugger für das SE-Protokoll, bei.
  968.  
  969. Es bleibt zu hoffen, da₧ weitere Editoren und Shells dieses nützliche
  970. Protokoll unterstützen werden. Dieser Text trägt dabei hoffentlich et-
  971. was zur Verbreitung bei ...
  972.  
  973.  
  974. Dirk Haun, 4. Januar 1998
  975.  
  976.  
  977.  
  978.