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 be informed when this number changes from zero to non-zero or vice-versa. 4.13.1 Reading And Writing Characteristics - The Host writes one or more characteristics by sending a Characteristics message to the Server. The length of this message is limited by the maximum length of a protocol message that the Server can receive. If the Host wishes to write more characteristics than will fit in a single Characteristics message, it sends multiple messages. If the Host wishes to read one or more characteristics, it sends one or more Read Characteristics messages to the Server. The Server responds by sending one or more Characteristics messages containing the requested information. 4.13.2 Clearing Input - The Host requests the Server to clear all input by sending a Clear Input message. Upon receipt of this message, the Server clears the Type-ahead Buffer and the Input Buffer (if a read is active). 4.13.3 Input Character Count Handling - The Host requests the number of characters in the Type-ahead and Input Buffers combined by sending a Check Input message to the Server. Upon receipt of this message, the Server sends an Input Count message to the Host. In addition to this operation, under the control of the INPUT-COUNT-STATE characteristic, the Server sends an Input State message to the Host whenever the number of characters in the Type-ahead and Input Buffers combined goes from zero to non-zero or non-zero to zero. This operation occurs without being specifically requested by the Host. The characteristics selects when an Input State message is sent: 1. Only when there is no outstanding READ, or 2. All the time except when a read request completes and the Server sends a Read Data message with "finished" set and a completion code, the "more type-ahead data" flag indicating whether or not there is data in the Type-ahead Buffer. Network Command Terminal Architectural Specification Page 53 4.14 Foundation Services Interface Events | There are two significant events that occur at the interface between the Foundation Services and the handler module (either | the Host or the Server module). These are: (1) the | establishment of a binding and (2) the breaking of a binding | (unbinding) | | The Host and Server modules participate in binding and | unbinding as defined in the Foundation Services specification. When a binding is established, the state variables and characteristics of the Host and Server modules are initialized. Each sends an Initiate message to the other. When a binding is broken, the Server module clears the Input and Type-ahead Buffers, loses knowledge of any pending read and temporary read states (e.g. "disable all control characters"), sets the output locking state variable to "unlock", and sets both the requested and real output discard states to "don't discard". No interface activity is defined at the host terminal interface because it it assumed that the operating system can directly view the state of the binding. NOTE While the Foundation Connection Management and Mode Management functions are specified using a subroutine interface (i.e. a polling model which implies the mode modules must periodically poll, using the READ-PORTAL-BINDING-STATE, READ-LOGICAL-TERMINAL-BINDING-STATE, READ-PORTAL-MODE-STATE, and READ-LOGICAL-TERMINAL-MODE-STATE functions, to detect changes in state), actual implementations would probably use an event queuing mechanism as suggested in the section Host Terminal Interface above. 4.15 Protocol Evolution Extensibility is a requirement of this specification. The philosophy guiding the operation of a system in meeting this goal is the following. Compatibility is the responsibility of the implementation using the higher version of the protocol. Compatibility is guaranteed only across one major version number (that part of the version number before the decimal point) of the protocol and means the higher version must use a subset of its protocol that is consistant with correct operation of the Network Command Terminal Architectural Specification Page 54 implementation using the lower numbered version of the protocol. Undefined fields, subfields and illegal values are protocol errors except for the Initiate message where they are ignored (so the version numbers can be exchanged). 4.16 Network Command Terminal Protocol Messages The following notation is used to describe the protocol messages: field (length) : coding = description of field. where: field = the name of the field being described. length = the length of the field, which can be indicated in one of three ways: 1. A number meaning number of 8-bit bytes (octet). 2. A number followed by a "B" meaning number of bits. 3. The letters "I-n" means this is an image field, with n being a number that specifies the maximum length of the field in 8-bit bytes. The image is preceded by a 1-byte count of the length of the remainder of the field. Image fields are variable in length and may be null (count=0). All 8-bits of each byte are used as information bits. The meaning and interpretation of each image field is as defined with that specific field. 4. "(length)" omitted -- the size of the field is not self defining. The field length is determined from the total size of the protocol message by subtracting the position of the start of the field from the total size of the message. (length) is omitted to circumvent the 255 byte limitation of the (I-n) specification. (length) can only be omitted where the field is the final field in the message. coding = the representation type used, where: A = 7-bit ASCII B = binary BM = a bit map of "length" bytes, which may contain Network Command Terminal Architectural Specification Page 55 subfields. A BM field is described as follows: ..AA .BBB depicts of bits 0-7 in a byte (grouped for convenience into two hex-digit sections). The low-order bit is on the right. A dot (.) means that the corresponding bit is reserved; it must be transmitted as zero. One or more capital letter (e.g., AA) define a subfield whose width is equal to the number of identical letter. The values of each such subfield are defined independently. In this example, the AA subfield would have value 0-3 defined, and the BBB subfield would have values 0-7 defined. C = a binary field containing the constant value shown to the right to the equal sign. The following rules apply to the notation: 1. If length and coding are omitted, field represents a number of subfields specified in the description. 2. Any bit or field described as "reserved" shall be zero unless otherwise specified. 3. All fields are presented to the Terminal Communication Services with the least-significant byte first. In an ASCII field, the left-most character is contained in the low-order byte. 4. All numbers are in decimal unless otherwise specified. 5. Byte positions within protocol messages and fields within messages all start at zero (0). 4.16.1 General Message Format - All protocol messages have the following form: MSGTYPE MSGDATA where: MSGTYPE (1) : B = This field contains one of the following message types: Value Message ----- ------- 1 Initiate Network Command Terminal Architectural Specification Page 56 2 Start Read 3 Read Data 4 Out-of-Band 5 Unread 6 Clear Input 7 Write 8 Write Completion 9 Discard State 10 Read Characteristics 11 Characteristics 12 Check Input 13 Input Count 14 Input State | 15 reserved for VMS | 16 reserved for VMS | 17 reserved for VMS In the message descriptions below, the entire message format, including MSGDATA, is described for each message. For each message type, the value of MSGTYPE is considered a constant. A "character pointer" is an interger defining the position of a character in a buffer. The first character in a buffer has position 0. 4.16.2 Initiate (H <--> S) - initiates command terminal protocol on a binding MSGTYPE FLAGS VERSION PARAMETER MESSAGES MSGTYPE (1) : C = 1 FLAGS (1) : C = 0 VERSION = A field identifying the protocol and software (implementation) version numbers. This field is subdivided as follows: VERSION ECO MOD REVISION where: VERSION(1) : B = Protocol version number. ECO(1) : B = ECO number for this version of the protocol. MOD(1) : B = Customer modification Network Command Terminal Architectural Specification Page 57 number. REVISION(8): A = Software revision number. PARAMETER = A field containing a repeating parameter set (there will be as many instances of the parameter set as are necessary). The parameter set consists of two subfields as follows: PARMTYPE VALUE where: PARMTYPE(1) : B = Parameter type which specifies the purpose of the following VALUE subfield. It assumes the following values: Value Meaning ----- ------- 0 Illegal 1 the VALUE subfield (valid in both directions) specifies the maximum size protocol message the sender of the Initiate Message can accept from its partner on the binding. As a lower bound, a server must be able to handle protocol messages of at least 132 (data) + 5 (CTERM header) + 2 (Foundation header) bytes = 139 bytes in length; a host must be able to handle protocol messages of at least 80 (data) + 8 (CTERM header) + 2 (Foundation header) bytes = 90 bytes in length. 2 the VALUE subfield is the maximum size (in bytes) input buffer that a server can support; a host can not request, in the MAX-LENGTH field of the Start Read message, a Read which excedes this value. Servers must be able to handle at least an 80 byte Input Buffer. A host must be able to handle a protocol message of size Input Buffer Size + 8 (CTERM header) + 2 (Foundation header) bytes = Input Buffer Size + 10 bytes. Valid Network Command Terminal Architectural Specification Page 58 only in the server to host (H <--- S) direstion. 3 the VALUE subfield is a bit map specifying which CTERM messages are supported by this implementation (the system transmitting this Initiate Message). A system indicates a message type is supported by setting the corresponding bit in the bit map to one (1). The bits of the full bit map are numbered from 0 through 255. Bit 0 of the bit map is not used. The next 255 bits in the full bit map correspond to the 255 possible CTERM messages, where MSGTYPE = 1 corresponds to bit 1 of the full bit map, ... , and MSGTYPE = 255 corresponds to bit 255. The full bit map is contained in 32 bytes; this field is transmitted low-order byte to high-order byte. Within a byte, the bits are transmitted low-order bit to high-order bit. Where there are trailing zero bytes (as will usually be the case), the trailing zero bytes are not transmitted and the count is adjusted accordingly. Support of the first 14 CTERM messages is mandatory. The TRG will maintain a registry of optional CTERM messages. Receipt of an unsupported message type is a protocol error. VALUE(I-255) = Value of specified parameter. 4.16.3 Start Read (H ---> S) - requests a read and describes an Input Buffer to the Server. MSGTYPE FLAGS MAX-LENGTH END-OF-DATA TIMEOUT END-OF-PROMPT START-OF-DISPLAY LOW-WATER TERMINATION-SET DATA Network Command Terminal Architectural Specification Page 59 MSGTYPE (1) : C = 2 FLAGS (2) : BM = Flags: .... ..EE ZZQT NDDD IIKV FCUU UU = underflow-handling definition 0: ignore underflow 1: write BEL to terminal 2: terminate C = "clear type-ahead" flag 0: don't clear type-ahead 1: clear type-ahead F = "formatting" flag 0: no special action 1: if last character output was CR, output LF; also, if first character of preloaded input is LF, ignore it V = "terminate on vertical change" flag 0: Do not terminate on vertical position change 1: Terminate read if there is a vertical position change on the presentation device while echoing an input character K = "continuation read" flag 0: This is not a continuation of a previous read 1: This read is a continuation of a previous read which terminated on some condition other than that specified for the user's READ request. It indicates that input data from the previous read is buffered in the Host; it is used for distributed input editing, in particular, delete character and delete word processing. NOTE When this flag has the value 1, the UU flag bits above must have the value 2, i.e. "terminate". II = "raise input" flag Network Command Terminal Architectural Specification Page 60 0: Parameter not present in READ request -- use characteristic 1: no conversion for this read only 2: for this read only, convert lower case alphas to upper case DDD = disable control definition 0: Parameter not present in READ request -- use characteristics 1: disable ^U and ^R only 2: disable all editing control characters 3: disable all control characters except XON and XOFF N = "no-echo" flag 0: Echo according to characteristics 1: Do not echo input characters (this read only) regardless of characteristics value. T = "terminator echo" flag 0: do not echo terminator 1: echo terminator Q = TIME-OUT field present flag 0: TIME-OUT field not present in READ request -- the default is an infinite time-out (i.e. no time-out). 1: TIME-OUT field present in READ request ZZ = "non-default terminator set" flag 0: use terminator set specified by previous read -- no terminator set specified and NON-DEFAULT-TERMINATOR-SET flag is TRUE 1: Use terminator set specified by this read 2: use universal termination set (i.e. all control characters except ^R, ^U, ^W, BS and HT) EE = "recognise input escape sequences" flag 0: parameter not present in READ request -- use characteristic 1: do not perform input escape sequence recognition for this read only Network Command Terminal Architectural Specification Page 61 2: for this read only, perform input escape sequence recognition MAX-LENGTH (2) : B = Input buffer length, in characters END-OF-DATA (2) : B = Character position of the character after the last character currently in the buffer TIMEOUT (2) : B = Interchatacter arrival time in seconds. A timeout break condition will occur if another character does not arrive within this time period. A value of 0 means take the characters currently in the Type-ahead Buffer and terminate the read immediately without waiting for further input. END-OF-PROMPT (2) : B = Character position of first character beyond the read-only (prompt) section of the buffer START-OF-DISPLAY(2) : B = Character position of the first character to be (re-)displayed. LOW-WATER (2) : B = Same field as in Read Data (below). (Generally set to END-OF-DATA on a Start Read, but does not have to be) TERMINATION-SET(I-32) : BM = The termination set for the read. The full 256-bit bit-mask is contained in 32 bytes. However, if there are trailing zero bytes in the 32 byte bit-mask (as will generally be the case), trailing zero bytes are not transmitted. This field is transmitted low-order byte to high-order byte. Within a byte, the bits are transmitted low-order bit to high-order bit. Therefore, for example, the character whose value is 65 is a terminator for this read only if the 2nd bit (bits numbered 1st to 8th) of the 9th byte (bytes numbered 1st to 32nd) is set. DATA : A = Input Buffer data Network Command Terminal Architectural Specification Page 62 4.16.4 Read Data (H <--- S) - the Server uses this message to transfer input data to the Host. | MSGTYPE FLAGS LOW-WATER VERTICAL-POSITION HORIZONTAL-POSITION TERMINATION-POSITION DATA MSGTYPE (1) : C = 3 FLAGS (1) : BM = Flags: ...T CCCC CCCC = completion code 0: termination character 1: valid escape sequence 2: invalid escape sequence 3: out-of-band character 4: input buffer full 5: timeout 6: unread 7: underflow 8: absentee token 9: vertical position change 10: line break 11: framing error 12: parity error 13: receiver over-run | | | NOTE | | The completion code | for an immediate timed | read (i.e. zero | timeout) will be | "timeout" only if no | other termination | condition (e.g. | "termination | character") is | encountered in | processing the | characters in the | type-ahead buffer. | | T = "more type-ahead data" flag 0: there is no data in the Type-ahead Buffer 1: there is data in the Type-ahead Buffer LOW-WATER (2) : B = Character position of the last character that has not been modified on this READ | VERTICAL-POSITION (1) : B = The relative vertical position change Network Command Terminal Architectural Specification Page 63 | (number of lines) on the presentation | device since the beginning of this read. | | HORIZONTAL-POSITION (1) : B = The relative horizontal position | change on the presentation device since | the beginning of this read. | | TERMINATION- | POSITION (2) : B = Number of DATA characters (excluding | terminators, escape sequences, etc.) in | the Input Buffer. Thus, when added to | the address of the head of the buffer, | it points to the character after the | last data character in the buffer; | thus, if there is a terminator or escape | sequence in the buffer, it points to the | terminator or the first character of the | escape sequence. DATA : A = Input Buffer data | | | NOTE | | The VERTICAL and HORIZONTAL-POSITION parameters are | undefined under the following circumstances: | 1. UNREAD received by Server | 2. READ with Escape Sequences imbedded in either PROMPT | or DATA fields | 3. Full Duplex Mode (i.e. unlocked Read Echos and | Writes are taking place simultaneously). | | | The Host resets its Cursor Position to 0,0 under the | following conditions: | 1. A READ is received and started by the Server | 2. A READ completes for any reason | 3. The Input Buffer is Redisplayed | | | 4.16.5 Out-of-Band (H <--- S) - contains an out-of-band character which has been received by the Server. MSGTYPE FLAGS CHARACTER MSGTYPE (1) : C = 4 | FLAGS (1) : BM = Flags: .... ...D | | D = discard control Network Command Terminal Architectural Specification Page 64 | 0: Do not alter output discard | state | 1: Set output discard state to | "discard" CHARACTER (1) : A = Out-of-band character received. 4.16.6 Unread (H ---> S) - requests the termination of the current read, if there is a read active. MSGTYPE FLAGS MSGTYPE (1) : C = 5 FLAGS (1) : BM = Flags: .... ...C C = unread condition 0: unconditional unread 1: only do unread if the Input and Type-ahead Buffers are empty 4.16.7 Clear Input (H ---> S) - requests clearing of the Type-ahead and Input Buffers. MSGTYPE FLAGS MSGTYPE (1) : C = 6 FLAGS (1) : C = 0 4.16.8 Write (H ---> S) - carries function request flags and, optionally, output data. MSGTYPE FLAGS PREFIX-VALUE POSTFIX-VALUE DATA MSGTYPE (1) : C = 7 | FLAGS (2) : BM = Flags: .... TSQQ PPEB DLUU UU = lock handling definition 0: unlock; default value for use if locking parameter not specified in WRITE request 1: lock before output; do not unlock after output Network Command Terminal Architectural Specification Page 65 2: lock before output and unlock after output 3: lock before output and unlock after output; redisplay after output | L = "newline" flag | 0: no special action | 1: at the end of the write, | output a line-feed and set an | internal "skip-line-feed" flag | so that if the first character | in the next write is a | line-feed, double spacing is | avoided D = "set output discard state" flag 0: do not modify output discard state 1: set output discard state to "do not discard" (before transmitting this data, if any) B = "beginning of message" flag 0: the data contained in this message is not the beginning of a host data message 1: the data contained in this message is the beginning of a host data message E = "end of message" flag 0: the data contained in this message is not the end of a host data message 1: the data contained in this message is the end of a host data message PP = prefix code 0: there is no prefix data; ignore the PREFIX-VALUE field 1: there is a "newline" count contained in the PREFIX-VALUE field 2: there is a prefix character contained in the PREFIX-VALUE field QQ = postfix code 0: there is no postfix data; ignore the POSTFIX-VALUE field 1: there is a "newline" count contained in the POSTFIX-VALUE Network Command Terminal Architectural Specification Page 66 field 2: there is a postfix character contained in the POSTFIX-VALUE field S = "completion status requested" flag 0: do not send a Write Completion message on completion of this request 1: send a Write Completion message on completion of this request T = "transparent" flag 0: no special action 1: data from this write message is written to Foundation Services using transparent write-characteristic PRE-FIX-VALUE (1) : B = 0, pre-fix newline count, or character, as defined by the PP flag POST-FIX-VALUE (1) : B = 0, post-fix newline count, or character, as defined by the QQ flag DATA : A = Output data. (This field may be absent.) 4.16.9 Write Completion (H <--- S) - carries write completion information. MSGTYPE FLAGS HORIZONTAL-POS VERTICAL-POS MSGTYPE (1) : C = 8 FLAGS (1) : BM = Flags: .... ...D D = discard status 0: no output lost due to output discard (control-O) by user 1: some output lost due to output discard (control-O) by user | HORIZONTAL-POS (2) : B = The relative horizontal position change | on the presentation device since the | beginning of this write. | | VERTICAL-POS (2) : B = The relative vertical position change | (number of lines) on the presentation | device since the beginning of this | write. Network Command Terminal Architectural Specification Page 67 | NOTE | | The VERTICAL and HORIZONTAL-POS parameters are undefined | under the following circumstances: | 1. WRITE with imbedded Escape Sequences | 2. Full Duplex Mode (i.e. unlocked Read Echos and | Writes are taking place simultaneously). | | | The Host resets its Cursor Position to 0,0 under the | following conditions: | 1. A READ is received and started by the Server | 2. A READ completes for any reason | 3. The Input Buffer is Redisplayed | | | 4.16.10 Discard State (H <--- S) - carries the output discard state most recently selected by the terminal user. MSGTYPE FLAGS MSGTYPE (1) : C = 9 FLAGS (1) : BM = Flags: .... ...D D = discard control 0: Output is to be discarded 1: Output is not to be discarded 4.16.11 Read Characteristics (H ---> S) - requests the current values of selected terminal characteristics to be returned to the Host. MSGTYPE FLAGS PARAMETER MSGTYPE (1) : C = 10 FLAGS (1) : C = 0 PARAMETER = This field may be repeated multiple times. This field contains a parameter set as two subfields as follows: SELECTOR CHARACTER where: Network Command Terminal Architectural Specification Page 68 SELECTOR(2) : BM = A characteristic selector (see the Terminal Characteristics subsection below). CHARACTER(1) : A = An subselector used only when the read characteristics is for the CHARACTER-ATTRIBUTES characteristic. This field is omitted if this is not for the CHARACTER-ATTRIBUTES characteristic. 4.16.12 Characteristics (H <--> S) - in the Host-to-Server direction, modifies specified terminal characteristics. In the Server-to-Host direction, contains the values of previously requested characteristics. MSGTYPE FLAGS PARAMETER MSGTYPE (1) : C = 11 FLAGS (1) : C = 0 PARAMETER = This field may be repeated multiple times. This field contains a parameter set as two subfields as follows: SELECTOR VALUE where: SELECTOR(2) : BM = A characteristic selector (see the Terminal Characteristics subsection below). VALUE : = Value field for characteristic (see the Terminal Characteristics subsection below for format of each characteristic) Network Command Terminal Architectural Specification Page 69 4.16.13 Check Input (H ---> S) - requests the count of characters in the Input and Type-ahead Buffers (combined) to be returned in an Input Count message. MSGTYPE FLAGS MSGTYPE (1) : C = 12 FLAGS (1) : C = 0 4.16.14 Input Count (H <--- S) - carries the count of characters in the Input and Type-ahead Buffers (combined); returned in response to a Check Input message. MSGTYPE FLAGS COUNT MSGTYPE (1) : C = 13 FLAGS (1) : C = 0 COUNT (2) : B = The requested input character count 4.16.15 Input State (H <--- S) - carries a change from zero to non-zero or vice versa in the count of characters in the Input and Type-ahead Buffers (combined). MSGTYPE FLAGS MSGTYPE (1) : C = 14 FLAGS (1) : BM = Flags: .... ...Z Z = count change flag 0: count became zero 1: count became non-zero | | | | | 4.16.16 Reserved for VMS -- see VMS Mini-Manual - | | MSGTYPE FLAGS | | MSGTYPE (1) : C = 15 | Network Command Terminal Architectural Specification Page 70 | 4.16.17 Reserved for VMS -- see VMS Mini-Manual - | | MSGTYPE FLAGS | | MSGTYPE (1) : C = 16 | | | | | 4.16.18 Reserved for VMS -- see VMS Mini-Manual - | | MSGTYPE FLAGS | | MSGTYPE (1) : C = 17 4.17 Selector Values For Characteristics Characteristics SELECTOR values are carried in Read Characteristics and Characteristics messages. A SELECTOR is a 16-bit value whose format is: | LLLLLLLL IIIIIIII LL: type of terminal characteristic identifier: 0: Foundation Physical Terminal Characteristic 1: Foundation Logical Terminal Characteristic 2: Network Command Terminal Logical Terminal Characteristic | 3-127: RESERVED for future expansion IIIIIIII: characteristic identifier (as defined in the table below for Command Terminal characteristics or in the Foundation Specification for the Foundation Characteristics). | Characteristic identifier types in the range 128 thru 255 are | reserved for implementors for "local" characteristics which exist | only within the Host or Server which implements them. This allows | inplementations to define "local" characteristics at will with some | reasonable guarantee that these "local" characteristics will | neither impact nor interfere with other TSA implementations. It is | a protocol error to receive a characteristic identifier in the | range 128-255 a remote implementation. Characteristics VALUEs are carried in Characteristics messages. The form of a VALUE depends on its type. The type of each characteristic is defined in the tables below. Types are Boolean, | Bit Map, Integer, String and Compound. The format of each type is defined below. Type Format Definition ---- ------ ---------- Network Command Terminal Architectural Specification Page 71 Boolean: BM(1) Low-order bit is the value (T = 1, F = 0) Bit Map: BM(x) x specified individually Integer: B(2) a 16-bit integer String: A(I-255) String of characters Compound: Compound characteristics value -- the value contains more than one field. The format of each compound characteristic value is defined in a subsection following the lists of characteristics below. 4.17.1 Foundation-maintained Characteristics - The following characteristics are maintained by the Foundation Services in the Server system. This is not a complete list of Foundation Characteristics, but, rather, a list of those Foundation Characteristics necessary for the correct operation of the Network Command Terminal. They may be read and, if enabled, written via the command terminal protocol. Refer to the Foundation Services specification for a definition of the meaning of characteristic values the Identifier values for these characteristics. Characteristic Type -------------- ---- MODE-WRITING-ALLOWED Boolean TERMINAL-ATTRIBUTES Bit Map BM(2) TERMINAL-TYPE String OUTPUT-FLOW-CONTROL Boolean OUTPUT-PAGE-STOP Boolean FLOW-CHARACTER-PASS-THROUGH Boolean INPUT-FLOW-CONTROL Boolean LOSS-NOTIFICATION Boolean LINE-WIDTH Integer PAGE-LENGTH Integer STOP-LENGTH Integer CR-FILL Integer Network Command Terminal Architectural Specification Page 72 LF-FILL Integer WRAP Integer HORIZONTAL-TAB Integer VERTICAL-TAB Integer FORM-FEED Integer INPUT-SPEED Integer OUTPUT-SPEED Integer CHARACTER-SIZE Integer PARITY-ENABLE Boolean PARITY-TYPE Integer MODEM-PRESENT Boolean AUTO-BAUD-DETECT Boolean MANAGEMENT-GUARANTEED Boolean SWITCH-CHARACTER-1 String SWITCH-CHARACTER-2 String | EIGHT-BIT Boolean | | TERM-MANAGEMENT-ENABLED Boolean 4.17.2 Handler-Maintained Characteristics - The following characteristics are maintained by the Network Command Terminal module the Server system. They may be read and written via the command terminal protocol. Characteristic Identifier Type -------------- ---------- ---- IGNORE-INPUT 1 Boolean CHARACTER-ATTRIBUTES 2 Compound CONTROL-O-PASS-THROUGH 3 Boolean RAISE-INPUT 4 Boolean NORMAL-ECHO 5 Boolean Network Command Terminal Architectural Specification Page 73 INPUT-ESCAPE-SEQUENCE- RECOGNITION-ENABLE 6 Boolean OUTPUT-ESCAPE-SEQUENCE- RECOGNITION-ENABLE 7 Boolean INPUT-COUNT-STATE 8 Integer AUTO-PROMPT 9 Boolean ERROR-PROCESSING 10 Bit Map BM(1) 4.17.2.1 CHARACTER-ATTRIBUTES Compound Characteristic - this is a fixed length characteristic whose format is CHARACTER MASK ATTRIBUTES where CHARACTER (1) : A = Character to which the following attributes apply. MASK (1) : BM = An 8-bit bit mask which is used to select bits in the following attributes field which are to be changed by this instance of the CHARACTER-ATTRIBUTES characteristic. Bits in the ATTRIBUTES field which are to retain their old value (to be left unchanged), should have the corresponding bits in the MASK field set zero; significant bits in the following ATTRIBUTES field should have the corresponding bits in the MASK field set one. ATTRIBUTES (1) : BM = Attribute-values: .FEE DIOO OO = Out-of-band handling 0: Not out-of-band character -- used to cancel any previous out-of-band definition (initial default for all characters is NOT out-of-band) 1: immediate clear (valid only for control characters) 2: deferred clear (valid only for control characters) 3: immediate hello I = include flag -- applies only when character is "immediate hello" 0: do not include character in Network Command Terminal Architectural Specification Page 74 input data stream (default) 1: include character in input data stream D = Out-of-band discard flag; whether a "clear" out-of-band character sets the output discard state to "discard" 0: do not alter output discard state (default) 1: set output discard state to "discard" EE = Control character echoing characteristic 0: don't echo the character 1: echo the character as itself 2: echo in standard form (initial default value for all control characters) where standard form is - CR echoes as CR,LF - LF echoes as CR,LF - ESC echoes as "$" (dollar sign) - All other characters echo as a "^" (up-arrow) followed by the printing character equal to <(VALUE+64) mod 128> (for example, VT echoes as ^K). 3: echo in standard form followed by echo as itself F = disable/enable special character function switch The special character function switch is used to enable or disable the special functions associated with certain well known control characters, i.e. OUTPUT-DISCARD (control-O), DELETE-CHARACTER (DEL), DELETE-WORD (control-W), CLEAR-INPUT (control-U), CLEAR-TYPE-AHEAD (control-X), REDISPLAY-INPUT (control-R), and QUOTE (control-V). 0: disable special function for character 1: enable special function for character (initial default value for control characters listed above) APPENDIX A INPUT EDITING ALGORITHMS A.1 INTRODUCTION This appendix contains model input editing algorithms for the Server module of the Network Command Terminal Software. These algorithms handle all local (where all editing is done in the Server) input editing functions and, in addition, the DELETE_CHAR and DELETE_WORD algorithms handle the Server part of the distributed input editing. A.2 DEFINITION LANGUAGE The algorithms in this appendix are specified in a sort of BLISS. The differences between the definition language and standard BLISS are listed below. For those who aren't familiar with BLISS, the English comments at the beginning of each procedure attempt to be complete. 1. Certain "obvious" operations the exact nature of which is implementation-dependent (for instance, the breaking down of Echo Set representation strings into individual characters) are sometimes specified in narrative form. 2. The FOR form is sometimes used in conjunction with narrative operations as a type of iteration. It is used to depict an undefined algorithm which returns a series of discrete values and after a while falls out of the loop at the bottom. A FOR expression never has a value. It is not considered a BLISS "loop", and therefore does not affect the scope of EXITLOOP. 3. The subroutine syntax used in the interface description in the body of this specification is also used here. That syntax is ROUTINE_NAME (input parameter, input parameter, ...; output parameter, output parameter, ... ). Output parameters are specified as addresses of values and not as BLISS output-registers; therefore, the subroutines may be transformed into standard BLISS by replacing the semicolon with a comma. If a status or return code is an output parameter, it is returned as the value of the subroutine. INPUT EDITING ALGORITHMS Page A-2 4. The separator-element in subroutine names in the Interfaces chapter and the narrative section on the Input Editing functions is a hyphen (-). This has been replaced by an underscore (_) in accordance with standard BLISS syntax. 5. All other non-standard constructions are defined via BLISS macros the first time they are used. A.3 BASE FUNCTIONS The following functions are used by the editing algorithms but are defined only externally in this Appendix: o PUT_ECHO (CHAR;HPOS,VPOS) -- Calls the Output Procedure with the specified character to be echoed. It returns the horizontal and vertical position this character will occupy on the display. This function cannot produce a resource failure; it does not return until it succeeds. o PUT_INPUT (CHAR) -- Appends the specified character to the Input Buffer. This function cannot produce a resource failure because: - The code which invokes the routine will not execute unless there is an input buffer available. - If this function fills the Input Buffer, the read is terminated and this input buffer will be unavailable before the next character is processed. o GET_INPUT (TYPE,POSITION; RETURN,CHAR) -- Gets a specified character from the Input Buffer, where: - TYPE is either "EDIT" or "ANY". If it is "EDIT", only editable characters (those past the prompt) will be returned. Otherwise, characters will be returned as described below. - POSITION is expressed in terms of characters from the end of the buffer, with 0 being the last character, 1 being the next-to-last, and so forth. - RETURN is the function status code. It may take the following values: . SUCCESS -- CHAR contains the character. . FAILURE -- POSITION does not point into the part of the Input Buffer currently being used. This return will be given if POSITION is negative or equal to or greater than the current length of the buffer. - CHAR is the returned character, if any. o DELETE_INPUT (NUM_CHARACTERS) -- Deletes the last NUM_CHARACTERS of the Input Buffer. This function has no return; if NUM_CHARACTERS is specified too large, only the editable part of the buffer will be INPUT EDITING ALGORITHMS Page A-3 deleted, while if it is negative, nothing will be deleted. A.4 DATA BASE VARIABLES The only common variables referred to by the algorithms below are the current horizontal and vertical positions, HPOS and VPOS, the horizontal position tracking ring (see next section), TAB_RING, the index into this ring buffer, INDEX, and the TERMINATE_FLAG which is set to tell the Input Process to terminate the current read. Note that HPOS and VPOS may not be equivalent to the actual current hardware cursor position; they are local to the Input Editing functions. A.5 TRACKING HORIZONTAL DISPLAY POSITION Horizontal position tracking employs a single tab stop ring buffer, TAB_RING, which maintains a count of the number of characters displayed past each tab stop on the current line. Each element of the ring will contain a number in the range 0 to 7 (tabs are at fixed positions eigth characters apart) so the ring elements can be as small as three bits each. With the aid of this ring, the input editing routines can correctly position the cursor on the screen when a tab is deleted. The buffer is circular (a ring) rather than a vector so it is never necessary to reset the pointer, INDEX, to the beginning -- this solves the problem with recognition where echoing doesn't always start from the beginning of the Input Buffer. This ring is only required for soft-copy terminals where deleted characters are blanked-out and the cursor backed-up one position; hard-copy terminals don't require this structure. A.6 OTHER THINGS OF INTEREST In the following algorithms, some operations on characters are described by reference to the "echo classes" to which the characters belong. These classes are distinguished by their effect on the horizontal and vertical position of output to the terminal display. The classes are: o SPACES -- these character increment the horizontal position by one. The characters with the following decimal values are spaces: 32-126. o NULLS -- these characters have no effect on either the horizontal or veritcal position. The characters with the following decimal values are nulls: 0-7, 14-31. o TAB -- this character sets the horizontal position to the least multiple of eight which is greater than or equal to the current horizontal position but less than the line width. The character with the following decimal value is a tab: 9. o OTHER -- these characters are the remaining characters not included in the above sets. Characters with the following decimal values are others: 8, 10-12, 13. INPUT EDITING ALGORITHMS Page A-4 The CLASS table is indexed by the value of a character, and contains the character's editing class, as defined above. The following symbols refer to a character's class or depict certain character values according to the context: o CR -- carriage return (character) o NUL -- null (character or class) o LF -- line feed (character) o TAB -- tab o SP -- blank (character) or space (class) o BS -- backspace (character) o BEL -- bell (character) o QUOTE -- value of the QUOTE characteristic, if quoting is enabled The following symbols refer to values of the TYPE parameter in the GET_INPUT function: o EDIT -- return only editable characters o ANY -- return read-only (prompt) characters as well A.7 ALGORITHMS The following subsections contain the input editing algorithms. The algorithms in each subsection are arranged in hierarchical order, with the lowest-level functions first. A.7.1 Routine ECHO (CHAR): Novalue = begin !+ ! ! This routine echos characters through the echo set, updates the ! TAB_RING for horizontal position tracking and, if the terminate ! on vertical change variable is TRUE (for distributed input editing) ! and the vertical position changes, the read termination flag is set ! TRUE to cause this read to be terminated. ! !- local THPOS, ! Temporary store for the old HPOS TVPOS; ! Temporary sTore for the old VPOS THPOS = .HPOS; ! Save initial Horizontal and vertical TVPOS = .VPOS; ! position For each ECHAR in CHAR's echo representation, from the first to the last, do PUT_ECHO(.ECHAR;HPOS,VPOS); ! Pass character to Output Procedure INPUT EDITING ALGORITHMS Page A-5 ! ! Update the horizontal position in the tab ring, TAB_RING. First update ! INDEX to point to the next ring entry if a tab stop has been crossed ! (17 is the number of entries a ring would require for a 132 character ! display line with tab stops 8 characters apart). ! Then enter the new horizontal position past the tab stop. ! if terminal is soft-copy then begin if .HPOS gtr .THPOS then INDEX = ((.TAB_RING[.INDEX] + .HPOS - .THPOS)/8 + .INDEX) mod 17; ! get ring indexs TAB_RING[.INDEX]=.HPOS MOD 8; ! load with number of characters past ! the current tab stop end; ! ! Set the TERMINATE_FLAG TRUE if the terminate on vertical change flag ! is set and there was a change in VPOS. ! if (.TVPOS neq .VPOS) and (terminate-on-vertical-change) then TERMINATE_FLAG = TRUE; end; A.7.2 Routine GOBACK (STYLE POS): novalue = !+ ! ! This routine traces back in the Input Buffer to find either the ! beginning of the buffer or the first editable character depending ! on whether the value of STYLE is ANY or EDIT respectively. ! POS returns the position in the Input Buffer of the first ! character found. ! !- Local ICHAR; ! Work variable for an Input Buffer character ! ! Scan back for the beginning of line ! .POS = (incr P from 0 do ! P is the position back from the ! current end of the Input Buffer if not GET_INPUT(.STYLE,.P;ICHAR) ! Exit from the loop and set POS then exitloop(.P); ! when beginning of buffer found end; INPUT EDITING ALGORITHMS Page A-6 A.7.3 Routine REDISPLAY_INPUT: Novalue = begin !+ ! ! This routine redisplays the Input Buffer at the start of the next ! line on the presentation device. Redisplaying is done through the ! Echo Set. The redisplay algorithm is the same for both hard-copy ! and soft-copy terminals. ! !- local ICHAR; ! Work variable ! ! Scan back to the beginning of line ! GOBACK(ANY;POS); ! Find start of current line ! ! Set the cursor position to the beginning of the next line in ! readiness for redisplaying the current line on the display. ! PUT_ECHO(CR;HPOS,VPOS); ! Start redisplay of Input Buffer PUT_ECHO(LF;HPOS,VPOS); ! on the next line ! ! Redisplay the characters from the Input Buffer ! decr P from .POS-1 to 0 do begin GET_INPUT(ANY,.P;ICHAR); ! Get character from Input Buffer | if GET_INPUT(EDIT,.P;dummy) ! Is it part of the prompt? | then ECHO(.ICHAR) ! No - echo translate | ! Yes - straight output | else PUT_ECHO(.ICHAR;HPOS,VPOS); end; end; A.7.3.1 routine INPUT_CHARACTER (CHAR): novalue = - begin !+ ! ! This routine handles the echoing of non-editing characters. ! It is included here for completness. The hard-copy character ! deletion function uses the /xxx/ figure to echo deleted ! characters. This routine supplies the final "/" of that ! figure. If the terminal is HARD-COPY and the previous INPUT EDITING ALGORITHMS Page A-7 ! function was DELETE-CHAR, the ending backslash is output first. ! !- if (terminal is HARD-COPY) and (last input was a DELETE-CHAR) then PUT_ECHO("\";HPOS,VPOS); ECHO(.CHAR); end; A.7.4 Routine DELETE_CHAR: Novalue = begin !+ ! ! This routine deletes the last character from the Input Buffer. In ! addition, it "unechoes" the character's echo representation (if any) ! from the display device. If the deleted character is preceded by a ! "quote" character, that character is also deleted from the display ! and Input Buffer. ! ! HARD-COPY ! ! If the last function processed was not another DELETE-CHARACTER ! or DELETE_WORD, echo a backslash ("\") followed by the echo ! representation of the character deleted from the Input Buffer; ! otherwise, just re-echo the deleted character. ! ! SOFT-COPY ! ! The "unechoing" of a character is driven not by the character but ! by its echo representation. Each character of the echo set ! is "unechoed" as follows provided the character is on the current ! line. All deletions around a line wrap are handled by redisplaying ! the contents of the Input Buffer on the next line of the display ! after removing the deleted character. ! ! SPACE If the horizontal position is not zero (HPOS neq 0), ! echo ,,. Otherwise, redisplay the ! Input Buffer after deleting the character from it. ! ! NULL Do nothing ! ! TAB If the horizontal position is zero (HPOS=0), ! redisplay the Input Buffer starting on the next line. ! Otherwise, use the tap stop ring, TAB_RING, to find the ! horizontal position of the display after deleting the TAB. ! The new horizontal position is the old position less the ! number spaces the TAB skipped; the number of spaces the TAB ! skipped is 8 minus the TAB_RING entry for the previous tab ! stop. ! INPUT EDITING ALGORITHMS Page A-8 ! OTHER For all other characters, redisplay the Input Buffer ! after deleting the character from it. ! ! This algorithm deals only with single line "unechoing"; if multiple ! lines on the display are involved in deleting the character or any ! complexity involved, this algorithm just rediplays the Input Buffer. ! !- local ICHAR, ! Character being deleted from Input Buffer INDEX, ! Work variable for index to TAB_RING CNT, ! Work variable for positions skipped by TAB QCHAR; ! Variable for storing possible quote ! character ! ! Attempt to get character to delete from Input Buffer; if the buffer is ! empty and either continuation read or terminate on underflow is TRUE, ! set the TERMINATE_FLAG so the DEL will be sent to the Host. ! If there is a character to delete, check if it is a "quoted" ! character and delete the QUOTE, too. ! if GET_INPUT(EDIT,0;ICHAR) then ! Don't get prompt characters begin DELETE_INPUT(1); ! Delete character from Input Buffer if GET_INPUT(EDIT,0;QCHAR) then if (.QCHAR eql QUOTE) then DELETE_INPUT(1); ! Delete QUOTE character,too ! ! HARD-COPY -- re-echo the character being deleted (preceded by a "\" ! if the previous input character wasn't a delete, too. ! If "quoted", echo quote, too. ! if (terminal is HARD-COPY) then begin if (last function wasn't DELETE-CHAR or DELETE-WORD) then PUT_ECHO("\";HPOS,VPOS);! Initiate \deleted characters\ figure ECHO(.ICHAR); ! Re-echo deleted character if ("quoted" character) then ECHO(QUOTE); ! ECHO Quote end ! ! SOFT-COPY -- process each character in the echo representation ! else for (each ECHAR in echo representation of character (and QUOTE if character quoted), from last to first) do selectone .CLASS[.ECHAR] of set [SP]: ! SPACE class character if .HPOS neq 0 then ! Not beginning of line INPUT EDITING ALGORITHMS Page A-9 begin PUT_ECHO(BS;HPOS,VPOS); ! Move back to deleted character PUT_ECHO(SP;HPOS,VPOS); ! Blank out deleted character PUT_ECHO(BS;HPOS,VPOS); ! Position on deleted character ! ! Adjust the ring buffer back one space ! if (.TAB_RING[.INDEX] eql 0) then if (.INDEX eql 0) then INDEX = 17 else INDEX = .INDEX - 1; else TAB_RING[.INDEX] = .TAB_RING[.INDEX] - 1; end ! ! This will only happen with local input editing as distributed input ! editing never has characters in the Input Buffer for more than one line ! on the presentation device. ! else ! Beginning of line being deleted begin REDISPLAY_INPUT; ! Redisplay Input Buffer exitloop; ! No need to finish for loop end; [TAB]: ! TAB character if .HPOS neq 0 then ! Not beginning of line begin if (INDEX = .INDEX - 1) lss 0 then INDEX = 17; ! Index to previous TAB_RING entry CNT=8-TAB_RING[.INDEX]; ! Get number of spaces to back over incr I from 1 to CNT do ! Backspace over the number of blanks PUT_ECHO(BS;HPOS,VPOS); ! the TAB skipped end; else ! Beginning of line being deleted begin REDISPLAY_INPUT; ! Redisplay Input Buffer exitloop; ! No need to finish for loop end; [NULL]: ! NULL class character NOP(); ! Do nothing [OTHERWISE]: ! For CR, LF, BS, and Quote ! ! If distributed input editing, the Host will handle these characters ! -- put the deleted character back in the Input Buffer, put the DEL ! in too, and terminate the read. ! begin if (terminate-on-vertical-change) then ! Distributed edit begin if ("quoted" character) then PUT_INPUT(QUOTE); ! If quoted, include QUOTE PUT_INPUT(ICHAR); ! Replace deleted character PUT_INPUT("DEL"); ! Delete character to Input Buffer TERMINATE_FLAG = TRUE; ! Terminate read INPUT EDITING ALGORITHMS Page A-10 end; else REDISPLAY_INPUT; ! Redisplay Input Buffer exitloop; ! No need to finish for loop end; tes; end; ! ! Empty Input Buffer. If this is a continuation-read or the user has ! specified termination on underflow, put a DEL in the Input Buffer and ! terminate the read. ! else if (continuation-read or terminate-on-underflow) then begin PUT_INPUT("DEL"); ! DEL to Input buffer TERMINATE_FLAG = TRUE; ! Terminate read end else if (BEL on underflow) then ! Ring bell if enabled for PUT_ECHO(BEL;HPOS,VPOS); ! underflow end; A.7.5 Routine DELETE_WORD: Novalue = begin !+ ! ! This routine deletes the "word" at the end of the Input Buffer. ! A "word" is defined as an alphanumeric string followed by a ! string of non-alphanumeric characters or end-of-buffer. A ! "word" is preceded by either a non-alphanumeric character or ! beginning-of-buffer. The effect of the DELETE_WORD function ! when applied to other than a "word", as defined above, is to ! delete all characters (except the prompt) from the Input Buffer. ! ! This algorithm scans back through the Input Buffer until it either ! finds there is no "word" at the end of the buffer or until it finds the ! number of characters in the "word" including the terminator. If there ! is no "word" at the end of the buffer, the count will be equal to the ! number of editable characters in the Input Buffer. DELETE_WORD ! then deletes this number of characters from the end of the Input Buffer ! using the DELETE_CHAR routine. Note, this means that characters will be ! "unechoed" identically when deleting either words or single characters. ! ! If the continuation-read flag is TRUE and a "word" or possible "word" ! terminator is at the beginning of the Input Buffer, the TERMINATE_FLAG ! is set so the delete will be handled by the Host as the first part ! of the "word" may be in the Host (a wrap terminated the previous read ! in the middle of a "word"). ! !- local CNT, ! Count for number of characters to delete INPUT EDITING ALGORITHMS Page A-11 KNT, ! Count of non-alphanumeric characters ICHAR; ! Work variable for Input Buffer character ! ! If the Input Buffer is empty, do nothing unless continuation-read ! or terminate-on-underflow is set in which case the control-W is put ! in the Input Buffer and the read terminated. If the Input Buffer is ! not empty, then scan back through the buffer to find the number of ! characters to be deleted. ! if GET_INPUT(EDIT,0;ICHAR) then ! If untrue, empty buffer begin KNT = 1; ! Initial count if .ICHAR neq alphanumeric then ! Count the number of begin ! non-alphanumerics KNT = (incr K from 1 do if not GET_INPUT(EDIT,.K;ICHAR) then exitloop(.P)! Empty else if ICHAR eql alphanumeric then exitloop(.P)) end; CNT=(incr P from KNT do if not GET_INPUT(EDIT,.P;ICHAR) then exitloop(.P) ! Buffer empty else if ICHAR neq alphanumeric then exitloop(.P);) ! Not in word if not continuation-read then incr P from 1 to .CNT DELETE_CHAR() ! Delete characters else if GET_INPUT(EDIT,.CNT;ICHAR) then ! Not start of buffer incr P from 1 to .CNT DELETE_CHAR() ! Delete characters else begin PUT_INPUT("control-W"); ! Control-W to user TERMINATE_FLAG = TRUE; ! Terminate read end; end ! ! Empty Input Buffer ! else if (continuation-read or terminate-on-underflow) then begin PUT_INPUT("control-W"); ! Control-W to user TERMINATE_FLAG = TRUE; ! Terminate read end else if (BEL on underflow) then ! Ring bell if enabled for PUT_ECHO(BEL;HPOS,VPOS); ! underflow end; A.7.6 Routine DELETE_INPUT: NOVALUE = begin !+ ! ! This routine deletes all editable characters (not the prompt) from INPUT EDITING ALGORITHMS Page A-12 ! the Input Buffer . After deleting the editable characters, it ! then redisplays the prompt (if any). ! !- local ICHAR, ! Work variable for character POS; ! Work variable for Input Buffer pointer ! ! If the Input Buffer is empty, do nothing. ! if GET_INPUT(EDIT,0;ICHAR) then begin ! ! Echo the delete character and advance the display to the next line. ! Delete the editable characters from the Input Buffer and then ! redisplay the prompt. ! ! ECHO(DELETE_CHARACTER); ! Echo ^U or whatever ! ! Get the range of characters to be deleted and delete them. ! GOBACK(EDIT;POS); ! Get range of characters to delete DELETE_INPUT(.POS); ! Delete them from Input Buffer REDISPLAY_INPUT(); ! Redisplay prompt end; end; APPENDIX B ESCAPE SEQUENCE RECOGNITION ALGORITHM The following description of an algorithm for recognizing escape sequences is provided for the convenience of implementors. Refer to the Video Systems Reference Manual for an exhaustive and definitive treatment of escape sequence parsing. (The Video Systems Reference Manual is an internal DIGITAL document in preparation by the Terminals and Workstations group.) The escape sequence recognizer can be described as a sequence of simple pattern matching rules. Each rule has an optional label, a match specification, and a label to branch to if the match is successful. Match specifications can be of two kinds: a quoted character, or a range of character codes, given as a pair of decimal numbers (minimum:maximum). Processing begins by applying the first rule to the first character after an ESC. If a match succeeds, the rule designated by the success branch is applied to the next character in the stream. If a match fails, the next rule in the sequence is applied to the same character. A special flag "*" as the success branch indicates that, if this match succeeds, the recognition of an escape sequence is complete; if the match fails, the characters examined are not part of any valid escape sequence. The comment included with a rule applies to the current character, or to the escape sequence being recognized, if the match succeeds. ESCAPE SEQUENCE RECOGNITION ALGORITHM Page B-2 Label Match Success Branch Comment ----- ----- -------------- ------- ";" 10 VT52 sequence "?" 10 " " "O" 20 " " "Y" 30 VT52 seq. (fixed length) "[" 15 ANSI control sequence 10 32:47 10 intermediate character 48:126 * final character 15 48:63 15 ANSI sequence parameter 20 32:47 20 intermediate character 64:126 * final character 30 32:126 40 fixed length VT52 seq. 40 32:126 * " "