# Name: RTbugval
# Author: Jeff Ryan
# Company: ReleaseTeam, Inc.
# Description: Displays the current values of selected fields to
#              standard output, one field per line.
# 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
$dbname = "";

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

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

# Type of ClearQuest record
$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 ($defect) = ""; # Variable to hold defect id from -i option

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

pod2usage ({ -exitval => 0, -verbose => 2 }) if ($help);

if ($defect eq "") {
  # The -i option was not used so read bugids from standard input
  @defects = <STDIN>;
} else {
  push (@defects, $defect);
}
chomp (@defects);

# Get the fields we are to print values for
@fields = @ARGV;
chomp (@fields);

&OpenSession ();

&PrintValues ();

&CloseSession ();

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

#######################################################################
# Subroutine: OpenSession ()
# Description: Creates the Session object required for communication
#              with ClearQuest.
# Input: None
# Output: None
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: PrintValues ()
# Description: Displays the values for each field specified for each
#              record.
# Input: None
# Output: None
sub PrintValues {
  foreach $defect (@defects) {
    print ("$defect\n");
    # Get the Entity object for the defect record
    $entityObj = 0;
    eval ("\$entityObj = \$CQSession->GetEntity (\$recordtype, " .
          "\$defect);");
    &CQ_error ("GetEntity") if ($@);
    foreach $field (@fields) {
      # Get the FieldInfo object for the field
      $fieldInfoObj = 0;
      eval ("\$fieldInfoObj = \$entityObj->GetFieldValue " .
            "(\$field);");
      if ($@) {
        print ("Problem retrieving information for \"$field\" field.\n");
        print ("Check the spelling and verify the field exists in ");
        print ("ClearQuest.\n\n");
        &CQ_error ("GetFieldValue");
      }

      eval ("\$value = \$fieldInfoObj->GetValue ();");
      &CQ_error ("GetValue") if ($@);
      print ("$field = $value\n");
    }
    print ("\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 the 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

RTbugval - print selected fields of defect records

=head1 SYNOPSIS

RTbugval [-help | -?] [-i] keyword keyword ...

=head1 OPTIONS

=over 8

=item B<-help | -?>

Display online documentation

=item B<-i bugid>

Specifies a single bugid to be used. If -i is specified, no bugids
will be read from standard input.

=back

=head1 DESCRIPTION

By default the RTbugval utility reads defect record IDs from the
standard input and writes the contents of the specified keyword
fields for each specified defect record to the standard output.
Usually, the record IDs are obtained by running RTfindbug.

The fields named by the keywords are printed in the order specified
in the invocation string.

=head1 EXAMPLES

The following command displays the State, Severity, and Priority
fields for all defect records in the database:

	RTfindbug | RTbugval State Severity Priority

=head1 SEE ALSO

RTfindbug, RTsortbug

=cut