home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ST-Computer Leser 1998 October
/
STC_CD_10_1998.iso
/
BASE
/
SEPROTO
/
SEPROTO.U
< prev
next >
Wrap
Text File
|
1998-09-26
|
33KB
|
1,096 lines
# ########################################################################
# @(#)seproto.u, Dirk Haun, 04.01.1998
# Beschreibung des SE-Protokolls
# ########################################################################
#
# Geschrieben mit UDO Release 6 PL 7
#
# ########################################################################
!language german
!docinfo [author] Dirk Haun
!docinfo [address] Europastr. 8
!docinfo [address] D-64569 Nauheim
!docinfo [address] ~
!docinfo [address] Dirk Haun @ WI2
!docinfo [title] Dokumentation zum
!docinfo [program] SE-Protokoll
!docinfo [version] Version 1.05
!docinfo [date] 04.01.1998
!hyphen Edi!-tor
!hyphen File!-name
!hyphen Kom!-man!-do
!hyphen Multi!-tasking
!hyphen Pro!-to!-koll
!hyphen schic!-ken
!hyphen Zei!-ger
!raw [stg] @subject "Programmieren/Atari"
!raw [stg] @options "+i +f +z"
!raw [stg] @extern "Chatwin" CHATWIN.HYP/Main
!raw [stg] @extern "Everest" EVEREST.HYP
!raw [stg] @extern "Fred" FRED.HYP/Main
!raw [stg] @extern "PC-Shell" PC_SHELL.HYP/Main
!raw [stg] @extern "qed" QED.HYP/Main
!raw [stg] @extern "SE-Lib" SELIB.HYP/Main
!raw [stg] @extern "Mxalloc" TOS.HYP/Mxalloc
!raw [stg] @extern "appl_write" TOS.HYP/appl_write
!raw [stg] @extern "appl_search" TOS.HYP/appl_search
!raw [stg] @extern "XAcc-Protokoll" XACC.HYP/Main
!use_nodes_inside_index [all]
!use_label_inside_index [all]
!use_alias_inside_index [all]
!no_effects asc
!begin_document
!maketitle
!tableofcontents
# ########################################################################
!node Einleitung
Sinn des SE-Protokolls ist die Kommunikation zwischen Shells zur
Pro!-gramm!-ent!-wicklung 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 ver!-an!-lassen,
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
(!V)SE_(!v), Nachrichten vom Editor an die Shell beginnen mit
(!V)ES_(!v).
Die aktuelle Versionsnummer des Protokolls ist 1.05.
!ifdest stg
Bitte lesen Sie auch !..
!subtoc stg
!endif
# ========================================================================
!subnode Kontaktaufnahme
Die Kontaktaufnahme läuft wie folgt ab:
Die Shell verschickt nach dem Start die Nachricht (!V)SE_INIT(!v). Als
Ant!-wort erhält sie darauf die Nachricht (!V)ES_OK(!v). Aus den
Bitfeldern in den bei!-den Nachrichten kann die Shell nun ableiten,
welche Kommandos sie an den Editor schicken kann und welche Kommandos
vom Editor zu er!-war!-ten sind. Wenn die Shell nicht mehr am
SE-Protokoll teilnehmen will (z.B. weil sie beendet wird), dann
schickt sie die Nachricht (!V)SE_QUIT(!v) an den Editor.
Der Editor verschickt nach dem Start die Nachricht (!V)ES_INIT(!v).
Als Ant!-wort erhält sie darauf die Nachricht (!V)SE_OK(!v). 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 er!-war!-ten sind. Wenn der Editor nicht mehr am
SE-Protokoll teilnehmen will (z.B. weil er beendet wird), dann schickt
er die Nachricht (!V)ES_QUIT(!v) 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 (!V)appl_search()(!v) zur Verfügung stehen. Shell und
Editor sollten also ein!-fach ihre jeweilige Init-Nachricht an alle
Prozesse (au₧er an System!-pro!-zesse) schicken.
Andere Möglichkeiten:
!begin_itemize
!item Wenn die Shell den Namen ihres Editors kennt, kann sie sich
na!-tür!-lich auch darauf beschränken, (!V)SE_INIT(!v) nur an
diesen zu schicken.
!index XAcc-Protokoll
!item Wenn die Funktion (!V)appl_search()(!v) nicht zur Verfügung
steht, bie!-tet sich das XAcc-Protokoll zur Kontaktaufnahme an:
Shell und Editor sollten ihre Init-Nachrichten dann einfach an
jeden Pro!-ze₧ schicken, der sich per XAcc anmeldet. Das
XAcc-Protokoll sieht au₧er!-dem noch eine maschinenlesbare
Kennung des Pro!-gramm!-typs (XDSC) vor, so da₧ man u.U. sogar
erkennen kann, ob es sich bei dem
Kom!-mu!-ni!-ka!-ti!-ons!-part!-ner um eine Shell (Kennung
''PE'' für ""Pro!-gramming En!-vi!-ron!-ment"") oder um einen
Editor (Kennung ''ED'' für ""Text Editor"") handelt.
!end_itemize
# ========================================================================
!subnode Anmerkungen
!index Nachricht
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 (!V)appl_write()(!v) verschickt wird. Das erste
Wort ent!-hält jeweils die Nummer der Nachricht, das zweite die
Ap!-pli!-ka!-ti!-ons-ID des Absenders, das dritte ist immer Null. Die
Be!-le!-gung der anderen Worte ist von der jeweiligen Nachricht
abhängig. Worte, für die keine Belegung angegeben wird, sind auf Null
zu setzen.
(!B)Bitte beachten:(!b) Da die Zählung bei 0 beginnt, ist mit ""Wort
3"" im fol!-gen!-den das (!I)vierte(!i) Wort gemeint!
Zur Verdeutlichung nochmals in C:
!begin_quote
!begin_verbatim
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 */
!end_verbatim
!end_quote
!smallskip
!index Zeiger
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 ""Read!-able""
zu allozieren! Das geschieht über den Gemdos-Aufruf Mxalloc().
!smallskip
!index Zeilennummern
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.
# ########################################################################
!node Nachrichten der Shell an den Editor
Die Shell kann folgende Nachrichten bzw. Kommandos an den Editor
sen!-den:
!begin_quote
!begin_verbatim
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
!end_verbatim
!end_quote
# ========================================================================
!subnode SE_INIT
!raw [stg] @xref ES_OK
!raw [stg] @xref SE_QUIT
Die Shell fragt an, ob ein Editor das SE-Protokoll versteht.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3]: Ein Bitset, welche Nachrichten die Shell versendet:
!begin_verbatim
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
!end_verbatim
!item [Wort 4+5]: Ein Bitset, welche Editorkommandos verstanden werden
!begin_verbatim
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
!end_verbatim
(!B)Hinweis:(!b) 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.
!item [Wort 6]: Unterstützte Versionsnummer des Protokolls als BCD-Zahl,
also 0x0105 (hexadezimal) für Version 1.05
!end_xlist
!smallskip
(!U)Antwort(!u)
Der Editor antwortet mit der Nachricht ES_OK.
!smallskip
(!B)siehe auch:(!b) ES_OK, SE_QUIT
# ========================================================================
!subnode SE_OK
!raw [stg] @xref ES_INIT
Die Shell sagt dem Editor, da₧ sie das Protokoll versteht.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3]: Ein Bitset, welche Nachrichten die Shell versendet:
!begin_verbatim
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
!end_verbatim
!item [Wort 4+5]: Ein Bitset, welche Editorkommandos verstanden werden:
!begin_verbatim
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
!end_verbatim
(!B)Hinweis:(!b) 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.
!item [Wort 6]: Unterstützte Versionsnummer des Protokolls als BCD-Zahl,
also 0x0105 (hexadezimal) für Version 1.05
!item [Wort 7]: Die ApId des Programmes, dessen Nachricht beantwortet wird
!end_xlist
!smallskip
(!U)Antwort(!u)
Keine. (!V)SE_OK(!v) ist bereits die Antwort der Shell auf die Nachricht
(!V)ES_INIT(!v).
# ========================================================================
!subnode SE_ACK
Die Shell bestätigt den Empfang eines Editorkommandos und gibt zu!-rück,
ob das Kommando ausgeführt wird.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3]: (!V)TRUE(!v)~: Kommando wird verstanden und ausgeführt, (!nl)
(!V)FALSE(!v): Das Kommando wird nicht verstanden
Ein (!V)SE_ACK(!v) mit (!V)TRUE(!v) 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!
!end_xlist
!smallskip
(!U)Antwort(!u)
Keine ((!V)SE_ACK(!v) ist bereits die Antwort auf eine Nachricht).
# ========================================================================
!subnode SE_OPEN
!raw [stg] @xref ES_ACK
Die Shell sagt dem Editor, da₧ er einen Text öffnen soll.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Ein Zeiger auf den Filenamen des zu öffnenden Files
!item [Wort 5+6]: Zeile, in die der Cursor positioniert werden soll
!item [Wort 7]: Spalte, in die der Cursor positioniert werden soll
!end_xlist
!smallskip
(!U)Antwort(!u)
Als Antwort erhält die Shell ein ES_ACK.
!smallskip
(!B)Hinweise:(!b) Die Angabe einer Zeilen- und Spaltennummer ist erst
ab Protokollversion 1.02 vorgesehen. Programme, die noch ältere
Protokoll!-ver!-si!-onen verwenden, sollten aber eigentlich die Worte
5-7 auf Null ge!-setzt haben. Will man ganz sicher gehen, mu₧ man
ggfs. die bei (!V)SE_INIT(!v) bzw. (!V)SE_OK(!v) übergebene
Versionsnummer der Shell abfragen.
Wenn die Shell keine Positionsangabe machen kann oder will, sollte sie
Zeile und Spalte auf Null setzen.
# ========================================================================
!subnode SE_ERROR
!raw [stg] @xref ES_ACK
Es ist ein Fehler beim Compilieren aufgetreten.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Ein Zeiger auf eine Infostruktur, die wie folgt
auf!-ge!-baut ist:
!end_xlist
!label ERRINFO
!begin_verbatim
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;
!end_verbatim
!smallskip
(!U)Antwort(!u)
Mit (!V)ES_ACK(!v) bestätigt der Editor die Meldung.
!smallskip
(!B)Hinweis:(!b) Wenn die Shell keine Positionsangabe machen kann oder
will, sollte sie Zeile und Spalte auf Null setzen.
# ========================================================================
!subnode SE_ERRFILE
!raw [stg] @xref ES_ACK
Es sind Fehler aufgetreten. Die Fehlermeldungen stehen in einem
Error!-file, welches in der Message spezifiziert wird.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Ein Zeiger auf den Filenamen des Errorfiles mit den
Fehler!-meldungen
!item [Wort 5+6]: Ein Zeiger auf den Namen des compilierten Textes
!end_xlist
!smallskip
(!U)Antwort(!u)
Mit ES_ACK bestätigt der Editor die Meldung.
# ========================================================================
!subnode SE_PROJECT
!raw [stg] @xref ES_ACK
Die Shell teilt dem Editor mit, da₧ das Projekt geändert wurde. Der
Filename des aktuellen Projektfiles wird als Parameter übergeben. Wird
(!V)NULL(!v) ü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.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Ein Zeiger auf den Namen des Projektfiles oder
(!V)NULL(!v).
!end_xlist
!smallskip
(!U)Antwort(!u)
Der Editor bestätigt mit ES_ACK.
!smallskip
(!B)Hinweis:(!b) Den Namen des Projektfiles auf (!V)NULL(!v) zu
setzen, ist erst ab Protokollversion 1.01 vorgesehen. Die Shell sollte
daher vorher über!-prüfen, ob der Editor mindestens Protokollversion
1.01 unter!-stützt.
# ========================================================================
!subnode SE_QUIT
Die Shell teilt dem Editor mit, da₧ sie jetzt beendet wird. Der Editor
sollte in dem Fall die Shell als Kommunikationspartner vergessen.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_description
!item [keine Parameter]
!end_description
!smallskip
(!U)Antwort(!u)
Es wird keine Antwort erwartet!
# ========================================================================
!subnode SE_TERMINATE
!raw [stg] @xref ES_ACK
Die Shell teilt dem Editor mit, da₧ dieser sich beenden soll. Der Editor
sollte in dem Fall sich selbst beenden und seinen ganz nor!-ma!-len
Terminierungsproze₧ durchlaufen (und dabei auch ein (!V)ES_QUIT(!v)
ver!-schic!-ken!). Der Grund für so eine Meldung der Shell könnte zum
Bei!-spiel zu wenig Speicher zum Compilieren sein.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_description
!item [keine Parameter]
!end_description
!smallskip
(!U)Antwort(!u)
Mit ES_ACK bestätigt der Editor die Meldung.
# ========================================================================
!subnode SE_CLOSE
!raw [stg] @xref ES_ACK
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.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Ein Zeiger auf den Namen einer Datei oder eine
Datei!-maske. ""(!V)*.*(!v)"" steht für alle
Textfenster (entspricht also dem (!V)SE_CLOSE(!v)
der Protokollversion 1.00).
!item [Wort 5]: 0 = nur sichern (!nl)
1 = sichern und schlie₧en (!nl)
2 = schlie₧en ohne Sichern (ab Version 1.04)
!end_xlist
!smallskip
(!U)Antwort(!u)
Mit ES_ACK bestätigt der Editor die Meldung.
!smallskip
(!B)Hinweis:(!b) In der Protokollversion 1.00 waren für
(!V)SE_CLOSE(!v) noch keine Parameter vorgesehen. Editoren, die nur
Version 1.00 unterstützen, werden daher die Dateimasken und das Flag
ignorieren und alle Texte sichern.
# ========================================================================
!subnode SE_MENU
!raw [stg] @xref ES_ACK
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.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Ein Zeiger auf eine Infostruktur, die wie folgt
auf!-ge!-baut ist:
!end_xlist
!label SEMENUINFO
!begin_verbatim
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;
!end_verbatim
!smallskip
(!U)Antwort(!u)
Mit ES_ACK bestätigt der Editor die Meldung.
!smallskip
(!B)Hinweise:(!b) Die Texte sind allesamt optional und können auch
(!V)NULL(!v) 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 (!V)ES_INIT(!v) bzw.
(!V)ES_OK(!v) gesetzt ist.
Beim Zugriff auf (!V)progName(!v) und (!V)shellCtrlStr(!v) mu₧ darauf
geachtet werden, da₧ der Kommunikationspartner diese auch schon
unterstützt (Protokollversion testen)!
# ########################################################################
!node Nachrichten des Editors an die Shell
Der Editor kann folgende Nachrichten bzw. Kommandos an die Shell sen!-den:
!begin_quote
!begin_verbatim
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
!end_verbatim
!end_quote
# ========================================================================
!subnode ES_INIT
!raw [stg] @xref SE_OK
Ein Editor fragt an, ob eine Shell das SE-Protokoll versteht.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3]: Ein Bitset, welche Shellnachrichten verstanden werden:
!begin_verbatim
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
!end_verbatim
!item [Wort 4+5]: Ein Bitset, welche Editorkommandos versendet werden:
!begin_verbatim
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
!end_verbatim
(!B)Hinweis:(!b) 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.
!item [Wort 6]: Unterstützte Versionsnummer des Protokolls als BCD-Zahl,
also 0x0105 (hexadezimal) für Version 1.05
!end_xlist
!smallskip
(!U)Antwort(!u)
Als Antwort erhält der Editor (!V)SE_OK(!v) von der Shell.
# ========================================================================
!subnode ES_OK
!raw [stg] @xref SE_INIT
Der Editor beantwortet die Anfrage der Shell nach dem Protokoll.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3]: Ein Bitset, welche Shellnachrichten verstanden werden:
!begin_verbatim
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
!end_verbatim
!item [Wort 4+5]: Ein Bitset, welche Editorkommandos versendet werden:
!begin_verbatim
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
!end_verbatim
(!B)Hinweis:(!b) 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.
!item [Wort 6]: Unterstützte Versionsnummer des Protokolls als BCD-Zahl,
also 0x0105 (hexadezimal) für Version 1.05
!item [Wort 7]: Die ApId des Programmes, dessen Nachricht beantwortet wird
!end_xlist
!smallskip
(!U)Antwort(!u)
Keine. (!V)ES_OK(!v) ist bereits die Antwort des Editors auf die Nachricht
(!V)SE_INIT(!v).
# ========================================================================
!subnode ES_ACK
Der Editor bestätigt den Empfang des Kommandos.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3]: (!V)TRUE(!v)~: Kommando wird verstanden und ausgeführt, (!nl)
(!V)FALSE(!v): Das Kommando wird nicht verstanden
Ein (!V)ES_ACK(!v) mit (!V)TRUE(!v) sagt nichts darüber aus, ob das
Kommando erfolgreich ausgeführt wurde. Es sagt nur, da₧ der Editor das
Kommando versteht und ausführen wird!
!end_xlist
!smallskip
(!U)Antwort(!u)
Keine ((!V)ES_ACK(!v) ist bereits die Antwort auf eine Nachricht).
# ========================================================================
!subnode ES_COMPILE
!raw [stg] @xref SE_ACK
Der Editor sagt der Shell, da₧ sie ein File übersetzen soll. Ein Zeiger
auf den Dateinamen kann in der Nachricht übergeben werden.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Zeiger auf den Namen der zu compilierenden Datei
oder (!V)NULL(!v).
!end_xlist
!smallskip
(!U)Antwort(!u)
Diese Nachricht mu₧ mit SE_ACK bestätigt werden.
!smallskip
(!B)Hinweis:(!b) Den Namen der zu compilierenden Datei auf
(!V)NULL(!v) zu setzen, ist erst ab Protokollversion 1.03 vorgesehen.
Der Editor sollte daher vorher über!-prüfen, ob die Shell mindestens
Protokollversion 1.03 unter!-stützt.
# ========================================================================
!subnode ES_MAKE
!raw [stg] @xref SE_ACK
Der Editor sagt der Shell, da₧ sie ein Make ausführen soll. Ein Filename
kann in der Nachricht übergeben werden, mu₧ aber nicht gesetzt sein und
mu₧ von der Shell auch nicht beachtet werden!
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Zeiger auf den Namen des Makefiles (oder NULL)
!end_xlist
!smallskip
(!U)Antwort(!u)
Die Shell bestätigt mit SE_ACK.
# ========================================================================
!subnode ES_MAKEALL
!raw [stg] @xref SE_ACK
Der Editor sagt der Shell, da₧ ein komplettes ""Make All"" ausgeführt
wer!-den soll. Ein Filename für das Makefile kann (mu₧ aber nicht) in
der Nachricht übergeben werden.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Zeiger auf den Namen des Makefiles (oder NULL)
!end_xlist
!smallskip
(!U)Antwort(!u)
Die Shell bestätigt mit SE_ACK.
# ========================================================================
!subnode ES_LINK
!raw [stg] @xref SE_ACK
Der Editor sagt der Shell, da₧ das Programm gelinkt werden soll. Ein
Filename kann in der Nachricht übergeben werden, mu₧ aber nicht
un!-be!-dingt von der Shell beachtet werden!
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Zeiger auf den Namen der Source, die gelinkt werden
soll (oder NULL)
!end_xlist
!smallskip
(!U)Antwort(!u)
Die Shell bestätigt mit SE_ACK.
# ========================================================================
!subnode ES_EXEC
!raw [stg] @xref SE_ACK
Der Editor sagt der Shell, da₧ das Programm zu der Source ausgeführt
werden soll. Ein Filename kann übergeben werden, mu₧ von der Shell aber
nicht beachtet werden.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Zeiger auf den Namen des auszuführenden Files
(oder NULL).
Bei einer Sourcedatei ist diese ggf. noch zu
compilieren und/oder zu linken
!end_xlist
!smallskip
(!U)Antwort(!u)
Die Shell bestätigt mit SE_ACK.
# ========================================================================
!subnode ES_MAKEEXEC
!raw [stg] @xref SE_ACK
Die Shell soll ein Make ausführen und danach das Programm ausführen.
Ein Filename für das Makefile kann (mu₧ aber nicht) in der Nachricht
übergeben werden.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Zeiger auf den Namen des Makefiles (oder NULL)
!end_xlist
!smallskip
(!U)Antwort(!u)
Die Shell bestätigt mit SE_ACK.
# ========================================================================
!subnode ES_PROJECT
!raw [stg] @xref SE_ACK
Der Editor teilt der Shell mit, da₧ das Projekt geändert/gewechselt
wur!-de. Der Filename des Projektfiles wird als Parameter in der
Nach!-richt übergeben. Wird (!V)NULL(!v) ü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.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Zeiger auf den Namen des Projektfiles oder
(!V)NULL(!v)
!end_xlist
!smallskip
(!U)Antwort(!u)
Die Shell bestätigt mit SE_ACK.
!smallskip
(!B)Hinweis:(!b) Den Namen des Projektfiles auf (!V)NULL(!v) zu
setzen, ist erst ab Protokollversion 1.01 vorgesehen. Der Editor
sollte daher vorher über!-prüfen, ob die Shell mindestens
Protokollversion 1.01 unter!-stützt.
# ========================================================================
!subnode ES_QUIT
Der Editor teilt der Shell mit, da₧ er jetzt beendet wird. Die Shell
sollte in dem Fall den Editor als Kommunikationspartner vergessen.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_description
!item [keine Parameter]
!end_description
!smallskip
(!U)Antwort(!u)
Es wird keine Antwort erwartet!
# ========================================================================
!subnode ES_SHLCTRL
Nachricht des Editors zur Kontrolle der Shell.
!smallskip
(!U)Aufbau der Nachricht(!u)
!begin_xlist [Wort 4+5:~]
!item [Wort 3+4]: Zeiger auf den Namen des obersten Fensters des
Editors oder (!V)NULL(!v)
!item [Wort 5]: Steuer-Flags: (!nl)
Bit 0: Shell soll sich toppen (Menü/Fenster)
!end_xlist
!smallskip
(!U)Antwort(!u)
Die Shell bestätigt mit SE_ACK.
!smallskip
(!B)Hinweis:(!b) Diese Nachricht existiert erst ab Protokollversion
1.05. Die übrigen Bits von Wort 5 sind für zukünftige Erweiterungen
reserviert.
# ########################################################################
!node History
(!B)Version 1.05(!b) vom 23.12.1997
!begin_itemize
!item neue Nachricht (!V)ES_SHLCTRL(!v)
!item neuer Eintrag (!V)shellCtrlStr(!v) in der Struktur
(!V)SEMENUINFO(!v) bei (!V)SE_MENU(!v)
!end_itemize
!smallskip
(!B)Version 1.04(!b) vom 08.01.1997
!begin_itemize
!item Flag 2 (""nur schlie₧en"") bei (!V)SE_CLOSE(!v)
!item neuer Eintrag (!V)progName(!v) in der Struktur
(!V)SEMENUINFO(!v) bei (!V)SE_MENU(!v)
!end_itemize
!smallskip
(!B)Version 1.03(!b) vom 19.11.1996
!begin_itemize
!item bei (!V)ES_COMPILE(!v) kann der Zeiger auf den Dateinamen jetzt
auch (!V)NULL(!v) sein.
!end_itemize
!smallskip
(!B)Version 1.02(!b) vom 13.08.1996
!begin_itemize
!item neue Nachricht (!V)SE_MENU(!v)
!item bei (!V)SE_OPEN(!v) kann nun auch eine Zeile und eine Spalte
angegeben werden
!end_itemize
!smallskip
(!B)Version 1.01(!b) vom 30.01.1996
!begin_itemize
!item Angabe von Dateimasken und Close-Flag bei (!V)SE_CLOSE(!v)
!item Projektname bei (!V)SE_PROJECT(!v) und (!V)ES_PROJECT(!v) kann
auch (!V)NULL(!v) sein
!end_itemize
!smallskip
(!B)Version 1.00(!b) vom 17.01.1994
!begin_itemize
!item erste öffentliche Version
!end_itemize
# ########################################################################
!node Autoren und Programme
Das SE-Protokoll wurde von Dirk Steins @ K2 und Frank Storm @ AC2
ent!-wickelt, die Erweiterungen zu den neueren Protokollversionen
stammen von Christian Felsch @ HH und Dirk Haun @ WI2.
Die Zahl der Programme, die das SE-Protokoll unterstützen, ist leider
noch nicht allzu gro₧:
!begin_itemize
!item Editoren:
!begin_itemize
!item Everest von Oliver Schmidt (ab Version 3.5)
!item Fred von Dirk Steins
!item qed von Christian Felsch (ab Version 3.3, ab Version 3.70
wird zudem Protokollversion 1.01 unterstützt)
!end_itemize
!item Shells:
!begin_itemize
!item Chatwin von Dirk Haun (ab Version 3.04 wird das SE-Protokoll
komplett unterstützt, ältere Versionen unterstützen nur die
wichtigsten Nachrichten)
!item Shell zum Megamax Modula-2 von Thomas Tempelmann
!item PC-Shell von Frank Schramm (ab Version 3.01)
!end_itemize
!item Sonstiges:
!begin_itemize
!item SE-Lib von Manfred Rosenboom und Dirk Haun
Dieser Bibliothek liegt auch der SE-Evaluator, eine Art
Debugger für das SE-Protokoll, bei.
!end_itemize
!end_itemize
Es bleibt zu hoffen, da₧ weitere Editoren und Shells dieses nützliche
Protokoll unterstützen werden. Dieser Text trägt dabei hoffentlich
et!-was zur Verbreitung bei !..
!smallskip
Dirk Haun, (!today)
!end_document