# *********************************************************************
# getrow.txt: help text
# Copyright (c) 2001,2006 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; version 2 dated June, 1991.
#
# 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: getrow.txt,v 1.2 2006/03/10 11:26:13 carlo Exp $

                      NoSQL operator: getrow

Selects rows matching a given AWK expression using column names.

Usage: getrow [options] expression

Options:
    --input (-i) 'file'
      Read input from 'file' instead of STDIN.

    --output (-o) 'file'
      Write output to 'file' instead of STDOUT.

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

    --no-header (-N)
      Remove header from output.

    --debug (-x)
      Display the resulting awk(1) program before running it.

    --not-empty (-e)
      Rows that contain only blanks and/or tabs are excluded
      from output.

    --test (-t)
      Instead of printing the table of matching rows, just print
      '1' if at least one matching row was found, or '0' otherwise.
      This way of returning a result code resembles the one used
      by expr(1).

    --key (-K)
      Instead of printing the complete matching rows, just print
      their first (leftmost) field, supposedly the record key.
      This will save a subsequent call to 'column' if all we
      need is to extract the matching record keys.

    --first-match (-f)
      Print only the first successful match and exit.
      Warning: this option will make the program close the
      input pipeline upon finding the first succesful match.
      This may cause a SIGPIPE and thus a non-zero status from
      the program that is writing to the pipeline itself.

Notes:

If the input table contains duplicated columns, with the same name
but different values, only the first (leftmost) one is taken into
account, but the output table will still have the duplicates with
their different values.

If no expression is specified, then the program exits with an error
message. The awk expression must be properly quoted, to prevent the
shell from parsing it.

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.

Hint: if all you need is to pick records that match a list of primary
keys, then a better/faster alternative would be to use the 'filtertable'
operator, like this:

     filtertable -- grep -f pick_list < input_table

where 'pick_list' is a file containing one key per line, each prepended
by a caret (^) and followed by a TAB, to make sure that it matches the
table leftmost field, that is the primary key.

