Re: 20040414: Attribute modification in Java2.1 NetCDF API

• To: John Caron <caron@xxxxxxxxxxxxxxxx>
• Subject: Re: 20040414: Attribute modification in Java2.1 NetCDF API
• From: Russ Rew <russ@xxxxxxxxxxxxxxxx>
• Date: Fri, 16 Apr 2004 09:52:57 -0600

>To: <support@xxxxxxxxxxxxxxxx>, 
>From: "Steve Loch" <sgl@xxxxxxxxxx>
>Subject: Attribute modification in Java2.1 NetCDF API
>Organization: British Oceanographic Data Centre
>Keywords: 200404141623.i3EGNSCT021650 netCDF 

Hi Steve,

>I think I was overly brief in my query. If the attribute doesn't
>require additional space then it should, in my view, be possible to
>update the file without regenerating from scratch. [I have always been
>surprised that the APIs (or rather the part of the NetCDF APIs that are
>documented for public consumption) don't allow the addition of free
>space within the header at definition time which would ameliorate the
>problem. Perhaps it's the complexities of garbage collection that led to
>the simpler choice.]

Actually the C, C++, and Fortran APIs provide functions for the
addition of free space within the header at definition time, although
they are documented in the man page reference and not in the User
Guides.  See the documentation for nc__enddef, nf__enddef, etc. (note
the double underbar in the function names):

     int nc__enddef(int ncid, size_t h_minfree,  size_t  v_align,
          size_t v_minfree, size_t r_align)

          Like nc_enddef() but has additional performance  tuning
          parameters.

          Caution: this function exposes internals of the  netcdf
          version  1 file format.  It may not be available on fu-
          ture netcdf implementations.

          The current netcdf file format has three sections,  the
          "header" section, the data section for fixed size vari-
          ables, and the data section for variables which have an
          unlimited dimension (record variables).  The header be-
          gins at the beginning of the file. The (offset) of  the
          beginning of the other two sections is contained in the
          header. Typically, there is no space between  the  sec-
          tions.  This  causes  copying overhead to accrue if one
          wishes to change the size of the sections, as may  hap-
          pen  when  changing  names  of  things,  text attribute
          values, adding attributes or  adding  variables.  Also,
          for  buffered  i/o, there may be advantages to aligning
          sections in certain ways.

          The minfree parameters allow one to  control  costs  of
          future  calls  to nc_redef(), nc_enddef() by requesting
          that minfree bytes be available at the end of the  sec-
          tion.   The h_minfree parameter sets the pad at the end
          of the "header" section. The v_minfree  parameter  sets
          the  pad  at the end of the data section for fixed size
          variables.

--Russ