Previous: Whats Missing, Up: C interface changes from NetCDF 2 to NetCDF 3


B.7 Other Changes

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 of the netCDF library in use is returned as a string by NF_INQ_LIBVERS. An error message corresponding to the status returned by a netCDF function call is returned as a string by the NF_STRERROR function.

A new NF_SHARE flag is available for use in an NF_OPEN or NF_CREATE CALL, to suppress the default buffering of accesses. The use of NF_SHARE for concurrent access to a netCDF dataset means you don't have to call NF_SYNC after every access to make sure that disk updates are synchronous. It is important to note that changes to ancillary data, such as attribute values, are not propagated automatically by use of the NF_SHARE flag. Use of the NF_SYNC function is still required for this purpose.

The version 2 interface had a single inquiry function, ncvarinq for getting the name, type, and shape of a variable. Similarly, only a single inquiry function was available for getting information about a dimension, an attribute, or a netCDF dataset. When you only wanted a subset of this information, you had to provide NULL arguments as placeholders for the unneeded information. The new interface includes additional inquire functions that return each item separately, so errors are less likely from miscounting arguments.

The previous implementation returned an error when 0-valued count components were specified in ncvarput and ncvarget calls. This restriction has been removed, so that now functions in the NF_PUT_VAR AND NF_GET_VAR families may be called with 0-valued count components, resulting in no data being accessed. Although this may seem useless, it simplifies some programs to not treat 0-valued counts as a special case.

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.

ncabort
NF_ABORT
ncattcopy
NF_COPY_ATT
ncattdel
NF_DEL_ATT
ncattget
NF_GET_ATT_DOUBLE, NF_GET_ATT_FLOAT, NF_GET_ATT_INT, NF_GET_ATT_LONG, NF_GET_ATT_SCHAR, NF_GET_ATT_SHORT, NF_GET_ATT_TEXT, NF_GET_ATT_UCHAR
ncattinq
NF_INQ_ATT, NF_INQ_ATTID, NF_INQ_ATTLEN, NF_INQ_ATTTYPE
ncattname
NF_INQ_ATTNAME
ncattput
NF_PUT_ATT_DOUBLE, NF_PUT_ATT_FLOAT, NF_PUT_ATT_INT, NF_PUT_ATT_LONG, NF_PUT_ATT_SCHAR, NF_PUT_ATT_SHORT, NF_PUT_ATT_TEXT, NF_PUT_ATT_UCHAR
ncattrename
NF_RENAME_ATT
ncclose
NF_CLOSE
nccreate
NF_CREATE
ncdimdef
NF_DEF_DIM
ncdimid
NF_INQ_DIMID
ncdiminq
NF_INQ_DIM, NF_INQ_DIMLEN, NF_INQ_DIMNAME
ncdimrename
NF_RENAME_DIM
ncendef
NF_ENDDEF
ncinquire
NF_INQ, NF_INQ_NATTS, NF_INQ_NDIMS, NF_INQ_NVARS, NF_INQ_UNLIMDIM
ncopen
NF_OPEN
ncrecget
(none)
ncrecinq
(none)
ncrecput
(none)
ncredef
NF_REDEF
ncsetfill
NF_SET_FILL
ncsync
NF_SYNC
nctypelen
(none)
ncvardef
NF_DEF_VAR
ncvarget
NF_GET_VARA_DOUBLE, NF_GET_VARA_FLOAT, NF_GET_VARA_INT, NF_GET_VARA_LONG, NF_GET_VARA_SCHAR, NF_GET_VARA_SHORT, NF_GET_VARA_TEXT, NF_GET_VARA_UCHAR
ncvarget1
NF_GET_VAR1_DOUBLE, NF_GET_VAR1_FLOAT, NF_GET_VAR1_INT, NF_GET_VAR1_LONG, NF_GET_VAR1_SCHAR, NF_GET_VAR1_SHORT, NF_GET_VAR1_TEXT, NF_GET_VAR1_UCHAR
ncvargetg
NF_GET_VARM_DOUBLE, NF_GET_VARM_FLOAT, NF_GET_VARM_INT, NF_GET_VARM_LONG, NF_GET_VARM_SCHAR, NF_GET_VARM_SHORT, NF_GET_VARM_TEXT, NF_GET_VARM_UCHAR, NF_GET_VARS_DOUBLE, NF_GET_VARS_FLOAT, NF_GET_VARS_INT, NF_GET_VARS_LONG, NF_GET_VARS_SCHAR, NF_GET_VARS_SHORT, NF_GET_VARS_TEXT, NF_GET_VARS_UCHAR
ncvarid
NF_INQ_VARID
ncvarinq
NF_INQ_VAR, NF_INQ_VARDIMID, NF_INQ_VARNAME, NF_INQ_VARNATTS, NF_INQ_VARNDIMS, NF_INQ_VARTYPE
ncvarput
NF_PUT_VARA_DOUBLE, NF_PUT_VARA_FLOAT, NF_PUT_VARA_INT, NF_PUT_VARA_LONG, NF_PUT_VARA_SCHAR, NF_PUT_VARA_SHORT, NF_PUT_VARA_TEXT, NF_PUT_VARA_UCHAR
ncvarput1
NF_PUT_VAR1_ double, NF_PUT_VAR1_ float, NF_PUT_VAR1_ int, NF_PUT_VAR1_ long, NF_PUT_VAR1_ schar, NF_PUT_VAR1_ short, NF_PUT_VAR1_ text, NF_PUT_VAR1_ uchar
ncvarputg
NF_PUT_VARM_DOUBLE, NF_PUT_VARM_FLOAT, NF_PUT_VARM_INT, NF_PUT_VARM_LONG, NF_PUT_VARM_SCHAR, NF_PUT_VARM_SHORT, NF_PUT_VARM_TEXT, NF_PUT_VARM_UCHAR, NF_PUT_VARS_DOUBLE, NF_PUT_VARS_FLOAT, NF_PUT_VARS_INT, NF_PUT_VARS_LONG, NF_PUT_VARS_SCHAR, NF_PUT_VARS_SHORT, NF_PUT_VARS_TEXT, NF_PUT_VARS_UCHAR
ncvarrename
NF_rename_var
(none)
NF_INQ_libvers
(none)
NF_strerror