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 / vt2spec.doc < prev next >

Wrap

Text File | 1988-05-03 | 323.1 KB | 7,981 lines

||||||||||||||||||||||||| THIS IS NOT A DELIVERABLE ||||||||||||||||||||||||| THIS IS NOT A DELIVERABLE ||||||||||||||||||||||||| THIS IS NOT A DELIVERABLE ||||||||||||||||||||||||| ||||||||||||||||||||||||| Program Design Specification for an ANSI X3.64 Compatible Virtual Terminal in Ada Prepared for: ||||||||||||||||||||||||| ||||||||||||||||||||||||| Advanced Computer Systems Lab ||||||||||||||||||||||||| Texas Instruments ||||||||||||||||||||||||| ||||||||||||||||||||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| THIS IS NOT A DELIVERABLE ||||||||||||||||||||||||| THIS IS NOT A DELIVERABLE ||||||||||||||||||||||||| THIS IS NOT A DELIVERABLE ||||||||||||||||||||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY||||||| ||||||||||||||||||||||||| Equipment Group - ACSL ||||||||||||||||||||||||| P.O. Box 801, M.S. 8007 ||||||||||||||||||||||||| McKinney, Texas 75069 ||||||||||||||||||||||||| 19-Oct-1984 ||||||||||||||||||||||||| ||||||||||||||||||||||||| TEXAS INSTRUMENTS INCORPORATED ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| ||||||||||||||||||||||||| CHAPTER 1 INTRODUCTION 1.1 PURPOSE . . . . . . . . . . . . . . . . . . . . . 1-1 1.2 SCOPE . . . . . . . . . . . . . . . . . . . . . . 1-1 1.2.1 Summary . . . . . . . . . . . . . . . . . . . . 1-2 1.2.1.1 Problem Statement . . . . . . . . . . . . . . 1-2 1.2.1.2 Objective . . . . . . . . . . . . . . . . . . 1-3 1.2.1.3 Scope . . . . . . . . . . . . . . . . . . . . 1-3 CHAPTER 2 APPLICABLE DOCUMENTS 2.1 GOVERNMENT STANDARDS . . . . . . . . . . . . . . . 2-1 2.2 GOVERNMENT SPECIFICATIONS . . . . . . . . . . . . 2-1 2.3 OTHER GOVERNMENT DOCUMENTS . . . . . . . . . . . . 2-3 2.4 OTHER PUBLICATIONS . . . . . . . . . . . . . . . . 2-3 CHAPTER 3 REQUIREMENTS 3.1 FUNCTION ALLOCATION . . . . . . . . . . . . . . . 3-1 3.1.1 Requirement . . . . . . . . . . . . . . . . . . 3-1 3.1.2 Packages Overview . . . . . . . . . . . . . . . 3-4 3.2 FUNCTION DESCRIPTION . . . . . . . . . . . . . . . 3-6 3.2.1 The Virtual Terminal Package . . . . . . . . . . 3-6 3.2.1.1 Introduction . . . . . . . . . . . . . . . . . 3-6 3.2.1.2 The Object Name . . . . . . . . . . . . . . . 3-6 3.2.1.3 Abstract . . . . . . . . . . . . . . . . . . . 3-6 3.2.1.4 Parameters . . . . . . . . . . . . . . . . . . 3-6 3.2.1.5 Local Constants, Types, And Variables . . . . 3-6 3.2.1.6 Errors . . . . . . . . . . . . . . . . . . . . 3-6 3.2.1.7 Exceptions . . . . . . . . . . . . . . . . . . 3-6 3.2.1.8 The Ada Source . . . . . . . . . . . . . . . . 3-6 3.2.2 The Scroll Terminal Package . . . . . . . . . 3-11 3.2.2.1 Introduction . . . . . . . . . . . . . . . . 3-11 3.2.2.2 The Object Name . . . . . . . . . . . . . . 3-11 3.2.2.3 Abstract . . . . . . . . . . . . . . . . . . 3-11 3.2.2.4 Parameters . . . . . . . . . . . . . . . . . 3-11 3.2.2.5 Local Constants, Types, And Variables . . . 3-11 3.2.2.6 Selectors (Functions) . . . . . . . . . . . 3-12 3.2.2.6.1 Determining The Current Position . . . . . 3-12 3.2.2.6.2 Determining The Terminal Size . . . . . . 3-13 3.2.2.6.3 Determining The Validity Of A Character . 3-14 3.2.2.6.4 Getting The Number Of Typed Function/Arrow Keys . . . . . . . . . . . . . . . . . . . 3-15 3.2.2.7 Actors (Procedures) . . . . . . . . . . . . 3-16 3.2.2.7.1 Opening A Scroll Terminal . . . . . . . . 3-16 3.2.2.7.2 Closing A Scroll Terminal . . . . . . . . 3-18 3.2.2.7.3 Positioning The Cursor . . . . . . . . . . 3-19 3.2.2.7.4 Setting A Horizontal Tab Stop . . . . . . 3-20 3.2.2.7.5 Clearing A Horizontal Tab Stop . . . . . . 3-21 3.2.2.7.6 Horizontal Tab . . . . . . . . . . . . . . 3-22 3.2.2.7.7 Moving To A New Line . . . . . . . . . . . 3-23 3.2.2.7.8 Moving To A New Page . . . . . . . . . . . 3-24 3.2.2.7.9 Writing Data To A Terminal . . . . . . . . 3-25 Page 2 3.2.2.7.10 Updating The Terminal Display Line . . . . 3-26 3.2.2.7.11 Determining The Validity Of A Character . 3-27 3.2.2.7.12 Getting Data From The Keyboard . . . . . . 3-28 3.2.2.7.13 Getting The Specified Function/Arrow Key From The List . . . . . . . . . . . . . . 3-30 3.2.2.7.14 Getting The Name Of A Function Key . . . . 3-32 3.2.2.7.15 Ringing The Terminal Bell . . . . . . . . 3-33 3.2.2.8 Errors . . . . . . . . . . . . . . . . . . . 3-33 3.2.2.9 Exceptions . . . . . . . . . . . . . . . . . 3-33 3.2.2.10 The Ada Source . . . . . . . . . . . . . . . 3-33 3.2.3 The Page Terminal Package . . . . . . . . . . 3-35 3.2.3.1 Introduction . . . . . . . . . . . . . . . . 3-35 3.2.3.2 The Object Name . . . . . . . . . . . . . . 3-35 3.2.3.3 Abstract . . . . . . . . . . . . . . . . . . 3-35 3.2.3.4 Parameters . . . . . . . . . . . . . . . . . 3-35 3.2.3.5 Local Constants, Types, And Variables . . . 3-35 3.2.3.6 Selectors (Functions) . . . . . . . . . . . 3-36 3.2.3.6.1 Determining The Active Position . . . . . 3-37 3.2.3.6.2 Determining The Size Of The Display . . . 3-38 3.2.3.6.3 Determining The Validity Of A Character . 3-39 3.2.3.6.4 Getting The Number Of Typed Function/Arrow Keys . . . . . . . . . . . . . . . . . . . 3-40 3.2.3.7 Actors (Procedures) . . . . . . . . . . . . 3-41 3.2.3.7.1 Opening A Page Terminal . . . . . . . . . 3-41 3.2.3.7.2 Closing A Page Terminal . . . . . . . . . 3-43 3.2.3.7.3 Setting The Current Position . . . . . . . 3-44 3.2.3.7.4 Deleting A Character . . . . . . . . . . . 3-45 3.2.3.7.5 Deleting A Line . . . . . . . . . . . . . 3-46 3.2.3.7.6 Erasing Areas In The Display . . . . . . . 3-47 3.2.3.7.7 Erasing Areas In Lines . . . . . . . . . . 3-48 3.2.3.7.8 Entering Insert Character Mode . . . . . . 3-49 3.2.3.7.9 Exiting Insert Character Mode . . . . . . 3-50 3.2.3.7.10 Inserting A Line . . . . . . . . . . . . . 3-51 3.2.3.7.11 Selecting The Graphic Rendition . . . . . 3-52 3.2.3.7.12 Setting A Horizontal Tab . . . . . . . . . 3-53 3.2.3.7.13 Clearing A Horizontal Tab . . . . . . . . 3-54 3.2.3.7.14 Performing A Horizontal Tab . . . . . . . 3-55 3.2.3.7.15 Writing Data To The Terminal . . . . . . . 3-56 3.2.3.7.16 Updating The Screen With Insert/Delete Line 3-57 3.2.3.7.17 Updating The Screen Without Insert/Delete Line . . . . . . . . . . . . . . . . . . . 3-58 3.2.3.7.18 Redrawing The Screen Complete . . . . . . 3-59 3.2.3.7.19 Updating A Line . . . . . . . . . . . . . 3-60 3.2.3.7.20 Getting Data From The Keyboard . . . . . . 3-61 3.2.3.7.21 Getting The Specified Function/Arrow Key From The List . . . . . . . . . . . . . . 3-63 3.2.3.7.22 Getting The Name Of A Function Key . . . . 3-65 3.2.3.7.23 Ringing The Terminal Bell . . . . . . . . 3-66 3.2.3.8 Errors . . . . . . . . . . . . . . . . . . . 3-66 3.2.3.9 Exceptions . . . . . . . . . . . . . . . . . 3-66 3.2.3.10 The Ada Source . . . . . . . . . . . . . . . 3-66 3.2.4 The Form Terminal Package . . . . . . . . . . 3-69 3.2.4.1 Introduction . . . . . . . . . . . . . . . . 3-69 3.2.4.2 The Object Name . . . . . . . . . . . . . . 3-69 3.2.4.3 Abstract . . . . . . . . . . . . . . . . . . 3-69 Page 3 3.2.4.4 Parameters . . . . . . . . . . . . . . . . . 3-69 3.2.4.5 Local Constants, Types, And Variables . . . 3-69 3.2.4.6 Selectors (Functions) . . . . . . . . . . . 3-70 3.2.4.6.1 Retrieving The Current Position . . . . . 3-70 3.2.4.6.2 Determining The Size Of The Display . . . 3-71 3.2.4.6.3 Determining The Form Status . . . . . . . 3-72 3.2.4.6.4 Determining The Termination Key . . . . . 3-73 3.2.4.7 Actors (Procedures) . . . . . . . . . . . . 3-74 3.2.4.7.1 Opening A Form Terminal . . . . . . . . . 3-74 3.2.4.7.2 Closing A Form Terminal . . . . . . . . . 3-76 3.2.4.7.3 Setting The Current Position . . . . . . . 3-77 3.2.4.7.4 Defining Qualified Areas . . . . . . . . . 3-78 3.2.4.7.5 Clearing A Qualified Area . . . . . . . . 3-79 3.2.4.7.6 Tabbing To The Next Qualified Area . . . . 3-80 3.2.4.7.7 Writing Data To The Terminal . . . . . . . 3-81 3.2.4.7.8 Reading Data From Qualified Areas . . . . 3-82 3.2.4.7.9 Erasing A Qualified Area . . . . . . . . . 3-83 3.2.4.7.10 Erasing The Display Screen . . . . . . . . 3-84 3.2.4.7.11 Activating A Form For Input . . . . . . . 3-85 3.2.4.8 Errors . . . . . . . . . . . . . . . . . . . 3-85 3.2.4.9 Exceptions . . . . . . . . . . . . . . . . . 3-85 3.2.4.10 The Ada Source . . . . . . . . . . . . . . . 3-85 3.2.5 The Virtual Terminal Content Package . . . . . 3-87 3.2.5.1 Introduction . . . . . . . . . . . . . . . . 3-87 3.2.5.2 The Object Name . . . . . . . . . . . . . . 3-87 3.2.5.3 Abstract . . . . . . . . . . . . . . . . . . 3-87 3.2.5.4 Parameters . . . . . . . . . . . . . . . . . 3-87 3.2.5.5 Local Constants, Types, And Variables . . . 3-87 3.2.5.6 Selectors (Functions) . . . . . . . . . . . 3-88 3.2.5.7 Actors (Procedures) . . . . . . . . . . . . 3-89 3.2.5.8 Errors . . . . . . . . . . . . . . . . . . . 3-89 3.2.5.9 Exceptions . . . . . . . . . . . . . . . . . 3-89 3.2.5.10 The Ada Source . . . . . . . . . . . . . . . 3-89 3.2.6 The Virtual Terminal Keyboard Input Package . 3-91 3.2.6.1 Introduction . . . . . . . . . . . . . . . . 3-91 3.2.6.2 The Object Name . . . . . . . . . . . . . . 3-91 3.2.6.3 Abstract . . . . . . . . . . . . . . . . . . 3-91 3.2.6.4 Parameters . . . . . . . . . . . . . . . . . 3-91 3.2.6.5 Local Constants, Types, And Variables . . . 3-91 3.2.6.6 Selectors (Functions) . . . . . . . . . . . 3-92 3.2.6.6.1 Getting The Number Of Typed Function/Arrow Keys . . . . . . . . . . . . . . . . . . . 3-92 3.2.6.7 Actors (Procedures) . . . . . . . . . . . . 3-93 3.2.6.7.1 Getting Data From The Keyboard . . . . . . 3-93 3.2.6.7.2 Getting The Specified Function/Arrow Key From The List . . . . . . . . . . . . . . 3-95 3.2.6.7.3 Getting The Name Of A Function Key . . . . 3-97 3.2.6.8 Errors . . . . . . . . . . . . . . . . . . . 3-97 3.2.6.9 Exceptions . . . . . . . . . . . . . . . . . 3-97 3.2.6.10 The Ada Source . . . . . . . . . . . . . . . 3-98 3.2.7 The Redisplay Package . . . . . . . . . . . . 3-99 3.2.7.1 Introduction . . . . . . . . . . . . . . . . 3-99 3.2.7.2 The Object Name . . . . . . . . . . . . . . 3-99 3.2.7.3 Abstract . . . . . . . . . . . . . . . . . . 3-99 3.2.7.4 Parameters . . . . . . . . . . . . . . . . . 3-99 Page 4 3.2.7.5 Local Constants, Types, And Variables . . . 3-99 3.2.7.6 Selectors (Functions) . . . . . . . . . . . 3-99 3.2.7.7 Actors (Procedures) . . . . . . . . . . . . 3-100 3.2.7.7.1 Redisplay_screen_with_movement . . . . . . 3-100 3.2.7.7.2 Redisplay_screen_with_redraw . . . . . . . 3-101 3.2.7.7.3 Redisplay_line_with_movement . . . . . . . 3-102 3.2.7.7.4 Redisplay_line_with_redraw . . . . . . . . 3-103 3.2.7.7.5 Redraw_screen . . . . . . . . . . . . . . 3-104 3.2.7.8 Errors . . . . . . . . . . . . . . . . . . . 3-105 3.2.7.9 Exceptions . . . . . . . . . . . . . . . . . 3-105 3.2.7.10 The Ada Source . . . . . . . . . . . . . . . 3-105 3.2.8 The Driver Package Specification . . . . . . . 3-106 3.2.8.1 Introduction . . . . . . . . . . . . . . . . 3-106 3.2.8.2 The Object Name . . . . . . . . . . . . . . 3-106 3.2.8.3 Abstract . . . . . . . . . . . . . . . . . . 3-106 3.2.8.4 Parameters . . . . . . . . . . . . . . . . . 3-106 3.2.8.5 Local Constants, Types, And Variables . . . 3-106 3.2.8.6 Selectors (Functions) . . . . . . . . . . . 3-106 3.2.8.7 Actors (Procedures) . . . . . . . . . . . . 3-107 3.2.8.7.1 Initializeing The Virtual Terminal . . . . 3-107 3.2.8.7.2 Closing The Virtual Terminal . . . . . . . 3-109 3.2.8.7.3 Interpreting ANSI Character Sequences . . 3-110 3.2.8.8 Errors . . . . . . . . . . . . . . . . . . . 3-112 3.2.8.9 Exceptions . . . . . . . . . . . . . . . . . 3-112 3.2.8.10 The Ada Source . . . . . . . . . . . . . . . 3-112 3.2.9 The Driver Package Body . . . . . . . . . . . 3-113 3.2.9.1 Introduction . . . . . . . . . . . . . . . . 3-113 3.2.9.2 The Object Name . . . . . . . . . . . . . . 3-113 3.2.9.3 Abstract . . . . . . . . . . . . . . . . . . 3-113 3.2.9.4 Parameters . . . . . . . . . . . . . . . . . 3-113 3.2.9.5 Local Constants, Types, And Variables . . . 3-113 3.2.9.6 Actors (Procedures) . . . . . . . . . . . . 3-114 3.2.9.6.1 Erasing To The End Of The Screen . . . . . 3-114 3.2.9.6.2 Erasing To The End Of A Line . . . . . . . 3-115 3.2.9.6.3 Moving The Cursor . . . . . . . . . . . . 3-116 3.2.9.6.4 Inserting A Line . . . . . . . . . . . . . 3-117 3.2.9.6.5 Deleting A Line . . . . . . . . . . . . . 3-118 3.2.9.6.6 Deleting A Character . . . . . . . . . . . 3-119 3.2.9.6.7 Procedure Beep . . . . . . . . . . . . . . 3-120 3.2.9.6.8 Writing Data To The Actual Terminal . . . 3-121 3.2.9.6.9 Moving The Cursor To A New Line . . . . . 3-122 3.2.9.6.10 Turning On Highlighting . . . . . . . . . 3-123 3.2.9.6.11 Turning Off Highlighting . . . . . . . . . 3-124 3.2.9.6.12 Entering Character Insert Mode . . . . . . 3-125 3.2.9.6.13 Exiting Character Insert Mode . . . . . . 3-126 3.2.9.6.14 Scrolling The Actual Display Up . . . . . 3-127 3.2.9.6.15 Scrolling The Actual Display Down . . . . 3-128 3.2.9.7 Errors . . . . . . . . . . . . . . . . . . . 3-128 3.2.9.8 Exceptions . . . . . . . . . . . . . . . . . 3-128 3.2.9.9 The Ada Source . . . . . . . . . . . . . . . 3-128 3.2.10 The TCF Package . . . . . . . . . . . . . . . 3-130 3.2.10.1 Introduction . . . . . . . . . . . . . . . . 3-130 3.2.10.2 Abstract . . . . . . . . . . . . . . . . . . 3-130 3.2.10.3 Parameters . . . . . . . . . . . . . . . . . 3-130 3.2.10.4 Local Constants, Types, And Variables . . . 3-130 Page 5 3.2.10.5 Selectors (Functions) . . . . . . . . . . . 3-131 3.2.10.6 Actors (Procedures) . . . . . . . . . . . . 3-131 3.2.10.6.1 Initialize The Terminal Capabilities File 3-132 3.2.10.7 Errors . . . . . . . . . . . . . . . . . . . 3-133 3.2.10.8 Exceptions . . . . . . . . . . . . . . . . . 3-133 3.2.10.9 The Ada Source . . . . . . . . . . . . . . . 3-133 3.2.11 The System Dependent Package SYSDEP . . . . . 3-136 3.2.11.1 Introduction . . . . . . . . . . . . . . . . 3-136 3.2.11.2 The Object Name . . . . . . . . . . . . . . 3-136 3.2.11.3 Abstract . . . . . . . . . . . . . . . . . . 3-136 3.2.11.4 Selectors (Functions) . . . . . . . . . . . 3-137 3.2.11.4.1 Determining The Validity Of A Character . 3-137 3.2.11.5 Actors (Procedures) . . . . . . . . . . . . 3-138 3.2.11.5.1 Opening The Physical Terminal . . . . . . 3-138 3.2.11.5.2 Closing The Physical Terminal . . . . . . 3-139 3.2.11.5.3 Writing Data To The Physical Terminal . . 3-140 3.2.11.5.4 Reading Data From The Terminal Keyboard . 3-141 3.2.11.5.5 Retrieving The TCF Name . . . . . . . . . 3-142 3.2.11.5.6 Retrieving The Terminal's Name . . . . . . 3-143 3.2.11.6 Errors . . . . . . . . . . . . . . . . . . . 3-143 3.2.11.7 Exceptions . . . . . . . . . . . . . . . . . 3-143 3.2.11.8 The Ada Source . . . . . . . . . . . . . . . 3-143 3.3 STORAGE AND PROCESSING ALLOCATION . . . . . . . 3-145 3.4 PROGRAM FUNCTIONAL FLOW CONTROL . . . . . . . . 3-145 3.4.1 General . . . . . . . . . . . . . . . . . . . 3-145 3.4.2 Keyboard Data . . . . . . . . . . . . . . . . 3-145 3.4.3 User Program Generated Data . . . . . . . . . 3-146 3.4.4 Program Interrupt Control . . . . . . . . . . 3-148 3.4.5 Subprogram Reference Control . . . . . . . . . 3-148 3.4.6 Special Control Features . . . . . . . . . . . 3-148 3.5 PROGRAMMING GUIDELINES . . . . . . . . . . . . . 3-149 3.5.1 Development Environment . . . . . . . . . . . 3-149 3.5.2 Ada Programming Standards . . . . . . . . . . 3-149 3.5.2.1 Introduction . . . . . . . . . . . . . . . . 3-149 3.5.2.2 Prologue Documentation . . . . . . . . . . . 3-149 3.5.2.3 Naming Conventions . . . . . . . . . . . . . 3-151 3.5.2.4 Declarations Usage . . . . . . . . . . . . . 3-152 3.5.2.4.1 Commenting Declarations . . . . . . . . . 3-152 3.5.2.4.2 Declaration Formatting . . . . . . . . . . 3-152 3.5.2.4.3 Use Of Constants . . . . . . . . . . . . . 3-154 3.5.2.4.4 Strong Typing . . . . . . . . . . . . . . 3-155 3.5.2.5 Coding Conventions . . . . . . . . . . . . . 3-156 3.5.2.5.1 Attributes . . . . . . . . . . . . . . . . 3-156 3.5.2.5.2 Upper/Lower Case Usage . . . . . . . . . . 3-156 3.5.2.5.3 Statement Formatting For Readability . . . 3-156 3.5.2.5.4 Subprogram Usage And Formatting . . . . . 3-159 3.5.2.5.5 Packages, Tasks And Generics . . . . . . . 3-161 3.5.2.5.6 Complex Expressions . . . . . . . . . . . 3-162 3.5.2.5.7 Labels And GOTOs . . . . . . . . . . . . . 3-162 3.5.2.5.8 Task Termination . . . . . . . . . . . . . 3-162 3.5.2.5.9 Exceptions . . . . . . . . . . . . . . . . 3-162 3.5.3 Program Version Identification And CM . . . . 3-164 Page 6 CHAPTER 4 QUALITY ASSURANCE CHAPTER 5 NOTES APPENDIX A THE TERMINAL CAPABILITIES FILE (TCF) A.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . A-1 A.2 CAPABILITIES . . . . . . . . . . . . . . . . . . . A-1 A.2.1 Basic Capabilities . . . . . . . . . . . . . . . A-4 A.2.2 Cursor Addressing . . . . . . . . . . . . . . . A-4 A.2.3 Area Clears . . . . . . . . . . . . . . . . . . A-5 A.2.4 Insert/Delete Line . . . . . . . . . . . . . . . A-5 A.2.5 Insert/Delete Character . . . . . . . . . . . . A-5 A.2.6 Highlighting, Underlining, And Visible Bells . . A-6 A.2.7 Function Keys . . . . . . . . . . . . . . . . . A-6 A.2.8 Initialization . . . . . . . . . . . . . . . . . A-6 APPENDIX B THE RECOGNIZED ANSI X3.64 SEQUENCES APPENDIX C APSE DEPENDENCIES C.1 INTEROPERABILITY AND TRANSPORTABILITY . . . . . . C-1 C.1.1 Terminal Communications . . . . . . . . . . . . C-1 APPENDIX D GLOSSARY CHAPTER 1 INTRODUCTION 1.1 PURPOSE This program design specification presents the detailed design of the ANSI compatible Virtual Terminal. It also establishes the programming guidelines and quality assurance provisions. 1.2 SCOPE This document presents the complete design specification for the ANSI compatible Virtual Terminal. The design specification consists of: 1. a cross reference of the requirements as defined in the ANSI compatible Virtual Terminal proposal with the appropriate paragraph and sub-paragraph within this document, 2. a complete functional description of each program unit within the ANSI compatible Virtual Terminal. For each program unit the following information is supplied (where applicable): a. an introduction, b. the name, c. an abstract, d. the input and output parameters, e. the local variables, types, and constants, f. the selector functions, g. the actor procedures, h. a complete description of the possible errors that could occur, (including a semantic description of the conditions which raise any exceptions), i. the exceptions raised and handled, and the semantic actions associated with them, (exceptions are not used exclusively for error handling; the semantics associated with those that have INTRODUCTION Page 1-2 SCOPE 16 Nov 84 other functionality are described here), j. the Ada source code specification for the module. The local variables and types, selector functions, and actor procedures are only included in the package specifications. They are not applicable for the procedures, tasks and functions in the packages, as these are implementation details. 3. the syntax and semantics of all the user interfaces within the ANSI compatible Virtual Terminal, 4. a complete definition of all the data and file structures that the ANSI compatible Virtual Terminal creates and uses in its functioning, 5. programming guidelines, 6. quality assurance. 1.2.1 Summary 1.2.1.1 Problem Statement - The character-imaging computer terminal, consisting of a display device and keyboard, is the most widely used means of communicating with computer systems. Even now, with relatively well developed techniques for device independence, programs tend to be targeted for either specific character-imaging computer terminals or a very small subset of character-imaging computer terminals. A complete intermediate-level virtualization of a character-imaging computer terminal will promote program transportability, high level terminal abstractions, and maximum flexibility for a tool writer. If this intermediate-level virtualization conforms to an existing standard for the device characteristics of the character-imaging computer terminal (ANSI X3.64-1979), there will be many advantageous side-effects [FRE83 ]: 1. The virtualization will closely match the functional characteristics of the conforming character imaging computer terminals, 2. the virtualization will be more widely accepted, 3. device independence can be promoted, 4. upward-compatibility of the virtualization will more closely follow the upward-compatibility of the standard. INTRODUCTION Page 1-3 Objective 16 Nov 84 1.2.1.2 Objective - The objectives in implementing an ANSI X3.64 compatible virtual terminal in Ada are: 1. provide an interface to the terminal that is device independent, 2. enhance transportability of application programs that use the virtual terminal, 3. promote upward compatibility with the acknowledged standard as it is extended to cover advances in terminal hardware, 4. provide the tool- and application-writer with an extensive set of terminal control functions that closely match the functional characteristics of most computers terminals on the market, 5. provide a level of interface to support the interception of the flow of characters to and from the computer terminal 6. provide valuable feedback concerning the CAIS V1.1 Section 7.1. 1.2.1.3 Scope - This virtual terminal will use the CAIS V1.1 Section 7.1 as the framework for the design. CHAPTER 2 APPLICABLE DOCUMENTS 2.1 GOVERNMENT STANDARDS The following documents of the exact issue shown form a part of this specification to the extent specified herein. In the event of conflict between the documents referenced herein and the contents of this specification, the contents of this specification shall be considered a superceding requirement. [DOD83 ] United States Department of Defense, "Reference Manual for the Ada Programming Language Draft, Revised MIL-STD-1815A," February 1983. [NAVY78] Navy, "Weapon System Software Development, Navy MIL-STD-1679," December 1978. [NAVY80] Navy, "Data Item Description, Program Design Specification, Navy DI-E-2138," November 1978. [USAF76] Data Item Description DI-E-30112 (USAF), Computer Program Listings, 10 March 1976. 2.2 GOVERNMENT SPECIFICATIONS The following documents of the exact issue shown form a part of this specification to the extent specified herein. In the event of conflict between the document referenced herein and the contents of this specification, the contents of this specification shall be considered a superceding requirement. [INT81A] Intermetrics Inc., "Draft IR-676 Ada System Specification for Ada Integrated Environment Type A," Wakefield, MA, March 1981. [INT81B] Intermetrics Inc., "Draft IR-677 Computer Program Development Specification for Ada Integrated Environment: Ada Compiler Phases Type B5," Wakefield, MA, March 1981. APPLICABLE DOCUMENTS Page 2-2 GOVERNMENT SPECIFICATIONS 16 Nov 84 [INT81C] Intermetrics Inc., "Draft IR-678 Computer Program Development Specification for Ada Integrated Environment: KAPSE/Database Type B5," Wakefield, MA, March 1981. [INT81D] Intermetrics Inc., "Draft IR-679 Computer Program Development Specification for Ada Integrated Environment: MAPSE Command Processor Type B5," Wakefield, MA, March 1981. [INT81E] Intermetrics Inc., "Draft IR-680 Computer Program Development Specification for Ada Integrated Environment: MAPSE Generation and Support Type B5," Wakefield, MA, March 1981. [INT81F] Intermetrics Inc., "Draft IR-681 Computer Program Development Specification for Ada Integrated Environment: Program Integration Facilities Type B5," Wakefield, MA, March 1981. [INT81G] Intermetrics Inc., "Draft IR-682 Computer Program Development Specification for Ada Integrated Environment: MAPSE Debugging Facilities Type B5," Wakefield, MA, March 1981. [INT81H] Intermetrics Inc, "Draft IR-683 Computer Program Development Specification for Ada Integrated Environment: MAPSE Text Editor Type B5," Wakefield, MA, March 1981. [INT81J] Intermetrics Inc., "IR-684 Ada Integrated Environment (AIE) Design Rational: Technical Report (Interim)," Wakefield, MA, March 1981. [INT82 ] Intermetrics Inc., "IR-678-1 Computer Program Development Specification for Ada Integrated Environment: KAPSE/Database Type B5," Wakefield, MA, June 1982. [SOF81A] SofTech Inc., "Draft Ada Language System Specification," Waltham, MA, June 1981. [SOF81B] SofTech Inc., "Draft Ada Language System VAX-11/780 VAX/VMS Runtime Support Library B5 Specification," Waltham, MA, July 1981. [SOF81C] SofTech Inc., "Preliminary Draft Ada Language System KAPSE B5 Specification," Waltham, MA, August 1981. [SOF82 ] SofTech Inc., "Draft Ada Language System Specification," Waltham, MA, August 1982. APPLICABLE DOCUMENTS Page 2-3 OTHER GOVERNMENT DOCUMENTS 16 Nov 84 2.3 OTHER GOVERNMENT DOCUMENTS The following documents of the latest issue per date of this PDS form a part of this specification. In the event of conflict between the document referenced herein and the contents of this specification, the contents of this specification shall be considered a superceding requirement. [TI82 ] Texas Instruments, "Proposal for Development of Ada Software Tools and Interface Standards," Lewisville, TX, February 1982. [TI83A ] Texas Instruments, "AIM Program Performance Specification," Lewisville, TX, 18 May 1983. [TI83B ] Texas Instruments, "APSE Interactive Monitor - Interim Report on Interface Analysis and Software Engineering Techniques," Lewisville, TX, 16 May 1983. [TI83C ] Texas Instruments, "APSE Interactive Monitor (AIM) Acceptance Test Plan", Contract N66001-82-C-0440, July 1983. [TI83D ] Texas Instruments, "APSE Interactive Monitor (AIM) Computer Program Test Specification", Contract N66001-82-C-0440, July 1983. [TI83E ] Texas Instruments, "APSE Interactive Monitor (AIM) Acceptance Test Procedures", Contract N66001-82-C-0440, July 1983. [TI83F ] Texas Instruments, "Software Quality Assurance Plan for APSE Interactive Monitor Program", 28 March 1983. [TI83G ] Texas Instruments, "APSE Interactive Monitor (AIM) Configuration Management Plan", 28 March 1983. 2.4 OTHER PUBLICATIONS [ABB82 ] Abbott, Russ, "Ada Style Guide (draft)," January 1982. [AKIN81] Akin, T. Allen, "Virtual Terminal Handler Preliminary Quick Reference," School of Information and Computer Science, Georgia Institute of Technology, April 1981. [AND82 ] Anderson, Peter J., "A Design Language Based On Ada," School of Computer Science and Technology, Rochester Institute of Technology, September 1982. APPLICABLE DOCUMENTS Page 2-4 OTHER PUBLICATIONS 16 Nov 84 [ANSI73] American National Standards Institute, "American National Standard Graphic Representation of the Control Characters of American National Standard Code for Information Interchange (ANSI Standard X3.32-1973)," July 1973. [ANSI74] American National Standards Institute, "American National Standard Code Extension Techniques for Use with the 7-Bit Coded Character Set of American National Standard Code for Information Interchange (ANSI Standard X3.41-1974)," May 1974. [ANSI77] American National Standards Institute, American National Standard Code for Information Interchange (ANSI Standard X3.4-1977)," June 1977. [ANSI79] American National Standards Institute, "American National Standard Additional Controls for Use with American National Standard Code for Information Interchange (ANSI Standard X3.64-1979)," July 1979. [APSE82] "Working Paper: Ada Programming Support Environment (APSE) Requirements for Interoperability and Transportability and Design Criteria for Standard Interface Specifications," Not Approved, October 1982. [ARPA1 ] ARPANET communication between John Foreman and Grady Booch, Subject: Review of Ada programming standards, May 10, 1983. [ARPA2 ] ARPANET communication between John Foreman and Grady Booch, Subject: Discussion of using attributes and constants, May 11, 1983. [ARPA3 ] ARPANET communication between John Foreman and Grady Booch, Subject: Discussion of using attributes and constants, May 11, 1983. [ARPA4 ] ARPANET communication between John Foreman and John Bailey, Subject: Review of Ada programming standards, May 13, 1983. [ARPA5 ] ARPANET communication between John Foreman and Grady Booch, Subject: Discussion of return statement usage, May 16, 1983. [ARPA6 ] ARPANET communication between John Foreman and Grady Booch, Subject: Error in text, page 270, May 10, 1983. [BALL81] Ball, J. Eugene, "Canvass: The Spice Graphics Package" (Spice Document s108), Carnegie Mellon University, Department of Computer Science, August 1981. APPLICABLE DOCUMENTS Page 2-5 OTHER PUBLICATIONS 16 Nov 84 [BOO83 ] Booch, Grady, Software Engineering With Ada, Benjamin/Cummings Publishing Co, Inc. Menlo Park, Ca, 1983. [CSC82A] Computer Sciences Corporation, "Configuration Management System Program Performance Specification ," Falls Church, VA, 8 December 1982. Prepared for Naval Ocean Systems Center under contract N00123-80-D-0364. [CSC82B] Computer Sciences Corporation, "Configuration Management System Interim Report on Interface Analysis," Falls Church, VA, August 1982. Prepared for Naval Ocean Systems Center under contract N00123-80-D-0364. [DEC82 ] Digital Equipment Corporation, "VAX-11 Utilities Reference Manual - Help Libraries", Maynard, MA, May 1982. [FORE83] Foreman, John, "COBOL Programming Standards", University of Dallas Graduate School of Management, Feb 1983. [FRA ] Franck, R., "Design and Implementation of a Virtual Terminal for a Real-time Application System" [FRE83 ] Freedman, Roy S., "Of Mice and CLP's", KITIA Working Group 1 Working Paper, April 1983 [GAR83 ] Gargaro, Anthony, "Program Invocation and Control", KITIA Working Group 1 Interim Technical Note, April 1983. [GREN80] Greninger, Lars and Roberts, Roger, "Considerations for a Local Virtual Terminal Interface," Presented at IEEE Conference, September 1980. [HON82A] Honeywell Information Systems Inc., Multics Programmers' Manual -- Communications Input/Output, July 1982. [HON82B] Honeywell Information Systems Inc., Multics Menu Creation Facilities, February 1983. [HON83 ] Honeywell Information Systems Inc., Multics Administrators' Manual -- Communications, February 1983. [INT83 ] Ada Style Manual, Intellimac, Inc, January 1983. [INTR82] Intermetrics IR-696-2, pp.82-86, Intermetrics, Inc, Cambridge, Mass, November 12, 1982. [ISO642] International Standards Organization, Standard number: ISO DP 6429, "Additional Control Functions for Character Imaging Devices (Draft)," Not approved, April 1982. APPLICABLE DOCUMENTS Page 2-6 OTHER PUBLICATIONS 16 Nov 84 [JOY81 ] Joy, W. and Horton, M., "TERMCAP," UNIX Programmer's ____ ____________ Manual, Seventh Edition, Berkley release 4.1, June 1981. ______ [KARL81] Winterstein, Persch, Drossopoulou, and Dausmann, Ada Documentation and Programming Guidelines, University of Karlsruhe, Federal Republic of Germany, Sept 1981. [KRA81 ] Krasner, Glenn, "The Smalltalk-80 Virtual Machine," Byte, August 1981. ____ [LAN79 ] Lantz, Keith and Rashid, Richard, "Virtual Terminal Management in a Multiple Process Environment," Proceedings of the Seventh Symposium on Operating Systems (ACM), December 1979. [LDI81 ] London Department of Industry, "Report on the Study of an Ada Based System Development Methodology," London, 1981. [MAG79 ] Magnee, F., Endrizzi, A., and Day, J, "A Survey of Terminal Protocols," Computer Networks, 1979, pp ________ ________ 299-314. [MEY81 ] Meyrowitz, Norman and Moser, Margaret, "Bruwin: An Adaptable Design Strategy for Window Manager/Virtual Terminal Systems," Department of Computer Science, Brown University, December 1981. [NOT ] Notkin, David S., Habermann, A. Nico, "Software Development Environment Issues as Related to Ada," Department of Computer Science, Carnegie-Mellon University. [SCH78 ] Schicker, P. and Duenki, A., "The Virtual Terminal Definition," Computer Networks, 1978, pp 429-441. ________ ________ [STA82 ] Standish, Thomas A., "A Philosophy for a Tool Extension Paradigm (Preliminary Position Paper)" Programming Environment Project, Computer Science Department, University of California, Irvine, CA [STE81 ] Stenning, Vic, Et Al., "The Ada Environment: A Perspective," Computer, Volume 14, number 6, June 1981, ________ pp 26-34, 36. [SUK81 ] Sukamar, Srinivas and Wiese, John D, "Hardware and Firmware Support for Four Virtual Terminals in One Display Station," Hewlett-Packard Journal, March 1981. _______________ _______ [TAF82 ] Taft, S. Tucker, "Portability and Extensibility in the Kernel and Database of a Programming Support Environment," Intermetrics, March 1982. APPLICABLE DOCUMENTS Page 2-7 OTHER PUBLICATIONS 16 Nov 84 [TAN81 ] Tanenbaum, A.S., "Computer Networks," Prentice-Hall Inc., Englewood Cliffs, New Jersey, 1981, pp 427- 429. [TAJ79 ] Tajima, Takashi and Katsuyama, Yoshiki, "Layered and Parametric Approach to Terminal Virtualization," Presented at International Conference on Communications, Boston, MA, June 1979. [TI81A ] Texas Instruments, "Ada Integrated Environment," Lewisville, TX, March 1981. Prepared for Rome Air Development Center (RADC) under DoD Contract F30602-80-C-0293. [TI81B] Equipment Group Programming Standards for Computer Programs, Advanced Computer Systems Laboratory, Texas Instruments, July 1981. [THA82 ] Thall, Richard, "The KAPSE for the Ada Language System," SofTech Inc, Proceedings of the Adatec conference on Ada, October 1982. [WOL81 ] Wolfe, Martin I., et al., "The Ada Language System," Computer, Volume 14, number 6, June 1981, pp 37-45. ________ CHAPTER 3 REQUIREMENTS 3.1 FUNCTION ALLOCATION 3.1.1 Requirement The requirements as specified in the NOSC Virtual Terminal proposal are itemized here. Included is the proposal page number, the requirement in textual form, and the PDS page number that addresses that requirement. REQUIREMENTS * Page: 2-5 Each of the three terminal types will have a set of procedures and functions that may be used by the application programmer or software tool writer. * Page: 2-5 The scroll-mode virtual terminal provides such functionality as: 1. setting tab stops, 2. clearing tab stops, 3. moving to a tab stop, 4. moving to a new line, 5. moving to a new page, 6. writing characters and strings to the display, 7. reading characters and strings from the keyboard, 8. setting and resetting the echo on the terminal, 9. ringing the terminals bell. REQUIREMENTS Page 3-2 Requirement 16 Nov 84 * Page: 2-6 The page-mode virtual terminal provides all of the scroll-mode terminal's functionality plus those such as: 1. deleting characters from the display, 2. deleting lines from the display, 3. erasing characters from the display, 4. erasing between specific positions on the display, 5. inserting characters onto the display, 6. inserting lines onto the display, 7. setting the graphic rendition on the display. * Page: 2-6 The form-mode virtual terminal provides functionality such as: 1. defining qualified areas on the display, 2. clearing qualified areas on the display, 3. moving by tab stops on the display 4. erasing between specified positions on the display, 5. activating a form for user fill in, 6. reading characters and strings from the display buffer, 7. writing characters and strings to the display buffer, 8. retrieving the function key which signaled a full form. * Page: 2-7 The virtual terminal will have a four-layer structure. * Page: 2-7 The user layer contains the interface that the tool writer sees. This includes all the functions, procedures, abstract types, and exceptions. REQUIREMENTS Page 3-3 Requirement 16 Nov 84 * Page: 2-7 The simulation layer supplies the software simulation to create those functions that the physical terminal does not support out of those functions that the physical terminal does support. * Page: 2-7 The simulation layer is written in Ada to support changes and additions as required. * Page: 2-7 The translator/driver layer provides the mapping from device independent generic character codes into device specific character codes. * Page: 2-7 This layer incorporates a variation of the UNIX terminal capabilities database which is used to define the mapping. * Page: 2-7 The physical terminal layer contains the actual physical terminal. * Page: 2-7 Only the translator/driver layer has any knowledge of the exact type of terminal that exists. * Page: 2-7 The simulation layer only knows that specific functions are not available and must be simulated using other generic functions. * Page: 2-7 The user layer only knows that the terminal is of a particular class and level. * Page: 2-7 The generic character codes that are produced out of the simulation layer conform to ANSI standard X3.64 [ANS79]. REQUIREMENTS Page 3-4 Packages Overview 16 Nov 84 3.1.2 Packages Overview There are ten major packages in the virtual terminal. These are: * virtual_terminal - This is the package that the user of the virtual terminal sees and interfaces with. It contains the following packages: - scroll_terminal - provides a device-independent scroll-mode terminal interface. - page_terminal - provides a device-independent page_mode terminal interface. - form_terminal - provides a device-independent form-mode terminal interface. * vt_contents - provides the constants, types,and variables that describe a virtual terminal display screen. This is the internal representation that all scroll, page, and form terminal packages use as the display screen virtualization. * redisplay - a set of redisplay algorithms that the program can choose to use. Includes: . redisplay screen with movement . redisplay screen with redraw . redisplay line with movement . redisplay line with redraw * driver - accepts a subset of the ANSI X3.64 format codes and converts (as required) into the format for the particular actual terminal type. * vt_input - reads characters and strings directly from the terminal keyboard. A task awaits the output from the terminal and stores it into an internal buffer. * TCF - Terminal Capabilities File handler opens the TCF then reads the data about the particular terminal into its visible data structures, then closes the TCF. * SYSDEP - centralizes all actual reads and writes to the physical terminal. This package also isolates all SYStem DEPendencies. Only this package need be changed when rehosting this virtual terminal. Figure 1 gives the package structure. REQUIREMENTS Page 3-5 Packages Overview 16 Nov 84 NOSC Virtual Terminal Structure REQUIREMENTS Page 3-6 FUNCTION DESCRIPTION 16 Nov 84 3.2 FUNCTION DESCRIPTION 3.2.1 The Virtual Terminal Package 3.2.1.1 Introduction - This package defines the user program interface that can be used to interact with a computer terminal. 3.2.1.2 The Object Name - virtual_terminal 3.2.1.3 Abstract - Three packages are defined within this package scroll_terminal, page_terminal, and form_terminal. Each of these packages contain a set of object definitions, procedures, and functions that the user program can make use of to communicate with the terminal. The detailed design of each of these internal packages follows in 3 separate sections of this design document. 3.2.1.4 Parameters - None. 3.2.1.5 Local Constants, Types, And Variables - None. 3.2.1.6 Errors - See the individual packages. 3.2.1.7 Exceptions - See the individual packages. 3.2.1.8 The Ada Source - The Ada source for the entire virtual_terminal package appears here. The actual description of each of these packages will follow in seperate sections of the document. PACKAGE virtual_terminal IS 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 IS LIMITED PRIVATE; PROCEDURE open (name : IN OUT string ); PROCEDURE close; PROCEDURE set_position (position : IN positive); FUNCTION position RETURN positive; FUNCTION size RETURN positive; PROCEDURE set_tab; PROCEDURE clear_tab; REQUIREMENTS Page 3-7 The Ada Source 16 Nov 84 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; FUNCTION valid_character( item : IN character ) RETURN boolean; 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 positive; previous_position : OUT natural); PROCEDURE function_key_name key_identifier : IN positive; key_name : OUT string; last : OUT natural); PROCEDURE bell; uninitialized : EXCEPTION; name_error : EXCEPTION; tcf_error : EXCEPTION; unsupported_terminal : EXCEPTION; invalid_function_key : EXCEPTION; PRIVATE TYPE funtion_key_descriptor IS positive; END scroll_terminal; 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, REQUIREMENTS Page 3-8 The Ada Source 16 Nov 84 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 IS LIMITED 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); PROCEDURE open (name : IN OUT string ); 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); 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_with_movement; PROCEDURE update_screen_with_redraw; REQUIREMENTS Page 3-9 The Ada Source 16 Nov 84 PROCEDURE update_line; PROCEDURE redraw_screen; FUNCTION valid_character( item : IN character ) RETURN boolean; 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 positive; previous_position : OUT natural); PROCEDURE function_key_name key_identifier : IN positive; key_name : OUT string; last : OUT natural); PROCEDURE bell; uninitialized : EXCEPTION; name_error : EXCEPTION; tcf_error : EXCEPTION; unsupported_terminal : EXCEPTION; invalid_function_key : EXCEPTION; PRIVATE TYPE funtion_key_descriptor IS positive; END page_terminal; PACKAGE form_terminal IS 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, alphabetics); TYPE area_value IS (no_fill, fill_with_zeroes, fill_with_spaces); PROCEDURE open (name : IN string); PROCEDURE close; PROCEDURE set_position (position : IN xy_position); FUNCTION position RETURN xy_position; REQUIREMENTS Page 3-10 The Ada Source 16 Nov 84 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; value : IN area_value := no_fill); 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; -- exceptions END form_terminal; END virtual_terminal; REQUIREMENTS Page 3-11 The Scroll Terminal Package 16 Nov 84 3.2.2 The Scroll Terminal Package 3.2.2.1 Introduction - This package provides a device-independent scroll-terminal interface to a user's program. 3.2.2.2 The Object Name - scroll_terminal 3.2.2.3 Abstract - 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. 3.2.2.4 Parameters - None. 3.2.2.5 Local Constants, Types, And Variables - The enumeration type function_key_enum is defined here. This enumerated type defines the 4 arrow keys and 32 function keys. The private limited type function_key_descriptor is defined here. This type is used to traverse the function key list whose reference is returned from a call to scroll_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. The enumerated type function_key_enum identifies the function/arrow keys that are used in the function/arrow key handling procedures and functions. REQUIREMENTS Page 3-12 Selectors (Functions) 16 Nov 84 3.2.2.6 Selectors (Functions) - 3.2.2.6.1 Determining The Current Position - 3.2.2.6.1.1 Introduction - This function is called to get the current active position on the virtual terminal. 3.2.2.6.1.2 The Object Name - position 3.2.2.6.1.3 Abstract - Scroll_terminal.position returns a value of type positive that is the current active position on the virtual 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. 3.2.2.6.1.4 Parameters - None. 3.2.2.6.1.5 Local Constants, Types, And Variables - TBD. 3.2.2.6.1.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.6.1.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.6.1.8 The Ada Source - FUNCTION position RETURN positive; REQUIREMENTS Page 3-13 Determining The Terminal Size 16 Nov 84 3.2.2.6.2 Determining The Terminal Size - 3.2.2.6.2.1 Introduction - This function is called to determine the length of the scroll terminals line. 3.2.2.6.2.2 The Object Name - size 3.2.2.6.2.3 Abstract - 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. 3.2.2.6.2.4 Parameters - None. 3.2.2.6.2.5 Local Constants, Types, And Variables - TBD. 3.2.2.6.2.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.6.2.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.6.2.8 The Ada Source - FUNCTION size RETURN positive; REQUIREMENTS Page 3-14 Determining The Validity Of A Character 16 Nov 84 3.2.2.6.3 Determining The Validity Of A Character - 3.2.2.6.3.1 Introduction - This procedure is called to determine whether a particular character can be considered valid for this environment. 3.2.2.6.3.2 The Object Name - valid_character 3.2.2.6.3.3 Abstract - Scroll_terminal.valid_character is called to check if the character specified in the input parameter is one that can be used (and therefore considered valid) for this environment. Character that should be considered suspect include: * XON (CTRL-S) * XOFF (CTRL-Q) * (CTRL-Y) * (CTRL-C) To be safe, a tool writer should call this procedure for every character that they want to use in the application. Of course, if appropriately designed, the application should only need to call this procedure once for each offensive character (probably either at the beginning of the program, or just before the character's first use). 3.2.2.6.3.4 Parameters - There is one input parameter, item, which identifies the character that the user is interested in checking. A boolean value is returned. True indicates that the character is valid and can be used, false indicates that the charater should not be used. 3.2.2.6.3.5 Local Constants, Types, And Variables - TBD. 3.2.2.6.3.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.6.3.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.6.3.8 The Ada Source - FUNCTION valid_character( item : IN character ) RETURN boolean; REQUIREMENTS Page 3-15 Getting The Number Of Typed Function/Arrow Keys 16 Nov 84 3.2.2.6.4 Getting The Number Of Typed Function/Arrow Keys - 3.2.2.6.4.1 Introduction - This function is called to get the number of function/arrow keys that were returned from a call on scroll_terminal.get. 3.2.2.6.4.2 The Object Name - function_count 3.2.2.6.4.3 Abstract - 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. 3.2.2.6.4.4 Parameters - 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. 3.2.2.6.4.5 Local Constants, Types, And Variables - TBD 3.2.2.6.4.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.2.6.4.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 3.2.2.6.4.8 The Ada Source - FUNCTION function_count(keys : IN function_key_descriptor) RETURN natural; REQUIREMENTS Page 3-16 Actors (Procedures) 16 Nov 84 3.2.2.7 Actors (Procedures) - 3.2.2.7.1 Opening A Scroll Terminal - 3.2.2.7.1.1 Introduction - This procedure is called to open the scroll terminal. 3.2.2.7.1.2 The Object Name - open 3.2.2.7.1.3 Abstract - Scroll_terminal.open is called to perform initialization and define a scroll-mode virtual terminal for the user's program to make use of. This initialization consists of: 1. defining the necessary data structures within the virtual terminal to support a scroll terminal. 2. calling the driver package and initializing the needed data structures from the terminal capabilities file. 3. raising the necessary exceptions if the scroll terminal could not be opened. 3.2.2.7.1.4 Parameters - The name parameter contains the name of the actual terminal that the user is interfacing with. This may change from one invocation of the program to another. This name must match exactly (string and case) with the terminal name as defined in the terminal capabilities file. If the string parameter is of length zero then the virtual terminal will attempt to find the terminal name through a system dependent manner. This will be performed through a call to a procedure in the package SYSDEP. If the terminal name can be determined, then it will be returned from this call in the name parameter. The scroll terminal may have been previously opened. In this case the terminal is implicitly closed and reopened. No implicit update will be performed before the close operation. 3.2.2.7.1.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.1.6 Errors - Errors include: * passing in a name that does not appear in the terminal capabilities file. * if the terminal capabilities file is not available to read. * if the terminal does not have the needed capabilities to be a scroll terminal. REQUIREMENTS Page 3-17 Opening A Scroll Terminal 16 Nov 84 3.2.2.7.1.7 Exceptions - The exceptions raised are (respectively): * uninitialized * name_error * tcf_error * unsupported_terminal 3.2.2.7.1.8 The Ada Source - PROCEDURE open (name : IN string); REQUIREMENTS Page 3-18 Closing A Scroll Terminal 16 Nov 84 3.2.2.7.2 Closing A Scroll Terminal - 3.2.2.7.2.1 Introduction - This procedure is called to close the scroll terminal. 3.2.2.7.2.2 The Object Name - close 3.2.2.7.2.3 Abstract - Scroll_terminal.close closes the virtual terminal. If the virtual terminal was already closed, then no operation will occur. 3.2.2.7.2.4 Parameters - None. 3.2.2.7.2.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.2.6 Errors - None. 3.2.2.7.2.7 Exceptions - None. 3.2.2.7.2.8 The Ada Source - PROCEDURE close; REQUIREMENTS Page 3-19 Positioning The Cursor 16 Nov 84 3.2.2.7.3 Positioning The Cursor - 3.2.2.7.3.1 Introduction - This procedure is called to set the active position within the line. 3.2.2.7.3.2 The Object Name - set_position 3.2.2.7.3.3 Abstract - 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>"). 3.2.2.7.3.4 Parameters - The parameter position of type positive identifies the character position that the caller wishes the active position to be changed to. 3.2.2.7.3.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.3.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.7.3.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.7.3.8 The Ada Source - PROCEDURE set_position (position : IN positive); REQUIREMENTS Page 3-20 Setting A Horizontal Tab Stop 16 Nov 84 3.2.2.7.4 Setting A Horizontal Tab Stop - 3.2.2.7.4.1 Introduction - This procedure will set a horizontal tab at the current active position. 3.2.2.7.4.2 The Object Name - set_tab 3.2.2.7.4.3 Abstract - 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. 3.2.2.7.4.4 Parameters - None. 3.2.2.7.4.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.4.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.7.4.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.7.4.8 The Ada Source - PROCEDURE set_tab; REQUIREMENTS Page 3-21 Clearing A Horizontal Tab Stop 16 Nov 84 3.2.2.7.5 Clearing A Horizontal Tab Stop - 3.2.2.7.5.1 Introduction - This procedure is called to clear a horizontal tab stop at the active position. 3.2.2.7.5.2 The Object Name - clear_tab 3.2.2.7.5.3 Abstract - 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. 3.2.2.7.5.4 Parameters - None, 3.2.2.7.5.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.5.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.7.5.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.7.5.8 The Ada Source - PROCEDURE clear_tab; REQUIREMENTS Page 3-22 Horizontal Tab 16 Nov 84 3.2.2.7.6 Horizontal Tab - 3.2.2.7.6.1 Introduction - This procedure is called to move to the specified tab stop. 3.2.2.7.6.2 The Object Name - tab 3.2.2.7.6.3 Abstract - 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 an implicit call on new_line will be performed and the active position moved to the next tab stop on that line. If there are no tab stops set on the line, then the implicit new_line will be performed and the active position left at the beginning of the line. 3.2.2.7.6.4 Parameters - There is one parameter count of type positive. Count specifies the number of tab stops to move. The default value for the parameter is one. 3.2.2.7.6.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.6.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.7.6.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.7.6.8 The Ada Source - PROCEDURE tab (count : IN positive := 1); REQUIREMENTS Page 3-23 Moving To A New Line 16 Nov 84 3.2.2.7.7 Moving To A New Line - 3.2.2.7.7.1 Introduction - This procedure is called to move the active position to the beginning of the next line. 3.2.2.7.7.2 The Object Name - new_line 3.2.2.7.7.3 Abstract - 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. 3.2.2.7.7.4 Parameters - The single parameter count of type positive indicates the number of times the new_line should be performed. 3.2.2.7.7.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.7.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.7.7.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.7.7.8 The Ada Source - PROCEDURE new_line (count : IN positive := 1); REQUIREMENTS Page 3-24 Moving To A New Page 16 Nov 84 3.2.2.7.8 Moving To A New Page - 3.2.2.7.8.1 Introduction - This procedure is called to move the active position to a "new page". 3.2.2.7.8.2 The Object Name - new_page 3.2.2.7.8.3 Abstract - Scroll_terminal.new_page causes a new page operation to be performed. An implicit call to update is performed then the new page operation as defined in the terminal capabilities file is performed. Typically this new page operation is the output of a form feed but a user can tailor this to be anything that is needed. 3.2.2.7.8.4 Parameters - The number of new page operations that are to be performed are passed into the procedure through the single parameter count of type positive. The default for count is one. 3.2.2.7.8.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.8.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.7.8.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.7.8.8 The Ada Source - PROCEDURE new_page (count : IN positive := 1); REQUIREMENTS Page 3-25 Writing Data To A Terminal 16 Nov 84 3.2.2.7.9 Writing Data To A Terminal - 3.2.2.7.9.1 Introduction - This procedure is called to write either character data or string data to the scroll terminal. 3.2.2.7.9.2 The Object Name - put 3.2.2.7.9.3 Abstract - There are two versions of the procedure differing only by their parameters. 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. 3.2.2.7.9.4 Parameters - Each procedure has one parameter called item of types character and string. The string parameter is variable length. 3.2.2.7.9.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.9.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.7.9.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.7.9.8 The Ada Source - PROCEDURE put (item : IN character); PROCEDURE put (item : IN string); REQUIREMENTS Page 3-26 Updating The Terminal Display Line 16 Nov 84 3.2.2.7.10 Updating The Terminal Display Line - 3.2.2.7.10.1 Introduction - This procedure is called to force the internal representation of the line out to the actual terminal display. 3.2.2.7.10.2 The Object Name - update_line 3.2.2.7.10.3 Abstract - It is important to realize that the operations: * set_position * 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. 3.2.2.7.10.4 Parameters - None. 3.2.2.7.10.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.10.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.7.10.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.7.10.8 The Ada Source - PROCEDURE update_line; REQUIREMENTS Page 3-27 Determining The Validity Of A Character 16 Nov 84 3.2.2.7.11 Determining The Validity Of A Character - 3.2.2.7.11.1 Introduction - This procedure is called to determine whether a particular character can be considered valid for this Environment. 3.2.2.7.11.2 The Object Name - valid_character 3.2.2.7.11.3 Abstract - Scroll_terminal.valid_character is called to check if the character specified in the input parameter is one that can be used (and therefore considered valid) for this environment. Character that should be considered suspect include: * XON (CTRL-S) * XOFF (CTRL-Q) * (CTRL-Y) * (CTRL-C) To be safe, a tool writer should call this procedure for every character that they want to use in the application. Of course, if appropriately designed, the application should only need to call this procedure once for each offensive character (probably either at the beginning of the program, or just before the character's first use). 3.2.2.7.11.4 Parameters - There is one input parameter, item, which identifies the character that the user is interested in checking. A boolean value is returned. True indicates that the character is valid and can be used, false indicates that the charater should not be used. 3.2.2.7.11.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.11.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.7.11.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.7.11.8 The Ada Source - FUNCTION valid_character( item : IN character ) RETURN boolean; REQUIREMENTS Page 3-28 Getting Data From The Keyboard 16 Nov 84 3.2.2.7.12 Getting Data From The Keyboard - 3.2.2.7.12.1 Introduction - This procedure is called to get all the data typed at the keyboard since the last call on scroll_terminal.get or since the virtual terminal was opened. 3.2.2.7.12.2 The Object Name - get 3.2.2.7.12.3 Abstract - 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. 3.2.2.7.12.4 Parameters - 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 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). REQUIREMENTS Page 3-29 Getting Data From The Keyboard 16 Nov 84 3.2.2.7.12.5 Local Constants, Types, And Variables - TBD 3.2.2.7.12.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.2.7.12.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 3.2.2.7.12.8 The Ada Source - PROCEDURE get( data : OUT string; last : OUT natural; keys : OUT function_key_descriptor; timeout : IN duration := duration'last ); REQUIREMENTS Page 3-30 Getting The Specified Function/Arrow Key From The List 16 Nov 84 3.2.2.7.13 Getting The Specified Function/Arrow Key From The List - 3.2.2.7.13.1 Introduction - This procedure is called to get the specified function/arrow key from the list of function/arrow keys that were returned from a call on scroll_terminal.get. 3.2.2.7.13.2 The Object Name - function_key 3.2.2.7.13.3 Abstract - 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). 3.2.2.7.13.4 Parameters - The parameters are: 1. 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. 2. 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. 3. key_identifier - returns an enumerated type which identifies the function/arrow key as described in the terminal capabilities file. 4. 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: a. the function/arrow key was pressed before any of the other keys. In this case previous_position would return a zero. b. the functon key was the last key pressed. In this case the value returned would be the same as last. c. 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 REQUIREMENTS Page 3-31 Getting The Specified Function/Arrow Key From The List 16 Nov 84 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. 3.2.2.7.13.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.13.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. The index may indicate a function/arrow key that is illegal. 3.2.2.7.13.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. The exception invalid_function_key may be raised from this procedure. 3.2.2.7.13.8 The Ada Source - PROCEDURE function_key(keys : IN function_key_descriptor; index : IN positive; key_identifier : OUT function_key_enum; previous_position : OUT natural); REQUIREMENTS Page 3-32 Getting The Name Of A Function Key 16 Nov 84 3.2.2.7.14 Getting The Name Of A Function Key - 3.2.2.7.14.1 Introduction - The procedure is called to get the name of the function key (as it appears on the actual terminal keyboard). 3.2.2.7.14.2 The Object Name - function_key_name 3.2.2.7.14.3 Abstract - 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. 3.2.2.7.14.4 Parameters - The parameters are: 1. key_identifier - a value of enumerated type function_key_enum which identifies the function key of interest. 2. key_name - a string which is the function key name as it appears in the terminal capabilities file (exactly). 3. 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). 3.2.2.7.14.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.14.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.2.7.14.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception scroll_terminal.uninitialized will be raised. 3.2.2.7.14.8 The Ada Source - PROCEDURE function_key_name key_identifier : IN positive; key_name : OUT string; last : OUT natural); REQUIREMENTS Page 3-33 Ringing The Terminal Bell 16 Nov 84 3.2.2.7.15 Ringing The Terminal Bell - 3.2.2.7.15.1 Introduction - Bell causes the actual terminal's bell to ring. 3.2.2.7.15.2 The Object Name - bell 3.2.2.7.15.3 Abstract - Scroll_terminal.bell will cause the terminal's bell to ring immediately when called. There is no implicit update_line performed. If the user has defined the bell field in the terminal capabilities file, then that sequence will be output to the terminal. 3.2.2.7.15.4 Parameters - None. 3.2.2.7.15.5 Local Constants, Types, And Variables - TBD. 3.2.2.7.15.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.2.7.15.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.2.7.15.8 The Ada Source - PROCEDURE bell; 3.2.2.8 Errors - As above in the individual sections. 3.2.2.9 Exceptions - As above in the individual sections. 3.2.2.10 The Ada Source - 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 IS LIMITED PRIVATE; PROCEDURE open (name : IN OUT string ); PROCEDURE close; PROCEDURE set_position (position : IN positive); FUNCTION position RETURN positive; FUNCTION size RETURN positive; REQUIREMENTS Page 3-34 The Ada Source 16 Nov 84 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; FUNCTION valid_character( item : IN character ) RETURN boolean; 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; name_error : EXCEPTION; tcf_error : EXCEPTION; unsupported_terminal : EXCEPTION; invalid_function_key : EXCEPTION; PRIVATE TYPE funtion_key_descriptor IS positive; END scroll_terminal; REQUIREMENTS Page 3-35 The Page Terminal Package 16 Nov 84 3.2.3 The Page Terminal Package 3.2.3.1 Introduction - This package provides a device-independent page-terminal interface to a user's program. 3.2.3.2 The Object Name - page_terminal 3.2.3.3 Abstract - 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. 3.2.3.4 Parameters - None. 3.2.3.5 Local Constants, Types, And Variables - The following types are defined in this package: 1. function_key_enum - an enumerated type defines the 4 arrow keys and 32 function keys. 2. function_key_descriptor - a limited private type (of type positive). 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. 3. 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. 4. select_enumeration - an enumerated type that identifies the range that a delete operation will affect. 5. 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. REQUIREMENTS Page 3-36 Selectors (Functions) 16 Nov 84 3.2.3.6 Selectors (Functions) - REQUIREMENTS Page 3-37 Determining The Active Position 16 Nov 84 3.2.3.6.1 Determining The Active Position - 3.2.3.6.1.1 Introduction - This function is called to get the line and column that the active position is on. 3.2.3.6.1.2 The Object Name - position 3.2.3.6.1.3 Abstract - 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. 3.2.3.6.1.4 Parameters - None. 3.2.3.6.1.5 Local Constants, Types, And Variables - TBD. 3.2.3.6.1.6 Errors - The page terminal may not have been opened prior to calling this function. 3.2.3.6.1.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.6.1.8 The Ada Source - FUNCTION position RETURN xy_position; REQUIREMENTS Page 3-38 Determining The Size Of The Display 16 Nov 84 3.2.3.6.2 Determining The Size Of The Display - 3.2.3.6.2.1 Introduction - This function is called to determine the size of the actual display. 3.2.3.6.2.2 The Object Name - size 3.2.3.6.2.3 Abstract - 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. 3.2.3.6.2.4 Parameters - None. 3.2.3.6.2.5 Local Constants, Types, And Variables - TBD. 3.2.3.6.2.6 Errors - The page terminal may not have been opened prior to calling this function. 3.2.3.6.2.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.6.2.8 The Ada Source - FUNCTION size RETURN xy_position; REQUIREMENTS Page 3-39 Determining The Validity Of A Character 16 Nov 84 3.2.3.6.3 Determining The Validity Of A Character - 3.2.3.6.3.1 Introduction - This procedure is called to determine whether a particular character can be considered valid for this environment. 3.2.3.6.3.2 The Object Name - valid_character 3.2.3.6.3.3 Abstract - Page_terminal.valid_character is called to check if the character specified in the input parameter is one that can be used (and therefore considered valid) for this environment. Character that should be considered suspect include: * XON (CTRL-S) * XOFF (CTRL-Q) * (CTRL-Y) * (CTRL-C) To be safe, a tool writer should call this procedure for every character that they want to use in the application. Of course, if appropriately designed, the application should only need to call this procedure once for each offensive character (probably either at the beginning of the program, or just before the character's first use). 3.2.3.6.3.4 Parameters - There is one input parameter, item, which identifies the character that the user is interested in checking. A boolean value is returned. True indicates that the character is valid and can be used, false indicates that the charater should not be used. 3.2.3.6.3.5 Local Constants, Types, And Variables - TBD. 3.2.3.6.3.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.6.3.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.6.3.8 The Ada Source - FUNCTION valid_character( item : IN character ) RETURN boolean; REQUIREMENTS Page 3-40 Getting The Number Of Typed Function/Arrow Keys 16 Nov 84 3.2.3.6.4 Getting The Number Of Typed Function/Arrow Keys - 3.2.3.6.4.1 Introduction - This function is called to get the number of function/arrow keys that were returned from a call on page_terminal.get. 3.2.3.6.4.2 The Object Name - function_count 3.2.3.6.4.3 Abstract - 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. 3.2.3.6.4.4 Parameters - 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. 3.2.3.6.4.5 Local Constants, Types, And Variables - TBD 3.2.3.6.4.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.3.6.4.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.3.6.4.8 The Ada Source - FUNCTION function_count(keys : IN function_key_descriptor) RETURN natural; REQUIREMENTS Page 3-41 Actors (Procedures) 16 Nov 84 3.2.3.7 Actors (Procedures) - 3.2.3.7.1 Opening A Page Terminal - 3.2.3.7.1.1 Introduction - This procedure is called to open the page terminal. 3.2.3.7.1.2 The Object Name - open 3.2.3.7.1.3 Abstract - Page_terminal.open is called to perform initialization and define a page-mode virtual terminal for the user's program to make use of. This initialization consists of: 1. defining the necessary data structures within the virtual terminal to support a page terminal. 2. calling the driver package and initializing the needed data structures from the terminal capabilities file. 3. raising the necessary exceptions if the page terminal could not be opened. 3.2.3.7.1.4 Parameters - The name parameter contains the name of the actual terminal that the user is interfacing with. This may change from one invocation of the program to another. This name must match exactly (string and case) with the terminal name as defined in the terminal capabilities file. If the string parameter is of length zero then the virtual terminal will attempt to find the terminal name through a system dependent manner. This will be performed through a call to a procedure in the package SYSDEP. If the terminal name can be determined, then it will be returned from this call in the name parameter. The page terminal may have been previously opened. In this case the terminal is implicitly closed and reopened. No implicit update will be performed before the close operation. 3.2.3.7.1.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.1.6 Errors - Errors include: 1. passing in a name that does not appear in the terminal capabilities file. 2. if the terminal capabilities file is not available to read. 3. if the terminal does not have the needed capabilities to be a page terminal. REQUIREMENTS Page 3-42 Opening A Page Terminal 16 Nov 84 3.2.3.7.1.7 Exceptions - The exceptions raised are (respectively): * name_error * tcf_error * unsupported_terminal 3.2.3.7.1.8 The Ada Source - PROCEDURE open (name : IN OUT string); REQUIREMENTS Page 3-43 Closing A Page Terminal 16 Nov 84 3.2.3.7.2 Closing A Page Terminal - 3.2.3.7.2.1 Introduction - This procedure is called to close the page terminal. 3.2.3.7.2.2 The Object Name - close 3.2.3.7.2.3 Abstract - Page_terminal.close closes the virtual terminal. If the virtual terminal was already closed, then no operation will occur. 3.2.3.7.2.4 Parameters - None. 3.2.3.7.2.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.2.6 Errors - None. 3.2.3.7.2.7 Exceptions - None. 3.2.3.7.2.8 The Ada Source - PROCEDURE close; REQUIREMENTS Page 3-44 Setting The Current Position 16 Nov 84 3.2.3.7.3 Setting The Current Position - 3.2.3.7.3.1 Introduction - This procedure is called to set the current position (line and column) on the virtual terminal display. 3.2.3.7.3.2 The Object Name - set_position 3.2.3.7.3.3 Abstract - 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. Wrapping occurs if the parameter contains a value that is outside the actual screen dimensions. 3.2.3.7.3.4 Parameters - This procedure has one parameter, position, which identifies the line and column that the active position should be moved to. 3.2.3.7.3.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.3.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.3.7.3.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.3.8 The Ada Source - PROCEDURE set_position (position : IN xy_position); REQUIREMENTS Page 3-45 Deleting A Character 16 Nov 84 3.2.3.7.4 Deleting A Character - 3.2.3.7.4.1 Introduction - This procedure is called to delete characters starting at the active position. 3.2.3.7.4.2 The Object Name - delete_character 3.2.3.7.4.3 Abstract - 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. 3.2.3.7.4.4 Parameters - The number of characters to be deleted is specified in the input parameter count. Count defaults to one character. 3.2.3.7.4.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.4.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.3.7.4.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.4.8 The Ada Source - PROCEDURE delete_character (count : IN positive := 1); REQUIREMENTS Page 3-46 Deleting A Line 16 Nov 84 3.2.3.7.5 Deleting A Line - 3.2.3.7.5.1 Introduction - This procedure is called to delete lines from the virtual display. 3.2.3.7.5.2 The Object Name - delete_line 3.2.3.7.5.3 Abstract - 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. 3.2.3.7.5.4 Parameters - The input parameter count contains the number of lines that will be deleted. The default is 1. 3.2.3.7.5.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.5.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.3.7.5.7 Exceptions - If the scroll terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.5.8 The Ada Source - PROCEDURE delete_line (count : IN positive := 1); REQUIREMENTS Page 3-47 Erasing Areas In The Display 16 Nov 84 3.2.3.7.6 Erasing Areas In The Display - 3.2.3.7.6.1 Introduction - This procedure is called to erase areas in the display. 3.2.3.7.6.2 The Object Name - erase_in_display 3.2.3.7.6.3 Abstract - 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. 3.2.3.7.6.4 Parameters - The single input parameter selection of type select_enum is used to select which of the three types of erase (listed above) are used. 3.2.3.7.6.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.6.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.6.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.6.8 The Ada Source - PROCEDURE erase_in_display (selection : select_enumeration); REQUIREMENTS Page 3-48 Erasing Areas In Lines 16 Nov 84 3.2.3.7.7 Erasing Areas In Lines - 3.2.3.7.7.1 Introduction - This procedure is called to erase areas in the virtual display's lines. 3.2.3.7.7.2 The Object Name - erase_in_line 3.2.3.7.7.3 Abstract - Page_terminal.erase_in_line causes areas in the line containing the active position to be erased. This erase operation can take three forms: 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. 3.2.3.7.7.4 Parameters - The single input parameter selection of type select_enum is used to select which of the three types of erase (listed above) are used. 3.2.3.7.7.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.7.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.7.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.7.8 The Ada Source - PROCEDURE erase_in_line (selection : select_enumeration); REQUIREMENTS Page 3-49 Entering Insert Character Mode 16 Nov 84 3.2.3.7.8 Entering Insert Character Mode - 3.2.3.7.8.1 Introduction - This procedure is called to enter the insert character mode for the line containing the active position. 3.2.3.7.8.2 The Object Name - enter_insert_mode 3.2.3.7.8.3 Abstract - 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. 3.2.3.7.8.4 Parameters - None. 3.2.3.7.8.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.8.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.8.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.8.8 The Ada Source - PROCEDURE enter_insert_mode; REQUIREMENTS Page 3-50 Exiting Insert Character Mode 16 Nov 84 3.2.3.7.9 Exiting Insert Character Mode - 3.2.3.7.9.1 Introduction - This procedure is called to exit insert character mode. 3.2.3.7.9.2 The Object Name - exit_insert_mode 3.2.3.7.9.3 Abstract - 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) no operation will occur. 3.2.3.7.9.4 Parameters - None. 3.2.3.7.9.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.9.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.9.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.9.8 The Ada Source - PROCEDURE exit_insert_mode; REQUIREMENTS Page 3-51 Inserting A Line 16 Nov 84 3.2.3.7.10 Inserting A Line - 3.2.3.7.10.1 Introduction - This procedure is called to insert blank lines on the virtual display. 3.2.3.7.10.2 The Object Name - insert_line 3.2.3.7.10.3 Abstract - 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. 3.2.3.7.10.4 Parameters - One input parameter count, of type positive identifies the number of blank lines that are to be inserted. The default is one. 3.2.3.7.10.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.10.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.10.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.10.8 The Ada Source - PROCEDURE insert_line (count : IN positive := 1); REQUIREMENTS Page 3-52 Selecting The Graphic Rendition 16 Nov 84 3.2.3.7.11 Selecting The Graphic Rendition - 3.2.3.7.11.1 Introduction - This procedure is called to change the graphic rendition of all the characters put onto the virtual display from this point on. 3.2.3.7.11.2 The Object Name - select_graphic_rendition 3.2.3.7.11.3 Abstract - 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. 3.2.3.7.11.4 Parameters - The single input parameter selection of type graphic_rendition_enumeration specified what the rendition will be. 3.2.3.7.11.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.11.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.11.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.11.8 The Ada Source - PROCEDURE select_graphic_rendition (selection : IN graphic_rendition_enumeration); REQUIREMENTS Page 3-53 Setting A Horizontal Tab 16 Nov 84 3.2.3.7.12 Setting A Horizontal Tab - 3.2.3.7.12.1 Introduction - This procedure will set a horizontal tab at the current active position. 3.2.3.7.12.2 The Object Name - set_tab 3.2.3.7.12.3 Abstract - Scroll_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 at the active position's column then no operation will occur. 3.2.3.7.12.4 Parameters - None. 3.2.3.7.12.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.12.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.12.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.12.8 The Ada Source - PROCEDURE set_tab; REQUIREMENTS Page 3-54 Clearing A Horizontal Tab 16 Nov 84 3.2.3.7.13 Clearing A Horizontal Tab - 3.2.3.7.13.1 Introduction - This procedure is called to clear a horizontal tab stop at the active position. 3.2.3.7.13.2 The Object Name - clear_tab 3.2.3.7.13.3 Abstract - Scroll_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.3.7.13.4 Parameters - None. 3.2.3.7.13.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.13.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.13.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.13.8 The Ada Source - PROCEDURE clear_tab; REQUIREMENTS Page 3-55 Performing A Horizontal Tab 16 Nov 84 3.2.3.7.14 Performing A Horizontal Tab - 3.2.3.7.14.1 Introduction - This procedure moves the active position to the next tab stop. 3.2.3.7.14.2 The Object Name - tab 3.2.3.7.14.3 Abstract - 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 downward through the lines. If there are no tab stops set, then no operation will occur. If there are not enough tab stops on the rest of the screen to fulfill the requested number to move, then the cursor will be moved to the last tab stop on the virtual display. 3.2.3.7.14.4 Parameters - The single input parameter count identifies the number of tab stops to move. The default is one. 3.2.3.7.14.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.14.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.14.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.14.8 The Ada Source - PROCEDURE tab (count : IN positive := 1); REQUIREMENTS Page 3-56 Writing Data To The Terminal 16 Nov 84 3.2.3.7.15 Writing Data To The Terminal - 3.2.3.7.15.1 Introduction - This procedure is called to write data to the virtual display. 3.2.3.7.15.2 The Object Name - put 3.2.3.7.15.3 Abstract - 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. 3.2.3.7.15.4 Parameters - 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. 3.2.3.7.15.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.15.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.15.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.15.8 The Ada Source - PROCEDURE put (item : IN character); PROCEDURE put (item : IN string); REQUIREMENTS Page 3-57 Updating The Screen With Insert/Delete Line 16 Nov 84 3.2.3.7.16 Updating The Screen With Insert/Delete Line - 3.2.3.7.16.1 Introduction - This procedure will cause the actual display to take on the characteristics of the virtual display. 3.2.3.7.16.2 The Object Name - update_screen_with_movement 3.2.3.7.16.3 Abstract - Page_terminal.update_screen_with_movement will cause the actual terminal's display to look like the virtual display. Please refer to the procedure update_screen_with_movement in the package redisplay. 3.2.3.7.16.4 Parameters - None. 3.2.3.7.16.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.16.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.16.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.16.8 The Ada Source - PROCEDURE update_screen_with_movement; REQUIREMENTS Page 3-58 Updating The Screen Without Insert/Delete Line 16 Nov 84 3.2.3.7.17 Updating The Screen Without Insert/Delete Line - 3.2.3.7.17.1 Introduction - This procedure will cause the actual display to take on the characteristics of the virtual display. 3.2.3.7.17.2 The Object Name - update_screen_with_redraw 3.2.3.7.17.3 Abstract - Page_terminal.update_screen_with_redraw will cause the actual terminal's display to look like the virtual display. Please refer to the procedure update_screen_with_redraw in the package redisplay. 3.2.3.7.17.4 Parameters - None. 3.2.3.7.17.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.17.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.17.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.17.8 The Ada Source - PROCEDURE update_screen_with_redraw; REQUIREMENTS Page 3-59 Redrawing The Screen Complete 16 Nov 84 3.2.3.7.18 Redrawing The Screen Complete - 3.2.3.7.18.1 Introduction - This procedure will draw the virtual screen on the terminal's display. 3.2.3.7.18.2 The Object Name - redraw_screen 3.2.3.7.18.3 Abstract - Page_terminal.redraw_screen will redraw the terminal's screen completely. The terminal's screen will be cleared then the old representation of the terminal's screen will be cleared then redisplay screen with redraw will be called. This procedure is supplied to clean up the display when any of the following ocurrs: * the system sends a message to the screen and the VT has no indication that this has occured, * the user inadvertently changes the screen either through a deliberate changing of the terminal parameters or accidentally doing something (like unplugging it), * noise ocurrs on the transmission lines, * some other unforseen thing happens. 3.2.3.7.18.4 Parameters - None. 3.2.3.7.18.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.18.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.18.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.18.8 The Ada Source - PROCEDURE redraw_screen; REQUIREMENTS Page 3-60 Updating A Line 16 Nov 84 3.2.3.7.19 Updating A Line - 3.2.3.7.19.1 Introduction - This procedure is called to force the actual terminal's line to look like the virtual representation of the line. 3.2.3.7.19.2 The Object Name - update_line 3.2.3.7.19.3 Abstract - This procedure will cause the actual terminal's line corrensponding to the line containing the active position to be changed to match the virtual line. Please refer to the procedure update_line within the package redisplay. 3.2.3.7.19.4 Parameters - None. 3.2.3.7.19.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.19.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.19.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.19.8 The Ada Source - PROCEDURE update_line; REQUIREMENTS Page 3-61 Getting Data From The Keyboard 16 Nov 84 3.2.3.7.20 Getting Data From The Keyboard - 3.2.3.7.20.1 Introduction - This procedure is called to get all the data typed at the keyboard since the last call on page_terminal.get or since the virtual terminal was opened. 3.2.3.7.20.2 The Object Name - get 3.2.3.7.20.3 Abstract - 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. 3.2.3.7.20.4 Parameters - 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 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). REQUIREMENTS Page 3-62 Getting Data From The Keyboard 16 Nov 84 3.2.3.7.20.5 Local Constants, Types, And Variables - TBD 3.2.3.7.20.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.3.7.20.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.3.7.20.8 The Ada Source - PROCEDURE get( data : OUT string; last : OUT natural; keys : OUT function_key_descriptor; timeout : IN duration := duration'last ); REQUIREMENTS Page 3-63 Getting The Specified Function/Arrow Key From The List 16 Nov 84 3.2.3.7.21 Getting The Specified Function/Arrow Key From The List - 3.2.3.7.21.1 Introduction - This procedure is called to get the specified function/arrow key from the list of function/arrow keys that were returned from a call on page_terminal.get. 3.2.3.7.21.2 The Object Name - function_key 3.2.3.7.21.3 Abstract - 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). 3.2.3.7.21.4 Parameters - The parameters are: 1. 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. 2. 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. 3. key_identifier - returns an enumerated type which identifies the function/arrow key as described in the terminal capabilities file. 4. 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: a. the function/arrow key was pressed before any of the other keys. In this case previous_position would return a zero. b. the functon key was the last key pressed. In this case the value returned would be the same as last. c. 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" last = 2 a reference to keys REQUIREMENTS Page 3-64 Getting The Specified Function/Arrow Key From The List 16 Nov 84 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. 3.2.3.7.21.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.21.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. The index may indicate a function/arrow key that is illegal. 3.2.3.7.21.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. The exception invalid_function_key may be raised from this procedure. 3.2.3.7.21.8 The Ada Source - PROCEDURE function_key(keys : IN function_key_descriptor; index : IN positive; key_identifier : OUT function_key_enum; previous_position : OUT natural); REQUIREMENTS Page 3-65 Getting The Name Of A Function Key 16 Nov 84 3.2.3.7.22 Getting The Name Of A Function Key - 3.2.3.7.22.1 Introduction - The procedure is called to get the name of the function key (as it appears on the actual terminal keyboard). 3.2.3.7.22.2 The Object Name - function_key_name 3.2.3.7.22.3 Abstract - 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. 3.2.3.7.22.4 Parameters - The parameters are: 1. key_identifier - a value of enumerated type function_key_enum which identifies the function key of interest. 2. key_name - a string which is the function key name as it appears in the terminal capabilities file (exactly). 3. 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). 3.2.3.7.22.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.22.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.3.7.22.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception page_terminal.uninitialized will be raised. 3.2.3.7.22.8 The Ada Source - PROCEDURE function_key_name key_identifier : IN positive; key_name : OUT string; last : OUT natural); REQUIREMENTS Page 3-66 Ringing The Terminal Bell 16 Nov 84 3.2.3.7.23 Ringing The Terminal Bell - 3.2.3.7.23.1 Introduction - Bell causes the actual terminal's bell to ring. 3.2.3.7.23.2 The Object Name - bell 3.2.3.7.23.3 Abstract - Page_terminal.bell will cause the terminal's bell to ring immediately when called. There is no implicit update performed. If the user has defined the bell field in the terminal capabilities file, then that sequence will be output to the terminal. 3.2.3.7.23.4 Parameters - None. 3.2.3.7.23.5 Local Constants, Types, And Variables - TBD. 3.2.3.7.23.6 Errors - The page terminal may not have been opened prior to calling this procedure. 3.2.3.7.23.7 Exceptions - If the page terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.3.7.23.8 The Ada Source - PROCEDURE bell; 3.2.3.8 Errors - As above in the individual sections. 3.2.3.9 Exceptions - As above in the individual sections. 3.2.3.10 The Ada Source - 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 IS LIMITED 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); REQUIREMENTS Page 3-67 The Ada Source 16 Nov 84 TYPE graphic_rendition_enumeration IS (primary_rendition, reverse_image); PROCEDURE open (name : IN OUT string); 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); 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_with_movement; PROCEDURE update_screen_with_redraw; PROCEDURE update_line; PROCEDURE redraw_screen; FUNCTION valid_character( item : IN character ) RETURN boolean; 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 positive; REQUIREMENTS Page 3-68 The Ada Source 16 Nov 84 previous_position : OUT natural); PROCEDURE function_key_name key_identifier : IN positive; key_name : OUT string; last : OUT natural); PROCEDURE bell; uninitialized : EXCEPTION; name_error : EXCEPTION; tcf_error : EXCEPTION; unsupported_terminal : EXCEPTION; invalid_function_key : EXCEPTION; PRIVATE TYPE funtion_key_descriptor IS positive; END page_terminal; REQUIREMENTS Page 3-69 The Form Terminal Package 16 Nov 84 3.2.4 The Form Terminal Package 3.2.4.1 Introduction - The form terminal package provides the functionality for manipulating a form terminal. 3.2.4.2 The Object Name - form_terminal 3.2.4.3 Abstract - A user's program may WITH this package to provide a device-independent terminal interface that is functionally equivalent to a form terminal. The display of a form-mode terminal is divided into qualified areas that have the same attributes. The user program defines qualified areas on the virtual display by making calls on form_terminal.set_position and form_terminal.define_qualified_area. A call upon form_terminal.activate_form will map the virtual terminal display into the actual terminal display and allow editing of the form without user program intervention. When the user has finished editing the form the user presses a function key (as defined in the terminal capabilities file) which returns control to the user's program. 3.2.4.4 Parameters - none 3.2.4.5 Local Constants, Types, And Variables - * 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 has 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. * area_value - indicates the initial value that the area should have when activated. NO_FILL indicates that the value has been specified by a previous PUT statement. FILL_WITH_ZEROES indicates that the value of the area is 0 when activated. FILL_WITH_SPACES indicates that the value of the area is blank when activated. REQUIREMENTS Page 3-70 Selectors (Functions) 16 Nov 84 3.2.4.6 Selectors (Functions) - 3.2.4.6.1 Retrieving The Current Position - 3.2.4.6.1.1 Introduction - This function is called to get the active position on the virtual display. 3.2.4.6.1.2 The Object Name - position 3.2.4.6.1.3 Abstract - Form_terminal.position returns a line/column pair of type xy_position that identifies where the active position is located on the virtual terminal display. 3.2.4.6.1.4 Parameters - None. 3.2.4.6.1.5 Local Constants, Types, And Variables - TBD. 3.2.4.6.1.6 Errors - The form terminal may not have been opened prior to calling this procedure. 3.2.4.6.1.7 Exceptions - 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. 3.2.4.6.1.8 The Ada Source - FUNCTION position RETURN xy_position; REQUIREMENTS Page 3-71 Determining The Size Of The Display 16 Nov 84 3.2.4.6.2 Determining The Size Of The Display - 3.2.4.6.2.1 Introduction - This function is called to determine the size of the actual display. 3.2.4.6.2.2 The Object Name - size 3.2.4.6.2.3 Abstract - 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. 3.2.4.6.2.4 Parameters - None. 3.2.4.6.2.5 Local Constants, Types, And Variables - TBD. 3.2.4.6.2.6 Errors - The form terminal may not have been opened prior to calling this function. 3.2.4.6.2.7 Exceptions - 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. 3.2.4.6.2.8 The Ada Source - FUNCTION size RETURN xy_position; REQUIREMENTS Page 3-72 Determining The Form Status 16 Nov 84 3.2.4.6.3 Determining The Form Status - 3.2.4.6.3.1 Introduction - The is_form_updated function determines changes to the form. 3.2.4.6.3.2 The Object Name - is_form_updated 3.2.4.6.3.3 Abstract - Form_terminal.is_form_updated returns whether the form was modified by the user since the last call on form_terminal.activate_form. 3.2.4.6.3.4 Parameters - None. 3.2.4.6.3.5 Local Constants, Types, And Variables - TBD 3.2.4.6.3.6 Errors - The form terminal may not have been opened prior to calling this procedure. 3.2.4.6.3.7 Exceptions - 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. 3.2.4.6.3.8 The Ada Source - FUNCTION is_form_updated RETURN boolean; REQUIREMENTS Page 3-73 Determining The Termination Key 16 Nov 84 3.2.4.6.4 Determining The Termination Key - 3.2.4.6.4.1 Introduction - The termination_key function determines the termination key. 3.2.4.6.4.2 The Object Name - termination_key 3.2.4.6.4.3 Abstract - Form_terminal.termination_key returns a number that indicates which key as specified in the Terminal Capabilities File terminated the activate_form procedure. 3.2.4.6.4.4 Parameters - None. 3.2.4.6.4.5 Local Constants, Types, And Variables - TBD 3.2.4.6.4.6 Errors - The form terminal may not have been opened prior to calling this procedure. 3.2.4.6.4.7 Exceptions - 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. 3.2.4.6.4.8 The Ada Source - FUNCTION termination_key RETURN termination_key_range; REQUIREMENTS Page 3-74 Actors (Procedures) 16 Nov 84 3.2.4.7 Actors (Procedures) - 3.2.4.7.1 Opening A Form Terminal - 3.2.4.7.1.1 Introduction - This procedure is called to open the form terminal. 3.2.4.7.1.2 The Object Name - open 3.2.4.7.1.3 Abstract - Form_terminal.open is called to perform initialization and define a form-mode virtual terminal for the user's program to make use of. This initialization consists of: 1. defining the necessary data structures within the virtual terminal to support a form terminal. 2. calling the driver package and initializing the needed data structures from the terminal capabilities file. 3. raising the necessary exceptions if the form terminal could not be opened. 3.2.4.7.1.4 Parameters - The name parameter contains the name of the actual terminal that the user is interfacing with. This may change from one invocation of the program to another. This name must match exactly (string and case) with the terminal name as defined in the terminal capabilities file. The form terminal may have been previously opened. In this case the terminal is implicitly closed and reopened. No implicit update will be performed before the close operation. 3.2.4.7.1.5 Local Constants, Types, And Variables - TBD. 3.2.4.7.1.6 Errors - Errors include: 1. passing in a name that does not appear in the terminal capabilities file. 2. if the terminal capabilities file is not available to read. 3. if the terminal does not have the needed capabilities to be a form terminal. 3.2.4.7.1.7 Exceptions - The exceptions raised are (respectively): * name_error * tcf_error REQUIREMENTS Page 3-75 Opening A Form Terminal 16 Nov 84 * unsupported_terminal 3.2.4.7.1.8 The Ada Source - PROCEDURE open (name : IN string); REQUIREMENTS Page 3-76 Closing A Form Terminal 16 Nov 84 3.2.4.7.2 Closing A Form Terminal - 3.2.4.7.2.1 Introduction - This procedure is called to close the form terminal. 3.2.4.7.2.2 The Object Name - close 3.2.4.7.2.3 Abstract - Form_terminal.close closes the virtual terminal. If the virtual terminal was already closed, then no operation will occur. 3.2.4.7.2.4 Parameters - None. 3.2.4.7.2.5 Local Constants, Types, And Variables - TBD. 3.2.4.7.2.6 Errors - None. 3.2.4.7.2.7 Exceptions - None. 3.2.4.7.2.8 The Ada Source - PROCEDURE close; REQUIREMENTS Page 3-77 Setting The Current Position 16 Nov 84 3.2.4.7.3 Setting The Current Position - 3.2.4.7.3.1 Introduction - This procedure is called to set the active position (line and column) on the virtual terminal display. 3.2.4.7.3.2 The Object Name - set_position 3.2.4.7.3.3 Abstract - Form_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. Wrapping occurs if the parameter contains a value that is outside the actual screen or line dimensions. 3.2.4.7.3.4 Parameters - This procedure has one parameter, position, which identifies the line and column that the active position should be moved to. 3.2.4.7.3.5 Local Constants, Types, And Variables - TBD. 3.2.4.7.3.6 Errors - The scroll terminal may not have been opened prior to calling this procedure. 3.2.4.7.3.7 Exceptions - If the scroll 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. 3.2.4.7.3.8 The Ada Source - PROCEDURE set_position (position : IN xy_position); REQUIREMENTS Page 3-78 Defining Qualified Areas 16 Nov 84 3.2.4.7.4 Defining Qualified Areas - 3.2.4.7.4.1 Introduction - This procedure defines sections of the display to be used as qualified areas of the form. 3.2.4.7.4.2 The Object Name - define_qualified_area 3.2.4.7.4.3 Abstract - 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. 3.2.4.7.4.4 Parameters - * 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. * value - the intial value of the area (default is no_fill). 3.2.4.7.4.5 Local Constants, Types, And Variables - TBD. 3.2.4.7.4.6 Errors - The form terminal may not have been opened prior to calling this procedure. 3.2.4.7.4.7 Exceptions - 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. 3.2.4.7.4.8 The Ada Source - PROCEDURE define_qualified_area (intensity : IN area_intensity := normal; protection : IN area_protection := protected; input : IN area_input := graphic_characters; value : IN area_value := no_fill); REQUIREMENTS Page 3-79 Clearing A Qualified Area 16 Nov 84 3.2.4.7.5 Clearing A Qualified Area - 3.2.4.7.5.1 Introduction - This procedure clears a qualified area on the form terminal screen. 3.2.4.7.5.2 The Object Name - clear_qualified_area 3.2.4.7.5.3 Abstract - 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. 3.2.4.7.5.4 Parameters - None. 3.2.4.7.5.5 Local Constants, Types, And Variables - TBD. 3.2.4.7.5.6 Errors - The form terminal may not have been opened prior to calling this procedure. 3.2.4.7.5.7 Exceptions - 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. 3.2.4.7.5.8 The Ada Source - PROCEDURE clear_qualified_area; REQUIREMENTS Page 3-80 Tabbing To The Next Qualified Area 16 Nov 84 3.2.4.7.6 Tabbing To The Next Qualified Area - 3.2.4.7.6.1 Introduction - The tab procedure moves to the next qualified area. 3.2.4.7.6.2 The Object Name - tab 3.2.4.7.6.3 Abstract - 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. 3.2.4.7.6.4 Parameters - None. 3.2.4.7.6.5 Local Constants, Types, And Variables - TBD. 3.2.4.7.6.6 Errors - The form terminal may not have been opened prior to calling this procedure. 3.2.4.7.6.7 Exceptions - 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. 3.2.4.7.6.8 The Ada Source - PROCEDURE tab; REQUIREMENTS Page 3-81 Writing Data To The Terminal 16 Nov 84 3.2.4.7.7 Writing Data To The Terminal - 3.2.4.7.7.1 Introduction - The put procedure writes data to the virtual display. 3.2.4.7.7.2 The Object Name - put 3.2.4.7.7.3 Abstract - There are two types of puts performed by the form_terminal. One writes a character, the other writes a string from 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 from the virtual form 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. 3.2.4.7.7.4 Parameters - * item: the character/string to be written to the display. 3.2.4.7.7.5 Local Constants, Types, And Variables - TBD. 3.2.4.7.7.6 Errors - The form terminal may not have been opened prior to calling this procedure. 3.2.4.7.7.7 Exceptions - 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. 3.2.4.7.7.8 The Ada Source - PROCEDURE put (item : IN character); PROCEDURE put (item : IN string); REQUIREMENTS Page 3-82 Reading Data From Qualified Areas 16 Nov 84 3.2.4.7.8 Reading Data From Qualified Areas - 3.2.4.7.8.1 Introduction - The get procedure reads data from qualified areas on the virtual display. 3.2.4.7.8.2 The Object Name - get 3.2.4.7.8.3 Abstract - 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 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. 3.2.4.7.8.4 Parameters - * item: the character/string to be read into. 3.2.4.7.8.5 Local Constants, Types, And Variables - TBD. 3.2.4.7.8.6 Errors - The form terminal may not have been opened prior to calling this procedure. 3.2.4.7.8.7 Exceptions - 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. 3.2.4.7.8.8 The Ada Source - PROCEDURE get (item : OUT character); PROCEDURE get (item : OUT string); REQUIREMENTS Page 3-83 Erasing A Qualified Area 16 Nov 84 3.2.4.7.9 Erasing A Qualified Area - 3.2.4.7.9.1 Introduction - The erase_area procedure erases a qualified area on the terminal form. 3.2.4.7.9.2 The Object Name - erase_area 3.2.4.7.9.3 Abstract - Form_terminal.erase_area clears the area in which the active position is located by replacing the area with blanks. 3.2.4.7.9.4 Parameters - None. 3.2.4.7.9.5 Local Constants, Types, And Variables - TBD. 3.2.4.7.9.6 Errors - The form terminal may not have been opened prior to calling this procedure. 3.2.4.7.9.7 Exceptions - 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. 3.2.4.7.9.8 The Ada Source - PROCEDURE erase_area; REQUIREMENTS Page 3-84 Erasing The Display Screen 16 Nov 84 3.2.4.7.10 Erasing The Display Screen - 3.2.4.7.10.1 Introduction - The erase_display procedure erases the display. 3.2.4.7.10.2 The Object Name - erase_display 3.2.4.7.10.3 Abstract - 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. 3.2.4.7.10.4 Parameters - None. 3.2.4.7.10.5 Local Constants, Types, And Variables - TBD. 3.2.4.7.10.6 Errors - The form terminal may not have been opened prior to calling this procedure. 3.2.4.7.10.7 Exceptions - 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. 3.2.4.7.10.8 The Ada Source - PROCEDURE erase_display; REQUIREMENTS Page 3-85 Activating A Form For Input 16 Nov 84 3.2.4.7.11 Activating A Form For Input - 3.2.4.7.11.1 Introduction - The activate form procedure activates a terminal form for input. 3.2.4.7.11.2 The Object Name - activate_form 3.2.4.7.11.3 Abstract - 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. 3.2.4.7.11.4 Parameters - None. 3.2.4.7.11.5 Local Constants, Types, And Variables - TBD. 3.2.4.7.11.6 Errors - The form terminal may not have been opened prior to calling this procedure. 3.2.4.7.11.7 Exceptions - 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. 3.2.4.7.11.8 The Ada Source - PROCEDURE activate_form; 3.2.4.8 Errors - As above in the individual sections. 3.2.4.9 Exceptions - As above in the individual sections. 3.2.4.10 The Ada Source - PACKAGE form_terminal IS 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, alphabetics); TYPE area_value IS (no_fill, fill_with_zeroes, fill_with_spaces); REQUIREMENTS Page 3-86 The Ada Source 16 Nov 84 PROCEDURE open (name : IN string); 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; value : IN area_value := no_fill); 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; -- exceptions END form_terminal; REQUIREMENTS Page 3-87 The Virtual Terminal Content Package 16 Nov 84 3.2.5 The Virtual Terminal Content Package 3.2.5.1 Introduction - This package defines the constants and types used in defining a virtual display. 3.2.5.2 The Object Name - vt_content 3.2.5.3 Abstract - This package contains the supporting contant and type definitions used by other packages in defining and manipulating a virtual display. Many of the enumerated types use names that match the names in the ANSI X3.64 [ANSI74] standard. 3.2.5.4 Parameters - None. 3.2.5.5 Local Constants, Types, And Variables - 1. class_enum - an enumerated type describing the class of the terminal. The choices are scroll, page, or form. 2. graphic_rendition_enum - an enumerated type describing the graphic rendition for a position on the virtual display. The choices are primary rendition and reverse image. 3. graphic_rendition_set - the set of all possible choices for graphics rendition for a position on the virtual display. 4. area_qualifier_enum - an enumerated type describing the area qualifiers. All are obvious with the following exceptions: a. accept no input means the area is protected against user modification, b. graphic input is all printing ascii characters, c. zero fill means that an area will be filled (written to) with ascii NULs (ascii code 0). 5. area_qualifiers_set - the set of all possible area qualifiers for a position on the virtual display. 6. edit_extent_enum - an enumerated type describing the extent on the virtual display that editting will effect. The choices are line and qualified area. 7. max_row - the absolute maximum number of rows that this virtual terminal will support. 8. max_column - the absolute maximum number of columns that this virtual terminal will support. REQUIREMENTS Page 3-88 Local Constants, Types, And Variables 16 Nov 84 9. column_range - the range of columns for the virtual display. 10. row_range - the range of rows for the virtual display. 11. vt_position_record - a type with x and y components that identify a specific position on the virtual display. 12. max_position_data - the maximum number that a position on the display can have as data. Normally limited to the ascii character set. 13. vt_position_data - the range of values that a position on the display can take. 14. vt_position_record - the contents of a position on the virtual display are: a. rendition - the graphic rendition of the position as described above, b. qualifiers - the area qualifiers as described above, c. data - the data. Normally this is ascii characters, d. tab_set - identifies whether this position has a tab stop set. 15. vt_column_array - an array of positions describing a line on the virtual display, 16. vt_content_array - an array of lines describing the contents of the full virtual display, 17. vt_content_record - a record containing the contents of the screen and fields identifying the active position, editting extent, and the contents of all positions on the virtual display, 18. vt_content_access - an access type pointing to a vt_content_record. 19. width - a variable set after VT initialization identifying the actual width (number of columns) that the terminal supports. 20. height - a variable set after VT initialization identifying the actual height (number of rows) that the terminal supports. 3.2.5.6 Selectors (Functions) - None. REQUIREMENTS Page 3-89 Actors (Procedures) 16 Nov 84 3.2.5.7 Actors (Procedures) - None. 3.2.5.8 Errors - None. 3.2.5.9 Exceptions - None. 3.2.5.10 The Ada Source - PACKAGE vt_content IS TYPE class_enum IS (scroll, page, form); TYPE graphic_rendition_enum IS ( sgpr, -- primary rendition sgri ); -- reverse image TYPE graphic_rendition_set IS ARRAY ( graphic_rendition_enum ) OF boolean; TYPE area_qualifiers_enum IS ( dqnn, -- accept no input and do not transmit dqag, -- accept graphic input dqan, -- accept numeric input dqaa, -- accept alphabetic input dqzf, -- zero fill area dqsf ); -- space fill in area TYPE area_qualifiers_set IS ARRAY( area_qualifiers_enum ) OF boolean; TYPE edit_extent_enum IS ( seel, -- edit in line seqa ); -- edit in qualified area max_row : positive CONSTANT := 72; max_column : positive CONSTANT := 132; SUBTYPE column_range IS POSITIVE RANGE 1..max_column; SUBTYPE row_range IS POSITIVE RANGE 1..max_row; TYPE vt_position_xy_record IS RECORD x_position :row_range; y_position :column_range; END RECORD; max_position_data : natural CONSTANT := 255; -- 8 bits SUBTYPE vt_position_data IS natural RANGE 0..max_position_data; REQUIREMENTS Page 3-90 The Ada Source 16 Nov 84 TYPE vt_position_record IS RECORD rendition :graphic_rendition_set; qualifiers :area_qualifiers_set; data :vt_position_data; tab_set :boolean; END RECORD; -- vt_position_record TYPE vt_column_array IS ARRAY( column_range ) OF vt_position_record; TYPE vt_content_array IS ARRAY( row_range ) OF vt_column_array; TYPE vt_content_record IS RECORD active_position :vt_position_xy_record; edit_extent :edit_extent_enum; element :vt_content_array; END RECORD; -- vt_content_record TYPE vt_content_access IS ACCESS vt_content_record; height : row_range; width : column_range; END vt_content; REQUIREMENTS Page 3-91 The Virtual Terminal Keyboard Input Package 16 Nov 84 3.2.6 The Virtual Terminal Keyboard Input Package 3.2.6.1 Introduction - 3.2.6.2 The Object Name - vt_input 3.2.6.3 Abstract - This package provides an interface to get keystrokes from the actual terminals keyboard. The keystrokes include regular ASCII keys and function keys (including the arrow keys). The function and arrow keys are identified through the use of the terminal capabilities database. There can be up to 32 function keys. There will always be 4 arrow keys. Facilities are provided to: 1. get all the keystrokes that were typed since the last call on vt_input.get, 2. get the total number of function keys that this terminal supports, 3. get the string (name) associated with each function key, 3.2.6.4 Parameters - None. 3.2.6.5 Local Constants, Types, And Variables - The private limited type function_key_descriptor is defined here. This type is used to traverse the function/arrow key list whose reference is returned from a call to vt_input.get (see below). The user must define a variable of this type (or more than one) in order to use the function/arrow key procedures and functions. The enumerated type function_key_enum identifies the function/arrow keys that are used in the function/arrow key handling procedures and functions. REQUIREMENTS Page 3-92 Selectors (Functions) 16 Nov 84 3.2.6.6 Selectors (Functions) - 3.2.6.6.1 Getting The Number Of Typed Function/Arrow Keys - 3.2.6.6.1.1 Introduction - This function is called to get the number of function/arrow keys that were returned from a call on vt_input.get. 3.2.6.6.1.2 The Object Name - function_count 3.2.6.6.1.3 Abstract - A value is returned of type natural that identifies the number of function/arrow keys that were typed since the last call on vt_input.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 vt_input.get. 3.2.6.6.1.4 Parameters - The single input parameter keys is the limited private type returned from the call on vt_input.get. This identifies the specific list of function/arrow keys that will be operated on by this function. 3.2.6.6.1.5 Local Constants, Types, And Variables - TBD 3.2.6.6.1.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.6.6.1.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception vt_input.uninitialized will be raised. 3.2.6.6.1.8 The Ada Source - FUNCTION function_count(keys : IN function_key_descriptor) RETURN natural; REQUIREMENTS Page 3-93 Actors (Procedures) 16 Nov 84 3.2.6.7 Actors (Procedures) - 3.2.6.7.1 Getting Data From The Keyboard - 3.2.6.7.1.1 Introduction - This procedure is called to get all the data typed at the keyboard since the last call on vt_input.get or since the virtual terminal was opened. 3.2.6.7.1.2 The Object Name - get 3.2.6.7.1.3 Abstract - When vt_input.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 vt_input.get are returned. 3.2.6.7.1.4 Parameters - 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 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). REQUIREMENTS Page 3-94 Getting Data From The Keyboard 16 Nov 84 3.2.6.7.1.5 Local Constants, Types, And Variables - TBD 3.2.6.7.1.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.6.7.1.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception vt_input.uninitialized will be raised. 3.2.6.7.1.8 The Ada Source - PROCEDURE get( data : OUT string; last : OUT natural; keys : OUT function_key_descriptor; timeout : IN duration := duration'last ); REQUIREMENTS Page 3-95 Getting The Specified Function/Arrow Key From The List 16 Nov 84 3.2.6.7.2 Getting The Specified Function/Arrow Key From The List - 3.2.6.7.2.1 Introduction - This procedure is called to get the specified function/arrow key from the list of function/arrow keys that were returned from a call on vt_input.get. 3.2.6.7.2.2 The Object Name - function_key 3.2.6.7.2.3 Abstract - As described in the procedure vt_input.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). 3.2.6.7.2.4 Parameters - The parameters are: 1. keys - the value of the private limited type function_key_descriptor that was returned from a call on vt_input.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. 2. 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. 3. key_identifier - returns an enumerated type which identifies the function/arrow key as described in the terminal capabilities file. 4. previous_position - a position in the string that was returned from a call on vt_input.get. This position is the one immediately before the function/arrow key was pressed. Three cases are important: a. the function/arrow key was pressed before any of the other keys. In this case previous_position would return a zero. b. the functon key was the last key pressed. In this case the value returned would be the same as last. c. 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". vt_input.get would return data = "ab" last = 2 a reference to keys REQUIREMENTS Page 3-96 Getting The Specified Function/Arrow Key From The List 16 Nov 84 When vt_input.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. 3.2.6.7.2.5 Local Constants, Types, And Variables - TBD. 3.2.6.7.2.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. The index may indicate a function/arrow key that is illegal. 3.2.6.7.2.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception vt_input.uninitialized will be raised. The exception invalid_function_key may be raised from this procedure. 3.2.6.7.2.8 The Ada Source - PROCEDURE function_key(keys : IN function_key_descriptor; index : IN positive; key_identifier : OUT function_key_enum; previous_position : OUT natural); REQUIREMENTS Page 3-97 Getting The Name Of A Function Key 16 Nov 84 3.2.6.7.3 Getting The Name Of A Function Key - 3.2.6.7.3.1 Introduction - The procedure is called to get the name of the function key (as it appears on the actual terminal keyboard). 3.2.6.7.3.2 The Object Name - function_key_name 3.2.6.7.3.3 Abstract - 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. 3.2.6.7.3.4 Parameters - The parameters are: 1. key_identifier - a value of enumerated type function_key_enum which identifies the function key of interest. 2. key_name - a string which is the function key name as it appears in the terminal capabilities file (exactly). 3. 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). 3.2.6.7.3.5 Local Constants, Types, And Variables - TBD. 3.2.6.7.3.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.6.7.3.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception vt_input.uninitialized will be raised. 3.2.6.7.3.8 The Ada Source - PROCEDURE function_key_name key_identifier : IN positive; key_name : OUT string; last : OUT natural); 3.2.6.8 Errors - A call could be made on any of these procedures or functions without previously having intialized the actual terminal. 3.2.6.9 Exceptions - The exception vt_input.uninitialized is raised if the actual terminal has not been initialized (by a previous call to driver.virtual_terminal_initialize). REQUIREMENTS Page 3-98 The Ada Source 16 Nov 84 3.2.6.10 The Ada Source - PACKAGE vt_input 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 IS LIMITED PRIVATE; 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); invalid_function_key : EXCEPTION; uninitialized : EXCEPTION; PRIVATE TYPE funtion_key_descriptor IS positive; END vt_input; REQUIREMENTS Page 3-99 The Redisplay Package 16 Nov 84 3.2.7 The Redisplay Package 3.2.7.1 Introduction - The redisplay package performs the function of mapping characters and lines from the data structures of the vt_content package to the actual display. 3.2.7.2 The Object Name - redisplay 3.2.7.3 Abstract - The redisplay package WITH's the vt_content package to make the data structures in vt_content visible to redisplay. The vt_content data structures describe how the image on the actual display looks after the redisplay package is invoked and how the image of the actual display looks before the redisplay package is invoked. When a change is made to the data structures in vt_content, the image on the actual display must be updated to reflect the change. 3.2.7.4 Parameters - None. 3.2.7.5 Local Constants, Types, And Variables - Tbd. 3.2.7.6 Selectors (Functions) - None. REQUIREMENTS Page 3-100 Actors (Procedures) 16 Nov 84 3.2.7.7 Actors (Procedures) - 3.2.7.7.1 Redisplay_screen_with_movement - 3.2.7.7.1.1 Introduction - This procedure transforms the present screen display into the desired screen display. 3.2.7.7.1.2 Abstract - Redisplay.redisplay_screen_with_movement has two input parameters that are pointers to a record of arrays. The record vt_content.vt_content_record describes the display. The arrays vt_content.vt_column_array in this record represent the individual lines of the display. This procedure uses insert and delete line to map the data structures of the virtual display onto the actual display minimizing the number of insertions and deletions used. The redisplay_screen_with_movement procedure makes repeated calls to the redisplay_line_with_movement procedures to redisplay the entire display. 3.2.7.7.1.3 Parameters - * old_screen - how the actual display looks before the redisplay package is called. The old_screen parameter will look like the new_screen parameter after redisplay is invoked. * new_screen - how the actual display looks after the redisplay package is called. 3.2.7.7.1.4 Local Constants, Types, And Variables - TBD. 3.2.7.7.1.5 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.7.7.1.6 Exceptions - If the virtual terminal has not been opened previously to this then the exception redisplay.uninitialized will be raised. 3.2.7.7.1.7 The Ada Source - PROCEDURE redisplay_screen_with_movement( old_screen : IN OUT vt_contents.vt_content_access; new_screen : IN OUT vt_contents.vt_content_access; REQUIREMENTS Page 3-101 Redisplay_screen_with_redraw 16 Nov 84 3.2.7.7.2 Redisplay_screen_with_redraw - 3.2.7.7.2.1 Introduction - This procedure determines the differences between the present screen display and the desired screen display and redraws those differences to the actual display. 3.2.7.7.2.2 Redisplay_screen_with_redraw - 3.2.7.7.2.3 Abstract - Redisplay.redisplay_screen_with_redraw has two input parameters that are pointers to a record of arrays. The record vt_content.vt_content_record describes the display. The arrays vt_content.vt_column_array in this record represent the individual lines of the display. This procedure redraws the differences found between the two input parameters onto the actual display. The redisplay_screen_with_redraw procedure makes repeated calls to the redisplay_line_with_redraw procedures to map the entire display. 3.2.7.7.2.4 Parameters - * old_screen - how the actual display looks before the redisplay package is called. The old_screen parameter will look like the new_screen parameter after redisplay is invoked. * new_screen - how the actual display looks after the redisplay package is called. 3.2.7.7.2.5 Local Constants, Types, And Variables - TBD. 3.2.7.7.2.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.7.7.2.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception redisplay.uninitialized will be raised. 3.2.7.7.2.8 The Ada Source - PROCEDURE redisplay_screen_with_redraw( old_screen : IN OUT vt_contents.vt_content_access; new_screen : IN vt_contents.vt_content_access ); REQUIREMENTS Page 3-102 Redisplay_line_with_movement 16 Nov 84 3.2.7.7.3 Redisplay_line_with_movement - 3.2.7.7.3.1 Introduction - This procedure transforms the present line of the display into the desired line of the display. 3.2.7.7.3.2 The Object Name - redisplay_line_with_movement 3.2.7.7.3.3 Abstract - Redisplay.redisplay_line_with_movement has two input parameters that are arrays of records vt_contents.vt_column_array describing a line on the display. The records of the vt_content.vt_column_array describe the terminal rendition, the qualifiers, the data, and the tab sets for each array. This procedure uses insert and delete character to map the data structures of the virtual display onto the actual display minimizing the number of insertions and deletions used. 3.2.7.7.3.4 Parameters - * old_line - how the actual display looks before the redisplay package is called. The old_line parameter will look like the new_line parameter after redisplay is invoked. * new_line - how the actual display looks after the redisplay package is called. 3.2.7.7.3.5 Local Constants, Types, And Variables - TBD. 3.2.7.7.3.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.7.7.3.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception redisplay.uninitialized will be raised. 3.2.7.7.3.8 The Ada Source - PROCEDURE redisplay_line_with_movement( old_line : IN OUT vt_contents.vt_column_array; new_line : IN vt_contents.vt_column_array ); REQUIREMENTS Page 3-103 Redisplay_line_with_redraw 16 Nov 84 3.2.7.7.4 Redisplay_line_with_redraw - 3.2.7.7.4.1 Introduction - This procedure determines the differences between the present line and the desired line and redraws those differences to the actual display. 3.2.7.7.4.2 The Object Name - redisplay_line_with_redraw 3.2.7.7.4.3 Abstract - Redisplay.redisplay_line_with_redraw has two input parameters that are arrays of records describing a line on the display. The records of the vt_content.vt_column_array describe the terminal rendition, the qualifiers, the data, and the tab sets for each array. This procedure redraws the differences found between the two input parameters onto the actual display. 3.2.7.7.4.4 Parameters - * old_line - how the actual display looks before the redisplay package is called. The old_line parameter will look like the new_line parameter after redisplay is invoked. * new_line - how the actual display looks after the redisplay package is called. 3.2.7.7.4.5 Local Constants, Types, And Variables - Tbd. 3.2.7.7.4.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.7.7.4.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception redisplay.uninitialized will be raised. 3.2.7.7.4.8 The Ada Source - PROCEDURE redisplay_line_with_redraw( old_line : IN OUT vt_contents.vt_column_array; new_line : IN vt_contents.vt_column_array ); REQUIREMENTS Page 3-104 Redraw_screen 16 Nov 84 3.2.7.7.5 Redraw_screen - 3.2.7.7.5.1 Introduction - This procedure redraws the entire display. 3.2.7.7.5.2 Redraw_screen - 3.2.7.7.5.3 Abstract - Redisplay.redraw_screen has two input parameter that are pointers to a record of arrays. The record vt_content.vt_content_record describes the display. The arrays vt_content.vt_column_array in this record represents the individual lines of the display. This procedure clears the terminal screen, blanks out the actual display and calls redisplay_screen_with_movement. 3.2.7.7.5.4 Parameters - * old_screen - how the actual display looks before the redisplay package is called. The old_screen parameter will look like the new_screen parameter after redisplay is invoked. * new_screen - how the actual display looks after the redisplay package is called. 3.2.7.7.5.5 Local Constants, Types, And Variables - Tbd. 3.2.7.7.5.6 Errors - The virtual terminal may not have been opened prior to calling this procedure. 3.2.7.7.5.7 Exceptions - If the virtual terminal has not been opened previously to this then the exception redisplay.uninitialized will be raised. 3.2.7.7.5.8 The Ada Source - PROCEDURE redraw_screen( old_screen : IN OUT vt_contents.vt_column_array; new_screen : IN vt_contents.vt_column_array ); uninitialized : EXCEPTION; REQUIREMENTS Page 3-105 Errors 16 Nov 84 3.2.7.8 Errors - As described in the individual sections. 3.2.7.9 Exceptions - As described in the inidividual sections. 3.2.7.10 The Ada Source - PROCEDURE redisplay_screen_with_movement( old_screen : IN OUT vt_contents.vt_content_access; new_screen : IN vt_contents.vt_content_access ); PROCEDURE redisplay_screen_with_redraw( old_screen : IN OUT vt_contents.vt_content_access; new_screen : IN vt_contents.vt_content_access ); PROCEDURE redisplay_line_with_movement( old_line : IN OUT vt_contents.vt_column_array; new_line : IN vt_contents.vt_column_array ); PROCEDURE redisplay_line_with_redraw( old_line : IN OUT vt_contents.vt_column_array; new_line : IN vt_contents.vt_column_array ); PROCEDURE redraw_screen( old_screen : IN OUT vt_contents.vt_column_array; new_screen : IN vt_contents.vt_column_array ); uninitialized : EXCEPTION; END redisplay; REQUIREMENTS Page 3-106 The Driver Package Specification 16 Nov 84 3.2.8 The Driver Package Specification 3.2.8.1 Introduction - This section defines the specification for the driver package. 3.2.8.2 The Object Name - driver 3.2.8.3 Abstract - The driver package performs the following functions: * Initialize the actual terminal, * Initialize the TCF, * Interpret the ANSI compatible character codes and translate them into device specific character codes. * close the actual terminal. 3.2.8.4 Parameters - none 3.2.8.5 Local Constants, Types, And Variables - * terminal_capabilites_enum - An enumeration type identifying the terminal capabilities. * terminal_capabilities_set - a boolean array of an enumeration of terminal capabilities. * supported_functions - a variable of type terminal_capabilties_set that identifies which functions are directly supported by the actual display. 3.2.8.6 Selectors (Functions) - none REQUIREMENTS Page 3-107 Actors (Procedures) 16 Nov 84 3.2.8.7 Actors (Procedures) - The following pages describe the specifications for the procedures of the driver package specification. 3.2.8.7.1 Initializeing The Virtual Terminal - 3.2.8.7.1.1 Introduction - This procedure is called to initialize the actual terminal. 3.2.8.7.1.2 The Object Name - virtual_terminal_initialize 3.2.8.7.1.3 Abstract - This procedure is called to initialize the virtual terminal. It precedes any other calls to the virtual terminal procedures and/or functions. This procedure makes a call to the tcf package to initialize the terminal capabilities file. If the input parameter 'name' is empty then the SYSDEP package is invoked. 3.2.8.7.1.4 Parameters - * name - A variable length character string holding terminal name. This name must match an entry in the terminal capabilities file exactly (case and character). * lines - the number of lines that the actual terminal display contains. * columns - the number of columns that the actual terminal display contains. 3.2.8.7.1.5 Errors - * missing tcf - the tcf either could not be opened or could not be read for some system dependent reason. * unsupported terminal - the terminal name could not be found in the terminal capabilities file. * missing capabilities - the terminal does not have the capabilities necessary to support the virtual terminal. 3.2.8.7.1.6 Exceptions - The following exception can be raised from this procedure: * tcf_error * name_error * unsupported_terminal REQUIREMENTS Page 3-108 Initializeing The Virtual Terminal 16 Nov 84 3.2.8.7.1.7 The Ada Source - PROCEDURE virtual_terminal_initialize( name : IN string; lines : OUT positive; columns : OUT positive ); REQUIREMENTS Page 3-109 Closing The Virtual Terminal 16 Nov 84 3.2.8.7.2 Closing The Virtual Terminal - 3.2.8.7.2.1 Introduction - This procedure is called to close the actual terminal. 3.2.8.7.2.2 The Object Name - close_virtual_terminal 3.2.8.7.2.3 Abstract - This procedure is called to reestablish the original terminal characteristics and close the virtual terminal. No virtual terminal procedures or functions should be called after this procedure (this naturally excludes the procedure virtual_terminal_initialize). If the virtual terminal has already been closed then this procedure performs no operation. 3.2.8.7.2.4 Parameters - none 3.2.8.7.2.5 Local Constants, Types, And Variables - tbd 3.2.8.7.2.6 Errors - None. 3.2.8.7.2.7 Exceptions - None. 3.2.8.7.2.8 The Ada Source - PROCEDURE close_virtual_terminal; REQUIREMENTS Page 3-110 Interpreting ANSI Character Sequences 16 Nov 84 3.2.8.7.3 Interpreting ANSI Character Sequences - 3.2.8.7.3.1 Introduction - This procedure interprets incoming commands from the user program using the terminal capabilities for the particular terminal. 3.2.8.7.3.2 The Object Name - interpret 3.2.8.7.3.3 Abstract - The interpret procedure accepts input in the form of a command string passed in as an input parameter and translates this command into the particular escape sequences for the specific terminal. The translation uses the information in the terminal capabilities data structures (within the package TCF). See an appendix for a description of the ANSI sequences that are interpreted. 3.2.8.7.3.4 Parameters - * command_string - a command from the user's program to be scanned and parsed into escape sequences. 3.2.8.7.3.5 Local Constants, Types, And Variables - tbd 3.2.8.7.3.6 Actors (Procedures) - The following procedures are discussed in the package body of driver. * erase_to_end_of_screen * erase_to_end_of_line * move_the_cursor_to * insert_line * delete_line * delete_character * beep * write_string * new_line * read_string * turn_on_highlighting * turn_off_highlighting REQUIREMENTS Page 3-111 Interpreting ANSI Character Sequences 16 Nov 84 * enter_insert_mode * exit_insert_mode * scroll_up * scroll_down 3.2.8.7.3.7 Errors - The virtual terminal may not have been initialized prior to a call on this procedure. 3.2.8.7.3.8 Exceptions - The exception driver.uninitialized will be raised if the virtual terminal has not been initialized prior to calling this procedure. 3.2.8.7.3.9 The Ada Source - PROCEDURE interpret (command_string : string); REQUIREMENTS Page 3-112 Errors 16 Nov 84 3.2.8.8 Errors - See the individual sections. 3.2.8.9 Exceptions - See the individual sections. 3.2.8.10 The Ada Source - PACKAGE driver IS -- Types TYPE terminal_capabilities_enum IS ( erase_to_end_of_screen_is, erase_to_end_of_line_is, move_the_cursor_is, insert_line_is, delete_line_is, delete_character_is, beep_is, highlight_is, insert_mode_is, scroll_up_is, scroll_down_is ); TYPE terminal_capabilities_set IS array( terminal_capabilities_enum ) OF boolean; -- Variables supported_functions : terminal_capabilities_set; -- Procedures PROCEDURE virtual_terminal_initialize( name : IN string; lines : OUT positive; columns : OUT Positive ); PROCEDURE close_virtual_terminal; PROCEDURE interpret ( command_string : IN string); uninitialized : EXCEPTION; name_error : EXCEPTION; tcf_error : EXCEPTION; unsupported_terminal : EXCEPTION; END driver; REQUIREMENTS Page 3-113 The Driver Package Body 16 Nov 84 3.2.9 The Driver Package Body 3.2.9.1 Introduction - This section defines the body of the driver package. 3.2.9.2 The Object Name - driver 3.2.9.3 Abstract - The driver package performs the following functions: * Initialize the actual terminal, * Initialize the TCF, * Interpret the ANSI compatible character codes and translate them into device specific character codes. * close the actual terminal. 3.2.9.4 Parameters - none 3.2.9.5 Local Constants, Types, And Variables - tbd REQUIREMENTS Page 3-114 Actors (Procedures) 16 Nov 84 3.2.9.6 Actors (Procedures) - The following procedures are part of the Interpret specification in the Driver package specification. 3.2.9.6.1 Erasing To The End Of The Screen - 3.2.9.6.1.1 Introduction - The erase_to_end_of_screen procedure erases from the current cursor position to the end of screen. 3.2.9.6.1.2 The Object Name - erase_to_end_of_screen 3.2.9.6.1.3 Abstract - This procedure is called to erase from the current cursor location to the end of the screen. The cursor is not moved. 3.2.9.6.1.4 Parameters - None. 3.2.9.6.1.5 Local Constants, Types, And Variables - tbd 3.2.9.6.1.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.1.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.1.8 The Ada Source - PROCEDURE erase_to_end_of_screen; REQUIREMENTS Page 3-115 Erasing To The End Of A Line 16 Nov 84 3.2.9.6.2 Erasing To The End Of A Line - 3.2.9.6.2.1 Introduction - The erase_to_end_of_line procedure erases from the current cursor position to the end of the current line. 3.2.9.6.2.2 The Object Name - erase_to_end_of_line 3.2.9.6.2.3 Abstract - This procedure is called to erase from the current cursor location to the end of the current line. The cursor is left at the point it was originally. 3.2.9.6.2.4 Parameters - none 3.2.9.6.2.5 Local Constants, Types, And Variables - tbd 3.2.9.6.2.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.2.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.2.8 The Ada Source - PROCEDURE erase_to_end_of_line; REQUIREMENTS Page 3-116 Moving The Cursor 16 Nov 84 3.2.9.6.3 Moving The Cursor - 3.2.9.6.3.1 Introduction - The move_the_cursor_to procedure moves the cursor a specified point on the actual terminal screen. 3.2.9.6.3.2 The Object Name - move_the_cursor_to 3.2.9.6.3.3 Abstract - This procedure is called to move the cursor to the specified position on the display screen. If the values of x and y are outside the legal range unpredictable results may occur. 3.2.9.6.3.4 Parameters - * p_x - the x (column) coordinate. * p_y - the y (line) coordinate. 3.2.9.6.3.5 Local Constants, Types, And Variables - tbd 3.2.9.6.3.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.3.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.3.8 The Ada Source - PROCEDURE move_the_cursor_to( p_x : IN positive; p_y : IN positive ); REQUIREMENTS Page 3-117 Inserting A Line 16 Nov 84 3.2.9.6.4 Inserting A Line - 3.2.9.6.4.1 Introduction - The insert_line procedure will insert a blank line on the terminal screen at the line on which the cursor is located. 3.2.9.6.4.2 The Object Name - insert_line 3.2.9.6.4.3 Abstract - This procedure is called to insert a blank line on the display at the line on which the cursor is placed. All of the lines including and below the line containing the cursor are pushed down one line and the bottom line is lost. The cursor is moved to the beginning of the blank line. To be safe, you should always place the cursor at the beginning of the line before issuing the procedure call. 3.2.9.6.4.4 Parameters - None. 3.2.9.6.4.5 Local Constants, Types, And Variables - tbd 3.2.9.6.4.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.4.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.4.8 The Ada Source - PROCEDURE insert_line; REQUIREMENTS Page 3-118 Deleting A Line 16 Nov 84 3.2.9.6.5 Deleting A Line - 3.2.9.6.5.1 Introduction - The delete_line procedure deletes lines at the current cursor position. 3.2.9.6.5.2 The Object Name - delete_line 3.2.9.6.5.3 Abstract - The procedure delete_line is called to delete the line containing the cursor. The lines below the one containing the cursor are moved up and a blank line appears at the bottom. The cursor is left at the beginning of the line on which it was residing before the procedure call (now, of course, containing new data). To be safe, you should always place the cursor at the beginning of the line before issuing the procedure call. 3.2.9.6.5.4 Parameters - None. 3.2.9.6.5.5 Local Constants, Types, And Variables - tbd 3.2.9.6.5.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.5.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.5.8 The Ada Source - PROCEDURE delete_line; REQUIREMENTS Page 3-119 Deleting A Character 16 Nov 84 3.2.9.6.6 Deleting A Character - 3.2.9.6.6.1 Introduction - The delete_character procedure deletes characters that the cursor is located on. 3.2.9.6.6.2 The Object Name - deletecharacter 3.2.9.6.6.3 Abstract - This procedure is called to delete the character that the cursor is sitting on. The caracters to the right of the cursor are moved left to fill in the deleted character and a blank character appears on the far right of the display screen. The cursor is left at the position it was in before the procedure call (of course, containing new data). 3.2.9.6.6.4 Parameters - None. 3.2.9.6.6.5 Local Constants, Types, And Variables - tbd 3.2.9.6.6.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.6.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.6.8 The Ada Source - PROCEDURE delete_character; REQUIREMENTS Page 3-120 Procedure Beep 16 Nov 84 3.2.9.6.7 Procedure Beep - 3.2.9.6.7.1 Introduction - The procedure beep rings the terminal bell. 3.2.9.6.7.2 The Object Name - beep 3.2.9.6.7.3 Abstract - This procedure is called to get the users attention. It does this by sending the sequence representing the bell obtained from the terminal capabilties file. 3.2.9.6.7.4 Parameters - none 3.2.9.6.7.5 Local Constants, Types, And Variables - tbd 3.2.9.6.7.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.7.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.7.8 The Ada Source - PROCEDURE beep; REQUIREMENTS Page 3-121 Writing Data To The Actual Terminal 16 Nov 84 3.2.9.6.8 Writing Data To The Actual Terminal - 3.2.9.6.8.1 Introduction - The procedure write_string places character strings on the terminal screen at the current cursor position. 3.2.9.6.8.2 The Object Name - write_string 3.2.9.6.8.3 Abstract - The procedure write_string is called to place character strings on the display at the current cursor position. The cursor is left at the position where the data ended on the display. If the string length extends such that data is written past the end of a line then unpredictable results will occur. 3.2.9.6.8.3.1 Parameters - * data - An input parameter of type string. 3.2.9.6.8.4 Local Constants, Types, And Variables - tbd 3.2.9.6.8.5 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.8.6 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.8.7 The Ada Source - PROCEDURE write_string( data : IN string ); REQUIREMENTS Page 3-122 Moving The Cursor To A New Line 16 Nov 84 3.2.9.6.9 Moving The Cursor To A New Line - 3.2.9.6.9.1 Introduction - The new_line procedure moves the cursor from its current position to the beginning of the next line. 3.2.9.6.9.2 The Object Name - new_line 3.2.9.6.9.3 Abstract - This procedure causes the cursor to go from its current position to the beginning of the next line. If the cursor was located at the bottom line of the screen then unpredictable results will occur. 3.2.9.6.9.4 Parameters - none 3.2.9.6.9.5 Local Constants, Types, And Variables - tbd 3.2.9.6.9.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.9.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.9.8 The Ada Source - PROCEDURE new_line; REQUIREMENTS Page 3-123 Turning On Highlighting 16 Nov 84 3.2.9.6.10 Turning On Highlighting - 3.2.9.6.10.1 Introduction - The turn_on_highlighting procedure puts the terminal in highlight mode. 3.2.9.6.10.2 The Object Name - turn_on_highlighting 3.2.9.6.10.3 Abstract - This procedure is called to start the highlighting mode. All characters written to the display after this are highlighted. The cursor is not moved and its position is not highlighted. 3.2.9.6.10.4 Parameters - none 3.2.9.6.10.5 Local Constants, Types, And Variables - tbd 3.2.9.6.10.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.10.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.10.8 The Ada Source - PROCEDURE turn_on_highlighting; REQUIREMENTS Page 3-124 Turning Off Highlighting 16 Nov 84 3.2.9.6.11 Turning Off Highlighting - 3.2.9.6.11.1 Introduction - The turn_off_highlighting procedure turns off the terminal's highlighting mode. 3.2.9.6.11.2 The Object Name - turn_off_highlighting 3.2.9.6.11.3 Abstract - This procedure is called to end the highlighting of characters. All characters written to the display screen after this call are not highlighted. The cursor is not moved. If this procedure is called and highlighting is not enabled, unpredictable results occur. 3.2.9.6.11.4 Parameters - none 3.2.9.6.11.5 Local Constants, Types, And Variables - tbd 3.2.9.6.11.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.11.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.11.8 The Ada Source - PROCEDURE turn_off_highlighting; REQUIREMENTS Page 3-125 Entering Character Insert Mode 16 Nov 84 3.2.9.6.12 Entering Character Insert Mode - 3.2.9.6.12.1 Introduction - The enter_insert_mode procedure begins character insertion mode. 3.2.9.6.12.2 The Object Name - enter_insert_mode 3.2.9.6.12.3 Abstract - This procedure is called to begin character insert mode. In this mode, as characters are written to the display screen, all characters to the right of the cursor are moved to the right. The characters at the far right of the display screen are moved off the display screen and lost (wrapping does NOT occur). The cursor is not moved. 3.2.9.6.12.4 Parameters - none 3.2.9.6.12.5 Local Constants, Types, And Variables - tbd 3.2.9.6.12.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.12.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.12.8 The Ada Source - PROCEDURE enter_insert_mode; REQUIREMENTS Page 3-126 Exiting Character Insert Mode 16 Nov 84 3.2.9.6.13 Exiting Character Insert Mode - 3.2.9.6.13.1 Introduction - The exit_insert_mode procedure exits the character insertion mode. 3.2.9.6.13.2 The Object Name - exit_insert_mode 3.2.9.6.13.3 Abstract - This procedure is called to exit the character insert mode. If this procedure is called and character insert mode is not enabled ( the procedure enter_insert_mode previously called), unpredictable results occur. The cursor is not moved. 3.2.9.6.13.4 Parameters - none 3.2.9.6.13.5 Local Constants, Types, And Variables - tbd 3.2.9.6.13.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.13.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.13.8 The Ada Source - PROCEDURE exit_insert_mode; REQUIREMENTS Page 3-127 Scrolling The Actual Display Up 16 Nov 84 3.2.9.6.14 Scrolling The Actual Display Up - 3.2.9.6.14.1 Introduction - The scroll_up procedure causes the terminal screen to scroll up on line. 3.2.9.6.14.2 The Object Name - scroll_up 3.2.9.6.14.3 Abstract - This procedure is called to cause the display screen to scroll up one line. The line at the top of the display screen is lost. The cursor follows the scroll operation (remains on the character it was positioned on). 3.2.9.6.14.4 Parameters - none 3.2.9.6.14.5 Local Constants, Types, And Variables - tbd 3.2.9.6.14.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.14.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.14.8 The Ada Source - PROCEDURE scroll_up; REQUIREMENTS Page 3-128 Scrolling The Actual Display Down 16 Nov 84 3.2.9.6.15 Scrolling The Actual Display Down - 3.2.9.6.15.1 Introduction - The scroll_down procedure causes the display screen to scroll down one line. 3.2.9.6.15.2 The Object Name - scroll_down 3.2.9.6.15.3 Abstract - This procedure is called to cause the display screen to scroll down one line. The line at the bottom of the display screen is lost. The cursor follows the scroll operation (remains on the character it was positioned on). 3.2.9.6.15.4 Parameters - none 3.2.9.6.15.5 Local Constants, Types, And Variables - tbd 3.2.9.6.15.6 Errors - The actual terminal may not have been initialized prior to a call to this procedure. 3.2.9.6.15.7 Exceptions - If the actual terminal has not previously been initialized then the exception driver.unitialized is raised. 3.2.9.6.15.8 The Ada Source - PROCEDURE scroll_down; 3.2.9.7 Errors - See the individual sections. 3.2.9.8 Exceptions - See the individual sections. 3.2.9.9 The Ada Source - PACKAGE BODY driver IS PROCEDURE virtual_terminal_initialize( name : IN string; lines : OUT positive; columns : OUT Positive ) IS NULL; END virtual_terminal_initialize; PROCEDURE close_virtual_terminal IS NULL; END close_virtual_terminal; PROCEDURE interpret ( IN commandstring : string ) IS PROCEDURE erase_to_end_of_screen; PROCEDURE erase_to_end_of_line; PROCEDURE move_the_cursor_to( p_x : IN postiive; REQUIREMENTS Page 3-129 The Ada Source 16 Nov 84 p_y : IN positive ); PROCEDURE insert_line; PROCEDURE delete_line; PROCEDURE deletecharacter; PROCEDURE beep; PROCEDURE write_string( data : IN string ); PROCEDURE new_line; PROCEDURE turn_on_highlighting; PROCEDURE turn_off_highlighting; PROCEDURE enter_insert_mode; PROCEDURE exit_insert_mode; PROCEDURE scroll_up; PROCEDURE scroll_down; END interpret; END driver; REQUIREMENTS Page 3-130 The TCF Package 16 Nov 84 3.2.10 The TCF Package 3.2.10.1 Introduction - This package defines the specification for the terminal capabilities file. 3.2.10.2 Abstract - This package incorporates a variation of the UNIX terminal capabilities data base which is used to define the mapping. The TCF Package defines one procedure called initialize. This initialize procedure opens the TCF data base file, fills in the data structures and then closes the TCF data base file. The 'name' parameter passed in holds the terminal name. This parameter is used to search the tcf file for the terminal characteristics associated with the terminal name. These characteristics are then put into the termcap_operations variable. The variable termcap_operations is used by both the driver package and the vt_input package. 3.2.10.3 Parameters - none 3.2.10.4 Local Constants, Types, And Variables - * max_term_cap_entry - the maximum number of entries in the terminal capabilities file. The maximum length is 1920. * max_string_data - a constant defining the maximum length of a data string. The maximum length is 100. * string_data_array - a string of data with a range of 1 to 100. * termcap_operation_record - a record containing a string, it's length, and any parameters (if required) describing a particular terminal operation. This is the terminal specific data that an ANSI operation is translated into. This data structure is filled by the procedure tcf.initialize from data contained in the terminal capabilities file. * termcap_entry_array - a subtype of a string with a range of 1 to the max_termcap_entry. * termcap_entries_enum - an enumeration of terminal capability entries. These match the entries in the terminal capabilities file. * termcap_operation_array - an array of termcap_operation_records. The array contains all the entries for the terminal of given name from the terminal capabilities file. This array is indexed by the termcap_entries_enum. * termcap_operations - A variable of type termcapoperations array that identify the operations associated with a particular terminal. REQUIREMENTS Page 3-131 Selectors (Functions) 16 Nov 84 3.2.10.5 Selectors (Functions) - none 3.2.10.6 Actors (Procedures) - The following pages describe the specifications for the procedures of the TCF package. REQUIREMENTS Page 3-132 Initialize The Terminal Capabilities File 16 Nov 84 3.2.10.6.1 Initialize The Terminal Capabilities File - 3.2.10.6.1.1 Introduction - The initialize procedure performs intialization on the terminal capabilities file. 3.2.10.6.1.2 The Object Name - initialize 3.2.10.6.1.3 Abstract - Initialize opens the terminal capabilities file, searches this file for capabilties associated with the particular terminal, and associates the capabilities to the termcap_operations array. If the input parameter 'name' is empty then the SYSDEP package is invoked. 3.2.10.6.1.4 Parameters - * name - the name of the terminal passed in from one of the terminal packages (scroll, form, page). 3.2.10.6.1.5 Local Constants, Types, And Variables - tbd 3.2.10.6.1.6 Errors - It may not be possible to open the terminal capabilities file. The named terminal may not be found in the terminal capabilities file. 3.2.10.6.1.7 Exceptions - The exception tcf_error can be raised from this procedure. The exception name_error can be raised from this procedure. 3.2.10.6.1.8 The Ada Source - PROCEDURE initialize ( name : IN string ); REQUIREMENTS Page 3-133 Errors 16 Nov 84 3.2.10.7 Errors - See the individual sections. 3.2.10.8 Exceptions - See the individual sections. 3.2.10.9 The Ada Source - PACKAGE tcf IS -- Constants max_termcap_entry : CONSTANT integer := 1920; max_string_data : CONSTANT integer := 100; -- Types SUBTYPE string_data_array IS string( 1..max_string_data ); TYPE termcap_operation_record is RECORD encoded_data : string; encoded_data_length : integer; parameter : integer; bool_parameter : boolean; END record; SUBTYPE termcap_entry_array IS string( 1..max_termcap_entry ); TYPE termcap_entries_enum IS ( cd, -- clear to end of display ce, -- clear to end of line cm, -- cursor movement i_s, -- initialization string al, -- insert line dl, -- delete line dc, -- delete character be, -- bell nl, -- new line so, -- start standout mode se, -- end standout mode im, -- enter insert mode ei, -- end insert mode sf, -- scroll up sr, -- scroll down ku, -- cursor up key kd, -- cursor down key kl, -- cursor left key kr, -- cursor right key l1, -- function key 1 label l2, -- function key 2 label l3, -- function key 3 label l4, -- function key 4 label l5, -- function key 5 label l6, -- function key 6 label REQUIREMENTS Page 3-134 The Ada Source 16 Nov 84 l7, -- function key 7 label l8, -- function key 8 label l9, -- function key 9 label y0, -- function key 10 label y1, -- function key 11 label y2, -- function key 12 label y3, -- function key 13 label y4, -- function key 14 label y5, -- function key 15 label y6, -- function key 16 label y7, -- function key 17 label y8, -- function key 18 label y9, -- function key 19 label h0, -- function key 20 label h1, -- function key 21 label h2, -- function key 22 label h3, -- function key 23 label h4, -- function key 24 label h5, -- function key 25 label h6, -- function key 26 label h7, -- function key 27 label h8, -- function key 28 label h9, -- function key 29 label v0, -- function key 30 label v1, -- function key 31 label v2, -- function key 32 label k1, -- function 1 key k2, -- function 2 key k3, -- function 3 key k4, -- function 4 key k5, -- function 5 key k6, -- function 6 key k7, -- function 7 key k8, -- function 8 key k9, -- function 9 key x0, -- function 10 key x1, -- function 11 key x2, -- function 12 key x3, -- function 13 key x4, -- function 14 key x5, -- function 15 key x6, -- function 16 key x7, -- function 17 key x8, -- function 18 key x9, -- function 19 key g0, -- function 20 key g1, -- function 21 key g2, -- function 22 key g3, -- function 23 key g4, -- function 24 key g5, -- function 25 key g6, -- function 26 key g7, -- function 27 key g8, -- function 28 key REQUIREMENTS Page 3-135 The Ada Source 16 Nov 84 g9, -- function 29 key t0, -- function 30 key t1, -- function 31 key t2, -- function 32 key wr, -- wraps at end of line su, -- scrolls up at bottom li, -- number of lines co -- number of columns ); TYPE termcap_operation_array is array(termcap_entries_enum) of termcap_operation_record; -- Variables termcap_operations : termcap_operation_array; -- Procedures PROCEDURE initialize ( name : IN string); -- Exceptions tcf_error : EXCEPTION; name_error : EXCEPTION; END tcf; REQUIREMENTS Page 3-136 The System Dependent Package SYSDEP 16 Nov 84 3.2.11 The System Dependent Package SYSDEP 3.2.11.1 Introduction - This package centralizes all system dependencies in the virtual terminal. 3.2.11.2 The Object Name - sysdep 3.2.11.3 Abstract - When rehosting the VT to another environment, only this package should need to be changed. The supported functions are: * open the physical terminal, * close the physical terminal, * put strings to the physical terminal, * get strings from the physical terminal, * get the terminal capabilities file (TCF) name, * get the terminal's name (to be subsequently looked up in the TCF), * check the validity of a particular character. REQUIREMENTS Page 3-137 Selectors (Functions) 16 Nov 84 3.2.11.4 Selectors (Functions) - 3.2.11.4.1 Determining The Validity Of A Character - 3.2.11.4.1.1 Introduction - This procedure is called to determine whether a particular character can be considered valid for this environment. 3.2.11.4.1.2 The Object Name - valid_character 3.2.11.4.1.3 Abstract - Sysdep.valid_character is called to check if the character specified in the input parameter is one that can be used (and therefore considered valid) for this environment. Character that should be considered suspect include: * XON (CTRL-S) * XOFF (CTRL-Q) * (CTRL-Y) * (CTRL-C) 3.2.11.4.1.4 Parameters - There is one input parameter, item, which identifies the character of interest. A boolean value is returned. True indicates that the character is valid and can be used, false indicates that the charater should not be used. 3.2.11.4.1.5 Local Constants, Types, And Variables - TBD. 3.2.11.4.1.6 Errors - The physical terminal may not have been opened prior to calling this procedure. 3.2.11.4.1.7 Exceptions - If the physical terminal has not been opened previously to this then the exception uninitialized will be raised. 3.2.11.4.1.8 The Ada Source - FUNCTION valid_character( item : IN character ) RETURN boolean; REQUIREMENTS Page 3-138 Actors (Procedures) 16 Nov 84 3.2.11.5 Actors (Procedures) - 3.2.11.5.1 Opening The Physical Terminal - 3.2.11.5.1.1 Introduction - This procedure is called to open the physical terminal. 3.2.11.5.1.2 The Object Name - Open 3.2.11.5.1.3 Abstract - Sysdep.open makes the physical terminal ready for receiving characters. The terminal connection should be such that keys that are pressed on the terminal keyboard must not be echoed automatically by the OS. As a general rule the terminal should be configured to accept all character sent to it. Similarly, all characters typed at the terminal keyboard should be returned when sysdep.get is called. This can be compromised somewhat to support flow control or other OS dependent operations. Any characters that are to be used for other purposes and thus not available to the VT should be noted and the function sysdep.valid_character made to reflect this. 3.2.11.5.1.4 Parameters - None. 3.2.11.5.1.5 Local Constants, Types, And Variables - TBD. 3.2.11.5.1.6 Errors - None. 3.2.11.5.1.7 Exceptions - It is assumed that the OS will generate an exception if the terminal could not be opened. This exception will be propogated out of this package. 3.2.11.5.1.8 The Ada Source - PROCEDURE open; REQUIREMENTS Page 3-139 Closing The Physical Terminal 16 Nov 84 3.2.11.5.2 Closing The Physical Terminal - 3.2.11.5.2.1 Introduction - This procedure is called to close the physical terminal. 3.2.11.5.2.2 The Object Name - 3.2.11.5.2.3 Abstract - Sysdep.close performs a close on the physical terminal. The actual actions performed are system dependent. 3.2.11.5.2.4 Parameters - None. 3.2.11.5.2.5 Local Constants, Types, And Variables - TBD. 3.2.11.5.2.6 Errors - None. 3.2.11.5.2.7 Exceptions - It is assumed that the OS will generate an exception if the terminal could not be opened. This exception will be propogated out of this package. 3.2.11.5.2.8 The Ada Source - PROCEDURE close; REQUIREMENTS Page 3-140 Writing Data To The Physical Terminal 16 Nov 84 3.2.11.5.3 Writing Data To The Physical Terminal - 3.2.11.5.3.1 Introduction - 3.2.11.5.3.2 The Object Name - put 3.2.11.5.3.3 Abstract - Sysdep.put is called to write data to the physical terminal's display screen. This data (ideally) is not interpreted or changed by the OS. This can be compromised to support flow control or other system dependent operations. If it is compromised, those special characters must be marked as not valid in a call to sysdep.valid_character. 3.2.11.5.3.4 Parameters - There are two input parameters. * data - the string buffer that the output characters are passed in through. * last - the last position in the string buffer that contains meaningful data. 3.2.11.5.3.5 Local Constants, Types, And Variables - TBD. 3.2.11.5.3.6 Errors - None. 3.2.11.5.3.7 Exceptions - It is assumed that the OS will generate an exception if the terminal could not be opened. This exception will be propogated out of this package. 3.2.11.5.3.8 The Ada Source - PROCEDURE put( data : IN string; last : IN natural ); REQUIREMENTS Page 3-141 Reading Data From The Terminal Keyboard 16 Nov 84 3.2.11.5.4 Reading Data From The Terminal Keyboard - 3.2.11.5.4.1 Introduction - This procedure is called to read data from the physical terminal's keyboard. 3.2.11.5.4.2 The Object Name - get 3.2.11.5.4.3 Abstract - Sysdep.get is called to retrieve data from the physical terminal's keyboard. This data (ideally) is not interpreted or changed by the OS. This can be compromised to support flow control or other system dependent operations. If it is compromised, those special characters must be marked as not valid in a call to sysdep.valid_character. 3.2.11.5.4.4 Parameters - There are two output parameters. * data - the string buffer that the input characters are to be returned in. * last - the last position in the string buffer that contains meaningful data to be returned from this procedure call. 3.2.11.5.4.5 Local Constants, Types, And Variables - TBD. 3.2.11.5.4.6 Errors - None. 3.2.11.5.4.7 Exceptions - It is assumed that the OS will generate an exception if the terminal could not be opened. This exception will be propogated out of this package. 3.2.11.5.4.8 The Ada Source - PROCEDURE get( data : OUT string; last : OUT natural ); REQUIREMENTS Page 3-142 Retrieving The TCF Name 16 Nov 84 3.2.11.5.5 Retrieving The TCF Name - 3.2.11.5.5.1 Introduction - This procedure is called to retrieve the the name of the terminal capabilities file. 3.2.11.5.5.2 The Object Name - tcf_name 3.2.11.5.5.3 Abstract - Sysdep.get_name is called to get the name of the TCF. 3.2.11.5.5.4 Parameters - There are two output parameters: * name - the string buffer that the name of the TCF will be put into, * last - the last significant character in the string buffer. 3.2.11.5.5.5 Local Constants, Types, And Variables - TBD. 3.2.11.5.5.6 Errors - None. 3.2.11.5.5.7 Exceptions - None. 3.2.11.5.5.8 The Ada Source - PROCEDURE tcf_name ( name : OUT string; last : OUT natural ); REQUIREMENTS Page 3-143 Retrieving The Terminal's Name 16 Nov 84 3.2.11.5.6 Retrieving The Terminal's Name - 3.2.11.5.6.1 Introduction - This procedure is called to return the terminal's name. 3.2.11.5.6.2 The Object Name - terminal_name 3.2.11.5.6.3 Abstract - Sysdep.terminal_name returns the name of the terminal. The exact manner that this name is determined is system dependent. This name is the one used to match the TCF entry and retreive the capabilities in the TCF package. 3.2.11.5.6.4 Parameters - There are two input parameters: * name - a string buffer that will contain the name of the terminal when the procedure returns, * last - the last significant position in the string buffer. 3.2.11.5.6.5 Local Constants, Types, And Variables - TBD. 3.2.11.5.6.6 Errors - None. 3.2.11.5.6.7 Exceptions - None. 3.2.11.5.6.8 The Ada Source - PROCEDURE terminal_name ( name : OUT string; last : OUT natural ); 3.2.11.6 Errors - See the individual sections above. 3.2.11.7 Exceptions - See the individual sections above. 3.2.11.8 The Ada Source - PACKAGE sysdep IS PROCEDURE open; PROCEDURE close; PROCEDURE put( data : IN string; last : IN natural ); PROCEDURE get( data : OUT string; last : OUT natural ); PROCEDURE tcf_name ( name : OUT string; last : OUT natural ); PROCEDURE terminal_name ( name : OUT string; last : OUT natural ); REQUIREMENTS Page 3-144 The Ada Source 16 Nov 84 FUNCTION valid_character ( item : IN character ) RETURN boolean; uninitialized : EXCEPTION; END sysdep; REQUIREMENTS Page 3-145 STORAGE AND PROCESSING ALLOCATION 16 Nov 84 3.3 STORAGE AND PROCESSING ALLOCATION Not Applicable. 3.4 PROGRAM FUNCTIONAL FLOW CONTROL 3.4.1 General This section describes the data flow through the NOSC virtual terminal. A physical terminal can be viewed as three seperate and individual devices. * the keyboard, * the display, * the bell. These separate devices will be treated individually in the NOSC VT. Data can flow from the keyboard and to the display independently. Similarly the bell can be rang independently from the other data flow. There are two asynchronous data generators in the NOSC VT. These are the keyboard (actually the user and their fingers) and the user's program. The data that is generated and processed is ANSI standard characters and character sequences. These will conform to the ASCII standard. 3.4.2 Keyboard Data The packages virtual_terminal.scroll_terminal and virtual_terminal.page_terminal treat the keyboard similarly. The form terminal treats the keyboard quite differently. First, a discussion of the flow of data from the keyboard to the user's program through the scroll_terminal and page terminal is given. Assume for the following examples that the appropriate terminal has been previously opened. The sequence that must be followed for a user's program to receive keyboard data is as follows: 1. The user calls either virtual_terminal.scroll_terminal.get or virtual_terminal.page_terminal.get. 2. The body of this procedure makes calls to the package vt_input.get. 3. The body of this procedure makes calls to the package SYSDEP to actually read the data from the keyboard. REQUIREMENTS Page 3-146 Keyboard Data 16 Nov 84 4. The data is returned from SYSDEP to vt_input.get which then returns the data to either virtual_terminal.scroll_terminal.get or virtual_terminal.page_terminal.get which ever is appropriate. For a form terminal the following sequence ocurrs: 1. The user program creates a form by making successive calls to virtual_terminal.form_terminal.define_qualified_area and virtual_terminal.form_terminal.set_position to setup the areas that input will be allowed. 2. A call is made on virtual_terminal.form_terminal.activate_form to place the virtual screen (which contains the form) onto the actual screen. 3. The procedure body of virtual_terminal.form_terminal.activate_form will read data from the keyboard to support the editting functions required of the form terminal by making calls on vt_input.get. 4. vt_input.get will make calls on SYSDEP to get the characters from the keyboard. 5. SYSDEP returns the string from the keyboard to vt_input.get who then passes the data back to the procedure body of activate_form which performs the local editting placing the data in the virtual display. 6. When the user presses a function key control is returned from the call on virtual_terminal.form_terminal.activate_form. 7. The user's program can then place the active position and read data from the virtual display using the various virtual_terminal.form_terminal.get procedures. 3.4.3 User Program Generated Data The data generated by the user program can be destined either for the virtual terminal's internal representation of the display, or the actual terminal's bell. A user's program will never write data directly to the actual terminal's display. Rather, the data is "buffered" in the virtual display until a call is made on any of: 1. redisplay.redisplay_screen_with_movement 2. redisplay.redisplay_screen_with_redraw 3. redisplay.redisplay_line_with_movement 4. redisplay.redisplay_line_with_redraw These procedures make the actual calls to driver to change the representation on the actual display. REQUIREMENTS Page 3-147 User Program Generated Data 16 Nov 84 In the packages virtual_terminal.scroll_terminal and virtual_terminal.page_terminal the data flows from the user's program to the display in the following way: 1. The user's program makes calls to change the representaiton of the virtual display. These calls could be to put data onto the virtual display, move the active position, or change the graphic rendition. 2. When the user's program calls one of the procedures within redisplay, the actual display will then be made to reflect the virtual display. The pacakge redisplay will make calls on driver.interpret to send data to the actual display. 3. driver.interpret will take the data (which is in the form of ANSI compatible character sequences), interpret it and make calls on SYSDEP to send the correct sequences to the actual terminal display. In the package virtual_terminal.form_terminal the data flows from the user's program to the display in the following way: 1. The user's program makes calls to change the representaiton of the virtual display. These calls could be to put data onto the virtual display, move the active position, or change the area intensity. 2. When the user's program calls form_terminal.activate_form, a call is made from within the body of activate_form to the procedure redisplay.redisplay_screen_with_movement to make the actual display look like the virtual display. 3. The package redisplay will make calls on driver.interpret to send data to the actual display. 4. driver.interpret will take the data (which is in the form of ANSI compatible character sequences), interpret it and make calls on SYSDEP to send the correct sequences to the actual terminal display. When the user's program makes a call on virtual_terminal.scroll_terminal.bell or virtual_terminal.page_terminal.bell a call is made from within the procedure body to driver.interpret passing the ANSI sequence to ring the bell. Driver.interpret then makes a call to SYSDEP passing the string that will ring the actual terminal's bell (the exact sequence is found in the terminal capabilities file). REQUIREMENTS Page 3-148 Program Interrupt Control 16 Nov 84 3.4.4 Program Interrupt Control Not applicable. 3.4.5 Subprogram Reference Control 3.4.6 Special Control Features Not applicable. REQUIREMENTS Page 3-149 PROGRAMMING GUIDELINES 16 Nov 84 3.5 PROGRAMMING GUIDELINES These are Texasn Instruments internal programming Guildelines. 3.5.1 Development Environment The programming language for the development of the NOSC virtual terminal shall be Ada. The user's manual shall be the Reference Manual for the Ada Programming Language [DOD83 ]. The support system shall be an Ada Programming Support Environment, specifically ROLM/DG Ada Development Environment. 3.5.2 Ada Programming Standards 3.5.2.1 Introduction - This section contains the various Ada coding practices which will be used on this project. The coding practices are specified as either "standards" or "guidelines." "Standards" are mandatory requirements while "guidelines" denote preferred practices. 3.5.2.2 Prologue Documentation - This section specifies the minimum information to be included in the prologue of a program unit. The prologue provides for program version identification to facilitate configuration management. STANDARD: Each program unit shall have an associated standard _________ prologue directly preceding the program unit. The standard prologue will contain the information shown in Example 1. STANDARD: All prologue information for each program unit shall be _________ present before the code is placed under configuration management control. STANDARD: The Revision History information shall contain the SAR _________ (Software Activity Request) number or equivalent for program version identification by configuration management control. REQUIREMENTS Page 3-150 Prologue Documentation 16 Nov 84 -----------------------PROLOGUE--------------------------------- -- -- Program Unit Name : -- Author : -- Date created : -- Last update : -- ---------------------------------------------------------------- -- -- Abstract : (A one-paragraph overall description -- : of the program unit function.) -- : -- : -- ---------------------------------------------------------------- -- -- Mnemonic : (Exact name program unit is compiled by) -- Name : (Short functional name of program unit) -- Release date : (Preliminary release) -- Revision History (After preliminary release) -- Date Author History -- -- (Explanation of change -- including SAR number) -- ----------------------- END PROLOGUE --------------------------- Example 1. Ada Prologue Example REQUIREMENTS Page 3-151 Naming Conventions 16 Nov 84 3.5.2.3 Naming Conventions - STANDARD: All names shall be understandable, significant, and _________ meaningful. Ada readily supports this objective by imposing almost no limit on the number of characters allowed in a name. [FORE83] STANDARD: The use of the underscore character (_) like the use of the _________ blank in English text strongly enhances readability. The (_) shall be used to separate full English words. Abbreviations may have internal (_) where desired. This standard is illustrated in Example 2. GUIDELINE: Names which look alike due to the overuse of "I", "1", __________ "0", "O", "2", and "Z" should be avoided. Do not select identifier names which might be confused with their contents. Choose names on the basis of what an identifier is FOR, not what the identifier contains. This guideline is illustrated in Example 2. [FORE83] POOR BETTER istemperatureextreme is_temperature_extreme switch_one end_mechanical_testing seven cost_per_unit Example 2. Variable Declarations GUIDELINE: Types should be named as common noun phrases describing __________ the class of things they represent [BOO83]. For example: -- tree, linked_list, index GUIDELINE: Objects/variables should be named as proper noun phrases __________ [BOO83]. For example: -- my_tree, personnel_linked_list, data_base_index REQUIREMENTS Page 3-152 Declarations Usage 16 Nov 84 3.5.2.4 Declarations Usage - 3.5.2.4.1 Commenting Declarations - GUIDELINE: Each constant, type, and object/variable identifier __________ declared should be accompanied by a brief comment if the identifier is not self-explanatory. The comments should be aligned as closely as possible for enhanced readability. This guideline is illustrated in Example 3. 3.5.2.4.2 Declaration Formatting - STANDARD: All declarations shall be aligned and each one shall be on _________ a separate line. Identifier lists shall not be used. This standard is illustrated in Example 3. GUIDELINE: The grouping of declarations should be consistent and __________ follow one of the methods described below. The decision as to which grouping method will be enforced shall be made by the project manager. The grouping methods are : 1. All declarations possessing the same characteristics should be grouped together and commented accordingly. For example, all CONSTANTS shall be together, all TYPES together, etc. Additionally, SUBTYPES should immediately follow their respective TYPES. A blank line should be used to separate the declaration groups. This guideline is illustrated in Example 3 and Example 9. 2. All declarations concerning the same usage should be grouped together and commented accordingly. A blank line should be used to separate the declaration groups. This guideline is illustrated in Example 4. REQUIREMENTS Page 3-153 Declaration Formatting 16 Nov 84 -- constant declarations block_size : CONSTANT := 560; -- physical record length days_per_month : CONSTANT := 31; ending_year : CONSTANT := 2000; -- last applicable year line_buffer : CONSTANT := 80; -- characters per line number_of_slots : CONSTANT := 30; page_size : CONSTANT := 54; -- lines per page screen_size : CONSTANT := 24*80; -- characters per VDT screen -- type declarations TYPE byte IS RANGE 0..16#FF#; -- byte addresses TYPE print_line IS ARRAY (1..line_buffer) OF character; TYPE page IS ARRAY (1..page_size) OF print_line; TYPE month_name IS (jan,feb,mar,apr,may,jun,jul,aug, sep,oct,nov,dec); SUBTYPE summer IS month_name RANGE jun..sep; TYPE queue_slot IS RANGE 1..number_of_slots; TYPE date IS RECORD day : integer RANGE 1..days_per_month; month : month_name; year : integer RANGE 0..ending_year; END RECORD; -- actual variables LAST_MESSAGE_OCCUPIED : QUEUE_SLOT; NEXT_AVAIL_MESSAGE : QUEUE_SLOT; EMPLOYEE_BIRTH_DATE : DATE; IS_EMPTY : BOOLEAN; -- queue status Example 3. Ada Declaration Formatting REQUIREMENTS Page 3-154 Declaration Formatting 16 Nov 84 -- day types TYPE day IS (monday,tuesday,wednesday,thursday, friday,saturday,sunday); today : day; tomorrow : day; -- card types TYPE suit IS (clubs,diamonds,hearts,spades); TYPE value IS ('2','3','4','5','6','7','8','9', '10',jack,queen,king,ace); TYPE player IS (north,west,south,east); TYPE card IS RECORD suit_name : suit; number_value : value; END RECORD; TYPE hand IS ARRAY(1..13) OF card; TYPE table IS ARRAY(player) OF hand; trumps : suit; first_table : table; second_table : table; Example 4. Ada Declaration Formatting 3.5.2.4.3 Use Of Constants - STANDARD: Each character literal or string literal shall be located _________ in the constant declarations. This standard is illustrated in Example 3. STANDARD: Do not embed "MAGIC NUMBER" constants in your code. Such _________ constants lack significance and are difficult to maintain [FORE83]. This standard is illustrated in Example 5. REQUIREMENTS Page 3-155 Use Of Constants 16 Nov 84 If the cost of sensors is 45.50 you might write the following statement to compute the cost of the sensors: sensor_cost := 45.50 * number_of_sensors; It is better to declare a constant, cost_per_sensor, initialized to 45.50, so that your statement would read: sensor_cost := cost_per_sensor * number_of_sensors; As such, changes in the cost of sensors are more easily accomplished since you will only have to make one change and not have to find all other occurrences of the "MAGIC NUMBER". [FORE83] Example 5. Magic Numbers GUIDELINE: The upper bounds of all non-dynamic ARRAYS should be __________ specified by constants. This guideline is illustrated in Example 3. SKIP 1 3.5.2.4.4 Strong Typing - GUIDELINE: The strong typing feature of Ada should be used __________ exhaustively. Types should be distinguished as far as the application allows. Different types should be declared if there is no common processing. [KARL81] GUIDELINE: Avoid declaring and using objects/variables of a universal __________ type, such as INTEGER or FLOAT. An exception to this guideline might be variables of the type BOOLEAN. This guideline is illustrated in Example 6. checking_balance : integer; -- poor TYPE cash_type IS RANGE 100..500; -- better checking_balance : cash_type; Example 6. Universal Types REQUIREMENTS Page 3-156 Coding Conventions 16 Nov 84 3.5.2.5 Coding Conventions - This section specifies coding practices which apply to Ada statements. 3.5.2.5.1 Attributes - GUIDELINE: The use of attributes is recommended for maintainability. __________ If you see a "MAGIC NUMBER", try to use an attribute or declare a constant. [ARPA3] 3.5.2.5.2 Upper/Lower Case Usage - STANDARD: All Ada reserved words shall be one case and all other _________ names shall be the other case. Comments may be mixed case. The examples given here use this standard. 3.5.2.5.3 Statement Formatting For Readability - STANDARD: Each statement shall begin on a separate line. Multiple _________ statements per line are not allowed. This standard is illustrated in Example 7. STANDARD: At least one space shall appear before and after all _________ relational and arithmetic operators. This standard is illustrated in all examples. STANDARD: Indentation is approached with "comb" structures. Examples _________ of proper indentation techniques are shown in Example 7 and Example 8. [ARPA4] REQUIREMENTS Page 3-157 Statement Formatting For Readability 16 Nov 84 IF valve_status = open THEN read_flow(rate); ELSE read_pressure(valve); END IF; ---------------------------------------------------------------- IF indent_on THEN check_left_margin; left_shift; ELSIF outdent_on THEN right_shift; ELSE carriage_return; continue_scan; END IF; ---------------------------------------------------------------- FOR i IN sensor_value_array'RANGE LOOP monitor_value_change(previous_reading_array(i), new_reading_array(i)); previous_reading_array(i) := new_reading_array(i); END LOOP; ---------------------------------------------------------------- WHILE data_available LOOP read(my_file,input_buffer); process(input_buffer); END LOOP; ---------------------------------------------------------------- main_cycle: LOOP get(temp); EXIT WHEN temp = critical_temp; END LOOP main_cycle; Example 7. Statement Alignment And Indentation REQUIREMENTS Page 3-158 Statement Formatting For Readability 16 Nov 84 CASE string_length IS WHEN 0 => string_error; WHEN 1..80 => copy_string; WHEN 81..160 => copy_string; string_length := string_length - max_string; WHEN 161 | 162 => delete_string; WHEN 163 => NULL; WHEN OTHERS => RAISE system_error; END CASE; ---------------------------------------------------------------- TASK sequencer IS ENTRY phase_1; ENTRY phase_2; ENTRY phase_3; END sequencer; TASK BODY sequencer IS BEGIN ACCEPT phase_1; ACCEPT phase_2; ACCEPT phase_3 do initiate_launch; END phase_3; END sequencer; ---------------------------------------------------------------- LOOP -- program unit statements SELECT ACCEPT make_deposit(id : IN account_type; amount : IN cash_type) DO -- program unit statements END make_deposit; OR ACCEPT make_drive_up_deposit(id : IN account_type; (amount : IN cash_type) DO -- program unit statements END make_drive_up_deposit; ELSE do_filing; END SELECT; -- program unit statements END LOOP; Example 8. Statement Alignment And Indentation REQUIREMENTS Page 3-159 Subprogram Usage And Formatting 16 Nov 84 3.5.2.5.4 Subprogram Usage And Formatting - STANDARD: The formal part of each subprogram shall be aligned and _________ coded with one argument per line. Additionally, parameter specification options shall be grouped together according to their mode as either IN, OUT, or IN OUT. This standard is illustrated in Example 9. STANDARD: The END which concludes a PROCEDURE or FUNCTION shall be _________ followed by the name of the program unit. This standard is illustrated in Example 9. GUIDELINE: Subprograms should be named with verb phrases [BOO83]. __________ For example: -- start_mixing_process, sort_list GUIDELINE: Subprograms should be used for main program units, __________ definition of functional control, and definition of type operations. [BOO83] GUIDELINE: Functions that return a boolean value should be named with __________ ______ _ _______ _____ phrases of the form "to be" [BOO83]. For example: -- is_not_empty GUIDELINE: Named parameter association is recommended for improved __________ readability and self-documentation. It also helps disambiguate instances of overloading. [BOO83] REQUIREMENTS Page 3-160 Subprogram Usage And Formatting 16 Nov 84 WITH sample; PROCEDURE analyze_sensor_values IS actual_data : sample.values; fitted_data : sample.values; PROCEDURE get_samples (data : OUT sample.values) IS SEPARATE; PROCEDURE limit_check (data : IN OUT sample.values) IS SEPARATE; PROCEDURE curve_fit (data : IN sample.values; limit: IN sample.values; fit : OUT sample.values) IS SEPARATE; PROCEDURE report (data : IN sample.values) IS SEPARATE; BEGIN get_samples (actual_data); limit_check (actual_data); curve_fit (actual_data, limit_data, fit => fitted_data); report (fitted_data); END analyze_sensor_values; FUNCTION is_odd(value : IN integer) RETURN boolean IS BEGIN RETURN ((value REM 2) /= 0); END is_odd; [BOO83] Example 9. Procedure And Function Formatting GUIDELINE: The use of the WITH statement without the USE statement is __________ recommended for understandability and clarity of locations of program units. This guideline is illustrated in Example 9 and in Example 10. GUIDELINE: Each subprogram or function should contain only one RETURN __________ statement and it must be the statement immediately preceding the END. This guideline is illustrated in Example 10. REQUIREMENTS Page 3-161 Subprogram Usage And Formatting 16 Nov 84 WITH text_io; FUNCTION is_read_flag_on RETURN boolean IS result : boolean; user_input : string(1..80); BEGIN edit_input: LOOP text_io.get(user_input); IF user_input(1..3) = "YES" THEN result := true; EXIT; ELSIF user_input(1..3) = "NO " THEN result := false; EXIT; ELSE text_io.put_line("Invalid response ... try again"); END IF; END LOOP edit_input; RETURN result; END is_read_flag_on; [ARPA5] Example 10. Use Of Return Statements 3.5.2.5.5 Packages, Tasks And Generics - GUIDELINE: Packages should be used for named collections of __________ declarations, groups of related program units, abstract data types, and abstract state machines. [BOO83] GUIDELINE: Tasks should be used for concurrent actions, routing __________ messages, controlling resources, and interrupts. [BOO83] GUIDELINE: Generic program units should be used for factoring the __________ properties of a class of program units, and passing types as parameters to program units. [BOO83] GUIDELINE: Overloading should only be used to name an equivalent __________ action for different types. [BOO83] GUIDELINE: Packages should be named with noun phrases summarizing the __________ package contents [BOO83]. For example: -- math_functions, earth_constants REQUIREMENTS Page 3-162 Packages, Tasks And Generics 16 Nov 84 GUIDELINE: Tasks should be named with noun phrases, usually denoting __________ some action [BOO83]. For example: -- timer, message_router, list_searcher 3.5.2.5.6 Complex Expressions - GUIDELINE: Complex expressions should be parenthesised for __________ readability and understandability. This guideline is illustrated in Example 11. -- poor gamma_value := beta_value + alpha_value / 2 ** 5 * 6; -- better gamma_value := beta_value + ((alpha_value / (2 ** 5)) * 6); Example 11. Complex Expressions 3.5.2.5.7 Labels And GOTOs - STANDARD: The use of LABELs and GOTO statements shall require project _________ manager approval on a case by case basis. 3.5.2.5.8 Task Termination - STANDARD: ABORT shall not be used except as a last resort and shall _________ require project manager approval on a case by case basis. [BOO83] GUIDELINE: Every server task should have a TERMINATE statement to __________ achieve regular termination with its parent unless an ENTRY is provided for termination. [BOO83] 3.5.2.5.9 Exceptions - GUIDELINE: Exceptions should be used as necessary to keep the flow of __________ control in the main body simple and representative of the body. All unusual cases should be handled as exceptions. This guideline is illustrated in Example 12. GUIDELINE: Exceptions should not be suppressed. __________ GUIDELINE: An exception should be captured at the lowest possible __________ level at which the program can properly respond to the error. This guideline is illustrated in Example 12. [BOO83] REQUIREMENTS Page 3-163 Exceptions 16 Nov 84 PROCEDURE driver IS -- ...program unit statments TYPE small IS DIGITS 5 RANGE 0.0..10.0; y : small; x : float; FUNCTION inverse(i: IN float) RETURN small IS BEGIN RETURN small(1.0/i); EXCEPTION WHEN numeric_error => RETURN small'LARGE; END inverse; -- ...program unit statements begin -- ...program unit statements y := inverse(x); -- ...program unit statements EXCEPTION WHEN constraint_error => NULL; END driver; [BOO83/ARPA6] Example 12. Exception Handling REQUIREMENTS Page 3-164 Program Version Identification And CM 16 Nov 84 3.5.3 Program Version Identification And CM The program version identification information is contained in the configuration section of the preamble. This section includes the preliminary release date and the revision history information for tracking. The configuration management procedures will be followed as stated in the NOSC Virtual Terminal Proposal. CHAPTER 4 QUALITY ASSURANCE This program uses a software development methodology which emphasizes object oriented design and development, controlled testing, verification and validation procedures, a baseline defined management and change control system and a software Quality Assurance Program which monitors all phases of the software development life cycle. The software life cycle is divided into unique phases with distinct initiation and termination points for each phase. Provisions for returning to a previous phase of a problem solution are allowed by using comprehensive change control. In all phases up to the test and integration phase, the status and progress are controlled and verified through a series of design reviews and audits. The software testing will be provided through the execution of those tasks necessary to ensure that the software performs, with a high degree of reliability, according to the Proposal. CHAPTER 5 NOTES APPENDIX A THE TERMINAL CAPABILITIES FILE (TCF) 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. 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 Pad? Description al str (P) Add new blank line be str (P) Bell cd str (P) Clear to end of display co num Number of columns in a line ce str (P) Clear to end of line cm str (P) Cursor motion dc str (P) Delete character dl str (P) Delete line ei str End insert mode g0 str sent by terminal function key 20 THE TERMINAL CAPABILITIES FILE (TCF) Page A-2 CAPABILITIES 16 Nov 84 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 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 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 (P) Newline character (default \n) se str End stand out mode sf str (P) Scroll forwards so str Begin stand out mode sr str (P) Scroll reverse (backwards) su bool Scrolls up at bottom of screen t0 str Sent by terminal function key 30 t1 str Sent by terminal function key 31 t2 str Sent by terminal function key 32 v0 str Label on function key 30 THE TERMINAL CAPABILITIES FILE (TCF) Page A-3 CAPABILITIES 16 Nov 84 v1 str Label on function key 31 v2 str Label on function key 32 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 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 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:cd=\E[J:ce=\E[K:cm=\E[%i%2;%2H:co#80:\ :dc=\E[1P:dl=1*\E[1M:ei=\E[4l:im=\E[4h:li#24:\ :se=\E[0m:so=\E[7m:\ :kb=^h:ku=\E[A:kd=\E[B:kl=\E[D:kr=\E[C:\ :k1=\E?a\014:l1=F1:k2=\E?b\014:l2=F2:\ :k3=\E?c\014:l3=F3:k4=\E?d\014:l4=F4:k5=\E?e\014:l5=F5:\ :k6=\E?f\014:l6=F6:k7=\E?g\014:l7=F7:k8=\E?h\014:l7=F7:\ :k9=\E?i\014:l9=F9:x0=\E?j\014:y0=F10:x1=\E?k\014:y1=F11:\ :x2=\E?l\014:y2=F12:x3=\E?m\014:y3=F13:x4=\E?n\014:y4=F14:\ :x5=\E?o\014:y5=F15:x6=\E?p\014:y6=F16:\ :sr=\EM:is=\E<\E[>1;2;3;4;5;6;7;8;9l\E[0m\E[11m\E[?7h:\ :be=\E[?5h\E[?5l: 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" THE TERMINAL CAPABILITIES FILE (TCF) Page A-4 CAPABILITIES 16 Nov 84 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 while the Lear Siegler ADM-3 is described as cl|adm3|3|lsi:\ :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, THE TERMINAL CAPABILITIES FILE (TCF) Page A-5 Cursor Addressing 16 Nov 84 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". 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. If the terminal can scroll the screen backwards, then this can be given as "sb", but just "al" suffices. Think about it. 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 THE TERMINAL CAPABILITIES FILE (TCF) Page A-6 Insert/Delete Character 16 Nov 84 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", "kd", and "kh" 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", etc. If these keys have labels, the labels can be given as "l1", ..., "l9", "y0", "y1", ..., "y6", etc. A.2.8 Initialization An initialization string can be specified to setup the 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: THE TERMINAL CAPABILITIES FILE (TCF) Page A-7 Initialization 16 Nov 84 t1|tv970|tv-970|televideo 970:\ :al=1\E[1L:cd=\E[J:ce=\E[K:cm=\E[%i%2;%2H:co#80:\ :dc=\E[1P:dl=1*\E[1M:ei=\E[4l:im=\E[4h:li#24:\ :se=\E[0m:so=\E[7m:\ :kb=^h:ku=\E[A:kd=\E[B:kl=\E[D:kr=\E[C:\ :k1=\E?a\014:l1=F1:k2=\E?b\014:l2=F2:\ :k3=\E?c\014:l3=F3:k4=\E?d\014:l4=F4:k5=\E?e\014:l5=F5:\ :k6=\E?f\014:l6=F6:k7=\E?g\014:l7=F7:k8=\E?h\014:l7=F7:\ :k9=\E?i\014:l9=F9:x0=\E?j\014:y0=F10:x1=\E?k\014:y1=F11:\ :x2=\E?l\014:y2=F12:x3=\E?m\014:y3=F13:x4=\E?n\014:y4=F14:\ :x5=\E?o\014:y5=F15:x6=\E?p\014:y6=F16:\ :sr=\EM:is=\E<\E[>1;2;3;4;5;6;7;8;9l\E[0m\E[11m\E[?7h:\ :be=\E[?5h\E[?5l: The initialization string is ":is=\E<\E[>1;2;3;4;5;6;7;8;9l\E[0m\E[11m\E[?7h". This string will be sent to the terminal when the VT initializes. APPENDIX B THE RECOGNIZED ANSI X3.64 SEQUENCES The interpreter procedure within the package driver will interpret a subset of the ANSI X3.64 standard sequences. This includes all of the seven bit ASCII characters as well as certain special sequences. The valid ANSI X3.64 sequences that will recognize are given below. Please refer to the ANSI Standard [ANSI79] for a complete description of these control sequences. ANSI Desription Character Designation Codes CSI Control Sequence Introducer ESC [ DCH Delete CHaracter ESC [ Pn P DL Delete Line ESC [ Pn M IL Insert Line ESC [ Pn L ED Erase in Display from active position to end ESC [ 0 J from start to active position ESC [ 1 J all of display ESC [ 2 J EL Erase in Line from active position to end ESC [ 0 K from start to active position ESC [ 1 K all of display ESC [ 2 K SGR Select Graphic Rendition primary rendition ESC [ 0 m reverse image ESC [ 7 m CUP Cursor Position ESC [ Pl ; Pc H SM Set Mode IRM insertion-replacement mode ESC [ 4 h RM Reset Mode IRM insertion-replacement mode ESC [ 4 l APPENDIX C APSE DEPENDENCIES C.1 INTEROPERABILITY AND TRANSPORTABILITY C.1.1 Terminal Communications The system dependent terminal operations including: * opening, * closing, * reading, * writing will be isolated in the package SYSDEP. Only SYSDEP will need to be modified when rehosting this virtual terminal. The TCF package will use standard Ada text I/O to read the terminal capabilities file. The interoperability of this file depends solely on the host system. APPENDIX D GLOSSARY Actual display ______ _______ The user's physical terminal display. Form ____ A way of representing the virtual display that supports the partitioning of the display into separate qualified areas. Form-mode terminal _________ ________ A form mode terminal is a terminal that has form fill-in capabilities (i.e. IBM 3278). That is, the application program presents the user with a form to fill in on his display screen. The user fills in the form by interacting with some local intelligence and transmits the data to the host through some special keystroke(s) (i.e. ENTER key). Page-mode terminal _________ ________ A page mode terminal is a terminal that has a two-dimensional display screen that can be directly addressed and may or may not have any local intelligence (i.e. VT100, Concept-100, Visual-50). Qualified area _________ ____ A set of adjacent character positions on the same line of the form-mode terminal virtual display. A qualified area has attributes such as: intensity, protection, format (numeric, alphabetic, etc), and defaults. Scroll-mode terminal ___________ ________ A scroll mode terminal is a terminal that operates like hardcopy terminal. That is, when a carriage return (or any terminator) is typed the terminal scrolls one line upward. The functionality of this terminal class is severely limited and therefore, is the simplest of the terminal classes. Terminal capabilities file ________ ____________ ____ A file that contains specific information about various terminals. Such information as what ASCII sequences should be sent to move the cursor, the width and length of the screen, what ASCII sequences should be sent to insert a line, etc Transportability ________________ Transportability of an APSE tool is the ability of the tool to be installed on a different KAPSE; the tool must perform with the same functionality in both APSEs. Transportability is measured in the degree to which this installation can be accomplished without reprogramming. GLOSSARY Page D-2 16 Nov 84 Virtual display _______ _______ A representation of the actual display using Ada data structures.