Updated for version 3.8.8

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.

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.

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

freeform_handler is a data handler which uses National Geophysical Data
Center's FreeForm/FFND API to serve data. To use with the Hyrax, you'll
need BES 3.13.0 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.

Customizations for Remote Sensing Systems (RSS) Data files

Two parameters in the configuration file control features that enable
using data from RSS. The parameter FF.RSSFormatSupport is used to 
activate parsing the RSS-format-specific .fmt files. The parameter
FF.RSSFormatFiles is used to specify a directory other than the data 
where the .fmt (and optional ancillary .das files) will be found. If 
this is not given or is the empty string, the handler will look in the
same directory as the data. If it is given, the handler will look _only_
in the specified directory.

FF.RSSFormatSupport = yes
FF.RSSFormatFiles = /usr/local/RSS


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>

4) The FreeForm library contains a useful data processing/transformation 
library. Here's an example of how to tweak data written on a big-endian
machine so it can be served from a little-endian one - include the following
at the start of the format file:

<code>
input_eqv begin constant
    data_byte_order text big_endian
end constant 
</code>

Thanks to Denis Nadeau for this information.

For more examples see the test files in the ff-test subdirectory. There is
a manual that describes FreeForm and handler on our web page - opendap.org -
in the User Documentation section.      

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

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>