Protocols

OLGA protocol

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
• 15.9.2 Notes on SE protocol
• 15.9.3 Messages from the shell to the editor
• 15.9.4 Messages from the editor to the shell
• 15.9.5 History, SE protocol
• 15.9.6 Authors and programs

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:

• If the shell knows the name of the editor, it can, of course, restrict itself to this and send SE_INIT only to it.
   

• If the function appl_search is not available, then the XAcc protocol provides an alternative for initiating contact: Shell and editor should simply send their init messages to every process that registers itself via XAcc. The XAcc protocol also provides for a machine-readable identification of the program type (XDSC), so that one may be able to recognize whether the communication partner one is dealing with is a shell (ID `PE' for "Programming Environment") or whether it is an editor (ID `ED' for "text EDitor").
   

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:

15.9.3.1 SE_INIT

The shell asks whether an editor understands the SE protocol.

Make-up of the message:

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:

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:

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:

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:

    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:

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:

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:

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:

  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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

• New message ES_SHLCTRL
   

• New entry shellCtrlStr in the structure SEMENUINFO for SE_MENU
   

Version 1.04 of 08.01.1997

• Flag 2 (Close only) for SE_CLOSE
   

• New entry progName in the structure SEMENUINFO for SE_MENU
   

Version 1.03 of 19.11.1996

• For ES_COMPILE the pointer to the filename may now also be NULL
   

Version 1.02 of 13.08.1996

• New message SE_MENU
   

• For SE_OPEN one can now also specify a line and a column
   

Version 1.01 of 30.01.1996

• Specification of file-masks and Close flag for SE_CLOSE
   

• Project name for SE_PROJECT and ES_PROJECT can now also be NULL
   

Version 1.00 of 17.01.1994

• First published version
   

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:

• Editors:
   

  • Clix by Steffen Engels
     

  • Everest by Oliver Schmidt (from version 3.5 on)
     

  • Fred by Dirk Steins
     

  • qed by Christian Felsch (from version 3.3 on, in addition from version 3.70 the protocol version 1.01 is supported as well)
     

• Shells:
   

  • Chatwin by Dirk Haun (from version 3.04 the SE protocol is supported completely, older versios support only the most important messages)
     

  • Shell for Megamax Modula-2 by Thomas Tempelmann and Dirk Steins
     

  • PC-Shell by Frank Schramm (from version 3.01 on)
     

• Miscellaneous:
   

  • SE-Lib by Manfred Rosenboom and Dirk Haun
     
    This library is accompanied also by SE-Evaluator, a kind of debugger for the SE protocol.
     

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

Protocols

OLGA protocol

System Services Protocol (SSP)