
	$Id: README 18161 2008-02-26 19:31:31Z pwest $

For information about building the FreeForm data handler, see the
INSTALL file.

This file provides basic information about the FreeForm handler and its
configuration. For more detailed information, see the Server
Installation Guide at http://www.opendap.org. Also note that there is
also a special manual for the FreeForm server that covers writing
format description files in detail available at the OPeNDAP web site.

For general information about configuration of the base software for
the OPeNDAP server, see the README that comes with that server and/or
the Server Installation Guide that can be found at www.opendap.org.

A configuration edition helper script, `bes-ff-data.sh' is provided in
this package for easy configuration of the Hyrax BES server, designed
to edit bes.conf. The script is called using:

<code>
   bes-ff-data.sh [<bes.conf file to modify> [<bes modules dir>]]
</code>
 
The `bes-conf' make target runs the script while trying to select paths
cleverly, and should be called using:

<code>
   make bes-conf
</code>

Test data are also installed, so after installing this handler, Hyrax
will have data to serve providing an easy way to test your new
installation and to see how a working bes.conf should look. To use
this, make sure that you first install the bes, and that dap-server
gets installed too.  Finally, every time you install or reinstall
handlers, make sure to restart the BES and OLFS.

--------------------------------------------------------------------------

dap_ff_handler is a data handler which uses National Geophysical Data
Center's FreeForm/FFND to serve data. The handler requires the OPeNDAP
dap-server software above version 3.7.5. To use with the BES, you'll
need BES 3.4.1 or greater.

The handler can read binary, ASCII, and dBASE data files using
FreeForm/FFND format descriptions. It can return both array and
sequence data types. The data in the data file is read then served
using the appropriate type according to the format description in the
required accompanying format file.

All the data and associated blocks (header information) are processed.
Basic information about the input file is given as Global Attributes as
is any header information. The file's data variables are mapped into
the closest DAP variable type using the FreeForm/FFND external format
file.

WRITING FORMAT DESCRIPTION FILES

Any data file served must be accompanied by a format description file
(<file_name>.fmt). The format description file defines the formats of
headers and data in the data file. The following shows a few examples
of data description files and their translation into DAP variables, for
more information about format descriptions, please see the
OPeNDAP-FreeFrom's user guide.

1) Format to read a dBASE sequence file 
   
<code>
       dbase_input_data "ISEE3_data"
       t 1 15 double 6
       Bx 16 30 double 6
       By 31 45 double 6
       Bz 46 60 double 6
       Bx2 61 75 double 6
</code>

   The above format file will map into the following DAP data set:

<code>
     Dataset {
       Sequence {
        Float64 t;
        Float64 Bx;
        Float64 By;
        Float64 Bz;
        Float64 Bx2;
       } ISEE3_data;
     } test5;
</code>


2) Format to read a binary array file

<code>
   binary_input_data "array_in"
   x 1 4 ARRAY["lat" 1 to 10]["lon" 1 to 10] of int32 0
   y 5 12 ARRAY["records" 1 to 10] of float64 15
</code>

   The above format file will map into the following DAP data set:

<code>
   Dataset {
      Int32 x[lat = 10][lon = 10];
      Float64 y[records = 10];
   } test3;
</code>


3) Format to read an ASCII sequence with a file header

<code>
      ASCII_file_header "header"
      count 1 2 short 0
      description 4 24 char 0

      ASCII_input_data "data"
      value 1 2 short 0
</code>

   The above format file will map into the following DAP data set:

<code>
       Dataset {
	  Sequence {
	  Int32 value;
	  } data;
	} test0;
</code>

For more examples see the test files in the ff-test subdirectory.         

--------------------------------------------------------------------------

Note: The FreeForm library, which is in the subdirectory 'FFND,' carries
the following notice regarding its copyright protection:

<code>
 * CAVEAT:
 * No claims are made as to the suitability of the accompanying
 * source code for any purpose.  Although this source code has been
 * used by the NOAA, no warranty, expressed or implied, is made by
 * NOAA or the United States Government as to the accuracy and
 * functioning of this source code, nor shall the fact of distribution
 * constitute any such endorsement, and no responsibility is assumed
 * by NOAA in connection therewith.  The source code contained
 * within was developed by an agency of the U.S. Government.
 * NOAA's National Geophysical Data Center has no objection to the
 * use of this source code for any purpose since it is not subject to
 * copyright protection in the U.S.  If this source code is incorporated
 * into other software, a statement identifying this source code may be
 * required under 17 U.S.C. 403 to appear with any copyright notice.
</code>

