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

Wrap

Text File | 1988-05-03 | 34.1 KB | 740 lines

,print 106 ,print 106 type 86 86 86 86 ,end 73501-85U/P7046 15 April 1985 Generic Message Handling Facility (GMHF) Functional Description l. Introduction This GMHF Functional Description (FD) describes the capabilities to be presented in the GMHF upon delivery. These capabilities are described in detail from a functional point of view. This is the final version of this FD, and is to be used as the basis for the critical design review (CDR). In addition, this FD will serve as an important piece of user documentation during the life cycle of the GMHF. In the sections which follow, we give an overview of the proposed GMHF structure. That structure is based upon five Ada packages and a generic definition. Each of these entities is discussed in a separate section. The GMHF interface is also discussed in a seperate section. The use of generics is covered in the section describing the Generic Message Definition. The preliminary version of this FD was reviewed by several interested parties. The comments received have been incorporated into this final version. 2. GMHF Overview The GMHF consists of five major Ada packages and an Ada generic declaration. The packages envisioned are: a. System Driver Package (SDP). b. Man Machine Interface Package (MMIP). c. Print Package (PP). d. File Access Package (FAP). e. Terminal Definition Package (TDP). In addition to the five major packages, there are several minor packages holding types, objects, and procedures which due to the current state of the compiler used could not be integrated into the five major packages. These packages are the Editor Types, Linked List Procedures, Classification Definition, and Typelist packages. They are discussed in detail in the User's Manual. The SDP is the stand-alone driver program. It calls the print package, the file access package, and the edit function package. In addition, it uses the man-machine interface package as a utility to handle its I/O. As described below, the SDP is the means whereby the user can most directly utilize the facilities in GMHF. The MMIP is a utility package which handles character inputs by the user. It encapsulates all GMHF special user io features, designed to provide a user friendly, command oriented interface while taling maximum advantage of existing Ada packages. The PP provides the GMHF access to the various hard copy output utilities. It is called by the SDP, and obtains any required printer definition data from the MMIP. The FAP contains the routines required to access the internal GMHF data base. In fact, that data base is part and parcel of FAP. It is called by SDP, or can be directly accessed by a software implementor. This direct access, external to GMHF, is one means of allowing implementors use of the text editor without requiring them to go through the SDP. The TDP holds all crt terminal dependencies. An implementor who wished to rehost this system to a non-VT100 emulator would only have to modify this package. The Generic Message Definition (GMD) provides the user the means to define a new message type in terms of a specific set of parameters. Each instance of this definition generates the data definitions and procedures required to edit messages of the type specified. The result of an instantiation is referred to as an editor. There are two user interface models implemented in GMHF. A basic, general purpose model is implemented in those screens which support user input outside of an editor. Within an editor, the tripartate screen definition defined in Veda's proposal is implemented. The basic user interface model is described in the MMIP discussion. The tripartate screen definition is reviewed and amplified in the editor section. 3. System Driver Package. If GMHF is to be used as a stand-alone system a system driver is needed. SDP provides all functions necessary to utilize GMHF is such cases. SDP's primary task is to activate functions of the various other packages of GMHF based on user inputs received through the man-machine interface (MMI) menus. Its goal is to provide an integrated, cohesive user interface to the GMHF in those cases where it is to be used as a whole. There are six MMI menus comprising SDP. They are: 1. GMHF Main Menu 2. Message/Edit Directory Menu 3. Message/Print Directory Menu 4. Process Edited Message Menu 5. Message/Delete Directory Menu 6. Review Message for Deletion Menu. The call tree of the menus is given below. Some return paths are not shown, but are described in the text which follows. In the call tree, it should be noted that the Message/Edit Directory Menu (menu 2) allows the user to call an editor. Upon exiting an editor, the user returns to the menu 2 program which automatically calls the Process Edited Message Menu. 1 ! ------------------------- ! ! ! 2 3 5 ! ! ! ------- PP 6 ! ! editor 4 SDP contains a menu handling procedure for each of the six menus. The procedures analyze the user inputs(returned from MMIP), perform any necessary data validation and then activate the functions as requested by the user.The menu handling procedures are based upon two files for each menu. The first is a menu display data file for each menu. This file holds the menu display characters in ASCII form. The second file contains that data specific to the menu in question required for MMIP to control the user's interaction with that menu. Below, a description of each menu of SDP is provided. Included for each is the menu title, the menu purpose and the options provided: (1) Title: GMHF Main Menu Purpose: This is the main menu for the system driver. It is the first menu to appear in the system and it may be recalled from any of the other system driver menus. It's purpose is to allow the user to access the various components of the GMHF. Options: (a) Enter Message Editing Facility - sends control to Message Edit/Directory Menu (b) Enter Message Print Facility - sends control to Message Print/ Directory Menu (c) Enter Message Delete Facility - sends control to Message Delete/ Directory Menu (d) EXIT GMHF - returns control to operating system if in stand-alone mode - returns control to calling procedure if embedded in external system. (2) Title: Message Edit/Directory Menu Purpose: This menu displays the current directory of messages in the internal data base and provides options to edit a specific message. The directory is listed by the message types followed by the number of messages for each type. Options: (a) Edit Message #___ of Type _______ - sends control to editor with existing message of a selected type and number. Upon return from the editor, control is automatically sent to the Process Edited Message Menu. (b) Edit New Message of Type _________ - sends control to editor with new message of a selected type.When editing a new message,the prototype message of that type is automatically provided as a template for the new message. Upon return from the editor, control is automatically sent to the Process Edited Message Menu. (c) Edit Prototype Message of Type ______ - sends control to editor for editing the prototype message of a selected type. Upon return from the editor, control is automatically sent to the Process Edited Message Menu. (d) Print Message Directory - activates Print-Directory procedure from Print Package. (e) Return to GMHF Main Menu - sends control back to GMHF Main Menu. (3) Title: Message Print/Directory Menu Purpose: This Menu displays the current directory of messages in the internal data base and provides options to print various items. Options: (a) Print Message # _____ of Type ________ - activates Print_Message procedure from Print Package. (b) Print Message # ___ through Message # __ of type____________. - activates Print_Group_of_Messages pro- cedure from Print Package. (c) Print Prototype Message of Type _____. - activates Print_Message procedure from Print Package. (d) Print Message Directory - activates Print-Directory procedure from Print Package. (e) Return to GMHF Main Menu - sends control back to GMHF Main Menu. (4) Title: Process Edited Message Menu Purpose: This menu allows the user to specify exactly what should be done with a message following an editing session. Options: (a) Resave Edited Message - replaces the original version of the message with the edited version. This option is not available if the user had selected the edit new message option. (b) Save Edited Message as New - allows user to store message as a new message, consequently not affecting the contents of the existing messages in any way. The new message will be assigned a message number one greater then the number currently stored forthat particular type. (c) Re-enter Message Editor - sends control back to the message editor with the same message still in the editor's workspace. (d) Print Edited Message - activates Print_Message procedure from the Print Package. (e) Return to Message Edit/Directory Menu - sends control back to the Message Edit/Directory Menu. (f) Return to GMHF Main Menu - sends control back to the GMHF Main Menu. (5) Title: Message Delete/Directory Menu Purpose: This menu displays the current directory of messages in the internal data base and provides the user the option to select one for deletion. Options: (a) Review Message # ____ of Type _____ for Deletion - sends control to Message Review for Deletion menu with the specified message in the workspace. (b) Return to GMHF Main Menu - sends control back to GMHF Main Menu. (6) Title: Message Review for Deletion Purpose: This menu displays the message text of the specified message and gives the user the ability to remove it from the data base. Options: (a) Delete this Message from Data Base - activates Delete_Message procedure from FAP. (b) Return to Message Deletion/Directory Menu - sends control back to the Message_Deletion Directory Menu. (c) Return to GMHF Main Menu - sends control back to GMHF Main Menu. NOTE: There is one additional menu which is not discussed in this section, rather it is discussed in the Edit Function Package (EFP). The menu is accessed only from the EFP and it is the one from which all editing functions are performed. 4. Man Machine Interface and Terminal Definition Packages. The MMIP consists of all of the procedures and data definitions which are necessary to interface the user to the system. The procedures and data definitions of the MMIP are used to support operation of almost all other packages. Those procedures and data definitions which rely on particular characteristics of the user terminal are contained in the Terminal Definition Package (TDP). As the GMHF is now configured, the TDP will be set up for all VT-100 series terminals or emulators. The implementor though, may edit the TDP and redefine the system to work on some other terminal. The minimal terminal characteristics assumed are: screen dimensions of at least 24 x 80 at least one of: reverse video, flash, bold face, or underscore(to 'highlight' the current line being edited) ASCII standard keyset some means of absolute cursor addressing (could be as primitive as home, followed by a sequence of LFs and RSs) Function keys preferred but not required (can be replaced by CTL or ESC sequences). An editor requires MMIP support to determine what function keys are to be used for editing, and what codes are used for absolute cursor addressing, erase screen, erase line, and reverse video. A detailed description of the editing functions and other elements relating to message editing is given in Section 7. The SDP relies heavily on the MMIP for support and control of its menus. The MMI menus to be used by the SDP are based upon defined fields. A field is a designated area on a menu where the cursor may reside at any given time. A menu is made up of one or more such fields and the cursor will not appear anywhere on the menu except in the defined fields. The MMI menus for this system utilize three different types of defined fields; Command fields, Data fields and List fields. Command fields are designated by a one character reverse video block. The Command field is used to tell the system that the user has specified that some function is to be performed. The software (in MMIP) will determine whether all prerequisites for the function selected have been satisfied. If so, control is returned to the calling procedure and the function is executed; if not the user is prompted. Data fields are designated by a one or more character underscore segment. Data fields are provided to allow the user to enter any data which may be required by a function to be commanded. Data fields are explicitly typed and range values may be defined for them. For example, we may have a data field for entering a message number, the field would be of length four, it would be of the integer data type and the range of values which may be entered into it would be from one to the number of messages which exist for the particular message type in question. List fields are designated by a right arrow symbol followed by a one or more character underscore segment. Associated with each List field is a finite list of possible values which may be entered into the field itself. The list is enclosed in a box and will appear on the same menu as the list field. A selection is automatically entered in the List field and is reverse video highlighted within the list. The user may scroll through the list at which time the value in the field is automatically updated. List fields eliminate the possibility of spelling errors and the possibility of choosing values which are invalid. List fields, like Data fields are used to support a function which might be commanded. To support the menus, five special function keys are designated to facilitate their use. The five function keys are termed, COMMAND key, TAB key, BACK_TAB key, UP_ARROW and DOWN_ARROW. The COMMAND key is used on a Command field only and it signals to the system to attempt to perform the function designated by the Command field. If a function being commanded requires support data either from a Data field, a List field, or both, the user must fill these fields with values prior to commanding the function. An attempt to do otherwise would cause the user to be prompted "support data required for this function". The TAB key and BACK_TAB key are both used to move from one field to another. Striking the TAB key will cause the cursor to move from the current active field to another in a direction which is mostly suited for that particular menu. The BACK_TAB key causes movement exactly the reverse of the TAB key. The UP_ARROW and DOWN_ARROW key are used to scroll up and down through a list of a particular list field. The current active item within a list is reverse video highlighted and striking the UP_ARROW key causes the active item to move up one selection in the list. Striking the DOWN_ARROW key causes the active item to move down one selection in the list. If a top of list or bottom of list is encountered, the list is cyclic so the user may continue to scroll through. 5. Print Package. The PP provides GMHF with three basic print functions: Print Message Directory, Print Message Text, and Print Group of Messages. The Print Message Directory function provides a hardcopy cross reference of message type versus number of messages for that type, for all defined message types of the GMHF. The Print Message Text function provides a hardcopy of the message content for a specified message number of a specified message type. The Print Group of Messages function provides the same capability but for a range of messages of a specified message type. All PP procedures are accessed only by the SDP. Users who wish to acquire hardcopy outputs of messages outside of the internal data base of the GMHF must generate their own procedures to do so. The PP uses the standard SYS$PRINT (VMS) attributes. 6. File Access Package. FAP is made up of both private procedures and public procedures. The private procedures are accessible only by the SDP. The private procedures include the following: (a) Get_Directory - this procedure will read the directory file to obtain the number of messages for each type currently in the internal data base. This procedure is called any time a directory is being displayed through the SDP. (b) Get_Message_Out - this procedure will retrieve a specified message from the internal data base and load it into the edit workspace. (c) Put_New_Message_In - this procedure will store the current message in the edit workspace as a new message of a specified type. (d) Put_Old_Message_Back_In - this procedure will resave the current message in the edit workspace in its original place in the data base or in place of some other message of the same type, currently in the data base. (e) Delete_Message_From_Data base - This procedure will remove an existing message from the data base. The procedures of the FAP which are public are to facilitate use of the EFP's capabilities on messages external to the GMHF's internal data base. The public procedures are as follows: (a) Load-External_Message_Into_Workspace - this procedure will load an external message into the workspace for editing. (b) Retrieve_Message_From_Workspace - this procedure retrieves a message from the edit workspace and places it into a data element which is accessible by an external routine. (c) Load_External_Message_Into_Database - this procedure will load an external message into the internal database. The message will be added as a new message of a specified type provided the type is defined in the GMHF and the message meets the criteria for the type. (d) Retrieve_Message_From_Database - this procedure retrieves a message from the internal database and places it into a data element which is accessable by external routines. 7. The Editor. An instance of an editor is the core of the GMHF. It is here that the user can actually create and edit messages. There is an editor created as the result of instantiating the GMD described below. Thus for each message type defined, an EFP exists. The functions detailed below are provided in the context of a tripartate screen format. The screen layout has been used by Veda in three applications. In each case, users and reviewers have found it easy to use and understand. The user screen is partitioned into three separate areas. The top portion of the screen is called the message area (MA) and is used to hold the text lines of the message being edited. If the message being edited is too large to fit in the MA, it is automatically scrolled as the user moves from line to line. At all times, one line of the message is designated as the current line. It is displayed in reverse video (backlit) in the MA. The center portion of the screen is called the work area (WA) and is used to display the line being edited and the prompts displayed to the user to support line editing. The lower portion of the screen is called the amplification area (AA) and is used to provide user prompt amplification and to support discrete field selection. The three screen areas are not of fixed size. They can be defined as part of the generic definition of a message editor. Generally speaking, an implementor would want the MA should be as large as possible, using the minimum space possible for the other two areas. In the current RAINFORM implementation, the MA includes lines 3 through 14. The WA includes lines l6 through l8, while the AA contains lines 20 through 24. Lines l and 2 are used for screen header data and system prompts, and are not considered a functional part of the editor, per se. At any given time, the user may be in either scroll mode or edit mode. When in scroll mode, only the MA is filled. The user can scroll up and down through the message being edited, in order to review the contents and select which line, if any, is to be edited. When the user enters edit mode, the current line is displayed in the WA, and the field prompt for the first field in the WA (and the AA if required). The user can then commence editing the line. Below we discuss scroll mode functions and edit mode functions. In cases where there is an overlap, the function is discussed in both places. It should be noted that these two modes are mutually exclusive. Whenever one is entered, the other is exited. 7.l Scroll Mode. The functions available to the user when in scroll mode are: (a) Previous line. (b) Next line. (c) Insert line. (d) Delete line. (e) Edit line. (f) Classify message. (g) End edit. When previous line is selected, the line numbered one less than the current line becomes the new current line. The old current line is redisplayed unbacklit, and the new current line is backlit. If the old current line was displayed at the top of the MA, a scroll down is performed and the new line displayed at the top of the MA. If this function is selected while the first line of the message is the current line, the user is prompted. The next line function is implemented analogously to the previous line function. Differences are that if the user is at the last line of message when next line is selected, the user be prompted if the message is already at maximum size. If it is not, the user will be asked to specify the type of line which is to be added, and a blank line of that type will be displayed in the WA for editing. At that point, the scroll mode is exited and the edit mode is entered. The insert line function allows the user to insert a line above the current line. When this option is chosen (and the message is not already at maximum length) an empty line is written in the MA, and the user is asked to specify the desired line type. This specification is done by providing the user with a display of the line types available for this message type. The display appears in the AA. The user selects the desired line type and a blank line of that type is displayed in the MA for editing. The edit mode is entered. The delete line function deletes the current line from the message. If the message contained only a single line the user is prompted (a message may be deleted elsewhere,using the delete message function, but no message may be reduced to zero lines). The message text in the MA is collapsed to reflect the line deletion. The user remains in scroll mode. When the user selects the edit line function, the current line is displayed in the WA, the first field is displayed, and the user is placed in edit mode. Each message has a classification attached to it. The classification of the current message is displayed in the upper left and lower right hand corners of the screen. The user may specify the message's classification. Upon user specification of classification, the message classification is updated. The end edit function is the exit point from the EFP. Upon its selection, the user is returned to the SDP. 7.2 Edit Mode. The functions available to the user in the edit mode are: (a) Previous line. (b) Next line. (c) Classify message. (d) End edit. (e) Previous field. (f) Next field. (g) Erase field. When in the edit mode, the user is provided a copy of the line under edit in the WA. As the user edits the line, he is prompted as to required contents as appropriate. In some cases, a field may be discrete in nature. That is, there may be a small number of possible valid entries. In such cases, the implementor may specify that such a field type use discrete entry. When editing such a field, the user is offered the list of valid entries from which to choose. He types one of the choices and it is automatically validated. This eliminates unnoticed typing errors. In other cases, fields may not be appropriate for such discrete entry, but may be defined in terms of the type of data which may be entered. When such a field specification is made, the implementor may specify valid types of data, and when appropriate, a range. As such a field is being edited, the data entry is validated automatically. Finally, lines and fields may have characters which are "protected". That is, characters which are required and may not be changed. The definition of each line and field provides for the specification of such protected characters. During the edit process, the user is not allowed to modify these characters. In one case, protected data are automatically entered. This is the case of a checksum character. If the implementor defines a field which has a checksum character, that character is automatically entered upon leaving the field. The remainder of this section discusses the functions available to the user while in the edit mode. The first four functions listed are also available in the scroll mode. They operate in essentially the same fashion in the edit mode. The only difference being that for previous line, next line, and end edit, the line currently being edited is formatted, saved, and displayed before the rest of the function actions are taken. The previous field function allows the user to leave the current field and places the cursor at the first character of the previous field, and displays the prompt for that field. If the user is in the first field and activates the previous field function, the editor cycles around to the last field in the line. The next field function is essentially the same as the previous field function except that the direction is reversed. If the user is in the last field of the line and selects next field, the editor places the cursor in the first field of the line. The erase field function allows the user to "blank out" the contents of a field, leaving it in its prototype (empty) state. 8. Generic Message Definition. The GMD defines a package entitled generic_message_editor. It contains the various type declarations which define the range of message structures which are implementable within the GMHF. The body of the generic_message_editor package contains all the functions needed to edit messages as defined in the generic_message_definition subpackage. The generic_message_editor accepts as formal parameters the implementor's specification of various message-type dependent parameters and procedures. It allows the implementor to create an instance of the message editor which is 'custom tailored' to a particular message type. The structure of the various entities comprising the GMD and the packages required to instantiate an editor are covered in great detail in the Users Manual (UM). It is worth noting that the UM contains explicit implementation instructions. In fact, it is as much of an implementors manual as it is a UM. 9. User Access. There are two methods of which an implementor may access the GMHF. The first is to access GMHF as a stand-alone system. When GMHF is used as a stand-alone system, all functions provided by the SDP are available, and all messages within the internal database may be handled. External messages may not be handled in the stand-alone mode unless moved into the internal database prior to entering the stand-alone mode. Procedures for doing this are discussed in the latter portion of this section. Stand alone access may be accomplished by invoking SDP from the host operating system, or by calling it from an implementor developed procedure. For the second method of access, the implementor is provided a library of public routines. This library contains any editors which exist and the Access_For_External_Users sub-package of the FAP. This particular sub-package contains four distinct procedures. One procedure, Load_External_Message_Into_Workspace, allows the implementor to load any message within the defined types of GMHF, from outside the system into the workspace for editing purposes. The implementor must first place the necessary message information into an External_Message data element which the procedure may then map into the edit workspace. Once an external message has been mapped into the workspace, the implementor may then activate an editor which provides the editing functions to the user. The user may obtain an edited message via the second procedure of the ACCESS_FOR_EXTERNAL_USERS sub-package, RETRIEVE_MESSAGE_FROM_WORKSPACE. This procedure re-maps the contents of the edit workspace back onto an EXTERNAL_MESSAGE data element with which the implementor may do as he pleases. The two procedures discussed do not provide access to the GMHF internal data base. The remaining two procedures do. LOAD_EXTERNAL_MESSAGE_INTO_DATABASE and RETRIEVE_MESSAGE_FROM_- DATABASE move external messages between the implementor's external data base and the GMHF internal data base. This is accomplished through an EXTERNAL_MESSAGE data element.