Release Notes for OPeNDAP/DODS C++ 3.4
                         Release Candidate 5
			     13 October 2003

Release candidates are not considered stable releases. Please treat it
accordingly (e.g., not installing as your operational system, expect
some bugs and report any you find).

New features and major bug fixes are listed below. Complete
documentation of the DODS system can be found on the DODS home page:

                http://unidata.ucar.edu/packages/dods

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

NEW FEATURES (detail follows)

Code changes
   1.  Using libcurl instead of libwww.
   2.  URL dereferencing done with curl instead of Perl.
   3.  C++ DAP is now thread-safe.
   4.  New interface for DAS and DDS classes.
   5.  Core compiles with gcc 3.2.1, Visual C++ 6.0 and gcc 2.95.
   6.  Bug fixes
   6a. Server and client code can once again deal with
       compressed responses.
   6b. Rolled new netCDF fix into nc-dods. This fixes an issue
       with performance seen with data on NFS mounted disks.
   6c. Fixed some cacheing bugs.
   6d. Added the methods Float32::value() and Float64::value().
   6e. fixed bugs in HTTPConnect.
   6f. Change aclocal.m4 to detect multiple version of matlab or idl lib due to 
       different architecture.
   6g. Added some missing nc FORTRAN wrapper.

Client usage changes
   7.  Passwords can be included in URLs.
   8.  Digest authentication is now supported.
   8a. Client-side caching is off by default, but old .dodsrc files may have
       it _on_ by default.

Server usage changes
   9.  dods.rc
   10. A smart time-out capability has been added to the servers.
   11. statistics

New software
   12. OPeNDAP AIS prototype is available
   13. netCDF client and server upgraded
   14. DODSter module added to emulate the MODster software.

Server usage notes
   15. Compression and caching decompressed files.
   16. Register your data set(s).
   17. Prettifying the DODS Directory response.

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

CODE CHANGES

 1. The DODS core now links to libcurl instead of libwww for WWW
    functions.  The libcurl library is smaller than libwww, is being
    actively developed, and is MT-safe.

 2. The server dispatch scripts no longer use the Perl HTTP, MIME and
    LWP classes.  Instead, URL dereferencing is done with curl, a
    freestanding binary that is part of the libcurl build.

 3. The core software is now multi-thread safe. 

 4. The interface to several important classes has been augmented.
    The DAS and DDS classes have a new set of interfaces so that STL
    iterators can be used to manipulate their contents.  The Old Pix
    interfaces are still present, although uses of Pix that rely on
    those objects being void pointers may fail in certain
    circumstances.

    To write out the names of all the variables in a DDS, you would use 
    Pix code like this:

       for (Pix p = dds.first_var(); p; dds.next_var(p)) {
           cout << dds.var(p)->name() << endl;
       }

    Using the STL for the same purpose, you would do this:

       for (DDS::Vars_iter i = dds.begin_var(); 1 != dds.end_var(); ++i) {
           cout << (*i)->name() << endl;
       }

    There have also been some additions to the DAS, DDS and AttrTable
    that make it easier for non-C++ programs to traverse those
    containers.

    For example, in the DDS class, we have the new method:

       Vars_iter get_vars_iter(int i);

    In AttrTable we have:

       Attr_iter get_attr_iter(int i);

    Both of these make it possible to access members of the DDS and
    DAS containers from C code using a simple integer index. This is
    important because C programs cannot create the fancy STL iterator
    objects.  (They can fake a Pix pointer, but this leads to problems
    and should not be done.)

 5. The C++ DAP now builds with gcc 3.2.1, in addition to gcc 2.95 and
    Visual C++ 6.0.  These are the compiler versions that have been
    tested.  Other versions may also work.  Other compilers may also
    work as long as they support the STL (Standard Template Library).

 6. Server bug fixes have included fixes to Sequence constraint
    behavior, the Grid constraint expression function, and memory
    leaks.

    The grid() server-side function is now part of all servers.
    Suppose you have a Grid variable SST that looks like:

       Grid {
         Array:
           Byte SST[lat=1024][lon=1024];
         Maps:
           Float64 lat[1024];
	   Float64 lon[1024];
       } SST;

    You can use the following constraints:

       ?grid(SST,"lat>10.0","lat<20.0")

    Returns the part where "lat" is between 10.0 and 20.0.  All the
    "lon" values are returned.

       ?grid(SST,"10.0<lat<20.0")

    This does the same thing, with a simpler syntax.
 
       ?grid(SST,"10.0<lat<20.0","-80.0<lon<-30.0")

    This returns the part of the Grid falling in the specified
    latitude/longitude box.

    The grid() function operates under the following restrictions: The
    map vectors must be monotonic for the selected Grid.  The quoted
    expressions must contain only the names of map vectors of the
    Grid, constants and relational operators.

    The function does not take into account the special
    characteristics of latitude and longitude. If map vectors wrap in
    an odd way, the behavior of grid() may not be what you expect. 

    Note: This is not a geoselection function.  Map vectors may be
      composed of any of the simple DAP types.  (Like strings, for
      example.) 

6a. Server and client code can once again deal with compressed
    responses. The libcurl library did not initially handle compressed
    responses. After some OPeNDAP contributed enhancements were added
    to libcurl it now supports compressed responses. 

6b. Rolled a new netCDF fix into the nc-dods code. This fixes an issue
    with performance seen when reading data on NFS mounted disks. The
    fix involved removing unneeded nc_sync() calls.

6c. Fixed cacheing bugs involving inability to create a .dods_cache
    directory in a writable directory and not using DODS_CONF
    settings.


CLIENT USAGE CHANGES

 7. The DODS core now supports the (nonstandard) password-in-URL
    syntax.  If you are accessing a password-protected data set, you
    can include your user name and password directly in the URL like
    so: 

      http://user:password@dods.org/cgi-bin/nph-nc/data.nc

    Including a password in the URL allows the user to avoid the extra
    overhead of the authentication dialog box that was the only option
    in earlier releases.

 8. Digest authentication is now supported.

 8a. In older (3.3) versions, caching was on by default. This sometimes leads
    to unexpected behavior, so the default has been changed to off. If you
    want to change this, set the value of USE_CACHE to 1 in your .dodsrc
    file. However, please note that if you already have a ~/.dodsrc file
    (e.g., from an older version of DODS/OPeNDAP) then caching may be on.
    Also note that a bug in 3.4RC3 and previous _ignored_ the value of
    USE_CACHE. This bug has been fixed in 3.4RC4

SERVER USAGE CHANGES

 9. The name of the server configuration file has been changed from
    dods.ini to dods.rc. The dods.rc server config file is a real
    server config file; i.e., there's no longer any need to edit the
    Perl scripts. 

10. A smart time-out capability has been added to the servers. It is
    configurable using the dods.rc file (the default is to never
    time out). This addresses a bug where a server fails to exit when
    a client has been killed.

11. A new feature of the servers allows the DODS project to gather
    access statistics from sites who choose to allow it.  During the
    installation process (via the installServer script), the server
    administrator is asked for permission to gather this data.  If
    permission is granted, the server will return DODS access data (no
    other data is provided) to queries that emanate from one of the
    official DODS web sites.  The statistics feature refers only to
    DODS server accesses, not to any accesses of other web content.

    Note: The DODS project understands that allowing access to the
      DODS/DAP server's usage information might not be acceptable to
      some server administrators. However, allowing us access to the
      server's usage information will help us direct future software
      development efforts. If you choose to enable this feature, only
      the local host and official DODS/OPeNDAP machines will be able
      to gain access to the statistical information.

    The file $DODS_ROOT/etc/INSTALL-servers contains more information
    about what data is gathered and how to configure or disable this
    feature.


NEW SOFTWARE

12. A very early prototype Ancillary Information Server (AIS) is
    available.  This version is for concept testing, and is likely to
    contain bugs and need substantial improvement.  However, the DODS
    project also needs people to contribute feedback to its
    development, so it is being made available for that purpose.
    Contact the project if you're interested in testing this software.


13. The DODS-enabled netCDF client library and servers have been
    upgraded to be compatible with netCDF 3.5. The netCDF client
    library now use a DODS error object to send the netCDF 3.5 system
    error codes to the client. The client library reports errors
    received from the servers in addition to DODS internal and local
    error codes. Also invalid_error messages due to handling error
    exception are fixed.

14. DODSster capabilities have been added to the server software.
    DODSster is an experimental system created in a partnership with
    the Earth System Science Workbench that provides a way for DODS
    servers to use the MODster system to serve MODIS data. With
    DODSster you can use a DODS server to fetch a URL from a MODster
    site and then serve it.

    For more information, see: http://essw.bren.ucsb.edu/modster/ or
    contact jgallagher@gso.uri.edu.

USAGE NOTES

15. When the OPeNDAP software is used to serve compressed files
    (e.g. files compressed using gzip), the files are decompressed and
    stored in a cache directory; data served are read from those
    cached files. The location of the cache directory is /usr/tmp by
    default. The limit on the size of the cache is 50 MB by default.
    Both these values can be changed by editing the values of the
    variables "cache_dir" and "cache_size" in the dods.rc
    configuration file. If you're serving large files, or are
    experiencing a large volume of traffic, you should increase the
    cache size.

    The decompression software uses the gzip program to do its work.
    If your computer does not have gzip in its /bin directory you'll
    need to edit the DODS_Cache.pm so that the correct version of gzip
    is used. Look in that file for '/bin/gzip' and replace that text
    with the correct pathname. To figure out where gzip is on your
    computer, type 'which gzip' at the command prompt.

      if ((! -e $cache_entity) && (-e $pathname)) { 
	my $uncomp = "/bin/gzip -c -d " . $pathname . " |";
	...


16. You can register your data set(s) with the us using our web
    page.  Find the registration page at:

      http://www.unidata.ucar.edu/packages/dods/home/data/addtolist.html

    Our list of available datasets can be found at the 

      Datasets:NVODS DODS Datasets 

    menu item on our home page: http://www.unidata.ucar.edu/packages/dods.
  
    You can also register your dataset with the Global Change Master
    Directory (http://gcmd.gsfc.nasa.gov/).  They maintain a list of 
    registered DODS data sets.
  
    The GCMD has a special portal dedicated to datasets accessible
    using DODS/OPeNDAP servers at:

      http://gcmd.gsfc.nasa.gov/Data/portals/dods/.
  

17. A tip from Joe McLean about customizing the DODS Directory
    response:
  
    After messing around with Apache for a few hours, I have found
    some configuration directives that may be of use in beautifying
    the appearance of a DODS directory on your user's Browser.
  
    example: http://ferret.pmel.noaa.gov/cgi-bin/nph-dods/data/PMEL/
  
    In your Apache httpd.conf file add the following:
  
    <Directory /path-to-dods(without cgi-bin or nph-dods)/data>
        Options +Indexes +FollowSymLinks
        IndexOptions FancyIndexing
        IndexOptions +FoldersFirst +NameWidth=* +IgnoreCase
        IndexOptions +SuppressDescription
        DefaultIcon /path-to-icons/dods.gif
        IndexOptions +IconHeight=20 +IconWidth=20
    </Directory>
  
    I copied the DODS logo from upper left hand corner of
    http://www.unidata.ucar.edu/packages/dods/home/getStarted/
    called it dods.gif and stuck it in my apache icons directory
    (in httpd.conf grep for Icon - something should show you the path)
  
    Information for Apache
      IndexOptions: http://httpd.apache.org/docs/mod/mod_autoindex.html#indexoptions
      Options: http://httpd.apache.org/docs/mod/core.html#options
      DefaultIcon: http://httpd.apache.org/docs/mod/mod_autoindex.html#defaulticon

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

$Id: NEWS,v 1.2.4.9 2003/12/02 17:08:19 edavis Exp $