view release on metacpan or  search on metacpan

ClearPrompt.pm  view on Meta::CPAN

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() I<function> always leaves the return code of the
clearprompt I<command> in C<$?> just as C<system('clearprompt ...')>
would.  If the prompt was interrupted via a signal, the function
returns the undefined value.

=head2 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 objects.

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

=head2 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
I<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 I<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 C<warn()> and C<die()> functions.  Now, since
C<warn()> and C<die()> send their output to stderr they could be
subsumed by the STDERR channel, but they have different semantics and
are thus treated separately. Messages thrown by warn/die are
I<anticipated> errors from within the current (perl) process, whereas
other messages arriving on stderr will typically be I<unexpected>
messages not under the control of the running script (for instance
those from a backquoted cleartool command). This distinction is quite
important in triggers, where the former may represent a policy decision
and the latter a plain old programming bug or system error such as a
locked VOB. Warn/die captures are also displayed with the appropriate
GUI icons and the title C<Warning> or C<Error>.

The 4 channels are known to ClearPrompt as WARN, DIE, STDOUT, and
STDERR.  To capture any of them to clearprompt just specify them with a
leading C<+> at I<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);

An additional pseudo-channel can be specified for email representing
interactions with the user via the clearprompt program itself. I.e. the
following

    use ClearCase::ClearPrompt qw(+PROMPT=vobadm);

will take all prompt strings and the user's responses and mail them to
the specified user(s).

=head2 MESSAGE CAPTURE NOTES

=over 4

=item *

The capture-to-dialog-box feature appears to be largely obsoleted by
ClearCase v4.2 which implements similar functionality. In 4.2, messages
to stdout/stderr are placed in the "trigger failed" dialog box. Of
course this doesn't help if the trigger generated warnings but didn't
fail but it solves the main problem.

=item *

As of ClearPrompt 1.25, the capture-to-dialog and capture-to-email
lists are discrete. This means that C<+WARN> will capture warnings to a
dialog box, while C<+WARN=vobadm> will send warnings via email but NOT
to a dialog box. To get both you must request both, e.g. C<+WARN
+WARN=vobadm>. This change was made as a result of the CC fix mentioned
above.

=item *

The email feature first attempts to use the Net::SMTP module.  If this
is uninstalled or reports failure, the I<notify> utility which first
shipped in CC 4.0 is used. Thus you must have either Net::SMTP or CC
4.0 (or both) for email to succeed.