# *********************************************************************
# jointable.txt: help text
#
# Copyright (c) 2001,2002,2003 Carlo Strozzi
#
# 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.
#
# *********************************************************************
# $Id: jointable.txt,v 1.4 2003/06/26 01:58:25 tmiller Exp $

                      NoSQL operator: jointable

Joins two NoSQL tables on a common field.

Usage: jointable [options] table_1 table_2

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

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

    --all (-a)
      In addition to normal output, produce a line for each
      unpairable line in table_1 (so called 'outer join').

    --ignore-case (-i)
      Ignore differences in case when  comparing fields.

    --numeric (-n)
      Input files are sorted numerically.

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

Notes:

Unless option '-n' is specified, the two tables must be sorted
alphabetically on the join field 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. 

The join may occur only between equally-named fields from the two
tables. If the requested join column does not exist in either table
the program will exit with an error. There is a good reason for this
restriction: information should be consistent across the whole database.
Joining makes sense only between a primary key from one table and a
foreign key from another table. The two fields are actually the very
same piece of information, so they should always be given the same
name, and that name should be unique. Enforcing this concept leads to
consistent database design.

If no join column is specified, then it defaults to the first (leftmost)
field in 'table_1' (the "master" table"), presumably the primary key
field. If that column does not exist also in the other table (although
usually in other than the first field), then the program will complain.

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.

