ckitem(1) USER COMMANDS ckitem(1)
NAME
ckitem - build a menu; prompt for and return a menu item
SYNOPSIS
ckitem [-Q] [-W width] [-uno] [-f file] [-l label] [[-i
invis] [, ...]] [-m max]
[-d default] [-h help] [-e error] [-p prompt] [-k pid [-s
signal]] [choice [...]]
erritem [-W] [-e error] [choice [...]]
helpint [-W] [-h help] [choice [...]]
DESCRIPTION
ckitem builds a menu and prompts the user to choose one item
from a menu of items. It then verifies the response.
Options for this command define, among other things, a
prompt message whose response will be a menu item, text for
help and error messages, and a default value (which will be
returned if the user responds with a carriage return). By
default, the menu is formatted so that each item is
prepended by a number and is printed in columns across the
terminal. Column length is determined by the longest
choice. Items are alphabetized. All messages are limited
in length to 70 characters and are formatted automatically.
Any white space used in the definition (including newline)
is stripped. The -W option cancels the automatic format-
ting. When a tilde is placed at the beginning or end of a
message definition, the default text will be inserted at
that point, allowing both custom text and the default text
to be displayed. If the prompt, help or error message is
not defined, the default message (as defined under NOTES)
will be displayed. Two visual tool modules are linked to
the ckitem command. They are erritem (which formats and
displays an error message) and helpitem (which formats and
displays a help message). These modules should be used in
conjunction with FML objects. In this instance, the FML
object defines the prompt. When choice is defined in these
modules, the messages will describe the available menu
choice (or choices). The options and arguments for this
command are:
-Q Specifies that quit will not be allowed as a valid
response.
-W Specifies that prompt, help and error messages will be
formatted to a line length of width.
-u Specifies that menu items should be displayed as an
unnumbered list.
-n Specifies that menu items should not be displayed in
alphabetical order.
1
ckitem(1) USER COMMANDS ckitem(1)
-o Specifies that only one menu token will be returned.
-f Defines a file, file. which contains a list of menu
items to be displayed. [The format of this file is:
token<tab>description. Lines beginning with a pound
sign (#) are designated as comments and ignored.]
-l Defines a label, label, to print above the menu.
-i Defines invisible menu choices (those which will not be
printed in the menu). (For example, "all" used as an
invisible choice would mean it is a legal option but
does not appear in the menu. Any number of invisible
choices may be defined.) Invisible choices should be
made known to a user either in the prompt or in a help
message.
-m Defines the maximum number of menu choices allowed.
-d Defines the default value as default. The default is
not validated and so does not have to meet any cri-
teria.
-h Defines the help messages as help.
-e Defines the error message as error.
-p Defines the prompt message as prompt.
-k Specifies that the process ID pid is to be sent a sig-
nal if the user chooses to abort.
-s Specifies that process ID pid defined with the -k
option is to be sent signal signal when quit is chosen.
If no signal is specified, SIGTERM is used.
choice
Defines menu items. Items should be separated by white
space or newline.
SEE ALSO
allocmenu(3X)
printmenu(3X)
setinvis(3X)
setitems(3X)
EXIT CODES
0 = Successful execution
1 = EOF on input
2 = Usage error
3 = User termination (quit)
4 = No choices from which to choose
2
ckitem(1) USER COMMANDS ckitem(1)
NOTES
The user may input the number of the menu item if choices
are numbered or as much of the string required for a unique
identification of the item. Long menus are paged with 10
items per page. When menu entries are defined both in a
file (by using the -f option) and also on the command line,
they are usually combined alphabetically. However, if the
-n option is used to suppress alphabetical ordering, then
the entries defined in the file are shown first, followed by
the options defined on the command line. The default prompt
for ckitem is:
Enter selection [?,??,q]:
One question mark will give a help message and then redisplay
the prompt. Two question marks will give a help message and
then redisplay the menu label, the menu and the prompt. The
default error message is:
ERROR - Does not match an available menu selection.
Enter one of the following:
- the number of the menu item you wish to select
- the token associated withe the menu item,
- partial string which uniquely identifies the token for
the menu item
- ?? to reprint the menu
The default help message is:
Enter one of the following:
- the number of the menu item you wish to select
- the token associated with the menu item,
- partial string which uniquely identifies the token for the
menu item
- ?? to reprint the menu
When the quit option is chosen (and allowed), q is returned
along with the return code 3.
3