EXTRACTFIELDVALUES(1) 

NAME
       ExtractFieldValues  -  extract  information from SDDF file
       and write to new text file(s) according to selection  cri-
       teria

SYNOPSIS
       ExtractFieldValues controlfile SDDFfile

DESCRIPTION
       The ExtractFieldValues program reads a control file and an
       SDDF data file and extracts field  values  from  specified
       SDDF  records.   The  extracted field values, and possibly
       string constants, are  written  to  output  text  file(s).
       Selection criteria and the output file(s) are specified in
       the external control file that is given as the first argu-
       ment.   The output file(s) are typically processed further
       using standard tools such as gnuplot.

       The first character in  each  line  of  the  control  file
       determines  what  action  is  being specified by the line.
       The recognized control types (in angle brackets) and  cor-
       responding formats (following the brackets) are:

        # text...
       marks  the  line as a comment line.  Comment lines have no
       effect on the output produced.

       
 O filename
       says to use filename for output.  All controls  until  the
       occurance  of  another 
 line will be directed
       to this file.  A maximum of 20  
  lines  may
       appear in a single control file.

        R recordname
       says  to  look for SDDF records with the given recordname.
       An 
 control line must appear in  the  control
       file  prior  to  the  first  control line.  A
       maximum of 256  lines may appear in a  single
       control  file.    A given recordname may appear in several
        control lines in a single  control  file  --
       these may be associated with different output files and/or
       have different selection  criteria  as  specified  by  the
       associated  controls.

        T fieldname  test_op  test_value
       says to look for the field fieldname in the active record-
       name and compare it's value to the  test_value  using  the
       test_op  comparison.   test_op may be on of the following:
       EQ (equal), NE (not equal), GT (greater  than),  LT  (less
       than),  GE  (greater  than  or equal to), LE (less than or
       equal to).  The fieldname should refer to a scalar  field,
       test_value  is  treated  as  being  of  type double, and a
        control line should appear  in  the  control
       file  prior  to the first  control line.    No
       output is produced solely as a result of the 
       line  --  it merely provides selection critera.  There may
       be multiple  control lines for a given 
 -- all will be tested.

        F field
       specifies  that  the value of field for the active record-
       name should be written to the active output file  filename
       if  all tests on field values for this record passed.  The
       field value should be a scalar.  A   control
       line  should appear in the control file prior to the first
        control line.  Also, all  lines for  a
       given  
 pair should appear prior
       to any of the  control lines.  There may be  multi-
       ple    lines for a given 

       -- all will be written if the selection criteria passed.

        S text string
       specifies that text string should be written to the active
       output file filename if all tests on field values for this
       record passed.  A  control line should appear
       in  the  control  file prior to the first  control
       line.  There may be multiple  lines  for  a  given
       
  and they may be interspersed
       with the  control lines.  The  output  record  will
       contain the field value and text strings in the same order
       they appear in the control file.

EXAMPLE
       As an example, a control file to extract the duration  and
       bytes  transferred for read and write operations is shown.
       Notice that for writes we only want operations occuring on
       processor 0.

       #
       # Information from Reads will go to /tmp/reads
       #
       O /tmp/reads
       R Read
       F Seconds
       F Number Bytes
       #
       # Information from Writes on processor 0 will go to /tmp/writes
       #
       O /tmp/writes
       R Write
       T Processor Number / EQ / 0
       F Seconds
       F Number Bytes

       The  files  produced (/tmp/reads and /tmp/writes) could be
       used as input to gnuplot to show the relationship  between
       transfer  size and operation duration in a graphical form.

FILES
       /Templates/extractFieldVal-
              ues.cntrl
              A more complex sample control file.

       /Templates/extractFieldVal-
              ues.ascii
              An SDDF input file that can be used in  conjunction
              with  extractFieldValues.cntrl  to  demonstrate the
              behavior of the ExtractFieldValues program.

SEE ALSO
       Ruth A. Aydt, The Pablo Self-Defining Data Format

COPYRIGHT
       Copyright  1996,  The  University  of  Illinois  Board  of
       Trustees.

AUTHOR
       Ruth A. Aydt, University of Illinois

Pablo Environment          Sep 26, 1996