Programmer's ROM - The Computer Language Library

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

/ Programmer's ROM - The Computer Language Library / programmersrom.iso / ada / message / gmhfuser.doc < prev next >

Wrap

Text File | 1988-05-03 | 86.0 KB | 1,938 lines

,print 106 type 86 86 86 86 ,end 73502-85U/P7046 15 April 1985 Revised: 3 May 1985 Generic Message Handling Facility Users Manual 1.0 Introduction. This Users Manual has been developed for users and implementors of the Generic Message Handling Facility (GMHF). Users are those who avail themselves of the software to store, retrieve, edit, and print messages of types for which editors have been instantiated. Implementors are those who instantiate editors for new message standards. This manual is intended to provide the information needed to both use the existing editors and instantiate new editors. Points of contact for additional information or constructive criticism are: Tom Vollman or Don McDougall Veda Incorporated 2 Three Notch Rd Lexington Park, MD 20636 (301)862-2108 ARPANET => CONTR12 @NOSC-TECR 1.1 Background. Veda first developed an automated message editing system for messages of the RAINFORM standard message format in the BASIC language in 1980. Subsequently, enhanced versions have been developed in FORTRAN. Why develop a version in Ada? Doesn't the world have enough message editors without building one more? In fact, the primary goal of this effort has not been simply the delivery of one more message editor, although we hasten to add that we feel a good one has been delivered. The Ada programming language has powerful facilities for defining structured data types, and validating elements to be of said types. In addition, Ada has a powerful generic facility that supports code reuseability and streamlines the software development process. At the same time, the military has a number of highly structured message formats (standards) and is in the process of developing more. Every command and control (C2) system which is fielded typically requires one or more editors for such message types. Therefore, research into how Ada's advanced features can most effectively be applied to message editors is of more than academic interest. In fact, such research can, and almost certainly will provide substantial long term cost savings to the government in terms of reduced software costs for C2 and other message handling systems. This effort has been one of the initial research efforts in this area. 1.2 Overview of GMHF Capabilities. It is important to keep in mind that GMHF has two features: the capability of editing messages, and the capability of creating editors for new types of messages. In this paragraph, we provide a brief overview of GMHF's capabilities in each area. Full details are provided in the GMHF Functional Description (FD), Veda Rpt no chrono-84U/P7046. The FD is available on ARPANET, stored in WIS.VEDA.DOCUMENTS. It is important to note that the FD is an essential part of the user documentation of GMHF, and as specified in the contract, the information contained therein is not repeated here. Therefore, a GMHF user should read the FD prior to using the system. 1.2.1 Message Editing/Handling Capabilities. GMHF allows a user to store messages, retrieve them, edit them and obtain hardcopies. The user may utilize all these facilities via a standalone system. Alternatively, the user may opt to use the editing functions alone, accessing them directly from his/her own message storage system. Once within the editor, standard editing features are implemented: Next Line Previous Line Insert Line Delete Line Edit Line Next Field Previous Field Erase Field Classify Message End Edit. These functions are implemented within the context of a three part CRT display. The top third of the screen displays the current portion of the message being edited, with the current line highlighted. The center portion of the screen holds the line being edited and a prompt as to the required contents of the current field being edited. The bottom portion of the screen is reserved for amplification of field prompts. It allows complicated fields, or fields with a wide range of entry choices to be fully described. As the user enters or modifies the contents of each field in a line, those contents are validated. If invalid entries are made, the user is notified and asked to re-enter valid data. In the case of complex fields, portions of a field may be individually validated. In this way, the user knows that when the message is complete, it is also correct (at least within the bounds defined by the specific implementation). 1.2.1 Generic Instantiation Capabilities. In instantiating the system for a new message type, or in implementing it on a new host, the implementor has a great deal of flexibility. The implementor may specify CRT parameters and how he/she would like the screen partitioned. Complete message structures, including: line types and parameters, field types and prompts, line entry validation, display/transmission format. In fact, the implementor may reuse portions of the code so as to have editors for the same message type which have varying degrees of validation and fault tolerance. 1.3 Security Issues. Some elements of some government message standards are classified. In fact, the full implementation of the RAINFORM editor is classified confidential. Veda has been careful to ensure that none of the procedures or packages which comprise the general part of the GMHF are classified. For demonstration purposes, Veda has provided a partial implementation of the RAINFORM instance which is unclassified and may be made available to anyone on any computer system, regardless of classification. Generally speaking, GMHF is structured in such a way that to implement a classified message standard, only the data definition and io packages need be classified. In some cases, the implementor might also embed classified processing in PACK_LINE, UNPACK_LINE, PARSE_LINE_TYPE, and/or VALIDATE_LINE_INSERTION (see paragraph 3.3, below). The versions of those procedures in the RAINFORM instances are unclassified. 2.0 How to Use GMHF. In this section, the details of how to use GMHF are provided. Much information is contained in the FD, and that information should be read prior to reading this manual. In particular, the FD describes the various menus and how the user interfaces with them. This is covered only briefly here. 2.1 Accessing the System in its Standalone Mode. When accessing the system as a standalone, the user is required to work with the menu driven man machine interface described in the FD. In the standalone mode the user is offered a finite number of functions, which he may access by activating one image,GMHF_DRIVER. This parameter- less procedure will in turn activate the man machine interface menus and the user may perform any of the available functions as desired. It is important to note that while in standalone mode, the system will only access messages within the internal database. To activate the system in standalone mode the user must enter: TEXE GMHF_DRIVER. Where TEXE is the exec for TeleSoft Ada version 2.1. 2.2 External Access to GMHF There are two basic access methods for the external user. One method provides direct access to the editors by an external user while the other method provides external access to GMHF's internal database. These two methods are discussed seperately in the following two sections. 2.2.1 Using the Editors from an External Viewpoint. When it is desired to use the instantiated editors in some fashion other than standalone mode, apart from the actual editors, the user is not provided any man machine interface support. He is instead provided a set of tools and a set of instructions of which to follow. The set of tools and instructions are: 1) Any user modules which require access to the editors must contain "with LINKED_LIST_PROCEDURES;" "with ACCESS_FOR_EXTERNAL_USERS;" "with instantiated_editor;" -- this is the package where the editor -- has been instantiated These packages contain the definitions of several data elements and subprograms which are required for the interface. 2) The user is responsible for loading the message into the EXTERNAL_ MESSAGE format as defined in EXTERNAL_INTERFACE. That format is: type EXTERNAL_MESSAGE is array(POSITIVE range <>) of LINE_OF_TEXT. Where LINE_OF_TEXT is defined as a string length 80. 3) The user is responsible for calling the routine which reformats the message into a linked list for editing. The routine is in the EXTERNAL_INTERFACE package and is called 'LOAD_EXTERNAL_MESSAGE_ INTO_LINKED_LIST'. 4) The user is responsible for activating the editor by calling EDITOR from the appropriate package for the message type. i.e. RAINFORM.EDITOR, UNITREP.EDITOR . 5) The user is responsible for calling the routine which reformats the message back into the EXTERNAL_MESSAGE type. The routine is in the EXTERNAL_INTERFACE package and is called 'RETRIEVE_MESSAGE_FROM_ LINKED_LIST'. Sample: with LINKED_LIST_PROCEDURES; use LINKED_LIST_PROCEDURES; with EXTERNAL_INTERFACE; use EXTERNAL_INTERFACE; with RAINFORM_EDITOR; use RAINFORM_EDITOR; -- procedure EDIT_MY_MESSAGE is CLASSIFICATION : STRING(1..12); MY_MESSAGE : EXTERNAL_MESSAGE; EDITABLE_MESSAGE : MESSAGE; begin . . . user written to load message into external_message type . . -- LOAD_EXTERNAL_MESSAGE_INTO_WORKSPACE(CLASSIFICATION, MY_MESSAGE, EDITABLE_MESSAGE); -- RAINFORM.EDITOR(EDITABLE_MESSAGE); -- RETRIEVE_MESSAGE_FROM_WORKSPACE(CLASSIFICATION, MY_MESSAGE, EDITABLE_MESSAGE); -- . . . user written to do with the message what he wants . . end EDIT_MY_MESSAGE; 2.2.2 External Access to GMHF's Internal Database It may be desired to add messages from some external source into GMHF's internal database or to extract messages from GMHF's internal database for us by some external source. The user is provided a set of tools and instructions to support such access to the database. The set of tools and instructions are: 1) Any user modules which require access to the database must contain "with ACCESS_FOR_EXTERNAL_USERS;" These packages contain the definitions of several data elements and subprograms which are required for the interface. 2) The user is responsible for loading the message into the EXTERNAL_ MESSAGE format as defined in ACCESS_FOR_EXTERNAL_USERS. That format is: type EXTERNAL_MESSAGE is array(POSITIVE range <>) of LINE_OF_TEXT; Where LINE_OF_TEXT is defined as a string length 80. 3) The user is responsible for calling the routines which load and retrieve messages from GMHF's database. There are two routines which perform these functions and they are located in the ACCESS_FOR_EXTERNAL_USERS package. The routines are LOAD_EXTERNAL_MESSAGE_INTO_DATABASE and RETRIEVE_MESSAGE_FROM_DATABASE. Sample: with ACCESS_FOR_EXTERNAL_USERS; use ACCESS_FOR_EXTERNAL_USERS; -- procedure USE_MY_MESSAGE is -- CLASSIFICATION : STRING(1..12); MESSAGE_TYPE : STRING(1..10); MY_MESSAGE : EXTERNAL_MESSAGE; -- begin . . . user written to load message into external_message type . . -- if YOU_WANT_TO_LOAD_MESSAGE_IN then -- LOAD_EXTERNAL_MESSAGE_INTO_DATABASE(CLASSIFICATION, MESSAGE_TYPE, MY_MESSAGE); -- -- in this example all parameters are sent in -- elsif YOU_WANT_TO_GET_MESSAGE_OUT then -- RETRIEVE_MESSAGE_FROM_DATABASE(CLASSIFICATION, MESSAGE_TYPE, MESSAGE_NUMBER, MY_MESSAGE); -- -- in this example message_type and message_number are sent in -- classification and my_message are passed out -- end if; . . . user written to do with the message what he wants . . end USE_MY_MESSAGE; 2.3 Editing a Message. As described in the FD and in the sections above, once a user has entered an editor, there are two modes in which it may be operated, scroll mode and edit mode. We shall discuss these modes separately. Upon entering the editor, the message and its classification are displayed, and the first line is displayed in reverse video (backlit). The backlit line denotes the 'current line'. The user is then placed in scroll mode, and the system awaits the user's input. The command key assignments for a VT 100 are given below. All command keys are implemented for a VT 100 on the numeric keypad. The user must enter numeric data from the standard numeric keys rather than the keypad. ------------------------- |PF1 |PF2 |PF3 |PF4 | | end |erase| next| prev| | edit| fld | fld| fld| ------------------------- |7 |8 |9 |- | | edit| | next| prev| | line| | line| line| ------------------------- |4 |5 |6 |, | |clsfy| |insrt|delet| | msg | | line| line| ------------------------- |1 |2 |3 |enter| | | | | | | | | | | ------------------- | |0 |. | | | tab | back|comm-| | | tab| and | ------------------------- 2.3.1 Scroll Mode. When in scroll mode, the user may scroll through the lines in the message being edited. The only legal user inputs are the commands: * classify message * next line * prev line * insert line * delete line * edit line. * end edit Any other user input will be discarded, and the user will be prompted that an invalid input has been entered. 2.3.1.1 Classify Message. When the user activates the Classify Message command, the classification prompt is displayed and the user is asked to enter either 'UNCLASSIFIED', 'CONFIDENTIAL', 'SECRET', or 'TOP SECRET'. Upon the user's entry of one of those classifications, the classification entered is displayed in the upper left and lower right hand corners of the crt. It is also stored as the classification for the current message. 2.3.1.2 Next Line. When the user activates the Next Line command, one of two things happens. If the user is not currently at the last line of the message, the next line becomes the current line. That is, the line which was the current line is displayed unbacklit, and the next line is displayed backlit. If the user is currently on the last line of the message when Next Line is activated, the prompt which offers the user a choice of line types is displayed. The user then chooses a line type (much like he chose a classification) and a model (prototype) line of that type is displayed as the new current line at the bottom of the message. If the line has any fields, the editor is placed in edit mode, the prototype line is displayed in the work area, the first field prompt is displayed and user input is awaited. Thus one way to get to edit mode is to add a line to the end of a message. The editor assumes that, if possible, the user will want to edit it, and behaves accordingly. The exceptional case is when the user attempts to add a line to the bottom of a message which is already at maximum length. The user is prompted that the message is at maximum length and asked to enter some other command. 2.3.1.3 Previous Line. When the Previous Line command is activated, the previous line becomes the current line unless the current line was the first line of the message. In that case, the user is prompted. 2.3.1.4 Insert Line. The user may activate the insert line command to insert a line directly above the current line. If the number of lines in the message being edited is already at maximum, the user is prompted. If not, the editor proceeds exactly as if the user had activated the Next Line command at the bottom of the message. That is, the user is asked to specify which type of line is to be added, and if that line type is editable, the edit mode is entered. 2.3.1.5 Delete Line. When the user activates the Delete Line command, the current line is deleted, and the message 'repacked'. If there is only one line in the message, the user is prompted that the last line in a message may not be deleted. An entire message may be deleted from outside the editor. 2.3.1.6 Edit Line. When the user activates the Edit Line command, the current line is moved to the work area and the edit mode is entered. The exceptional case is when the current line has no fields; that is, it is not editable. In that case, the user is prompted that a line with no fields cannot be edited. 2.3.1.7 End Edit. When the user activates the End Edit command, the editor is exited and control is transferred to the calling procedure. If the user called the editor from the System Driver package (using GMHF in its stand alone mode) he is presented with a menu which allows him to dispose of the edited message as he sees fit. If the user accessed the editor directly, it is the responsibility of the accessing routine to deal with the edited message. 2.3.2 Edit Mode. The main purpose of the scroll mode is to allow the user to rapidly move through the message to position himself to the line which he wishes to edit. The purpose of the edit mode is to support the actual editing of a line. The following are the commands available to the user while in edit mode: * next field * previous field * erase field * classify message * next line * previous line * end edit When the user is in edit mode, he has the opportunity to modify the contents of the line being edited. However, this can only be done within the constraints placed upon the message type. For example, if the implementor has defined a field whose contents must be an integer between 7 and 32, then the user is not allowed to enter anything else in such a field. The editor accepts user input on a field at a time basis. That is, when the user has entered the (maximum) number of characters in the current field, the editor accepts them, validates them, and either prompts the user that the entry was invalid, or moves on to the next field. It is important to realize that NO CARRIAGE RETURN or ENTER is necessary. The editor will automatically act when the user has completed a field by filling it. In many cases, fields are of variable length, and a user's entry will be fewer characters than the maximum allowed. In such a case, when the user has completed his desired entry he may enter any valid command key. The editor accepts the characters entered, validates them, and then handles the command. The user is assisted by implementor defined prompts for each field. The editor underlines the field being edited, and displays the prompt for that field. A field prompt may be a two part entity. A one line prompt is displayed under the underlined field. Any desired amplifying information is displayed in the bottom portion of the crt (amp area). 2.3.2.1 Next Field. When the Next Field command is activated, the field prompt for the current field is erased, and the prompt for the next field is displayed. The cursor is positioned at the beginning of the enterable portion of the field, and user input is awaited. If the current field is the last field of the line and Next Field is activated, the editor cycles around to the first field of the line. 2.3.2.2 Previous Field. The Previous Field command is analygous to the Next Field command. 2.3.2.3 Erase Field. The Erase Field command causes the current contents of the field being edited to be replaced with the contents of an empty field of that type. 2.3.2.4 Classify Message. The Classify Message command performs exactly the same function here as it does in the scroll mode. The only difference is that when the user has completed classifying the message, the field following the (old) current field becomes current, is prompted, and may be edited. If the user was in the middle of a field when the Classify Message key was struck, the contents of that field are validated prior to activating the Classify Message command. 2.3.2.5 Next Line. The Next Line command performs the same here as it does when activated in scroll mode. The only difference is that prior to activating the command, the contents of the current line being edited are validated and saved. 2.3.2.6 Previous Line. The Previous Line command performs the same here as it does when activated in scroll mode. The only difference is that prior to activating the command, the contents of the current line being edited are validated and saved. 2.3.2.7 End Edit. The End Edit command performs the same here as it does when activated in scroll mode. The only difference is that prior to activating the command, the contents of the current line being edited are validated and saved. 3.0 How to Implement New Message Types. This section describes the steps which must be taken in order to use the generic definition to implement a message editor for a new message type. This section can best be read in conjunction with the Appendices. In addition, a reader should probably browse through the formal part of the generic definition. In order to implement a new message type through generic instantiation, the implementor must complete four steps. Those steps are described in this section in a logical order of execution. The first three steps involve preparing the required entities for the statement which causes the instantiation; the fourth step consists of those activities required to get the message handling system recompiled with the new message type integrated into the structure. Should an implementor desire to implement this system on a terminal which is not a VT-100 or a VT-100 emulator, a fifth step is required. Finally, this implementation uses a procedure MAN_MACHINE_INTERFACE.READ_NOECHO which is based upon a VMS kapse package HOST_LCD_IF. If the system is to be implemented in another Ada environment, the availability of an equivalent to HOST_LCD_IF will have to be examined. It is important to note, that there is no hard requirement for reading without echoing the terminal input back to the screen. However, it sweetens the user interface by allowing the use of CTL and ESC sequences for commands without requiring screen echoes to be erased. 3.1 Line Structure Definition. To accomplish this first step, there are several tasks which must be completed. These tasks involve specifying three numeric parameters of the line structure, giving names to line types and field types, and defining the details of the line structure in a file. A utility program is available which creates the file in the required format. An alternative method for defining the line structures is discussed in Appendix D. In the alternative method, the line structure is not defined in a file but is compiled as a constant. This method uses a different generic definition. The difference is transparent to a user. The first task is to create those entities which describe the structure of each of the formatted lines being implemented. This is done by identifying: a. The maximum number of fields that occur in any type of line being implemented. If some lines have no (changeable) fields while others have 1 or 2 or even 27 fields, then the maximum number of fields is the number of fields contained in the line which has the most fields. b. Similarly, the maximum number of characters which may occur in the longest line must be identified. c. Finally, the maximum number of lines which may be contained in a single message must be specified. These numbers are passed as actual parameters during generic instantiation. The next task in this first step is to provide the generic with a set of names for the various lines. This is accomplished through an enumerated type, which is passed to the generic as an actual parameter. Each line must be represented by a unique item of the enumerated type. While the names given lines need have no relation to the content normally associated with a line of that type, one should attempt to enhance code understandability by using names which relate to content wherever possible. The next task is to specify names for each type of field associated with the message standard. This is done exactly as were the line names. It is important to note that the same field may be used in many different lines. Furthermore, it may be used in the same line more than once. Thus a field is a structural entity in its own right, and by defining the structure of fields, we are defining a set of building blocks which are used to make up lines. Details on the specification of line names, field names and field I/O are given in Appendix A. The final task in this step is to create files which will contain the structure of each line and the prompts for each line. The implementor accomplishes this by first creating editable files using some text editor - we use EDT on the VAX. The format for those files and detailed instructions on how to build them are given in Appendix B. Upon completing the creation of the editable files, utilities (see Appendix B) are run which create the files in formats readable by other GMHF procedures. As part of the process of creating the editable file and running the utilities, the user will be asked to specify a name for the output files which are created by the utilities. These filenames are passed as actual parameters when instantiating the generic. 3.2 Field I/O. The unit of information entered by a GMHF user is a field, or in some cases a component. The most difficult task for an implementor is the specification of field io. There are two requirements. First, the user must develop a procedure to be passed as an actual parameter which matches the formal parameter GET_FIELD. Depending upon the number and complexity of the fields used in the particular message type being implemented, this may be a significant task. The task is made simpler by the various predefined io packages listed in Chapter 14 of the Ada LRM. The second task is development of a set of field prompts for display during an editing session. The second task is optional to the extent that a single standard prompt could be used; that approach would not take full advantage of the editor's capabilities. First, the user must develop a GET FIELD routine. This routine has six parameters: field_type : in field_name - a variable stating the name of the type of field being edited. field_gotten : in out string - a string containing the current contents of the field - both before and after the call to GET_FIELD. field_position : in positive - the column number of the first character of the field on the screen during editing. field_length : in positive - the maximum number of characters possible in a field of this type. command_gotten : out command - a variable to return any user entered command to the editor. command_flag : out boolean - a flag to tell the editor whether the user entered a command. The first parameter is passed to GET_FIELD so that GET_FIELD will know what kind of field is to be input. The existing contents of the field are passed in field_gotten. Whatever the user inputs will modify the contents of field_gotten which is then returned to the editor. The third and fourth parameters will (probably) be required by GET_FIELD for cursor positioning and dimensioning of arrays. The final two fields are "passed through" GET_FIELD from the READ routine to the editor. While the implementor may develop any kind of GET_FIELD routine he or she chooses, Veda has developed a number of procedures which may be used by GET_FIELD, and which are in fact used by other portions of the system. A detailed set of implementation recommendations for GET_FIELD is given in Appendix A; the general structure is discussed here. GET_FIELD is called by the PROCESS_EDIT_LINE_COMMAND procedure. It (as we see it) should call the procedure MMIP.READ; READ gets a string entered by the user. It watches for user entered commands, accepting them without echoing them to the screen. It returns the user entered (actually user modified) string, and any command entered. Thus GET_FIELD can use MMIP.READ to interface with the user and obtain the user's input. Thus GET_FIELD must only validate the user entered data. If the data entered were valid, GET_FIELD returns to the editor which processes the data and any command which might have been entered. If the data did not represent a valid entry for a field of the type being input, then GET_FIELD should (probably) prompt the user that the input was invalid, reset the cursor to the starting position of the field on the screen, and accept the user's next attempt at entering the data. These latter functions can be performed using the procedures MAN_MACHINE_INTERFACE.PROMPT and TERMINAL_DEFINITION.GOTO_CRT_POSITION. Thus, generally speaking, GET_FIELD may be implemented as a case statement based upon field type. In each case it either calls MMIP.READ itself or calls a routine which then calls MMIP.READ. Upon return from READ, GET_FIELD validates the data and returns to the editor. The data validation can be performed by reading the data from the field_gotten string into a variable of the appropriate type and letting Ada raise an exception if the data are not valid. Again, the details of one approach to implementing GET_FIELD are given in Appendix A. The second task in this step is the definition of the field prompts. When the user is editing some field of a line, he/she may be prompted as to the desired/required contents of that field. Space is available on the screen for the display of such prompts. The user must create a file of field prompts, the name of which is input to the generic as an actual parameter. This is accomplished in a manner similar to the creation and naming of the line structure definition file discussed above. Details are provided in Appendix B. 3.3 Line Handling Procedures. The third step in implementing GMHF for a new message type is the implementor's specification of how lines are to be handled. The generic definition allows the user to pass five procedures as actual parameters, only two of which are required. The first two procedures are PACK_LINE and UNPACK_LINE; defaults are supplied which are, in essence, null procedures. These procedures allow the user to edit the line in one format, while storing it in another. If such flexibility is neither desired nor required, the defaults may be used. For example, some message standard formats define their lines in a fixed format. UNITREP is an example of such a format. Certain fields always start in certain columns. Other message standards are more free in their format. One example of such freeness is the elimination of superfluous blanks from an empty field, or from a field whose length is variable. The editor allows the lines to be displayed in their expanded form for user input, but stored in a more condensed form. RAINFORM is an example of a message standard with some level of freeness. When a line is being taken from storage and moved into the workspace for the user to edit, UNPACK_LINE is called. When the user finishes editing the line, PACK_LINE is called prior to re-storing it. For example, if a user is editing line seven of a message with eight or more lines, and presses the NEXT LINE command key, PACK_LINE will be called and line seven will be packed and stored. Then line eight will be retrieved from storage, UNPACK_LINE will be called, and the unpacked form of line eight will be displayed in the work area for user edit. Thus the implementor has the option to determine what difference, if any, there is to be between the stored format of the line, and the format displayed for editing. Note that it is the packed format which is displayed in the message area (the top portion) of the screen during an edit session. In this way the user sees what is being stored. Note also that both the packed and unpacked versions of the lines are stored as character strings. The third procedure which a user may provide is VALIDATE_LINE_INSERTION. This procedure is also defined with a 'null' default, and is thus optional for the implementor. It is called by the editor when the user has specified the type of a new line to be added to the message. The implementor can use this procedure to prompt the user regarding the validity of the line choice specified, or may take whatever stronger action is required. The fourth procedure is PARSE_LINE_TYPE and is required. When a user calls the editor, he/she must specify which message is to be edited. That message is then read into the workspace from the external file by the editor. The file holds each line as a string of variable length, and reads it into a string of length MAXIMUM_CHARACTERS_PER_ LINE. PARSE_LINE_TYPE is required to determine, based upon the string of characters which comprise the line, the line type of the line. PARSE_LINE_TYPE is passed a pointer (access variable) to the string, and must return a value of type LINE_NAME. The final procedure is GET_LINE_NAME and it is also required. When a user asks to insert a line, he must specify which line type he desires to add to the message. GET_LINE_NAME accepts the user's keyboard entry as input and validates that it is a legal entry. 3.4 Instantiation and Recompilation. When the three steps discussed above have been completed, the implementor can heave a sigh of relief, because he or she is just about done. The final step is to put all the pieces together and recompile the system. This is done as follows. First, package TYPELIST is edited, and a name for the new message type being implemented is inserted in type AVAILABLE_TYPES. Then a package must be created to instantiate the new editor and CALLEDIT.TXT must be updated "WITH" the new package and to call the editor upon request. In theory, all that information could be placed in one package; however, certain implementations of Ada place rather stringent requirements on the size of compilation units. Such restrictions may require the implementor to further segment components into artificial subcomponents. Finally, certain GMHF components must be recompiled. The order of recompilation is given below. A complete discussion of GMHF recompilation and interpackage dependencies is given in Appendix C. 1. Compile package(s) containing line name and field name definitions. 2. Create line structure, field prompt, and prompt look-up files. 3. Compile package(s) containing GET_FIELD procedure and any associated data types. (There may be several) 4. Compile package(s) containing PACK_LINE, UNPACK_LINE, VALIDATE_LINE_INSERTION, PARSE_LINE_TYPE, and GET_LINE_TYPE. 5. Recompile TYPELIST. 6. Recompile FILE_ACCESS_PACKAGE (specification & body) 7. Compile new package which instantiates generic 8. Recompile CALL_EDITOR (specification & body) 9. Recompile PRINT_PACKAGE (specification & body) 10. Recompile GENERAL_MENU_ROUTINES (specification & body) 11. Recompile SYSTEM_DRIVER (specification & body) 12. Recompile the driver procedure GMHF_DRIVER 3.5 Reimplementing for a CRT Which Is Not a VT-100 Emulator. All CRT dependencies are confined to the TERMINAL_DEFINITION package. These dependencies may be grouped into four general types: CRT physical size and layout parameters, assignment of user command keys, CRT related procedures, and menu display files. 3.5.1 CRT Layout. The implementor may modify the number of rows and columns that define a particular CRT. Within those parameters, the implementor may modify the division of the screen into three horizontal slices. It is important to note that the message area should not start above line 3, and that the work area must be at least 4 rows deep. The implementor may change the locations where the message classification is displayed. In fact, if a specific application does not deal with messages which may be classified, the implementor may opt to 'null-out' the procedure CLASSIFICATION_DEFINITION.DISPLAY_ CLASSIFICATION. 3.5.2 User Command Keys. The present implementation uses escape (ESC) sequences to denote user commands. As can be seen in sections above, these are implemented via the numeric keypad on a VT-100 terminal. The same sequences may be used on virtually any ASCII terminal. However, if for any reason an implementor wishes to change the assignment of commands to keyset keys, the types FUNCTION_KEY, SYSTEM_DRIVER_KEYS, and EDIT_FUNCTION_KEYS may be edited. Furthermore, if the implementor would prefer to use another character than ESC for a lead-in character (e.g. CTL), the element START_OF_FUNCTION may have its initialization clause modified. 3.5.3 CRT Procedures. Those CRT related procedures used within the GMHF are listed in the specification of the TERMINAL_DEFINITION package. They should be easy to modify/emulate on virtually any modern CRT. 3.5.4 Menu Display Files. The seven menus used in GMHF are currently stored in the files EDITMENU.DSP, GMHF.DSP, GMHF1.DSP, GMHF12.DSP, GMHF2.DSP, GMHF3.DSP, and GMHF31.DSP. These files are intended for use on a VT100, as they use VT ESC sequences. They may require minor modification if the system is rehosted on another terminal. The only changes required are for positioning the cursor and turning on and off the underline attribute. The latter is not required, but is makes the displays look nicer. 4.0 Current GMHF Status. 4.1 Functional Problems (Bugs). There are no known bugs in GMHF at this time (version 1.0). 4.2 Implementation Compromises (Kludges). The problems encountered to date which have impacted GMHF system development and structure include: * limitation of executable blocks to 32768 bytes * problems with nested generics * failure to support incomplete type definitions within generics * failure to support separate compilation of subunits of generics These problems have forced the GMHF to be structured in a manner which is somewhat less than optimal. In particular, the first problem mentioned above has caused what should be one routine, GET_FIELD to be broken into several, as discussed in Appendix A, below. Also, the package GENERIC_MENU_ROUTINES need not exist as a stand-alone package; its proper place is as a subset of the SYSTEM_DRIVER package. EDITOR_TYPES would not exist if we could instantiate generics within a generic. This problem forces us to define parameters which should actually be dependent upon generic parameters outside of the generic. This is serious as it requires that 'maximum values' for certain parameters be 'hard coded' into the system instead of being determined in an instantiation. LINKED_LIST_PROCEDURES should be a subpackage of the generic definition. However, the inability to use incomplete type definitions within generic definitions makes that, at present, impossible. This causes the same problem that was mentioned in the last paragraph. In both cases, additional compilation units are needlessly required; they do not add to program clarity or structure, rather the opposite. Separate compilation of generic subunits has not altered the structure of the GMHF, but has substantially increased the required debugging time. While that is not a factor for users to be concerned with, it is for future maintenance personnel. 4.3 Alternative Approaches (Improvements/fixes). Aside from the restructuring implied in the paragraph above, there are two additional improvements which might be made. First, all enumerated I/O should be done with minimal user entry. This can be implemented by displaying the choices in a prompt and having the user enter a prefix, or by selection from a list. This would be easy to implement using a package of R.G. Cleaveland. The second change is not strictly speaking an improvement, but rather a look at an alternative method of storing the data. Rather than inputting structured types, and converting to strings, we might experiment with maintaining the data in structured types. This might limit the flexibility provided the user on input, but would be an opportunity to further explore the bounds of how Ada can be used to implement complex data structures. Appendix A. Defining Data Structures and Implementing GET_FIELD. In the first section of this appendix, we discuss the various utilities which are available to support the instantiation process. In the second section, we present what seems to us to be a well-structured approach to building and storing the data types and elements needed, and the GET_FIELD procedure. In the third section we present what we actually had to do, due to current compiler constraints. A.1 Utilities Available to Support Implementation. There are three sets of utilities which are available for use by implementors. The utilities will be of use in generating the procedures required to implement a new editor. An implementor may have to develop (and pass as actual parameters to the generic) any or all of: get_line_name get_field pack_line unpack_line validate_line_insertion parse_line_type. While the task of generating the first versions of these routines was non-trivial, future implementors will benefit from the experiences of their predecessors. In particular, new versions these programs which are required for future instantiations may be more easily implemented by making use of the utilities discussed here. The three types of utilities are: subprograms which are part of the underlying GMHF system and which are not message type dependent; subprograms which were developed to simplify the development of the RAINFORM and Unitrep instances, and which may have utility in other instantiations; subprograms which generate the files required for a new message type. The first set of utilities consists of all those routines which are visible in the packages: TERMINAL_DEFINITION, MAN_MACHINE_INTERFACE, CLASSIFICATION_DEFINITION, LINKED_LIST_PROCEDURES, FILE_ACCESS, PRINT_PROCEDURES, GENERIC_MENU_ROUTINES, SYSTEM_DRIVER, and EDITOR_TYPES. Those routines in the first two packages listed will likely be especially useful. They include such utilities as cursor movement and user prompting which almost certainly will be required by any implementor. The second set of utilities consists of the procedures contained in STATIC_GET_FIELD_UTILITIES and in GENERIC_GET_FIELD_UTILITIES. These utilities were developed to support the development of the RAINFORM version of GET_FIELD, and were used in the development of the Unitrep version. They support integer, decimal, character, and enumerated type I/O within the GMHF structure for prompts and user interface via command entries. The third set of utilities are routines which convert user created files into direct access files used by the editor. These programs are contained in the package FILE_UTILITIES, and are called by executing certain parameterless procedures. Their use is discussed in Appendix B. A.2 Recommended Implementation Structure. The simplest way of implementing the data and I/O required for a new message standard is presented below. It involves defining objects, types, subprograms, and files. The objects and types are discussed in this section, as is the GET_FIELD procedure. Other subprograms are straightforward but message type dependent. Guidance for those may be obtained from the generic definition and by looking at the existing RAINFORM and Unitrep examples. The creation of the files is discussed in Appendix B, below. package NEW_MESSAGE_DATA is -- -- these first three elements are not really required here, and -- could simply be specified as literals in the statement which -- instantiates the generic. -- NEW_MESSAGE_MAXIMUM_FIELDS_PER_LINE : positive := ??; NEW_MESSAGE_MAXIMUM_CHARACTERS_PER_LINE : positive := ??; NEW_MESSAGE_MAXIMUM_LINES_PER MESSAGE : positive := ??; -- -- We now define the names which we give to the lines in the -- new message type. -- type NEW_MESSAGE_LINE_NAMES is (LINE_NAME_1,LINE_NAME_2, . . . LINE_NAME_N); -- -- We now provide the a routine to accept user input of a -- line name. -- procedure GET_LINE_NAME(LINE_TYPE : out NEW_MESSAGE_LINE_NAMES); -- -- We now define the names which we give to the fields in the -- new message type. -- type NEW_MESSAGE_FIELD_NAMES is (FLD_NAME_1, FLD_NAME_2, . . . FLD_NAME_M); -- -- We now define the field types associated with the field -- names. By and large, these field types fall into two -- categories: constrained predefined Ada types, and new -- enumerated types. Veda adopted a convention that for -- enumerated fields, we assigned the most appropriate name -- to FLD_NAME_K (ie. to the corresponding item of -- NEW_MESSAGE_FIELD_NAMES) and named the associated type -- FLD_NAME_K_TYPE (ie. we appended the suffix 'TYPE' to the -- field name given in NEW_MESSAGE_FIELD_NAMES). There may be -- some fields which are in essence records (several components) -- which have as a component an enumerated type. Since the -- component is not named in NEW_MESSAGE_FIELD_NAMES we need not -- append the suffix 'TYPE' after the most appropriate name. -- -- For example, LATITUDE might be a field name. Then we could -- have type LATITUDE_DEGREES is natural range 0..89; -- type LATITUDE_MINUTES is natural range 0..59; -- type NORTH_SOUTH_CARDINAL is (N,S); -- -- -- having defined all the data types, one can then define the -- I/O routines for these types. Veda has included a package -- GET_FIELD_UTILITIES which contains procedures for getting -- constrained integer, decimal, and character types. It also -- provides a generic definition of a routine for getting -- enumerated types, and two special purpose generics for -- getting enumerated types for data elements which -- start with digits, or which contain blanks and/or hyphens. -- It is worth noting that all of these routines rely on -- existing Ada routines or generic definitions, which are -- embedded in our procedures. In this way we minimize new -- code development while maintaining an integrated user -- tolerant interface. -- -- -- Having defined the data structures and I/O routines, we now -- define the GET_FIELD procedure whose format is as follows: -- procedure GET_FIELD(FIELD_TYPE : in NEW_MESSAGE_FIELD_NAMES; FIELD_GOTTEN : in out string; FIELD_POSITION : in positive; FIELD_LENGTH : in positive; COMMAND_GOTTEN : out COMMAND; COMMAND_FLAG : out boolean) is -- some local data definitions begin COMMAND_FLAG := false; COMMAND_GOTTEN := nil; case FIELD_TYPE is when FIELD_NAME_1 => -- statements for getting a field of this type when FIELD_NAME_2 => -- statements for getting a field of this type end case; end GET_FIELD; end NEW_MESSAGE_DATA; Obviously, the body of GET_FIELD would go in the body of NEW_MESSAGE_DATA; also,the other procedures which are to be passed as actual parameters in the instantiation process might also be put in this package. A.3 Actual RAINFORM Implementation Structure. In the case of the RAINFORM instance, the version of the compiler in use (Telesoft 2.1) constrained executable modules (xxx.COD) to 32k bytes. The RAINFORM line standard has many line types and even more field types. Therefore the structures required for instantion are contained in five packages. The line names, field names, and enumerated types are contained in mini_lines_and_fields. The procedures which are to be passed as actual parameters to the generic definition are found in formal_ generic_parameters (in honor of what they are to be matched with). However, although GET_RAINFORM_FIELD is contained in that package to become the actual get_field, it was too big to keep in one place. Therefore five subsidiary packages are used: sub_pkg_1, sub_pkg_2, ... sub_pkg_5. These subpackages contain the routines required to input values of enumerated types. Thus in some cases, GET_RAINFORM_FIELD calls procedures in sub_pkg_1 ( or _2 or _3 or _4 or _5). Finally, to support the input of user entered data, several utility procedures were developed which are either called by GET_RAINFORM_FIELD, or by routines called by GET_RAINFORM_FIELD. These are found in static_get_field_utilities. In addition, the enumerated io was facilitated by several generic definitions. These are found in generic_get_field_utilities. One of the routines is general in nature while the others are somewhat dependent upon the RAINFORM message data types. Even these last may be useful when modified to deal with data types found in other message standards. A.4 Generic Message Editor Formal Part. Here we give the formal part of the generic definition. ************************************************************************ package file_generic is -- this generic definition reads the line structure from a file -- which is passed as a generic parameter generic maximum_fields_per_line, maximum_characters_per_line, maximum_lines_per_message : positive; type line_name is (<>); with procedure get_line_name(line_type : out line_name) is <>; type field_name is (<>); -- and the legal field names. line_structure_file_name : string; prompt_vector_file_name : string; --holds lookup table for field pmts field_prompt_file_name : string; -- holds field prompts themselves with procedure get_field(field_type : in field_name; field_gotten : in out string; field_position : in positive; field_length : in positive; command_gotten : out command; command_flag : out boolean) is <>; with procedure pack_line(line_to_pack : in out line_of_text; line_format : in line_definition) is null_procedure; with procedure unpack_line(line_to_unpack : in out line_of_text; line_format : in line_definition) is null_procedure; with procedure validate_line_insertion is null_procedure; with procedure parse_line_type(pointer_to_line : node; line_type_found : out line_name); package filed_generic_message_editor is -- -- in the real generic, there are some variables defined here. -- procedure editor(message_passed : in out message); end filed_generic_message_editor; end file_generic; Appendix B. Creating the Line Structure, Field Prompt, and Lookup Table Files. I. Creating Line Structure File General Purpose: A sequential file must be created which contains definitions of all Line Types for a particular message type. This file can be easily edited using a line or full screen editor (e.g. EDT). The data file will be validated and processed into a direct access file for use by the editior. Specific Process: 1) editing source file - Edit a file with the name of your choice but with suffix '.sce' (e.g. RAINFORM.SCE). For each unique line of the particular message type, enter the required information in the following format: ----------------------------------------------------------------- record # information ---------- --------------------------------------------------- n line_name n + 1 number_of_fields n + 2 prototype_line n + 3 field_name position length required_flag n + 4 field_name position length required_flag . . . . . . . . . . ----------------------------------------------------------------- Where: line_name- is a value from the enumerated type which contains all line_names for the message type number_of_fields- may range from 0 to the maximum fields per line for the message type prototype_line- string enclosed in quotation marks. This string should represent how the line would look with no data entered in it. There is no set length for a prototype_line but the length may not exceed the maximum characters per line for the message type. If the prototype_line can not be fit on one line, the continuation character '&' may be used to signify continuation on the next line. The '&' must be the next character following the closing '"' of the first line of text for the prototype_line. ( e.g. "SAMPLE PROTO LINE / / / WITH "& "A CONTINUATION ONTO THE NEXT LINE " ---- | | field_name- is a value from the enumerated type which contains | all field_names for the message type | | position- integer representing where in the prototype line need | this field begins this | for -| length- integer representing the length of the field each | field | required_flag- boolean value which is set to true if an entry | into the field is required for the line to be valid. Set to | false if the field isn't required | ---- 2) Once the data has been entered for each line of the message type, the file should be saved. The user then must prepare the file formatting routines which process the file and place the data in a direct access file. The steps for doing so are as follows: i) Edit the file linefield.sp. This file should be a package specification which contains the following: - an enumerated type LIST_OF_LINES which contains the line names for all lines of the message type - an enumerated type LIST_OF_FIELDS which contains the field names for the message type. - a positive constant MAXIMUM_FIELDS_PER_LINE - a positive constant MAXIMUM_CHARACTERS_PER_LINE ii) Compile the file linefield.sp then compile the file buildfile.txt iii) Execute the program LINE_MAKER. This will validate and reformat the source file you have edited. If you have any errors in the source file the program will kickout with an appropriate error message, usally having to due with an illegal line name or field name. The error message will specify the line number in the source file which the error was raised. Once the file is completely validated and reformatted, the end product will be a file of the same name as the source but with a '.DES' suffix. The process is then complete. The filename may then be passed as an actual parameter for the instantiation of a new editor. II. Creating Prompt File General Purpose: A file must be created which contains text for each prompt to be displayed during an edit session. The prompts are used to aid a user in editing a message by providing specific information about the field currently being edited. This file can be easily edited using a line or full screen editor (e.g. EDT). The data file will be processed into a direct access file for use by the editor. Specific Process: 1) editing source file - Edit a file with the name of your choice but with suffix '.sce' (e.g. RFPROMPT.SCE). For each unique prompt of the particular message type, enter the required information in the following format: ----------------------------------------------------------------- record # information ---------- --------------------------------------------------- n prompt_text n + 1 number_of_amp_prompts n + 2 row,column,amp_prompt_text n + 3 row,column,amp_prompt_text . . . . . . . . . . ----------------------------------------------------------------- Where: prompt_text - is a text string enclosed in '"'. This string of text will appear in the work area of the edit screen, centered underneath the field for which it supports. number_of_amp_prompts - may range from 0 up to the maximum number of amp lines that will fit on the screen - at present with a VT-100 that maximum is 5. This number represents how many amp prompts are to follow for this particular field prompt. ---- | | row- integer representing what row on the crt the amp | text will appear | | column- integer representing what column on the crt the amp need | text will begin being displayed this | for -| amp_prompt_text- text_string enclosed in '"'. This text will each | appear in the amp area of the edit screen at the location amp | specified by row and column | | | ---- Note: There are two prompts which are required in this file, a prompt which displays the list of possible classifications for the messages and a prompt with the list of available line names for the message type being instantiated. You may look at the existing '.sce' files for examples of these prompts. 2) Once the data has been entered for each prompt of the message type, the file should be saved. Then execute the program PROMPT_MAKER. This will validate and reformat the source file you have edited. If you have any errors in the source file the program will kickout with an appropriate error message. The error message will specify the line number in the source file which the error was raised. Once the file is completely validated and reformatted, the end product will be a file of the same name as the source but with a '.DES' suffix. The process is then complete. The filename may then be passed as an actual parameter for the instantiation of a new editor. III.Creating Look_up Table File General Purpose: A sequential file must be created which contains a cross reference between each line and the field prompts associated with the fields of the line. This file can be easily edited using a line or full screen editor (e.g. EDT). The data file will be processed into a direct access file for use by the editor. Specific Process: 1) editing source file - Edit a file with the name of your choice but with suffix '.sce' (e.g. RFLUT.SCE). For each unique line of the particular message type, enter the required information in the following format: ----------------------------------------------------------------- record # information ---------- --------------------------------------------------- n line_name,prompt_record_number,prompt_record_number... . . . . . . . . . . ----------------------------------------------------------------- Where: line_name - is the line name for which the prompts support. need ---- one | for | prompt_record_number -represents the record number in the each | prompt '.des' file where the prompt for the particular field of | field is located. line | ---- Note: The first entry in this file should be: SPECIAL, classification_record_number, line_names_record_number 2) Once the data has been entered for each line of the message type, the file should be saved. The user then must prepare the file formatting routines which process the file and place the data in a direct access file. The steps for doing so are as follows: i) Edit the file linefield.sp. This file should be a package specification which contains the following: - an enumerated type LIST_OF_LINES which contains the line names for all lines of the message type - an enumerated type LIST_OF_FIELDS which contains the field names for the message type. - a positive constant MAXIMUM_FIELDS_PER_LINE - a positive constant MAXIMUM_CHARACTERS_PER_LINE (*** NOTE You may already have done this for the ***) (*** structure file. DO NOT repeat it if so. ***) ii) Compile the file linefield.sp then compile the file buildlut.txt iii) Execute the program LUT_MAKER. This will validate and reformat the source file you have edited. If you have any errors in the source file the program will kickout with an appropriate error message, usally having to due with an illegal line name or field name. The error message will specify the line number in the source file which the error was raised. Once the file is completely validated and reformatted, the end product will be a file of the same name as the source but with a '.DES' suffix. The process is then complete. The filename may then be passed as an actual parameter for the instantiation of a new editor. Appendix C. Package Interdependencies and Recompilation Order. In this section we attempt to specify and to describe graphically the interdependencies between the various GMHF packages. Each package has potentially a specification part and a body. The dependencies are specified for each. Since the dependencies are being provided to ease recompilation, dependencies upon such packages as TEXT_IO and DIRECT_IO are not listed. file name package name dependencies ------------- --------------------------- --------------------------- TERMDEF.SP terminal_definition none TERMDEF.TXT terminal_definition none MMIP.SP man_machine_interface none MMIP.TXT man_machine_interface host_lcd_if (VMS) terminal_definition TYPELIST.SP type_list none CLASS.SP classification_definition none CLASS.TXT classification_definition terminal_definition man_machine_interface LNKLST.SP linked_list_procedures classification_definition LNKLST.TXT linked_list_procedures man_machine_interface FAP.SP file_access type_list linked_list_procedures FAP.TXT file_access terminal_definition man_machine_interface classification_definition PP.SP print_procedures type_list linked_list_procedures file_access PP.TXT print_procedures man_machine_interface classification_definition EDITTYPES.SP editor_types terminal_definition linked_list_procedures EDITTYPES.TXT editor_types none GENFILE.TXT file_generic man_machine_interface linked_list_procedures Note : filed_generic is the editor_types generic definition -- in body -- terminal_definition classification_definition file_access GENMENU.SP generic_menu_routines terminal_definition file_access linked_list_procedures GENMENU.TXT generic_menu_routines man_machine_interface CALLEDIT.SP call_editor file_access linked_list_procedures CALLEDIT.TXT call_editor type_list * each of the packages * which contain * instances of an * editor SDP.SP system_driver generic_menu_routines SDP.TXT system_driver terminal_definition man_machine_interface type_list linked_list_procedures file_access print_procedures classification_definition call_editor GMHF.TXT gmhf_driver terminal_definition man_machine_interface general_menu_routines system_driver As can be seen from the list, and the figure below, when a new editor is instantiated, type_list must be edited and it, file_access, and print_package recompiled. Then a 'with' clause for the package containing the new instance must be added to the body of call_editor, and the bodies of call_editor and system_driver recompiled. Below, we describe the Rainform and Unitrep implementations. First, we list some utility packages which can be of much use in implementing a new message type. ------------------------------------------------------------------------ ------------------------------------------------------------------------ these are utilities - they can be used to help generate a 'get_field' and to build the several files needed to instantiate an editor --------------------------------------------------------------------- MINIGFU.TXT generic_get_field_utilities terminal_definition man_machine_interface -also message type dependent STATICGFU.SP static_get_field_utilities man_machine_interface STATICGFU.TXT static_get_field_utilities none BUILDFILE.SP line definition file none creation utility BUILDFILE.TXT line definition file line_field_lists creation utility (linefield.sp) BUILDPMT.SP prompt file none creation utility BUILDPMT.TXT prompt file none creation utility BUILDLUT.SP look-up table file none creation utility BUILDLUT.TXT look-up table file line_field_lists creation utility (linefield.sp) ------------------------------------------------------------------------ ------------------------------------------------------------------------ these are the Rainform implementation packages ---------------------------------------------- LNSANDFDS.SP mini_lines_and_fields none SUBGRF1.TXT sub_pkg_1 terminal_definition man_machine_interface mini_lines_and_fields generic_get_field_utilities SUBGRF2.TXT sub_pkg_2 terminal_definition man_machine_interface mini_lines_and_fields generic_get_field_utilities SUBGRF3.TXT sub_pkg_3 terminal_definition man_machine_interface mini_lines_and_fields static_get_field_utilities generic_get_field_utilities SUBGRF4.TXT sub_pkg_4 terminal_definition man_machine_interface mini_lines_and_fields static_get_field_utilities generic_get_field_utilities SUBGRF5.TXT sub_pkg_5 terminal_definition man_machine_interface mini_lines_and_fields generic_get_field_utilities FGPARAMS.SP formal_generic_parameters man_machine_interface linked_list_procedures mini_lines_and_fields FGPARAMS.TXT formal_generic_parameters terminal_definition sub_pkg_1 sub_pkg_2 sub_pkg_3 sub_pkg_4 sub_pkg_5 generic_get_field_utilities static_get_field_utilities FGP2.SP more_formal_generic_parameters editor_types linked_list_procedures FGP2.TXT more_formal_generic_parameters terminal_definition man_machine_interface RFEDITOR.TXT rf_editor classification_definition linked_list_procedures file_generic mini_lines_and_fields formal_generic_parameters more_formal_generic_parameters Rainform Data Files ------------------- RAINFORM.SCE RAINFORM.DES RNPROMPT.SCE RNPROMPT.DES RNPMTLUT.SCE RNPMTLUT.DES ------------------------------------------------------------------------ these are the Unitrep implementation packages ---------------------------------------------- URLNSFLDS.SP Unitrep_lines_and_fields none URFLDTYPS.SP Unitrep_field_types none URPROCS.SP UR_procedures Unitrep_lines_and_fields URPROCS.TXT UR_procedures Unitrep_field_types UNITREP.SP Unitrep_interface man_machine_interface linked_list_procedures Unitrep_lines_and_fields UNITREP.TXT Unitrep_interface terminal_definition static_get_field_utilities UR_procedures Unitrep_field_types UREDITOR.TXT UR_editor Unitrep_lines_and_fields Unitrep_interface file_generic Unitrep Data Files ------------------- UNITREP1.SCE UNITREP2.SCE UNITREP.DES URPROMPT.SCE URPROMPT.DES URPMTLUT.SCE URPMTLUT.DES ------------------------------------------------------------------------ these are external user interface packages ------------------------------------------ EXTRNUSR.SP access_for_external_users linked_list_procedures EXTRNUSR.TXT access_for_external_users type_list classification_definition file_access ________________________________________________________________________ In the figure below, if a package is linked to another by a with clause, a line is drawn from the dependent package to the independent package. If the with clause appears in the specification part of the dependent package, the line appears on the left side of the graph (from the 'spec' side). If the with clause is attached to the body of the dependent package, the line is drawn from the right side of the graph ( the 'body' side). The graph is drawn in an increasing order of dependencies. package name spec body ------------ ---- ---- --------------- | | | terminal_definition |-------| | |<-----------------| | | | | | | | | | | | --------------- | | | | | | | | | | | | | | | | | | | | | --------------- | | | | | | | | | |-/ | | | | | man_machine_ |-^------>| | | | | | | | interface | | | | |<------------| | | | | --------------- | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | -------- |_|_|_|_| | | | | | | | /| | | | |\| | | typelist | | | |<-------x | | | | | x | | (loop | | |---> | | | | | | | | | | over | | | | -------- | | | | | | | | 5) | | | | | | | | | | | | | | | | | | | | | | | | | | | | --------------- | | | | | | | | | | | | | | |--/ | | | | | | | classification_ | | | | | | | | | | | | | | definition | | | | ->| | |<----^-|-|-^-|--^-| (loop | | | | | --------------- | | | | | | | over | | | | | | | | | | | | 1- 3 | | | | | | | | | | | | times) | | | | | --------------- | | | | | | | | | | | |<| | |----/ |_|_| | | | linked_list_ | | | | | | | /| | |\| | | procedures |-^-|-|-->| | |<----x | | | x--| | (loop | | ||| --------------- | | | | | | over | | ||| | | | | | | 3) | | ||| | | | | | | | | ||| --------------- | | | | | | | | || \--| | |------/ | | | | | file_access_ | | || | | | | | | | | package | |-||--->| | |<--------^-^-|--^-| (loop | | || --------------- | | | | | over | | || | | | | | 1 - 3 | | || | | | | | times) | | || --------------- | | | | | | | \^----| | |--------/ | | | | print_package | | | | | | | | | | | | | | | |<----------^-| | | (loop | | | --------------- | | | | over | | | | | | | 1) | | | | | | | | | | --------------- | | | | | \--^----| | |-----------/ | | | generic_menu_ | | | | | | | | routines | | ->| | | | | | | | | --------------- | | | | | | | | | | | | | | | | | | | | | | | | --------------- | | | | | | | | |-------------^-/ | editor_types |----^--^>| | | | | | | | | | | | | | | | --------------- | | | | | | | | | | | | | | | --------------- | | | | | | | | | | filed_generic \----^--^-| | |-------------^---/ | | | | | | | | --------------- | to | | | typelist | | --------------- | all editors | | | | | | / call_editor \--^-| | |-------------^-------/ | | | |<------------| | --------------- | | | | --------------- | \-| | |-------------/ system_driver_ | | | package | | | --------------- ^ | procedure GMHF_driver ----------/ Appendix D. An Alternate Version of the Generic Definition. At present, there are two versions of the generic definition. In the 'standard' version, the message type being implemented has its line structure defined in a file. It reads records of that file on a direct access basis depending upon which line is being edited. The structure of the current line is kept in a record of type LINE_DEFINITION which is defined in the package EDITOR-TYPES. The original design called for the entire line structure definition to be held in an array of elements of type LINE_DEFINITION. In fact, one object of such an array would be declared and initialized as a constant. That constant would then be passed to the generic definition as a parameter, in place of the line structure file name. This structure is implemented as follows: 1) define a package within which an element of type LINE_DEFINITION_ARRAY is declared and initialized as shown: LINE : LINE_DEFINITION_ARRAY:=( -- --ACFT (5, "ACFT/ / / / NM/ ", ((2, 6, 6, false), (2, 13, 5, false), (6, 19, 6, false), (5, 26, 3, false), (2, 32, 38, false), others => (27,1,1,false)) ), -- --ADD (0, "ADD ", (others => (27,1,1,false))), -- --AFTER (0, "AFTER ", (others => (27,1,1,false))), -- --AMBTN (17, "AMBTN/ / / / / / / / / / / / / / / / / ", ((21, 7, 3, true), (9, 11, 4, true), (5, 16, 3, true), (5, 20, 3, true), (5, 24, 3, true), (9, 28, 4, false), (5, 33, 2, false), (5, 36, 2, false), (5, 39, 2, false), (9, 42, 4, false), (5, 47, 2, false), (5, 50, 2, false), (5, 53, 2, false), (9, 56, 4, false), (5, 61, 2, false), (5, 64, 2, false), (5, 67, 2, false), others => (27,1,1,false))), -- --AREA_LL (8, "AREA/ / / / / / / / ", ((11, 6, 6, true), (12, 13, 7, true), (11, 21, 6, true), (12, 28, 7, true), (11, 36, 6, true), (12, 43, 7, true), (11, 51, 6, false), (12, 58, 7, false),others => (27,1,1,false))), -- --AREA_C (3, "AREA/ / / NM ", ((11, 6, 6, true), (12, 13, 7, true), ( 5, 21, 3, true),others => (27,1,1,false))), -- --AREA_A (1, "AREA/A- ", (( 2, 8, 12, true),others => (27,1,1,false))), -- --ASSOC (1, "ASSOC/ ", (( 2, 7, 63, false),others => (27,1,1,false))), -- -- WEX (11, "WEX/ Z / / / / NM/ T/ K/ / / F/ ", (( 3, 5, 8, true), (20, 14, 3, true), (11, 18, 6, true), (12, 25, 7, true), ( 5, 33, 4, true), ( 7, 40, 3, true), ( 5, 45, 3, true), (26, 50, 4, true), ( 7, 55, 1, true), (17, 57, 4, true), ( 7, 63, 1, false),others => (27,1,1,false))), --FREE (1, " ", (( 2, 1, 69, false),others => (27,1,1,false))), others =>(0, " ", (others => (27,1,1,false))) ); 2) 'with' the package defined above to the package in which COMPILED_GENERIC is instantiated, and pass the name of the element of type LINE_DEFINITION_ARRAY (in the example - LINE) as an actual parameter. 3) note that in EDITOR_TYPES, the definition of LINE_ DEFINITION_ARRAY is dependent on its index. This might require modification. 4) use the editor created just as you would an editor created using FILED_GENERIC in the 'standard' fashion.