Digital Terminal Software Architecture Network Command Terminal Specification | | Version 1.4 Leland Webber George Conant Henry Lowe Chuck Jones | | 15 February 1984 Network Command Terminal Architectural Specification Page 2 1.0 INTRODUCTION . . . . . . . . . . . . . . . . . . . . 5 1.1 Relation To Digital's Network Architecture . . . . 5 1.2 Relation To Digital's Terminal Software Architecture . . . . . . . . . . . . . . . . . . . 5 1.3 Definition Of Character Set . . . . . . . . . . . 6 1.4 Requirements, Goals, And Non-Goals . . . . . . . . 6 2.0 NETWORK COMMAND TERMINAL OVERVIEW . . . . . . . . . 8 2.1 Host Terminal Interface . . . . . . . . . . . . 10 2.1.1 Writing Characters . . . . . . . . . . . . . . . 10 2.1.2 Reading Characters . . . . . . . . . . . . . . . 10 2.1.3 Out-of-band Input . . . . . . . . . . . . . . . 11 2.1.4 Writing Characteristics . . . . . . . . . . . . 11 2.1.5 Reading Characteristics . . . . . . . . . . . . 11 2.2 Server Terminal Interface . . . . . . . . . . . 11 2.2.1 Echoing . . . . . . . . . . . . . . . . . . . . 12 2.2.2 Type-ahead . . . . . . . . . . . . . . . . . . . 12 2.2.3 Input Editing . . . . . . . . . . . . . . . . . 12 2.2.4 Output Control . . . . . . . . . . . . . . . . . 12 2.2.5 Out-of-band Input . . . . . . . . . . . . . . . 12 2.2.6 Quoting . . . . . . . . . . . . . . . . . . . . 13 2.2.7 Output/Echo Synchronization . . . . . . . . . . 13 2.3 Multi-character Input Tokens . . . . . . . . . . 13 2.4 Escape Sequences . . . . . . . . . . . . . . . . 14 2.5 A Data Flow Model . . . . . . . . . . . . . . . 14 2.5.1 Pre-Input Process . . . . . . . . . . . . . . . 15 2.5.2 Input Process . . . . . . . . . . . . . . . . . 17 2.5.3 Input Process/Host Terminal Interface Interaction 18 2.5.4 Output Procedure . . . . . . . . . . . . . . . . 19 2.5.5 Output Process . . . . . . . . . . . . . . . . . 19 2.5.6 Synchronization . . . . . . . . . . . . . . . . 20 3.0 INTERFACES . . . . . . . . . . . . . . . . . . . . 21 3.1 Host Terminal Interface . . . . . . . . . . . . 21 3.1.1 Reading Normal Characters . . . . . . . . . . . 22 3.1.2 Reading Out-of-band Characters . . . . . . . . . 26 3.1.3 Writing Characters . . . . . . . . . . . . . . . 26 3.1.4 Control And Status Functions . . . . . . . . . . 28 3.1.5 Reading And Writing Characteristics . . . . . . 29 3.2 Server Terminal Interface . . . . . . . . . . . 30 3.2.1 Quoting . . . . . . . . . . . . . . . . . . . . 30 3.2.2 Output Control . . . . . . . . . . . . . . . . . 31 3.2.3 Input Editing . . . . . . . . . . . . . . . . . 31 3.2.3.1 Redisplay Input . . . . . . . . . . . . . . . . 31 3.2.3.2 Delete Character . . . . . . . . . . . . . . . . 32 3.2.3.3 Delete Word . . . . . . . . . . . . . . . . . . 32 3.2.3.4 Clear Input . . . . . . . . . . . . . . . . . . 32 3.2.3.5 Clear Type-ahead . . . . . . . . . . . . . . . . 33 3.3 Terminal Characteristics . . . . . . . . . . . . 33 3.4 Termination Set . . . . . . . . . . . . . . . . 37 4.0 OPERATION . . . . . . . . . . . . . . . . . . . . 38 4.1 Interfaces And Protocols . . . . . . . . . . . . 39 4.2 Host/Server Division Of Labor . . . . . . . . . 39 4.3 Data Channels . . . . . . . . . . . . . . . . . 39 4.4 Protocol Message Overview . . . . . . . . . . . 40 4.5 General Message Processing . . . . . . . . . . . 40 4.6 Protocol Errors . . . . . . . . . . . . . . . . 41 Network Command Terminal Architectural Specification Page 3 4.7 Initialization . . . . . . . . . . . . . . . . . 41 4.8 Characteristics Management . . . . . . . . . . . 42 4.9 Read Request Processing . . . . . . . . . . . . 42 4.9.1 Issuing The Read . . . . . . . . . . . . . . . . 42 4.9.2 Unreading . . . . . . . . . . . . . . . . . . . 43 4.9.3 Position Modeling . . . . . . . . . . . . . . . 43 4.9.4 Read Completion . . . . . . . . . . . . . . . . 43 4.9.5 Input Editing . . . . . . . . . . . . . . . . . 43 4.9.5.1 Distributed Input Editing . . . . . . . . . . . 44 4.9.5.2 Selecting Distributed Input Editing . . . . . . 45 4.10 Other Input Processing . . . . . . . . . . . . . 45 4.10.1 Input Escape Sequences . . . . . . . . . . . . . 45 4.10.2 Raising Input . . . . . . . . . . . . . . . . . 47 4.10.3 Out-of-Band Processing . . . . . . . . . . . . . 47 4.10.4 Control-V . . . . . . . . . . . . . . . . . . . 47 4.10.5 Control-X . . . . . . . . . . . . . . . . . . . 47 4.10.6 Control-O . . . . . . . . . . . . . . . . . . . 47 4.10.7 Errors On Input . . . . . . . . . . . . . . . . 48 4.11 Write Request Processing . . . . . . . . . . . . 48 4.12 Other Output Processing . . . . . . . . . . . . 49 4.12.1 Output Discard State Handling . . . . . . . . . 49 4.12.2 Locking . . . . . . . . . . . . . . . . . . . . 51 4.12.3 Output Escape Sequences . . . . . . . . . . . . 51 4.13 Additional Status And Control Operation . . . . 51 4.13.1 Reading And Writing Characteristics . . . . . . 52 4.13.2 Clearing Input . . . . . . . . . . . . . . . . . 52 4.13.3 Input Character Count Handling . . . . . . . . . 52 4.14 Foundation Services Interface Events . . . . . . 53 4.15 Protocol Evolution . . . . . . . . . . . . . . . 53 4.16 Network Command Terminal Protocol Messages . . . 54 4.16.1 General Message Format . . . . . . . . . . . . . 55 4.16.2 Initiate (H <--> S) . . . . . . . . . . . . . . 56 4.16.3 Start Read (H ---> S) . . . . . . . . . . . . . 58 4.16.4 Read Data (H <--- S) . . . . . . . . . . . . . . 62 4.16.5 Out-of-Band (H <--- S) . . . . . . . . . . . . . 63 4.16.6 Unread (H ---> S) . . . . . . . . . . . . . . . 64 4.16.7 Clear Input (H ---> S) . . . . . . . . . . . . . 64 4.16.8 Write (H ---> S) . . . . . . . . . . . . . . . . 64 4.16.9 Write Completion (H <--- S) . . . . . . . . . . 66 4.16.10 Discard State (H <--- S) . . . . . . . . . . . . 67 4.16.11 Read Characteristics (H ---> S) . . . . . . . . 67 4.16.12 Characteristics (H <--> S) . . . . . . . . . . . 68 4.16.13 Check Input (H ---> S) . . . . . . . . . . . . . 69 4.16.14 Input Count (H <--- S) . . . . . . . . . . . . . 69 4.16.15 Input State (H <--- S) . . . . . . . . . . . . . 69 4.16.16 Reserved for VMS -- see VMS Mini-Manual . . . . 69 4.16.17 Reserved for VMS -- see VMS Mini-Manual . . . . 70 4.16.18 Reserved for VMS -- see VMS Mini-Manual . . . . 70 4.17 Selector Values For Characteristics . . . . . . 70 4.17.1 Foundation-maintained Characteristics . . . . . 71 4.17.2 Handler-Maintained Characteristics . . . . . . . 72 4.17.2.1 CHARACTER-ATTRIBUTES Compound Characteristic . 73 Network Command Terminal Architectural Specification Page 4 APPENDIX A INPUT EDITING ALGORITHMS A.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . A-1 A.2 DEFINITION LANGUAGE . . . . . . . . . . . . . . . A-1 A.3 BASE FUNCTIONS . . . . . . . . . . . . . . . . . . A-2 A.4 DATA BASE VARIABLES . . . . . . . . . . . . . . . A-3 A.5 TRACKING HORIZONTAL DISPLAY POSITION . . . . . . . A-3 A.6 OTHER THINGS OF INTEREST . . . . . . . . . . . . . A-3 A.7 ALGORITHMS . . . . . . . . . . . . . . . . . . . . A-4 A.7.1 Routine ECHO (CHAR): Novalue = . . . . . . . . . A-4 A.7.2 Routine GOBACK (STYLE . . . . . . . . . . . . . A-5 A.7.3 Routine REDISPLAY_INPUT: Novalue = . . . . . . . A-6 A.7.3.1 routine INPUT_CHARACTER (CHAR): novalue = . . . A-6 A.7.4 Routine DELETE_CHAR: Novalue = . . . . . . . . . A-7 A.7.5 Routine DELETE_WORD: Novalue = . . . . . . . . A-10 A.7.6 Routine DELETE_INPUT: NOVALUE = . . . . . . . A-11 APPENDIX B ESCAPE SEQUENCE RECOGNITION ALGORITHM Network Command Terminal Architectural Specification Page 5 1.0 INTRODUCTION This specification describes a model for communication between terminal-handling subsystems and operating systems in a communications network. The integration of this communication with other aspects of terminal operation derives from the Digital Terminal Software Architecture. Systems in which this model could be implemented include, but are not necessarily limited to, intelligent terminals, host systems, front end systems, and terminal concentrators. It is the intent of this specification to define 1. first, the services (viz., interface funcitons or primitive operations) and semantics (but not the syntax) of the services provided by this model for terminal handling by Digital's Terminal Software Architecture, and 2. second, the communication protocol (both syntax and semantics) used by this model to provide the defined services. This document consists of four major sections: 1. A description of requirements and goals 2. A "black-box" model that identifies important interfaces 3. An interface description 4. A protocol model that defines messages and the operation of the modules that provide the interfaces on the one hand and send and receive the messages on the other 1.1 Relation To Digital's Network Architecture The remote command terminal architecture is a component of the network application layer of Digital's Network Architecture. 1.2 Relation To Digital's Terminal Software Architecture The remote command terminal architecture is a component of the mode layer of Digital's Terminal Software Architecture. Network Command Terminal Architectural Specification Page 6 1.3 Definition Of Character Set This specification is intended for use with the 8-bit coded character set defined in DEC Standard 169. The term "character" means an 8-bit value from this character set. This character set defines the names of characters referred to in this specification (e.g., BEL). 1.4 Requirements, Goals, And Non-Goals Requirements are those attributes that the model described below must have. The requirements of the remote command terminal architecture are: . LOGON -- A person using one of a variety of terminals can log on to any Digital system (specifically, RSTS/E, RSX-11M, IAS, TOPS-10, TOPS-20, or VMS), give operating system level commands to the system, receive system responses, and communicate with all programs that are run under the operating system provided that a path exists between the terminal and host consisting of communication links and DECnet systems. . STANDARDS -- This model adheres to any previously defined corporate terminal architecture standards. . MODULARITY -- Terminal functions that can be classified together (e.g., input line editing) are either handled completely by the model or handled completely outside of the model. . SIMPLICITY -- The implementation of this model in hosts, communications processors, terminal concentrators, and terminals is sufficiently simple both to be understood by a wide variety of Digital developers and support personnel and to be contained in a reasonable amount of memory. . REASONABLE PERFORMANCE -- The performance of products adhering to this model can be made sufficiently good that users (people and programs) find it acceptable. . EVOLUTION -- This model allows future modifications. . FLEXIBILITY -- This model allows implementors to trade performance for size. . TERMINAL SUPPORT -- The model will support all specific and generic terminal types defined by the Digital Terminal Software Architecture. "Goals" are those attributes that are desirable in the model described below. The goals of the remote command terminal architecture, listed in descending order of preference, are: Network Command Terminal Architectural Specification Page 7 . HUMAN ENGINEERING -- The model should be compatible with established concepts of ease of use at the terminal/user interface. . EXCELLENT PERFORMANCE -- The performance of an implementation adhering to the model should be considered consistent with the lower level communication service class, if any, which the implementation uses, particularly with respect to response time as seen by terminal users. . EXTERNAL STANDARDS COMPATIBILITY -- The model should not preclude host compatibility with existing external standards (e.g., ANSI escape sequences). . TERMINAL CHARACTERISTICS -- The model should support all terminal characteristics of all host systems as seen by both terminal users and programs, (implying that all existing programs will communicate with terminals accessed via implementations of this model). . NEW STANDARDS -- Where possible, similar functions seen by a terminal user (e.g., the echoing of "delete previous line") should be standardized across hosts and servers. The non-goals of the remote command terminal architecture are: . INVENTION -- The model should not include new terminal services, with specific reference to the following: - Forms Applications - Graphics Applications - Editor Applications The model may provide a set of terminal handler "primitives", which are essentially atomic functions, which may be used by the applications listed above, but it will not provide any explicit, sophisticated support for these applications. . ROGUE DEVICES -- The model should not provide support for "strange devices" (e.g. Cassette Drives, etc.) simply because such devices may be connected to a terminal interface. The model does not need to support any device which does not behave like a "normal" interactive terminal. In particular, support is not guaranteed for devices which do not support local flow control conventions (XON/XOFF for Digital terminals). Network Command Terminal Architectural Specification Page 8 2.0 NETWORK COMMAND TERMINAL OVERVIEW This section describes a model for distributed terminal handling. In this model, the terminal-handling functions historically provided by system terminal drivers are provided by a collection of terminal handling modules distributed among the systems of a network. There are two types of terminal handling modules: those residing in host systems and those residing in server systems. A host system runs an operating system that has resources such as application programs, compilers, and command language interpreters available to human terminal users. A server system is an intelligent system (in that it is capable of communicating with a host system via a protocol and capable of communicating with a human terminal user via a command language) to which one or more terminal devices (keyboards, printers, screens, etc.) are attached. Examples of a server system are: a PDP-11/23 operating as a dedicated terminal concentrator, a personal computer attached to a network, and a VMS system that allows a user to issue the SET HOST command to connect to a remote host. Figure 2-1 below depicts these concepts. Network Command Terminal Architectural Specification Page 9 +---------------------------+ | | | HOST SYSTEM | | | | +------+ +------+ | | | USER |...| USER | | | +------+ +------+ | | | | | | V V | | +------------------+ | | | OPERATING SYSTEM | | | +------------------+ | +------------------+ | | | | | | | (1) | | SERVER SYSTEM | | V | | | | +----------------------+- - - - - -+---------------+ | | | DISTRIBUTED COMMON TERMINAL HANDLER | | | +----------------------+- - - - - -+---------------+ | | | | | | | | | | (2) | +---------------------------+ | V | | +------------+ | | | FOUNDATION | | | | SERVICES | | +--+------------+--+ | | | | | | | | physical terminals Figure 2-1 Distributed Common Terminal Services Model In this figure, the module labeled Foundation Services is included for compatibility with the Foundation Services of the Digital Terminal Software Architecture. Briefly, this module is introduced to have a clean position for future incorporation of terminal-model-independent control functions (for example, cursor movement) and for logical to physical terminal mapping functions (these functions would allow a CRT user, for example, to create two logical terminals, log each one on to a separate host, and see the output from each host appear in a separate window on the screen). The complete functions of this module are described in the Digital Terminal Software Architecture Foundation Services Specification. For the present, the reader should assume that the Foundation Services module provides a one-to-one correspondence between a logical terminal and a physical terminal. Figure 2-1 presents a logical view of distributed terminal handling. The emphasis here is in viewing the host-resident and server-resident terminal-handling functions as creating a single, distributed terminal handler. It is this view of terminal handling that is described in more detail below. Network Command Terminal Architectural Specification Page 10 Figure 2-1 describes how each terminal attached to a given server may communicate with a given host. In a network, each such terminal may communicate with a different host, and a given host communicate simultaneously with terminals attached to multiple servers. Figure 2-1 and the model presented below concentrate on the communication of a single terminal with a single host. Multiple such communications may occur simultaneously in a network. In figure 2-1, two interfaces, labeled (1) and (2) are identified. These are key interfaces in that their definition captures the essence of the functions of the proposed distributed terminal handler. This specification does not require that these interfaces be implemented as descibed in any host or server system. However, their precise definition is viewed as the best way to develop the protocol description that is presented further below. 2.1 Host Terminal Interface This interface, labeled (1) in figure 2-1, is the interface that an operating system may use to communicate with a terminal. This interface is defined to allow the operating system to provide application programs with the same terminal access functions they have had historically via system-resident terminal handlers. Examples of functions that are available at the host terminal interface are: 2.1.1 Writing Characters - The operating system may send characters from an output buffer to the terminal. 2.1.2 Reading Characters - The operating system may provide a read buffer for receiving characters from the terminal. The handler will terminate the read on a "termination" condition. A termination condition may occur in a number of ways: when the read buffer is filled, when a termination character is entered (the operating system defines the active set of termination characters when it issues the read request), when the interarrival time of characters from the terminal exceeds a threshold, or by request of the operating system (via an "unread" function). The handler provides input buffer editing, echoing, and other input-related functions. Synchronization of input character echoing with output characters is also done within the handler. Network Command Terminal Architectural Specification Page 11 2.1.3 Out-of-band Input - The operating system may read out-of-band characters (e.g., control-C) that have been entered at the terminal. These characters are delivered to the operating system independently from the normal stream of input characters. The host specifies which characters are out-of-band characters and enables this function by writing characteristics. 2.1.4 Writing Characteristics - The operating system may set various terminal characteristics. Some of these characteristics have been mentioned above. Additional examples of characteristics are: . the "normal echo" flag - a Boolean variable that defines whether or not characters other than control characters are echoed . the "raise input" flag - a Boolean variable that defines whether or not an entered lower case character is raised to an upper case character before being processed in any other way There are several more characteristics. These are described in detail further below. 2.1.5 Reading Characteristics - The operating system may read any characteristic. 2.2 Server Terminal Interface This interface is labeled (2) in figure 2-1. The functions of this interface can be described at two levels. At the lowest level, it is the interface over which characters to and from a human terminal user pass. This interface level is described in detail in the Foundation Services specification. At a higher level are the functions perceived by the human using the terminal. Examples of the higher level functions that are available at the server terminal interface are: Network Command Terminal Architectural Specification Page 12 2.2.1 Echoing - This is the function of printing back out on the terminal any character that is input. A character is echoed when it satisfies the current read pending from the operating system. For purposes of echoing, input characters are either control characters (and DEL) or non-control characters. Non-control characters either echo as themselves or do not echo as specified by the NORMAL-ECHO characteristic. Control characters (and DEL) either do not echo, echo as themselves, or echo in a "standard way" as specified by the CHARACTER- ATTRIBUTES characteristic. Echoing in a "standard way" allows the operating system, for example, to have a echoed when a carriage return is entered. 2.2.2 Type-ahead - This is the function of internally queuing entered input characters for which there is no current pending read request from the operating system. 2.2.3 Input Editing - This includes the functions associated with the DELETE, control-U, and control-R input characters (viz., delete previous character, delete current input, and display current input). It also includes the functions associated with the VMS control-X character (delete type-ahead as well as current input) and the TOPS-20 control-W character (delete previous word). 2.2.4 Output Control - This is the function associated with the control-O input character (alternate keystrokes discard some amount of queued output and reenable output). This function also sets a characteristic that may be read by the operating system indicating if output discard operation is in effect. 2.2.5 Out-of-band Input - This is the function generally associated with the control-C, control-Y, and control-T input character (depending on the operating system). This function has two forms. In either form, an entered out-of-band character is placed in a separate out-of-band buffer that can be read by the operating system independently from normal input. In one form (normally used Network Command Terminal Architectural Specification Page 13 for control-C and control-Y), the entry of this character also clears any type ahead and terminates the current read, if any; in the other form it doesn't. 2.2.6 Quoting - This is a function that allows a terminal user to pass through a character as data that is otherwise defined as a control character (e.g., an input editing character, an output control character, or an out-of-band character). This function is associated with the control-V character. Its effect is to shield the following character in the input from stream from recognition as a control character. 2.2.7 Output/Echo Synchronization - This is the function of synchronizing output from the operating system with echoed output resulting from operating system read requests. The form that this synchronization takes is controlled by the host. In general, if an operating system requests a read, the characters from any previous output function will appear on the terminal before the first character echoed as a result of the read. However, write output can "break through" a read in progress under certain conditions. The resolution of the "collision" of input echoing and these types of output can be controlled by the operating system through the use of a LOCKING flag on WRITEs from the operating system. 2.3 Multi-character Input Tokens Certain sequences of input characters, called "tokens" below, are considered as groups. These are: (1) a quote character followed by any character and (2) an escape sequence. The characters which comprise a token will not be divided across two or more reads unless the first character of the token was the first character placed in an empty read buffer. This can not happen for quoted characters except for the incongruous case of one character reads. For the details of escape sequence handling, see below and the subsections on Input and Output Escape Sequence Handling in the OPERATION section. Network Command Terminal Architectural Specification Page 14 2.4 Escape Sequences Escape sequence recognition may be enabled or disabled. When enabled, escape sequences are recognized as a syntactic unit (token) and treated, wherever possible, as a unit. When enabled, on input they terminate reads, do not echo, and have precedence greater than that of enabled editing characters. On output, they are written to the Foundation Services transparently and cause the horizontal and vertical position modeling to be set back to the origin. The Network Command Terminal Module only performs escape sequence recognition; it does not parse escape sequences. For the convenience of implementors, an algorithm for escape sequence recognition is contained in Appendix B. A complete and definitive algorithm for escape sequence parsing may be found in the Video Systems Reference Manual, a DIGITAL internal document that is being prepared by the Terminals and Workstations group. 2.5 A Data Flow Model Figure 2-2 below depicts the distributed common terminal handler of figure 2-1 as if it were a single module in a single system, internally composed of three processes, a procedure, and four buffers. This version of the model emphasizes the flow of data between the operating system and the terminal. Network Command Terminal Architectural Specification Page 15 S H /--------\ +-----------+ +-------------+ E O | OUTPUT | | OUTPUT |---->| OUTPUT | R S -->| BUFFER |-->| PROCESS | | PROCEDURE |---------> V T | | | | +-->| | E \--------/ +-----------+ | +-------------+ R T | E | T R | E M +--------+ R I | M N | I A /--------\ +---------+ /--------\ +-----------+ N L | INPUT | | INPUT | | TYPE- | | PRE-INPUT | A <--| BUFFER |<--| PROCESS |<--| AHEAD |<--| PROCESS |<-- L I | | | | | BUFFER | +-| | N \--------/ +---------+ \--------/ | +-----------+ I T | N E | T R /-------------\ | E F | OUT-OF-BAND | | R A <--| BUFFER |<----------------------+ F C | | A E \-------------/ C E Figure 2-2 Refined Common Terminal Services Model The purpose of the model depicted in figure 2-2 and described below is to describe more fully how data moves between the operating system and the terminal. In this model, distributed operation is shown as the cooperation of multiple processes. The reader should assume that each process can run at its own speed, independently from every other process. 2.5.1 Pre-Input Process - This process reads characters from the server terminal interface. Each such character is examined to determine how it should be processed. The examination proceeds as follows. First, if the input character is defined as an out-of-band character (the operating system may define multiple such characters), the character is placed in the Out-of-band Buffer. The Out-of-band Buffer, as well as the remaining buffers, is really a queue in which the characters placed in it retain their order. There are three types of Out-of-band characters: 1. Hello -- a "hello" out-of-band character normally has no effect on the normal input data stream (as an option, however, a copy of a "hello" out-of-band character can be included in the Type-ahead Buffer as well as in the Network Command Terminal Architectural Specification Page 16 Out-of-Band Buffer). 2. Immediate clear -- An "immediate clear" out-of-band character clears the Type-ahead Buffer and terminates any pending read. Only control characters can be "clear" out-of-band characters. 3. Deferred clear -- A "deferred clear" out-of-band character, unlike the other out-of-band characters, consists of two consecutive, identical control characters treated as a unit. It clears the type-ahead buffer and terminates any pending read. Only one character is put into the Out-of-band Buffer. Out-of-band characters are read one at a time at the host-terminal interface. Normally, non-control out-of-band characters are not echoed -- if the option to include a copy of a "hello" out-of-band character as normal input is exercised, the copy (treated as a normal input character) may be echoed depending on whether that character would normally be echoed. Control out-of-band characters are echoed according to the CHARACTER-ATTRIBUTES characteristic. They are echoed immediately without regard to whether the Server is locked. Second, if control-X is enabled (control characters are enabled by the operating system via writing characteristics), and a control-X character is read, the Type-ahead Buffer is cleared, and, if a read is pending, the control-X is changed to a control-U and placed in the Type-ahead Buffer. Third, if the control-O function is enabled, and a control-O character is read, an "output-discard" state variable used by the Output Process is toggled. This state variable takes on "discard output" and "don't discard output" values. The value of this state variable affects the operation of the Output Process, as described below. The operating system may read the value of the state variable by reading its state. It may set the value to "don't discard output" whenever it issues a write request. Finally, if the input character is not one of the above, it is placed in the Type-ahead Buffer. Characters flagged with an error (i.e. line break, framing error, parity error, and receiver overrun) are either discarded or placed in the Type-ahead Buffer (together with the error) according to the value of the ERROR-PROCESSING characteristic. If the Pre-input Process cannot completely process a character because the Out-of-band Buffer or the Type-ahead Buffer is full or because the Output Procedure rejects the call to output (because it was rejected by the Foundation Services), the Pre-Input Process is modelled as looping until the character can be completely processed. During this time, the Pre-Input Network Command Terminal Architectural Specification Page 17 Process is not reading characters from the server terminal interface. This will cause data entered by the terminal user to be queued within the Foundation Services module and, possibly, within hardware. Eventually, input data will be lost if the Pre-input Process cannot make progress. (Notification of data loss to the terminal user is a function performed by the Foundation Services module and/or terminal hardware.) 2.5.2 Input Process - Where an Input Buffer is present (i.e., the host has a read request outstanding), this process reads characters from the Type-ahead Buffer and writes them to the Input Buffer. Each such character is examined to determine how it should be processed. The examination proceeds as follows. First, if escape sequence recognition is enabled and the character is part of an escape sequence, it is processed by the escape sequence state machine. If the character is the last character of an escape sequence, the read is terminated. The details of escape sequence processing are in the OPERATION section below. Second, if the character is an enabled input editing character, the input editing function is performed. The defined input editing functions are: . delete character (DEL) - this function causes the character at the end of the Input Buffer to be removed and "unechoed" . delete word (control-W) - this function causes the word at the end of the Input Buffer to be removed and "unechoed" . delete input (control-U) - this function causes the Input Buffer to be emptied and the prompt redisplayed on the next line. . redisplay input (control-R) - this function causes the entire Input Buffer plus the prompt (if any) to be re-echoed starting on the next line of the presentation device. Third, if the character is a termination character, the Input Process terminates the current read and returns the Input Buffer to the operating system (see below). The termination character is echoed if the operating system has enabled echoing for this termination character. Finally, if the character is a normal data character, it is placed in the Input Buffer and echoed. If the character fills the buffer, the current read request is terminated. Network Command Terminal Architectural Specification Page 18 In addition to the processing described above, the Input Process treats the following as termination conditions: 1. if no character appears in the Type-ahead Buffer for a continuous period of time (defined by the operating system), 2. if the Input Process receives an "unread" request from the operating system, 3. if the user enters an enabled DEL, control-W, control-U, or control-X character while the Input Buffer is empty (this termination condition is selected by the operating system independently for each read request), 4. an enabled vertical change on the presentation device occurs as the result of echoing a user entered character (this termination condition is selected by the operating system independently for each read request), or 5. an error (i.e. line break, framing error, parity error, or receiver overrun) is flagged on an input character from the user. See the OPERATIONS section below for details of the handling implied by these conditions. As in the case of the Pre-input Process, if the Input Process cannot completely process a character because the operating system has no active read request (see below) or because the Output Procedure rejects the call to output the echo, the Input Process is modelled as looping until the character can be completely processed. During this time, the Input Process is not reading characters from the Type-ahead Buffer. This will eventually cause the Pre-Input Process to stop processing data as described above. 2.5.3 Input Process/Host Terminal Interface Interaction - The description above refers to "returning the Input Buffer to the operating system". This can be visuallized as follows. When the terminal is first connected to the operating system, the Input Buffer in figure 2-2 is not really present. The operating system makes the Input Buffer "present" by issuing a read request at the host terminal interface, specifying the address of an Input Buffer. "Returning the Input Buffer to the operating system" is equivalent to marking the Input Buffer as "read complete". Such an Input Buffer is not really "present" in the handler thereafter. Network Command Terminal Architectural Specification Page 19 The read function invoked by the operating system is powerful. It allows the operating system to preload the Input Buffer (for prompts), to define a portion of the Input Buffer at the beginning to be not deletable by input editing functions (also for prompts), and to cause the buffer to be "echoed" from any position to the end (for TOPS-20 input recognition operation). The read function is defined in more detail below. 2.5.4 Output Procedure - The purpose of this procedure is to co-ordinate the output of characters to the Foundation Service from the Output Process and the Input Process (echoing). The Output Procedure is called by the Output Process to write output characters and by the Input Process to write echoed characters. The Output process defines the points in its stream of output characters at which it is willing to let echo characters be output. This is done via "lock" and "unlock" functions. "Lock" is a request to block the Input Process. "Unlock" is a request to unblock the Input Process. When output isn't locked, echo takes precedence. 2.5.5 Output Process - The purpose of this process is to handle the output-discard state and to send characters from the Output Buffer to the Output Procedure. The operation of this process proceeds as follows. As described above, there is a state variable that controls output data discarding. If the value of the state variable is "discard output", the Output Process discards data in the Output Buffer; otherwise, it calls the Output Procedure to write the data to the terminal. Data in the Output Buffer consist logically of characters and flags. There are "start-of-message" and "end-of-message" flags. These flags are set as a result of the host terminal interface write function, described in more detail below. A "start-of-message" flag may "lock" the Output Procedure so it accepts no characters for echoing from the Input Process. There are two "end-of-message" flags. One will "unlock" the Ouptut Procedure after the last character from the write has been processed. The other optionally causes a "redisplay" of the Input Buffer if the Output Procedure was just "unlocked". If the Output Process cannot completely process a character because the server terminal interface is not accepting characters (this could happen if the terminal user enters an Network Command Terminal Architectural Specification Page 20 XOFF character), the Output Process is modelled as looping until the character can be completely processed. During this time, the Output Buffer is not being emptied. This will eventually be observed at the host terminal interface as an inability to successfully issue the "write" function. 2.5.6 Synchronization - The description of two points of synchronization concludes this section. When the operating system has no outstanding read request, it may redefine the echo characteristics without a race condition for normal input characters. That is, this operation ensures that there is no ambiguity about how a given normal input character will be echoed. If the operating system has a read request outstanding while it changes the echo characteristics the echo translation for an input character is indeterminate. The above description of conflict resolution by the Output Procedure pertains to a conflict of echo data with output data. In that case, the echoing is a result of a read request given by the operating system BEFORE the write request that produced the output. In the case of the conflict of echo data with output data when the corresponding read request was made AFTER the write request, the distributed terminal handler always completes the output before echoing the input. This means that if an operating system issues a write, then a read, then a write, the output data from the first write request is guaranteed to be given to the terminal before the first echoed character from the read request. The output from the second write request "breaks through" the read request if the read is still active when the write arrives. If this happens, the optional locking of the Output Procedure described above determines whether or not echoes from the read can be intermingled with output from the write. The definition of output/echo synchronization given above means that a read request may be delayed arbitrarily long behind an output request (if, for example, the terminal user enters a XOFF with no succeeding XON for a long period of time) even in the case where the operating system has set the echo characteristics to "don"t echo" for the read. This means that input from and output to "full duplex" terminals does not occur simultaneously with complete independence. Network Command Terminal Architectural Specification Page 21 3.0 INTERFACES As stated above, there are two major interfaces to the Handler: the host terminal interface, which exists in a host, and the server terminal interface, which exists in a server. These are each described below. 3.1 Host Terminal Interface The host terminal interface functions described below are modeled as being provided by subroutines. Each subroutine description consists of a name followed by a list of arguments and return values enclosed in parentheses. The arguments appear first and are separated from the return values by a semicolon. Optional arguments are enclosed in brackets ([...]). The following conventions pertain to the interface description: 1. Each function in this interface includes a portal identifier which specifies the associated logical terminal. A portal identifier is defined in the Foundation Services Specification. 2. The term "buffer" refers to the combination of address and length information that identifies data and its location. 3. There are two types of interface functions: those that complete immediately (referred to below as atomic functions), and those that queue a request to perform a function at some point in the future (referred to below as queued requests). The latter functions require resources to queue the request and, so, have "insufficient resources" failure returns. If a queued request succeeds (i.e., the request is successfully queued), then the requested function will be performed sequentially with respect to all other queued requests. For example, a queued request to WRITE-CHARACTERISTICS is followed by a queued request to READ-CHARACTERISTICS, then the values returned from the read request will reflect the previous write request. The interface functions described below contain "polling" functions. A polling function obtains status about a previously queued request. An implementation would probably convey this kind of status through an event queuing mechanism rather than polling. The polling form was chosen here so that all information flowing between the requestor of a function and the provider of the function would be modeled in a single, consistent way. Network Command Terminal Architectural Specification Page 22 3.1.1 Reading Normal Characters - Some of the arguments for the following function are index values into the Input Buffer. These indices are 16-bit values. The maximum size of an Input Buffer is 2**16-1 bytes. READ (PORTAL-ID, BUFFER, END-OF-DATA, UNDERFLOW-HANDLING, NO-ECHO, NON-DEFAULT-TERMINATION-SET, CLEAR-TYPE-AHEAD-FLAG, FORMATTING-FLAG, TERMINATOR-ECHO-FLAG, [RAISE-INPUT], [RECOGNIZE-INPUT-ESCAPE-SEQUENCES] [DISABLE-CONTROL], [TIMEOUT,] [END-OF-PROMPT,] [START-OF-DISPLAY,] [LOW-WATER,] [TERMINATION-SET]; RETURN) -- queues a read request. - BUFFER is a buffer to receive input; the maximum size is 2**16-1 bytes. - END-OF-DATA is the character position after the end of existing data. The first character of new input data will go into this position. This pointer also marks the end of the display. - UNDERFLOW-HANDLING defines the action when an enabled DEL, control-W, or control-U character is entered for an empty Input Buffer. It is one of the following: . IGNORE - ignore such a character . NOTIFY - send a BEL character to the terminal . TERMINATE - treat it as a READ termination - NO-ECHO is a Boolean flag. If TRUE, this over-rides any echoing specified by the characteristics. - NON-DEFAULT-TERMINATION-SET is a Boolean flag. If FALSE, it causes the Server to use an universal default termination set for this READ; the default is all control characters except control-R, control-U, control-W, BS and HT. If TRUE, the Server uses either the termination set specified by this READ or, if no termination set is specified with this READ, the last termination set it received with a previous READ. - CLEAR-TYPE-AHEAD-FLAG is a Boolean flag. When it is true, the Type-ahead Buffer is cleared before the READ is processed. - FORMATTING-FLAG is a Boolean flag. If TRUE and the last character output was a CR, then output a LF (avoid overprinting); in addition, if the first character of the preloaded input would echo as a LF, ignore it (avoids accidental double spacing). If FALSE, no special action. - TERMINATOR-ECHO-FLAG is a Boolean flag. If TRUE, termination character echoed; if FALSE, it is not eched. - RAISE-INPUT is a Boolean flag. If TRUE, lower case alphabetic characters are converted to upper case for this read (overriding the value of the corresponding characteristic). If FALSE, no conversion is made (overriding the value of the characteristic). If this optional parameter is not present, the characteristic prevails. - RECOGNIZE-INPUT-ESCAPE-SEQUENCES is a boolean flag. When it is true, the distributed terminal handler recognizes input escape sequences and processes them as described in Network Command Terminal Architectural Specification Page 23 the Input Escape Sequence subsection of the OPERATION section below. When the flag is false, input escape sequences are not recognized and the characters of the escape sequence are treated as individual input characters. If this parameter is not present, input escape sequence processing is handled according to the value of the INPUT-ESCAPE-SEQUENCE-RECOGNITION characteristic. - DISABLE-CONTROL defines which control characters are disabled as control characters and processed as normal data. This specification overrides the value of characteristics (e.g., control-U) for the duration of the read. It is one of the following: . NONE - all control characters perform their normal function (subject to the current characteristics) . CLEAR and REDISPLAY - the input editing control characters control-U and control-R are treated as normal data characters (i.e. they are disabled as editing characters for the duration of this read). . EDIT - input editing control characters (viz., DEL, control-W, control-U, and control-R) are treated as normal data characters. . ALL - all control characters are treated as normal data characters except XON and XOFF; this includes all input editing characters, control-O, control-X, and all out-of-band characters. NOTE As XON and XOFF recognition is in the Foundation Layer, turning it on and off must be done by setting the Foundation INPUT-FLOW-CONTROL characteristic appropriately. Thus, for Read-Pass-All, the host must alter the Foundation INPUT-FLOW-CONTROL characteristic as well as the relavant CTERM characteristics. It is also recommended that Read-Pass-All be implemented by altering the appropriate CTERM characteristics (for the control characters) rather than using the ALL flag on the READ request. The reason for this that there are race conditions between READ's (control-X isn't disabled between READ's for starters); use ALL with great care. - TIMEOUT is the intercharacter arrival timeout value in seconds. If a character does not arrive at the beginning of the Type-ahead Buffer during this amount of time after the previous character has been removed, the READ terminates. A zero (0) value means take the characters currently in the Type-ahead Buffer and terminate the READ immediately without waiting for further input. Network Command Terminal Architectural Specification Page 24 - END-OF-PROMPT is the character position after a non-deletable prompt. This prompt may be displayed along with the rest of the input buffer, but it cannot be deleted by the terminal user. If this argument is not present, the end of prompt position is set to the beginning of the buffer. - START-OF-DISPLAY is the first character position of data to be displayed immediately. The data will be displayed by "echoing" it. That is, the characters to be displayed will be translated into their echo representation just as if they had been entered at the terminal. If this argument is not present, the start of display position is set to the end-of-data value. - LOW-WATER is the last character position in the buffer that is to be considered not to have been modified by input editing since the READ was issued. This parameter may be decremented during the read, but is not incremented. The modified value of this argument is returned with a read completion indication via the READ-POLL function. If this argument is not present, the low water position is set to the beginning of the buffer. - TERMINATION-SET is the set of characters that can terminate the READ. This set takes the form of a 256-bit mask. If this argument is not present, the termination set most recently specified via the READ function is used. - RETURN is one of the following: . success - READ request queued . failure - READ request currently queued . failure - inconsistent arguments Certain combinations of pointer values are considered as errors. An example is when END-OF-DATA is less than END-OF-PROMPT. UNREAD (PORTAL-ID, CONDITION; RETURN) -- queues a request to (conditionally) terminate a previously queued read request. - CONDITION is one of the following: . ALWAYS -- terminate a read unconditionally . EMPTY -- terminate a read only if the Type-ahead and Input Buffers are empty (except for a prompt). - RETURN is one of the following: . success . failure - UNREAD request currently queued . failure - no unterminated read requests outstanding | | If CONDITION has the value ALWAYS and input escape sequence | recognition is enabled, this resets the input escape sequence | state machine. It is indeterminate if the current READ request will be terminated by this request. This is due to the race condition Network Command Terminal Architectural Specification Page 25 that can occur within the Handler when a read request is being terminated by internal algorithmic activity (e.g., after a termination character is entered by the terminal user) at approximately the same time that the operating system issues the UNREAD request. READ-POLL (PORTAL-ID; RETURN, BUFFER, LOW-WATER, | MORE-DATA-FLAG, VERTICAL-POSITION, HORIZONTAL-POSITION TERMINATOR-POSITION) -- checks if a previously queued READ request is complete. - RETURN is one of the following: . success - read terminated by a termination character . success - read terminated by a valid escape sequence . success - read terminated by an invalid escape sequence . success - read terminated by an out-of-band character . success - read terminated because the buffer filled . success - read terminated by intercharacter arrival timeout . success - read terminated by an UNREAD request . success - read terminated by underflow (e.g., a DEL character was entered when the Input Buffer was empty) . success - read terminated by an absentee token (complete token would not fit in current read -- still in server) . success - read terminated by line break (final character in buffer is NUL received with break) . success - read terminated by framing error (final character in buffer is character on which error occurred) . success - read terminated by parity error (final character in buffer is character on which error occurred) . success - read terminated by receiver overrun (final character in buffer is character on which error occurred) . failure - no read request outstanding . failure - READ not complete - BUFFER is a returned buffer (returned only on success) - LOW-WATER is the updated value of the corresponding parameter from the READ function (returned only on success). - MORE-DATA-FLAG is a Boolean flag indicating if there was more data in the Type-ahead Buffer when the read terminated. | - VERTICAL-POSITION is the ralative vertical position change | (number of lines) on the presentation device since the | beginning of this read. | - HORIZONTAL-POSITION is the ralative horizontal position | change on the presentation device since the beginning of | this read. | - TERMINATOR-POSITION is the number of data characters | (excluding terminators, escape sequences, etc.) in the | buffer. Thus, if there is a terminator or escape sequence | in the buffer, it points to the terminator or the first Network Command Terminal Architectural Specification Page 26 | character of the escape sequence. NOTE The prompt from the READ function is not returned by the READ-POLL function. 3.1.2 Reading Out-of-band Characters - READ-OUT-OF-BAND (PORTAL-ID; RETURN, OUT-OF-BAND-CHARACTER) -- requests the return of a pending Out-of-band character. - RETURN is one of the following: . success - Out-of-band character returned . success - "line break" occured; no Out-of-band character returned . failure - no Out-of-band character pending 3.1.3 Writing Characters - The following function is used to send characters to the logical terminal. It may also be used to control the terminal without sending characters to it. In particular, the DON'T-DISCARD-FLAG has meaning in the WRITE function even if no data is written. | WRITE (PORTAL-ID, DON'T-DISCARD-FLAG, NEWLINE-FLAG [,LOCKING] [,TRANSPARENT-FLAG] [,COMPLETION-STATUS-FLAG] [,BUFFER] [,PREFIX-CODE, PREFIX-VALUE] [,POSTFIX-CODE, POSTFIX-VALUE]; RETURN [,REQUEST-ID]) -- requests several funtions including writing data to the terminal. - DON'T-DISCARD-FLAG is a Boolean value that, if true, sets the output discard state of the Handler to "not discarding" before the output data is processed (see READ-DISCARD-STATE function below). | - NEWLINE-FLAG is a Boolean value that, if true, directs the | logical terminal to output a linefeed at the end of a write | and set an internal "skip linefeed" flag so that if the | first character in the next write is a linefeed, double | spacing is avoided. - LOCKING a value which defines how locking is to be handled for the duration of this write. The values are as follows: . 0 -- unlock . 1 -- lock before writing data; do not unlock after writing data Network Command Terminal Architectural Specification Page 27 . 2 -- lock before writing data and unlock at end of data; do not redisplay . 3 -- lock before writing data and unlock at end of data; redisplay Input Buffer after unlocking. - TRANSPARENT-FLAG is a Boolean value that, if true, causes the data in this write request to be written to the Foundation Services using the "transparent" Write-Character function. "Transparent" write does not expand tabs or wrap and resets HPOS and VPOS (position modeling) to zero. - COMPLETION-STATUS-FLAG is a Boolean value that, if true, causes the Handler to return a write completion status via the WRITE-POLL function. - BUFFER is a buffer containing the data to be sent to the terminal. This argument is optional because the functions requested by setting the other arguments true may be requested without requesting data output. The WRITE function is modelled as copying the data from this buffer immediately to a buffer internal to the Handler (an implementation may, of course, not operate this way). - PREFIX-CODE defines whether or not data should be prefixed to the output and, if so, how PREFIX-VALUE should be interpretted. It is one of the following: . NONE - don't prefix the output data . NEW-LINES - prefix the output data with followed by the number of 's specified in PREFIX-VALUE . CHARACTER - prefix the output data with the character specified in PREFIX-VALUE - PREFIX-VALUE is either a number or a character, as defined by PREFIX-CODE. - POSTFIX-CODE is interpretted exactly as PREFIX-CODE, except that it applies to post-fixed data. - POSTFIX-VALUE is interpretted exactly as PREFIX-VALUE. - RETURN is one of the following: . success - request queued . failure - insufficient resources - REQUEST-ID is a value returned only if COMPLETION-STATUS-FLAG is true. It is a handle for executing the WRITE-POLL function. The following function is only required if the WRITE function requests completion status. WRITE-POLL (PORTAL-ID, REQUEST-ID; RETURN, HORIZONTAL-POSITION, VERTICAL-POSITION) -- polls to get back status of a previously queued WRITE request that requested completion status. - REQUEST-ID is a value returned from a previous WRITE request Network Command Terminal Architectural Specification Page 28 - RETURN is one of the following: . success - WRITE complete, no data discarded . success - WRITE complete, data discarded due to control-O action by user . failure - no outstanding WRITE request for REQUEST-ID . failure - WRITE request stilled queued | - HORIZONTAL-POSITION is the relative horizontal position | change of the cursor on the presentation device at the | completion of the WRITE. | - VERTICAL-POSITION is the relative vertical position change | of the cursor on the presentation device at the completion | of the WRITE. 3.1.4 Control And Status Functions - CLEAR-INPUT (PORTAL-ID; RETURN) -- queues a request to clear the Type-ahead and Input Buffers. - RETURN is one of the following: . success - request queued . failure - insufficient resources | | If input escape sequence recognition is enabled, this resets | the input escape sequence state machine. CHECK-INPUT (PORTAL-ID; RETURN) -- queues a request to return the number of characters in the Type-ahead and Input Buffers (combined). The requested value is returned via the CHECK-INPUT-POLL function. No more than one CHECK-INPUT request may be queued at a time. - RETURN is one of the following: . success - request queued . failure - CHECK-INPUT request currently queued CHECK-INPUT-POLL (PORTAL-ID; RETURN, COUNT) -- returns the character count requested via a previous CHECK-INPUT function. The value returned is the value at some point in the past between execution of the CHECK-INPUT request and the completion this function. - RETURN is one of the following: . success - COUNT returned . failure - CHECK-INPUT request queued but not complete . failure - CHECK-INPUT request not queued - COUNT -- the requested count (returned only on success) Network Command Terminal Architectural Specification Page 29 READ-INPUT-STATE (PORTAL-ID; INPUT-STATE) -- returns the input state of the terminal at some point in the past. - INPUT-STATE indicates whether or not the number of characters in the Input and Type-ahead Buffers (combined) is zero or not. One of the following: . ZERO . NON-ZERO READ-DISCARD-STATE (PORTAL-ID; DISCARD-STATE) -- reads the discard state of the terminal at some point in the past - DISCARD-STATE is a value in indicating if output to the terminal is being discarded by the Handler (due to the entry of a control-O). One of the following: . DISCARDING - output is being discarded . NOT-DISCARDING - output is not being discarded The state may be set to NOT-DISCARDING via the WRITE function. 3.1.5 Reading And Writing Characteristics - WRITE-CHARACTERISTIC (PORTAL-ID, (SELECTOR,VALUE) [,...]; RETURN) -- queues a request to write a collection of selected characteristics. - SELECTOR is a characteristic selector (e.g., "RAISE-INPUT") - VALUE is the new value for the specified characteristic - RETURN is one of the following: . success . failure - insufficient resources This function allows the operating system to write both Foundation-maintained characteristics and Handler-maintained characteristics. While the latter may always be written by the operating system, the former may not always be. If the operating system attempts to write a Foundation-maintained characteristic while such writing is disabled (see the Foundation Services specification), the write will fail, but the operating system will be given no explicit indication that the write failed. The operating system may ascertain that the write failed by reading the characteristic(s) back via the following function to see if they changed. READ-CHARACTERISTIC (PORTAL-ID, (SELECTOR,VALUE) [,...]; RETURN) -- requests the return of the values of the selected characteristics. The VALUE (the information being requested) parameter will in general be "null" except in the case of characteristics with compound values where part of the value may be used to further define (help select) the characteristic whose value is being requested -- see section "Selector Values Network Command Terminal Architectural Specification Page 30 for Characteristics" in the OPERATION section below for further details of compound characteristic values. The values are returned by the READ-CHARACTERISTIC-POLL function. - SELECTOR is a characteristic selector - RETURN is one of the following: . success - request queued . failure - previous request outstanding . failure - insufficient resources READ-CHARACTERISTIC-POLL (PORTAL-ID; RETURN, (SELECTOR, VALUE) [,...]) -- returns the values of characteristics previously requested by the READ-CHARACTERISTIC function. - RETURN is one of the following: . success - VALUEs returned . failure - no request queued . failure - READ-CHARACTERISTIC request still queued - SELECTOR is a characteristic selector - VALUE is the value of the corresponding characteristic (returned on success) 3.2 Server Terminal Interface As stated above, this interface contains functions at two levels. At one level, this interface allows the Network Command Terminal Module in the server system to read and write characters, to detect mode changes, and to read and write characteristics. These interface functions are described in the Foundation Services Specification. They can be duplicated here, if desired, once the Foundation Services Specification is approved. At the second level, this interface contains functions perceived by the human terminal user, as described generally above in the overview section. The quoting, output control, and input editing control functions are described more fully below. 3.2.1 Quoting - If quoting is enabled (via a characteristic) and a control-V character is entered at the terminal, the character following the control-V is not recognized as a control character. It is not acted upon as an output control character, an input editing character, an out-of-band character, or a termination character. Network Command Terminal Architectural Specification Page 31 The control-V and following character are treated as a single character (a token). Therefore, entering a DEL character after such a pair causes the pair to be deleted. The control-V is passed to the operating system on read completion. If the complete token will not fit in the current Input Buffer, the READ is terminated (status -- success, terminated by absentee token) and the host will have to post another READ to get the token plus any subsequent input (a quoted character token does not terminate a READ). 3.2.2 Output Control - If output discarding is enabled (via a characteristic) and a control-O character is entered at the terminal, the discard state of the terminal (read by the operating system via a READ-DISCARD-STATE function) is toggled. That is, if its current value is "discarding", it is set to "not discarding" and vice versa. 3.2.3 Input Editing - There are five input editing functions: 1. redisplay input 2. delete character 3. delete word 4. clear input 5. clear type-ahead The descriptions which follow summarize how input editing is invoked and the effect of the Server's input editing algorithms on the presentation device. The details of input editing are described in the "OPERATION" section below. 3.2.3.1 Redisplay Input - This function is invoked by the entry of a control-R character. It redisplays the prompt from the READ function (if any) concatenated with the contents of the Input Buffer on the line after the current one. Network Command Terminal Architectural Specification Page 32 3.2.3.2 Delete Character - This function is invoked by the entry of a DEL character. If underflow occurs and is a termination condition, the editing is handled by the host. Otherwise, the last character of the Input Buffer is deleted. If the character has been echoed, its echo representation is deleted from the presentation device as follows: o hard-copy terminals -- If the character is the first character in a row to be deleted, a backslash (\) is output. The character is then echoed as it originally was. When the first non-delete character is entered after multiple DEL characters, an ending backslash is output. o softcopy terminals -- Each character in the echo representation is deleted separately, from the last to the first. In general, these echoed characters are removed directly from the screen. This processing is done according to the input editing algorithm described in the appendix. 3.2.3.3 Delete Word - This function is invoked by the entry of a control-W character. It deletes the "word" at the end of the Input Buffer. A word is defined as consisting of a string of consecutive alphanumeric characters followed by a string of non-alphanumeric characters or the end of the Input Buffer. A word is preceded by either a non-alphanumeric character or the beginning of the Input Buffer. The effect of the delete word function when applied to other than a word, as defined above, is to delete all characters from the Input Buffer. "Unechoing" for delete word is handled as though a DEL had been issued for each character being deleted, i.e. for soft-copy terminals, each character is blanked out and for hard-copy terminals, each character deleted is re-echoed using the \xxx\ figure. This process is done according to the input editing algorithm described in the appendix. 3.2.3.4 Clear Input - This function is invoked by the entry of a control-U character. It clears the Input Buffer, the control character is echoed and the prompt redisplayed on the next line. Network Command Terminal Architectural Specification Page 33 3.2.3.5 Clear Type-ahead - This function is invoked by the entry of a control-X character. It clears the Type-ahead Buffer and then places a control-U in the Type-ahead Buffer if there is an active READ. 3.3 Terminal Characteristics An operating system has access to several characteristics via the WRITE-CHARACTERISTICS and READ-CHARACTERISTICS functions. Some characteristics that may be read and written via these functions are maintained by the Foundation Services and are described in the Foundation Services Specification. Foundation-maintained characteristics are maintained across bindings. Other characteristics are maintained by the Handler itself. These characteristics are not maintained across bindings. Each of these characteristics is described below. The following descriptions summarize the terminal characteristics maintained by the Handler. Each characteristic description includes the initial value of the characteristic when a binding is first formed. Each characteristic is one of the following types: o Boolean -- takes TRUE and FALSE values. o Integer -- signed integer; bit width is 16 bits unless specified otherwise. o Bit Map -- a string of bits, each having a separately defined meaning. o Compound -- a value which consists of more than one field. The characteristics are defined below. o IGNORE-INPUT -- causes all input from the Server Terminal Interface to be discarded without processing - Boolean (initial value is FALSE) - If TRUE, the Handler discards all input. - If FALSE, the Handler processes all input. o CHARACTER-ATTRIBUTES -- specifies, on a per character basis, the attributes of the character. The format of this compound characteristic is defined in a subsection following the protocol message definitions and the lists of characteristics. CHARACTER-ATTRIBUTES defines the following attributes for each character: - Out-of-Band Handling -- specifies whether a particular character is an out-of-band character and the type of out-of-band character it is. If a character is an Network Command Terminal Architectural Specification Page 34 out-of-band character, it is passed to the operating system independently from other input characters. The actions specified for the out-of-band characters should be performed in the order specified so the order of arrival of Out-of-Band messages and Read messages at the host will be predictable. (a) Not out-of-band character (b) Immediate-clear out-of-band character; the character is placed in the Out-of-band Buffer. The Type-ahead Buffer is then cleared (regardless of the enabled or disabled state of control-X) and the current read (if one is outstanding) is terminated. (c) Deferred-clear out-of-band character; this is actually a double control character (two consecutive, identical control characters). If only a single control character of this type, it is treated as though it were not an out-of-band character. A deferred-clear out-of-band character produces the same effect as an immediate-clear out-of-band character except that only one of the two characters is placed in the Out-of-band Buffer for transmission to the operating system. (d) Immediate-hello out-of-band character; this is passed to the operating system independently of other input characters, but it does not clear the Type-ahead Buffer or terminate the current read as with the "clear" out-of-band characters. - Include Flag -- indicates whether a copy of a hello out-of-band character should be included in the normal data stream. - Out-of-Band Discard Flag -- indicates whether or not an entered clear out-of-band character sets the output discard state to "discard". - Control Character Echoing -- how a control character or DEL should be echoed. - Disable/Enable Special Character Function -- specifies whether the special functions associated with certain well known control characters are enabled or disabled. Network Command Terminal Architectural Specification Page 35 o CONTROL-O-PASS-THROUGH -- whether or not control-O characters are passed through as input data characters when enabled as a control character - Boolean (initial value is FALSE) - if TRUE, the control-O is passed through as input data in addition to performing its control functions. - if FALSE, the control-O is not passed through as data. o RAISE-INPUT -- whether or not the lower case alphabetic characters are to be converted to upper case on input - Boolean (initial value is FALSE) - If TRUE, the characters whose decimal values are 97 --> 122, inclusive, have their values decremented by 32 (decimal). This is done by the Input Process as characters are moved from the Type-ahead Buffer to the Input Buffer. - If FALSE, no conversion is done. o NORMAL-ECHO -- how characters other than control characters and DEL are echoed - Boolean (initial value is TRUE) - Values are: . If TRUE, echo the characters. . If FALSE, don't echo the characters. o INPUT-ESCAPE-SEQUENCE-RECOGNITION-ENABLE -- whether input escape sequences are recognized - Boolean (initial value TRUE) - If TRUE, input escape sequences are recognized and processed as described in the Input Escape Sequence subsection of the OPERATION section below. - If FALSE, input escape sequences are not recognized and the characters in the escape sequence are treated as normal data. o OUTPUT-ESCAPE-SEQUENCE-RECOGNITION-ENABLE -- whether output escape sequences are recognized - Boolean (initial value TRUE) - If TRUE, output escape sequences are recognized and processed as described in the Output Escape Sequences subsection of the OPERATION section below. - If FALSE, output escape sequences are not recognized and the characters in the escape sequence are treated as normal data. Network Command Terminal Architectural Specification Page 36 o INPUT-COUNT-STATE -- defines how the automatic transmission of Input State messages is to be handled - Integer (initial value DO-NOT-SEND) - Values are 1- DO-NOT-SEND -- do not automatically send Input State messages when the number of input characters changes between zero and non-zero. 2- NO-READ-SEND -- the Input State message is automatically sent only when there is no outstanding READ. 3- SEND -- the Input State message is automatically sent when the combined Input Buffer and Type-ahead count changes between zero and non-zero except when a read terminates (in which case, the same information is sent in the Read Data message). o AUTO-PROMPT -- whether or not a control-A is sent to the terminal after the prompt, if any, before the read - Boolean (initial value is FALSE) - If TRUE, a control-A is sent. - If FALSE, a control-A is not sent. o ERROR-PROCESSING -- whether or not the following types of error (received together with an input character from the Logical Terminal Service) are ignored by the Pre-input Process (i.e. the Pre-input Process discards the error and character so the Input Process never sees either the error or the input character) or are queued in the Type-ahead Buffer (together with the character on which the error occurred). Characters received with one of the following error indications are not processed according to the normal precedence rules specified for the Pre-input Process (see the subsection Pre-Input Process). Instead, they are always processed with the lowest precedence (so an error can't accidentally cause something dreadful to happen, e.g. a parity error turn an ordinary X into a control-X): - Bit map with one bit for each type of error. The values for each bit are "ignore" (0) or "queue" (1) (initial value for each error type is "ignore") - Error types are . "line break" . "framing error" . "parity error" . "receiver overrun" Network Command Terminal Architectural Specification Page 37 3.4 Termination Set The Termination Set is a 256 bit map whose initial value is zero. There is one bit for each of the characters whose value is in the range 0-255. A character is a termination character if its corresponding bit is set. Network Command Terminal Architectural Specification Page 38 4.0 OPERATION This chapter considers the Handler as a distributed system. Figure 4-1 shows the Handler's structure. +------------------+ | HOST SYSTEM | | | | +----------+ | | | USER | | | +----------+ | | | | | V | | +--------------+ | | | OPERATING | | +----------------------+ | | SYSTEM | | | | | +--------------+ | | SERVER SYSTEM | | | (1) | | | | V | | | | +--------------+ | Command Terminal | +------------------+ | | | HOST HANDLER |=|= = = = = = = = = |=| SERVER HANDLER | | | | MODULE | | Protocol | | MODULE | | | +--------------+ | | +------------------+ | | | (3) | | | (4) | (2) | | V | | V V | | +--------------+ | | +--------+---------+ | | | FOUNDATION | | | | COMM. | LOGICAL | | | | SERVICES | | | | | TERMINAL| | | +--------------+ | | | | | +------------------+ | | FOUNDATION | | | | SERVICES | | +----------------------+ | TERMINAL DEVICE(S) Figure 4-1 Structure of Distributed Terminal Handler In Figure 4-1, interfaces (1) and (2) are equivalent to the interfaces of the same number in Figure 2-1. Interfaces (3) and (4) allow the two modules comprising the Handler to make use of a binding between them to transmit and receive command terminal protocol messages. The functions of these interfaces (3 and 4) are described in the Foundation Services specification. In the descriptions below, the part of the Handler residing in the Host system is referred to as the "Host Module", or more simply the "Host". Similarly, the part of the Handler residing in the Server system is referred to as the "Server module" or the "Server". Network Command Terminal Architectural Specification Page 39 4.1 Interfaces And Protocols Examination of the interfaces (only interfaces (1) and (2) -- interfaces (3) and (4) are operating at a lower level and are not relevant for purposes of this discussion) specified in section 3 and the protocol specified in this section will show that the functions offered are not identical. The protocol, for example, supports terminating a READ on a vertical change in the echoed image of input data, a function which is not available at interface (1). This difference between the functions of the interfaces and the protocol is a result of the relation between the two. It is the interfaces that are of primary importance and the protocol is just a means to support these interfaces in a distributed environment. Standardized conceptual interfaces, such as (1) and (2), are one of the key factors in distributed processing. While the protocols which are used to support these interfaces are, in a certain sense, more visible than the conceptual interfaces themselves, it is important not to get their roles reversed. The idea of a layered architecture, used in both DNA and TSA, is based on conceptual interfaces. 4.2 Host/Server Division Of Labor This specification defines most of the distributed terminal handler functions to be performed by the Server. The reason for this is that the goal of reasonable performance implies the need to handle user input editing requests close to the user. This, in turn, implies that the Input Process (and, therefore, the Pre-Input Process and Output Procedure) of figure 2-2 must reside in the Server. The Host module primarily converts host terminal interface requests to protocol messages and vice versa. The Host module is, therefore, not discussed in detail below. Much of the algorithmic operation of the Server is implied by the descriptions in section 2. The descriptions below do not restate the operation implied by section 2 but add information regarding protocol operation, the relation to the Foundation Services interface and, in some cases, details of algorithmic operation not found in section 2. 4.3 Data Channels The Host and Server modules communicate via a binding provided by the Foundation Services. Network Command Terminal Architectural Specification Page 40 4.4 Protocol Message Overview The message types in the command terminal protocol are summarized below. Message Direction Definition ------- --------- ---------- Initiate H <--> S carries initialization information Start Read H ---> S carries READ request Read Data H <--- S carries input data Out-of-Band H <--- S carries out-of-band input data Unread H ---> S carries UNREAD request Clear Input H ---> S carries Clear Input request Write H ---> S carries WRITE request Write Complete H <--- S carries write completion status Discard State H <--- S carries a change to the output discard state due to a terminal user request (via an entered output-discard character) Read Characteristics H ---> S requests characteristics Characteristics H <--> S carries characteristics Check Input H ---> S requests input count Input Count H <--- S carries input count Input State H <--- S indicates a change from zero to non-zero or vice versa in the number of characters in the Input and Type-ahead Buffers combined 4.5 General Message Processing The network command terminal protocol is a request/response protocol. That is, the Host module sends one, or several related, messages to the Server module in response to a single queued request (as described in the host terminal interface) from the operating system. The Server module, in turn, sends one, or several related, messages to the Host module in response. The response messages are not necessarily sent Network Command Terminal Architectural Specification Page 41 immediately or in a predictable order, but they are eventually sent. The Server never sends data to the Host except in response to a previously received read request (conveyed to the Server via a Start Read message). The Server receives all protocol messages on a single data channel of the underlying binding. These messages are generally processed to completion in the order they are received. This ensures that functions that the operating system expects to have executed sequentially are done so. 4.6 Protocol Errors A protocol error occurs when a protocol message is received which cannot be interpreted in a way that will ensure secure and synchronized operation. An example is when a Server receives a second Start Read message without having completed | the previous read request. Unless otherwise specified, the | occurance of non-zero values in unused or reserved fields and | 1's in unused or reserved bits in bitmaps can be ignored. All | other errors in received messages constitute a protocol error | with the single exception of the Initiate Message -- see the | Protocol Evolution section below for a statement of protocol compatibility. A module detecting a protocol error breaks the connection over which the protocol was operating. This process, known as unbinding, is defined in the Foundation Services specification. 4.7 Initialization When a pair of Host and Server modules first communicate over a given binding, each sends an Initiate message to the other. It is a protocol error for a module to receive any message other than this message when the binding is first used. Similarly, it is a protocol error to receive this message at any other time. The Initiate message contains a version identification. An implementation of this version (1.0.0 in the protocol) assumes it is compatible with any future (i.e., higher-numbered) version; it is not a protocol error to receive a version number higher than 1.0.0. The Initiate message is designed for easy extension; any parameter which either module receives which it does not understand is ignored. Network Command Terminal Architectural Specification Page 42 4.8 Characteristics Management The Host sends a Read Characteristics message to elicit a Characteristics message from the Server. If the operating system changes the characteristics when there is no read request pending, the terminal characteristics will be as specified for subsequently issued reads and writes. It is a protocol error if an invalid selector or value is specified in a Read Characteristics or Characteristics message. 4.9 Read Request Processing 4.9.1 Issuing The Read - When the host terminal interface READ function is executed, the Host sends a Start Read message. This message contains the parameters from the READ function. The portion of data in the host's BUFFER after START-OF-DISPLAY is sent in the DATA field of the Start Read message. It is assumed that the Start Read message will be large enough to contain all the data to be sent to the Server. If formatting has been selected (the FORMATTING-FLAG on the READ) and the last character output was a CR, then a LF is output (to avoid overprinting); in addition, if the first character of the preloaded input would echo as a LF, it is ignored (to avoid accidental double spacing). If the Start Read contains a prompt, the Input Process writes out the characters in the prompt without performing any echo translation on these characters. Next, the Input Process invokes the foundation services RESET PAGE-STOP-POSITION function. If the Output-page-stop characteristic is true, this function causes the foundation page-stop-position variable to be set 0; invoking this function when a Read is issued, allows the foundation "output page stop" algorithm to produce the correct visual effect. If the Output-page-stop characteristic is false, this function has no effect. If the AUTO_PROMPT characteristic is TRUE, before the data in the Start Read's DATA field (the prompt) is echoed, a control-A is sent to the terminal (this is usually used by automatic input devices to determine when a READ is posted). If a Server receives a Start Read message while it has a read pending, it is a protocol error. Network Command Terminal Architectural Specification Page 43 4.9.2 Unreading - If a Host wants to terminate a read request it issued earlier, it may send an Unread message to the Server. An Unread message terminates the current read request (if any) when the Unread message is processed in the Server. This is considered a termination condition and the read request is completed as described below. A Host may specify that only an outstanding read for which the Input Buffer is empty and the Type-ahead buffer is also empty will be terminated. | | If an Unread terminates a pending read with a non-empty Input | and/or Type-ahead buffer, the input escape sequence state | machine is reset if input escape sequence recognition is | enabled. Since a read completion and an Unread message may cross between the Host and the Server, an Unread received by the Server when no read is outstanding is not a protocol error and is ignored. 4.9.3 Position Modeling - The Input Editing functions in the Server require knowledge of the active horizontal output position (input editing is discussed in detail in Appendix A). The active horizontal and vertical positions are maintained by the Foundation Services and are available at the server terminal interface. 4.9.4 Read Completion - When a termination condition occurs in the Server (including processing an Unread message), the current read request is completed. All input data is sent to the Host via a Read Data message. The maximum protocol message size must be selected to be large enough to contain both the Read message protocol header and the whole Input Buffer. If there was a prompt in the Start Read message, this prompt is not returned to the Host in the Read Data message (the prompt is non-deletable and the Host is assumed to know what it was in the event it is required). 4.9.5 Input Editing - Input editing can be handled in either of the following ways: Network Command Terminal Architectural Specification Page 44 1. entirely within the server system (local) provided sufficient resources are available in the Server to contain the entire Input Buffer specified with the READ request at interface (1), or 2. distributed between the server and host systems (as described below) when either 1. the Server does not have sufficient resources to contain the complete Input Buffer, or 2. the Host wants to provide more elegant handling of the presentation of the echoed image of the human user's input. The server system's input editing algorithms do not assume the existence of "up-line" and "delete-line" functions on the presentation device and therefore input editing functions such as redisplay and clear input can not blank-out the image of the currently active input line on the screen or redisplay the Input Buffer in place. Instead, they will echo the input editing control characters, issue a CR, LF to advance to the next line on the presentation device and then redisplay the edited Input Buffer. Hosts requiring a more elegant treatment of the image on the presentation device should use distributed input editing. 4.9.5.1 Distributed Input Editing - With distributed input editing, some of the input editing functions are handled in the server and the remainder in the host. Typically, the input editing operations which involve only the current physical line on the presentation device are handled in the server, e.g. delete character and delete word. Operations which involve more than just one line on the presentation device are handled in the host when distributed input editing is selected, e.g. a delete around a line wrap. Also, operations which involve redisplaying in place or blanking-out one or more lines are handled in the host. The Host chooses whether to use local or distributed input editing. If a Host chooses to implement and use distributed input editing, the Host module must provide procedures to handle input editing functions. Network Command Terminal Architectural Specification Page 45 4.9.5.2 Selecting Distributed Input Editing - The Host selects distributed input editing by setting the following characteristics and Start Read message flags: 1. setting control-R and control-U to be termination characters rather than enabled input editing characters -- this causes the handling of redisplay and clear input to be passed to the Host which can handle multiple line deletes and redisplay in place 2. setting the Start Read message continuation-read flag TRUE when the host already has a portion of the input from the READ function -- this causes delete character and delete word to be passed to the Host when the Server can not handle the operation because the word or character to be deleted has already been sent to the host (see the Input Editing appendix for details) 3. setting the Start Read message terminate-on-vertical-change flag -- this avoids the wrap problem by ensuring the Server never has more data than can be contained on one line on the presentation device. The effect of these characteristic and flag settings is to limit the Server, for distributed input editing, to handling only character and word deletions where the item to be deleted is entirely on one line on the presentation device. The Server input editing algorithms in the appendix will handle either local or distributed input editing depending on the values of the Start Read message flags. See the appendix for details of operation. 4.10 Other Input Processing In addition to normal input processing, the Server handles escape sequence recognition, case raising for input characters, input processing for out-of-band, control-V, control-X, control-O characters and errors on input. 4.10.1 Input Escape Sequences - Input Escape sequence recognition is enabled or disabled through the INPUT-ESCAPE-SEQUENCE-RECOGNITION-ENABLE characteristic and RECOGNISE-INPUT-EXCAPE-SEQUENCE flag on the READ function. When enabled, input escape sequence handling is as follows: Network Command Terminal Architectural Specification Page 46 1. Input escape sequences are parsed by a state machine in the input process and terminate the current read. 2. Handling of the escape sequence as a whole (token) takes precedence over the processing of any individual character within the escape sequence which may be defined as a terminator. 3. Input escape sequences do not echo. 4. If an input clear type-ahead function (control-X) is invoked simultaneously with the parsing of an escape sequence, this will result in the read being terminated with an "invalid escape sequence" status (the control-X | will clear the type-ahead buffer) and the input escape | sequence state machine is reset (the control-U put into the | type-ahead buffer after clearing it will not be processed | as part of an escape sequence). | | 5. The input escape sequence state machine is reset as a | result of terminating a read due to either a Clear-input or | Unread from the Host. 6. An input escape sequence is a token and will not be split across two or more reads and remain valid. Buffering of the escape sequence is handled as follows: 1. If the escape sequence can be contained in the current read buffer, it is included with and terminates that read, 2. if the escape sequence won't fit in the current read buffer and the read buffer was non-empty before the start of the escape sequence, the current read is terminated with a status of "terminated by absentee token". Normally, the host will post another read to get the escape sequence (case 3 or 4 below apply). 3. If the escape sequence goes into an empty read buffer and is completely contained, the read is terminated with a "valid escape sequence" status. 4. If the escape sequence goes into an empty read buffer but is bigger than the buffer, the read is terminated with an "invalid escape sequence" status after filling the buffer with characters from the escape sequence. The host may get the remaining characters from the escape sequence by posting another read for them -- they are returned as normal data as the input process is no longer in the escape sequence state. Network Command Terminal Architectural Specification Page 47 4.10.2 Raising Input - The Host may request that the Server raise the case of input characters by setting the RAISE-INPUT characteristic true. When this is done, the Server examines every character as it moves them from the Type-ahead Buffer to the Input Buffer to see if it is a lower case alphabetic character (in the range 97-122, decimal). If so, it is coverted to the upper case equivalent (by subtracting 32, decimal). This processing is done by the Input Process. The effect of this characteristic may be overridden for individual READ's by the RAISE-INPUT flag on the READ. 4.10.3 Out-of-Band Processing - When an enabled out-of-band character or "line break" is recognized by the Server, it is sent to the Host via an Out-of-Band message. If it is a "clear" out-of-band character, the Type-ahead Buffer is cleared, and if a read is pending, the read is terminated. A copy of each "hello" out-of-band character is included in the normal data stream if the HELLO-OUT-OF-BAND-PASS-THROUGH characteristic is true. For those cases where Out-of-Band processing results in transmitting both a Out-of-Band message and a Read Data message, the Out-of-Band message is always transmitted first. 4.10.4 Control-V - When the user enters a control-V, the character after the control-V is ignored as either a control character, an out-of-band character, or a termination character. The control-V is buffered as a normal data character. 4.10.5 Control-X - When the user enters a control-X character, the Server clears the Type-ahead Buffer. If there is a read active, the Server also executes a clear input function, the latter being the same function as if the user had entered a control-U. 4.10.6 Control-O - The control-O character affects output discard handling, discussed below. Network Command Terminal Architectural Specification Page 48 4.10.7 Errors On Input - Input characters from the Foundation Services can have four errors associated with them, i.e. line break, framing error, parity error, and receiver overrun error. The Pre-input Process, depending on the value of the characteristic ERROR-PROCESSING, may either discard these error characters (in which case the error is ignored as the Input Process never sees the error or the character on which it occurred) or it queues the character and the error along with normal input in the Type-ahead Buffer for the Input Process. When the Input Process gets one of these errors, it terminates the current Read. If a Read is not active in the server, the error condition will terminate the next Read which would normally include this character. Any characters preceding the error are returned as normal; the character on which the error occurred is the last character in the buffer returned when the Read is terminated. The character on which the error occurred is always returned, even if it is the only character returned with the terminated Read (and is probably garbage). What happens to the characters in the Type-ahead Buffer after the character on which the error occurred is implementation dependent. 4.11 Write Request Processing A Host sends output to the Server via the Write message. The Server may queue the information from a Write message. If it does, it also queues the FLAG field information. The Write messages are processed to completion in the order received. Due to restrictions in the maximum length of a protocol message that the Server can receive, the information from a single WRITE request by the operating system may be carried in multiple Write messages. When this occurs, the first such message contains all flags from the WRITE request, and the "beginning of message" flag in the message is set. Write messages containing intermediate data have the "beginning of message" and "end of message" flags cleared. The Write message containing the final data has the "end of message" set. (A single Write message containing all data from a single WRITE request has both the "beginning of message" and "end of message" flags set.) All Write message flags are ignored except when "beginning of message" is set. It is a protocol error for a Server to receive Write messages with the "beginning of message" and "end of message" flags set incorrectly. The following are protocol errors: . receiving the first Write message on the binding with "beginning of message" clear. . receiving a Write message with "end of message" set followed by a message with "beginning of message" clear. Network Command Terminal Architectural Specification Page 49 . receiving a message with "end of message" clear followed by a message with "beginning of message" set. (There is an exception to this when the output discard state is toggled, as described below.) In the descriptions below, a "message" means the flags and data from a single WRITE request, regardless of the number of Write messages used to convey the request. If a message has "don't discard" flagged, the output discard state is set to "don't discard" before the message data are written. If a message has "completion status requested" flagged, then the Server sends a Write Completion message after writing the message data. The Write message contains information regarding prefixing and postfixing data to the message data. The "prefix code" and "postfix code" flags values and the PREFIX-VALUE and POSTFIX-VALUE fields contain the information required to pre- and postfix the message data. A Host may send a Write message without data to effect control. In this case, the "beginning of message" and "end of message" flags are both set, and the Write message does not contain the DATA field. The rules stated above for "beginning of message" and "end of message" flags also apply. This means that the Host cannot interrupt the sending of a sequence of Write messages containing output data to send control data. 4.12 Other Output Processing In addition to writing data, the Server handles the output discard state, locking, and output escape sequences. These are described below. 4.12.1 Output Discard State Handling - The Server maintains two state variables used for output discard processing: one (the "requested state") that reflects what the user or operating system most recently requested, and one (the "real state") that represents how the Server is currently processing output. Each state variable may take on the "discard" or "don't discard" value. The initial state of each is "don't discard" when a binding is first used. When the user enters a control-O character, the requested state is toggled, and a Discard State message is sent to the Host containing the new requested state. When the Server receives a Write message with the "set output discard state" flag set, it sets the requested state to "don't discard". Network Command Terminal Architectural Specification Page 50 When the requested state makes a change to "discard", the Server sets the real state to "discard" also. In this state, the Server discards the data from all received Write messages. When the Server sets the real state to "discard", it also clears the output "lock" if one is in effect. However, the Server continues to process the flags from Write messages with the exception of "unlock" and "redisplay" flags. When the Server sets the requested state to "don't discard" because of Write message flag processing, it also sets the real state to "don't discard"; it does not change the real state to "don't discard" as a result of a control-O from the terminal user. The Host maintains a single version of the output discard state. It sets this version to (1) the most recent value from a received Discard State message, (2) "don't discard" as the result of a WRITE request from the operating system specifying DON'T-DISCARD, or (3) "don't discard" as the result of a READ request from the operating system. (The Host returns this version of the state on a READ-DISCARD-STATE function). When the Host sets the state to "don't discard" as the result of receiving a Discard State message containing the "don't discard" state or as the result of the operating system executing a WRITE with the DON'T-DISCARD-FLAG true, it sends a Write message to the Server with the "set output discard state" flag set. When the discard state is set to "don't discard" as the result of a READ request from the operating system, the Server sets the real discard state to "don't discard" when it receives the Start Read message generated as a result of the READ request. While the host's state is "discard", it discards any data (but not flags) from operating system WRITE requests. The result of the operation described above is that a change to the real "discard" state is always a result of the entry of a control-O by the user and is acted upon immediately by the Server. A change to the real "don't discard" state is always caused by Host action. A control-O from the user to change the state back to "don't discard" requires a round trip protocol exhange between the Server and the Host. It is possible for the Server to have a resource failure in attempting to send a Discard State message. If so, the Server loops, trying to send the message. (This looping is done by the Pre-Input process.) Eventually, either the message is successfully sent, or data being entered by the terminal user are lost. Because a change to the real "discard" state may take place in the middle of a multi-message write, a Write message with the "set discard output state" flag set is not considered a protocol error even if the last Write message received did not have the "end of message" flag set. Network Command Terminal Architectural Specification Page 51 4.12.2 Locking - Locking resolves the potential priority conflict between output data from a WRITE request and output resulting from echoed input. When the Server is not "locked", echo output has priority on a character by character basis. When the Server is "locked", no echo output is accepted until the Server is "unlocked". The one exception to this is that out-of-band control characters are echoed by the Pre-Input Process without regard to whether the Server is locked. Their echoing has priority over other output. Locking and unlocking is controled by parameters in the Write message. If a Write message requests "locking", echoing is locked out before the data are written. If a Write message requests "unlock" and optionally "redisplay", echoing is unlocked after the data are written and the Input Buffer is optionally redisplayed. Once "locked", there are three ways in which the Server can be "unlocked": 1. all data are written and the Write message requested "unlock", 2. a control-O is entered which sets the read-discard-state to "discard", or 3. a "clear" out-of-band character is entered. 4.12.3 Output Escape Sequences - If output escape sequence recognition is enabled (by characteristic only), output escape sequences are written to the Foundation Services with the Transparent Write. After writing the escape sequence, the horizontal and vertical position are both set zero. If either OUTPUT-DISCARD or OUT-OF-BAND-DISCARD are enabled and a discard character is entered while writing an escape sequence, a "cancel" character must be written to the Foundation Services (to return the terminal to a reasonable state). 4.13 Additional Status And Control Operation In addition to the operation described above, the Server provides the Host with the ability to read and write characteristics, to clear input, to request the number of characters in the combined Input and Type-ahead Buffers, and to Network Command Terminal Architectural Specification Page 52