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