# *********************************************************************
#  Written by and copyright Carlo Strozzi <carlos@linux.it>.
#
#  jointable.txt: help text
#  Copyright (C) 2001 Carlo Strozzi <carlos@linux.it>
#
#  This program is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation; either version 2 of the License, or
#  (at your option) any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You should have received a copy of the GNU General Public License
#  along with this program; if not, write to the Free Software
#  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
#
# *********************************************************************

                      NoSQL operator: jointable

Joins two NoSQL tables on a common field.

Usage: jointable [options] table_1 table_2

Options:
    --tmpfile (-t) 'file'
      Use 'file' as a temporary workarea. If this not specified,
      then the work file is automatically created with mktemp(1)
      and removed and removed with rm(1) at the end, at the cost
      of two system(3) operations. If 'jointable' appears multiple
      times along the same pipeline, a different 'file' must be used
      on each invocation.

    --column (-j) 'column'
      Join on 'column' from both files.

    -1 'column'
      Join on 'column for the first table.

    -2 'column'
      Join on 'column for the second table.

    --help (-h)
      Display this help text.

    --all (-a) 1|2
      In addition to normal output, produce a line for each
      unpairable line in file 1 or 2 respectively.

    --debug (-x)
      Display the join(1) command to STDERR.

    --suppress-join-column (-J)
      Exclude the join column from the output table.

Notes:

The two tables must be sorted alphabetically on the respective join
fields for the operation to function correctly.

Either one or the other, but not both, of the two input tables must
be specified as '-', meaning STDIN. See join(1) for more details
on the meaning of each option. 

If only one of '-1' or '-2' is specified, then the other one
defaults to the first (leftmost) field of the associated table.

Either '-j' or the '-1,-2' options should be specified. If they
are both present, 'join' will try to apply them in a sensible
fashion. Thus, if '-j' comes last it will override both '-1' and
'-2', while if '-j' comes first then '-1,-2' will override the
'-j' specification only for the associated table.

If none of '-j', '-1' or '-2' is specified, then the two tables
are joined on their respective first (leftmost) fields.

If either of the two input tables contain duplicated columns, i.e.
columns with the same name but possibly different values, only the
first (leftmost) one is taken into account. The output will still have
the duplicates, but this time with equal column values.

The following names are reserved to the awk language, and should not
be used to indicate column names:

BEGIN, END, break, continue, else, exit, exp, for, getline, if, in,
index, int, length, log, next, print, printf, split, sprintf, sqrt,
substr, while, and possibly others. See mawk(1) for more on this.

$Id$
