Programmer's ROM - The Computer Language Library

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

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

Wrap

Text File | 1988-05-03 | 105.0 KB | 2,691 lines

--:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: --man.txt --:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Drawing A14589 April 17, 1985 Ada Menu Manager Users Guide Contract N66001-85-C-0035 For the Naval Ocean System Center San Diego, California Ford Aerospace and Communication Corp. Drawing A14589 April 17, 1985 Approval for Release ----------------------------------------------- K. Lamarche, Engineer Ada Menu Handler Project (NOSC) ----------------------------------------------- J. Roberts, Supervisor Range Programs S/W Development ----------------------------------------------- D. McKinney, Manager Software Engineering Ford Aerospace and Communication Corp. Drawing A14589 April 17, 1985 1. _O_v_e_r_v_i_e_w The purpose of the Menu Manager is to provide a tool to make and use menus as designed by a user. This enables users of a software system to select desired system operations from a display menu by typing a single selection key. The Menu Manager is written in Ada. Procedures must be supplied by the user to interface between the Ada environment and the command line inter- preter since each Ada environment and operating system may have a different method of providing this capability. The Menu Manager consists of two main programs: a Menu Com- piler and a Menu Handler. Menus are created in the Menu Defini- tion Language using a standard editor. The resulting Menu Defini- tion file is then compiled into a non-readable Menu Definition Table. The tables are input to the Menu Handler to produce termi- nal displays, and to respond to user selections. Ford Aerospace and 1 Communication Corp. Drawing A14589 April 17, 1985 Table 1 Diagram of the Menu Manager operating system | | | | | Menu Definition File ------------------ | written in Menu | | Definition | | Language | ------------------ | | | | | ------------------ | Menu Compiler | ------------------ | | | | | ------------------ | Non-readable | | Menu Definition | | Table | ------------------ | | | | | ------------------ | Menu Handler | ------------------ | | | | | ------------------ | Terminal Display | | Response to | | User Selection | ------------------ The design objectives can be divided into user related objectives and software product objectives. 1.1 _U_s_e_r__R_e_l_a_t_e_d__O_b_j_e_c_t_i_v_e_s A. Control Option Flexibility The options provided include selection of independent pro- grams to execute serially with the Menu Handler, selection of tasks to execute concurrently with the Menu Handler, and selection of any other previously defined menu. The confi- guration file (Mencon) included with this package provides the option of changing the default values assigned to Ford Aerospace and 2 Communication Corp. Drawing A14589 April 17, 1985 maximum file name length, screen length, the length of lines within a Menu Definition file, the menu quit character, and the screen width. By editing the configuration file, the user can tailor the Menu Manager to fit the needs of a par- ticular operating system. B. Menu Networks One menu may be accessed by another menu by being included as a selection in the menu. The menus may be organized into a standard tree type structure, or into any other type of network. C. Menu Modification New menus can be created or existing menus modified at any time. The Menu Definition Language is simple and easily learned. The Menu Compiler checks for syntax and logic errors in the Menu Definition file. The menus are easy to change as resources are added to or deleted from a system. D. Ada Procedure Calls The menus can also be used to select internal Ada procedures when the Menu Manager is compiled as part of a larger Ada program. The calls to the internal procedure must be entered into the package body of the unit named Process_Initiator. The Process_Initiator body is contained in the files Proctord.ada and Proctore. ada. To use this option, the Ada procedures must be linked to the main Menu Handler program Menushow. The Menu Handler code must be re-compiled for every such change. 1.2 _S_o_f_t_w_a_r_e__P_r_o_d_u_c_t__O_b_j_e_c_t_i_v_e_s A. Portability The Ada code in the Menu Manager has been designed to be as reusable as possible. The initial version is built for use under the AOS (Advanced Operating System) operating system on the Data General 4,000 and 10,000 computers, but system- dependent and terminal interfaces are as general as possible to facilitate porting to other operating systems. B. Ada Style The Ada code in the Menu Manager was designed to take advan- tage of the special structures available in the Ada language. The main functional procedure and data structure groupings are contained in separate packages, some of which are used by both the Menu Compiler and Menu Handler. The data typing facilities of Ada are used to create specialized data structures wherever appropriate. A dynamic string function is also utilized in these programs. Ford Aerospace and 3 Communication Corp. Drawing A14589 April 17, 1985 1.3 _U_s_i_n_g__t_h_e__M_e_n_u__C_o_m_p_i_l_e_r The Menu Compiler is used to process the Menu Definition file written by the user in the Menu Definition Language. If no disabling or fatal errors occur during compilation, a Menu Defin- ition Table is created. As the compiler analyzes the Menu Defini- tion file, messages are displayed on the users terminal. The mes- sages alert the user when a syntax error is found, and when the compiler has completed. The messages are sent to the standard system output, generally the terminal where the Menu Compiler has executed. The messages are not currently sent to a file or hard copy printer, so the user will have to stop and start the display scrolling if many messages are displayed. A message displayed for a syntax error includes the following: The code number for the error. The line number in the Menu Definition file where the error was found. The severity of the syntax error. The explanation of the error. The possible errors that may be invoked are discussed in more detail in Section V, Ada Package Descriptions. In most cases, a syntax error will not terminate compilation or creation of a Menu Definition Table. The Menu Definition Table that has been compiled with errors may still be used as a menu. The resulting menu may not appear on the display as expected, and its reaction to user input may also not be as expected. A sample menu with such errors is provided in Appendix 2 as an example of what can happen to a menu compiled with errors. The final message delivered to the users terminal will indi- cate the total number of errors found in this compilation. It will also indicate the total severity of these errors, which is the highest severity of any error found. If the Menu Definition File was fully compiled and the Menu Definition Table was created successfully, the compiler will terminate with a message to that effect. 1.4 _U_s_i_n_g__t_h_e__M_e_n_u__H_a_n_d_l_e_r The Menu Handler uses the Menu Definition Table created by the compiler and produces a menu. The menu includes both the ter- minal display and the processing of user inputs. The display and processing produced by user input are almost totally defined in the Menu Definition File, and the values present in the confi- guration file Mencon. The Menu Definition File is described in Section III. The configuration file Mencon is described in Sec- tion II. The following describes the features that all menus have in common. Ford Aerospace and 4 Communication Corp. Drawing A14589 April 17, 1985 When a menu is run by the Menu Handler, it waits for a sin- gle character of user input. The character ! is reserved as an escape character and may not be used for user defined input. After typing a !, the user can enter a full line of text. The text line typed (minus the !) will be passed to the Process_Initiator unit. The Process_Initiator unit will attempt to pass the line to the command line interpreter of the operating system. If the capability of interfacing between the Ada environ- ment and the command line interpreter does not exist, this option will not be available. The last line of the menu display is always reserved for the ==>> prompt. This signals the user that the Menu Handler is wait- ing for input. The line above the prompt is called the Menu Information line. This line may display a message from the Menu Handler when the screen is refreshed. If erroneous key input is entered, the bad selection message from the Menu Definition file will be displayed. When a background task is passed to the com- mand line interpreter, the Menu Information line will display a message to that effect. When the Menu Definition file is created, the user should not use the last two lines as they are reserved for the prompt and the Menu Information line. The Menu display is refreshed on every user input. The current software uses simple I/O (input / output) instructions to implement this. The display consists of lines passed sequentially to the screen. If more sophisticated display techniques are desired the Ada program code will have to be altered. Messages are displayed to the user when the Menu Handler is being run. These messages alert the user that a file was not found, that a menu was not correctly configured for the current run of the Menu Handler, or that a process line was not correctly interpreted by the command line interpreter. The message is displayed and the Menu Handler waits until the user hits a key before returning to the menu display. A quit character is used to exit the Menu Handler program. The quit character is defined in the configuration file (Mencon). The character may be used as a selection key in the Menu Defini- tion file, but the quit character will have precedence. If that character is typed as a menu selection, the Menu Handler will terminate before any attempt is made to process the selection. Ford Aerospace and 5 Communication Corp. Drawing A14589 April 17, 1985 2. _D_e_s_c_r_i_p_t_i_o_n__o_f__t_h_e__C_o_n_f_i_g_u_r_a_t_i_o_n__F_i_l_e__(_M_e_n_c_o_n_) Mencon is the configuration file that contains the user defined items. The user defined items are the maximum file name length, the Menu Compiler input file name, the maximum number of characters per line in the Menu Compiler input file, the Menu Handler input file name, the screen width and the menu quit char- acter. This file can be edited by the user so so the values it contains will be compatable with a particular operating system. For example, many operating systems do not allow file names longer than eight characters. If a particular operating does allow file names longer than eight characters, the value of the maximum length allowed for a file name can be changed to reflect this fact. Any of the values given for the user defined items can be modified to cater to the needs of an operating system. The Menu Manager programs do not have to be re-compiled when the values in the Mencon file are changed. However, menus compiled with one configuration should be run with the same configuration. Otherwise an error will result when the Menu Handler trys to access the Menu Definition Table and the menu will not be pro- cessed. If nonsense values are entered, the Ada package Process_Configuration will substitute reasonable default values for those items. This insures that the Menu Manager programs will still perform. Table 2 illustrates the configuration file and the default values provided. ---------------------------------------------------------------- | Mencon - Menu Manager Configuration File | | Maximum length allowed for a file name in this operating system: | | 15 | | File where the Menu Compiler will always get its input: | | MENUFILE | | Maximum characters per line in the Menu Compiler input file: | | 100 | | File where the Menu Handler will always get its input: | | MENUTABL | | Screen width | | 80 | | Screen length | | 22 | | Character used to exit the Menu Handler | | @ | ----------------------------------------------------------------- Table 2 Ford Aerospace and 6 Communication Corp. Drawing A14589 April 17, 1985 3. _D_e_s_c_r_i_p_t_i_o_n__o_f__t_h_e__P_r_o_c_e_s_s___I_n_i_t_i_a_t_o_r__A_d_a__P_a_c_k_a_g_e A primary concern of installation of the Menu Manager is providing a method to access the command line interpreter from the Ada environment, and to access other Ada procedures that are not part of the Menu Manager software. It is not possible to deliver a procedure that accomplishes this since 1) this goes beyond the scope of the Ada language, and 2) the Menu Manager may be used on different operating systems with different command line interpreters. What has been delivered is an Ada package that contains a procedure with a basically null procedure body. The package unit name is Process_Initiator, and the procedure in this package is Command_Line_Processor. The code for the package body is in Appendix 5, Source Code. The procedure provides a link to the Menu Handler program. The Menu Handler program calls this pro- cedure and passes it the actual parameters shown. The installer of the Menu Manager must determine if an Ada procedure is avail- able to pass a character string to the command line interpreter. This procedure must be specified and called within the Command_Line_Processor procedure. The code provides further explanation on what object contains the character string, and other parameters that are passed to and from the Menu Handler. Without the capability to issue a line to the command line inter- preter, the Menu Handler cannot call software external to the Ada environment and will be limited to calling Ada procedures. The ability to call user defined Ada procedures will also require that the user provide some interface to the Menu Handler. The Menu Handler receives procedure names as character strings. However, the procedure call statements cannot be created at run time because the procedure may not have been linked to the Menu Handler. Another procedure within the Process_Initiator package is used as the interface for user defined Ada procedures. The procedure is named Ada_Procedure_Call. The body of the procedure will consist mainly of a multi-conditional statement, where a condition exists for each Ada procedure that may be called. Each condition will test if the character string passed to Ada_Procedure_Call matches an Ada procedure name. If this condi- tion is true the procedure will be called. Any procedure called by Ada_Procedure_Call must be linked in some way to the Process_Initiator package. There are three methods of doing this described in the code. The code also describes the other parameters passed to and from the Menu Handler and the Ada_Procedure_Call procedure. Any changes made to the Process_Initiator package body will require re-compilation of the body. The main procedure (Menushow) will at least have to be re-linked. In some Ada environments, the main procedure may have to be re-compiled and then re-linked. Ford Aerospace and 7 Communication Corp. Drawing A14589 April 17, 1985 4. _M_e_n_u__D_e_f_i_n_i_t_i_o_n__L_a_n_g_u_a_g_e__S_y_n_t_a_x 4.1 _I_n_t_r_o_d_u_c_t_i_o_n This section defines the syntax used in the Menu Definition Language. The files created using this language will be processed by the Menu Compiler to create table files, called Menu Definition Tables, containing information used at run time by the Menu Handler. When creating a menu, the menu designer must make some basic decisions: - What selection keys will be available to the menu user, - What action will occur when any of these selections is made, - What the menu display will look like, ie. what text will be shown to describe the selection choices to the menu user. The Menu Definition Language is used to set these charac- teristics of the menu. The menu designer uses a series of instructions with desired qualifiers, to produce a menu with the specific selection choices, action invoked, and display appear- ance desired. The description of the Menu Definition Language starts with a description of lexical units, which are the building blocks for the lines of the Menu Definition File. Part III contains a general description of the Menu Definition File and the instruction format. Part IV describes the details and syntax of the instructions used. 4.2 _D_e_f_i_n_i_t_i_o_n__o_f__B_a_s_i_c__L_e_x_i_c_a_l__U_n_i_t_s In describing the Menu Definition Language syntax, the fol- lowing lexical units will be referred to: 4.2.1 _R_e_s_e_r_v_e_d__I_d_e_n_t_i_f_i_e_r These are character strings with specific meaning to the Menu Compiler. The software keys only on the first charac- ter of Reserved_Identifiers, therefore the user has great free- dom to use desired words. For example, one Reserved_Identifier is the character string "SELECTION", for which the user can write any string that begins with the letter 'S' and contains no Word_Separators (described below). The following strings would be interpreted by the Table Generation Software as a "SELECTION" Ford Aerospace and 8 Communication Corp. Drawing A14589 April 17, 1985 Reserved_Identifier: "SELECTION" "Select" "S" "Slctn" BN notation Reserved_Identifier ::= Control_Identifier| Action_Identifier| Comment_Identifier 4.2.2 _C_o_n_t_r_o_l__I_d_e_n_t_i_f_i_e_r These strings are a subset of the Reserved_Identifiers. Within the Menu Definition File, they specify what "type" of definition is desired, ie specifying a selection key and its corresponding action, or specifying the error message to appear should the menu user type an invalid entry. Since the Control_Identifiers are all Reserved_Identifiers, only the first letter is significant as described above. BN notation Control_Identifier ::= Control_Character{character other than Word_Separators} Control_Character ::= E|S|L|C 4.2.3 _A_c_t_i_o_n__I_d_e_n_t_i_f_i_e_r These are character strings that specify the action to be performed when a selection is made from the menu being defined. They are also a subset of the Reserved_Identifiers, and only the first character is significant. BN notation Action_Identifier ::= Action_Character{characters other than Word_Separators} Action_Character ::= M|P|T|A 4.2.4 _W_o_r_d__S_e_p_a_r_a_t_o_r These are character strings that are used to separate the entities of the Menu Definition File. Word_Separators are any one or a combination of the following characters: ':' ',' ' '(blank) '<CR>' '<TAB>' ';' BN notation Word_Separator ::= Word_Separator_Char{Word_Separator_Char} Word_Separator_Char ::= :|,| |<CR>|<TAB>|; 4.2.5 _U_s_e_r__E_n_t_r_y These are user determined character strings, always enclosed in the delimiters "[ ]". The string within the delim- iters defines program, task, and menu names, line number and column number values, display text, and desired error mes- sages. The string within the delimiters can contain any charac- ters, however if the right delimiter character is desired Ford Aerospace and 9 Communication Corp. Drawing A14589 April 17, 1985 within the string, 2 consecutive right delimiter characters must be used. Some examples of User_Entries: [SYSTEM.TXT] [ Pick again, that is not valid ] [ [341,106]]systat.mac ; 3 ] BN notation User_Entry ::= Left_Delimiter{any character other than Right_Delimiter | Right_Delimiter Right_Delimiter} Right_Delimiter Left_Delimiter ::= [ Right_Delimiter ::= ] 4.2.6 _C_o_m_m_e_n_t The Comment, signified by a Comment_Identifier, makes the Menu Compiler ignore all characters following until the end of the line. Examples of Comments: * This is a Comment line.... SELECTION [4], PROGRAM [SAMPLE] *This comment follows code BN notation Comment ::= Comment_Identifier{any character string}<CR> Comment_Identifier ::= * 4.3 _S_t_r_u_c_t_u_r_e__o_f__M_e_n_u__D_e_f_i_n_i_t_i_o_n__F_i_l_e The Menu Definition File contains lines of text which are processed by the Menu Compiler. All blank lines are ignored. The Menu Definition contains two sections, the Title is always first, followed by the Body. The Title section is simply one line containing a single User_Entry. The delimited character string in the User_Entry is a file name, 8 characters or less, the first character being a letter, and no embedded blanks or special characters except the underscore '_'. This file name will be the external identification of the resulting Menu Description. Later we will see how a menu can be made to call another menu, using the Title name for that call. The Menu Compiler creates a Menu Definition Table from the Menu Descrip- tion File. This table file will have the name specified in the Title. Blanks before and after the Title name are ignored. Example of Title lines: [ MenuA ] The Menu Compiler will create a table file from the subsequent Menu Description. The table file will be called "MenuA". Other examples: [ M1_SAMPLS ] [A] Ford Aerospace and 10 Communication Corp. Drawing A14589 April 17, 1985 The Body section of the Menu Description contains a series of "definition instructions". Each instruction con- sists of a Control_Identifier followed by Reserved_Identifiers and/or User_Entries which qualify what is desired. More than one instruction can be put on a line, but they must be separated by Word_Separators, and the syntax of each instruction must be correct. An example of an instruc- tion is shown below: Control_ Reserved_Identifiers and User_ Identifier Identifiers to qualify action __|___ _______________|_______________ | | | | | | | SELECT:[4], PROG [FILEFIX], MENU [FILESEL] |________________________________________| | Full Instruction The use of each Control_Identifier is shown in the next section. 4.4 _I_n_s_t_r_u_c_t_i_o_n_s__a_n_d__U_s_e__o_f__C_o_n_t_r_o_l___I_d_e_n_t_i_f_i_e_r_s The following defines the use of the Control_Identifiers available. Remember that all Control_Identifiers are Reserved_Identifiers and that only the first character is significant. Any string starting with the same letter as the Control_Identifier can be used to perform the stated type of instruction. See section II for more detail. The following descriptions refer to the names of lexical units described in section II. Refer to sec- tion II as needed for more details. 4.4.1 _E_r_r_o_r__l_i_n_e The Error_line Control_Identifier is used to indicate what character string should be displayed should the menu user make a selection that is not defined. The form for an Error_line instruction is: The Control_Identifier, Error_line , followed by a Word_Separator, followed by a User_Entry where the character string is the line output on an invalid menu selection. Examples of Error_line instructions: E,[Improper Selection, Try Again] Err [ Err, [Improper Choice]] ] E_line [] * No error line on bad selection Only one error line will be used when the menu is running and receives bad selections. The last Error_line defined in the Menu Definition will be used when the menu runs. The error line can be up to the maximum column number of characters long, and will always appear on a predesignated line on the menu display. The default Error_line if none is specified in the Menu Definition File, is a blank line. Ford Aerospace and 11 Communication Corp. Drawing A14589 April 17, 1985 4.4.2 _S_e_l_e_c_t_i_o_n The Selection Control_Identifier is used to specify each menu selection key and the resulting action when the menu is running. The form of the Selection instruction is: The Control_Identifier, Selection , followed by a Word_Separator, followed by a User_Entry where the character string is one character specifying the keyboard key to type in order to invoke action when this menu is used. This is followed by another Word_Separator, followed by one of a set of Action_Identifiers that define what will occur when the designated key is typed at this menu being defined. The set of Action_Identifiers is: Ada If the designated key is typed at the running menu, an Ada procedure will be started. The procedure must be linked to the Menu Handler software. The procedure runs to completion, and the Menu Handler continues follow- ing. Task If the designated key is typed, the task specified will begin executing in background. The task must not require the terminal or else it will not perform correctly. Program If the designated key is typed, the program specified will begin executing. The program will run in fore- ground and take control of the terminal. On completion, it will return control to the Menu Handler. Menu If the designated key is typed, the Menu specified will be called and appear on the screen. The Menu Handler is still controlling the terminal and accepting inputs, but it is using a different Menu Definition Table to format the display and process inputs. Following one of these Action_Identifiers is a Word_Separator, and then a User_Entry, where the character string is the name of the Task, Program, or Menu to be called. The user can define only one Task or Program in the selection instruction. However, a Menu can be included in the instruction after a Task or Program is specified. An example of this is shown below. A Menu Action_Identifier listed in the Selection instruction will cause the specified menu to be called to the screen. If the Menu is specified after a Program, the menu will appear on the screen after the terminal control is returned to the Menu Handler from the Program. If the menu was specified after a Task or by itself, the terminal control never leaves the Menu Handler, and the menu will appear on the screen immediately after the selection is made. A message will be given at run time if a selection is made for a menu for which there is no Menu Ford Aerospace and 12 Communication Corp. Drawing A14589 April 17, 1985 Definition Table. Only one menu can be listed in the Selection instruction, and it must be the last Action_Identifier listed. If no Menu Action_Identifier is listed, then the current menu will be restored when terminal control is returned to the Menu Handler. Some examples of Selection instructions and the action of the resulting menu are given: Instruction: S:[G] TASK:[GOFORIT.CODE] Action of Menu: When "G" is entered to the Menu Handler, the task GOFORIT.CODE is started in background. Terminal control is still in the Menu Handler. Since no Menu Action_Identifier is listed, the current menu displays again, while the task GOFORIT is running. Instruction: Slct [M] : M [moremenu] Action of Menu: When "M" is entered to the Menu Handler, the new menu "moremenu" is called. This new menu is produced from a Menu Definition Table just as the previous one was. The new Menu Definition file dictates what appears on the screen and the processing of the menu users inputs. Instruction: Selection [@], Program:[test1], Menu:[samplers] Action of Menu: When '@' is entered to the Menu Handler, the program test1 starts and takes the terminal control. When test1 completes, the Menu Handler regains terminal control and now calls a new menu to display on the screen and process inputs. This new menu is produced using the Menu Definition Table "samplers", which was generated using this same Menu Compiler. The Column_number and Line_number instructions described below are used to put text on the menu display. When the Menu Handler is run, the menu display area on the screen is cleared. The menu designer must use the following instructions to place whatever is desired on the display. 4.4.3 _C_o_l_u_m_n__n_u_m_b_e_r The Column_number Control_Identifier sets the screen column position so that some character string can be shown at this position on the menu display. The form for a Column_number instruction is: The Control_Identifier, Column_number , followed by a Word_Separator, followed by a User_Entry where the delimited character string is an integer range 1 to the maximum column number, designating the column where the desired text will appear Ford Aerospace and 13 Communication Corp. Drawing A14589 April 17, 1985 on the menu display. Optionally following, is another Word_Separator, then another User_Entry where the delimited character string is the desired text to appear on the menu display. 4.4.4 _L_i_n_e__n_u_m_b_e_r The Line_number Control_Identifier sets the screen line position so that some character string can be shown at this position on the menu display. The form for a Line_number Instruction is: The Control_Identifier, Line_number , followed by a Word_Separator, followed by a User_Entry where the delimited character string is an integer range 1 to the maximum line number, designating the line where the desired text will appear on the menu display. As with the Column_number, a Word_Separator and a User_Entry can optionally follow containing text to be displayed at the desired position on the menu display. The optional User_Entry containing desired text can only be put following a Column_number instruction or a Line_number instruction, and it must be separated from the instruction by a Word_Separator. The first character of the desired text will appear on the menu display at the last set column and line positions. Column 1 and Line 1 are the default display positions prior to the column or line number being set using these instructions. The maximum line number and maximum column number will be parameters of the Menu Handler package. They are originally set to 80 for the max- imum column number, and 21 for the maximum line number. How- ever, they can be changed to fit the display terminals in use. Following are examples of Column_number instructions, Line_number instructions, and defining text on the menu display: Ford Aerospace and 14 Communication Corp. Drawing A14589 April 17, 1985 Example: C,[1] Line [3]: [Type "A" to run SAMPLE program] Results in the following menu display: Column 1 Line 3 Type "A" to run SAMPLE program Example: Line_number [5]: Column_number [13], [Pick one of the following letters] Line [7] [X] Column:[18] [Y], Column:[22] [Z] Results in the following menu display: 1111111222 Column 3456789012 Line 5 Pick one of the following letters Line 7 X Y Z The Line_number and Column_number instructions are a common use of more than one instruction on a line. Note that the Menu Handler puts no text on the menu display related to the valid keyboard selections defined in the Menu Definition File. Therefore, the user should use the above text displaying mechanism to display on the menu all valid key selections and their corresponding action. The user can specify up to the maximum column number of characters in the User_Entry for the text. However, an error will be given if the string will not fit on a line given the latest column set- ting. For example: Assuming the maximum column number is 80, the instruction COLUMN [50], [{some 31 character string........}] will give an error from Menu Compiler. Ford Aerospace and 15 Communication Corp. Drawing A14589 April 17, 1985 5. _O_p_e_r_a_t_i_n_g__I_n_s_t_r_u_c_t_i_o_n_s 1. Create a Menu Definition file using the Menu Definition Language. Any available editor may be used. This file must be copied into the filename that has been specified in the Mencon file as the input file to the Menu Compiler. For example, if the mencon file has the filename menu_def as the input file to the menu compiler, the Menu Definition file would have to be copied into menu_def. 2. Execute the main Ada program Menuread within the Ada environment. This creates a non-readable Menu Definition Table that is referred to by the title the user gave the menu when it was defined in step 1. Refer to Section III, Menu Definition Language Syntax, for further explanation of Menu Definition title syntax. 3. Copy the Menu Definition Table into the filename specified as the input file to the Menu Handler in the Mencon file. For example, if the mencon file has the filename menu_tabl as the input file to the menu handler, the Menu Definition Table would have to be copied into menu_tabl. 4. Execute the main Ada program Menushow within the Ada environment. 5. The menu displayed is based on the Menu Definition. The keys that can be typed are those given in valid selection instructions in the Menu Definition file. Invalid key selec- tions are flagged by a bad selection message as defined in the Menu Definition file. The lines of text displayed are those the user specified in the Menu Definition file. Ford Aerospace and 16 Communication Corp. Drawing A14589 April 17, 1985 6. _A_d_a__P_a_c_k_a_g_e__D_e_s_c_r_i_p_t_i_o_n_s Each package in the Menu Manager is split into two files. One file contains the package specification and the other con- tains the package body. The file that contains the package specification has a filename that ends in e. The file that con- tains the package body has a filename that ends in d. The full library unit name (i.e. the package name) is the same for both the specification and the body files. The filenames differ only in that one ends in e and the other ends in d. The filenames of each package are taken from the first four characters of the unit name, concatenated with the last three characters of the unit name, and appended with an e or d as appropriate. An eight char- acter file naming convention was observed, since many operating systems will not allow more than an eight character file name. The package descriptions are arranged alphabetically begin- ning with the units needed by the Menu Compiler, followed by the units needed by the Menu Handler. A * indicates the package is used by both the Menu Compiler and Menu Handler. The last descriptions are of the two main programs, Menuread.ada and Menushow.ada. 6.1 _M_e_n_u__C_o_m_p_i_l_e_r__P_a_c_k_a_g_e_s 6.1.1 _C_o_m_p_i_l_e_r__M_e_s_s_a_g_e_s * This package contains the procedures, data structures and values necessary for displaying messages during compilation. All the messages that the Menu Compiler and Menu Handler issue are in the COMERRS file. The first line is the code of severity for the message: NO_ERROR for information messages that are not related to errors, WARNING_ERROR for errors that that will not terminate the compilation or the creation of the Menu Definition Table, DISABLING_ ERROR for errors that will not ter- minate the compilation but will terminate the creation of the Menu Definition Table, and FATAL_ERROR for errors severe enough to terminate both the compilation and the creation of the Menu Definition Table. The second line is a 236 character line con- taining the text of the error message. One procedure (Initilize_Messages) of this package reads the COMERRS file into an array kept in the package. The array is used during compilation. The file is open only when it is initially being read, then closed for the duration of the program run. Compiler_Messages is contained in the files Compgesd.ada and Compgese.ada. The Compiler_Messages package is dependent on the Text_Handler_Subset and Text_IO Ada packages. Ford Aerospace and 17 Communication Corp. Drawing A14589 April 17, 1985 Table 3 Menu Compiler and Menu Handler Error Codes ---------------------------------------------------------------- | Severity Code | Definition | ---------------------------------------------------------------- | NO_ERROR | Information messages not related to errors | ---------------------------------------------------------------- | WARNING_ERRORS | Errors that will not terminate compilation | | | or the creation of the Menu Definition | | | Table. | ---------------------------------------------------------------- | DISABLING_ERROR | Errors that will not terminate compilation, | | | but will terminate the creation of the Menu | | | Definition Table. | ---------------------------------------------------------------- | FATAL_ERROR | Errors severe enough to terminate both the | | | compilation and the creation of the Menu | | | Definition Table. | ---------------------------------------------------------------- 6.1.2 _D_i_s_p_l_a_y__P_r_o_c_e_s_s_i_n_g * This package contains the procedures to handle the Menu Display. It stores the screen layout as an array of strings. The procedures are used to process the array of strings, and output the display to the screen. The package uses a Current Read Counter, and a Current Write Counter. These values indicate the next display line to be read and written from the display array. Display lines are read when the display is put to the Menu Definition Table file. Display lines are written when the Menu Definition Table file contains text to be put into the screen layout, and when the Menu Defini- tion Table is read by the Menu Handler. Display_Processing is contained in the files Dispingd.ada and Dispinge.ada. The Display_Processing unit is dependent on the Text_IO Ada package. 6.1.3 _H_a_n_d_l_e__C_o_m_p_i_l_e_r__C_o_m_p_o_n_e_n_t_s This package contains the pro- cedures used to process the compiler variables, i.e. the current line and column number, the bad selection message, and processing related to specific Control Identifiers. Handle_Compiler_Components is contained in the files Handntsd.ada and Handntse.ada. The Handle_Compiler_Components unit is dependent on the Text_Handler_Subset Ada package. 6.1.4 _P_r_o_c_e_s_s__C_o_n_f_i_g_u_r_a_t_i_o_n * This package contains the user defined items as read from the configuration file. The objects are kept in the package specification so that they are accessible to the main procedures Ford Aerospace and 18 Communication Corp. Drawing A14589 April 17, 1985 of the Menu Compiler, and the Menu Handler. The objects are also given default values in case an error occurs while reading the file, all objects will still have legal values. If problems do occur while the configuration file is being read, a !! prompt signals the user that problems exist. This is necessary because before reading the configuration file, the Menu Manager programs do not know how large the screen width is, and full text lines may not be correctly displayed. In any case, the configuration objects will at least have legal default values so the Menu Manager procedures can perform. Process_Configuration is contained in the files Prociond.ada and Procione.ada. The Process_Configuration unit is dependent on the Text_ IO and Text_Handler_Subset Ada packages. 6.1.5 _P_r_o_c_e_s_s__M_e_n_u__C_o_n_t_r_o_l__T_a_b_l_e * This package contains the subprograms necessary to hold and use the Menu Control list. This list is a dynamic list of Menu Control items. Each item in the list characterizes a menu selec- tion. Information contained in each item includes: the selection key defined in the menu, the type of action performed when this key is typed, and the name of the process or command executed. Process_Menu_Control_Table is contained in the files Proc- bled. ada and Procblee.ada. The Process_Menu_Control_Table unit is dependent on the Sequential_IO, Text_IO, and Text_Handler_Subset Ada packages. 6.1.6 _P_r_o_c_e_s_s__M_e_n_u__D_e_f__S_t_r_i_n_g * This package is used by the Menu Compiler, and contains the subprograms necessary for basic processing of the Menu Definition file. The Menu Definition file is written in the Menu Definition Language, and is a description of the menu display and menu action. The file can be thought of a series of lexical units, that are characters in a set of characters. The characters are arranged in the file so they can be sequentially extracted. This package contains subprograms to extract and handle these lexical units. Analyzing the lexical units for correct content and order is a function of the Handle_ Compiler_Components package. No com- piler errors regarding lexical units appears in this package. The Menu Definition file is an external file that is created and modified with an available editor, and uses the operations of a particular operating system. One of the functions of this pack- age is to transfer the external file to a Menu Definition string. The string is a dynamic character string that contains all the characters in the file. The string is kept in this package and is processed when the lexical units are extracted. This keeps the Menu Defintion file open for a minimum amount of time. Ford Aerospace and 19 Communication Corp. Drawing A14589 April 17, 1985 Process_Menu_Def_String is contained in the files Procinge.ada and Procingd.ada. The Process_Menu_Def_String unit is dependent on the Text_IO and Text_Handler_Subset Ada packages. 6.1.7 _T_e_x_t__H_a_n_d_l_e_r__S_u_b_s_e_t This package is a subset of the Text Handler package from the Language Reference Manual (ANSI/MIL-STD-1815A). It contains only the procedures needed by the Menu Manager project. The TEXT type is a dynamic character string type. This is implemented using access types where the object is a pointer to a string. The string expands dynamically because the object points to a new string that includes the text of the previous string and more. This is one of the few non- generic library units in the Menu Manager, and must be compiled before the other units are. Text_Handler_Subset is contained in the files Textsetd.ada and Textsete.ada. The Text_Handler_Subset unit is dependent on the Unchecked_Deallocation Ada package. 6.1.8 _P_r_o_c_e_s_s__I_n_i_t_i_a_t_o_r This is the package body for the Process_Initiator package. This file will be edited by the user to provide necessary pro- cedures run from the Menu Handler. Procedures must be supplied by the user to interface between the Ada environment and the operat- ing system command line interpreter. If the Ada environment does not have the capability of issuing a command line from within the Ada program, the Menu Handler cannot be used to issue commands to the operating system command line interpreter. Process_Initiator is contained in the files Proctord.ada and Proctore.ada. The Process_Initiator unit is dependent on the Text_IO Ada package. 6.2 _M_e_n_u__H_a_n_d_l_e_r__P_a_c_k_a_g_e_s 6.2.1 _C_o_n_t_r_o_l_l_i_n_g__M_e_n_u__I_n_f_o__L_i_n_e This is the package that holds and processes the Menu Infor- mation line. This line appears at the next to last line of the Menu Display. It conveys simple information to the user when the menu is displayed. The line is usually blank but will display a bad selection or task started message if necessary. This package can be modified to contain other text information should the sys- tem be expanded. Controlling_Menu_Info_Line is contained in the files Contined.ada and Continee.ada. This unit has no dependencies. 6.2.2 _H_a_n_d_l_e__P_r_o_c_e_s_s_e_s This package contains the subprograms used by the Menu Handler to process the requests for action that result from the menu users input. This package will also contain Ford Aerospace and 20 Communication Corp. Drawing A14589 April 17, 1985 the file name of the Menu Definition Table that defined the next menu to be displayed. Handle_Processes is contained in the files Handsesd.ada and Handsese.ada. The Handle_Processes unit is dependent on the Text_ Handler_Subset Ada package. 6.2.3 _P_r_o_c_e_s_s__I_n_i_t_i_a_t_o_r This package contains two procedures, Ada_Procedure_Call and Command_Line_Processor, the bodies of which must be user supplied except for a few sample and skeletal statements. These procedures provide the interface between the Menu Handler and the command line interpreter, and the interface between the Menu Handler and any Ada procedures that the user wants to link to the Menu Handler program. The package specification contains procedure specifications for the two interface procedures. These should not be changed since this provides the link between the interface procedures and the rest of the Menu Handler software. The user must supply the statements in the procedure bodies to insure that the procedures input and return the desired values. Refer to Sec- tion II, Description of the Mencon and Process_Initiator Files, for a more complete description of the necessary user supplied procedure bodies. Process_Initiator is contained in the files Proctord.ada and Proctord.ada. The Process_Initiator unit is dependent on the Text_IO Ada package. 6.3 _M_a_i_n__P_r_o_g_r_a_m_s 6.3.1 _M_e_n_u_r_e_a_d This is the main processor routine for the Menu Compiler. The procedure first reads the configuration file Mencon. It then instantiates the packages needed using the values found in Men- con, and reads the Menu Definition input file. The name of this file is specified in the configuration file. Menuread processes the Menu Definition file to create the Menu Definition Table used by the Menu Handler. Menuread is contained in the file Menuread.ada. The Menuread procedure is dependent on the Text_IO, Handle_Compiler_Components, Display_Processing, Process_Menu_Control_Table, Process_Menu_Def_ String, Compiler_Messages, Process_Configuration, and Text_Handler_ Sub- set Ada packages. 6.3.2 _M_e_n_u_s_h_o_w This procedure is the main program executed when the Menu Handler is run. Menushow first reads the configuration file Men- con. Using the values in that file, the program will instantiate Ford Aerospace and 21 Communication Corp. Drawing A14589 April 17, 1985 packages to create procedures that will run for this particular configuration. The program reads the Menu Definition Table created by the Menu Compiler. This file name is specified in the configuration file. Menushow will display the proper menu layout, and perform the proper processing on the users inputs. Menushow is contained in the file Menushow.ada. The Menushow procedure is dependent on the Text_IO, Display_Processing, Pro- cess_ Menu_Control_Table, Compiler_Messages, Process_Configuration, Text_ Handler_Subset, Controlling_Menu_Info_Line, Handle_Processes, and Process_Initiator Ada packages. Ford Aerospace and 22 Communication Corp. Drawing A14589 April 17, 1985 7. _A_p_p_e_n_d_i_x__1__I_n_s_t_a_l_l_a_t_i_o_n Each Ada package in the Menu Manager is split into two files. One file contains the package specification and the other contains the package body. The file that contains the package specification has a filename that ends in e. The file that con- tains the package body has a filename that ends in d. The full library unit name (i.e. the package name) is the same for both the specification and the body files. The filenames differ only in that one ends in e and the other ends in d. The filenames of each package are taken from the first four characters of the unit name, concatenated with the last three characters of the unit name, and appended with an e or d as appropriate. An eight char- acter naming convention was observed, since many operating sys- tems will not allow filenames of more than eight characters. These names can be changed by the user if their particular system has the capability of reading more than eight characters. The main procedures (Menuread.ada and Menushow.ada) have the same unit name as filenames. The following are the files delivered: - Overhead Files (Used by both the Menu Compiler and Menu Handler): - Comerrs - Mencon Menu Compiler Unit Name Files that contain the Unit ______________________________________________________________ Compiler_Messages Compgese.ada * Compgesd.ada * Display_Processing Dispinge.ada * Dispingd.ada * Handle_Compiler_Components Handntse.ada Handntsd.ada Process_Configuration Procione.ada * Prociond.ada * Process_Menu_Control_Table Procblee.ada * Procbled.ada * Process_Menu_Def_String Procinge.ada Procingd.ada Text_Handler_Subset Textsete.ada * Textsetd.ada * * indicates that these files are also used by the Menu Handler Ford Aerospace and 23 Communication Corp. Drawing A14589 April 17, 1985 Menu Handler Unit Name Files that contain the Unit ______________________________________________________________ Controlling_Menu_Info_Line Continee.ada Contined.ada Handle_Processes Handsese.ada Handsesd.ada Process_Initiator Proctore.ada Proctord.ada Main Programs Menuread.ada Menushow.ada 7.1 _C_o_m_p_i_l_i_n_g__a_n_d__L_i_n_k_i_n_g 1. The package specification with the filename Textsete.ada must be compiled first. 2. Compile the rest of the package specifications. (Those files with names ending in e.) 3. Compile the package bodies. (Those files with names ending ending in d.) 4. Compile the main programs (Menuread.ada and Menushow.ada.) 5. Link the main programs. The user should note that if any package specification is re-compiled, it is necessary to re-compile any of that specifica- tions dependencies. A package dependency is any other Ada library unit name included within the code in a "with" clause. Therefore, dependencies of unit "A" are those units that have "A" in their with clause. Refer to Section V, Ada Package Descriptions, to determine package dependencies. In some versions of Ada, if a package body has been re-compiled its dependencies may also have to be re-compiled, even if the package specification has not been changed. Menuread is a dependency of the Ada packages Text_IO, Handle_Compiler_Components, Display_Processing, Process_Menu_ Control_Table, Process_Menu_Def_String, Compiler_Messages, Process_Configuration, and Text_Handler_Subset. Menushow is a dependency of the Ada packages TextIO, Display_Processing, Process_Menu_Control_Table, Compiler_Messages, Process_Configuration, Text_Handler_Subset, Controlling_Menu_Info_Line, Handle_Processes and Process_Initiator. Changes to the above packages will require re-compiling and re-linking either or both of the main programs. Ford Aerospace and 24 Communication Corp. Drawing A14589 April 17, 1985 8. _A_p_p_e_n_d_i_x__2__U_s_i_n_g__t_h_e__S_a_m_p_l_e__M_e_n_u__D_e_f_i_n_i_t_i_o_n__F_i_l_e_s Three sample Menu Definition Files have been delivered with the Menu Manager, file sampmen1.mne, sampmen2.mne, sampmen3.mne. These Menu Definition Files can be compiled by the Menu Compiler, and the menus run using the Menu Handler, to demonstrate how the Menu Manager works. The user should first examine the files, and follow the syn- tax of the Menu Definition Language used, to determine how the resulting menus will operate. The menus can be compiled and run following the installation of the Menu Manager software. It is not necessary to have interfaces to the operating system CLI (Command Line Interpreter) set up. These sample menus are intended to be used with the stub procedure delivered as the CLI interface, and the skeleton procedure delivered as the interface with other Ada procedures (a sample procedure delivered within the PROCESS_INITIATOR package is called by the sample menus). To use the sample menus, follow the installation instruc- tions so that the program Menuread and Menushow exist as execut- able programs. It is assumed that the MENCON configuration file contains the default values, if the values have been changed, the instructions discussed here will differ accordingly. Copy the sampmen1.mne file into the filename MENUFILE (this is the name of the Menu Compiler input file as defined in the MENCON configuration file). Execute the Menuread program. The screen should clear and a final message should appear. The program takes about 1 minute to run (based on medium loading on the Rolm Ada compiler on a Data General 4000 machine). Follow the two steps above for the other sample menu files, sampmen2.mne, and sampmen3.mne. Notice the error message that appears when the third menu is compiled. The errorous menu will be run to demonstrate the effect of doing so. The Menu Compiler has created Menu Definition Tables for the three menus. The file names correspond to the title given as the first user literal in each Menu Definition File (see Menu Defini- tion Language guide). The titles, and consequently the file names of the three Menu Definition Tables are sam1, sam2, and sam3. The Menu Handler is now run with any of these Menu Definition Table files. Copy the file sam1 into the name MENUTABL. MENUTABL is the file where the Menu Handler receives its input, as defined in the MENCON configuration file. Execute the Menushow program. Some overhead processing is done (takes about 30 seconds), then the display will clear and Ford Aerospace and 25 Communication Corp. Drawing A14589 April 17, 1985 the display layout for the sam1 menu will appear as defined in the sampmen1.mne Menu Definition File. The inputs allowed are now dependent on the Menu Definition File. According to the sample, selection keys 'a', 'b', and 'c' are available. Try typing another key and the Bad Selection Message, also defined in the Menu Definition File, will appear at the bottom of the screen. The '!' character can be used to type a command line to the CLI (the line is passed to the stub CLI interface, which simply causes the line to be written back, and waits for a character typed to continue the Menu Handler). The default QUIT character defined in the MENCON file is the '@'. Typing this character will cause the Menu Handler to terminate unless the QUIT character in the MENCON file is changed. Selection key 'c' on the sam1 menu will call the sample Ada procedure delivered (this procedure dislays a line and waits for a character to be typed). When the procedure is completed, the next menu handled is the sam2 menu. The layout for this menu is displayed, and user inputs are now processed based on the valid selection keys defined in the sampmen2.mne Menu Definition File. Note that the Bad Selection Message is different for this menu. Move to the sam3 menu by typing the selection key '3'. The sam3 menu had a syntax error in its Menu Definition File, but a Menu Definition Table was still created, and conse- quently, the menu can still be called. Note however that one of the display lines is not displayed because the error appeared in the user literal defining that display line. Note also that all the selection keys still work as defined in the Menu Definition File, since no errors were found in the Selection instructions. This produces the interesting affect in that selection keys can be made available to the menu user, but no display is required to explain them. Remember that the Menu Display Layout, and the valid selection keys are completely defined by the user in the Menu Definition File. From the sam3 menu, the user can type '%' to execute the sample Ada procedure again, and the Menu Handler now handles the sam1 menu again. The Menu Handler is exited by hitting the QUIT character. This gives a quick demonstration of how the Menu Compiler and Handler works. The user should experiment with Menu Defini- tion Files to demonstrate the error messages that appear (for example the user can enter an Ada procedure name that in not currently linked to the handler, and try to make that selec- tion when the menu is run). The text of the three sample Menu Definition Files is shown below: Ford Aerospace and 26 Communication Corp. Drawing A14589 April 17, 1985 Sample Menu 1 * This is Sample Menu 1 delivered with the Menu Manager. This * Menu calls a "Task", a "Program" and an Ada procedure followed * by a call to another menu. [ sam1 ] * Will create a Menu Definition Table called * "sam1" Line[2] Col[1] [ This is the Sample Menu 1, it is used to demonstrate the Menu Manager.] l[4] [ The selections available are:] l[7] col[10] [ 'a' to start the task 'ABDCE'] l[9] [ 'b' to start the program 'XYZ' ] l[11] [ 'c' to start Ada procedure SAMPLE_1, and bring up menu 'sam2'] Error_line_is [ That selection is bad, try again ] S [ a ] Task [ ABCDE ] Select [ b ] program [ XYZ ] Select [c] Ada [ SAMPLE_1 ] Menu [ sam2 ] Ford Aerospace and 27 Communication Corp. Drawing A14589 April 17, 1985 Sample Menu 2 [sam2];Error[ Wrong selection, try again ] * This the Sample Menu 2 delivered with the Menu Manager. This * menu includes selection commands that only call the other menus, * no programs, tasks or Ada procedures are called in this menu. Select [ 1 ] Menu [ sam1 ] Sel [3] Menu_def_table [sam3] Line [5] Column [6] [This menu is the Sample Menu 2 delivered to demonstrate the Menu Manager.] Line [8] [The menu is used to select the other menus. The selections include:] Line_number [10] Col[15] [type "1" to display menu "sam1"] Lin[11] [type "3" to display menu "sam3"] *** End of sampmen2.mne, Menu Def Table sam2 **** Ford Aerospace and 28 Communication Corp. Drawing A14589 April 17, 1985 Sample Menu 3 * This is Sample Menu 3 delivered with the Menu Manager for * demonstration. This menu will contain to selections that * call the Ada procedure followed by displaying each of the * other sample menus. The 3 selection will contain a slight * syntax error. This will demonstrate how the compiler produces * a Menu Def Table even if Warning type errors are found. The * resulting action of the Menu should be examined by the user. [sam3],Error[opps...] L[4] [This is Sample Menu 3 delivered to the user. The Men Definition File for] L[5] [this Menu contains some syntax errors, however a Menu Definition Table is] L[6] [still created, and the action of the resulting menu should be noted.] l[9] Column [5] [The '%' will call the Ada procedure "SAMPLE_1" followed by menu "sam1"] l[10] [The '#' will call the Ada procedure followed by menu "sam3" * note the Line * has no closing delimiter. [ sample text] l[12] [The '$' will call the Ada procedure followed by displaying menu "sam2"] Select [ % ] Ada [SAMPLE_1] Menu [sam1] Select [ # ] Ada [SAMPLE_1] Menu [sam3] Sel [ $ ] Ada [SAMPLE_1] Menu [sam2] l[15] col [2] [Note that although the line defining selection '#' is not displayed] l[16] [the selection key still works. This is because the syntax error was] l[17] [found in the line to be put to the Menu Layout, and no error was ] l[18] [found in the Select command identifying the '#' character.] Ford Aerospace and 29 Communication Corp. Drawing A14589 April 17, 1985 9. _A_p_p_e_n_d_i_x__3__M_e_n_u__C_o_m_p_i_l_e_r__a_n_d__M_e_n_u__H_a_n_d_l_e_r__M_e_s_s_a_g_e_s FATAL_ERROR Error in opening the Menu Definition File given. The compiler cannot continue. Check that the file exists. FATAL_ERROR Error in opening the Menu Definition Table File. The file specification given in the Title User Identifier may be an improper file specif- ication for this operating system. The compiler cannot continue. WARNING_ERROR A User Literal specifying a Selection Key must follow the Select Identifier. The selection instruction will be ignored. WARNING_ERROR The Selection Key given in the User Literal must be a single character. The selection instruction will be ignored. WARNING_ERROR The Character given for a Selection Key is not currently allowed. The selection instruction will be ignored. WARNING_ERROR An Action Identifier and a process to be ini- tiated must follow the Selection Key in a selection instruction. WARNING_ERROR The Identifier given in the selection instruc- tion is not a valid Action Identifier. WARNING_ERROR A User Literal giving the file name of a pro- cess to be initiated must follow an Action Identifier. The Action Identifier will be ignored. WARNING_ERROR Only one process and one menu is allowed to be initiated on each selection instruction. Subse- quent processes defined in this selection instruction will be ignored. WARNING_ERROR A User Literal containing a file name of a Menu Definition Table must follow a MENU Action Identifier. This Menu Definition Table will be used as the next menu for the selection being defined. WARNING_ERROR A User Literal specifying an integer column number is expected after the COLUMN identifier. WARNING_ERROR The Column number given is not in the range of the current screen size configuration. The column number value will remain unchanged. Ford Aerospace and 30 Communication Corp. Drawing A14589 April 17, 1985 WARNING_ERROR A User Literal specifying an integer line number is expected after the LINE identifier. WARNING_ERROR The Line number given is not in the range of the current screen size configuration. The line number value will remain unchanged. WARNING_ERROR A User Literal specifying a Bad Selection Mes- sage is expected after the ERROR Identifier. WARNING_ERROR The Bad Selection Message given is too long to fit on the screen under the current screen size configuration. The User Defined Variables can be changed to set a new screen size configura- tion. DISABLING_ERROR The first non-comment Lexical Unit in the Menu Definition File must be a User Literal contain- ing the name of the Menu Definition Table file that will be created. Compilation will con- tinue but no Menu Definition Table will be created. WARNING_ERROR The Control Identifier given is not recognized. The Identifier will not be processed. WARNING_ERROR The Text string specified is to long too fit on the current Line and Column. Text that was there before will remain there. NO_ERROR Error status is FATAL - No Menu Definition table is created, and the Menu Compiler has Aborted. NO_ERROR Error Status is DISABLE - Menu Definition File compiled completely, however a Menu Definition Table was not created due to Disabling Errors. NO_ERROR Error status is WARNING - Menu Definition File compiled completely, and the Menu Definition Table is created. However, errors may cause UNPREDICTABLE RESULTS if the Menu Handler is run with the table file created here. NO_ERROR Error status is NO ERRORS - Menu Definition File compiled completely, and the Menu Defini- tion Table is created. FATAL_ERROR Unable to find the Menu Definition Table given for processing. Make sure the Menu Definition Table was created by the compiler. The Menu Handler will abort. Ford Aerospace and 31 Communication Corp. Drawing A14589 April 17, 1985 WARNING_ERROR The Menu to be displayed was compiled with a different screen size configuration then what is currently in effect with this execution of the Menu Handler. The previous menu will be displayed. WARNING_ERROR The name of the menu of the process given is too long for the current configuration. The User Defined variable can be adjusted to change the maximum file name size. DISABLING_ERROR The name given for the Menu Definition Table is too long. No Menu Definition Table will be created. NO_ERROR Please enter the name of the Menu Definition File to be compiled. FATAL_ERROR Unable to find the Menu Definition Table given for processing. Make sure the Menu Definition Table was created by the compiler. The Menu Handler will abort. WARNING_ERROR Menu to be displayed was compiled with a dif- ferent screen size configuration than what is currently in effect with this execution of the Menu Handler. The previous menu will be displayed. WARNING_ERROR The name of the menu of process given is too long for the current configuration. The user defined variable can be adjusted to change the maximum file name size. DISABLING_ERROR The name given for the Menu Definition Table is too long. No Menu Definition Table will be created. NO_ERROR Please enter the name of the Menu Definition File to be compiled. FATAL_ERROR The initial Menu Table file given is not found. The Menu Handler will abort. FATAL_ERROR The initial Menu Table file given was compiled with a different configuration than is currently running on the Menu Handler. The con- figurations must be consistent for each menu description. The Menu Handler will abort. Ford Aerospace and 32 Communication Corp. Drawing A14589 April 17, 1985 WARNING_ERROR The Menu Table File for the menu selected is not found. Make sure the Menu Definition File for the menu was compiled. Previous Menu will be displayed. WARNING_ERROR The Menu selection was compiled with a dif- ferent configuration than is currently running on the Menu Handler. Previous Menu will be displayed. WARNING_ERROR The command line interpreter for this operating system cannot process the given line. This Ada environment must have the capability to pass a command line to the system command line inter- preter. WARNING_ERROR The Command Line Interpreter for this operating system cannot process this concurrent task. The Ada environment must have the capability to pass a command to the system command line interpreter, and have it run concurrently with this Menu Handler. WARNING_ERROR The Command Line Interpreter returns errors when the command given is issued. The Ada environment must have the capability to pass a command to the system command line interpreter and start the process. WARNING_ERROR The Ada Procedure desired is not currently linked to the Menu Handler software. The pack- age body PROCESS_INITIATOR must be edited to include reference to the Ada procedure if the procedure is desired in the Menu Definition. Ford Aerospace and 33 Communication Corp. Drawing A14589 April 17, 1985 10. _A_p_p_e_n_d_i_x__4__G_l_o_s_s_a_r_y MENU This term refers to text displayed on the users screen, AND the users possible inputs to the system. Both the display and and the response to user input is involved in defining a menu. MENU DEFINITION FILE The user supplied text file, written in the Menu Definition Language, that is the description of the menu display, and definition of valid user Inputs. MENU DEFINITION TABLE The output from the Menu Compiler. This is a non-text table file containing the menu description in the form needed by the Menu Handler. PACKAGE This is an Ada library unit. A package contains procedures that can be called be referring to the package. The package may also contain objects of variable that are kept in the package for the life of its reference, even though the calling program may not be using a pro- cedure from that package. This allows a nice method of organizing processing. PROGRAM A file name or command that is passed to the operating system Command Line Interpretor, and is executed in fore- ground. The Menu Handler will wait for the command to finish before continuing. TASK A file name or command that is passed to the operating system Command Line Interpretor, and is executed in back- ground. The Menu Handler continues con- currently with the Task. Ford Aerospace and 34 Communication Corp. Drawing A14589 April 17, 1985 11. _A_p_p_e_n_d_i_x__5__S_o_u_r_c_e__C_o_d_e This appendix contains the source code for the Menu Manger. The files are arranged in alphabetical order by file name. The user is urged to read the comments contained in the files Proctord.ada and Proctore.ada before attempting to supply the necessary procedures to interface between the Ada environment and the command line interpreter. Refer also to Section II, Descrip- tion of the Mencon and Process_Initiator Files, for more explana- tion. For full Source Code Listing, refer to Drawing No. A14588 delivered with the Menu Manager. Ford Aerospace and 35 Communication Corp. Drawing A14589 April 17, 1985 CONTENTS 1. Overview................................................ 1 1.1 User Related Objectives............................ 2 1.2 Software Product Objectives........................ 3 1.3 Using the Menu Compiler............................ 4 1.4 Using the Menu Handler............................. 4 2. Description of the Configuration File (Mencon).......... 6 3. Description of the Process_Initiator Ada Package........ 7 4. Menu Definition Language Syntax......................... 8 4.1 Introduction....................................... 8 4.2 Definition of Basic Lexical Units.................. 8 4.3 Structure of Menu Definition File.................. 10 4.4 Instructions and Use of Control_Identifiers........ 11 5. Operating Instructions.................................. 16 6. Ada Package Descriptions................................ 17 6.1 Menu Compiler Packages............................. 17 6.2 Menu Handler Packages.............................. 20 6.3 Main Programs...................................... 21 7. Appendix 1 Installation................................. 23 7.1 Compiling and Linking.............................. 24 8. Appendix 2 Using the Sample Menu Definition Files....... 25 9. Appendix 3 Menu Compiler and Menu Handler Messages...... 30 10. Appendix 4 Glossary..................................... 34 11. Appendix 5 Source Code.................................. 35 Ford Aerospace and - i - Communication Corp. --:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: --items. --:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Menu Manager Contract N66001-85-C-0035 Naval Ocean System Center Items of Interest Encountered During Work on Project This report was prepared on June 24, 1984 as a result of discussion during the demonstration of NOSC tool 48, the Menu Manager. It is being sent over the network in lieu of a formally delivered final report. The list is a collection of information found in the following sources: - Monthly Progress Reports Delivered from November 84 - March 85 - Presentation Slide Package, given on demonstration of Menu Manager tool, June 20, 1985 - Programmers Notebook, on file in SVO Software Engineering Dept. The items are listed by month. November 84 Experiments were done using the TeleSoft Ada on the Sun Work Station with Unix operating system. Single character input was not possible since the TEXT_IO.GET was reading from a buffer, signaled by a RETURN key. When return is hit, the characters previously typed are then passed to the input routines of the Ada program. We were able to get single character input by sending a call from the Ada program to the operating System to put the terminal in raw mode, then after input session, send another "stty" command to put the terminal back in normal mode. Our first Ada programs are written as Ada packages. The packages contain the procedures necessary, and the initialization statements of the package form the whole program. The Ada package is run rather than running the procedures. January 85 Problems have been found using the TeleSoft Ada compiler. Using the command line ADA/MPP/SOURCE_LISTING <filename> is supposed to compile the source code and produce a source listing. Run time errors occur when we run a program compiled in this way. In Conversation with Tim LaSelle of TeleSoft, he informs us the listing feature is unpredictable. We are receiving run errors when a very small program that declares a Variant record is run. The errors will not appear in the output of the program, only on the display as the program is run. Error message is "Exception on Production #263" (the number varies). In conversation with Tim LaSelle of TeleSoft, he tells us that variant records and generic processing is still unpredictable in TeleSoft Ada. He could not tell exactly what the different exception numbers meant. February 85 Test programs that do not run in the TeleSoft Ada environments will run successfully in the Data General / Rolm Ada environment. A test program taking 10 seconds to compile on the Rolm compiler took over 5 minutes on TeleSoft. There has been some discussion on the legality of the following Ada code: type DYN_STRING (SIZE: NATURAL := 0) is record DATA: STRING (1..SIZE); end record; X : DYN_STRING := (5,"HELLO"); Y : DYN_STRING := (6,"HELLOX"); . . X := Y; The discussion involves whether the declaration fixes the length of the string or if the string is truly dynamic. When tried on the Rolm compiler, the assignment is legal, however the object declarations as written above are not legal. In the case above, memory would be allocated for the object "X" and "Y" such that the largest possible type could be accommodated; this means a string of constraint 0..NATURAL'LAST. In our final design for the Menu Manager, we have realized some inherent characteristics of a system independent Menu Manager. The ability to pass a string to the operating system CLI for interpretation is dependent on the Ada environment and its interface with the operating system. In our final product we will leave stubs for such a CLI call, and the string to be passed will simply be displayed. Allowing the call of further Ada procedures is usage dependent. We will leave sample code to show a call to one sample Ada procedure, but further Ada procedures desired to be called by the Menu Handler will involve the user editing a section of the Ada code, recompiling that section and relinking the Menu Handler section (Menu Compiler will not have to be relinked). March 85 We tried to use an aggregate to assign the text for the program messages to a variable. We got an error that the source line and the string literal were too long. We will have to put the text for the messages on a file, and read the text into the array variable at run time. We reconstructed the code that caused the error and tried compiling. A partial listing of that compile is below. Ada 5.241 6/24/85 at 11:10:31 :UDD1:LAMARCHE:ADA:RUN:COMPGESD.ADA page 1 ------+------------------------------------------------------------------------- 1 ! 2 ! 3 ! -- COMPILER_MESSAGES;COMPGESD.ADA;KJL;04/18/85 4 ! 5 ! -- Package body to handle compiler messages. 6 ! 26 ! 27 ! with TEXT_IO; 28 ! package body COMPILER_MESSAGES is 29 ! 30 ! MESSAGE_SIZE: constant := 236; -- string size of messages. 31 ! LAST_MESSAGE: constant := 36; -- number of messages in : COMERRS file 32 ! 33 ! -- Set of severity codes 34 ! type ERROR_TYPES is (FATAL_ERROR,DISABLING_ERROR,WARNING_ERROR, : NO_ERROR); 35 ! 36 ! -- Structure used to store message information from COMERRs file. 37 ! type MESSAGE_INFO is 38 ! record 39 ! ERROR_STATUS: ERROR_TYPES; 40 ! MESSAGE_LINE: STRING(1..MESSAGE_SIZE); 41 ! end record; 42 ! 43 ! type MESSAGE_LIST_TYPE is array (1..LAST_MESSAGE) of MESSAGE_INFO; 44 ! 45 ! 46 ! NUMBER_OF_ERRORS: INTEGER := 0; -- Tally of all types of errors 47 ! MESSAGE_LIST: MESSAGE_LIST_TYPE := ( 48 ! 1 => 49 ! (FATAL_ERROR, 50 ! "Error in opening the Menu Definition File given. The compiler cannot ------+------------------------------------------------------------------------- Ada 5.241 6/24/85 at 11:10:31 :UDD1:LAMARCHE:ADA:RUN:COMPGESD.ADA page 2 ------+------------------------------------------------------------------------- : continue. Check that the file exists. : : ------+------------------------------------------------------------------------- *** Source line is too long. *** String literal is too long. ------+------------------------------------------------------------------------- 51 ! "), 52 ! 2 => 53 ! (FATAL_ERROR, ------+------------------------------------------------------------------------- *** Source line is too long. *** String literal is too long. ------+------------------------------------------------------------------------- 54 ! "Error in opening Menu Definition Table file. The file specification : given in the Title User Identifier may be an : improper file spec for this operating system. The : compiler can not continue. 55 ! "), 56 ! 3 => ------+------------------------------------------------------------------------- *** Source line is too long. *** String literal is too long. ------+-------------------------------------------------------------------------