$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.