clearprompt

Prompt for user input

APPLICABILITY

SYNOPSIS

• UNIX only-Prompt for text:

clearprompt text -out·file pname [ -mul·ti_line ]

[ -def·ault string | -dfi·le pname ]
-pro·mpt prompt_string [ -pre·fer_gui ]

• UNIX only-Prompt for pathname:

clearprompt file -out·file pname [ -pat·tern match_pattern ]

[ -def·ault filename | -dfi·le pname ] [ -dir·ectory dir_path ]
-pro·mpt prompt_string [ -pre·fer_gui ]

• UNIX only-Prompt for list:

clearprompt list -out·file pname [ -items choice[,choice] [ -choices ] | -dfi·le pname ]

-pro·mpt prompt_string [ -pre·fer_gui ]

• UNIX only-Prompt for continue-processing choice:

clearprompt proceed [ -typ·e type ] [ -def·ault choice ]

[ -mas·k choice[,choice] ] -pro·mpt prompt_string [ -pre·fer_gui ]

• UNIX only-Prompt for yes-no choice:

clearprompt yes_no [ -typ·e type ] [ -def·ault choice ]

[ -mas·k choice[,choice] ] -pro·mpt prompt_string [ -pre·fer_gui ]

• Windows only-Prompt for text:

clearprompt text -out·file pname [ -mul·ti_line ]

[ -def·ault string | -dfi·le pname ]
-pro·mpt prompt_string

• Windows only-Prompt for pathname:

clearprompt file -out·file pname [ -pat·tern match_pattern ]

[ -def·ault filename | -dfi·le pname ] [ -dir·ectory dir_path ]
-pro·mpt prompt_string

• Windows only-Prompt for list:

clearprompt list -out·file pname [ -items choice[,choice] [ -choices ] | -dfi·le pname ]

-pro·mpt prompt_string

• Windows only-Prompt for continue-processing choice:

clearprompt proceed [ -typ·e type ] [ -def·ault choice ]

[ -mas·k choice[,choice] ] -pro·mpt prompt_string [ -newline ]

• Windows only-Prompt for yes-no choice:

clearprompt yes_no [ -typ·e type ] [ -def·ault choice ]

[ -mas·k choice[,choice] ] -pro·mpt prompt_string [ -newline ]

proceed choice is one of: proceed, abort

yes_no choice is one of: yes, no, abort

type is one of: ok, warning, error

DESCRIPTION

The clearprompt command prompts the user for input, then either stores the input in a file or returns an appropriate exit status. clearprompt is designed for use in trigger action and GUI scripts. (See the mktrtype reference page.)

NOTE: On Windows 98 and Windows Me systems, you must invoke clearprompt from the command prompt's start /wait command.

On UNIX systems, clearprompt can interact with the user either through stdin and stderr (CLI mode), or through a pop-up window (GUI mode). It uses the latter style when a trigger fires on an operation invoked through the GUI program xclearcase.

A trigger action script (or any other script) can use the exit status of clearprompt proceed or clearprompt yes_no to perform conditional processing:

RESTRICTIONS

None.

OPTIONS AND ARGUMENTS

text [ -mul·ti_line ]

file

list

proceed

yes_no

(Mutually exclusive) Specifies the kind of user input to be prompted for:

text prompts for a single text line (with no trailing <NL> character). text -multi_line works just like cleartool comment input: in command-line mode, the user can enter any number of lines (on UNIX systems, terminated with RETURN or CTRL+D). If the -multi_line option is not used, a text string that exceeds 138 characters (all uppercase) or 193 characters (all lowercase) will be truncated.

file prompts for a file name or, if -prefer_gui is specified, opens a file browser window.

list prompts for a choice from a list of items.

proceed prompts for a choice between the alternatives proceed and abort. The default for this option is proceed unless you override it by specifying -default abort.

yes_no prompts for a choice among the alternatives yes, no, and abort. The default for this option is yes unless you override it by specifying -default no or -default abort.

-out·file pname

Specifies the file to which the user's input is written.

-def·ault string

Specifies the default text to be written to the -outfile file if the UNIX user presses RETURN (in CLI mode) or clicks OK (in GUI mode), or if the Windows user clicks OK.

-def·ault filename

Specifies the default file name string to be written to the -outfile file if the UNIX user presses RETURN (in CLI mode) or clicks OK (in GUI mode), or if the Windows user clicks OK.

-dfi·le pname

A variant of -default; reads the default text from a file instead of the command line. With the list argument, -dfile reads a list of comma-separated items from a file instead of from the command line.

-def·ault choice

Specifies the choice made if the UNIX user presses RETURN (in CLI mode) or clicks OK (in GUI mode), or if the Windows user clicks OK. The specified default is silently included in the -mask list.

-typ·e type

Specifies the severity level: ok, warning, or error. The only effect is in the way the user is prompted for input.

-ite·ms choice[,choice]

Restricts the universe of choices for a list interaction.

-choices

Allows the user to select more than one choice from the list.

-mas·k choice[,choice]

Restricts the choices for a proceed or yes_no interaction. Defaults for proceed and yes_no, whether or not they are explicitly specified, are included among the -mask arguments.

-newline

With proceed or yes_no on Windows, forces all "\n" sequences in prompt_string to be displayed as newline characters. Ignored in other modes (which already interpret "\n" this way) and on UNIX.

-pat·tern match_pattern

-dir·ectory dir_path

On UNIX systems, when clearprompt file executes in GUI mode, the file browser window contains a pathname filter. On Windows systems, the file prompt window contains the pathname filter.

By default, this window displays the names of all files in the current working directory. You can use the -directory and/or -pattern option to specify a different directory and/or file name pattern (for example, *.c) to restrict which file names are displayed. The user can change the filter after the file browser appears.

-pro·mpt prompt_string

Specifies the prompt message to be displayed.

-pre·fer_gui

Causes clearprompt to try to work in GUI mode; but if the attempt to open an interaction window fails, falls back to CLI mode.

Exceptions: GUI mode is forced if any of these conditions are true:

clearprompt is invoked by a trigger firing on an xclearcase (not cleartool) operation. If an interaction window cannot be created, an error occurs.

The environment variable ATRIA_FORCE_GUI is set to 1.

EXAMPLES

NOTE: See the mktrtype reference page for additional examples.

• Prompt the user to enter a name, writing the user's input to file uname. Use the value of the USER environment variable if the user presses RETURN.

% clearprompt text -outfile uname -default $USER -prompt "Enter User Name:"

• Ask a question and prompt for a yes/no response. Make the default response no.

y:\> clearprompt yes_no -prompt "Do You Want to Continue?" ^
-default no -mask yes,no

On Windows 98 or Windows Me, prepend the command shell's start /wait command:

y:\> start /wait clearprompt yes_no -prompt "Do You Want to Continue?" ^
-default no -mask yes,no

• Ask a question and prompt for a yes/abort response, excluding no as a choice, and using a separate window if possible. The default is yes because no default is explicitly specified.

% clearprompt yes_no -prompt "OK to continue?" -mask abort -prefer_gui

• Prompt for a file name. Restrict the choices to files with a .c extension, and write the user's selection to a file named myfile.

c:\> clearprompt file -prompt "Select File From List" -outfile myfile ^
-pattern '*.c'

SEE ALSO

mktrigger, mktrtype, xclearcase