
NetCDF 2.4.3 Release Notes

Version 2.4.3 of Unidata's netCDF software is now available via anonymous
FTP from

     ftp://ftp.unidata.ucar.edu/pub/netcdf/netcdf.tar.Z

Instructions for installation are contained in the INSTALL file that
accompanies the software.

Release 2.4.3 is a minor update for version 2.4 (see list of changes,
below). Version 2.4 incorporates support for new platforms and updated
versions of previously-supported platforms, provides new optimizations,
improves the documentation, incorporates fixes for reported bugs, and
includes other miscellaneous improvements. Version 2.4 is intended to be a
stable release incorporating bug fixes and improvements that do not involve
significant additions to the netCDF data model or interfaces.
----------------------------------------------------------------------------

Platforms

This release has been built and tested on the following platforms:

   * AIX-4.1 (IBM Powerstation)
   * BSDI 2.1 (Intel x86, FORTRAN interface not tested)
   * HPUX-9.05 (HP PA-RISC)
   * IRIX-5.3, IRIX-6.2, IRIX64-6.2 (SGI Indigo)
   * Linux 1.3.95 (486 PC, see notes)
   * MSDOS using gcc, f2c, and GNU make (IBM PS/2, 386)
   * OpenVMS-6.2 (Digital MicroVAX, C++ interface not tested)
   * OSF1-4.0 (Digital Alpha)
   * OS/2 2.1 (Gateway, 486)
   * SunOS-4.1.4, SunOS-5.5 (Sun SPARCstation)
   * ULTRIX-4.4, ULTRIX-4.5 (Digital VAXstation, C++ interface not tested)
   * UNICOS-8 (Cray Y-MP, T3D, C++ interface not tested)
   * Windows NT-3.51 (Pentium)

The 2.4 release integrates the use of the nclong typedef into the netCDF
implementation. This means that C/C++ programs on platforms with

  sizeof(long) > sizeof(int)

(e.g. the DEC Alpha) will have to be recompiled and must use nclong as the
variable type corresponding to NC_LONG data. All programs that use NC_LONG
data should also use the nclong data type to declare such data for
portability.

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

Recent Minor Releases

The 2.4.3 release contains a few minor changes:

   * Added a couple of omitted steps needed for building under Windows NT to
     the INSTALL document.
   * Added the `-p fdigs,ddigs' option to ncdump. This replaces and behaves
     like the (now deprecated and undocumented) `-d' option, except that it
     overrides any values specified by the `C_format' attribute for float or
     double values.
   * Made precisions specified by the `-p' or (now deprecated) `-d' options
     apply to float or double attributes as well as data values.
   * Fixed cause of potential overflow in ncdump when doing fuzzy comparison
     with fill value. This might occur when comparing values near -FLT_MAX
     with a fill value near FLT_MAX, or similarly for doubles.
   * Ported configuration mechanism to IRIX64 6.2 and GNU make(1) 3.74.
   * Made generation of position-independent code the default.
   * Adapted XDR test program to systems whose doesn't define FLT_EPSILON
     and DBL_EPSILON.
   * Improved installation procedures on LINUX systems using the GNU make(1)
     utility.
   * Incorporated improvements for CRAY PVP systems: faster writing of
     initial fill-values and better FFIO error messaging (from Robert
     Swanson -- Lockheed Martin Technical Services, National Environmental
     Supercomputing Center).
   * Corrected typo in FORTRAN manual page: changed NCCREDF to NCREDF.

The 2.4.2 release contained the following changes:

   * Ported to an Intel 386-based, BSD/OS 2.1 system (but with no FORTRAN
     support).
   * Ported to DJGPP Version 2 for MS-DOS.
   * For CRAY systems, changed XDRing of scalars to use the same functions
     as XDRing of vectors. This provides a workaround for a CRAY problem
     where the same value written as an attribute produced a slightly
     different external representation than when written as a variable.
   * Added the fortc(1) macro file `linux.m4' to the distribution.
   * Liberalized conditions on use and distribution of the netCDF software
     by changing a sentence in the software copyright notice and in netcdf.h
     from a requirement to a request.
   * Fixed an ncgen bug in generating the proper value for a scalar
     character variable initialized from a string in a CDL file.

The 2.4.1 release contains fixes for some minor bugs in the previous 2.4
release, and some documentation updates:

   * Slightly modified VAX OpenVMS build mechanism: made `makevms.com'
     command procedures VAX-C specific in order to better specify the build
     environment and avoid incompatibilities.
   * Slightly modified ncdump/ncdump.c: expanded use of isprint() into two
     statements to avoid problems under Alpha OpenVMS where that function is
     actually a complicated macro.
   * Fixed ncgen bug in filling one-dimensional string variables when
     specified with multiple values that should be concatenated,
     eliminatiing spurious "too many values for this variable" message.
   * In User's Guide, added links to C++ and NetcdfPerl interface
     documentation.

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

Optimizations

Significant optimizations are included for Cray UNICOS platforms. The Cray
optimizations use the Cray FFIO library with buffering user-configurable
through an environment variable. These optimizations make netCDF on the Cray
competitive with Fortran binary I/O. Thanks to Jeff Kuehn and Steve Luzmoor
for contributing these optimizations.

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

Documentation Improvements

The NetCDF User's Guide has been significantly revised, including some
important additions. Changes include the following:

   * a new appendix that formally specifies the netCDF format, independent
     of its implementation;
   * a new section on limitations of the netCDF data model and
     implementation;
   * a new section on compiling and linking with the netCDF library;
   * a new section on UNICOS optimization;
   * a new section discussing the correspondence between CDL, netCDF,
     Fortran, and C data types;
   * clarification of, and some changes to, recommended standard attribute
     conventions;
   * clarification of cross-section access, strided access, and mapped
     access to arrays;
   * better embedding of URLs, so the derived HTML form of the User's Guide
     has working links to external documents and references; and
   * a more useful Index.

The new NetCDF User's Guide is included in the netCDF source distribution,
but is also available independently in three forms:

HTML
     as a set of HTML documents for viewing with a web browser.
PostScript
     as a compressed PostScript file. When uncompressed, this is suitable
     for printing or viewing with a PostScript viewer. (In the PostScript
     file, the Table of Contents is printed last, so please reorder before
     duplicating.)
Info files
     as a compressed tar file of Info files, suitable for viewing with an
     Info documentation browsing system such as xinfo or GNU info.

The supplementary class documentation for the C++ interface has also been
revised and expanded.

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

Other Improvements

Limitations in the ncgen utility program on the maximum number of variables,
dimensions, or attributes have been eliminated. The size of the ncgen
executable is now significantly smaller.

The ncdump program now uses the underscore character (_) to display
fill-values (data that hasn't been written yet or missing values). The ncgen
utility recognizes these, as well as the old FloatInf and DoubleInf symbols
for backward compatibility.

This release increases advisory limits for the maximum number of dimensions,
variables, and attributes in a netCDF file, to accommodate users who found
the old limits constraining. These limits are still advisory, to make
applications easier to write when dynamic memory allocation would be awkward
or impractical (e.g. in Fortran applications). The maximum number of
dimensions per netCDF file has been increased from 32 to 100. The maximum
number of variables per netCDF file has been increased from 512 to 2000. The
maximum number of attributes per variable has been increased from 512 to
2000.

The experimental C++ interface has been integrated into the netCDF
distribution and is now built by default as part of the installation, if a
suitable C++ compiler is available. C++ interface changes include:

   * New get_rec(), put_rec(), and set_rec() member functions were added to
     the NcVar class to make it easier to step through records and access
     just one record of variable data.
   * A new get_index() member function was added to the NcVar class that
     finds the record number of the first variable that matches a specified
     key.
   * The NcFile class hierarchy was simplified in a backward-compatible way,
     to make it easier for users to derive their own specialized netCDF file
     classes.

Thanks to Dan Schmitt of Texas A&M University for contributing these
additions.

In the C++ interface, you can no longer use unadorned integer constants to
put attribute values, because it's ambiguous whether you intend the
attribute type to be byte, short, or long. You can get the right attribute
type by casting or using a variable value of the appropriate type. Another
similar problem led to the removal of as_int() member functions, because of
ambiguity and portability problems. You now have to use as_short() or
as_nclong() to access a variable value as an integer. Similarly, we removed
overloading on int and int* data types where it would encourage writing
nonportable programs that behave differently on machines with different int
sizes.

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

Bug Fixes

The 2.4 release contains fixes for bugs in the previous 2.3.2 release. Below
we list the most significant fixes. A more complete list is in the CHANGES
file in the distribution.

C library fixes:

   * Fixed the `xdr_NC_fill' bug in ncrecput(), which misbehaved if invoked
     after reading a non-record variable.
   * Fixed ncredef() bug that caused a segmentation violation from
     dereferencing a null pointer if ncredef() was called immediately after
     nccreate().
   * Fixed bug that occurred when reentering definition mode to add a new
     record variable to a file that had only one record variable of type
     NC_BYTE, NC_CHAR, or NC_SHORT. In these cases, a special-case
     optimization was used to avoid padding each record value out to four
     bytes, but the redefinition was not accounting for this optimization.
   * Fixed bugs so ncvarid() and ncdimid() will work on a variable or
     dimension that has been renamed to a shorter name while in data mode.
   * Makefile and configuration fixes for more robust adaptation to various
     platforms
   * The ncsync() function was changed to re-read the header on files opened
     for writing in addition to re-reading the header on files opened for
     read-only access, as in the previous version.
   * New names of variables and dimensions renamed in define mode will now
     be immediately recognized.
   * For VMS platforms, files opened with "ctx=stm" keyword to use stream
     mode. This will permit reading netCDF files from VMS system that have
     been FTPd in binary mode from a UNIX system without modifying RMS
     attributes after file transfer.

Fortran library fixes:

   * Improved error handling from the Fortran interface, where failures from
     C calls were occasionally not reflected in Fortran error returns. In
     particular, the library now catches attempts to retrieve information
     when no attributes, dimensions, or variables are defined yet. Attempts
     to rename components in files opened for read-only access now fail
     properly.
   * Improved error message from Fortran interface when user forgets to
     include netcdf.inc and then calls NCCRE or NCOPN.
   * Corrected a few bugs in the Fortran interface module
     (fortran/jackets.src) dealing with interconversion between Fortran
     INTEGERs and C longs.
   * Added SINGLE_PRECISION to `fortran/fortc' system and modified file
     fortran/ftest.src accordingly.

C++ library fixes:

   * Several memory leaks were plugged.
   * Tested that file was not in define mode when NcFile::sync() is called.
   * Changed return type of NcVar::edges() from const long* to long*, to
     make the result modifiable for immediate use in accessing array
     sections.
   * Fixed bug in NcVar::set_cur() to allow extending along record
     dimension.
   * Fixed off-by-one problem with strings.
   * Made changes necessary to work with g++.
   * Fixed a bug in NcVar::get_att(NcToken) member, to make it return 0 for
     attributes that don't exist.
   * NcAtt::is_valid() had been returning FALSE for global attributes, but
     this fix makes it return TRUE when appropriate.
   * NcAtt::remove() member function now checks to make sure in define_mode
     first, before deleting attribute.

Utility program fixes:

   * Fixed a problem with ncgen -f that showed up on AIX, where
     double-precision constants like 1.5d+30 were being stored using
     single-precision representations, such as 1.5e+30.
   * Fixed ncgen to accept null-string attributes.
   * Fixed ncgen to print an error message when a duplicate attribute for a
     variable is declared in CDL input.
   * Fixed ncgen handling of hexadecimal notation for byte constants, so now
     '\x80' works as documented for specifying a byte value, for example.
   * Fixed ncgen to permit variable, dimension, and attribute names to
     contain the string "netcdf".
   * Incorporated Brian Lincoln's fix for the way ncgen handles
     multidimensional strings, providing padding in the most rapidly-varying
     dimension instead of just concatenating the strings.
   * Made ncgen generate an error message when the type of the _FillValue
     attribute doesn't match the type of the associated variable. The
     library is supposed to catch all these, but doesn't for record
     variables.
   * Fixed bug with ncgen generating C or Fortran programs that didn't use
     ".nc" file extensions on created netCDF files.
   * Use of the "-f" option of ncdump for annotating with full attributes
     caused multidimensional character arrays to be incorrectly annotated
     (the comma delimiter was missing).
   * Some ncdump option combinations caused memory leaks.
   * Fixed ncdump bug that appeared on some platforms when dumping a
     0-length attribute. Now ncdump will represent a 0-length attribute of
     any type as the empty string, since CDL has no syntax for 0-length
     attributes.

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

Providing Feedback

Questions or suggestions about this release may be sent to
<support@unidata.ucar.edu>, mentioning the platform and version of the
software.
----------------------------------------------------------------------------
