
$Id: README 14237 2006-07-20 16:49:07Z jimg $

This is the OPeNDAP HDF4 Data Handler. It is used along with the OPeNDAP
DAP Server.

For information about building the OPeNDAP netCDF Data Handler, see the
INSTALL file.

This data handler is component of the OPeNDAP DAP Server; the server base
software is designed to allow any number of handlers to be configured easily.
See the DAP Server README and INSTALL files for information about
configuration, including how to use this handler.

Copyright information:
This software was originally written at JPL as part of the DODS NASA ESIP
Federation Cooperative Agreement Notice. The original copyright described 
free use of the software 'for research purposes' although it was not clear 
what exactly those were. In Spring of 2003 we (OPeNDAP) sought clarification
of that language and JPL/CalTech asked us to change to the copyright text
now included in the code. 

In Fall of 2005 we decided to release the software under the LGPL, based on a
previous discussion with personnel at JPL.

James Gallagher
Updated 9/22/2005 

Support for HDF data types:
    HDF Version:  This release of the server supports HDF4.2r1. 
    SDS:          This is mapped to a DAP2 Grid (if it has a dimension 
                  scale) or Array (if it lacks a dim scale).  
    Raster image: This is read via the HDF 4.0 General Raster
                  interface and is mapped to Array.  Each
                  component of a raster is mapped to a new dimension
                  labelled accordingly. For example, a 2-dimensional,
                  3-component raster is mapped to an  m x n x 3
                  Array. 
    Vdata:        This is mapped to a Sequence, each element of
                  which is a Structure.  Each subfield of the
                  Vdata is mapped to an element of the Structure.
                  Thus a Vdata with one field of order 3 would be
                  mapped to a Sequence of 1 Structure containing 3
                  base types.
    Attributes:   HDF attributes on SDS, rasters are
                  straight-forwardly mapped to DAP attributes (HDF
                  doesn't yet support Vdata attributes).  File
                  attributes (both SDS, raster) are mapped as
                  attributes of a DAP variable called "HDF_GLOBAL" (by
                  analogy to the way DAP handles netCDF global
                  attributes, i.e., attaching them to "NC_GLOBAL").  
    Annotations:  HDF file annotations mapped in the DAP to attribute 
                  values of type "String" attached to the fake DAP
                  variable named "HDF_ANNOT".  HDF annotations on
                  objects are currently not read by the server. 
    Vgroups:      Vgroups are straight-forwardly mapped to 
                  Structures.

Special characters in HDF identifiers:
  - A number of non-alphanumeric characters (e.g., space, #, +, -)
    used in HDF identifiers are not allowed in the names of DAP
    objects, object components or in URLs.  The HDF4 data handler
    therefore deals internally with translated versions of these
    identifiers.  To translate the WWW convention of escaping such
    characters by replacing them with "%" followed by the hexadecimal
    value of their ASCII code is used.  For example, "Raster Image #1"
    becomes "Raster%20Image%20%231".  These translations should be
    transparent to users of the server (but they will be visible in
    the DDS, DAS and in any applications which use a client that does
    not translate the identifiers back to their original form).   

Known problems:

Handling of floating point attributes:
  - Because the DAP software encodes attribute values as ASCII
    strings there will be a loss of accuracy for floating point
    attributes.  This loss of accuracy is dependent on the version of
    the C++ I/O library used in compiling the DODS software (i.e., the
    amount of floating point precision is preserved when outputting to
    ASCII is dependent on the library).  Typically it is very small
    (e.g., at least six decimal places are preserved).

Handling of global attributes:
  - The server will merge the separate global attributes for the SD,
    GR interfaces with any file annotations into one set of global
    attributes.  These will then be available through any of the
    global attribute access functions.
  - If the client opens a constrained dataset (e.g., in SDstart), any
    global attributes of the unconstrained dataset will not be
    accessible because the constraint creates a "virtual dataset"
    which is a subset of the original unconstrained dataset.

Todd Karakashian (Todd.K.Karakashian@jpl.nasa.gov)
Isaac Henry (ike@seanet.jpl.nasa.gov)
Jake Hamby (Jake.Hamby@jpl.nasa.gov)

NASA/JPL April 1998
