  1.  NAME

  xtract - Extract data from a CODAS database

  2.  USAGE

  xtract control_file

  3.  DESCRIPTION

  This utility extracts data from a CODAS database and generates
  different types of ASCII files. These can be used as input to further
  other processing or visualizing tools. Unlike adcpsect which was
  created to access data from an ADCP database, xtract does not depend
  on the database being accessed. More exactly, it does not depend on
  the producer definition file used to create the CODAS database. You
  can therefore access with the same utility any CODAS database.

  A producer definition file is required for creating a CODAS database.
  This file defines the variables that are going to be present in the
  database. Once the database has been created, information from the
  producer definition file is saved into the database, so that access to
  the variable properties is possible without the need of the original
  definition file.

  The way xtract access the variables is by using their names, as they
  are defined in the database. See varnames(5) for more information on
  the syntax used to specify a variable name in the control file.

  All extracted data are rescaled to their physical unit and converted
  to FLOAT before output.

  4.  PARAMETERS

  The control file must define the following parameters:

     year_base: YYYY
        Year base to use for converting time into decimal days.

     dbname: name
        Name (with path) of database to access.

     step_size: n
        Number of profiles to move during each steps.

  5.  OPTIONS

  The different type of files to output is controlled by the options
  listed in the control file. Several output files can be generated by
  declaring several product types and/or repeating repeating them with
  different options. The main options define the kind of file to
  generate. Possibilities are:

     OPTIONS:
        This key word can be used to improve the clarity of the control
        file and specify the beginning of options. It has no effect.
     variable: <product specifications>
        This generates a columnar output with the values of each
        specified variable var in different columns. Several variables
        can be specified by repeating option var.  Variables values are
        listed along columns in the same order they are specified in the
        control file. Lines containing only bad or data outside range
        are not output.

        Product specifications are a list of sub-options. These are:

        <common_options>
           See below for a list of common options.

        var: <variable specifications>
           This option specifies a variable to extract from the
           database. It can be repeated in order to extract data from
           several variables simultaneously.

        end
           This keyword is mandatory and terminates the list of selected
           sub-options.

     profile: <product specifications>
        This options generates a profile file with in the first column
        values corresponding to X variable, all the other columns having
        values from the specified Y variables.  Several Y variables can
        be specified by repeating option Y. Variables values are listed
        along columns in the same order they are specified in the
        control file, except for the X data which appear in the first
        column. Lines with bad X values are not output.

        Product specifications are a list of sub-options. These are:

        <common_options>
           See below for a list of common options.

        X: <variable specifications>
           This option specifies the X variable in the profile.

        Y: <variable specifications>
           This option specifies an Y variable to extract from the
           database. It can be repeated in order to extract data from
           several variables simultaneously.

        end
           This keyword is mandatory and terminates the list of selected
           sub-options.

     contour: <product specifications>
        This options generates a contour file with in the first two
        columns values corresponding to X and Y variables, respectively,
        all other columns having values from the specified Z variables.
        Several Z variables can be specified by repeating option Z.
        Variables values are listed along columns in the same order they
        are specified in the control file, except for X and Y data which
        appear in columns one and two, respectively. Lines with bad X
        orY values are not output.

        Product specifications are a list of sub-options. These are:

        <common_options>

           See below for a list of common options.

        X: <variable specifications>
           This option specifies the X variable in the contour.

        Y: <variable specifications>
           This option specifies the Y variable in the contour.

        Z: <variable specifications>
           This option specifies a Z variable to extract from the
           database. It can be repeated in order to extract data from
           several variables simultaneously.

        end
           This keyword is mandatory and terminates the list of selected
           sub-options.

     end
        This keyword is mandatory and terminates the list of selected
        options.

  6.  VARIABLE SPECIFICATIONS

  Variable specifications are a list of sub-options which is the same
  for each product listed above:

     name: name[:grid specifications]
        Name of variable to access and extract. See varnames(5) for more
        information on the syntax of variable names. A grid
        specification can be appended to the variable name (separate
        both with a colon) in order to extract certain points. Grid
        specifications can be formulated as follows:

        {n1, n2, ... }
           where n? are integers, specifies a grid by bin indexes.

        {r1, r2, ... }
           where r? are floats, specifies a grid by the values of the
           variable itself. This is most useful if applied to variable
           DEPTH for extracting data at specific depths.

        {(t1), r1, ... }
           This option is similar to the previous one, however it
           specifies a tolerance t1 to be applied around the following
           grid points. Tolerance values must be floats and can be
           repeated within the list in order to have different tolerance
           values for different grid points. This option allows to
           extract only data having values near specific ones.

     min= value
        Specifies a minimal threshold for the given variable in order to
        be valid. The value can be either float or a string specifying
        another variable name in the database. In the latter case, the
        value of this variable is used as the threshold value.  This is
        also different in the sense that it is updated for each profile.
        Default is -1.0E38.

     max= value
        This option is similar to option min, but is used for specifying
        a maximal threshold value. Default is 1.0E38.

     scale= value
        This option specifies a scaling factor to be multiplied to the
        extracted data before output. In case threshold values are
        specified with options min and/or max, these are also scaled by
        the same value.  Default is 1.0.

     end
        This keyword is mandatory and terminates the list of selected
        sub-options.

  Specifying threshold values with options min and max are especially
  useful when extracting DEPTH data from a post-processed ADCP dataset.
  Setting the minimal and maximal threshold values to
  ACCESS_VARIABLES.first_good_bin and ACCESS_VARIABLES.last_good_bin,
  respectively, will produce only values of good bins. Note that values
  outside the given ranges are still output, but as bad values.

  Some application require depth data to be negative, but these must be
  positive for some other. Sometimes velocity data must be in cm/s
  instead of m/s. The main purpose of specifying option scale is to
  generate compatible files for these different requirements.

  7.  COMMON OPTIONS

  Options common to the different products are:

     file: file
        Specifies the name for the output file.

     combined
        When several variables are to be extracted, the amount of data
        might not be the same for each of them. Normally, if a variable
        has less data, bad values are output. If this option is
        specified, output will stop when one of the specified variables
        has no more data. See also option undefined

        For the variable product, all specified variables are affected.
        For the profile product, only Y variables are affected. Finally,
        for the contour product, only Z variables are affected.

     no_bad
        This options avoids output of bad data. It affects the same
        variables as those affected by option combined.

     separate
        This option writes a % between each profile written to the
        output file. This can be useful during post-processing for
        retrieving only data from specific profiles.

     undefined
        When several variables of different length have to be output in
        the same file, undefined data can be output as -1.0E38 instead
        of being flagged as bad. See also option combined. This option
        affects the same variables as those affected by option combined.

     longitude_180
        Specify this for converting longitude values between -180 and
        +180 degree before using them.

  8.  TIME RANGES

  Finally, the control file is terminated by a list of time ranges.  See
  time_rng(5) for the syntax of these.

  9.  OUTPUT FILES

  All files specified by the different file options.

  10.  AUTHOR

  Pierre Jaccard, Geophysical Institute, University of Bergen, 1999

