.TH report "" "" "/rdb Command"
.PC "Write reports using a form and a table"
\fBreport \fIform \fB< \fItableorlist\fR
.PP
The command
.B report
produces reports, form letters, mailing labels, invoices,
and so forth, for each row in
.IR tableorlist ,
following the template within file
.IR form .
.PP
You must use a text editor to fill out
.I form
to determine how the form will appear.
Insert column names from
.I tableorlist
between angle brackets (< >)
where you want the data to appear within the report.
.PP
You can even call shell commands from within a form,
pass them data from
.IR tableorlist ,
print their output within your formatted form.
This is a powerful extension to COHERENT shell programming.
.PP
.B report
mostly replaces the older commands
.B label
and
.BR letter .
These commands are still part of
.BR /rdb ,
in part for compatibility with older versions, and in part as examples
of shell programming.
.SH "Form Syntax"
The following describes the format of a form:
.IP "\fIregular text\fR"
.B form
prints any characters in your form that do not match the symbols
shown below.
.IP "\fI<column-name>\fR"
Angle brackets indicate that data from
.I "column-name"
in the current row of
.I tableorlist
should be inserted in place of the column name.
.IP "\fI<!command!>\fR"
Angle brackets and exclamation points indicate that the shell is to execute
.IR command .
Any output from
.I command
appears at this point in the report.
.IP "\fI<!cmd <col>!>\fR"
This is an insertion within a command.
The data from column
.I col
in the current row of
.I tableorlist
are passed to
.IR cmd .
This passes the contents of
.I col
as an argument to
.IR command .
The output of
.I command
then replaces this entry within the form.
.PP
If
.B report
does not recognize a column name, it prints
.I "<column-name>"
as if it were normal text.
This allows you to use the angle brackets as literal characters within your
form, if you wish.
It also helps you debug your form:
if the data from the table are not replacing
.IR "<column-name>" ,
then
.I "column-name"
does not exactly match the column name in the table.
Check for spelling errors, upper- and lower-case discrepancies,
embedded blanks, and nonprinting characters.
.SH Example
Consider table
.BR maillist ,
as follows:
.DM
Name    Ronald McDonald
Company McDonald's
Street  123 Mac Attack
City    Memphis
State   TENN
ZIP     30000
Phone   (111) 222-3333
.DE
.DM
Name    Chiquita  Banana
Company United Brands
Street  Uno Avenido de la Reforma
City    San Jose
State   Costa Rica
ZIP     123456789
Phone   1234
.DE
.PP
You could use an editor to develop a form like the following:
.DM
<Name>
<Company>
<Street>
< City >, <State>  <ZIP>
.DE
.DM
Hi <  Name >:
.sp \n(pDu
The date and time is <!date!>
.sp \n(pDu
We are also sending this letter to:
.sp \n(pDu
<! column Name City < mailtable | row 'Name != "<Name>"' | justify !>
Bye <! echo <Name> !>
.DE
.PP
Note that we have used all three types of inserts:
column name, command, and command insert.
Now with these two files ready, you only need type
.DM
	report form < maillist
.DE
.PP
to see the following output:
.B1
Ronald McDonald
McDonald's
123 Mac Attack
Memphis, TENN  30000
.sp
Hi Ronald McDonald:
.sp \n(pDu
The date and time is Wed Aug 19 01:58:19 PST 1983
.sp \n(pDu
We are also sending this letter to:
.sp
Name            City   
--------------- -------
Chiquita Banana San Jose
.sp \n(pDu
Bye Ronald McDonald
.B2
.PP
.B1
Chiquita  Banana
United Brands
Uno Avenido de la Reforma
San Jose, Costa Rica  123456789
.sp \n(pDu
Hi Chiquita  Banana:
.sp \n(pDu
The date and time is Wed Aug 19 01:58:40 PST 1983
.sp \n(pDu
We are also sending this letter to:
.sp \n(pDu
Name            City   
--------------- -------
Ronald McDonald Memphis
.sp \n(pDu
Bye Chiquita  Banana
.B2
.PP
Some users have noted that the shell escape places an
extra line in the output.
If you don't want the extra line say something like:
.DM
	<! echo -n `date` !>
.DE
.SH "See Also"
.B
label,
letter
.R
.br
COHERENT Lexicon:
.B
echo
.R