1 03/19/85  menu_
  2 
  3 
  4 The menu_ subroutine provides menu display and selection services.  It
  5 can display a menu in a window and get a selection from the user.  The
  6 entries work with menu objects.  A menu object is a pointer to an
  7 internal description of a menu.  The caller is expected to preserve the
  8 pointer, and to perform no operation on it other than comparison with
  9 the null pointer or with another menu object, except through the menu_
 10 subroutine.  Declarations for the entries and the associated structures
 11 are in the include file menu_dcls.incl.pl1.
 12 
 13 
 14 Entry points in menu_:
 15    (List is generated by the help command)
 16 
 17 
 18 :Entry:  create:  03/19/85 menu_$create
 19 
 20 
 21 Function:  This entry creates a menu object given its description.  The
 22 menu data structure is allocated in a caller supplied area, and may be
 23 saved across processes by calling menu_$store.  A pointer to the new
 24 menu is returned, also with the minimum size of a window to hold the
 25 menu.
 26 
 27 
 28 Syntax:
 29 declare menu_$create entry ((*) char (*) varying, (*) char (*) varying,
 30      (*) char (*) varying, ptr, (*) char (1) unal, ptr, ptr, ptr,
 31      fixed bin (35));
 32 call menu_$create (choices, headers, trailers, format_ptr, keys,
 33      area_ptr, needs_ptr, menu, code);
 34 
 35 
 36 Arguments:
 37 choices
 38    is an array of the names of the options.  (Input) If the maximum
 39    number of choices is exceeded, the code menu_et_$too_many_options is
 40    returned.  The current maximum is 61.
 41 headers
 42    is an array of headers.  (Input) If the length of the first header
 43    is zero, then no headers are used.  This allows the caller to
 44    specify no headers, without resorting to a zero-extent array, which
 45    is invalid PL/I.
 46 trailers
 47    is an array of trailers.  (Input) As for headers, a zero-length
 48    first trailer means that no trailers are displayed.
 49 
 50 
 51 format_ptr
 52    points to a structure, menu_format, that controls formatting of the
 53    menu.  (Input) This structure is declared in menu_dcls.incl.pl1.
 54 keys
 55    is an array specifying the keystroke for each option.  (Input) The
 56    array must have at least as many elements as the array of option
 57    names.  If not, the error code menu_et_$too_few_keys is returned.
 58    It may have more keys than choices.  Each item of the array must be
 59    unique, or menu_et_$keys_not_unique is returned.  If the valid keys
 60    (the keys for which there are choices) are either all upper case or
 61    all lower case, menu_$get_choice will treat upper and lower case
 62    letters identically.
 63 
 64 
 65 area_ptr
 66    is a pointer to an area where the menu description is allocated.
 67    (Input) If the area is not large enough, the area condition is
 68    signalled.  If this pointer is null, the system free area is used.
 69 needs_ptr
 70    points to the menu_requirements structure giving requirements to
 71    display the menu.  (Input)  The caller supplies this structure and
 72    fills in the version number menu_requirements_version_1, the
 73    remaining members are output from this entry.
 74 menu
 75    is a newly created menu object.  (Output)
 76 code
 77    is a standard system error code, or an error code from menu_et_.
 78    (Output)
 79 
 80 
 81 :Entry:  delete:  03/19/85 menu_$delete
 82 
 83 
 84 Function:  This entry deletes a menu object from a specified value
 85 segment.
 86 
 87 
 88 Syntax:
 89 declare menu_$delete entry (char (*), char (*), char (*), fixed bin
 90      (35));
 91 call menu_$delete (dirname, entryname, menu_name, code);
 92 
 93 
 94 Arguments:
 95 dirname
 96    is the pathname of the containing directory.  (Input)
 97 entryname
 98    is the entryname of the segment.  (Input) It must have the value
 99    suffix.
100 menu_name
101    is the name that was assigned to the menu when it was stored (see
102    the description of menu_$store).  (Input)
103 code
104    is a standard system error code.  (Output)
105 
106 
107 :Entry:  describe:  03/19/85 menu_$describe
108 
109 
110 Function:  This entry fills in a caller-supplied data structure
111 describing some of the aspects of a menu object.  The caller can use
112 this to ensure a window is sufficiently large to hold a menu.
113 
114 
115 Syntax:
116 declare menu_$describe entry (ptr, ptr, fixed bin (35));
117 call menu_$describe (menu, needs_ptr, code);
118 
119 
120 Arguments:
121 menu
122    is the menu object to describe.  (Input)
123 needs_ptr
124    points to a structure declared like menu_requirements.
125   (Input) The caller fills in the version to
126    be menu_requirements_version_1, and the remaining members are filled
127    in by this entry.
128 code
129    is a standard system error code.  (Output)
130 
131 
132 :Entry:  destroy:  03/19/85 menu_$destroy
133 
134 
135 Function:  This entry is used to delete a menu object.  The caller uses
136 this to free storage of a menu, since the representation of a menu is
137 not known outside the menu_ subroutine.  This entry has no effect on
138 screen contents or on stored menus.
139 
140 
141 Syntax:
142 declare menu_$destroy entry (ptr, fixed bin (35));
143 call menu_$destroy (menu, code);
144 
145 
146 Arguments:
147 menu
148    is the menu object to destroy.  (Input)
149 code
150    is a standard system error code.  (Output)
151 
152 
153 :Entry:  display:  03/19/85 menu_$display
154 
155 
156 Function:  This entry displays a menu object on a supplied window.
157 
158 
159 Syntax:
160 declare menu_$display entry (ptr, ptr, fixed bin (35));
161 call menu_$display (window, menu, code);
162 
163 
164 Arguments:
165 window
166    is a pointer to an IOCB for an I/O switch attached through
167    window_io_.  (Input) This window must be large enough to hold the
168    menu.  A menu window should be used ONLY for menu I/O, if redisplay
169    optimizations are desired.
170 menu
171    is the menu object to be displayed.  (Input)
172 code
173    is a standard system error code.  (Output)
174 
175 
176 :Entry:  get_choice:  03/19/85 menu_$get_choice
177 
178 
179 Function:  This entry returns a choice from a menu.  The menu is
180 assumed to be already displayed in the window.
181 
182 
183 Syntax:
184 declare menu_$get_choice entry (ptr, ptr, ptr, bit (1) aligned,
185      fixed bin, fixed bin (35));
186 call menu_$get_choice (window, menu, function_key_info, fkey,
187      selection, code);
188 
189 
190 Arguments:
191 window
192    is a pointer to the IOCB for the I/O switch used to display the
193    menu.  (Input)
194 menu
195    is the menu object on display in the window.  (Input)
196 function_key_info
197    is a pointer to a data structure describing the function keys
198    available on the terminal.  (Input) This data structure is obtained
199    by the caller from the ttt_info_$function_key_data subroutine.  If
200    this pointer is null, no function keys are used.
201 
202 
203 fkey
204    returns a value of "1"b if a function key was hit instead of a menu
205    selection.  (Output)
206 selection
207    gives the option number or function key number chosen by the user.
208    For an option, it is a number between 1 and the highest defined
209    option, inclusive.  For a function key, it is the number of the
210    function key.
211 code
212    is a standard system error code.  (Output)
213 
214 
215 Notes:  If a terminal has no function keys, the caller can define input
216 escape sequences for function keys.  These may be chosen to have
217 mnemonic value to the end user.  For example, if Function Key 1 is used
218 to print a help file, the input sequence ESC h could replace it.  In
219 some applications, this will be easier for the end user to remember
220 than an unlabelled function key.  The caller can define these keys by
221 allocating and filling in the same function key structure normally
222 returned by the ttt_info_ subroutine.
223 
224 If a key is hit that is not one of the option keys and is not a
225 function key, then the terminal bell is rung.
226 
227 
228 :Entry:  list:  03/19/85 menu_$list
229 
230 
231 Function:  This entry lists the menu objects stored in a specified
232 value segment.
233 
234 
235 Syntax:
236 declare menu_$list entry (char (*), char (*), char (*), ptr, fixed bin,
237      ptr, fixed bin (35));
238 call menu_$list (dirname, entryname, menu_starname, area_ptr,
239      menu_list_info_version, menu_list_info_ptr, code);
240 
241 
242 Arguments:
243 dirname
244    is the pathname of the containing directory.  (Input)
245 entryname
246    is the entryname of the segment.  (Input) It must have the value
247    suffix.
248 menu_starname
249    is matched against the names of the menus stored in the segment.
250    (Input) Only names that match menu_starname are returned.  (see the
251    description of menu_$store).
252 area_ptr
253    is a pointer to an area in which to allocate the structure
254    containing the menu names.  (Input) If it is null, the system free
255    area is used.
256 
257 
258 menu_list_info_version
259    is the version of the menu_list_info structure that the caller
260    expects.  (Input) It must be a supported menu_list_info structure
261    version.  The only supported version is menu_list_info_version_1.
262 menu_list_info_ptr
263    is a pointer to the menu_list_info structure, declared in
264    menu_dcls.incl.pl1.  (Output)
265 code
266    is a standard system error code.  (Output)
267 
268 
269 :Entry:  retrieve:  03/19/85 menu_$retrieve
270 
271 
272 Function:  This entry retrieves a menu from a specified segment.  The
273 segment must be a value segment.  The menu data structure is allocated
274 in a caller-supplied area.  The menu information is copied from the
275 menu object stored in the segment into the newly allocated structure.
276 
277 
278 Syntax:
279 declare menu_$retrieve entry (char (*), char (*), char (*), ptr, ptr,
280      fixed bin (35));
281 call menu_$retrieve (dirname, entryname, menu_name, area_ptr, menu_ptr,
282      code);
283 
284 
285 Arguments:
286 dirname
287    is the pathname of the containing directory.  (Input)
288 entryname
289    is the entryname of the segment.  (Input) It must have the value
290    suffix.
291 menu_name
292    is the name that was assigned to the menu when it was stored (see
293    the description of menu_$store).  (Input)
294 area_ptr
295    is a pointer to an area where the menu object is allocated.  (Input)
296    If this argument is null, the system free area is used.  If the area
297    is not large enough, the area condition is signalled.
298 
299 
300 menu_ptr
301    is a pointer to the menu object that is retrieved from the segment.
302    (Output)
303 code
304    is a standard system error code.  (Output)
305 
306 
307 :Entry:  store:  03/19/85 menu_$store
308 
309 
310 Function:  This entry stores a menu object in a specified segment.  The
311 specified segment must be a value segment.
312 
313 
314 Syntax:
315 declare menu_$store entry (char (*), char (*), char (*), bit(1)
316      aligned, ptr, fixed bin (35));
317 call menu_$store (dirname, entryname, menu_name, create_sw, menu_ptr,
318      code);
319 
320 
321 Arguments:
322 dirname
323    is the pathname of the containing directory.  (Input)
324 entryname
325    is the entryname of the segment.  (Input) It must have the value
326    suffix.
327 menu_name
328    is a name to be assigned to the menu.  (Input)
329 create_sw
330    determines whether or not the segment is created if it does not
331    already exist.  If the segment does not exist, a value of "1"b will
332    cause it to be created.  (Input)
333 menu_ptr
334    is a pointer to the menu object that is to be stored in the segment.
335    (Input)
336 code
337    is a standard system error code.  (Output)