EXOS 2.1 Editor Driver Specification

5. Reading From the Editor

When the editor receives a read character function call, it examines the EXOS variable FLG_EDIT. This byte contains a series of flags which control the response of the editor to this read character function call. The editor's action will first be described in general terms without reference to the individual flags. The effect of each flag will then be described in detail.

5.1 Basic Editor Read Action

Assuming for now a typical setting of the flags in FLG_EDIT, when the editor receives a read character function call it interprets this as a request to send a line of text back to the applications program. It does not return a character immediately but records the state of the flags and enters its main editing loop which provides the actual editing facility to the user. It is only while in this loop that the cursor on the video page will flash. A flashing cursor thus indicates that the editor is waiting for a key to be pressed.

This loop reads a character from the keyboard, responds to it and then loops back for another one. This allows the user to type in text which will be inserted into the editor's text buffer and displayed on the video page, and to carry out various editing functions. The details of the editing functions are given later. There are two keys which are of importance here - Escape and Enter.

If Escape (ASCII code 01Bh) is received from the keyboard then this character will immediately be returned to the applications program as the response to the read character call, regardless of the state of any of the FLG_EDIT flags. This provides a way of interrupting a line input operation.

If Enter (ASCII code 0Dh) is pressed then this is a command to the editor to begin sending text back to the applications program. The details of how much text is sent are determined by the flags and will be described below. An internal editor flag is set to indicate that it is in the process of sending text, and the first character is returned to the applications program. When the applications program makes another read character call the internal flag is still set, so instead of entering the editing loop, it simply returns the next character of the requested text immediately. This continues until all the required text has been sent at which time the internal flag is cleared so the next read character call will again enter the editing loop.

It is up to the applications program to recognize when it has read all the characters to avoid re­starting a new read operation. How to recognize this depends on the setting of the editor flags and is described later.

Note that the editor flags are sampled once when the first read character call is made and then not again until all the text has been sent. Changing them in the meantime will therefore have no effect on the read which is in progress. If a write character call is made while a read is in progress then the internal flag is cleared so that the read will be aborted. This also applies if any special function calls are made.

5.2 The Editor Read Flags in Detail

The assignment of bits in the FLG_EDIT EXOS variable is:

bit­7 - SEND NOW
bit­6 - SEND ALL
bit­5 - NO READ
bit­4 - NO SOFT
bit­3 - NO PROMPT
bit­2 - AUTO ERA
bit­1 - not used
bit­0 - not used

5.2.1 The SEND NOW Flag (bit­7)

If this flag is set then the editor will start returning text immediately, without reading from the keyboard at all. If it is clear then the main editing loop will be entered and no text will be returned until the user types Enter. In either case the amount of text returned is the same and depends on the setting of the other flags.

5.2.2 The SEND ALL Flag (bit­6)

This is the main flag which determines how much text is sent. If it is clear then the paragraph containing the cursor will be sent. If it is set then the whole editor buffer will be sent.

In the first case the applications program will be sent the characters of the paragraph one by one terminated with a CR and then an LF. This CR-LF can be used by the applications program to determine when to stop reading (beware if NO SOFT is clear! - see below). The cursor will be left on the first character of the next paragraph with a new (empty) paragraph being created if that was the last one.

If SEND ALL is set then the entire buffer will be sent. This will include CR-LF sequences at least between each paragraph (again see NO SOFT flag below) so this cannot be used to indicate the end of the text. Instead, after the last CR-LF has been sent (the last characters sent will always be CR-LF), the next character read will produce a .EOF (end of file) error. This error will only be received for one character so the applications program must notice it and stop reading. If another character was to be read the this would start the whole reading process again from the start of the buffer.

5.2.3 The NO READ Flag (bit­5)

If this flag is set then Enter will not in fact return any characters at all to the applications program. The only way to get back to the applications program is thus to press Escape. Although no characters are returned, the routine which selects which characters to send depending on the flags, is still executed. Thus the cursor is moved in the same way as if the text was returned. If SEND ALL is clear then pressing Enter will just move to the start of the next paragraph, putting in a new line if it was at the end of the buffer. This will make the editor behave rather like a typewriter.

5.2.4 The NO SOFT Flag (bit­4)

This flag controls the sending of soft carriage returns and soft spaces. Soft carriage returns are those which separate successive lines of a paragraph. Soft spaces are those spaces which are inserted for justification, and also the spaces before the left margin of a line.

If this flag is clear the soft spaces are returned as normal ASCII spaces (20h) and soft carriage returns are returned as normal CR-LF sequences. If the flag is set the both of these are suppressed and no characters are returned for them.

Beware that if NO SOFT and SEND ALL are both clear then there is no way for the applications program wether a CR-LF which it receives is the end of the paragraph, in which case it should stop reading, or simply the separator between two lines of the paragraph, in which case it should continue. Therefore this combination of flags should be avoided - at least one of them should always be set.

5.2.5 The NO PROMPT Flag (bit­3)

This flag is normally clear. If it is set then the cursor position when the read operation was started is remembered. When it comes to returning text, if the cursor has not been moved out of the original paragraph, or to before the remembered postition in the current paragraph, and if SEND ALL is clear, then the current paragraph will be sent back but starting from the character at the remembered cursor position rather than the start.

If the cursor has been moved out of these bounds then the whole paragraph will be returned as usual, or the whole editor buffer if SEND ALL is set

This feature is used by BASIC when doing an INPUT command. It prints the prompt and then does an editor read with this flag set. When the paragraph is sent to BASIC the prompt will not be returned, just the response to it.

5.2.6 The AUTO ERA Flag (bit­2)

This flag is also normally clear. If it is set then, if the very first character typed at the keyboard is a printing character (as opposed to an editing function or cursor movement) then the current line will be cleared before responding to the key. This is provided mainly for BASIC to allow commands such as RUN to be typed on top of an existing lines after editing a program. It may just conceivably be of some use to other applications programs.

5.3 Typical Flag Combinations

The use of these flags can be rather confusing so this section discuses some examples of their use from IS­BASIC and the built in word processor (WP). This covers most useful combinations and certainly shows the use of each of the flags.

5.3.1 BASIC reading a command line. Flags=000101xx

When BASIC is reading a command line from the editor it is expecting either an immediate mode command (such as RUN) or a new line starting with a line number to be typed. In either case it wants to read a single paragraph entered by the user. This might be newly typed by him or it might be a line which already exists in the editor buffer which he simply moves the cursor to and re­enters.

Clearly BASIC wants to wait for the user to type Enter so the SEND NOW flag is clear. Only one paragraph, rather than the whole buffer is wanted so SEND ALL is clear and BASIC wants to actually be sent the text so NO READ is clear. BASIC is not interested in the breaks between lines in the paragraph (since one command line can over flow onto several screen lines) so NO SOFT is set. NO PROMPT is clear and AUTO ERA is set (as explained above).

5.3.2 BASIC doing an input command. Flags=000110xx

When BASIC is doing an input command it also wants to read in a single paragraph so the SEND NOW, SEND ALL, NO READ and NO SOFT flags are all set the same as for reading a command. In this case however BASIC will write out a prompt and wants to read in just the response to that prompt, rather than having the prompt at the start of the paragraph which it receives, To do this it sets the NO PROMPT flag. The AUTO ERA flag is clear.

5.3.3 WP normal editing mode. Flags=001xx0xx

In normal editing mode the word processor wants to let the user get on with his editing without data being sent to the word processor. The SEND NOW flag is clear to allow the user to do editing. The SEND ALL is clear and the NO READ is set to ensure that no characters are returned to the word processor when Enter is pressed but the cursor will be moved to the start of the next paragraph. The NO SOFT and NO PROMPT flags are irrelevant when NO READ is set, and the AUTO ERA flag is clear.

This will have the effect of allowing the user to move all over his document, pressing Enter and using any of the editing features. Only when Escape is pressed will the word processor applications program be alerted. In fact the eight function keys have the ESC code as the first code in their programmed string so the word processor gets alerted when they are pressed as well.

5.3.4 WP Printing a document. Flags=11000xxx

When the word processor is asked to print a document it must read the wole of the editor's text buffer in order to print it. Also it wants to get the data immediately rather than waiting for the user to press Enter. To achieve this SEND NOW and SEND ALL are both set. NO READ is of course clear or no text would be sent and NO SOFT is clear so that all spaces and soft carriage returns will be sent to ensure that the formatting of the printed document is correct. NO PROMPT is clear. AUTO ERA does not matter because SEND NOW is set so the user doesn't get a chance to press a key.

Next Chapter: Editing Functions.

David Bouman. (dsbouma@cs.vu.nl)