CKITEM(1) User Commands CKITEM(1)

NAME

ckitem, erritem, helpitem - build a menu; prompt for and return a
menu item

SYNOPSIS

ckitem [-Q] [-W width] [-uno] [-f filename] [-l label]
[ [-i invis] [,]...] [-m max] [-d default] [-h help]
[-e error] [-p prompt] [-k pid [-s signal]]
[choice [...]]


/usr/sadm/bin/erritem [-W width] [-e error] [choice [..]]


/usr/sadm/bin/helpitem [-W width] [-h help] [choice [..]]

DESCRIPTION

The ckitem utility 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 formatting.
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).

OPTIONS

The following options are supported:

-d default
Define the default value as default. The default is
not validated and so does not have to meet any
criteria.


-e error
Define the error message as error.


-f filename
Define a file, filename, 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.)


-h help
Define the help messages as help.


-i invis
Define 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.


-k pid
Specify that the process ID pid is to be sent a signal
if the user chooses to abort.


-l label
Define a label, label, to print above the menu.


-m max
Define the maximum number of menu choices that the
user can choose. The default is 1.


-n
Specify that menu items should not be displayed in
alphabetical order.


-o
Specify that only one menu token will be returned.


-p prompt
Define the prompt message as prompt.


-Q
Specify that quit will not be allowed as a valid
response.


-s signal
Specify 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.


-u
Specify that menu items should be displayed as an
unnumbered list.


-W width
Specify that prompt, help and error messages will be
formatted to a line length of width.

OPERANDS

The following operand is supported:

choice
Define menu items. Items should be separated by white space
or newline.

EXIT STATUS

The following exit values are returned:

0
Successful execution.


1
EOF on input, or negative width on -W option, or inability to
open file on -f option, or usage error.


3
User termination (quit).


4
No choices from which to choose.

SEE ALSO

attributes(7)

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 if you typed a number is:

ERROR: Bad numeric choice specification


The default error message if you typed a string is:

ERROR: Entry does not match available menu selection. Enter the number
of the menu item you wish to select, the token which is associated
with the menu item, or a partial string which uniquely identifies the
token for the menu item. Enter ?? to reprint the menu.


The default help message is:

Enter the number of the menu item you wish to select, the token
which is associated with the menu item, or a partial string which
uniquely identifies the token for the menu item. Enter ? to
reprint the menu.


When the quit option is chosen (and allowed), q is returned along
with the return code 3.

September 14, 1992 CKITEM(1)