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 new-
       line)  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.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       attributes(5)

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 alphabeti-
       cally. 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.

SunOS 5.11							    14 Sep 1992 							 ckitem(1)