Go to the previous, next section.

NetCDF Operations

This chapter presents the interfaces of the netCDF routines that deal with a netCDF file as a whole.

A netCDF file that has not yet been opened can only be referred to by its file name. Once a netCDF file is opened, it is referred to by an ID, which is a small nonnegative integer returned when you create or open the file. A netCDF ID is a file handle, much like a file descriptor in C or a logical unit number in FORTRAN. In any single program, the netCDF IDs of distinct open netCDFs are distinct. A single netCDF file may be opened multiple times and will then have multiple distinct netCDF IDs; however at most one of the open instances of a single netCDF file should permit writing. When an open netCDF file is closed, its ID no longer refers to it, and that ID may be subsequently reassigned to refer to a different netCDF that is opened later.

The operations supported on a netCDF file as a single object are:

Create, given file path and whether to overwrite or not.
Open for access, given file path and read or write intent.
Put into define mode, to add dimensions, variables, or attributes.
Take out of define mode, checking consistency of additions.
Close, writing to disk if required.
Get number of dimensions, number of variables, number of global attributes, and ID of the unlimited dimension if any.
Synchronize to disk to make sure it is current.
Set and unset nofill mode for optimized sequential writes.

After a summary of conventions used in describing the netCDF C and FORTRAN interfaces, the rest of this chapter presents the interfaces for these operations.

NetCDF Library Interface Descriptions

Each interface description for a particular netCDF function in this and later chapters contains:

A description of the purpose of the function;
A list of possible error conditions;
A C function prototype that presents the type and order of the formal parameters to the function;
A description of each formal parameter in the C interface;
An example of a C program fragment calling the netCDF function and perhaps other netCDF functions to do something useful;
A FORTRAN function prototype that presents the type and order of the formal parameters to the FORTRAN function or functions that provide the same functionality as the C function;
A description of each formal parameter in the FORTRAN interface; and
An example of a FORTRAN program fragment that duplicates the function of the example C fragment.

The C function prototypes specify the order and type of each formal parameter and conform to the ANSI C standard. FORTRAN does not have function prototypes, but a similar syntax is used to concisely present the order and types of FORTRAN formal parameters. In the few cases in which a single C function corresponds to two FORTRAN functions, the FORTRAN functions prototypes are presented together.

The FORTRAN examples use two nonstandard notations: INCLUDE statements and in-line comments. In each case, we use the VMS FORTRAN notation, as in the following example:

      INCLUDE 'netcdf.inc'
      INTEGER NCID       ! this is an in-line comment

FORTRAN examples (and the FORTRAN interface) abide by the six-character limitation on the length of FORTRAN names, except that parameters names may be up to eight characters long.

Create a NetCDF file

The function nccreate (or NCCRE for FORTRAN) creates a new netCDF file, returning a netCDF ID that can subsequently be used to refer to the netCDF file. The new netCDF file is placed in define mode.

In case of an error, nccreate returns -1; NCCRE returns a nonzero value in rcode. Possible causes of errors include::

Passing a file name that includes a directory that does not exist.
Specifying a file name of a file that exists and also specifying NC_NOCLOBBER (or NCNOCLOB).
Attempting to create a netCDF file in a directory where you don't have permission to create files.

nccreate: C Interface

int nccreate (const char* path, int cmode);

path: The file name of the new netCDF file. This can be given as either an absolute path name (from the root of the file system) or a relative path name (from the current directory).
cmode: Should be specified as either NC_CLOBBER or NC_NOCLOBBER. These constants are defined in the include file named `netcdf.h'. NC_CLOBBER means that even if the file already exists, you want to create a new file with the same name, erasing the old file's contents. NC_NOCLOBBER means you want to create a new netCDF file only if the given file name does not refer to a file that already exists.

In this example we create a netCDF file named `foo.nc'; we want the file to be created in the current directory only if a file with that name does not already exist:

#include "netcdf.h"
   ...
int ncid;
   ...
ncid = nccreate("foo.nc", NC_NOCLOBBER);

NCCRE: FORTRAN Interface

INTEGER FUNCTION NCCRE (CHARACTER*(*) PATH, INTEGER CMODE,
                        INTEGER RCODE)

PATH: The file name of the new netCDF file. This can be given as either an absolute path name (from the root of the file system) or a relative path name (from the current directory).
CMODE: Should be specified as either NCCLOB or NCNOCLOB. These constants are defined in the include file `netcdf.inc'. NCCLOB means that even if the file already exists, you want to create a new file with the same name, erasing the old file's contents. NCNOCLOB means you want to create a new netCDF file only if the given file name does not refer to a file that already exists.
RCODE: Returned error code. If no errors occurred, 0 is returned.

In this example we create a netCDF file named `foo.nc', assuming we want the file to be created in the current directory only if a file with that name does not already exist:

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID
         ...
      NCID = NCCRE('foo.nc', NCNOCLOB, RCODE)

Open a NetCDF File for Access

The function ncopen (or NCOPN for FORTRAN) opens an existing netCDF file for access.

In case of an error, ncopen returns -1; NCOPN returns a nonzero value in rcode. Possible causes of errors include::

The specified netCDF file does not exist.
The mode specified is something other than NC_WRITE or NC_NOWRITE.

ncopen: C Interface

int ncopen(const char* path,int mode);

path: Absolute or relative file name for netCDF file to be opened.
mode: Either NC_WRITE, to open the file for writing, or NC_NOWRITE, to open the file read-only. "Writing" means any kind of change to the file, including appending or changing data, adding or renaming dimensions, variables, and attributes, or deleting attributes.

Here is an example using ncopen to open an existing netCDF file named `foo.nc' for reading:

#include "netcdf.h"
   ...
int ncid;
   ...
ncid = ncopen("foo.nc", NC_NOWRITE);

NCOPN: FORTRAN Interface

      INTEGER FUNCTION NCOPN(CHARACTER*(*) PATH,
     +                       INTEGER RWMODE,
     +                       INTEGER RCODE)

PATH: Absolute or relative file name for netCDF file to be opened.
RWMODE: Either NCWRITE, to open the file for writing, or NCNOWRIT, to open the file read-only. "Writing" means any kind of change to the file, including appending or changing data, adding or renaming dimensions, variables, and attributes, or deleting attributes.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example of using NCOPN to open an existing netCDF file named `foo.nc' for reading:

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID
         ...
      NCID = NCOPN('foo.nc', NCNOWRIT, RCODE)

Put Open NetCDF File into Define Mode

The function ncredef (or NCREDF for FORTRAN) puts an open netCDF file into define mode, so dimensions, variables, and attributes can be added or renamed and attributes can be deleted.

In case of an error, ncredef returns -1; NCREDF returns a nonzero value in rcode. Possible causes of errors include::

The specified netCDF file is already in define mode.
The specified netCDF file was opened for read-only.
The specified netCDF ID does not refer to an open netCDF file.

ncredef: C Interface

int ncredef(int ncid);

ncid: netCDF ID, returned from a previous call to ncopen or nccreate.

Here is an example using ncredef to open an existing NetCDF file named `foo.nc' and put it into define mode:

#include "netcdf.h"
   ...
int ncid;
   ...
ncid = ncopen("foo.nc", NC_WRITE);    /* open file */
   ...
ncredef(ncid);                        /* put in define mode */

NCREDF: FORTRAN Interface

SUBROUTINE NCREDF(INTEGER NCID, INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example of using NCREDF to open an existing netCDF file named `foo.nc' and put it into define mode:

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID
         ...
      NCID = NCOPN('foo.nc', NCWRITE, RCODE)
         ...
      CALL NCREDF(NCID, RCODE)

Leave Define Mode

The function ncendef (or NCENDF for FORTRAN) takes an open netCDF file out of define mode. The changes made to the netCDF file while it was in define mode are checked and committed to disk if no problems occurred. The netCDF file is then placed in data mode, so variable data can be read or written.

This call can be expensive, since it involves initializing non-record variables and copying data under some circumstances. See section NetCDF File Structure and Performance, for a more extensive discussion.

In case of an error, ncendef returns -1; NCENDF returns a nonzero value in rcode. Possible causes of errors include:

The specified netCDF file is not in define mode.
The specified netCDF ID does not refer to an open netCDF file.

ncendef: C Interface

int ncendef(int ncid);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.

Here is an example using ncendef to finish the definitions of a new netCDF file named `foo.nc' and put it into data mode:

#include "netcdf.h"
   ...
int ncid;
   ...
ncid = nccreate("foo.nc", NC_NOCLOBBER);

   ...      /* create dimensions, variables, attributes */

ncendef(ncid);  /*leave define mode*/

NCENDF: FORTRAN Interface

SUBROUTINE NCENDF(INTEGER NCID, INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCENDF to finish the definitions of a new netCDF file named `foo.nc' and put it into data mode:

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID
         ...
      NCID = NCCRE('foo.nc', NCNOCLOB, RCODE)

         ...  !  create dimensions, variables, attributes

      CALL NCENDF(NCID, RCODE)

Close an Open NetCDF File

The function ncclose (or NCCLOS for FORTRAN) closes an open netCDF file. If the file is in define mode, ncendef (or NCENDF) will be called before closing. (In this case, if ncendef [or NCENDF] returns an error, ncabort [or NCABOR] will automatically be called to restore the file to the consistent state before define mode was last entered.) After an open netCDF file is closed, its netCDF ID will be reassigned to the next netCDF file that is opened or created.

In case of an error, ncclose returns -1; NCCLOS returns a nonzero value in rcode. Possible causes of errors include:

The netCDF was in define mode and the automatic call made to ncendef (or NCENDF) failed.
The specified netCDF ID does not refer to an open netCDF file.

ncclose: C Interface

int ncclose(int ncid);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.

Here is an example using ncclose to finish the definitions of a new netCDF file named `foo.nc' and release its netCDF ID:

#include "netcdf.h"
   ...
int ncid;
   ...
ncid = nccreate("foo.nc", NC_NOCLOBBER);

   ...      /* create dimensions, variables, attributes */

ncclose(ncid);       /* close netCDF file */

NCCLOS: FORTRAN Interface

SUBROUTINE NCCLOS(INTEGER NCID, INTEGER RCODE)

NCID: netCDF ID, returned from a previous call to NCOPN or NCCRE.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCCLOS to finish the definitions of a new netCDF file named `foo.nc' and release its netCDF ID:

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID, RCODE
         ...
      NCID = NCCRE('foo.nc', NCNOCLOB, RCODE)

         ...  ! create dimensions, variables, attributes

      CALL NCCLOS(NCID, RCODE)

Inquire about an Open NetCDF File

The function ncinquire (NCINQ for FORTRAN) returns information about an open netCDF file, given its netCDF ID. It can be called from either define mode or data mode. It returns values for the number of dimensions, the number of variables, the number of global attributes, and the dimension ID of the dimension defined with unlimited size, if any. No I/O is required when this or any other `inquire' function in the netCDF interface is called, since the functions merely return information that is stored in a table for each open netCDF file.

In case of an error, ncinquire returns -1; NCINQ returns a nonzero value in rcode. Possible cause of errors includes:

The specified netCDF ID does not refer to an open netCDF file.

ncinquire: C Interface

int ncinquire(int ncid, int* ndims, int* nvars, int* ngatts,
              int* recdim);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
ndims: Returned number of dimensions defined for this netCDF file. If this parameter is given as `(int *) 0', the number of dimensions will not be returned so no variable to hold this information needs to be declared.
nvars: Returned number of variables defined for this netCDF file. If this parameter is given as `(int *) 0', the number of variables will not be returned so no variable to hold this information needs to be declared.
ngatts: Returned number of global attributes defined for this netCDF file. If this parameter is given as `(int *) 0', the number of global attributes will not be returned so no variable to hold this information needs to be declared.
recdim: Returned ID of the unlimited dimension, if there is one for this netCDF file. If no unlimited size dimension has been defined, -1 is returned for the value of recdim. If this parameter is given as `(int *) 0', the record dimension ID will not be returned so no variable to hold this information needs to be declared.

Here is an example using ncinquire to find out about a netCDF file named `foo.nc':

#include "netcdf.h"
   ...
int ncid, ndims, nvars, ngatts, recdim;
   ...
ncid = ncopen("foo.nc", NC_NOWRITE);
   ...
ncinquire(ncid, &ndims, &nvars, &ngatts, &recdim);

NCINQ: FORTRAN Interface

      SUBROUTINE NCINQ(INTEGER NCID, INTEGER NDIMS, INTEGER NVARS,
     *                 INTEGER NGATTS, INTEGER RECDIM, INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
NDIMS: Returned number of dimensions defined for this netCDF file.
NVARS: Returned number of variables defined for this netCDF file.
NGATTS: Returned number of global attributes defined for this netCDF file.
RECDIM: Returned ID of the unlimited dimension, if there is one for this netCDF file. If no unlimited size dimension has been defined, -1 is returned for the value of RECDIM.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCINQ to find out about a netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID, NDIMS, NVARS, NATTS, RECDIM, RCODE
         ...
      NCID = NCOPN('foo.nc', NCNOWRIT, RCODE)
         ...
      CALL NCINQ(NCID, NDIMS, NVARS, NATTS, RECDIM, RCODE)

Synchronize an Open NetCDF File to Disk

The function ncsync (or NCSNC for FORTRAN) makes sure that the disk copy of a netCDF file open for writing is current. The netCDF file must be in data mode. A netCDF file in define mode is synchronized to disk only when ncendef (or NCENDF) is called. A process that is reading a netCDF file that another process is writing can also call ncsync (or NCSNC for FORTRAN) to get updated with the changes made by the writing process (e.g. the number of records written), without having to close and reopen the file.

It can be expensive in computer resources to always synchronize to disk after every write of variable data or change of an attribute value. There are two reasons you might want to synchronize after writes:

To minimize data loss in case of abnormal termination, or
To make data available to other processes for reading immediately after it is written. But note that a process that already had the file open for reading would not see the number of records increase when the writing process calls ncsync; to accomplish this, the reading process must call ncsync.

Data is automatically synchronized to disk when a netCDF file is closed, or whenever you leave define mode.

In case of an error, ncsync returns -1; NCSNC returns a nonzero value in rcode. Possible causes of errors include:

The netCDF file is in define mode.
The specified netCDF ID does not refer to an open netCDF file.

ncsync: C Interface

int ncsync(int ncid);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.

Here is an example using ncsync to synchronize the disk writes of a netCDF file named `foo.nc':

#include "netcdf.h"
   ...
int ncid;
   ...
ncid = ncopen("foo.nc", NC_WRITE);  /* open for writing */

   ...          /* write data or change attributes */

ncsync(ncid);      /* synchronize to disk */

NCSNC: FORTRAN Interface

      SUBROUTINE NCSNC(INTEGER NCID, INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCSNC to synchronize the disk writes of a netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID, RCODE
         ...
      NCID = NCOPN('foo.nc', NCWRITE, RCODE)
         ...
* write data or change attributes
         ...
      CALL NCSNC(NCID, RCODE)

Back Out of Recent Definitions

The function ncabort (or NCABOR for FORTRAN), if not in define mode, closes the netCDF file. If the file is being created and is still in define mode, the file is deleted. If define mode was entered by a call to ncredef (or NCREDF), the netCDF file is restored to its state before definition mode was entered and the file is closed. The main reason for calling ncabort (or NCABOR) is to restore the netCDF to a known consistent state in case anything goes wrong during the definition of new dimensions, variables, or attributes.

This function is called automatically if ncclose (or NCCLOS) is called from define mode and the call to leave define mode before closing fails.

In case of an error, ncabort returns -1; NCABOR returns a nonzero value in rcode. Possible causes of errors include:

When called from define mode while creating a netCDF, deletion of the file failed.
The specified netCDF ID does not refer to an open netCDF file.

ncabort: C Interface

int ncabort(int ncid);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.

Here is an example using ncabort to back out of redefinitions of a file named `foo.nc':

#include "netcdf.h"
   ...
int ncid;
   ...
ncid = ncopen("foo.nc", NC_WRITE);  /* open for writing */
   ...
ncredef(ncid);                    /* enter define mode */
   ...
if (ncdimdef(ncid, "lat", 18L) == -1)
   ncabort(ncid);                 /* define failed, abort */

NCABOR: FORTRAN Interface

      SUBROUTINE NCABOR(INTEGER NCID, INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
RCODE: Returned error code. If no errors occurred, 0 is returned.

Here is an example using NCABOR to back out of redefinitions of a file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID, RCODE, LATID
         ...
      NCID = NCOPN('foo.nc', NCWRITE, RCODE)
         ...
      CALL NCREDF(NCID, RCODE)
         ...
      LATID = NCDDEF(NCID, 'LAT', 18, RCODE)
      IF (RCODE .EQ. -1) THEN  ! dimension definition failed
         CALL NCABOR(NCID, RCODE)  ! abort redefinitions
      ENDIF
         ...

Set Fill Mode for Writes

These calls are intended for advanced usage, to optimize writes under some circumstances described below. The function ncsetfill (or NCSFIL for FORTRAN) sets the fill mode for an netCDF file open for writing and returns the current fill mode. The fill mode can be specified as either NC_FILL or NC_NOFILL (NCFILL or NCNOFILL for FORTRAN). The default behavior corresponding to NC_FILL is that data is pre-filled with fill values, that is fill values are written when you create non-record variables or when you write a value beyond data that hasn't been written yet. This makes it possible to detect attempts to read data before it was written. See section Missing Values, for more information on the use of fill values. See section Attribute Conventions for information about how to define your own fill values.

The behavior corresponding to NC_NOFILL overrides the default behavior of prefilling data with fill values. This can be used to enhance performance, because it avoids the duplicate writes that occur when the netCDF library writes fill values that are immediately overwritten with data.

A value indicating which mode the netCDF file was already in is returned. You can use this value to temporarily change the fill mode of an open netCDF file and then restore it to the previous mode.

After you turn on NC_NOFILL mode for an open netCDF file, you must be certain to write valid data in all the positions that will later be read. Note that NC_NOFILL mode is only a transient property of a netCDF file open for writing: if you close and reopen the file, it will revert to the default behavior. You can also revert to the default behavior by calling ncsetfill (or NCSFIL for FORTRAN) again to explicitly set the fill mode to NC_FILL.

There are three situations where it is advantageous to set nofill mode:

Creating and initializing a netCDF file. In this case, you should set nofill mode before calling ncendef (NCENDF for FORTRAN), and then write completely all non-record variables and the initial records of all the record variables you want to initialize.
Extending an existing record-oriented netCDF file. Set nofill mode after opening the file for writing, then append the additional records to the file completely, leaving no intervening unwritten records.
Adding new variables that you are going to initialize to an existing netCDF file. Set nofill mode before calling ncendef (NCENDF for FORTRAN), then write all the new variables completely.

If the netCDF file has an unlimited dimension and the last record was written while in NC_NOFILL mode, then the file will be 4 bytes longer than if NC_NOFILL mode wasn't set, but this will be completely transparent if you access the data only through the netCDF interfaces.

In case of an error, ncsetfill returns -1; NCSFIL returns a nonzero value in rcode. Possible causes of errors include:

The specified netCDF ID does not refer to an open netCDF file.
The specified netCDF ID refers to a file open for read-only access.
The fillmode argument is neither NC_NOFILL nor NC_FILL (neither NCNOFILL nor NCFILL for FORTRAN).

ncsetfill: C Interface

int ncsetfill(int ncid, int fillmode);

ncid: NetCDF ID, returned from a previous call to ncopen or nccreate.
fillmode: Desired fill mode for the file, either NC_NOFILL or NC_FILL.
ncsetfill: Returns the current fill mode of the file before this call, either NC_NOFILL or NC_FILL.

Here is an example using ncsetfill to set nofill mode for subsequent writes of a netCDF file named `foo.nc':

#include "netcdf.h"
   ...
int ncid;
   ...
ncid = ncopen("foo.nc", NC_WRITE);  /* open for writing */

   ...          /* write data with default prefilling behavior */

ncsetfill(ncid, NC_NOFILL);      /* set nofill mode */

   ...          /* write data with no prefilling */

NCSFIL: FORTRAN Interface

      INTEGER FUNCTION NCSFIL(INTEGER NCID, INTEGER FILLMODE,
     +                        INTEGER RCODE)

NCID: NetCDF ID, returned from a previous call to NCOPN or NCCRE.
FILLMODE: Desired fill mode for the file, either NCNOFILL or NCFILL.
RCODE: Returned error code. If no errors occurred, 0 is returned.
NCSFIL: Returns the current fill mode of the file before this call, either NCNOFILL or NCFILL.

Here is an example using NCSFIL to set nofill mode for a netCDF file named `foo.nc':

      INCLUDE 'netcdf.inc'
         ...
      INTEGER NCID, RCODE, OMODE
         ...
      NCID = NCOPN('foo.nc', NCWRITE, RCODE)
         ...
* write data with default prefilling behavior
         ...
      OMODE = NCSFIL(NCID, NCNOFILL, RCODE)
         ...
* write data with no prefilling
         ...

Go to the previous, next section.