.TH screen "" "" "/rdb Command"
.PC "Convert a form into a screen-input shell program"
\fBscreen  < \fIform\fB > \fIshellprogram\fR
.PP
.II "screen^make input form"
The command
.B screen
reads
.I form
and writes a COHERENT shell program that paints the screen and reads
a user's input.
Because the output of
.B screen
is a shell script, you can edit it to validate data,
read data and write it onto the screen, and so on.
.I form
must be in the same format as described in the manual entry for the command
.BR report .
.PP
.B screen
writes a simple shell script.
The script works ``as is'' to read data
typed onto the screen and to write a standard table.
It uses the
.B /rdb
command
.B cursor
to move to each input field on the screen.
.PP
A script output by
.B screen
can be used in many ways.
You can use it as a form, to enter data into a new table.
You can edit the script to have it append its output into an
existing table,
to pass its data via a pipe to another command, or to read
data from a table and display them on the screen.
Commands can be edited into the screen-form script.
You can add calls to the
.B /rdb
command
.BR validate ,
to confirm that the user has added data that are at least sensible.
You can even embed the script within another shell script, to perform
screen entry for it.
.SH "Setup Steps"
To create a screen-entry form, do the following:
.IP \fB1.\fR
Use your text editor to write the screen-form file.
.IP \fB2.\fR
Run
.B screen
to read the form file.
Redirect its output into the file in which you wish to store the form's
executable script.
.IP \fB3.\fR
Edit the shell script to meet your requirements,
such as adding validation, record locking, and so forth.
.IP \fB4.\fR
Run the executable shell script to input data and write a new table.
.SH Example
A simple form looks like this:
.DM
                           Mail List Entry Form
                       <!date!>
.sp \n(pDu
Name  : <Name>             Company: <Company>
Street: <Street>
City  : <City>             State  : <State>       ZIP: <ZIP>
Phone : <Phone>
.DE
.PP
Everything is written to the screen except what is between angle brackets
``<>'', which are variables to be input.
Exclamation marks within angle brackets (e.g., \fB<!date!>\fR)
mark commands to execute when the program is running.
.PP
When
.B screen
reads the above form and compiles it, it writes the following shell script:
.DM
: paint crt screen
exec 1>/dev/tty
cat <<SCREEN
${CLEAR}                           Mail List Entry Form
.DE
.DM
Name  :                    Company:          
Street:         
City  :                    State  :               ZIP:      
Phone :        
.DE
.DM
SCREEN
.sp \n(pDu
: read user input
cursor  1 23 ; date;
cursor  3  8 ; read Name;
cursor  3 36 ; read Company;
cursor  4  8 ; read Street;
cursor  5  8 ; read City;
cursor  5 36 ; read State;
cursor  5 55 ; read ZIP;
cursor  6  8 ; read Phone;
.DE
.DM
: output table head
exec 1>&2
echo "Name  Company  Street  City  State  ZIP  Phone"
echo "----  -------  ------  ----  -----  ---  -----"
: append row
echo "$Name  $Company  $Street  $City  $State  $ZIP  $Phone"
.DE
.PP
This shell progam is in three parts, each introduced by a comment:
.IP "\fBpaint crt screen\fR"
This section clears the screen, then paints the form onto it.
.IP "\fBread user input\fR"
This section
moves the cursor to each input field, then waits for
the user to enter a string of characters.
Each field is linked to a column; that is, what the user types in that field
will be written into the column to which the field is linked.
.IP "\fBoutput table head\fR"
The final section writes the new table in standard
.B /rdb
format; that is, a column header followed by the row of data entered by the
user.
.PP
To let you use the screen program in a pipe,
the generated commands send the interactive output to the screen through the
standard output temporarily tied to
.BR /dev/tty ,
and to the output table through the standard-error device.
To accomodate COHERENT's implementation of 
.BR exec ,
you must tie the standard error to the standard output
when you run the script screen has created.
For example
.DM
	mail.s > mail.t 2>&1 
.DE
.PP
The following shows the form compiled above, with example data:
.B1
                           Mail List Entry Form
                      Wed Sep  4 14:09:30 EDT 1987
.sp
Name  : Hi Ho              Company:          
Street: 1st St.
City  : LA                 State  : CA            ZIP: 90024      
Phone : 213-555-1212
.B2
.PP
The above input creates the following table:
.PP
.DM
Name    Company Street  City    State   ZIP     Phone
----    ------- ------  ----    -----   ---     -----
Hi Ho   HH Inc. 1st St. LA      CA      90024   213-555-1212
.DE
.PP
You can redirect output into a file or pipe.
Here, it was directed into table
.BR mail.t .
You can use this table as its stands alone,
or you can append it to another table by by piping it to the
.B append
command.
For example:
.DM
	mail.s 2>&1 | append mail.t
.DE
.SH "See Also"
.B
cursor,
lock,
unlock,
validate
.R
.br
COHERENT Lexicon:
.B
cat,
echo,
exec,
ksh,
read,
sh
.R