Home ProtocolsProtocols OLGA protocolOLGA protocol System Services Protocol (SSP)System Services Protocol (SSP)

15.9 SE protocol

The purpose of the SE protocol is the communication between program development shells and editors, hence the name: Shell-Editor protocol.

This protocol serves, under multitasking systems, to cause the shell to perform compilation and similar actions from within the editor, and to return shell error-messages and/or error files to the editor.

Commands or messages from the shell to the editor start with SE_, messages from the editor to the shell start with ES_.

The current version number of the protocol is 1.05.


15.9.1 Contact initiation

Initiating contact proceeds as follows:

After startup, the shell sends the message SE_INIT. As a reply it will then receive the message ES_OK. From the bit-fields of both messages the shell can now deduce which commands it can send to the editor and which commands are to be expected from the editor. If the shell no longer wishes to participate in the SE protocol (for instance because it is being terminated) then it will send the message SE_QUIT to the editor.

After launching, the editor sends the message ES_INIT. As a reply it will then receive the message SE_OK. From the bit-fields of both messages the editor can now deduce which commands it can send to the shell and which commands are to be expected from the shell. If the editor no longer wishes to participate in the SE protocol (for instance because it is being terminated) then it will send the message ES_QUIT to the editor.

The remaining question is to whom the shell and editor should send these messages. The SE protocol is best suited for use under a multitasking system, in which the AES function appl_search will normally be available. So the shell and editor should simply send their respective init message to all processes (except the system processes).

Other possibilities:

15.9.2 Notes on SE protocol

When we talk of a 'message' in the following, then this means an AES message that consists of 8 WORDs (integers) and is sent with the AES function appl_write. The first WORD always contains the number of the message, the second the application ID of the sender and the third is always NULL. The allocation of the other WORDs depends on the particular message in each case. WORDs for which no allocation is specified are to be set to NULL.

Please note: As the count starts from 0, then 'WORD 3' in the following means the fourth WORD!

For clarification, once again in C:

 int msg[8];

 msg[0] = SE_ACK;   /* Message                          */
 msg[1] = gl_apid;  /* ID of the sender                 */
 msg[2] = 0;        /* 0, i.e. no excess length         */
 msg[3] = TRUE;     /* This is "WORD 3"                 */
 msg[4] = msg[5] = msg[6] = msg[7] = 0; /* Rest to NULL */
 appl_write (editor, 16, msg);          /* Send         */

If a pointer (i.e. an address) is contained in a message, then the upper WORD of the address is passed in the first and the lower WORD in the second of the specified WORDs.

With pointers to memory areas, each sender of the message must ensure that these memory areas can also be read by the receiver (memory protection!). For this they have to be allocated as 'readable'! This is achieved via the Gemdos call Mxalloc.

With some messages it is possible to pass line and column numbers for the cursor position. As there are different opinions whether lines and/or columns should be counted starting from zero or from one, it is recommended that these statements should be checked before adoption and corrected if necessary. So if the editor starts counting its lines from one then a line number of zero should not upset it and it should be handled as line one.


15.9.3 Messages from the shell to the editor

The shell can send the following messages or commands to the editor:

Message Number
SE_INIT 0x4200
SE_OK 0x4201
SE_ACK 0x4202
SE_OPEN 0x4203
SE_ERROR 0x4204
SE_ERRFILE 0x4205
SE_PROJECT 0x4206
SE_QUIT 0x4207
SE_TERMINATE 0x4208
SE_CLOSE 0x4209
SE_MENU 0x420A

15.9.3.1 SE_INIT

The shell asks whether an editor understands the SE protocol.


Make-up of the message:

Word 3: A bitset specifying which messages the shell sends:
 

Message Bit Hex value
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
Word 4+5: A bitset specifying which editor commands are understood:
 

Message Bit Hex value
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

Note: WORD 4 and 5 together form a LONGword. Since the messages defined to date only require 12 bits, WORD 4 will normally be NULL.
 
Word 6: Supported version number of the protocol as BCD number, thus 0x0105 (hexadecimal) for Version 1.05
 

Reply:

The editor replies with the message ES_OK.


See also: ES_OK   SE_QUIT

15.9.3.2 SE_OK

The shell tells the editor that it understands the protocol.


Make-up of the message:

Word 3: A bitset specifying which messages the shell sends:
 

Message Bit Hex value
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
Word 4+5: A bitset specifying which editor commands are understood:
 

Message Bit Hex value
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

Note: WORD 4 and 5 together form a LONGword. Since the messages defined to date only require 12 bits, WORD 4 will normally be NULL.
 
Word 6: Supported version number of the protocol as BCD number, thus 0x0105 (hexadecimal) for version 1.05
 
Word 7: The apID of the program whose message is being answered
 

Reply:

None (SE_OK is already the reply of the shell to the message ES_INIT).

15.9.3.3 SE_ACK

The shell confirms the receipt of the editor command and returns whether the command is executed.


Make-up of the message:

Word 3: TRUE : Command is understood and will be executed
FALSE: The command is not understood
 
A SE_ACK with TRUE says nothing about whether the command was executed successfully. It only says that the shell understands the command and will execute it!
 

Reply:

None (SE_ACK is already the reply to a message).

15.9.3.4 SE_OPEN

The shell tells the editor that it is to open a text.


Make-up of the message:

Word 3+4: A pointer to the filename of the file to be opened
 
Word 5+6: Line at which the cursor is to be positioned
 
Word 7: Column at which the cursor is to be positioned
 

Reply:

As a reply the shell receives an ES_ACK.


Note: The specification of line and column numbers is only provided for from protocol Version 1.02 onwards. Programs that still use older protocol versions should really have set the WORDs 5..7 to NULL. If one wants to be quite certain, then it may be necessary to enquire the version number of the shell passed by SE_INIT or SE_OK.

If the shell can't or doesn't want to make any position specification, it should set the line and column to zero.

15.9.3.5 SE_ERROR

An error has arisen during compilation.


Make-up of the message:

Word 3+4: A pointer to an info structrure that is built up as follows:
 
    typedef struct
    {
      char *errFile; /* Pointer to the name of the compiled file   */
      char *errMess; /* Pointer to the error-message               */
      int errNum;    /* The error number                           */
      long errLine;  /* The erroneous line                         */
      int errRow;    /* The column with the error (or 0)           */
    } ERRINFO;

Reply:

The editor confirms the message with ES_ACK.


Note: If the shell can't or doesn't want to make any position specification, it should set the line and column to zero.

15.9.3.6 SE_ERRFILE

Errors have occurred. The error-messages are contained in an error file which is specified in the message.


Make-up of the message:

Word 3+4: A pointer to the filename of the error file with the error-messages
 
Word 5+6: A pointer to the name of the compiled text
 

Reply:

The editor confirms the message with ES_ACK.

15.9.3.7 SE_PROJECT

The shell tells the editor that the project has been altered. The filename of the current project file will be passed as a parameter. If NULL is passed, the current project should be logged off.

A sensible reaction of the editor in this case would be to also change the project, insofar as it supports this.


Make-up of the message:

Word 3+4: A pointer to the name of the project file, or NULL.
 

Reply:

The editor acknowledges with ES_ACK.


Note: Setting the name of the project file to NULL is available only from protocol Version 1.01 onwards. The shell should therefore check beforehand whether the editor understands protocol Version 1.01 or higher.

15.9.3.8 SE_QUIT

The shell tells the editor that is is being terminated. The editor in this case should forget the shell as a communications partner.


Make-up of the message:

No parameters


 


Reply:

No reply is expected!

15.9.3.9 SE_TERMINATE

The shell tells the editor that it should terminate itself. The editor should terminate itself in this case and run through its normal termination process (and during this also send an ES_QUIT). The reason for such a message from the shell could be insufficient memory for compilation, for instance.


Make-up of the message:

No parameters


 


Reply:

The editor confirms the message with ES_ACK.

15.9.3.10 SE_CLOSE

The shell tells the editor that it is to save or close given texts. When closing altered texts the editor should first issue a confirmation query.


Make-up of the message:

Word 3+4: A pointer to the name of a file, or a file mask. '*.*' represents all text windows (so corresponds to the SE_CLOSE of the protocol Version 1.00).
 
Word 5: 0 = Save only
1 = Save and close
2 = Close without saving (from version 1.04 on)
 

Reply:

The editor confirms the message with ES_ACK.


Note: In the protocol Version 1.00 no provision was made for parameters for SE_CLOSE. Editors that only support Version 1.00 will therefore ingnore the file masks and the flag and save all texts.

15.9.3.11 SE_MENU

The shell tells the editor what it should enter for individual programs in its menu. This way the editor can use the same texts as the shell for those menu entries that trigger an action in the shell.


Make-up of the message:

Word 3+4: A pointer to an info structure, which is built up as follows:
 
  typedef struct
  {
    char *compStr;      /* Text for the menu entry "Compiler"       */
    char *makeStr;      /* Text for the menu entry "Makefile"       */
    char *makeAllStr;   /* Text for the menu entry "Make all"       */
    char *linkStr;      /* Text for the menu entry "Linker"         */
    char *execStr;      /* Text for the menu entry "Execute"        */
    char *makeExecStr;  /* Text for the menu entry "Make & Execute" */
    char *progName;     /* Name of the shell (from version 1.04 on) */
    char *shellCtrlStr; /* Text for the menu entry "Shell Control"  */
                        /* (from version 1.05 on)                   */
  } SEMENUINFO;

Reply:

The editor confirms the message with ES_ACK.


Note: The texts are all optional and can also be NULL if the shell has no corresponding menu entry. This does not mean, however, that the shell does not offer this functionality. Therefore the editor should insert defaults for all texts if necessary.

This message exists only from protocol Version 1.02 onwards. But a test if the corresponding bit in ES_INIT or ES_OK is set is sufficient.

When accessing progName and shellCtrlStr one has to ensure that the communications partner also supports these already (test the protocol version)!

15.9.4 Messages from the editor to the shell

The editor can send the following messages or commands to the shell:

Message Number
ES_INIT 0x4240
ES_OK 0x4241
ES_ACK 0x4242
ES_COMPILE 0x4243
ES_MAKE 0x4244
ES_MAKEALL 0x4245
ES_LINK 0x4246
ES_EXEC 0x4247
ES_MAKEEXEC 0x4248
ES_PROJECT 0x4249
ES_QUIT 0x424A
ES_SHLCTRL 0x424B

15.9.4.1 ES_INIT

The editor asks whether a shell understands the SE protocol.


Make-up of the message:

Word 3: A bitset specifying which shell messages are understood:
 

Message Bit Hex value
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
Word 4+5: A bitset specifying which editor commands are sent:
 

Message Bit Hex value
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

Note: WORD 4 and 5 together form a LONGword. Since the messages defined to date only require 12 bits, WORD 4 will normally be NULL.
 
Word 6: Supported version number of the protocol as BCD number, thus 0x0105 (hexadecimal) for Version 1.05
 

Reply:

As a reply the editor receives SE_OK from the shell.

15.9.4.2 ES_OK

The editor replies to the query from the shell about the protocol.


Make-up of the message:

Word 3: A bitset specifying which shell messages are understood:
 

Message Bit Hex value
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
Word 4+5: A bitset specifying which editor commands are sent:
 

Message Bit Hex value
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

Note: WORD 4 and 5 together form a LONGword. Since the messages defined to date only require 12 bits, WORD 4 will normally be NULL.
 
Word 6: Supported version number of the protocol as BCD number, thus 0x0105 (hexadecimal) for Version 1.05
 
Word 7: The apID of the program whose message is replied to
 

Reply:

None (ES_OK is already the reply of the editor to the message SE_INIT).

15.9.4.3 ES_ACK

The editor confirms the receipt of the command.


Make-up of the message:

Word 3: TRUE : Command will be understood and executed
FALSE: The command is not understood
 
An ES_ACK with TRUE says nothing about whether the command was executed successfully. It only says that the editor understands the command and will execute it!
 

Reply:

None (ES_ACK is already a reply to a message).

15.9.4.4 ES_COMPILE

The editor tells the shell that it should translate a file. A pointer to the filename can be passed in the message.


Make-up of the message:

Word 3+4: Pointer to the name of the file to be compiled, or NULL.
 

Reply:

This message must be confirmed with SE_ACK.


Note: Provision for setting the name of the file to be compiled to NULL is available only in protocol versions from 1.03 on. The editor should therefore check beforehand that the shell supports at least protocol Version 1.03.

15.9.4.5 ES_MAKE

The editor tells the shell that it should perform a 'make'. A filename can be passed in the message, but does not have to be set and also does not have to be paid regard to by the shell!


Make-up of the message:

Word 3+4: Pointer to the mame of the makefile, or NULL
 

Reply:

The shell confirms the message with SE_ACK.

15.9.4.6 ES_MAKEALL

The editor tells the shell that a complete 'make all' is to be performed. A filename for the makefile can (but does not have to) be passed in the message.


Make-up of the message:

Word 3+4: Pointer to the name of the makefile or NULL
 

Reply:

The shell confirms the message with SE_ACK.

15.9.4.7 ES_LINK

The editor tells the shell that a program is to be linked. A filename can be passed in the message, but does not necessarily have to be paid regard to by the shell!


Make-up of the message:

Word 3+4: Pointer to the name of the source that is to be linked or NULL
 

Reply:

The shell confirms the message with SE_ACK.

15.9.4.8 ES_EXEC

The editor tells the shell that the program for the source is to be executed. A filename can be passed, but does not have to be paid regard to by the shell.


Make-up of the message:

Word 3+4: Pointer to the name of the file to be executed or NULL
 
For a source file it may be necessay to compile and/or link it first
 

Reply:

The shell confirms the message with SE_ACK.

15.9.4.9 ES_MAKEEXEC

The shell should perform a 'make' and execute the program afterwards. A filename for the makefile can (but does not have to be) passed in the message.


Make-up of the message:

Word 3+4: Pointer to the name of the makefile or NULL
 

Reply:

The shell confirms the message with SE_ACK.

15.9.4.10 ES_PROJECT

The editor tells the shell that the project has been altered/changed. The filename of the project file will be passed as a parameter in the message. If NULL is passed, then the current project should be logged off.

A sensible reaction of the shell in this case would be to also change the project, as long as it supports this.


Make-up of the message:

Word 3+4: Pointer to the name of the projectfile or NULL
 

Reply:

The shell confirms the message with SE_ACK.


Note: Provision for setting the name of the projectfile to NULL is only available in protocol versions from 1.01 on. The editor should therefore check beforehand that the shell supports at least protocol Version 1.01.

15.9.4.11 ES_QUIT

The editor tells the shell that it is now being terminated. The shell should forget about the editor as a communications partner in that case.


Make-up of the message:

No parameters


 


Reply:

No reply is expected!

15.9.4.12 ES_SHLCTRL

Message of the editor for controlling the shell.


Make-up of the message:

Word 3+4: Pointer to the name of the topped window of the editor or NULL
 
Word 5: Control flags:
Bit 0: Shell should top itself (Menu/Window)
 

Reply:

The shell confirms the message with SE_ACK.


Note: This message exists only from protocol Version 1.05 onwards. The remaining bits of WORD 5 are reserved for future extensions.

15.9.5 History, SE protocol

Version 1.05 of 23.12.1997


Version 1.04 of 08.01.1997


Version 1.03 of 19.11.1996


Version 1.02 of 13.08.1996


Version 1.01 of 30.01.1996


Version 1.00 of 17.01.1994

15.9.6 Authors and programs

The SE protocol was developed by Dirk Steins and Frank Storm, while the extensions to the newer protocol versions originate from Christian Felsch and Dirk Haun.

The number of programs that support the SE protocol is unfortunately not very large as yet:

It is to be hoped that further editors and shells will support this useful protocol in the future. We hope that this text will help its wider distribution and adoption.


Dirk Haun, 23.12.1997
English version: Peter West, DDP Translations


Home ProtocolsProtocols OLGA protocolOLGA protocol System Services Protocol (SSP)System Services Protocol (SSP)