Next: , Previous: Attributes, Up: Top


Appendix A NetCDF 2 to NetCDF 3 Fortran 77 Transition Guide

A.1 Overview of FORTRAN interface changes

NetCDF version 3 includes a complete rewrite of the netCDF library. It is about twice as fast as the previous version. The netCDF file format is unchanged, so files written with version 3 can be read with version 2 code and vice versa.

The core library is now written in ANSI C. You must have an ANSI C compiler to compile this version. The FORTRAN interface is layered on top of the C interface using a different technique than was used in netCDF-2.

Rewriting the library offered an opportunity to implement improved C and FORTRAN interfaces that provide some significant benefits:

It is not necessary to rewrite programs that use the version 2 FORTRAN interface, because the netCDF-3 library includes a backward compatibility interface that supports all the old functions, globals, and behavior. We are hoping that the benefits of the new interface will be an incentive to use it in new netCDF applications. It is possible to convert old applications to the new interface incrementally, replacing netCDF-2 calls with the corresponding netCDF-3 calls one at a time.

Other changes in the implementation of netCDF result in improved portability, maintainability, and performance on most platforms. A clean separation between I/O and type layers facilitates platform-specific optimizations. The new library no longer uses a vendor-provided XDR library, which simplifies linking programs that use netCDF and speeds up data access significantly in most cases.

A.2 The New FORTRAN Interface

First, here's an example of FORTRAN code that uses the netCDF-2 interface:

     ! Use a buffer big enough for values of any type
     DOUBLE PRECISION DBUF(NDATA)
     REAL RBUF(NDATA)
     ...
     EQUIVALENCE (RBUF, DBUF), ...
     INT XTYPE     ! to hold the actual type of the data
     INT STATUS    ! for error status
     ! Get the actual data type
     CALL NCVINQ(NCID, VARID, ...,XTYPE, ...)
     ...
     ! Get the data
     CALL NCVGT(NCID, VARID, START, COUNT, DBUF, STATUS)
     IF(STATUS .NE. NCNOERR) THEN
        PRINT *, 'Cannot get data, error code =', STATUS
        ! Deal with error
        ...
     ENDIF
     IF (XTYPE .EQ. NCDOUBLE) THEN
        CALL DANALYZE(DBUF)
     ELSEIF (XTYPE .EQ. NCFLOAT) THEN
        CALL RANALYZE(RBUF)
     ...
     ENDIF

Here's how you might handle this with the new netCDF-3 FORTRAN interface:

     ! I want to use doubles for my analysis
     DOUBLE PRECISION DBUF(NDATA)
     INT STATUS
     ! So I use a function that gets the data as doubles.
     STATUS = NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, DBUF)
     IF(STATUS .NE. NF_NOERR) THEN
        PRINT *, 'Cannot get data, ', NF_STRERROR(STATUS)
        ! Deal with error
        ...
     ENDIF
     CALL DANALYZE(DBUF)

The example above illustrates changes in function names, data type conversion, and error handling, discussed in detail in the sections below.

A.3 Function Naming Conventions

The netCDF-3 C library employs a new naming convention, intended to make netCDF programs more readable. For example, the name of the function to rename a variable is now NF_RENAME_VAR instead of the previous NCVREN.

All netCDF-3 FORTRAN function names begin with the NF_ prefix. The second part of the name is a verb, like GET, PUT, INQ (for inquire), or OPEN. The third part of the name is typically the object of the verb: for example DIM, VAR, or ATT for functions dealing with dimensions, variables, or attributes. To distinguish the various I/O operations for variables, a single character modifier is appended to VAR:

At the end of the name for variable and attribute functions, there is a component indicating the type of the final argument: TEXT, INT1, INT2, INT, REAL, or DOUBLE. This part of the function name indicates the type of the data container you are using in your program: character string, 1-byte integer, and so on.

Also, all PARAMETER names in the public FORTRAN interface begin with the prefix NF_. For example, the PARAMETER which was formerly MAXNCNAM is now NF_MAX_NAME, and the former FILFLOAT is now NF_FILL_FLOAT.

As previously mentioned, all the old names are still supported for backward compatibility.

A.4 Type Conversion

With the new interface, users need not be aware of the external type of numeric variables, since automatic conversion to or from any desired numeric type is now available. You can use this feature to simplify code, by making it independent of external types. The elimination of type punning prevents some kinds of type errors that could occur with the previous interface. Programs may be made more robust with the new interface, because they need not be changed to accommodate a change to the external type of a variable.

If conversion to or from an external numeric type is necessary, it is handled by the library. This automatic conversion and separation of external data representation from internal data types will become even more important in netCDF version 4, when new external types will be added for packed data for which there is no natural corresponding internal type, for example, arrays of 11-bit values.

Converting from one numeric type to another may result in an error if the target type is not capable of representing the converted value. (In netCDF-2, such overflows can only happen in the XDR layer.) For example, a REAL may not be able to hold data stored externally as an NF_DOUBLE (an IEEE floating-point number). When accessing an array of values, an NF_ERANGE error is returned if one or more values are out of the range of representable values, but other values are converted properly.

Note that mere loss of precision in type conversion does not return an error. Thus, if you read double precision values into an INTEGER, for example, no error results unless the magnitude of the double precision value exceeds the representable range of INTEGERs on your platform. Similarly, if you read a large integer into a REAL incapable of representing all the bits of the integer in its mantissa, this loss There are two new functions in netCDF-3 that don't correspond to any netCDF-2 functions: NF_INQ_LIBVERS and NF_STRERROR. The version ation The previous implementation returned an error when the same dimension was used more than once in specifying the shape of a variable in ncvardef. This restriction is relaxed in the netCDF-3 implementation, because an autocorrelation matrix is a good example where using the same dimension twice makes sense.

In the new interface, units for the IMAP argument to the NF_PUT_VARM and NF_GET_VARM families of functions are now in terms of the number of data elements of the desired internal type, not in terms of bytes as in the netCDF version-2 mapped access interfaces.

Following is a table of netCDF-2 function names and names of the corresponding netCDF-3 functions. For parameter lists of netCDF-2 functions, see the netCDF-2 User's Guide.

NCABOR
NF_ABORT
NCACPY
NF_COPY_ATT
NCADEL
NF_DEL_ATT
NCAGT
NF_GET_ATT_DOUBLE, NF_GET_ATT_REAL, NF_GET_ATT_INT, NF_GET_ATT_INT1, NF_GET_ATT_INT2
NCAGTC
NF_GET_ATT_TEXT
NCAINQ
NF_INQ_ATT, NF_INQ_ATTID, NF_INQ_ATTLEN, NF_INQ_ATTTYPE
NCANAM
NF_INQ_ATTNAME
NCAPT
NF_PUT_ATT_DOUBLE, NF_PUT_ATT_REAL, NF_PUT_ATT_INT, NF_PUT_ATT_INT1NF_PUT