03/19/85 menu_ The menu_ subroutine provides menu display and selection services. It can display a menu in a window and get a selection from the user. The entries work with menu objects. A menu object is a pointer to an internal description of a menu. The caller is expected to preserve the pointer, and to perform no operation on it other than comparison with the null pointer or with another menu object, except through the menu_ subroutine. Declarations for the entries and the associated structures are in the include file menu_dcls.incl.pl1. Entry points in menu_: (List is generated by the help command) :Entry: create: 03/19/85 menu_$create Function: This entry creates a menu object given its description. The menu data structure is allocated in a caller supplied area, and may be saved across processes by calling menu_$store. A pointer to the new menu is returned, also with the minimum size of a window to hold the menu. Syntax: declare menu_$create entry ((*) char (*) varying, (*) char (*) varying, (*) char (*) varying, ptr, (*) char (1) unal, ptr, ptr, ptr, fixed bin (35)); call menu_$create (choices, headers, trailers, format_ptr, keys, area_ptr, needs_ptr, menu, code); Arguments: choices is an array of the names of the options. (Input) If the maximum number of choices is exceeded, the code menu_et_$too_many_options is returned. The current maximum is 61. headers is an array of headers. (Input) If the length of the first header is zero, then no headers are used. This allows the caller to specify no headers, without resorting to a zero-extent array, which is invalid PL/I. trailers is an array of trailers. (Input) As for headers, a zero-length first trailer means that no trailers are displayed. format_ptr points to a structure, menu_format, that controls formatting of the menu. (Input) This structure is declared in menu_dcls.incl.pl1. keys is an array specifying the keystroke for each option. (Input) The array must have at least as many elements as the array of option names. If not, the error code menu_et_$too_few_keys is returned. It may have more keys than choices. Each item of the array must be unique, or menu_et_$keys_not_unique is returned. If the valid keys (the keys for which there are choices) are either all upper case or all lower case, menu_$get_choice will treat upper and lower case letters identically. area_ptr is a pointer to an area where the menu description is allocated. (Input) If the area is not large enough, the area condition is signalled. If this pointer is null, the system free area is used. needs_ptr points to the menu_requirements structure giving requirements to display the menu. (Input) The caller supplies this structure and fills in the version number menu_requirements_version_1, the remaining members are output from this entry. menu is a newly created menu object. (Output) code is a standard system error code, or an error code from menu_et_. (Output) :Entry: delete: 03/19/85 menu_$delete Function: This entry deletes a menu object from a specified value segment. Syntax: declare menu_$delete entry (char (*), char (*), char (*), fixed bin (35)); call menu_$delete (dirname, entryname, menu_name, code); Arguments: dirname is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) It must have the value suffix. menu_name is the name that was assigned to the menu when it was stored (see the description of menu_$store). (Input) code is a standard system error code. (Output) :Entry: describe: 03/19/85 menu_$describe Function: This entry fills in a caller-supplied data structure describing some of the aspects of a menu object. The caller can use this to ensure a window is sufficiently large to hold a menu. Syntax: declare menu_$describe entry (ptr, ptr, fixed bin (35)); call menu_$describe (menu, needs_ptr, code); Arguments: menu is the menu object to describe. (Input) needs_ptr points to a structure declared like menu_requirements. (Input) The caller fills in the version to be menu_requirements_version_1, and the remaining members are filled in by this entry. code is a standard system error code. (Output) :Entry: destroy: 03/19/85 menu_$destroy Function: This entry is used to delete a menu object. The caller uses this to free storage of a menu, since the representation of a menu is not known outside the menu_ subroutine. This entry has no effect on screen contents or on stored menus. Syntax: declare menu_$destroy entry (ptr, fixed bin (35)); call menu_$destroy (menu, code); Arguments: menu is the menu object to destroy. (Input) code is a standard system error code. (Output) :Entry: display: 03/19/85 menu_$display Function: This entry displays a menu object on a supplied window. Syntax: declare menu_$display entry (ptr, ptr, fixed bin (35)); call menu_$display (window, menu, code); Arguments: window is a pointer to an IOCB for an I/O switch attached through window_io_. (Input) This window must be large enough to hold the menu. A menu window should be used ONLY for menu I/O, if redisplay optimizations are desired. menu is the menu object to be displayed. (Input) code is a standard system error code. (Output) :Entry: get_choice: 03/19/85 menu_$get_choice Function: This entry returns a choice from a menu. The menu is assumed to be already displayed in the window. Syntax: declare menu_$get_choice entry (ptr, ptr, ptr, bit (1) aligned, fixed bin, fixed bin (35)); call menu_$get_choice (window, menu, function_key_info, fkey, selection, code); Arguments: window is a pointer to the IOCB for the I/O switch used to display the menu. (Input) menu is the menu object on display in the window. (Input) function_key_info is a pointer to a data structure describing the function keys available on the terminal. (Input) This data structure is obtained by the caller from the ttt_info_$function_key_data subroutine. If this pointer is null, no function keys are used. fkey returns a value of "1"b if a function key was hit instead of a menu selection. (Output) selection gives the option number or function key number chosen by the user. For an option, it is a number between 1 and the highest defined option, inclusive. For a function key, it is the number of the function key. code is a standard system error code. (Output) Notes: If a terminal has no function keys, the caller can define input escape sequences for function keys. These may be chosen to have mnemonic value to the end user. For example, if Function Key 1 is used to print a help file, the input sequence ESC h could replace it. In some applications, this will be easier for the end user to remember than an unlabelled function key. The caller can define these keys by allocating and filling in the same function key structure normally returned by the ttt_info_ subroutine. If a key is hit that is not one of the option keys and is not a function key, then the terminal bell is rung. :Entry: list: 03/19/85 menu_$list Function: This entry lists the menu objects stored in a specified value segment. Syntax: declare menu_$list entry (char (*), char (*), char (*), ptr, fixed bin, ptr, fixed bin (35)); call menu_$list (dirname, entryname, menu_starname, area_ptr, menu_list_info_version, menu_list_info_ptr, code); Arguments: dirname is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) It must have the value suffix. menu_starname is matched against the names of the menus stored in the segment. (Input) Only names that match menu_starname are returned. (see the description of menu_$store). area_ptr is a pointer to an area in which to allocate the structure containing the menu names. (Input) If it is null, the system free area is used. menu_list_info_version is the version of the menu_list_info structure that the caller expects. (Input) It must be a supported menu_list_info structure version. The only supported version is menu_list_info_version_1. menu_list_info_ptr is a pointer to the menu_list_info structure, declared in menu_dcls.incl.pl1. (Output) code is a standard system error code. (Output) :Entry: retrieve: 03/19/85 menu_$retrieve Function: This entry retrieves a menu from a specified segment. The segment must be a value segment. The menu data structure is allocated in a caller-supplied area. The menu information is copied from the menu object stored in the segment into the newly allocated structure. Syntax: declare menu_$retrieve entry (char (*), char (*), char (*), ptr, ptr, fixed bin (35)); call menu_$retrieve (dirname, entryname, menu_name, area_ptr, menu_ptr, code); Arguments: dirname is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) It must have the value suffix. menu_name is the name that was assigned to the menu when it was stored (see the description of menu_$store). (Input) area_ptr is a pointer to an area where the menu object is allocated. (Input) If this argument is null, the system free area is used. If the area is not large enough, the area condition is signalled. menu_ptr is a pointer to the menu object that is retrieved from the segment. (Output) code is a standard system error code. (Output) :Entry: store: 03/19/85 menu_$store Function: This entry stores a menu object in a specified segment. The specified segment must be a value segment. Syntax: declare menu_$store entry (char (*), char (*), char (*), bit(1) aligned, ptr, fixed bin (35)); call menu_$store (dirname, entryname, menu_name, create_sw, menu_ptr, code); Arguments: dirname is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) It must have the value suffix. menu_name is a name to be assigned to the menu. (Input) create_sw determines whether or not the segment is created if it does not already exist. If the segment does not exist, a value of "1"b will cause it to be created. (Input) menu_ptr is a pointer to the menu object that is to be stored in the segment. (Input) code is a standard system error code. (Output) ----------------------------------------------------------- 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