03/19/85 cb_menu_ The cb_menu_ subroutine allows a COBOL program to use the Multics menu facility (menu_). Through cb_menu_ a COBOL 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 COBOL 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 described below. Entry points in cb_menu_: (List is generated by the help command) :Entry: create: 03/19/85 cb_menu_$create Function: Utilized to create a menu-object. Returns a menu-id which may be subsequently used by other entry points. Syntax: declarations: 01 choices-table. 02 choices PIC X(n1) OCCURS (m1) TIMES. 01 headers-table. 02 headers PIC X(n2) OCCURS (m2) TIMES. 01 trailers-table. 02 trailers PIC X(n3) OCCURS (m3) TIMES. 01 keys-table. 02 keys PIC X(1) OCCURS (m4) TIMES. 01 menu-format. 02 menu_version USAGE IS COMP-6 02 constraints USAGE IS COMP-6 03 max-width. 03 max-height. 02 no-of-columns USAGE IS COMP-6. 02 flags. 03 center-headers PIC 9(1). 03 center-trailers PIC 9(1). 02 pad-char PIC X(1). 01 menu-needs USAGE IS COMP-6. 02 lines-needed. 02 width-needed. 02 no-of-options. 77 menu-id USAGE IS COMP-6. 77 ret-code USAGE IS COMP-6. call "cb_menu_$create" USING choices-table, headers-table, trailers-table, menu-format, keys-table, menu-needs, menu-id, ret-code. Arguments: choices-table is a table of elementary data items which are the text of the options that the user wishes to display in the menu. n1 is the length, in characters, of the longest character string comprising the text of an option. m1 is the extent of the table, i.e., the number of options in the menu being described. This table must be at least of extent 1. headers-table is a table of elementary data items 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 table, i.e., the number of headers (lines) desired. At least one header must be specified (if the first header is set to space(s), no headers will be used). trailers-table is an table of trailers (displayed immediately below the menu). (Input) n3, m3, are analogous to n2, m2 respectively. menu-format is a group item defining the format of the menu being created. (Input) In the COBOL program the caller is responsible for setting the following elementary data items: menu-version the version number of the menu facility. (only version 1 is currently defined) max-width maximum width of the window on which the menu is to be displayed. max-height maximum height of window on which the menu is to be displayed. no-of-columns number of columns to be used to display the options. center-headers 0 or 1; 0 = no, 1 = yes. center-trailers 0 or 1 (same as center-headers) keys-table is a table (maximum value of m4 is 61) that identifies the keystroke to be associated with each choice. (Input) This table must be at least as long as the number of choices in the menu. Each element in the table must be unique. menu-needs a group item that contains menu related information on successful execution of call. (Output) Returned information: lines-needed the number of lines required to display the menu. width-needed the number of columns needed to display the menu. no-of-options the number of options defined in the menu. menu-id the menu-object identifier (i.e., it is the menu object "pointer".) (Output) It must not be altered in any way by the application program. ret-code return code. (Output) :Entry: delete: 03/19/85 cb_menu_$delete Function: Deletes a menu object from a given value segment. Syntax: declarations: 77 dir-name PIC X(168). 77 entry-name PIC X(32). 77 name-of-menu PIC X(32). 77 ret-code USAGE IS COMP-6. call "cb_menu_$delete" USING dir-name, entry-name, name-of-menu, ret-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. name-of-menu name used to identify the menu object when the menu object was stored. (Input) ret-code return code. (Output) :Entry: describe: 03/19/85 cb_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: 01 menu-needs USAGE IS COMP-6. 02 lines-needed. 02 width-needed. 02 no-of-options. 77 menu-id USAGE IS COMP-6. 77 ret-code USAGE IS COMP-6. call "cb_menu_$describe" USING menu-id, menu-needs, ret-code. Arguments: menu-id the menu identifier returned by cb_menu_$create (or cb_menu_$retrieve in cases where the menu object has been stored). (Input) menu-needs a group item that contains menu related information on successful execution of call. (Output) Returned information: lines-needed the number of lines needed to display the menu. width-needed the number of columns needed to display the menu. no-of-option the number of options defined in the menu. ret-code return code. (Output) :Entry: destroy: 03/19/85 cb_menu_$destroy Function: Used to free storage of a menu (not to be confused with cb_menu_$delete, which is used to delete the menu object from a value segment). Destroying the menu has no effect on the screen contents. Syntax: declarations: 77 menu-id USAGE IS COMP-6. 77 ret-code USAGE IS COMP-6. call "cb_menu_$destroy" USING menu-id, ret-code. Arguments: menu-id menu identifier returned by cb_menu_$create or cb_menu_$retrieve. (Input/Output) (If usage-mode is 0 (see cb_menu_$init2) this operand will be ignored.) Set to an invalid value on return to prevent the old menu-id from being accidentally used. ret-code return code. (Output) (See Appendix B.) :Entry: display: 03/19/85 cb_menu_$display Function: Invoked to display a menu in a given window. Syntax declarations: 77 window-id USAGE IS COMP-6. 77 menu-id USAGE IS COMP-6. 77 ret-code USAGE IS COMP-6. call "cb_menu_$display" USING window-id, menu-id, ret-code. Arguments: window-id a window identifier returned by cb_window_$create entry point. (Input) If usage-mode = 0 this operand will be ignored (see cb_menu_$init2). menu-id menu identifier returned when the menu object was created or retrieved. (Input) ret-code return code. (Output) :Entry: get_choice: 03/19/85 cb_menu_$get_choice Function: Returns the choice made by the user, i.e., a number representing either the menu item chosen or the function key (or its equivalent escape sequence) entered. Syntax: declarations: 77 function-key-info PIC X(n1). 77 window-id USAGE IS COMP-6. 77 menu-id USAGE IS COMP-6. 77 fkeys USAGE IS COMP-6. 77 selection USAGE IS COMP-6. 77 ret-code USAGE IS COMP-6. call "cb_menu_$get_choice" USING window-id, menu-id, function-key-info, fkeys, selection, ret-code. Arguments: window-id a window identifier returned by the cb_window_$create entry point. (Input) If usage-mode = 0 this operand will be ignored (see cb_menu_$init2). menu-id menu identifier returned by cb_menu_$create or cb_menu_$retrive. (Input) function-key-info a character elementary data item (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 fkeys = 1 user entered a function key or escape sequence fkeys = 0 user selected an option (Output) selection is a number 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. ret-code return code. (Output) (See Appendix B.) :Entry: init1: init2: 03/19/85 cb_menu_$init1, cb_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: inter code integer usage-mode call cb_menu_$init1 call cb_menu_$init2 (usage-mode, user-window-lines, user-window-columns, user-window-id, ret-code) Arguments: usage-mode usage-mode = 0 means that the caller does not wish to do any explicit window management. (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 cb_window_ subroutine will be ignored and will return an appropriate error code. See Error Code Handling, below. All calls to the cb_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 cb_window_ will be supported and, for the entry points of cb_menu_ that require a window identifier, the caller must use a legal window-id (returned by cb_window_$create). user-window-lines the number of physical lines (rows) of the user i/o window when cb_menu_$init is called (which must be the first cb_menu_ call in the application.) Undefined if usage-mode = 0. (Output) user-window-columns the number of columns of the user i/o window at time that cb_menu_$init is called (see immediately above). (Output) Undefined if usage-mode = 0. user-window-id window identifier of the user i/o window. (Output) Undefined if usage-mode = 0. ret-code return code. (Output) :Entry: list: 03/19/85 cb_menu_$list Function: Used to list the menu object(s), stored in value segment. The menu objects selected are those that match the string input by the caller. Syntax: declarations: 01 matched-names. 02 no-of-matches USAGE IS COMP-6. 02 menu-names PIC X(32) OCCURS (m1) TIMES. 77 dir-name PIC X(168). 77 entry-name PIC X(32). 77 match-string PIC X(32). 77 ret-code USAGE IS COMP-6. call "cb_menu_$list" USING dir-name, entry-name, match-string, matched-names, ret-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 elementary data item that is to be used as the selection criteria for determining what menu object, if any, is contained in the specified value segment that match (or contain) this string. (Input) no-of-matches the number of matches found. (Output) If none, then it is 0. menu-names On return, contains the names of all menu objects, in the specified value segment, that match the character string match-string. (Output) Note, if m1 is not large enough to contain all the names, only m1 names will be returned. ret-code return code. (Output) :Entry: retrieve: 03/19/85 cb_menu_$retrieve Function: Used to retrieve a menu object previously stored via the cb_menu_$store subroutine. Syntax: declarations: 77 dir-name PIC X(168). 77 entry-name PIC X(32). 77 name-of-menu PIC X(32). 77 menu-id USAGE IS COMP-6. 77 ret-code USAGE IS COMP-6. call "cb_menu_$retrieve" USING dir-name, entry-name, name-of-menu, menu-id, ret-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. name-of-menu name of the menu object used when the object was stored. (Input) menu-id is the menu id returned by the call. (Output) ret-code return code. (Output) :Entry: store: 03/19/85 cb_menu_$store Function: Used to store a menu object in a specified value segment. Syntax: declarations: 77 dir-name PIC X(168). 77 entry-name PIC X(32). 77 name-of-menu PIC X(32). 77 create-seg USAGE IS COMP-6. 77 menu-id USAGE IS COMP-6. 77 ret-code USAGE IS COMP-6. call "cb_menu_$store" USING dir-name, entry-name, name-of-menu, create-seg, menu-id, ret-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 menu object is to be placed. (Input) The suffix "value" need not be specified. name-of-menu 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 is the menu object identifier returned by cb_menu_$create or cb_menu_$retrieve. (Input) ret-code return code. (Output) :Entry: terminate: 03/19/85 cb_menu_$terminate Function: Must be the last call to the menu manager in the menu application. Syntax: declarations: none call "cb_menu_$terminate". Arguments: There are no arguments. ----------------------------------------------------------- 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