NetCDF Error Handling

Each netCDF function in the C, Fortran 77, and Fortran 90 APIs returns 0 on success, in the tradition of C. More...

Functions
const char *	nc_strerror (int ncerr1)
	Given an error number, return an error message. More...

Detailed Description

Each netCDF function in the C, Fortran 77, and Fortran 90 APIs returns 0 on success, in the tradition of C.

NetCDF Error Handling.

When programming with netCDF in these languages, always check return values of every netCDF API call. The return code can be looked up in netcdf.h (for C programmers) or netcdf.inc (for Fortran programmers), or you can use the strerror function to print out an error message. (See nc_strerror/NF_STRERROR/NF90_STRERROR).

In general, if a function returns an error code, you can assume it didn't do what you hoped it would. The exception is the NC_ERANGE error, which is returned by any of the reading or writing functions when one or more of the values read or written exceeded the range for the type. (For example if you were to try to read 1000 into an unsigned byte.)

In the case of NC_ERANGE errors, the netCDF library completes the read/write operation, and then returns the error. The type conversion is handled like a C type conversion, whether or not it is within range. This may yield bad data, but the netCDF library just returns NC_ERANGE and leaves it up to the user to handle. (For more information about type conversion see Type Conversion).

NetCDF functions return a non-zero status codes on error.

Each netCDF function returns an integer status value. If the returned status value indicates an error, you may handle it in any way desired, from printing an associated error message and exiting to ignoring the error indication and proceeding (not recommended!). For simplicity, the examples in this guide check the error status and call a separate function, handle_err(), to handle any errors. One possible definition of handle_err() can be found within the documentation of nc_strerror().

The nc_strerror() function is available to convert a returned integer error status into an error message string.

Occasionally, low-level I/O errors may occur in a layer below the netCDF library. For example, if a write operation causes you to exceed disk quotas or to attempt to write to a device that is no longer available, you may get an error from a layer below the netCDF library, but the resulting write error will still be reflected in the returned status value.

Function Documentation

nc_strerror()

const char* nc_strerror

(

int

ncerr1

)

Given an error number, return an error message.

This function returns a static reference to an error message string corresponding to an integer netCDF error status or to a system error number, presumably returned by a previous call to some other netCDF function. The error codes are defined in netcdf.h.

Parameters

ncerr1

error number

Returns

short string containing error message.

Here is an example of a simple error handling function that uses nc_strerror() to print the error message corresponding to the netCDF error status returned from any netCDF function call and then exit:

#include <netcdf.h>
   ...
void handle_error(int status) {
if (status != NC_NOERR) {
   fprintf(stderr, "%s\n", nc_strerror(status));
   exit(-1);
   }
}

Definition at line 87 of file derror.c.