NAME

MPE::Suprtool - Perl extension for calling Robelle Suprtool

SYNOPSIS

  use MPE::Suprtool;

  chdir "/$ENV{HPACCOUNT}/PUB" or die "Cannot cd to PUB: $!\n";
     # May be necessary to chdir to an MPE group
     # (depending on Suprtool version)

  my $supr = MPE::Suprtool->new
     or die "Cannot run Suprtool\n";

  my $account = 518;

  $supr->cmd(
   "bas ordrdb,5,password",
   "chain order-detail,account=$account",
   "extr order-num, account, invoice",
   "output ordlist,ascii",
   "purge ordlist",
   "exit") or die "Error on Suprtool comand '" . $supr->lastcmd . 
     "', status = " . $supr->status . "\n";

  print "I wrote ", $supr->count, " records.";

DESCRIPTION

This module allows you to easily call Robelle's Suprtool from Perl and pass it commands dynamically. You must, of course, already have Suprtool installed. This module is somewhat easier than creating a Suprtool script file, running Suprtool and then reading JCWs to figure out if it worked.

See http://www.robelle.com for more on Suprtool.

new ( [args] )

Creates a new Suprtool object. new optionally takes arguments; these arguments are in key-value pairs. Available options:

  OPTION     DEFAULT

  pri           'DS'
     specifies the process queue for Suprtool
     legal values are 'CS', 'DS', or 'ES'

  printstate    'ER'
     specifies when Suprtool prints
     legal values are 'ER' - print on error
                      'AL' - always print
                      'NE' - never print

  xl            'ST2XL.PUB.ROBELLE'
     where Perl should look for the Suprtool2 subroutine
     (Can also be changed when installing module--see README)


  Example:
    my $supr = MPE::Suprtool->new( printstate => 'AL', pri => 'CS')
               or die "Cannot run Suprtool\n";

cmd( @list )

cmd submits a command or list of commands to Suprtool. This is a list of strings, which can be an array variable, string literals, a list of scalar string variables, or just about any combination. The normal Perl rules apply, so if you want to say OUTPUT $NULL you'll need to use single quotes 'OUTPUT $NULL' or escape the $ in double quotes: "OUTPUT \$NULL"

Of course, sometimes you want to interpolate a variable. The commands are only executed when there's an "EXIT" in a string by itself. Each command string can be up to 256 characters long. You can combine commands in one string by separating them with a semicolon.

The following all have the same effect:

  $supr->cmd("INPUT FILE1; KEY 1,4; OUTPUT FILE2", "EXIT");

OR

  $supr->cmd("INPUT FILE1", "KEY 1,4");
  $supr->cmd("OUTPUT FILE2", "EXIT");

OR

  $supr->cmd("INPUT FILE1");
  $supr->cmd("KEY 1,4");
  $supr->cmd("OUTPUT FILE2");
  $supr->cmd("EXIT");

OR

  @a = ("KEY 1,4", "OUTPUT FILE2");
  $supr->cmd("INPUT FILE1", @a, "EXIT");

and so on.

cmd will return false if there is an error. You can use status to see the status, which is usually not very informative, and lastcmd to see the command in the list which returned the error.

lastcmd

The last command executed. If cmd is passed a list, it will stop on any command giving an error. Some syntax errors will be caught on the command containing the error, but most errors will only get caught on the 'EXIT' command, so this is of limited utility.

Information returned by the calls

See the documenation in the Suprtool manual for the control record for these items.

status

  0 - Successfull
  1 - Unable to Access Files
  2 - Suprtool Aborted
  3 - Unable to Create Suprtool Process
  4 - Invalid Total Type
  5 - Unable to Create Suprtool Process

count

The number of records that Suprtool output.

totals

If you specify the Total command as part of an extract task, Suprtool2 returns the totals in the totals array. Totals are returned in exactly the same order in which they were specified.

  Example:

    $supr->cmd(
     "in sales",
     "def division,1,4",
     "def sale-amt,5,6,display",
     "if division='WEST'",
     "ext division, sale-amt",
     "total sale-amt",
     "out sales2,link",
     "purge sales2",
     "exit") or die "Error on Suprtool\n";

     @tot = $supr->totals();
     print "The sum of sales in the west is ", $tot[0], "\n";

EXPORT

None by default.

AUTHOR

Ken Hirsch <kenhirsch@myself.com>

Many thanks to Robelle, which generously supported the completion of this module.

This module may be used and distributed on the same terms as Perl.

SEE ALSO

perl(1).

MPE::Image on CPAN

http://www.robelle.com

BUGS

As of Suprtool 4.3, the suprtool2 routine only works if the current working directory of your Perl process is an MPE group.