The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
ClearCase-ClearPrompt-1.22
River stage one • 1 direct dependent • 2 total dependents
++
/ ClearCase::ClearPrompt

NAME

ClearCase::ClearPrompt - Handle clearprompt in a portable, convenient way

SYNOPSIS

 use ClearCase::ClearPrompt qw(clearprompt);

 # Boolean usage
 my $rc = clearprompt(qw(yes_no -mask y,n -type ok -prompt), 'Well?');

 # Returns text into specified variable (context sensitive).
 my $txt = clearprompt(qw(text -pref -pro), 'Enter text data here: ');

 # Asynchronous usage - show dialog box and continue
 clearprompt(qw(proceed -mask p -type ok -prompt), "You said: $txt");

 # Trigger series (record/replay responses for multiple elements)
 use ClearCase::ClearPrompt qw(clearprompt +TRIGGERSERIES);
 my $txt = clearprompt(qw(text -pref -pro), 'Response for all elems: ');

 # Automatically divert trigger error msgs to clearprompt dialogs
 use ClearCase::ClearPrompt qw(+ERRORS);

 # Prompt for a directory (not supported natively by clearprompt cmd)
 use ClearCase::ClearPrompt qw(clearprompt_dir);
 my $dir = clearprompt_dir('/tmp', "Please choose a directory");

DESCRIPTION

This module provides four areas of functionality, each based on clearprompt in some way but otherwise orthogonal. These are:

  • Clearprompt Abstraction

    Provides a simplified interface to the clearprompt program, taking care of creating and removing temp files as required.

  • Trigger Series Support

    Records and replays responses across multiple trigger firings.

  • Message Capture

    Catches messages to stdout or stderr which would otherwise be lost in a GUI environment and pops them up as dialog boxes using clearprompt.

  • Directory Chooser

    Allows clearprompt to be used to select directories (aka folders).

All of which are discussed in more detail below.

CLEARPROMPT ABSTRACTION

Native ClearCase provides a utility (clearprompt) for collecting user input or displaying messages within triggers. However, use of this tool is awkward and error prone, especially in multi-platform environments. Often you must create temp files, invoke clearprompt to write into them, open them and read the data, then unlink them. In many cases this code must run seamlessly on both Unix and Windows systems and is replicated throughout many scripts. ClearCase::ClearPrompt abstracts this dirty work without changing the interface to clearprompt.

The clearprompt() function takes the exact same set of flags as the eponymous ClearCase command, e.g.:

    my $response = clearprompt('text', '-def', '0', '-pro', 'Well? ');

except that the -outfile flag is unnecessary since creation, reading, and removal of this temp file is managed internally.

In a void context, clearprompt() behaves asynchronously; i.e. it displays the dialog box and returns so that execution can continue. This allows it to be used for informational displays. In any other context it waits for the dialog's button to be pushed and returns the appropriate data type.

The clearprompt() function always leaves the return code of the clearprompt command in $? just as system('clearprompt ...') would. If the prompt was interrupted via a signal, the function returns the undefined value.

TRIGGER SERIES

Since clearprompt is often used in triggers, special support is provided in ClearCase::ClearPrompt for multiple trigger firings deriving from a single CC operation upon multiple obects.

If the boolean $ClearCase::ClearPrompt::TriggerSeries has a true value, clearprompt will 'stash' its responses through multiple trigger firings. For instance, assuming a checkin trigger which prompts the user for a bugfix number and a command "cleartool ci *.c", the TriggerSeries flag would cause all response(s) to clearprompts for the first file to be recorded and replayed for the 2nd through nth trigger firings. The user gets prompted only once.

Trigger series behavior can also be requested at import time via:

    use ClearCase::ClearPrompt qw(+TRIGGERSERIES);

This feature is only available on CC versions which support the CLEARCASE_SERIES_ID environment variable (3.2.1 and up) but attempts to use it are harmless in older versions. The module will just drop back to prompting per-file in that case.

MESSAGE CAPTURE

In a ClearCase GUI environment, output to stdout or stderr (typically from a trigger) has no console to go to and thus disappears without a trace. This applies to both Unix and Windows GUI's and - especially on Windows where the GUI is used almost exclusively - can cause trigger bugs to go undetected for long periods. Trigger scripts sometimes exec clearprompt manually to display error messages but this is laborious and will not catch unanticipated errors such as those emanating from included modules or child processes.

ClearCase::ClearPrompt can be told to fix this problem by capturing all stderr/stdout and displaying it automatically using clearprompt. There's also a facility for forwarding error messages to a specified list of users via email.

ClearPrompt can capture messages to 4 "channels": the stdout and stderr I/O streams and the Perl warn() and die() functions. As the latter two send their output to stderr they could be subsumed by the stderr channel, but they have slightly different semantics and are thus treated separately; messages thrown by warn/die are anticipated errors from within the current (perl) process. Other messages arriving on stderr will typically be unexpected messages not under the control of the running script, for instance those from a backquoted cleartool command. This distinction is especially important in triggers where the former may represent a policy decision and the latter a plain old programming bug or system error. Warn/die captures are also displayed with the appropriate GUI icons and the title "Warning" or "Error".

The 4 channels are known as WARN, DIE, STDOUT, and STDERR. To capture any of them to clearprompt just specify them with a leading + at use time:

        use ClearCase::ClearPrompt qw(+STDERR +WARN +DIE);

These 3 "error channels" can also be requested via the meta-command

        use ClearCase::ClearPrompt qw(+ERRORS);

while all 4 can be captured with

        use ClearCase::ClearPrompt qw(+CAPTURE);

Messages may be automatically mailed to a list of users by attaching the comma-separated list to the name of the channel using '=' in the import method, e.g.

    use ClearCase::ClearPrompt '+ERRORS=vobadm';
    use ClearCase::ClearPrompt qw(+STDOUT=vobadm +STDERR=tom,dick,harry);

Note: the email feature requires the Net::SMTP module to be installed and correctly configured. You may find the supplied ./examples/smtp.pl script useful for this purpose.

SAMPLE CAPTURE USAGE

Try setting ATRIA_FORCE_GUI=1 by hand and running the following little script which generates a warning via warn() and a hard error from a child process:

   BEGIN { $ENV{ATRIA_FORCE_GUI} = 1 }
   use ClearCase::ClearPrompt qw(+CAPTURE);
   warn qq(This is a warning\n);
   system q(perl nosuchscript);

You should see a couple of error msgs in dialog boxes, and none on stderr. Removing the '+CAPTURE' would leave the messages on text-mode stderr. Changing it to '+WARN' would put the warning in a dialog box but let the error msg come to text stderr, while changing it to '+STDERR' would put both messages in the same dialog since warn() would no longer be treated specially. Appending "=<username>" would cause mail to be sent to <username>.

DIRECTORY PROMPTING

The clearprompt command has no builtin directory chooser, so this module provides a separate clearprompt_dir() function which implements it with "clearprompt list" and opendir/readdir/closedir. Usage is

    use ClearCase::ClearPrompt qw(clearprompt_dir);
    $dir = clearprompt_dir($starting_dir, $prompt_string);

This is pretty awkward to use since it doesn't employ a standard directory-chooser interface but it works. The only way to make your selection final is to select "." or hit the Abort button. And there's no way to create a directory via this interface. You would not use this feature unless you had to, typically.

MORE EXAMPLES

Examples of advanced usage can be found in the test.pl script. There is also a <./examples> subdir with a few sample scripts.

NOTES

An apparent undocumented "feature" of clearprompt(1) is that it catches SIGINT (Ctrl-C) and provides a status of 4 rather than returning the signal number in $? according to normal (UNIX) signal semantics. We fix that up here so it looks like a normal signal 2. Thus, if clearprompt() returns undef the signal number is reliably in $? as it's documented to be.

Also, there is a bug in ClearCase 4.0 for Win32. The list option doesn't display the prompt text correctly. This is a bug in CC itself, not the module, and is fixed in CC 4.1.

PORTING

This package is known to work fine on Solaris 2.5.1/perl5.004_04, Solaris 7/perl5.6, and Windows NT 4.0SP3/5.005_02. As these platforms are quite different they should take care of any significant portability issues but please send reports of tweaks needed for other platforms to the address below.

AUTHOR

David Boyce <dsb@world.std.com>

Copyright (c) 1999,2000 David Boyce. All rights reserved. This Perl program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

clearprompt(1), perl(1)