1 03/19/85 cb_menu_
2
3
4 The cb_menu_ subroutine allows a COBOL program to use the Multics menu
5 facility menu_. Through cb_menu_ a COBOL program may create a menu
6 object, display the menu, and get a user-entered selection from a menu.
7 Once a menu object has been created, the COBOL program can use this
8 menu object by referencing it via a menu-id returned to the caller when
9 the menu object was created or when a stored menu object was retrieved.
10
11 The functionality available is provided through the various entry
12 points described below.
13
14
15 Entry points in cb_menu_:
16 List is generated by the help command
17
18
19 :Entry: create: 03/19/85 cb_menu_$create
20
21
22 Function: Utilized to create a menu-object. Returns a menu-id which
23 may be subsequently used by other entry points.
24
25
26 Syntax:
27 declarations:
28 01 choices-table.
29 02 choices PIC Xn1 OCCURS m1 TIMES.
30 01 headers-table.
31 02 headers PIC Xn2 OCCURS m2 TIMES.
32 01 trailers-table.
33 02 trailers PIC Xn3 OCCURS m3 TIMES.
34 01 keys-table.
35 02 keys PIC X1 OCCURS m4 TIMES.
36 01 menu-format.
37 02 menu_version USAGE IS COMP-6
38 02 constraints USAGE IS COMP-6
39 03 max-width.
40 03 max-height.
41
42
43 02 no-of-columns USAGE IS COMP-6.
44 02 flags.
45 03 center-headers PIC 91.
46 03 center-trailers PIC 91.
47 02 pad-char PIC X1.
48
49 01 menu-needs USAGE IS COMP-6.
50 02 lines-needed.
51 02 width-needed.
52 02 no-of-options.
53
54 77 menu-id USAGE IS COMP-6.
55 77 ret-code USAGE IS COMP-6.
56 call "cb_menu_$create" USING choices-table, headers-table,
57 trailers-table, menu-format, keys-table, menu-needs, menu-id,
58 ret-code.
59
60
61 Arguments:
62 choices-table
63 is a table of elementary data items which are the text of the
64 options that the user wishes to display in the menu. n1 is the
65 length, in characters, of the longest character string comprising
66 the text of an option. m1 is the extent of the table, i.e., the
67 number of options in the menu being described. This table must be
68 at least of extent 1.
69 headers-table
70 is a table of elementary data items to be displayed at the top of
71 the menu. Input n2 is the length, in characters, of the longest
72 header specified. m2 is the extent of the table, i.e., the number
73 of headers lines desired. At least one header must be specified
74 if the first header is set to spaces no headers will be used.
75
76
77 trailers-table
78 is an table of trailers displayed immediately below the menu.
79 Input n3, m3, are analogous to n2, m2 respectively.
80 menu-format
81 is a group item defining the format of the menu being created.
82 Input In the COBOL program the caller is responsible for
83 setting the following elementary data items:
84 menu-version the version number of the menu facility.
85 only version 1 is currently defined
86 max-width maximum width of the window on which the
87 menu is to be displayed.
88 max-height maximum height of window on which the
89 menu is to be displayed.
90 no-of-columns number of columns to be used to display
91 the options.
92 center-headers 0 or 1; 0 = no, 1 = yes.
93 center-trailers 0 or 1 same as center-headers
94
95
96 keys-table
97 is a table maximum value of m4 is 61 that identifies the keystroke
98 to be associated with each choice. Input This table must be at
99 least as long as the number of choices in the menu. Each element in
100 the table must be unique.
101 menu-needs
102 a group item that contains menu related information on successful
103 execution of call. Output
104 Returned information:
105 lines-needed the number of lines required
106 to display the menu.
107 width-needed the number of columns needed
108 to display the menu.
109 no-of-options the number of options defined
110 in the menu.
111
112
113 menu-id
114 the menu-object identifier i.e. it is the menu object "pointer".
115 Output It must not be altered in any way by the application
116 program.
117 ret-code
118 return code. Output
119
120
121 :Entry: delete: 03/19/85 cb_menu_$delete
122
123
124 Function: Deletes a menu object from a given value segment.
125
126
127 Syntax:
128 declarations:
129 77 dir-name PIC X168.
130 77 entry-name PIC X32.
131 77 name-of-menu PIC X32.
132 77 ret-code USAGE IS COMP-6.
133 call "cb_menu_$delete" USING dir-name, entry-name, name-of-menu,
134 ret-code.
135
136
137 Arguments:
138 dir-name
139 pathname of the directory containing the menu object. Input
140 entry-name
141 entry name of value segment containing the menu object. Input The
142 suffix "value" need not be specified.
143 name-of-menu
144 name used to identify the menu object when the menu object was
145 stored. Input
146 ret-code
147 return code. Output
148
149
150 :Entry: describe: 03/19/85 cb_menu_$describe
151
152
153 Function: Returns information about a menu object. It returns the
154 number of options in the menu, the number of lines and number of
155 columns required to display the menu. It is primarily used to
156 determine if the menu can be displayed in a given window.
157
158
159 Syntax:
160 declarations:
161 01 menu-needs USAGE IS COMP-6.
162 02 lines-needed.
163 02 width-needed.
164 02 no-of-options.
165
166 77 menu-id USAGE IS COMP-6.
167 77 ret-code USAGE IS COMP-6.
168 call "cb_menu_$describe" USING menu-id, menu-needs, ret-code.
169
170
171 Arguments:
172 menu-id
173 the menu identifier returned by cb_menu_$create or
174 cb_menu_$retrieve in cases where the menu object has been stored.
175 Input
176 menu-needs
177 a group item that contains menu related information on successful
178 execution of call. Output
179 Returned information:
180 lines-needed the number of lines needed to
181 display the menu.
182 width-needed the number of columns needed
183 to display the menu.
184 no-of-option the number of options defined
185 in the menu.
186 ret-code
187 return code. Output
188
189
190 :Entry: destroy: 03/19/85 cb_menu_$destroy
191
192
193 Function: Used to free storage of a menu not to be confused with
194 cb_menu_$delete which is used to delete the menu object from a value
195 segment. Destroying the menu has no effect on the screen contents.
196
197
198 Syntax:
199 declarations:
200 77 menu-id USAGE IS COMP-6.
201 77 ret-code USAGE IS COMP-6.
202 call "cb_menu_$destroy" USING menu-id, ret-code.
203
204
205
206 Arguments:
207 menu-id
208 menu identifier returned by cb_menu_$create or cb_menu_$retrieve.
209 Input/Output If usage-mode is 0 see cb_menu_$init2 this operand
210 will be ignored. Set to an invalid value on return to prevent the
211 old menu-id from being accidentally used.
212 ret-code
213 return code. Output See Appendix B.
214
215
216 :Entry: display: 03/19/85 cb_menu_$display
217
218
219 Function: Invoked to display a menu in a given window.
220
221
222 Syntax
223 declarations:
224 77 window-id USAGE IS COMP-6.
225 77 menu-id USAGE IS COMP-6.
226 77 ret-code USAGE IS COMP-6.
227 call "cb_menu_$display" USING window-id, menu-id, ret-code.
228
229
230
231 Arguments:
232 window-id
233 a window identifier returned by cb_window_$create entry point.
234 Input If usage-mode = 0 this operand will be ignored see
235 cb_menu_$init2.
236 menu-id
237 menu identifier returned when the menu object was created or
238 retrieved. Input
239 ret-code
240 return code. Output
241
242
243 :Entry: get_choice: 03/19/85 cb_menu_$get_choice
244
245
246 Function: Returns the choice made by the user, i.e., a number
247 representing either the menu item chosen or the function key or its
248 equivalent escape sequence entered.
249
250
251 Syntax:
252 declarations:
253 77 function-key-info PIC Xn1.
254 77 window-id USAGE IS COMP-6.
255 77 menu-id USAGE IS COMP-6.
256 77 fkeys USAGE IS COMP-6.
257 77 selection USAGE IS COMP-6.
258 77 ret-code USAGE IS COMP-6.
259 call "cb_menu_$get_choice" USING window-id, menu-id,
260 function-key-info, fkeys, selection, ret-code.
261
262
263 Arguments:
264 window-id
265 a window identifier returned by the cb_window_$create entry point.
266 Input If usage-mode = 0 this operand will be ignored see
267 cb_menu_$init2.
268 menu-id
269 menu identifier returned by cb_menu_$create or cb_menu_$retrive.
270 Input
271
272
273 function-key-info
274 a character elementary data item n1 as required used to specify
275 the role of function keys if they exist for the terminal being
276 used or an equivalent set of escape sequences if the terminal does
277 not have function keys or not the function keys required by the
278 application. Input The objective is to let the application use
279 the terminal's function keys if possible, else specify key sequences
280 to be used to simulate function keys. Each character in the string
281 corresponds to one function key. If the character is a space, then
282 it is not relevant if the corresponding function key exists or not.
283 If the character is not a space, that character will be used to
284 simulate a function key if the terminal does not have function keys.
285 If the terminal does not have a function key for every non-space
286 character in the string, then function keys will be simulated.
287 Thus, the string " ?p q" means that the caller does not care whether
288 the terminal has function key 0 or 3, but the caller does wish to
289 use function keys 1,2, and 4. If any of these 3 function keys is
290 not present on the terminal, then esc-? will substitute for F1,
291 esc-p will substitute for F2, and esc-q will substitute for F4.
292
293
294 fkeys
295 fkeys = 1 user entered a function key or escape sequence fkeys = 0
296 user selected an option Output
297 selection
298 is a number representing the choice made by the user. Output If
299 the user has chosen an option, it is a number between 1 and the
300 highest defined option. If the user has entered a function key, or
301 escape sequence simulating a function key, it is the number
302 associated with the function key.
303 ret-code
304 return code. Output See Appendix B.
305
306
307 :Entry: init1: init2: 03/19/85 cb_menu_$init1, cb_menu_$init2
308
309
310 Function: These must be the first calls made to the menu manager.
311 They set up the necessary environment for the menu application and
312 return information concerning the user I/O window.
313
314
315 Syntax:
316 declarations:
317 inter code
318 integer usage-mode
319 call cb_menu_$init1
320 call cb_menu_$init2 usage-mode user-window-lines
321 user-window-columns user-window-id ret-code
322
323
324 Arguments:
325 usage-mode
326 usage-mode = 0 means that the caller does not wish to do any
327 explicit window management. Input When he/she wishes to display a
328 menu, the window required will be automatically created. This means
329 that the application will operate in a two window mode, the window
330 containing the menu, and the user_io window. Both windows will be
331 managed automatically for the user. If the user specifies this
332 mode, all calls to the cb_window_ subroutine will be ignored and
333 will return an appropriate error code. See Error Code Handling,
334 below. All calls to the cb_menu_ subroutine that require a window
335 identifier will ignore the user provided window-id.
336 usage-mode = 1 means that the user wishes to define the number and
337 characteristics of the windows to be used in the application. Thus,
338 calls to cb_window_ will be supported and, for the entry points of
339 cb_menu_ that require a window identifier, the caller must use a
340 legal window-id returned by cb_window_$create.
341
342
343 user-window-lines
344 the number of physical lines rows of the user i/o window when
345 cb_menu_$init is called which must be the first cb_menu_ call in
346 the application. Undefined if usage-mode = 0. Output
347 user-window-columns
348 the number of columns of the user i/o window at time that
349 cb_menu_$init is called see immediately above. Output Undefined
350 if usage-mode = 0.
351 user-window-id
352 window identifier of the user i/o window. Output Undefined if
353 usage-mode = 0.
354 ret-code
355 return code. Output
356
357
358 :Entry: list: 03/19/85 cb_menu_$list
359
360
361 Function: Used to list the menu objects, stored in value segment.
362 The menu objects selected are those that match the string input by the
363 caller.
364
365
366 Syntax:
367 declarations:
368 01 matched-names.
369 02 no-of-matches USAGE IS COMP-6.
370 02 menu-names PIC X32 OCCURS m1 TIMES.
371
372 77 dir-name PIC X168.
373 77 entry-name PIC X32.
374 77 match-string PIC X32.
375 77 ret-code USAGE IS COMP-6.
376 call "cb_menu_$list" USING dir-name, entry-name, match-string,
377 matched-names, ret-code.
378
379
380 Arguments:
381 dir-name
382 pathname of directory containing the menu object. Input
383 entry-name
384 entry name of value segment containing the menu object. Input The
385 suffix "value" need not be specified.
386 match-string
387 a character elementary data item that is to be used as the selection
388 criteria for determining what menu object, if any, is contained in
389 the specified value segment that match or contain this string.
390 Input
391
392
393 no-of-matches
394 the number of matches found. Output If none, then it is 0.
395 menu-names
396 On return, contains the names of all menu objects, in the specified
397 value segment, that match the character string match-string.
398 Output Note, if m1 is not large enough to contain all the names,
399 only m1 names will be returned.
400 ret-code
401 return code. Output
402
403
404 :Entry: retrieve: 03/19/85 cb_menu_$retrieve
405
406
407 Function: Used to retrieve a menu object previously stored via the
408 cb_menu_$store subroutine.
409
410
411 Syntax:
412 declarations:
413 77 dir-name PIC X168.
414 77 entry-name PIC X32.
415 77 name-of-menu PIC X32.
416 77 menu-id USAGE IS COMP-6.
417 77 ret-code USAGE IS COMP-6.
418 call "cb_menu_$retrieve" USING dir-name, entry-name, name-of-menu,
419 menu-id, ret-code.
420
421
422 Arguments:
423 dir-name
424 pathname of the directory containing the menu object. Input
425 entry-name
426 entry name of value segment containing menu object. Input The
427 suffix "value" need not be specified.
428 name-of-menu
429 name of the menu object used when the object was stored. Input
430 menu-id
431 is the menu id returned by the call. Output
432 ret-code
433 return code. Output
434
435
436 :Entry: store: 03/19/85 cb_menu_$store
437
438
439 Function: Used to store a menu object in a specified value segment.
440
441
442 Syntax:
443 declarations:
444 77 dir-name PIC X168.
445 77 entry-name PIC X32.
446 77 name-of-menu PIC X32.
447 77 create-seg USAGE IS COMP-6.
448 77 menu-id USAGE IS COMP-6.
449 77 ret-code USAGE IS COMP-6.
450 call "cb_menu_$store" USING dir-name, entry-name, name-of-menu,
451 create-seg, menu-id, ret-code.
452
453
454 Arguments:
455 dir-name
456 pathname of directory into which the menu object is to be placed.
457 Input
458 entry-name
459 entry name of value segment into which menu object is to be placed.
460 Input The suffix "value" need not be specified.
461 name-of-menu
462 is the name to be assigned to the stored menu object. Input
463
464
465 create-seg
466 create-seg = 0 means do not store if value segment identified by
467 entry-name does not already exist. Input create-seg = 1 means
468 create value segment, if it does not already exist, and store menu
469 object in it.
470 menu-id
471 is the menu object identifier returned by cb_menu_$create or
472 cb_menu_$retrieve. Input
473 ret-code
474 return code. Output
475
476
477 :Entry: terminate: 03/19/85 cb_menu_$terminate
478
479
480 Function: Must be the last call to the menu manager in the menu
481 application.
482
483
484 Syntax:
485 declarations: none
486 call "cb_menu_$terminate".
487
488
489 Arguments:
490 There are no arguments.