Re: ncdigest V1 #887: Reserving header space and use of double underbar tuning functions

• To: Harvey.Davies@xxxxxxxx
• Subject: Re: ncdigest V1 #887: Reserving header space and use of double underbar tuning functions
• From: Russ Rew <russ@xxxxxxxxxxxxxxxx>
• Date: Mon, 18 Jul 2005 13:51:50 -0600

Harvey,

> There was discussion in ncdigest V1 #887 on reserving header space using
> the double underbar tuning function nc__enddef.
> 
> I believe there is a need to:
> 
> 1. Clarify the status of the three double underbar tuning functions
> nc__create, nc__open and nc__enddef
> 
> 2. Make clearer recommendations about their use.
> 
> The NetCDF C Interface Guide contains section 2.10 headed
> "Leave Define Mode with Performance Tuning: nc__enddef" with URL
> http://my.unidata.ucar.edu/content/software/netcdf/docs/netcdf-c/nc_005f_005fenddef.html
> This section contains the following warning paragraph:
> 
> Caution: this function exposes internals of the netcdf version 1 file
> format. Users should use nc_enddef in most circumstances. This function
> may not be available on future netcdf implementations.
> 
> Does this warning apply to all three tuning functions?

No, the tuning parameters available with nc__create() and nc__open()
merely specify a property of an open netcdf dataset, not part of the
file format.  They are not persistent, so not stored in the file.

> Are these functions supported by
> 1. OPeNDAP (DODS)
> 2. netCDF-4?

OPeNDAP provides only read access to data on an OPeNDAP server.  The
nc__create() and nc__enddef() calls are not useful in the context of
read-only access.  The "chunksize" parameter in nc__open() might be
exploited by OPeNDAP for allowing client control of the buffer sizes
used for network data access, but as far as I can tell it's currently
ignored.

Ed Hartnett summarized the situation for netCDF-4: the interfaces with
extra tuning parameters are supported, but the tuning parameters are
ignored.  Similarly, a program that uses the nc__create(), nc__open(),
and nc__enddef() interfaces with extra tuning parameters can be linked
with the OPeNDAP library, but will not have any effect different from
using the simpler nc_create(), nc_open(), and nc_enddef() interfaces.

In developing netCDF, we're now more aware of the importance of
backward compatibility than when the warning above was written.  It's
become a fundamental development principle that current and future
versions of our netCDF libraries must continue to support both access
to earlier forms of netCDF data and linking of programs that use
earlier versions of the netCDF API.  We'll change the documentation to
make clear that the interface will continue to be supported.

Thanks for pointing out the need for a clarification.

--Russ

_____________________________________________________________________

Russ Rew                                         UCAR Unidata Program
russ@xxxxxxxxxxxxxxxx                     http://www.unidata.ucar.edu

• References:
  • RE: ncdigest V1 #887: Reserving header space and use of double underbar tuning functions
    • From: Harvey.Davies