$Id: CHANGES,v 1.2 1994/11/11 20:36:19 dianam Exp $

The default fill values for double and floating-point data were changed.
The previous strategy of using numbers that mapped to IEEE NaN under XDR
caused portability problems.  Now FILL_FLOAT and FILL_DOUBLE are large
constants within the floating-point range.  As before, we continue to
recommend that users define their own variable-specific fill values rather
than use the default ones provided.

The way in which the default fill values are defined in the FORTRAN
interface was changed, so that now the FORTRAN default fill values will
always be the same as the C default values.  This eliminates the need for
the platform-specific foo0.inc files where these constants were previously
defined.

Support for generalized hyperslabs was added.  This adds the new functions
ncvarputg and ncvargetg to the C interface, and new subroutines NCVPTG,
NCVPGC, NCVGTG, and NCVGGC to the Fortran interface.

The FILL parameters defined in the netcdf.inc include file for integer types
for the FORTRAN interface were "fixed" to be the same as the FILL parameters
in the C interface.  In previous releases these had differed from the C
interface values, which meant C and FORTRAN programs would not agree on
default fill values.  This fix is unfortunate but necessary to bring the two
interfaces back into line.

The installation procedure on UNIX platforms was changed to use the GNU
configure approach to constructing makefiles based on inquiries run from a
configure shell script.

Names acceptable to ncgen for
	netcdf name { ... }
may now start with a non-alphabetic character and include any characters
except blanks or "{" characters.

Some new informational files were added at the top-level:  FAQ for answers
to frequently asked questions, ORIGIN to describe where the distribution
came from, COPYRIGHT separates out the Copyright notice from the README
file.

Changed recommended netCDF file extension from ".cdf" to ".nc", and added
"-b" option of ncgen to produce ".nc" files.

Added several options to ncdump to control annotations in output.

An experimental draft prototype C++ interface has been added.  See the c++
subdirectory for the implementation, an example of the use, and soime
preliminary minimal documentation.

Many "const" declarations were added to the interfaces and documentation, to
specify where functions do not change values through passed in pointers.

Added three new C convenience functions to the interface to handle record
I/O.  ncrecget, ncrecput, and ncrecinq permit accessing a whole record's
worth of data with a single call.

Made clearer in the User's Guide that a NULL pointer can be provided for any
return parameter from an inquire function, to indicate that you don't want
that value returned.  Also indicated that inquire functions never incur any
I/O.


------ Mon Dec 23 MST 1991  Changes in netCDF (2.01 to 2.02)

A "memory leak" is fixed that would cause any program that opened and closed
many netCDF files to grow.

All inquire functions (ncinquire, ncdiminq, ncvarinq, ncattinq) now permit a
NULL pointer to be given for any of their return parameters, to indicate
when no return value for that parameter is desired.

The default library type that is built by the distributed Makefile is now
"nonsharable" rather than "sharable".

The format that ncdump uses to output byte data is changed from octal to
decimal.

------ Mon Nov 25 1991	Changes in netCDF (2.0 to 2.01)

Correct usage of the XDR_LD macro is added to all appropriate
program-building rules in all appropriate sub-Makefiles.  This is needed for
proper program-creation under the IRIX operating-system.

Corrects the major.minor revision ID for SunOS sharable libraries to 2.01.

Adds support for the creation of the netCDF Fortran interface under the IRIX
operating-system.

------ Wed Oct  9 1991	Changes in netCDF (1.11 to 2.0)

The netCDF C interfaces were changed to use long values rather than ints for
netCDF dimensions on all machines.  This changed the following interfaces that
formerly use "int" or "int*" for dimensions and dimension pointers:

  int ncdimdef(int cdfid, const char* name, int length);
  int ncdiminq(int cdfid, int dimid, char* name, int* length);
  int ncvarput1(int cdfid, int varid, int *coords, void* value);
  int ncvarget1(int cdfid, int varid, int *coords, void* value);
  int ncvarput(int cdfid, int varid, int *start, int *count, void* value);
  int ncvarget(int cdfid, int varid, int *start, int *count, void* value);

to use "long" or "long*" instead:

  int ncdimdef(int cdfid, const char* name, long length);
  int ncdiminq(int cdfid, int dimid, char* name, long* length);
  int ncvarput1(int cdfid, int varid, long *coords, void* value);
  int ncvarget1(int cdfid, int varid, long *coords, void* value);
  int ncvarput(int cdfid, int varid, long *start, long *count, void* value);
  int ncvarget(int cdfid, int varid, long *start, long *count, void* value);

No change to data representation or file formats was required, since the XDR
form of integers is 32 bits.  The main advantage of this change is that on
platforms such as MSDOS machines on which integers are only 16 bits, it is
now possible to access data from variables that have a dimension greater
than 32767.  This is of some practical importance, since CD-ROM disks are
being written with large datasets in netCDF form, and it is desirable to be
able to access this data from inexpensive 16-bit machines.

Since ints and longs are the same on most current platforms (Suns,
DECstations, VAXen, IBM RS6000s, SGIs, HPs, CRAYs, ...), this change does
not break old code.  Applications compiled with the old interface on such
machines will work the same way as they did before without recompiling.
Standard C compilers that support prototypes permit using int values for
dimension size and automatically convert them to longs before the call.  C
code that uses pointers to ints instead of pointers to longs (where required
by the new interfaces) will elicit warning messages from lint and from
standard C compilers, so all such problems may be caught at compile time.

Programs compiled under the old interface on machines with 16-bit ints
(primarily MSDOS machines based on the 80286 or earlier chips) must be
recompiled.  Such programs are also the main beneficiaries of the change.

Modifications necessitated by this interface change are included in this
version, including changes to the man-page reference documentation, the
User's Guide, the nctest test program, the ncdump and ncgen utilities, and
the Fortran jackets.

A bug on VMS was fixed by forcing stream mode access on netCDF files.

ncdump was fixed to work on platforms that have 16-bit integers, even for
variables that have a dimension to large to fit in a 16-bit integer.

The "-c" option of ncgen was fixed to work even when a large number of
values need to be initialized, instead of overflowing the array reserved for
C statements.

Changes were incorporated in the Makefiles to permit building netCDF on SGI
platforms.

A bug setting fill values for short integers, in which only every other
value was filled, was fixed.


------ Wed May 15 1991	Changes in netCDF (1.10 to 1.11)

Fix for opening two or more netCDF files for writing when more than one file
was in redefine mode.  The fix permits multiple netCDF files in redefine
mode simultaneously.

Improvements to INSTALL documentation.

Some files in the source distribution were renamed, to conform to the strict
conventions of MSDOS and OS/2.

ANSI C function prototypes for netCDF functions were added to netcdf.h, for
use in checking calls to the library when you have an ANSI C compiler.

The Makefiles for netCDF were revised to make installation easier.  The
Makefiles now also make shared libraries for SunOS and AIX platforms.

The generation of Fortran jackets for various platforms from a single m4
source is now possible with versions of m4 that don't have the defn()
built-in macro, e.g. Ultrix.  FORTRAN jackets in Microsoft C for Micrsoft
FORTRAN on MSDOS and OS/2 are now supported.

The netCDF User's Guide was revised to include write-ups for the new
functions ncsetfill() and NCSFIL(), to contain an updated Foreward, a
description of the use of the reserved attribute "_FillValue", and an
appendix containing a description of the suggested units syntax standard.  A
copy of our units file was included in the netcdf/doc directory.  A more
recent version of texinfo.tex is distributed with the User's Guide.

*****
A change was made to putget.c to eliminate unnecessary seeks.  This results
in a considerable performance enhancement for sequential writes.

***** A new function ncsetfill(int fillmode) (NCSFIL(INTEGER FILLMODE) for
FORTRAN) has been added, to support optimization of writes without
prefilling.  

Example:
	ncsetmode(NC_NOFILL) ; 
	ncvarput
	ncvarput

This is a performance enhancement which can be used to eliminate the dual
"writes" that result from the netcdf putting its default fill value in only
to be immediately overwritten by the data.

Caveats:

    It is incumbent upon the applications program to be certain that all the
data positions have valid data "put" to them.
    If the netcdf file has an unlimited dimension and the last record was
"put" while NC_NOFILL was set, then the file will be 4 bytes longer than if
NC_NOFILL wasn't set.

*****
IF an attribute named "_FillValue" exists for a given netcdf variable AND
the attribute is of same type of the variable AND the "count" (array length)
of the attribute is 1, THEN the value of that attribute will be henceforth
used as the "fill value" for that variable.

Example:
	long lfill = -1 ;
	long_id = ncvardef(cdfid, "avar", NC_LONG, ndims, dims) ;
 	ncattput(id, Long_id, "_FillValue", NC_LONG, 1, &lfill) ;

The purpose of this is to save the applications programmer the work of
"prefilling" and also to eliminate the dual "writes" that result from netcdf
putting its default fill value in, only to be immediately overwritten by the
programmers preferred value.

Caveat:
	If you change or add this attribute after the variable has been
	instantiated (first ncendef after ncvardef of the variable), it
	doesn't go back and change the old stuff. 

*****
A fix was put in ncdump for printing byte-values '\374' through '\377',
which printed as multiple bytes on platforms where chars are signed rather
than unsigned.

Integrated the changes needed to support FORTRAN jackets for the Microsoft
FORTRAN compiler and C compiler under MSDOS and OS/2 into the new
netcdf/fortran/msoft directory.

A problem in the library that would only appear when trying to read a very
large array on machines with 16-bit ints was fixed.  The nctest program was
changed to test for this case, so it would reveal the problem.

The single big malloc() of enough space to hold all the data for a variable
with one big ncvarget() call to get it all, was changed to a small malloc()
and multiple ncvarget() calls for each "row" of data.  This will make ncdump
smaller at run-time and make it work better on 16-bit machines for large
arrays.

Reference documentation, in the form of Unix man pages, was added to the
netcdf/doc directory, to supplement the TeXinfo documentation for the User's
Guide.  The new files are ncdump.1, ncgen.1, netcdf.3, and netcdf.3f for the
ncdump and ncgen utilities and for the C and FORTRAN interfaces,
respectively.

In the netCDF User's Guide, a new chapter on ``netCDF File Structure and
Performance'' was added, and the interface description for the nctypelen()
function was moved.  A Makefile for printing the manual from the ug.texinfo
source and the source for texindex.c were added.

ncgen was modified to accept the hyphen character ("-") as acceptable in
names for dimensions, variables, and attributes.

The top-level Makefile was changed to build and install the FORTRAN
interface by default.  The PORTING documentation was modified to describe
necessary steps to include the FORTRAN interface.  The default OS for the
FORTRAN interface was changed to "sun".

------ Thu Oct 25 05:26:01 MDT 1990	Changes in netCDF (1.09 to 1.10)

The double-precision `fill value' for MIPSEL (DECstation) architectures was
fixed.

A list of which platforms have suitable vendor-supplied XDR libraries and
where they can be found was added to the netCDF/PORTING document.

The Makefile in netcdf/ncgen was fixed to eliminate an extra compilation
when testing the Fortran generated by "ncgen -f".

Several bugs were fixed in the Fortran jackets, the README documentation was
improved, and the names of the `vaxultrix' directory and macro files were
changed to `ultrix' after fixes were incorporated for the DECstation/Ultrix
platform.  Several of the sets of system-specific NOTES files were
simplified and corrected.  The Makefile was improved by removing a feature
not available in make on some systems, and by providing a more informative
error message when a value for the OS macro is not specified.  Comments were
removed from two of the calls to test drivers for NCVPT1() and NCVGT1() in
the Fortran test program, and problems revealed by these tests on the unicos
platform were fixed.  Blank-filling of character strings returned by NCVGTC()
and NCAGTC() was fixed for multi-dimensional string arrays.  Null-terminating
of character attribute values stored with NCAPTC() calls was fixed, so now
such attributes are only null-terminated if the user has explicitly provided
the terminating null character.  New versions of the pre-generated source
for the Fortran test driver and jackets library incorporating these fixes
were created for aix, sun, ultrix, unicos, and vms.

------ Wed Oct 17 14:37:04 MDT 1990	Changes in netCDF (1.08 to 1.09)

The portable XDR library we distribute has been modified so that it will
compile and work properly under OS/2 and MSDOS (Microsoft 6.0 compiler) with
netCDF files larger than 64K.  This means that a vendor XDR, such as Sun
PCNFS or IBM TCP/IP, is NO LONGER required in order to compile netCDF on
these platforms.  In order to `seek' past the 64k mark in files, a change
has been made to the XDR interface:

	xdr_setpos takes a `long' rather than `int' position argument.
	xdr_getpos returns a `long' rather than `int' position argument.

On machines which have 32 bit ints and 32 bit longs, this change is
transparent.  The Microsoft compilers should use the /Za option (ANSI)
so that the proper conditional compilation code is visible.

There is now a single source for the netCDF FORTRAN interface, instead of
several diverging sources.  A new system for parameterizing the FORTRAN
interface generates working jacket libraries for various versions of
FORTRAN-to-C calling conventions, including those found on Sun, VAX/ULTRIX,
VAX/VMS, CRAY/UNICOS, and IBM RS6000/AIX.  It is much easier to create and
test a FORTRAN interface for a new platform, since all the differences among
the various platforms and FORTRAN-to-C calling conventions are isolated in a
small set of M4 macros.  The FORTRAN jackets will now work for FORTRAN
compilers that don't support either or both of the nonstandard BYTE
(integer*1) or the short (INTEGER*2) types.

Declarations for the netCDF functions (as opposed to subroutines) in the
FORTRAN interface are now included in the `netcdf.inc' file, so users don't
need to declare them.  This may cause incorrect warnings about unused integer
variables, which can be ignored.

Ncgen no longer depends on /usr/include/limits.h, since this file is absent
from some versions of Unix.

------ Thu Aug  2 09:57:08 MDT 1990    Changes in netCDF (1.07 to 1.08)

Fixed bug in ncdump: reading octal constants beginning with leading 0 as
decimal.

Fixed bug in ncgen found by Saber C: memory leak and problem with
non null-terminated character array attributes.

Enhanced ncdump to insert line breaks after new-lines in multi-line
attributes, and tested for this in test0.cdl example.

------ Mon Jul 23 10:01:58 MDT 1990	Changes in netCDF (1.06 to 1.07)

The netCDF User's Guide can now be used as an on-line ``hypertext''
document if you have a texinfo reader.  Texinfo is available as part of
the GNU emacs editor (from prep.ai.mit.edu), and a texinfo reader is
also available as an X Windows client named "xinfo".  The texinfo system
allows a single source (in this case netcdf/src/doc/ug.texinfo) to be
used to generate both a hard-copy manual (the netCDF User's Guide) and
files that provide an on-line hypertext version of the manual.

Numerous bugs in the "-f" option of ncgen have been fixed, and a much
more stringent test of the execution of the resulting FORTRAN code is
now part of "make test" in the ncgen directory.  "ncgen -f" now
generates FORTRAN code works on (at least) Sun f77, VMS FORTRAN, and
DEC ULTRIX f77.

Numerous bugs in the FORTRAN jackets have been fixed, including:

	NCVGTC() now correctly blank-fills character hyperslab arrays
	that it returns.

	The ID of the unlimited dimension returned by NCINQ() is no
	longer off by one.

