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'