# Name: RTdumpbug
# Authors: Shawn Doyle, Jeff Ryan
# Company: ReleaseTeam, Inc.
# Description: A script that dumps all field/value pairs for a
#              Rational ClearQuest record.
# Support: If you have any problems or would like to see additional
#          functionality, send an email to support@releaseteam.com
#######################################################################

########################
# USER DEFINED VARIABLES
########################
# Name of the ClearQuest database to search
$dbname = "";

# Username with access to the above database
$CQ_user = "";

# Password for the above user
$CQ_password = "";

# Type of ClearQuest record to dump
$recordtype = "defect";

###########################################
# NO USER DEFINED VARIABLES BELOW THIS LINE
###########################################

use CQPerlExt;
use Getopt::Long;
use Pod::Usage;

require 5.6.0; # CQPerlExt module requires at least Perl version 5.6.0

my ($help) = 0;     # Flag for the -help and -? options
my ($no_aster) = 0; # Flag for the -n option

######################
# Start main execution
######################
GetOptions ("help|?" => \$help, "n" => \$no_aster) ||
  pod2usage ({ -exitval => 2, -verbose => 0 });
pod2usage ({ -exitval => 0, -verbose => 2 }) if ($help);

&OpenSession ();

if (@ARGV) {
  @defects = @ARGV;
} else {
  @defects = <STDIN>;
}
chomp (@defects);
foreach $defect (@defects) {
  &dumpbug ($defect);
  print ("\n");
}

&CloseSession ();

exit (0);
####################
# End main execution
####################

#######################################################################
# Subroutine: OpenSession
# Description: Creates the Session object required for communication
#              with ClearQuest.
sub OpenSession {
  eval ("\$CQSession = CQPerlExt::CQSession_Build ();");
  &CQ_error ("CQSession_Build") if ($@);
  eval ("\$CQSession->UserLogon (\$CQ_user, \$CQ_password, " .
        "\$dbname, \"\");");
  &CQ_error ("UserLogon") if ($@);
}

#######################################################################
# Subroutine: dumpbug ()
# Description: Displays all fields and their values.
# Input: $defect - ClearQuest defect to display
# Output: None
sub dumpbug {
  my ($defect) = @_;

  # Set the entity
  $entityObj = 0;
  eval ("\$entityObj = \$CQSession->GetEntity (\$recordtype, " .
        "\$defect);");
  &CQ_error ("GetEntity") if ($@);

  # Get a reference to a string array
  eval ("\$fieldNameList = \$entityObj->GetFieldNames ();");
  &CQ_error ("GetFieldNames") if ($@);

  unless ($no_aster) {
    for ($i = 0; $i < 72; $i++) {
      print ("*");
    }
    print ("\n");
  }
  # Iterate through the fields and output the field name and value
  $i = 0;
  foreach (@$fieldNameList) {
    $fieldInfoObj = 0;
    eval ("\$fieldInfoObj = \$entityObj->GetFieldValue " .
          "(\$\$fieldNameList[\$i]);");
    &CQ_error ("GetFieldValue") if ($@);
    eval ("\$fieldValue = \$fieldInfoObj->GetValue ();");
    &CQ_error ("GetValue") if ($@);
    print ("$$fieldNameList[$i++] : $fieldValue\n");
  }
}

#######################################################################
# Subroutine: CloseSession ()
# Description: Destroys Session object.
# Input: None
# Output: None
sub CloseSession {
  eval ("CQSession::Unbuild (\$CQSession);");
  &CQ_error ("Unbuild") if ($@);
}

#######################################################################
# Subroutine: CQ_error ()
# Description: Displays the error given by a failed ClearQuest API
#              command.
# Input: $method - Name of ClearQuest API method that failed
# Output: None
sub CQ_error {
  my ($method) = @_;
  print ("ERROR: $method failed with the following message:\n$@\n");
  exit (1);
}

__END__

=head1 NAME

RTdumpbug - print a defect record

=head1 SYNOPSIS

RTdumpbug [-help | -?] [-n] [ClearQuest ID ...]

=head1 OPTIONS

=over 8

=item B<-help | -?>

Display online documentation.

=item B<-n>

Suppresses the printing of the row of asterisks (***) that is
ordinarily printed before each defect record.

=back

=head1 DESCRIPTION

Use RTdumpbug to print defect records to the standard output. The
record IDs of the defect record(s) can be supplied on the command
line. If no IDs are specified, the list of record IDs to be printed
is read from the standard input.

By default, for each record ID RTdumpbug writes a row of asterisks and
then each fieldname:value pair for the record, one per line.

=head1 EXAMPLES

The RTfindbug utility is particularly useful in conjuction with
RTdumpbug. For example, the following prints all severity 1 bugs:

	RTfindbug Severity == 1 | RTdumpbug

Another way to use RTdumpbug is as follows:

	RTdumpbug XXXaa00055 XXXaa00122 ...

where XXXaa00055 and XXXaa00122 are the bug IDs of the bugs to be
printed.

=head1 SEE ALSO

RTfindbug, RTsortbug

=cut