Programmer's ROM - The Computer Language Library

home *** CD-ROM | disk | FTP | other *** search

/ Programmer's ROM - The Computer Language Library / programmersrom.iso / ada / virterm / vt2user.doc < prev

Wrap

Text File | 1988-05-03 | 124.9 KB | 2,955 lines

||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| USER MANUAL for an ANSI X3.64 Compatible Virtual Terminal in Ada Prepared for: ||||||||||||||||||||||||| ||||||||||||||||||||||||| NAVAL OCEAN SYSTEMS CENTER (NOSC) ||||||||||||||||||||||||| United States Navy ||||||||||||||||||||||||| San Diego, Ca 92152 ||||||||||||||||||||||||| ||||||||||||||||||||||||| Contract No. N66001-84-R-0030 ||||||||||||||||||||||||| Item No. 0028 ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| Equipment Group - ACSL ||||||||||||||||||||||||| P.O. Box 801, M.S. 8007 ||||||||||||||||||||||||| McKinney, TX 75069 ||||||||||||||||||||||||| 15-Mar-1985 ||||||||||||||||||||||||| ||||||||||||||||||||||||| TEXAS INSTRUMENTS INCORPORATED ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| CONTENTS CHAPTER 1 INTRODUCTION CHAPTER 2 SCROLL TERMINAL INTRODUCTION . . . . . . . . . . . . . . . . . . . 2-1 PROGRAM LEVEL INTERFACES . . . . . . . . . . . . . 2-1 Types . . . . . . . . . . . . . . . . . . . . . 2-3 Open . . . . . . . . . . . . . . . . . . . . . . 2-3 Close . . . . . . . . . . . . . . . . . . . . . 2-4 Set_position . . . . . . . . . . . . . . . . . . 2-4 Position . . . . . . . . . . . . . . . . . . . . 2-5 Size . . . . . . . . . . . . . . . . . . . . . . 2-5 Set_tab . . . . . . . . . . . . . . . . . . . . 2-5 Clear_tab . . . . . . . . . . . . . . . . . . . 2-5 Tab . . . . . . . . . . . . . . . . . . . . . . 2-5 New_line . . . . . . . . . . . . . . . . . . . . 2-6 New_page . . . . . . . . . . . . . . . . . . . . 2-6 Put (character) . . . . . . . . . . . . . . . . 2-6 Put (string) . . . . . . . . . . . . . . . . . . 2-6 Update_line . . . . . . . . . . . . . . . . . . 2-6 Get . . . . . . . . . . . . . . . . . . . . . . 2-7 Function_count . . . . . . . . . . . . . . . . . 2-8 Function_key . . . . . . . . . . . . . . . . . . 2-8 Function_key_name . . . . . . . . . . . . . . . 2-9 Exceptions . . . . . . . . . . . . . . . . . . 2-10 CHAPTER 3 PAGE TERMINAL INTRODUCTION . . . . . . . . . . . . . . . . . . . 3-1 PROGRAM LEVEL INTERFACES . . . . . . . . . . . . . 3-2 Types . . . . . . . . . . . . . . . . . . . . . 3-4 Open . . . . . . . . . . . . . . . . . . . . . . 3-4 Close . . . . . . . . . . . . . . . . . . . . . 3-5 Set_position . . . . . . . . . . . . . . . . . . 3-6 Position . . . . . . . . . . . . . . . . . . . . 3-6 Size . . . . . . . . . . . . . . . . . . . . . . 3-6 Delete_character . . . . . . . . . . . . . . . . 3-6 Delete_line . . . . . . . . . . . . . . . . . . 3-7 Erase_in_display . . . . . . . . . . . . . . . . 3-7 Erase_in_line . . . . . . . . . . . . . . . . . 3-7 Enter_insert_mode . . . . . . . . . . . . . . . 3-8 Exit_insert_mode . . . . . . . . . . . . . . . . 3-8 Insert_line . . . . . . . . . . . . . . . . . . 3-9 Select_graphic_rendition . . . . . . . . . . . . 3-9 Set_tab . . . . . . . . . . . . . . . . . . . . 3-9 Clear_tab . . . . . . . . . . . . . . . . . . 3-10 Tab . . . . . . . . . . . . . . . . . . . . . 3-10 Put (character/string) . . . . . . . . . . . . 3-10 Update_screen . . . . . . . . . . . . . . . . 3-10 Page 2 Update_line . . . . . . . . . . . . . . . . . 3-11 Update_cursor . . . . . . . . . . . . . . . . 3-11 Redraw_screen . . . . . . . . . . . . . . . . 3-11 Get . . . . . . . . . . . . . . . . . . . . . 3-11 Function_count . . . . . . . . . . . . . . . . 3-12 Function_key . . . . . . . . . . . . . . . . . 3-13 Function_key_name . . . . . . . . . . . . . . 3-14 Bell . . . . . . . . . . . . . . . . . . . . . 3-14 Exceptions . . . . . . . . . . . . . . . . . . 3-14 CHAPTER 4 FORM TERMINAL INTRODUCTION . . . . . . . . . . . . . . . . . . . 4-1 PROGRAM LEVEL INTERFACES . . . . . . . . . . . . . 4-2 Types . . . . . . . . . . . . . . . . . . . . . 4-3 Open . . . . . . . . . . . . . . . . . . . . . . 4-3 Close . . . . . . . . . . . . . . . . . . . . . 4-4 Set_position . . . . . . . . . . . . . . . . . . 4-4 Position . . . . . . . . . . . . . . . . . . . . 4-5 Size . . . . . . . . . . . . . . . . . . . . . . 4-5 Define_qualified_area . . . . . . . . . . . . . 4-5 Clear_qualified_area . . . . . . . . . . . . . . 4-6 Tab . . . . . . . . . . . . . . . . . . . . . . 4-6 Put (character And String) . . . . . . . . . . . 4-6 Get (character And String) . . . . . . . . . . . 4-6 Erase_area . . . . . . . . . . . . . . . . . . . 4-7 Erase_display . . . . . . . . . . . . . . . . . 4-7 Activate_form . . . . . . . . . . . . . . . . . 4-7 Is_form_updated . . . . . . . . . . . . . . . . 4-8 Termination_key . . . . . . . . . . . . . . . . 4-8 Exceptions . . . . . . . . . . . . . . . . . . . 4-8 APPENDIX A THE TERMINAL CAPABILITIES FILE INTRODUCTION . . . . . . . . . . . . . . . . . . . A-1 CAPABILITIES . . . . . . . . . . . . . . . . . . . A-1 Basic Capabilities . . . . . . . . . . . . . . . A-4 Cursor Addressing . . . . . . . . . . . . . . . A-5 Area Clears . . . . . . . . . . . . . . . . . . A-5 Insert/Delete Line . . . . . . . . . . . . . . . A-5 Insert/Delete Character . . . . . . . . . . . . A-6 Highlighting, Underlining, And Visible Bells . . A-6 Function Keys . . . . . . . . . . . . . . . . . A-6 Initialization . . . . . . . . . . . . . . . . . A-6 APPENDIX B PROGRAMMER'S NOTES COMPILING THE VIRTUAL TERMINAL . . . . . . . . . . B-1 REDISPLAY . . . . . . . . . . . . . . . . . . . . B-2 OTHER PACKAGES . . . . . . . . . . . . . . . . . . B-3 CHOOSING AN INTERFACE LEVEL . . . . . . . . . . . B-6 EFFICIENCY . . . . . . . . . . . . . . . . . . . . B-7 Page 3 SYSTEM DEPENDENCIES . . . . . . . . . . . . . . . B-7 APPENDIX C SAMPLE PROGRAMS CHAPTER 1 INTRODUCTION This virtual terminal provides a minimal set of control functions and procedures for manipulating asynchronous character-at-a-time ascii terminals. Such terminals include Televideo-970's (which we used for implementation), DEC VT-100's, DASHER terminals, Visual-50', etc. It does not support such terminals as IBM 3278 and other block oriented terminals. A tool or application writer can use this package with minimal knowledge of the terminal that his program is to write to, and achieve device independence and program clarity. Device independence is achieved by using a capabilities database called the Terminal Capabilities File (TCF). This terminal capabilities database is similar to the UNIX TERMCAP. Additional function key definitions and their labels have been added and the confusing assortment of control function definitions have been removed (for better or worse). The virtual terminal is 100% written in Ada. 99.9% should be completely transportable (it is ANSI standard Ada). The rest is isolated in the package SYSDEP. This should make it easy to modify and upgrade. The implementation has been performed on a Data General MV10000 in the Ada Development Environment. Comments on this environment can be found in Appendix B and in the document titled "A Virtual Terminal in Ada - Informal Technical Report" delivered as part of this contract. The virtual terminal consists of three seperate packages. Namely: * scroll_terminal * page_terminal * form_terminal These packages are described in detail later. The three packages stand alone when in use by the application programmer. That is, one simply has to WITH the appropriate package and begin using it. A compilation unit would look like this: INTRODUCTION Page 1-2 WITH page_terminal; PROCEDURE my_main IS BEGIN page_terminal.open; ... page_terminal.close; END my_main; PRAGMA main; Some sample programs are given in Appendix C. CHAPTER 2 SCROLL TERMINAL 2.1 INTRODUCTION This package provides a device-independent scroll-terminal interface to a user's program. A user's program can WITH this package to provide a device-independent terminal interface that is functionally equivalent to a scroll-terminal. This is the simplest form of terminal that this virtual terminal supports. This package should be chosen for any of the following reasons: 1. The user's terminal is primitive. Either it could be a CRT with little functionality, or a printing terminal. 2. The user wants maximum transportability. 3. The user does not need advanced capabilities for the application. 4. The user's appication may run over low speed communication lines, making the page and form mode unacceptable. 2.2 PROGRAM LEVEL INTERFACES The source code for the spec is as follows: PACKAGE scroll_terminal IS TYPE function_key_enum IS ( up_arrow, down_arrow, left_arrow, right_arrow, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12, f13, f14, f15, f16, f17, f18, f19, f20, f21, f22, f23, f24, f25, f26, f27, f28, f29, f30, f31, f32 ); TYPE function_key_descriptor( length : positive := 32) IS PRIVATE; PROCEDURE open (name : IN string := "none" ); SCROLL TERMINAL Page 2-2 PROCEDURE close; PROCEDURE set_position (position : IN positive); FUNCTION position RETURN positive; FUNCTION size RETURN positive; PROCEDURE set_tab; PROCEDURE clear_tab; PROCEDURE tab (count : IN positive := 1); PROCEDURE new_line (count : IN positive := 1); PROCEDURE new_page (count : IN positive := 1); PROCEDURE put (item : IN character); PROCEDURE put (item : IN string); PROCEDURE update_line; PROCEDURE get( data : OUT string; last : OUT natural; keys : OUT function_key_descriptor; timeout : IN duration := duration'last ); FUNCTION function_count(keys : IN function_key_descriptor) RETURN natural; PROCEDURE function_key(keys: IN function_key_descriptor; index : IN positive; key_identifier : OUT function_key_enum; previous_position : OUT natural); PROCEDURE function_key_name ( key_identifier : IN function_key_enum; key_name : OUT string; last : OUT natural); PROCEDURE bell; uninitialized : EXCEPTION; tcf_error : EXCEPTION; terminal_too_primitive : EXCEPTION; unsupported_terminal : EXCEPTION; invalid_function_key : EXCEPTION; PRIVATE TYPE keystroke_record IS RECORD key : function_key_enum; position : positive; SCROLL TERMINAL Page 2-3 END RECORD; TYPE function_key_array IS ARRAY( positive RANGE <> ) OF keystroke_record; TYPE function_key_descriptor( length : positive := 32 ) IS RECORD no_of_keys : natural := 0; keys : function_key_array( 1..length ); END RECORD; END scroll_terminal; 2.2.1 Types The following types are defined here: * function_key_enum - this enumerates all of the function keys that can be referenced in the virtual terminal. Four arrow keys and 32 function keys are supported in this virtual terminal. These values can be used to reference function keys in the procedures function_key and function_key_name described later. * function_key_descriptor - a private type used to identify the function keys that were returned from a call on get. 2.2.2 Open Scroll_terminal.open is called to open the scroll terminal. Scroll_terminal.open must be the first procedure called in the virtual terminal package. A call on any other procedure or function before calling open will result in the exception scroll_terminal.uninitialized being raised. The single string parameter "name" is the name of the terminal if it is known by the programmer. If open is called with no parameter then "none" is used as the default. In this case the virtual terminal will look for a file name "TERM" on your path, open it, and read the first line. This string will be used as the terminal name. The format of the string must match exactly (even in case) the terminal name field in the terminal capabilities file. Please refer to Appendix A for a discussion of the TCF. Due to a bug in the Data General ADE you MUST put a second line in the TERM file. The contents of the second line are not used. An example TERM file: tv970 this line overcomes the END_ERROR problem of the ADE The exceptions that can be raised from a call on open are: SCROLL TERMINAL Page 2-4 * tcf_error - an error occured when reading and/or processing the terminal capabilities file. Some possible causes are: - the TCF file is not on your path. - the format of the TCF file is incorrect. - the TCF file is opened for exclusive access by someone else. - a system error occured. * unsupported_terminal - this terminal is unsupported. This could be caused by one of the following: - There is no TERM file on your path. - The TERM file could not be opened. - The TCF file had no entry for this terminal. 2.2.3 Close Scroll_terminal.close is called to close the scroll terminal. It must be the last procedure called. Any procedure or function called after this one will raise the exception unitialized. If scroll_terminal.close is called and the scroll terminal is already closed, nothing happens. 2.2.4 Set_position Scroll_terminal.set_position allows the user's program to move the current position randomly about within the current line. It does not affect the actual terminal's line. If scroll_terminal.update_line is called from the user's program then set_position will not allow the active position to move backward past the position that was active at the time that update_line was called. If an attempt is made to move backward past the old active position, then the active position will be moved only to position corresponding to the old active position. As an example consider the following: ... -- assume the user has opened the scroll_terminal previously virtual_terminal.scroll_terminal.put( "My_prompt>" ); virtual_terminal.scroll_terminal.update_line; virtual_terminal.scroll_terminal.set_position( 1 ); The last statement would move the active position to position number eleven (the character count of "My_prompt>" plus 1) in the current line (immediately after the string "My_prompt>"). SCROLL TERMINAL Page 2-5 If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.5 Position Scroll_terminal.position returns a value of type positive that is the current active position on the scroll terminal's line. This position is the place where further output will be directed. It should be noted that this does not necessarily correspond to where the actual terminal's cursor is located unless executed after scroll_terminal.update_line procedure is called and before scroll_terminal.put or scroll_terminal.tab is called again. If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.6 Size Scroll_terminal.size returns a value of type positive which is the length of the scroll terminal's line. This value is extracted from the terminal capabilities file and may or may not reflect the actual terminal's line length. If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.7 Set_tab Scroll_terminal.set_tab will set a horizontal tab at the active position. This tab will stay in place even after update or new_line have been called. If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.8 Clear_tab Scroll_terminal.clear_tab will remove the tab stop at the location of the active position. This clears the tab completely and it will remain gone after an update or new_line has been called. If there was no tab stop set at the active position then no operation will be performed. If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.9 Tab Scroll_terminal.tab will move the active position to the specified horizontal tab stop counting upward from the next tab stop. If there are no further tab stops on the line then no operation will occur. If there are no tab stops set on the line, then no operation will occur. If the scroll terminal has not been opened previously to this then SCROLL TERMINAL Page 2-6 the exception scroll_terminal.uninitialized will be raised. 2.2.10 New_line Scroll_terminal.new_line will move the active position to the beginning of the next line. This process performs an implicit call on update and clears the internal buffer. The tab stops active on the previous line remain in effect. If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.11 New_page Scroll_terminal.new_page causes a form feed character to be output to the terminal. An implicit call to update is performed then the new page operation is performed. If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.12 Put (character) When scroll_terminal.put is called the data is placed into the current line at the active position. The active position is advanced past the character that was placed into the line. The data is lost if the active position moves past the length of the line. Also, the active position is left pointing at the last character on the line if this occurs. If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.13 Put (string) When scroll_terminal.put is called the data is placed into the current line at the active position. The active position is advanced past the last character of the data that was placed into the line. The data is lost if the active position moves past the length of the line. Also, the active position is left pointing at the last character on the line if this occurs. If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.14 Update_line This procedure is called to force the internal representation of the line out to the actual terminal display. It is important to realize that the operations: * set_position SCROLL TERMINAL Page 2-7 * set_tab * clear_tab * tab * put perform there operations on a virtual representation of the terminal and not directly on the terminal itself. Scroll_terminal.update_line is called to force the internal representation to the actual terminal display. Refer to set_position and put for restrictions imposed by update_line. If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.15 Get When scroll_terminal.get is called the keys that the user struck at the actual terminal keyboard since the virtual terminal was opened, or since the last call to scroll_terminal.get are returned. A string parameter named data returns the string that the user typed. Function/arrow keys that were typed are not embedded in this string, they are identified seperately. The last position of the string is returned in the parameter last of type natural. A timeout can be specified of type duration. This allows the get to eventually timeout and return. A default for this parameter is specified as duration'last which is a system dependent value. Hopefully it is large enough to effectively mean infinitely. The function/arrow keys are identified by the paramter keys of private limited type function_key_descriptor. Three cases are important: 1. get returns with the parameter last equal to zero, and there were no function/arrow keys pressed. This means that no keys were typed since the last call on get or since the virtual terminal was called. 2. get returns with the parameter last equal to zero, and there were function/arrow keys pressed. This means that only function/arrow keys were pressed since the last call on get or since the virtual terminal was initialized. 3. get returns with the parameter last not equal to zero and there were function/arrow keys pressed. Here both function/arrow keys and regular keys were pressed. As an example, consider the case where a user opens the virtual terminal then presses three keys. First an (say) "a" is pressed, then a function key (say "F1" on some terminal), and finally a (say) "b" is pressed. The string parameter data would have length SCROLL TERMINAL Page 2-8 2 and contain the characters "a" and "b" as its values. The keys parameter could then be used to get the function key that was pressed ("F1") by making a call on function_count to get the number of function keys that were pressed (this would return a 1). Then a call on function_key passing in the keys parameter obtained from the call on get with the index set to 1 (the first key struck) will return a key_identifier which is an enumeration of the function key pressed (in this case an f1) and the previous_position in the string that was returned from the call on get (in this case it would return a 2). On the Data General ADE two items are noted: 1. the timeout parameter has no effect. 2. characters are returned one at a time. DG-AOS/VS has no facility for clearing the typeahead buffer. This will be fixed in later releases of the AOS. 2.2.16 Function_count A value is returned of type natural that identifies the number of function/arrow keys that were typed since the last call on scroll_terminal.get. There is a 20 key limit on the number of function/arrow keys that can be buffered. If the number returned is zero then no function/arrow keys were typed since the last call on scroll_terminal.get. The single input parameter keys is the limited private type returned from the call on scroll_terminal.get. This identifies the specific list of function/arrow keys that will be operated on by this function. If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.17 Function_key As described in the procedure scroll_terminal.get, this procedure returns a key_identifier that has a value of type function_key_enum identifying the function/arrow key that corresponds to the index parameter in the list of function keys identified by the keys parameter. This procedure is called repeatedly to process the function/arrow keys varying index (usually in ascending numerical order). The parameters are: * keys - the value of the private limited type function_key_descriptor that was returned from a call on scroll_terminal.get. This is a user variable. A user may have more than one of these variables, and consequently, identify more than one list of function/arrow keys. SCROLL TERMINAL Page 2-9 * index - the number of the function/arrow key in the list of function/arrow keys identified by the parameter keys, that the user is interested in. * key_identifier - returns an enumerated type which identifies the function/arrow key as described in the terminal capabilities file. * previous_position - a position in the string that was returned from a call on scroll_terminal.get. This position is the one immediately before the function/arrow key was pressed. Three cases are important: - the function/arrow key was pressed before any of the other keys. In this case previous_position would return a zero. - the functon key was the last key pressed. In this case the value returned would be the same as last. - the function/arrow key was pressed in the middle of the string. In this case the character position before the function/arrow key would be returned. An example. Consider the case where a character "a" was pressed, then function key "F9" (as defined in the terminal capabilities file), then the key "b". scroll_terminal.get would return data = "ab" last = 2 a reference to keys When scroll_terminal.function_key is called and passed the reference to keys and the index = 1, then key_identifier would return f9 and previous_position would return 1. If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.18 Function_key_name This procedure returns a string that is the name of the function key. This information is extracted from the terminal capabilities database when the virtual terminal is opened and stored in the tcf package data structures. The parameters are: * key_identifier - a value of enumerated type function_key_enum which identifies the function key of interest. * key_name - a string which is the function key name as it appears in the terminal capabilities file (exactly). SCROLL TERMINAL Page 2-10 * last - a natural number which is the last character position in the key_name. This version of the terminal capabilities file limits the number of function keys to 32 (plus the four arrow keys). If the scroll terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 2.2.19 Exceptions The following exceptions are defined in the scroll_terminal package: * uninitialized - raised when any procedure or function is called prior to calling scroll_terminal.open (or after calling scroll_terminal.close and prior to calling scroll_terminal.open again). * tcf_error - raised when an error occured when reading and/or processing the terminal capabilities file. Some possible causes are: - the TCF file is not on your path. - the format of the TCF file is incorrect. - the TCF file is opened for exclusive access by someone else. - a system error occured. * terminal_too_primitive - raised when your terminal does not have the needed functionality to support this terminal type (this one should never be raised in scroll_terminal operations). * unsupported_terminal - this terminal is unsupported. This could be caused by one of the following: - There is no TERM file on your path. - The TERM file could not be opened. - The TCF file had no entry for this terminal. CHAPTER 3 PAGE TERMINAL 3.1 INTRODUCTION This package provides a device-independent page-terminal interface to a user's program. A user's program can "WITH" this package to provide a device-independent terminal interface that is functionally equivalent to a page-terminal. This is the most advanced form of terminal that this virtual terminal supports. This package should be chosen for any of the following reasons: 1. The user's terminal has advanced features. The terminal is directly addressable, with erase to end of line, and erase to end of screen capabilities. 2. The user wants advanced capabilities and is willing to sacrifice some transportability. The screen is addressed as follows (column, row): (1,1) (page_terminal.size.column, 1) ____________________________________________________ | | | | | | | | | | | | | | | | | | | | | | | | | ___________________________________________________| (1,page_terminal.size.line) (page_terminal.size.column, page_terminal.size.line ) where the size is a function call returning an xy_position record PAGE TERMINAL Page 3-2 containing a line and column number. These values are obtained from the terminal capabilities file. 3.2 PROGRAM LEVEL INTERFACES The source code for the spec is as follows: PACKAGE page_terminal IS TYPE function_key_enum IS ( up_arrow, down_arrow, left_arrow, right_arrow, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12, f13, f14, f15, f16, f17, f18, f19, f20, f21, f22, f23, f24, f25, f26, f27, f28, f29, f30, f31, f32 ); TYPE function_key_descriptor( length : positive := 32) IS PRIVATE; TYPE xy_position IS RECORD line : positive; column : positive; END RECORD; TYPE select_enumeration IS (from_xy_position_to_end, from_start_to_xy_position, all_positions); TYPE graphic_rendition_enumeration IS (primary_rendition, reverse_image, no_image ); PROCEDURE open (name : IN string := "none" ); PROCEDURE close; PROCEDURE set_position (position : IN xy_position); FUNCTION position RETURN xy_position; FUNCTION size RETURN xy_position; PROCEDURE delete_character (count : IN positive := 1); PROCEDURE delete_line (count : IN positive := 1); PROCEDURE erase_in_display (selection : select_enumeration); PROCEDURE erase_in_line (selection : select_enumeration); PROCEDURE enter_insert_mode; PROCEDURE exit_insert_mode; PROCEDURE insert_line (count : IN positive := 1); PAGE TERMINAL Page 3-3 PROCEDURE select_graphic_rendition (selection : IN graphic_rendition_enumeration); PROCEDURE set_tab; PROCEDURE clear_tab; PROCEDURE tab (count : IN positive := 1); PROCEDURE put (item : IN character); PROCEDURE put (item : IN string); PROCEDURE update_screen ( top_line : IN positive; bottom_line : IN positive ); PROCEDURE update_line( the_line : IN positive ); PROCEDURE update_cursor; PROCEDURE redraw_screen; PROCEDURE get( data : OUT string; last : OUT natural; keys : OUT function_key_descriptor; timeout : IN duration := duration'last ); FUNCTION function_count(keys : IN function_key_descriptor) RETURN natural; PROCEDURE function_key(keys: IN function_key_descriptor; index : IN positive; key_identifier : OUT function_key_enum; previous_position : OUT natural); PROCEDURE function_key_name ( key_identifier : IN function_key_enum; key_name : OUT string; last : OUT natural); PROCEDURE bell; uninitialized : EXCEPTION; tcf_error : EXCEPTION; terminal_too_primitive : EXCEPTION; unsupported_terminal : EXCEPTION; invalid_function_key : EXCEPTION; PRIVATE TYPE keystroke_record IS RECORD key : function_key_enum; position : positive; END RECORD; PAGE TERMINAL Page 3-4 TYPE function_key_array IS ARRAY( positive RANGE <> ) OF keystroke_record; TYPE function_key_descriptor( length : positive := 32 ) IS RECORD no_of_keys : natural := 0; keys : function_key_array( 1..length ); END RECORD; END page_terminal; 3.2.1 Types The following types are defined in the page_terminal: * function_key_enum - an enumerated type defines the 4 arrow keys and 32 function keys. * function_key_descriptor - a limited private type. This type is used to traverse the function key list whose reference is returned from a call to page_terminal.get (see below). The user must define a variable of this type (or more than one) in order to use the function key procedures and functions. * xy_position - a record with a line component and a column component. Each of these is of type positive. This type identifies a position on the display. * select_enumeration - an enumerated type that identifies the range that a delete operation will affect. * graphic_rendition - an enumerated type that identifies a graphic rendition (either primary, reverse, or none) that a single position in the virtual display will have. The enumerated type function_key_enum identifies the function/arrow keys that are used in the function/arrow key handling procedures and functions. 3.2.2 Open Page_terminal.open is called to open the page terminal. Page_terminal.open must be the first procedure called in the virtual terminal package. A call on any other procedure or function before calling open will result in the exception page_terminal.uninitialized being raised. The single string parameter "name" is the name of the terminal if it is known by the programmer. If open is called with no parameter then "none" is used as the default. In this case the virtual terminal will look for a file name "TERM" on your path, open it, and read the first line. This string will be used as the terminal name. The format of the string must match exactly (even in case) the terminal name field in the terminal capabilities file. Please refer to Appendix PAGE TERMINAL Page 3-5 A for a discussion of the TCF. Due to a bug in the Data General ADE you MUST put a second line in the TERM file. The contents of the second line are not used. An example TERM file: tv970 this line overcomes the END_ERROR problem of the ADE The exceptions that can be raised from a call on open are: * tcf_error - an error occured when reading and/or processing the terminal capabilities file. Some possible causes are: - the TCF file is not on your path. - the format of the TCF file is incorrect. - the TCF file is opened for exclusive access by someone else. - a system error occured. * unsupported_terminal - this terminal is unsupported. This could be caused by one of the following: - There is no TERM file on your path. - The TERM file could not be opened. - The TCF file had no entry for this terminal. * terminal_too_primitive - raised if your terminal is considered too primitive to be a page terminal. Your terminal MUST support: - erase to end of screen - erase to end of line - move the cursor 3.2.3 Close Page_terminal.close is called to close the page terminal. It must be the last procedure called. Any procedure or function called after this one will raise the exception unitialized. If page_terminal.close is called and the page terminal is already closed, nothing happens. PAGE TERMINAL Page 3-6 3.2.4 Set_position Page_terminal.set_position will move the active position in the virtual terminal display to the new coordinates given in the parameter list. A call on this procedure does not affect the actual terminal's display, only the virtual representation of the display. This procedure has one parameter, position, which identifies the line and column that the active position should be moved to. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.5 Position Page_terminal.position returns a line/column pair of type xy_position that identifies where the active position is located in the virtual terminal. It should be noted that this is NOT where the cursor is located on the actual terminal's screen. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.6 Size Page_terminal.size returns the number of columns and number of lines contained in the actual display. This information is located in the terminal capabilities file and can be set and altered by the user. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.7 Delete_character Page_terminal.delete_character will delete the number of characters specified in the input parameter from the virtual display. The characters that are deleted include the character that the active position is on and all characters to the right for up to the parameter count. Characters to the right of the deleted characters that are on the same line are moved to the left to fill the space of the deleted characters. If more characters are specified than character positions left on the line, then only those characters left on the line will be deleted. The number of characters to be deleted is specified in the input parameter count. Count defaults to one character. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. PAGE TERMINAL Page 3-7 3.2.8 Delete_line Page_terminal.delete_line will delete the number of lines specified in the input parameter from the virtual display starting at the active position and proceding downward. A call on this procedure will not affect the actual display, only the virtual representation of the display. The lines below the line containing the active position will move upward to fill the space deleted. If the number of lines specified in the input parameter is more than the number of lines left on the display then only those lines left on the display will be deleted. If the active position is located in the middle of the line, then after the delete the active position will be left at the left margin of the virtual display on the line that moved up to replace the deleted lines. The input parameter count contains the number of lines that will be deleted. The default is 1. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.9 Erase_in_display Page_terminal.erase_in_display is called to erase areas in the virtual display. The areas that can be erased are: 1. entire display, 2. from current position to end of display, 3. from beginning of display to active position. Again, remeber, this procedure only affects the virtual representation of the display not the actual display. If the active position is at the end of the virtual display and a call is made to erase to end of display, no operation will occur. If the active position is at the beginning of the display and a call is made to erase from beginning of the display to the active position, no operation will occur. The single input parameter selection of type select_enum is used to select which of the three types of erase (listed above) are used. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.10 Erase_in_line Page_terminal.erase_in_line causes areas in the line containing the active position to be erased. This erase operation can take three forms: PAGE TERMINAL Page 3-8 1. erase the entire line, 2. erase from the active position to the end of the line, 3. erase from the beginning of the line to the active position. The erase operation leaves the active position where it was located before the erase operation was called. It effective causes the correct amount of blanks to be written to the screen to erase the area requested. If the active position is at the beginning of the line and the area requested was from the beginning of the line to the active position, then no operation will occur. If the active position was at the end of the line and the area requested was from the active position to the end of the line then no operation will occur. If erase entire line is selected the cursor will remain where it was before the operation occured and the line will be erased. The single input parameter selection of type select_enum is used to select which of the three types of erase (listed above) are used. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.11 Enter_insert_mode Page_terminal.enter_insert_mode causes characters entered to push the characters that follow on the line containing the active position to the right. For example, if a line contains: a b c d | active position located here A call on page_terminal.enter_insert_mode followed by a call on page_terminal.put (say the string was "test" would cause the line to look like: a b t e s t c d | active position now here If the inserting of characters pushes characters off the end of the line, then those characters pushed off the end are lost. If insert mode was already in effect then no operation will occur. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.12 Exit_insert_mode Page_terminal.exit_insert_mode is called to exit insert character mode. Calls to page_terminal.put will replace the existing characters at the active position on the virtual display after page_terminal.exit_insert_mode is called. If insert mode is not on (a previous call to page_terminal.enter_insert-mode was made) PAGE TERMINAL Page 3-9 no operation will occur. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.13 Insert_line Page_terminal.insert_line will insert blank lines onto the virtual display. The number of blank lines is specified in the input parameter. The lines below and including the line containing the active position are pushed downward in the virtual display. The active position is moved to the beginning of the blank line corresponding to the line containing the active position before the call on page_terminal.insert_line was made. Lines that are pushed off the end of the virtual display are lost. One input parameter count, of type positive identifies the number of blank lines that are to be inserted. The default is one. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.14 Select_graphic_rendition Page_terminal.select_graphic_rendition sets the graphic rendition to that specified by the input parameter. The choices are: 1. primary_rendition - display according to the ANSI standard ASCII codes, 2. reverse_image - This can be configured via the terminal capabilities file to be anything that the terminal can support and the user desires. Typically it means black on white (when the default is white on black). 3. no rendition - all following characters will be represented as blanks (have no visible representation on the screen). If the selected rendition is currently in effect no operation will ocurr. The single input parameter selection of type graphic_rendition_enumeration specified what the rendition will be. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.15 Set_tab Page_terminal.set_tab will set a horizontal tab at the active position. This tab will affect all lines on the virtual display regardless of the line position of the active position. In other words, only the column of the active position is used and it spans all lines on the virtual display. If there is already a tab stop PAGE TERMINAL Page 3-10 at the active position's column then no operation will occur. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.16 Clear_tab Page_terminal.clear_tab will clear a horizontal tab at the active position. This clear will affect all lines on the virtual display regardless of the line position of the active position. In other words, only the column of the active position is used and it spans all lines on the virtual display. If there is no tab stop at the active position's column then no operation will occur. 3.2.17 Tab Page_terminal.tab moves the active position to a tab stop based on the input parameter. Tabs will be counted from the next tab (to the right) on the same line as the active positon moving right through the line. If there are no tab stops set, then no operation will occur. If there are not enough tab stops on the rest of the line to fulfill the requested number to move, then the cursor will be moved to the last tab stop on the line. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.18 Put (character/string) Two versions of page_terminal.put exist: 1. put a string to the virtual display, and, 2. put a character to the display. These work equivalently. They place characters into the virtual display at the active position moving the active position to the character following the inserted string or character. If the characters placed on the display extend past the end of the line then the characters will be lost. Page_terminal.put is affected by calls on page_terminal.enter_insert_mode and page_terminal.exit_insert_mode. The single input parameter item of type character or string is the character(s) to be placed onto the virtual display. These characters should only be printable ASCII characters. Others will be removed. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.19 Update_screen Page_terminal.update_screen makes the physical screen look like the internal representation of the virtual screen. What this PAGE TERMINAL Page 3-11 really means is that you can make as many calls on * put * insert_line, delete_line * insert_character, delete_character and nothing will be seen on your physical terminal until update_screen is called. At that point a heuristic algortihm determines a minimum distance between the virtual and physical displays and changes the physical display. You must specify the top and bottom line that the update operation will operate on. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.20 Update_line Same as update_screen but operates on only the given line. 3.2.21 Update_cursor Page_terminal.update_cursor is called to make the cursor on the physical display be located at the same position as on the virtual display. This one is called when you want just to move the cursor around without incurring the overhead of updating (which would do the same thing at an exorbitant cost). If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.22 Redraw_screen Page_terminal.redraw_screen does just that, it redraws the physical screen making it look like the virtual screen. This is called to repaint the screen when something unusual happens, like a broadcast message from someone, or mail has been received and your screen has been changed. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.23 Get When page_terminal.get is called the keys that the user struck at the actual terminal keyboard since the virtual terminal was opened, or since the last call to page_terminal.get are returned. A string parameter named data returns the string that the user typed. Function/arrow keys that were typed are not embedded in this string, they are identified seperately. The last position of the string is returned in the parameter last of type natural. A PAGE TERMINAL Page 3-12 timeout can be specified of type duration. This allows the get to eventually timeout and return. A default for this parameter is specified as duration'last which is a system dependent value. Hopefully it is large enough to effectively mean infinitely. The function/arrow keys are identified by the paramter keys of private limited type function_key_descriptor. Three cases are important: 1. get returns with the parameter last equal to zero, and there were no function/arrow keys pressed. This means that no keys were typed since the last call on get or since the virtual terminal was called. 2. get returns with the parameter last equal to zero, and there were function/arrow keys pressed. This means that only function/arrow keys were pressed since the last call on get or since the virtual terminal was initialized. 3. get returns with the parameter last not equal to zero and there were function/arrow keys pressed. Here both function/arrow keys and regular keys were pressed. As an example, consider the case where a user opens the virtual terminal then presses three keys. First an (say) "a" is pressed, then a function key (say "F1" on some terminal), and finally a (say) "b" is pressed. The string parameter data would have length 2 and contain the characters "a" and "b" as its values. The keys parameter could then be used to get the function key that was pressed ("F1") by making a call on function_count to get the number of function keys that were pressed (this would return a 1). Then a call on function_key passing in the keys parameter obtained from the call on get with the index set to 1 (the first key struck) will return a key_identifier which is an enumeration of the function key pressed (in this case an f1) and the previous_position in the string that was returned from the call on get (in this case it would return a 2). On the Data General ADE two items are noted: 1. the timeout parameter has no effect. 2. characters are returned one at a time. DG-AOS/VS has no facility for clearing the typeahead buffer. This will be fixed in later releases of the AOS. 3.2.24 Function_count A value is returned of type natural that identifies the number of function/arrow keys that were typed since the last call on page_terminal.get. There is a 20 key limit on the number of function/arrow keys that can be buffered. If the number returned is zero then no function/arrow keys were typed since the last call on page_terminal.get. PAGE TERMINAL Page 3-13 The single input parameter keys is the limited private type returned from the call on page_terminal.get. This identifies the specific list of function/arrow keys that will be operated on by this function. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.25 Function_key As described in the procedure page_terminal.get, this procedure returns a key_identifier that has a value of type function_key_enum identifying the function/arrow key that corresponds to the index parameter in the list of function keys identified by the keys parameter. This procedure is called repeatedly to process the function/arrow keys varying index (usually in ascending numerical order). The parameters are: * keys - the value of the private limited type function_key_descriptor that was returned from a call on page_terminal.get. This is a user variable. A user may have more than one of these variables, and consequently, identify more than one list of function/arrow keys. * index - the number of the function/arrow key in the list of function/arrow keys identified by the parameter keys, that the user is interested in. * key_identifier - returns an enumerated type which identifies the function/arrow key as described in the terminal capabilities file. * previous_position - a position in the string that was returned from a call on page_terminal.get. This position is the one immediately before the function/arrow key was pressed. Three cases are important: - the function/arrow key was pressed before any of the other keys. In this case previous_position would return a zero. - the functon key was the last key pressed. In this case the value returned would be the same as last. - the function/arrow key was pressed in the middle of the string. In this case the character position before the function/arrow key would be returned. An example. Consider the case where a character "a" was pressed, then function key "F9" (as defined in the terminal capabilities file), then the key "b". page_terminal.get would return data = "ab" PAGE TERMINAL Page 3-14 last = 2 a reference to keys When page_terminal.function_key is called and passed the reference to keys and the index = 1, then key_identifier would return f9 and previous_position would return 1. If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.26 Function_key_name This procedure returns a string that is the name of the function key. This information is extracted from the terminal capabilities database when the virtual terminal is opened and stored in the tcf package data structures. The parameters are: * key_identifier - a value of enumerated type function_key_enum which identifies the function key of interest. * key_name - a string which is the function key name as it appears in the terminal capabilities file (exactly). * last - a natural number which is the last character position in the key_name. This version of the terminal capabilities file limits the number of function keys to 32 (plus the four arrow keys). If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.27 Bell Page_terminal.bell sends the sequence defined as bell in the terminal capabilities file. This sequence is sent immediately to the physical terminal. No buffering ocurrs (and it does not wait for an update_screen or update_line call). If the page terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.28 Exceptions The following exceptions are defined in the page_terminal package: * uninitialized - raised when any procedure or function is called prior to calling page_terminal.open (or after calling page_terminal.close and prior to calling page_terminal.open again). PAGE TERMINAL Page 3-15 * tcf_error - raised when an error occured when reading and/or processing the terminal capabilities file. Some possible causes are: - the TCF file is not on your path. - the format of the TCF file is incorrect. - the TCF file is opened for exclusive access by someone else. - a system error occured. * terminal_too_primitive - raised when your terminal does not have the needed functionality to support this terminal type. In a page terminal you must have these three capabilities: * erase to end of line * erase to end of screen * move the cursor * unsupported_terminal - this terminal is unsupported. This could be caused by one of the following: - There is no TERM file on your path. - The TERM file could not be opened. - The TCF file had no entry for this terminal. CHAPTER 4 FORM TERMINAL 4.1 INTRODUCTION This package provides a device-independent form-terminal interface to a user's program. A user's program can "WITH" this package to provide a device-independent terminal interface that is functionally equivalent to a form-terminal. This is the most advanced form of terminal that this virtual terminal supports. This package should be chosen for any of the following reasons: 1. The user's terminal has advanced features. The terminal is directly addressable, with erase to end of line, and erase to end of screen capabilities. 2. The user wants advanced capabilities and is willing to sacrifice some transportability. The screen is addressed as follows: (1,1) (1, form_terminal.size.column ) ____________________________________________________ | | | | | | | | | | | | | | | | | | | | | | | | | ___________________________________________________| (form_terminal.size.line, 1) (form_terminal.size.line, form_terminal.size.column) FORM TERMINAL Page 4-2 where the size is a function call returning an xy_position record containing a line and column number. These values are obtained from the terminal capabilities file. 4.2 PROGRAM LEVEL INTERFACES The source code for the spec is as follows: PACKAGE form_terminal IS TYPE xy_position IS RECORD line : positive; column : positive; END RECORD; TYPE termination_key_range IS RANGE 1..32; TYPE area_intensity IS (none, normal, high); TYPE area_protection IS (unprotected, protected); TYPE area_input IS (graphic_characters, numerics ); PROCEDURE open (name : IN string := "none"); PROCEDURE close; PROCEDURE set_position (position : IN xy_position); FUNCTION position RETURN xy_position; FUNCTION size RETURN xy_position; PROCEDURE define_qualified_area (intensity : IN area_intensity := normal; protection : IN area_protection := protected; input : IN area_input := graphic_characters ); PROCEDURE clear_qualified_area; PROCEDURE tab; PROCEDURE put (item : IN character); PROCEDURE put (item : IN string); PROCEDURE get (item : OUT character); PROCEDURE get (item : OUT string); PROCEDURE erase_area; PROCEDURE erase_display; PROCEDURE activate_form; FUNCTION is_form_updated RETURN boolean; FUNCTION area_qualifier_requires_space RETURN boolean; FUNCTION termination_key RETURN termination_key_range; FORM TERMINAL Page 4-3 uninitialized : EXCEPTION; tcf_error : EXCEPTION; terminal_too_primitive : EXCEPTION; unsupported_terminal : EXCEPTION; invalid_function_key : EXCEPTION; END form_terminal; 4.2.1 Types * termination_key_range - indicates the number of a function keys available to use as a terminate key. The range is 1 to 32. The terminate key is the key that was pressed to return control back to the user's program. * area_intensity - indicates the intensity at which the characters in the area should be displayed. NONE indicates that characters are not displayed. NORMAL indicates the default setting of the terminal at the instant the user is running a form terminal. HIGH intensity indicates something other than NORMAL where the characters are visible on the display. * area_protection - specifies whether the user can modify the contents of the area when the form ha s been activated. The choices are PROTECTED and UNPROTECTED. * area_input - specifies the valid characters that may be entered by the user. GRAPHIC_CHARACTERS indicates that any printable characters may be entered. The choices are NUMERIC, ALPHABETIC, and GRAPHIC_CHARACTERS. 4.2.2 Open Form_terminal.open is called to open the form terminal. Form_terminal.open must be the first procedure called in the virtual terminal package. A call on any other procedure or function before calling open will result in the exception form_terminal.uninitialized being raised. The single string parameter "name" is the name of the terminal if it is known by the programmer. If open is called with no parameter then "none" is used as the default. In this case the virtual terminal will look for a file name "TERM" on your path, open it, and read the first line. This string will be used as the terminal name. The format of the string must match exactly (even in case) the terminal name field in the terminal capabilities file. Please refer to Appendix A for a discussion of the TCF. Due to a bug in the Data General ADE you MUST put a second line in the TERM file. The contents of the second line are not used. An example TERM file: FORM TERMINAL Page 4-4 tv970 this line overcomes the END_ERROR problem of the ADE The exceptions that can be raised from a call on open are: * tcf_error - an error occured when reading and/or processing the terminal capabilities file. Some possible causes are: - the TCF file is not on your path. - the format of the TCF file is incorrect. - the TCF file is opened for exclusive access by someone else. - a system error occured. * unsupported_terminal - this terminal is unsupported. This could be caused by one of the following: - There is no TERM file on your path. - The TERM file could not be opened. - The TCF file had no entry for this terminal. * terminal_too_primitive - raised if your terminal is considered too primitive to be a form terminal. Your terminal MUST support: - erase to end of screen - erase to end of line - move the cursor 4.2.3 Close form_terminal.close is called to close the form terminal. It must be the last procedure called. Any procedure or function called after this one will raise the exception unitialized. If form_terminal.close is called and the form terminal is already closed, nothing happens. 4.2.4 Set_position form_terminal.set_position will move the active position in the virtual terminal display to the new coordinates given in the FORM TERMINAL Page 4-5 parameter list. A call on this procedure does not affect the actual terminal's display, only the virtual representation of the display. if the parameter contains a value that is outside the actual screen dimensions it will be set to the screen dimension which it exceeds. This procedure has one parameter, position, which identifies the line and column that the active position should be moved to. If the form terminal has not been opened previously to this then the exception form_terminal.uninitialized will be raised. 4.2.5 Position form_terminal.position returns a line/column pair of type xy_position that identifies where the active position is located in the virtual terminal. It should be noted that this MAY not be where the cursor is located on the actual terminal's screen. If the form terminal has not been opened previously to this then the exception form_terminal.uninitialized will be raised. 4.2.6 Size form_terminal.size returns the number of columns and number of lines contained in the actual display. This information is located in the terminal capabilities file and can be set and altered by the user. If the form terminal has not been opened previously to this then the exception form_terminal.uninitialized will be raised. 4.2.7 Define_qualified_area Form_terminal.define_qualified_area is called to define qualified areas. These qualified areas are bounded by the next qualified area defined such that the end of a qualified area is indicated by the beginning of the next qualified area. Each qualified area may have user editing restrictions imposed. A virtual display that has no qualified area defined by the user program is considered protected and set to blank. The parameters to this procedure are as follows: * intensity - set the intensity of the qualified area (default is normal). * protection - set the protection of the qualified area (default is protected). * input - the permissible input characters for the area. FORM TERMINAL Page 4-6 4.2.8 Clear_qualified_area Form_terminal.clear_qualified_area removes an area qualifier from the active position. The qualified area that precedes this one is extended to encompass the removed area. If the form terminal has not been opened previously to this then the exception generated in the driver package, driver.uninitialized, will be propogated out to the calling program unit. 4.2.9 Tab Form_terminal.tab moves the active position the specified number of qualified areas toward the end of the display. The resultant active position is the first character position of the designated qualified area. If the next qualified area moved to is at the end of a line, the active position is at the first qualified area of the next line. If the next qualified area moved to is at the end of the form, then the active position is at the first qualified area of the form. If the form terminal has not been opened previously to this then the exception generated in the driver package, driver.uninitialized, will be propogated out to the calling program unit. 4.2.10 Put (character And String) There are two types of puts performed by the form_terminal. One writes a character, the other writes a string to the virtual display. Form_terminal.put may write a character to the virtual display at the active position. The column of the active position is incremented by one. Form_terminal.put may also write a string to the virtual display at the active position. The column of the active position is incremented by length of the string. If the character/string is written in the last column of a line, the active position is advanced to the first column of the following line. If the character/string is written to the last column of the last line, the active position is moved to the first column of the first line. The one parameter to this procedure is the character/string to be written to the display. If the form terminal has not been opened previously to this then the exception generated in the driver package, driver.uninitialized, will be propogated out to the calling program unit. 4.2.11 Get (character And String) There are two types of reads performed by the form_terminal. One reads a character, the other reads a string from the actual display. Form_terminal.get may read a character from the virtual FORM TERMINAL Page 4-7 display at the active position. The active position is advanced forward one position. Form_terminal.get may also read a string from the virtual display at the active position. The active position is advanced forward the length of the string. The only parameter to this procedure is the character/string to be read from the display. If the form terminal has not been opened previously to this then the exception generated in the driver package, driver.uninitialized, will be propogated out to the calling program unit. 4.2.12 Erase_area Form_terminal.erase_area clears the area in which the active position is located by replacing the area with blanks. If the form terminal has not been opened previously to this then the exception generated in the driver package, driver.uninitialized, will be propogated out to the calling program unit. 4.2.13 Erase_display Form_terminal.erase_display clears the display and removes all user program defined area qualifiers. The display is then reset to the default form which consists of one qualified area (the entire size of the display) which is blank and protected. If the form terminal has not been opened previously to this then the exception generated in the driver package, driver.uninitialized, will be propogated out to the calling program unit. 4.2.14 Activate_form Form_terminal.activate_form maps the virtual display into the actual display. Activate_form calls redisplay_screen_with_movement procedure to make the terminal display look like the data structures in the vt_contents package. This is called once when activate form is first called. When the form is activated the cursor is placed at the first editing position on the form. Form editing is performed by the procedure body of activate_form. The procedure body calls vt_input.get to read the characters from the keyboard into the data structures of vt_contents. Redisplay_line_with_movement is called after each call of vt_input.get to redisplay the virtual display line to the actual display line. Control returns to the user's program when a function key is depressed. The virtual form will exist in the data structures until the virtual display is erased or the qualified areas are cleared. The user's program may then choose to define another form if desired. If the form terminal has not been opened previously to this then FORM TERMINAL Page 4-8 the exception generated in the driver package, driver.uninitialized, will be propogated out to the calling program unit. 4.2.15 Is_form_updated Form_terminal.is_form_updated is called by the programmer to determine if the user modified the previous form while it was active. The user can accomplish this by inserting any data into the form or deleting any data. If the form terminal has not been opened previously to this then the exception generated in the driver package, driver.uninitialized, will be propogated out to the calling program unit. 4.2.16 Termination_key Form_terminal.termination_key returns a value between 1 and 32 indicating which function key the user struck to exit from the previous form while it was active. If the form terminal has not been opened previously to this then the exception generated in the driver package, driver.uninitialized, will be propogated out to the calling program unit. 4.2.17 Exceptions The following exceptions are defined in the page_terminal package: * uninitialized - raised when any procedure or function is called prior to calling page_terminal.open (or after calling page_terminal.close and prior to calling page_terminal.open again). * tcf_error - raised when an error occured when reading and/or processing the terminal capabilities file. Some possible causes are: - the TCF file is not on your path. - the format of the TCF file is incorrect. - the TCF file is opened for exclusive access by someone else. - a system error occured. * terminal_too_primitive - raised when your terminal does not have the needed functionality to support this terminal type. In a page terminal you must have these three capabilities: FORM TERMINAL Page 4-9 * erase to end of line * erase to end of screen * move the cursor * unsupported_terminal - this terminal is unsupported. This could be caused by one of the following: - There is no TERM file on your path. - The TERM file could not be opened. - The TCF file had no entry for this terminal. APPENDIX A THE TERMINAL CAPABILITIES FILE A.1 INTRODUCTION The Terminal Capabilities File is a variation of the TERMCAP developed in the Berkeley extensions to the UNIX operating system. The TCF is a data base describing terminals. Terminals are described in the TCF by giving a set of capabilities which they have, and by describing how operations are performed. Padding requirements and initialization sequences are included in the TCF. Entries in the TCF consist of a number of ":" separated fields. The first entry for each terminal gives the names which are known for the terminal, separated by "|" characters. The first name is always 2 characters long and is used by older UNIX systems which store the terminal type in a 16 bit word in a systemwide data base. The second name given is the most common abbreviation for the terminal, and the last name given should be a long name fully identifying the terminal. This second name is the one that is matched against the VMS logical name "TERM". The second name should contain no blanks; the last name may well contain blanks for readability. This virtual terminal uses the second name as a match against the user supplied terminal name. A.2 CAPABILITIES (P) indicates padding may be specified. Padding is an amount of time to be waited after the command is executed. Name Type Description al str Add new blank line be str Bell cd str Clear to end of display co num Number of columns in a line ce str Clear to end of line cm str Cursor motion dc str Delete character dl str Delete line THE TERMINAL CAPABILITIES FILE Page A-2 ei str End insert mode im str Enter insert character mode is str Terminal initialization string k1 str Sent by terminal function key 1 k2 str Sent by terminal function key 2 k3 str Sent by terminal function key 3 k4 str Sent by terminal function key 4 k5 str Sent by terminal function key 5 k6 str Sent by terminal function key 6 k7 str Sent by terminal function key 7 k8 str Sent by terminal function key 8 k9 str Sent by terminal function key 9 l1 str Label on function key 1 l2 str Label on function key 2 l3 str Label on function key 3 l4 str Label on function key 4 l5 str Label on function key 5 l6 str Label on function key 6 l7 str Label on function key 7 l8 str Label on function key 8 l9 str Label on function key 9 kd str Sent by terminal down arrow key kl str Sent by terminal left arrow key kr str Sent by terminal right arrow key ku str Sent by terminal up arrow key li num Number of lines on screen or page nl str Newline character (default \n) se str End stand out mode sf str Scroll forwards so str Begin stand out mode sr str Scroll reverse (backwards) su bool Scrolls up at bottom of screen wr bool Wraps at end of line x0 str Sent by terminal function key 10 x1 str Sent by terminal function key 11 x2 str Sent by terminal function key 12 x3 str Sent by terminal function key 13 x4 str Sent by terminal function key 14 x5 str Sent by terminal function key 15 x6 str Sent by terminal function key 16 x7 str Sent by terminal function key 17 x8 str Sent by terminal function key 18 x9 str Sent by terminal function key 19 g0 str Sent by terminal function key 20 g1 str Sent by terminal function key 21 g2 str Sent by terminal function key 22 g3 str Sent by terminal function key 23 g4 str Sent by terminal function key 24 g5 str Sent by terminal function key 25 g6 str Sent by terminal function key 26 g7 str Sent by terminal function key 27 g8 str Sent by terminal function key 28 g9 str Sent by terminal function key 29 t0 str Sent by terminal function key 30 t1 str Sent by terminal function key 31 THE TERMINAL CAPABILITIES FILE Page A-3 t2 str Sent by terminal function key 32 y0 str Label on function key 10 y1 str Label on function key 11 y2 str Label on function key 12 y3 str Label on function key 13 y4 str Label on function key 14 y5 str Label on function key 15 y6 str Label on function key 16 y7 str Label on function key 17 y8 str Label on function key 18 y9 str Label on function key 19 h0 str Label on function key 20 h1 str Label on function key 21 h2 str Label on function key 22 h3 str Label on function key 23 h4 str Label on function key 24 h5 str Label on function key 25 h6 str Label on function key 26 h7 str Label on function key 27 h8 str Label on function key 28 h9 str Label on function key 29 v0 str Label on function key 30 v1 str Label on function key 31 v2 str Label on function key 32 an str Ansi terminal vt str VT terminal ca str Clear all of line cl str Clear screen ds str De-initialization string The following entry describes the Televideo-970, among the more complex entries in the TCF file as of this writing. t1|tv970|tv-970|televideo 970:\ :al=1*\E[1L:am:bs:cd=\E[J:ce=\E[K:cl=\E[2J:cm=\E[%i%2;%2H:co#80:\ :dc=\E[1P:dl=1*\E[1M:dn=\E[1B:ei=\E[4l:ho=\E[H:im=\E[4h:li#24:mi:\ :nd=\E[1C:as=\E[10m:ae=\E[11m:ms:pt:se=\E[0m:so=\E[7m:up=\E[1A:\ :vs=\E[>4h:ve=\E[>4l:kb=^h:ku=\E[A:kd=\E[B:kl=\E[D:kr=\E[C:\ :kh=\E[H:kn#8:k1=\EOS:k2=\EOT:k3=\EOU:k4=\EOV:k5=\EOW:l6=blue:\ :sr=\EM:is=\E<\E[2J:\ :ca=\E[2K:ds=\E[?2l:\ :l1=F1:l2=F2:l3=F3:l4=F4:l5=F5:l6=F6:l7=F7:l8=F8:l9=F9:y0=F10:\ :y1=F11:y2=F12:y3=F13:y4=F14:y5=F15:y6=F16:\ :y7=Shift F1:y8=Shift F2:y9=Shift F3:h0=Shift F4:h1=Shift F5:\ :h2=Shift F6:h3=Shift F7:h4=Shift F8:h5=Shift F9:h6=Shift F10:\ :h7=Shift F11:h8=Shift F12:h9=Shift F13:v0=Shift F14:v1=Shift F15:\ :v2=Shift F16:an:\ :k1=\E?a:k2=\E?b::k3=\E?c:k4=\E?d:k5=\E?e:k6=\E?f:k7=\E?g:k8=\E?h:\ :k9=\E?i:x0=\E?j:x1=\E?k:x2=\E?l:x3=\E?m:x4=\E?n:x5=\E?o:x6=\E?p:\ :x7=\E?A:x8=\E?B:x9=\E?C:g0=\E?D:g1=\E?E:g2=\E?F:g3=\E?G:g4=\E?H:\ :g5=\E?I:g6=\E?J:g7=\E?K:g8=\E?L:g9=\E?M:t0=\E?N:t1=\E?O:t2=\E?P:\ :ku=\E[A:kd=\E[B:kr=\E[C:kl=\E[D: THE TERMINAL CAPABILITIES FILE Page A-4 Note that entries may continue onto multiple lines by giving a \ as the last character of a line, and that empty fields may be included for readability (here between the last field on a line and the first field on the next). Capabilities in TCF are of three types: Boolean capabilities which indicate that the terminal has some particular feature, numeric capabilities giving the size of the terminal or the size of particular delays, and string capabilities, which give a sequence which can be used to perform particular terminal operations. All capabilities have two letter codes. Numeric capabilities are followed by the character "#" and then the value. Thus "co" which indicates the number of columns the terminal has gives the value "80" for the Televideo-970. String valued capabilities, such as "ce" (clear to end of line sequence) are given by the two character code, an "=", and then a string ending at the next following ":". A delay in milliseconds may appear after the "=" in such a capability. The delay must be an integer, e.g. "20". A number of escape sequences are provided in the string valued capabilities for easy encoding of characters there. A "\E" maps to an ESCAPE character, "^x" maps to a control-x for any appropriate x, and the sequences "\n" "\r" "\t" "\b" "\f" give a newline, return, tab, backspace and formfeed. Finally, characters may be given as three octal digits after a "\", and the characters "^" and "\" may be given as "\^" and "\\". If it is necessary to place a ":" in a capability it must be escaped in octal as "\072". We now outline how to prepare descriptions of terminals. The most effective way to prepare a terminal description is by imitating the description of a similar terminal in TCF. Be aware that a very unusual terminal may expose deficiencies in the ability of the TCF file to describe it or bugs in the virtual terminal. To easily test a new terminal description, you can set the environment variable TCF to a pathname of a file containing the description you are working on and the virtual terminal will look there rather than the standard location. A.2.1 Basic Capabilities The number of columns on each line for the terminal is given by the "co" numeric capability. If the terminal is a CRT, then the number of lines on the screen is given by the "li" capability. If the terminal scrolls at the right edge of the screen, use ":wr:" to signal this. If the terminal scrolls up at the bottom of the screen, use ":su:" to signal this. These capabilities suffice to describe hardcopy and "glass-tty" terminals. Thus the model 33 teletype is described as t3|33|tty33:co#72 THE TERMINAL CAPABILITIES FILE Page A-5 while the Lear Siegler ADM-3 is described as cl|adm3|3|lsi:\ adm3:wr:li#24:co#80 A.2.2 Cursor Addressing Cursor addressing in the terminal is described by a "cm" string capability. These substitute to encodings of the current line or column position, while other characters are passed through unchanged. If the "cm" string is thought of as being a function, then its arguments are the line and then the column to which motion is desired, and the "%" encodings have the following meanings: %d use as many digits as necessary %2 use 2 digits %3 use 3 digits %. encode binary value into a character (7 bits) %+x adds x to value, then %. %<xy if value < x adds y; then in any case %. %r reverses order of line and column, no output %i increments line/column (for 1 origin) %% gives a single % Consider the HP2645, which, to get to row 3 and column 12, needs to be sent "\E&a12c03Y" padded for 6 milliseconds. Note that the order of the rows and columns is inverted here, and that the row and column are printed as two digits. Thus its "cm" capability is "cm=6\E&%r%2c%2Y". The Microterm ACT-IV needs the current row and column sent preceded by a "^T", with the row and column simply encoded in binary, "cm=^T%.%.". A final example is the LSI ADM-3a, which uses row and column offset by a blank character, thus "cm=\E=%+ %+ ". A.2.3 Area Clears If the terminal can clear from the current position to the end of the line, leaving the cursor where it is, this should be given as "ce". If the terminal can clear from the current position to the end of the display, then this should be given as "cd". If the terminal can clear an entire line regardless of cursor location on the line, this should be given as "ca". If the terminal can clear an entire display then this should be given as "cl". A.2.4 Insert/Delete Line If the terminal can open a new blank line before the line where the cursor is, this should be given as "al"; this is done only from the first position of a line. The cursor must then appear on the newly blank line. If the terminal can delete the line which the cursor is on, then this should be given as "dl"; this is done only from the first position on the line to be deleted. THE TERMINAL CAPABILITIES FILE Page A-6 A.2.5 Insert/Delete Character There are two basic kinds of intelligent terminals with respect to insert/delete character which can be described using the TCF. The most common insert/delete character operations affect only the characters on the current line and shift characters off the end of the line rigidly. Other terminals, such as the Concept 100 and the Perkin Elmer Owl, make a distinction between typed and untyped blanks on the screen, shifting upon an insert or delete only to an untyped blank on the screen which is either eliminated, or expanded to two untyped blanks. You can find out which kind of terminal you have by clearing the screen and then typing text separated by cursor motions. Type "abc def" using local cursor motions (not spaces) between the "abc" and the "def". Then position the cursor before the "abc" and put the terminal in insert mode. If typing characters causes the rest of the line to shift rigidly and characters to fall off the end, then your terminal does not distinguish between blanks and untyped positions. If the "abc" shifts over to the "def" which then move together around the end of the current line and onto the next as you insert, you have the second type of terminal. If you have this second type of terminal, you will get no support from the virtual terminal. This may be changed in further versions. Give as "im" the sequence to get into insert character mode. Give as "ei" the sequence to leave insert mode. A.2.6 Highlighting, Underlining, And Visible Bells If your terminal has sequences to enter and exit standout mode these can be given as "so" and "se" respectively. If there are several flavors of standout mode (such as inverse video, blinking, or underlining - half bright is not considered "standout") the prefered mode is inverse video by itself. If the terminal has a way of flashing the screen to indicate an error quietly (a bell replacement) then this can be given as "be"; it must not move the cursor. A.2.7 Function Keys If the terminal has function keys that transmits codes when the keys are pressed, this information can be given. Note that it is not possible to handle terminals where the keypad only works in local (this applies, for example, to the unshifted HP 2621 keys). The codes sent by the left arrow, right arrow, up arrow, down arrow, and home keys can be given as "kl", "kr", "ku", and "kd" respectively. If there are function keys such as "f1", "f2", ..., "f9", the codes they send can be given as "k1", "k2", ..., "k9", "x0", "x1", ..., "x6" If these keys have labels, the labels can be given as "l1", ..., "l9", "y0", "y1", ..., "y6". A.2.8 Initialization An initialization string can be specified to setup the THE TERMINAL CAPABILITIES FILE Page A-7 characteristics of a terminal. If the terminal must have its function keys defined or turn on the keypad mode this can be done with is. Using the Televideo-970 example again: t1|tv970|tv-970|televideo 970:\ :al=1*\E[1L:am:bs:cd=\E[J:ce=\E[K:cl=\E[2J:cm=\E[%i%2;%2H:co#80:\ :dc=\E[1P:dl=1*\E[1M:dn=\E[1B:ei=\E[4l:ho=\E[H:im=\E[4h:li#24:mi:\ :nd=\E[1C:as=\E[10m:ae=\E[11m:ms:pt:se=\E[0m:so=\E[7m:up=\E[1A:\ :vs=\E[>4h:ve=\E[>4l:kb=^h:ku=\E[A:kd=\E[B:kl=\E[D:kr=\E[C:\ :kh=\E[H:kn#8:k1=\EOS:k2=\EOT:k3=\EOU:k4=\EOV:k5=\EOW:l6=blue:\ :sr=\EM:is=\E<\E[2J:\ :ca=\E[2K:ds=\E[?2l:\ :l1=F1:l2=F2:l3=F3:l4=F4:l5=F5:l6=F6:l7=F7:l8=F8:l9=F9:y0=F10:\ :y1=F11:y2=F12:y3=F13:y4=F14:y5=F15:y6=F16:\ :y7=Shift F1:y8=Shift F2:y9=Shift F3:h0=Shift F4:h1=Shift F5:\ :h2=Shift F6:h3=Shift F7:h4=Shift F8:h5=Shift F9:h6=Shift F10:\ :h7=Shift F11:h8=Shift F12:h9=Shift F13:v0=Shift F14:v1=Shift F15:\ :v2=Shift F16:an:\ :k1=\E?a:k2=\E?b::k3=\E?c:k4=\E?d:k5=\E?e:k6=\E?f:k7=\E?g:k8=\E?h:\ :k9=\E?i:x0=\E?j:x1=\E?k:x2=\E?l:x3=\E?m:x4=\E?n:x5=\E?o:x6=\E?p:\ :x7=\E?A:x8=\E?B:x9=\E?C:g0=\E?D:g1=\E?E:g2=\E?F:g3=\E?G:g4=\E?H:\ :g5=\E?I:g6=\E?J:g7=\E?K:g8=\E?L:g9=\E?M:t0=\E?N:t1=\E?O:t2=\E?P:\ :ku=\E[A:kd=\E[B:kr=\E[C:kl=\E[D: The initialization string is ":is=\E<\E[2J". This string will be sent to the terminal when the virtual terminal is initialized. The de-initialization string, ds, sends a string of escape sequences that changes the terminal upon exiting the program. APPENDIX B PROGRAMMER'S NOTES B.1 COMPILING THE VIRTUAL TERMINAL To compile the virtual terminal (scroll_terminal, page_terminal, and form_terminal), compile the source in the following order: 1. vtcontent_spec.ada 2. sysdep_spec.ada 3. tcf_spec.ada 4. scroll_spec.ada 5. page_spec.ada 6. form_spec.ada 7. vtinput_spec.ada 8. driver_spec.ada 9. redisplay_spec.ada 10. sysdep_body.ada 11. tcf_body.ada 12. driver_body.ada 13. vtinput_body.ada 14. redisplay_body.ada 15. scroll_body.ada 16. page_body.ada 17. form_body.ada PROGRAMMER'S NOTES Page B-2 18. activate_form.ada I suggest you compile with the /debug switch so you can debug your code and catch any constraint errors coming from the VT code. If you decide to attempt compilation with /suppress to remove error checking, we have found that vtinput_body.ada will not compile with correct code. B.2 REDISPLAY Our goal was to implement the Gosling redisplay algorithm (the one used in Unix Emacs). However, due to the gross inefficiencies of the code generated from the DG compiler, we compromised on an incremental form of redisplay. There is a field in the screen definition (found in the file vtcontent_spec.ada) that is called corresponding_line. This field is used to identify the line in the actual_screen (that reflects what is currently on the screen) that corresponds to a particular line in the virtual_screen (the one where all operations occur until update_X (screen or line) is called. It works OK. It is definitely faster than the Gosling redisplay. Things you should keep in mind: * Use insert and delete line as much as possible. These will work faster if your terminal supports the operations. * The redisplay is not smart enough to figure out combinations of insert and delete when you have simply repainted lines on the screen. That is, if you DO NOT use insert and delete line, then the redisplay algorithm won't either. * Be very careful specifying the top line and bottom line in an update_screen call. You can get into trouble with these parameters. We considered removing them, but can be much faster with them there. * If your terminal support ANSI X3.64 sequences then specify the :an boolean field in the TCF. Your terminal must support * insert line with a parameter - ESC [ Pn M * delete line with a parameter - ESC [ Pn L * Erase in display - ESC [ 0 J, ESC [ 1 J, ESC [ 2 J (in order: erase from active position to end, from start to active position, and all positions). * Erase in line - ESC [ 0 K, ESC [ 1 K, ESC [ 2 K (in (again in order: erase from active position to end, from start to active position, and all positions). * Select graphic rendition - ESC [ 0 m, ESC [ 7 m (primary rendition, reverse image). PROGRAMMER'S NOTES Page B-3 * Cursor position ESC [ Pl ; Pc H (where Pl is the line number as an ASCII number sequence, and Pc is the column number). If you can specify this then the parameter modes will be be used and this thing will really fly when inserting and deleting lines. B.3 OTHER PACKAGES The structure of this virtual terminal is shown in the figure below. PROGRAMMER'S NOTES Page B-4 ______________ ______________ ______________ | Scroll mode | | Page mode | | Form mode | |______________| |______________| |______________| | | | | | | |______________| |______________| |______________| | | | | | | | | | | | | | \_____ _____ |_ | _ | ___/_____________ | _ | _| __/ | | V | | | | | | | | | | | | | | | ____________v_ \_____ | _ | | | | | | | vt_content | | \ | | | | | | |______________|<_________ |_ | _ | _/__ | _________________ | _ | _/ | | | | | | | | |______________| | | | | | | ^ | | | | | | ______|_______ | | | | | | | redisplay | | | | | | | |______________|<_________ |_ | __/_____ | __________________/ | | | | | | | |______________| | | | | | | \__________\________________ ______/ | ____/ V ___v________v_ _______v______ | Driver |___ ______________________| VT_input | |______________| V |______________| | |__ | _________________ ___| | |______________| | V |______________| | | __________v___ ___v__________ | TCF | | SYSDEP | |______________| |______________| | | | | |______________| |______________| ^ | ^ _______|__ ___V____|__ | TCF file | ' ____________ | ======== | | | -------- \ | ======== | | | | | | ======== | 8 ` | |________| | ======== | 8 `|_____________| | ======== | 8 ______________ |__________| \\========== ==\ \\========== =| TERMINAL The package definitions are as follows: * scroll_terminal, page_terminal, form_terminal - these are what the user program uses and are described in this document. * redisplay - the package containing various redisplay line and redisplay screen procedures. PROGRAMMER'S NOTES Page B-5 * driver - this package is called via driver.interpret to cause operations to occur on the screen. The procedure interpret can be sent any string. Two things may occur with the string. - the string matches one of the ANSI sequences that driver understands. The sequence is transformed into one that the particular terminal that the user has (semantically the same, functionally different). I.E. If your terminal is a vt52, to move the position 7,7 the string sent would need to be "ESC Y & &". This information is store in the terminal capabilities file and is read into internal data structures by the TCF package upon initialization. Driver.interpret will take the sequence "ESC [ 7 ; 7 H" and translate it into the sequence "ESC Y & &" before sending it to the terminal display. A single call on driver.interpret will always result in something being sent to the screen immediately. Do not send partial escape sequences, they will not be understood or translated. The sequences understood are: . ESC [ Pn P - Delete Character . ESC [ Pn M - Delete Line . ESC [ Pn L - Insert Line . ESC [ 0 J - Erase in display from active pos to end . ESC [ 1 J - Erase in display from start to active pos . ESC [ 2 J - Erase in display all positions . ESC [ 0 K - Erase in line from active pos to end . ESC [ 1 K - Erase in line from start to active pos . ESC [ 2 K - Erase in line all positions . ESC [ 0 m - Select primary rendition . ESC [ 7 m - Select reverse image rendition . ESC [ Pl ; Pc H - Cursor position . ESC [ 4 h - Enter insert mode . ESC [ 4 l - Exit insert mode Where - Pn is an ASCII representation of a number parameter. ESC means the escape character. Pl is like Pn but represents the line number, ditto with Pc as the column number. PROGRAMMER'S NOTES Page B-6 You may find out if your terminal supports one or more of these functions by interogating the variable driver.supported_functions which identifies those operations that have an entry in the TCF file. - if the sequence is not one that is understood then it is sent directly to the screen with no translation or filtering. * vt_input - gets characters from the terminal and detects function and arrow keys (this one is extremely inefficient at this time, due to bugs in the DG implementation of unchecked_conversion). * TCF - reads in the terminal capabilities file and provides the needed data structures containing the information to the other packages. * SYSDEP - isolates all system dependencies. This is described in the next section. B.4 CHOOSING AN INTERFACE LEVEL There are many ways of interfacing to the packages within the virtual terminal. Depending on what is desired (speed, functionality) different choices can be made to enhance those desires. This matrix should provide guidance on how to use the different packages within the scroll and page mode terminal packages. The form terminal interfaces are a different beast and cannot be applied to the matrix in a usable way. I desire: Interface to package: Direct communication with the SYSDEP for input terminal, direct communication SYSDEP for output with the keyboard. No function key identification, No TCF translation. This is the fastest mode. TCF translation of the output, SYSDEP for input output immediately, input with driver for output no function key indentification. This is very fast for input, fairly fast for output. TCF translation of the output, vt_input for input output immediately, input with driver for output function key identification. This is fairly fast for output, not so fast for input. PROGRAMMER'S NOTES Page B-7 TCF translation of the output, page_terminal, scroll_terminal for output when requested, input output with no function key translation. SYSDEP for input fairly fast for output, very fast for input. and so forth... B.5 EFFICIENCY The system as it now stands is inefficient. If the /suppress option is used it can be made somewhat more efficient. All packages can be recompiled with this switch except vt_input which cannot. This is due to a problem with the code generated by the DG compiler. The vt_input procedure and function calls require a level of type changing when calls are made from the page_terminal body into the vt_input package. This is a significant overhead that can be reduced when unchecked conversion is available. The data structures defined in the vt_content package are quite large. Part of the reason is that the DG generated a 32-bit word for every type of elementary object (even booleans get a 32-bit word!). Arrays have a 16-word overhead associated with every individual one. Strings are store as 32-bit words with each character stored in the upper 8 bits. Some of the interfaces could be made in-line. We tryed that and discovered a serious problem with the debugger. So we removed it for development. Since it could hinder transportability, we decided to leave it out. B.6 SYSTEM DEPENDENCIES All system dependencies are isolated in the package SYSDEP. Of course, coding work-arounds are technically system dependencies, these are not identified here. An implementation must provide the capabilities as described in the interface spec. These interfaces are described below. * open - Open the console for binary I/O, no echo. * close - Close the console. Parameters should be reset to original condition. * put - Put a string to the terminal. There should be no translation of the characters. There can be exceptions to this rule (like CTRL-S and CTRL-Q) and these exceptions must be identified in valid_character below. PROGRAMMER'S NOTES Page B-8 * get - Get a string from the terminal keyboard. This ocurrs with no echo and no translations. * tcf_name - Returns the name of the terminal capabilities file as a string. You better pass in a string of sufficient length to handle the name that is returned or you will get a constraint error. 80 is a good random number. * terminal_name - Returns the name of the terminal. This name of a string like "tv970". If the name cannot be determined then last is returned as 0 (zero). Again, you better make the name parameter big enough to hold the value returned. A DG implementation note: This procedure looks for a file called TERM on your searchlist. * valid_character Returns a boolean value identifying whether the character passed in is safe to used in the environment. Suspicious characters include CTRL-S CTRL-Q CTRL-C CTRL-Y. APPENDIX C SAMPLE PROGRAMS The biggest sample program is the interactive/batch form generator that is one of the tools developed by Texas Instruments under contract. This tools should be available in the same location as this virtual terminal. A code segment that will handle reading data from the terminal using the input procedures and functions described in scroll_terminal and page_terminal is as follows: LOOP page_terminal.get( data, last, keys ); number_of_function_keys := page_terminal.function_count( keys ); IF last=0 -- only function keys THEN FOR i IN 1..number_of_function_keys LOOP page_terminal.function_key( keys, i, id, position ); handle_the_function_key( id ); END LOOP; ELSE -- data here too last_position := 1; FOR i IN 1..number_of_function_keys -- go through the -- function keys LOOP page_terminal.function_key( keys, i, id, position ); IF position<>0 THEN handle_the_string( data( last_position..position ), ( position-last_position+1 ) ); last_position := position + 1; END IF; handle_the_function_key( id ); END LOOP; END IF; END LOOP;