.TH row "" "" "/rdb Command"
.PC "Make a new table where rows match logical condition"
\fBrow '\fIcolumn condition column-or-value ..\fB' < \fItable\fR
.PP
.II "table^split"
.II "table^create new"
.II "row^select via expression"
The command
.B row
creates a new table from
.IR table .
The new table
consists of only those rows that meet
.IR condition .
.PP
.B row
uses a script written in the
.B awk
language, which gives you great power for specifying the logical condition.
.PP
Several conditional expressions can be combined with the
logical AND (&&) and OR (||) operators.
Because the logical conditions are represented by special characters,
they must be enclosed by apostrophes, to protect them from being
interpreted by the shell.
If you have special characters within a column name,
enclose the column name in quotation marks.
.SH Example
First a simple example.
Consider table
.B inventory :
.DM
Item    Onhand  Cost    Value   Description
----    ------  ----    -----   -----------
1       3       5       15      rubber gloves
2       100     1       100     test tubes
3       5       8       40      clamps
4       23      2       51      plates
5       99      2       97      cleaning cloth 
6       89      18      1602    bunsen burners 
7       5       175     875     scales
.DE
.PP
To make a table of all of the parts that cost more that $5, type:
.DM
	row 'Cost > 5' < inventory
.DE
.PP
The new table appears as follows:
.DM
Item    Onhand  Cost    Value   Description
----    ------  ----    -----   -----------
3       5       8       40      clamps
6       89      18      1602    bunsen burners
7       5       175     875     scales
.DE
.PP
Now a more complex example.
If you want a table of all the burners
and of all of the items of which we have fewer than ten in stock, type:
.DM
	row 'Description ~ /burner/ || Onhand < 10' < inventory
.DE
.PP
The new table appears as follows:
.DM
Item    Onhand  Cost    Value   Description
----    ------  ----    -----   -----------
1       3       5       15      rubber gloves
3       5       8       40      clamps
6       89      18      1602    bunsen burners
7       5       175     875     scales
.DE
.PP
The string
.B "~ /burner/"
searches for the string ``burner'' anywhere in the column.
The double pipe (||) means logical OR.
.SH "Column Names"
The commands
.BR row ,
.BR compute ,
and
.B validate
recognize column names as upper- and lower-case letters,
digits, and the underscore `_'.
The regular expression is [A-Za-z0-9_].
If you have any other characters in your column names, put
apostrophes or quotation marks around them.
.PP
.B row
compares the recognized strings with the table's head line.
Only if it finds a match does it convert the string
to the \fB$1, $2...\fR column positions that
.B awk
needs.
.SH "awk's Reserved Words"
.B awk
is the pattern-scanning language that does all of the work for the
commands
.BR row ,
.BR compute ,
and
.BR validate .
.PP
.B awk
recognizes the following words as having special significance.
If you name a columns with any of these reserved words
and then try to use them in a query, the
.B /rdb
commands that are built around
.B awk
turn them into column positions and
.B awk
does not see them.
It is best to avoid these names as column heads or simply
capitalize the first letter of each of your column names.
.PP
This list also indicates the many functions you have with
.BR awk .
However, do not rely on the following descriptions.
The tutorial section of
your COHERENT manual contains a summary of the
.B awk
language.
.PP
Please note that this list of
.B awk
functions and reserved words comes from UNIX System V.
Other implementations of
.B awk
may not contain all of these functions.
.DM
.ta 1.5i
\fIReserved Word	Description\fR
.tc .
\fBBEGIN\fR	Pattern that matches before first input record
\fBEND\fR	Pattern that matches after last input record
\fBbreak\fR	Exit the nearest \fBfor\fR or \fBwhile\fR loop
\fBcontinue\fR	Go to next iteration of \fBfor\fR or \fBwhile\fR loop
\fBelse\fR	Used in \fBif then else\fR expression
\fBexit\fR	Leave program entirely, as if at end of input
\fBexp\fR	Raise number to a power
\fBfor\fR	\fBfor (\fIexpression\fB ; \fIcondition\fB; \fIexpression\fB)\fR
\fBgetline\fR	Get next input line
\fBif\fR	\fBif (\fIcondition\fB) \fIstatement \fB[else \fIstatement\fB]\fR
\fBin\fR	\fBfor (\fIvariable \fBin \fIarray\fB) \fIstatement\fR
\fBindex\fR	\fBindex ( \fIstring1\fB, \fIstring2 \fB)\fR
\fBint\fR	Truncate argument to integer
\fBlength\fR	Return current line length, or length of argument
\fBlog\fR	Return log (to base 2) of argument
\fBnext\fR	Skip to next record and reexecute all commands
\fBprint\fR	Output variables
\fBprintf\fR	\fBprintf ("\fIformat\fB", \fIvariable\fB, ... )\fR
\fBsplit\fR	\fBsplit (\fIstring\fB, \fIarrayname\fB, \fIseparator\fB)\fR
\fBsprintf\fR	\fBsprintf ("\fIformat\fB", \fIvariable, ... \fB)\fR
\fBsqrt\fR	Return square root of argument
\fBsubstr\fR	\fBsubstr ( \fIstring\fB, \fIstart\fB, \fInumber \fB)\fR
\fBwhile\fR	\fBwhile ( \fIcondition\fB ) \fIstatement\fR
.tc
.DE
.PP
Although
.B row
is built around the
.B awk
language,
.B row
has the advantage of knowing about the names of the columns.
Therefore, you can use column names instead
of column positional numbers.
To grasp the full power of
.B row
and
.BR compute ,
read the COHERENT manual's tutorial on
.BR awk .
.SH "Case of Column Names"
.I "(Ruby re-creation only.)"
Column names are case sensitive, as in the original
.BR /rdb .
If the environment variable
.B RDB_ICASE
is set to 1, upper and lower case are ignored when column names are looked up.
An exact match always wins;
if several columns differ only in case, the command stops with an
.I ambiguous
error.
Names that are also
.B awk
reserved words or are followed by
.B (
are never taken for columns.
.SH "See Also"
.B
compute,
row,
select,
validate
.R
.br
COHERENT Tutorials:
.B
Introduction to the awk Language
.R