03/19/85 ft_menu_ The ft_menu_ subroutine allows a FORTRAN program to use the Multics menu facility (menu_). Through ft_menu_ a FORTRAN program may create a menu object, display the menu, and get a user-entered selection from a menu. Once a menu object has been created, the FORTRAN program can use this menu object by referencing it via a menu-id returned to the caller when the menu object was created or when a stored menu object was retrieved. The functionality available is provided through the various entry points defined below. Entry points in ft_menu_: (List is generated by the help command) :Entry: create: 03/19/85 ft_menu_$create Function: Utilized to create a menu object. It returns a menu identifier (menu_id) which is subsequently used to reference the menu object. Syntax: declarations: character*n1 choices(m1) character*n2 headers(m2) character*n3 trailers(m3) character*1 keys(m4) character*1 pad_char integer menu_format(6) integer menu_needs(3) integer menu_id integer code call ft_menu_$create (choices, headers, trailers, pad_char, menu_format, key, menu_needs, menu_id, code) Arguments: choices is an array of character variables which are the text of the options that the user wishes to display in the menu. (Input) n1 is the length, in characters, of the longest character string comprising the text of an option. m1 is the extent of the array, i.e., the number of options in the menu being described. This array must be at least of extent 1. headers is an array of character variables to be displayed at the top of the menu. (Input) n2 is the length, in characters, of the longest header specified. m2 is the extent of the array, i.e., the number of headers (lines) desired. At least one header must be specified (if the first variable is set to blanks, no headers will be used). trailers is an array of trailers (displayed immediately below the menu). (Input) n3, m3, are analogous to n2, m2 respectively. menu_format is an array, which specifies the format of the menu being created. (Input) Prior to calling this entry point, the FORTRAN programmer is responsible for setting the following variables: menu_format(menu_version) = version number of menu_ (currently, only version 1 is defined). menu_format(max_width) = maximum width of the window on which the menu will be displayed. menu_format(max_heigth) = maximum height of window on which menu is to be displayed. menu_format(no_of_columns) = number of columns to be used by the menu manager to display the options. menu_format(center_headers) = 0 or 1; 0 = no, 1 = yes. menu_format(center_trailers) = 0 or 1; 0 = no, 1 = yes. pad_char is the character that the menu facility will display at the right and left of a centered header or trailer to fill out the line. (Input) keys is an array (maximum value of m4 is 61) that identifies the keystroke to be associated with each choice. (Input) This array must be at least as long as the number of choices in the menu. Each element in the array must be unique. menu_needs an array that contains menu related information on successful execution of call. (Output) Returned information: menu_needs(lines_needed) the number of lines required to display the menu. menu_needs(width_needed) the number of columns required to display the menu. menu_needs(no_of_options) the number of options defined in the menu. menu_id the menu identifier (i.e., the menu object "identifier"). (Output) It must not be altered in any way by the application program. code return code. (Output) :Entry: delete: 03/19/85 ft_menu_$delete Function: Deletes a menu object from a given value segment. (See ft_menu_$store.) Syntax: declarations: character*168 dir_name character*32 entry_name character*32 menu_name integer code call ft_menu_$delete (dir_name, entry_name, menu_name, code) Arguments: dir_name pathname of the directory containing the menu object. (Input) entry_name entry name of value segment containing the menu object. (Input) The suffix "value" need not be specified. menu_name name used to identify the menu object when the menu object was stored. (Input) code return code. (Output) :Entry: describe: 03/19/85 ft_menu_$describe Function: Returns information about a menu object. It returns the number of options in the menu, the number of lines and number of columns required to display the menu. It is primarily used to determine if the menu can be displayed in a given window. Syntax: declarations: integer menu_id integer menu_needs(3) integer code call ft_menu_$describe (menu_id, menu_needs, code) Arguments: menu_id the menu identifier returned by ft_menu_$create or ft_menu_$retrieve. (Input) menu_needs an array into which menu related information is returned. (Output) Returned information: menu_needs(lines_needed) the number of lines required to display the menu. menu_needs(width_needed) the number of columns needed to display the menu. menu_needs(no_of_options) the number of options defined in the menu. code return code. (Output) :Entry: destroy: 03/19/85 ft_menu_$destroy Function: Invoked to delete a menu object from storage. (Not to be confused with ft_menu_$delete, which deletes the menu object from a value segment.) Deleting the menu object has no effect on the screen contents. Syntax: declarations: integer menu_id integer code call ft_menu_$destroy (menu_id, code); Arguments: menu_id menu identifier returned by ft_menu_$create or ft_menu_$retrieve. (Input/Output) Set to an invalid value on return to prevent the old menu_id from being accidentally used. code return code. (Output) :Entry: display: 03/19/85 ft_menu_$display Function: Invoked to display a menu in a given window. Syntax: declarations: integer window_id integer menu_id integer code call ft_menu_$display (window_id, menu_id, code) Arguments: window_id a window identifier returned by ft_window_$create. (Input) If usage_mode = 0 this argument will be ignored (see ft_menu_$init2). menu_id menu identifier returned when the menu object was created or retrieved. (Input) code return code. (Output) :Entry: get_choice: 03/19/85 ft_menu_$get_choice Function: Returns the choice made by the user, i.e., an integer representing either the menu item chosen or the function key (or its equivalent escape sequence) entered. Syntax: declarations: character*n1 function_key_info integer window_id integer menu_id integer fkeys integer selection integer code call ft_menu_$get_choice (window_id, menu_id, function_key_info, fkeys, selection, code) Arguments: window_id a window identifier returned by ft_window_$create. (Input) If usage_mode = 0 this argument will be ignored. (see ft_menu_$init2) menu_id menu identifier returned by ft_menu_$create or ft_menu_$retrieve. (Input) function_key_info a character variable (n1 as required) used to specify the role of function keys (if they exist for the terminal being used) or an equivalent set of escape sequences if the terminal does not have function keys or not the function keys required by the application. (Input) The objective is to let the application use the terminal's function keys if possible, else specify key sequences to be used to simulate function keys. Each character in the string corresponds to one function key. If the character is a space, then it is not relevant if the corresponding function key exists or not. If the character is not a space, that character will be used to simulate a function key if the terminal does not have function keys. If the terminal does not have a function key for every non-space character in the string, then function keys will be simulated. Thus, the string " ?p q" means that the caller does not care whether the terminal has function key 0 or 3, but the caller does wish to use function keys 1,2, and 4. If any of these 3 function keys is not present on the terminal, then esc-? will substitute for F1, esc-p will substitute for F2, and esc-q will substitute for F4. fkeys if fkeys = 1 user entered a function key or escape sequence if fkeys = 0 user selected an option (Output) selection is an integer representing the choice made by the user. (Output) If the user has chosen an option, it is a number between 1 and the highest defined option. If the user has entered a function key, or escape sequence simulating a function key, it is the number associated with the function key. code return code. (Output) :Entry: init1: init2: 03/19/85 ft_menu_$init1, ft_menu_$init2 Function: These must be the first calls made to the menu manager. They set up the necessary environment for the menu application and return information concerning the user i/o window. Syntax: declarations: integer code integer usage_mode call ft_menu_$init1 () call ft_menu_$init2 (usage_mode,user_window_lines,user_window_columns, user_window_id,code) Arguments: usage_mode usage_mode = 0 means that the caller does not wish to do any window management at all. (Input) When he/she wishes to display a menu, the window required will be automatically created. This means that the application will operate in a two window mode, the window containing the menu, and the user_io window. Both windows will be managed automatically for the user. If the user specifies this mode, all calls to the ft_window_ subroutine will be ignored and will return an appropriate error code. All calls to the ft_menu_ subroutine that require a window identifier will ignore the user provided window_id. usage_mode = 1 means that the user wishes to define the number and characteristics of the windows to be used in the application. Thus, calls to ft_window_ will be supported and, for the entry points of ft_menu_ that require a window identifier, the caller must use a legal window_id (returned by ft_window_$create). user_window_lines the number of lines (rows) in the user i/o window at the time the user invokes ft_menu_$init (which must be the first call to the menu manager in the application). (Output) Undefined if usage_mode = 0. user_window_columns the number of columns of the user i/o window when ft_menu_$init invoked. (Output) Undefined if usage_mode = 0. user_window_id window identifier of the user i/o window. (Output) Undefined if usage_mode = 0. code return code. (Output) :Entry: list: 03/19/85 ft_menu_$list Function: Used to list the menu object(s) stored in value segment. The names selected are those that match a user provided string. Syntax: declarations: character*168 dir_name character*32 names_array(m1) character*32 entry_name character*32 match_string integer no_of_matches integer code call ft_menu_$list (dir_name, entry_name, match_string, no_of_matches, names_array, code) Arguments: dir_name pathname of directory containing the menu object. (Input) entry_name entry name of value segment containing the menu object. (Input) The suffix "value" need not be specified. match_string a character variable that is to be used as the selection criteria to determine what menu object, if any, is contained in the specified value segment that match (or contain) this string. (Input) If set to space(s), all names returned. no_of_matches the number of matches found. (Output) If none, then is is 0. names_array an array, of extent m1. (Output) The user should insure that m1 is sufficiently large to contain all matches that may be found. Contains the names of all menu objects, in the specified value segment, that match the character string match_string. code return code. (Output) :Entry: retrieve: 03/19/85 ft_menu_$retrieve Function: Used to retrieve a menu object previously stored via the ft_menu_$store. Once retrieved, the user can reference the menu object via the menu identifier (menu_id). Syntax: declarations: character*168 dir_name character*32 entry_name character*32 menu_name integer menu_id integer code call ft_menu_$retrieve (dir_name, entry_name, menu_name, menu_id, code) Arguments: dir_name pathname of the directory containing the menu object. (Input) entry_name entry name of value segment containing menu object. (Input) The suffix "value" need not be specified. menu_name name of the menu object used when the object was stored. (Input) menu_id is the menu id returned by the call. (Output) It is used as the menu object identifier. code return code. (Output) :Entry: store: 03/19/85 ft_menu_$store Function: Used to store a menu object in a specified value segment. Syntax: declarations: character*168 dir_name character*32 entry_name character*32 menu_name integer create_seg integer menu_id integer code call ft_menu_$store (dir_name,entry_name, menu_name, create_seg, menu_id, code) Arguments: dir_name pathname of directory into which the menu object is to be placed. (Input) entry_name entry name of value segment into which the menu object is to be placed. (Input) The suffix "value" need not be specified. menu_name it is the name to be assigned to the stored menu object. (Input) create_seg create_seg = 0 means do not store if value segment identified by entry_name does not already exist. (Input) create_seg = 1 means create value segment, if it does not already exist, and store menu object in it. menu_id it is the menu object identifier returned when ft_menu_$create or ft_menu_$retrieve was called. (Input) code return code. (Output) :Entry: terminate: 03/19/85 ft_menu_$terminate Function: Must be the last call to the menu manager in the menu application. It will remove the special environment created by ft_menu_$init1 and ft_menu_$init2. Syntax: declarations: none call ft_menu_$terminate () ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved