clearprompt

Prompts for user input

Applicability

Product

Command type

VersionVault

command

Platform

UNIX®

Linux®

Windows®

Synopsis

  • UNIX® and Linux® 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® and Linux® 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® and Linux® only—Prompt for list:
    clearprompt list –out/file pname [ –items choice[,choice] [ –choices ]
    | –dfi/le pname ] –pro/mpt prompt_string [ –pre/fer_gui ]
  • UNIX® and Linux® 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® and Linux® 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.)

On UNIX® and Linux® 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 xversionvault.

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

User selection

Exit status

yes

0

proceed

0

no

1

abort

2

Restrictions

None.

Options and arguments

text [ –mul/ti_line ] , file, proceed, list, 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® and Linux® 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® or Linux® 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® or Linux® 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® or Linux® 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]
Specifies the 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® and Linux® .
–pat/tern match_pattern , –dir/ectory dir_path
On UNIX® and Linux® systems, when clearprompt file executes in GUI mode, the file browser window contains a path name filter. On Windows® systems, the file prompt window contains the path name 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 starts.

–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 is true:
  • clearprompt is invoked by a trigger firing on an xversionvault (not cleartool) operation. If an interaction window cannot be created, an error occurs.
  • The environment variable CCASE_FORCE_GUI is set to 1.

Examples

Note: See the mktrtype reference page for additional examples.
  • On a UNIX® or Linux® system, 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:"

  • On a Windows® system, 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 a UNIX® or Linux® system, 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

  • On a Windows® system, 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'