FormRead

FormRead is an Internet utility and a helper for Netscape Navigator; it allows to interpret, read and possibly format as desired informations contained in a form, sent through method "POST" at an e-mail address; this makes it very interesting both for personal use and as a stage in a CGI script chain.

Type

Utility for Dos/Windows/Unix; freeware/GNU General Public License 2.0.

Version

1.2 / english.

Description

This program allows to read a form received as application/x-www-form-urlencoded which was sent through <form action="mailto:somebody@somewhere.on.the.web" method="POST">.
"Read" the form is just one of its uses; actually, FormRead can be used to transform templates by replacing field names with the corresponding values received, or to produce an html representation of the received data.
Without this program, if you wanted to process a form, you'd have to either write or dig up routines to translate the values of the form's fields from "URL encoding" to whatever your program required. This was a hassle in C, and a real pain in the shell. Which is where FormRead comes in. It decodes all the form fields and sticks them into your template for easy perusal by a shell script, a C program, a Perl script, or whatever you like, then executes whatever viewer or program you specify. FormRead can be used as a helper for Netscape Navigator, and is shipped with full source code that can be compiled with Borland C and GCC.

Requirements

• Windows system (Netscape helper);
• standard C compiler (Unix/Linux usage).

Features

An example is the easiest way to demonstrate formread's use. Suppose you have the following in an HTML file:

<form method="POST" action="mailto:somebody@somewhere.on.the.web" >
<input type="hidden" name="Form_Name" value="bugrep">
What's your name?
<input type=text size=30 name=name>
<p>
Type some comments.
<br>
<textarea name=_comments rows=10 cols=60></textarea>
What problem are you having? <select name=problem multiple>
<option> Sleeplessness
<option> Unruly goat
<option> Limousine overcrowding
</select>
<p>
<input type=submit value=" Send 'em in! ">
</form>

When the user selects the "Send 'em in!" button, a mail will be sent to somebody@somewhere.on.the.web which contains form data edited by the user. Suppose that 'somebody' is you, and you want to read form data.
If you click on the attachment of the mail you received, you'll get a strangely formatted string that resembles what the sender has introduced in the form fields. FormRead let you read the data in a more intellegible format. To achieve this, you must configure FormRead as helper application in Netscape->General Preferences->Helpers, by adding the type:

Mime type: application
Mime subtype: x-www-form-urlencoded

and setting "Launch the application" to the pathname of FormRead.

FormRead has the following syntax:

FormRead [-u | -m | -t] [-h | -n] [-o dest | -d dir] [-e ext] filename

Here is an explanation of the parameters:

-o Save report to file 'dest': reader is not invoked
-d Save report in dir: a unique file name is used with the mask 'formXX.XXX'
-e Set output file extension; default is '.txt' for text files and '.htm' if HTML filter is active

-u Unix format (lines end with CR)
-m Macintosh format (lines end with LF)
-t Dos format (lines end with CR+LF, default)

-h HTML filter
-n disable HTML filter

The hidden field Form_Name (after the <form ..> definition in HTML source at the beginning of this section) specify the template to be used by FormRead to format the data and the configuration to be used.
In this case, the template used is 'bugrep.frt' and the configuration file is 'bugrep.frr'.

The configuration file is simply a text file containing two definitions:

READER: program
FORCEPAR: parameter(s)

The READER is the program to run against the formatted data to let the user read them. The FORCEPAR field contains additional parameters that can be used to override command line arguments.

Both 'bugrep.frt' and 'bugrep.frr' must reside in FormRead's directory. If the template is not found or Form_Name is not specified, a standard text file with the following layout is used:

field: value

Text format is ruled by parameters -u/-m/-t; the default is Dos text (each line ended by CR+LF, parameter -t); with -u lines are ended by LF alone and with -m by CR alone. If the additional parameter -h is specified, text is filtered with HTML, to produce a tabular representation; by default, this filter is off (parameter -n).

A template can contain everything, except null characters (ascii 0); each occurrence of field names is replaced by their respective values, and no other data is appended. Thus, parameters -u/-m/-t and -h/-n are only meaningful for those forms which have no template file. It is important to use field names that cannot occur in the text introduced by the user, since replacement takes place with several passages (one for each field).

If no Form_Name field is present or, in this case, 'bugrep.frr' is not found, FormRead use the settings stored in 'default.frr'.

IMPORTANT! You must create a file named 'default.frr' in the directory of FormRead and write in it at least the line:

READER: program

where 'program' is the standard application to be run against the formatted data. This can be a text viewer, or even the same Netscape. In this case, add the line:

FORCEPAR: -h -e .htm

to force html processing and set output extension to '.htm'. Otherwise, you could add parameter -h at the end of the pathname in the "Launch the application" field, while configuring Netscape.

If you don't want to use FormRead as helper, but you want to save transformed data to a file for later use, specify the parameter -o, followed by the name of the file to store data.

By using a CGI script that changes the parameter following -o, you can use FormRead to save all forms received and transformed in a certain directory. The same result can be achieved by using parameter '-d' and specifying an existing directory (both with or without ending slash/backslash); all the files saved in this way have the format 'formXX.XXX', where each 'X' is replaced with 'A'-'Z'. Be aware that FormRead does not check for the existance of the directory.

Errors can only happen when data file is opened; in this case, an error message is printed and displayed with the viewer, reporting the kind of error. All other errors are simply ignored (but should never happen, on normal conditions).

By default, formatted data is saved in FormRead's directory to 'formdata.txt' (or 'formdata.htm' if HTML filter is active, or 'formdata' + extension specified with parameter -e). This file is not removed when FormRead ends, but is overwritten at each call. This is useful under Windows 95, because when you run a Windows app from a Dos app the Dos app does NOT wait for the Windows app to end before continuing.

Download

Download FormRead (version 1.2 for Dos/Windows)

Download FormRead (version 1.2 for Unix)

Top of page