Next: , Previous: nc_create_par, Up: Datasets


2.8 Open a NetCDF Dataset for Access: nc_open

The function nc_open opens an existing netCDF dataset for access. It determines the underlying file format automatically. Use the same call to open a netCDF classic, 64-bit offset, or netCDF-4 file.

Usage

     int nc_open (const char *path, int omode, int *ncidp);
path
File name for netCDF dataset to be opened. When DAP support is enabled, then the path may be an OPeNDAP URL rather than a file path.
omode
A zero value (or NC_NOWRITE) specifies the default behavior: open the dataset with read-only access, buffering and caching accesses for efficiency

Otherwise, the open mode is NC_WRITE, NC_SHARE, or NC_WRITE|NC_SHARE. Setting the NC_WRITE flag opens the dataset with read-write access. ("Writing" means any kind of change to the dataset, including appending or changing data, adding or renaming dimensions, variables, and attributes, or deleting attributes.)

The NC_SHARE flag is only used for netCDF classic and 64-bit offset files. It is appropriate when one process may be writing the dataset and one or more other processes reading the dataset concurrently; it means that dataset accesses are not buffered and caching is limited. Since the buffering scheme is optimized for sequential access, programs that do not access data sequentially may see some performance improvement by setting the NC_SHARE flag.

It is not necessary to pass any information about the format of the file being opened. The file type will be detected automatically by the netCDF library.

If a the path is a DAP URL, then the open mode is read-only. Setting NC_WRITE will be ignored.

ncidp
Pointer to location where returned netCDF ID is to be stored.

Errors

When opening a netCDF-4 file HDF5 error reporting is turned off, if it is on. This doesn't stop the HDF5 error stack from recording the errors, it simply stops their display to the user through stderr.

nc_open returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

Return Codes

NC_NOERR
No error.
NC_NOMEM
Out of memory.
NC_EHDFERR
HDF5 error. (NetCDF-4 files only.)
NC_EDIMMETA
Error in netCDF-4 dimension metadata. (NetCDF-4 files only.)
NC_ENOCOMPOIND
(NetCDF-4 files only.)

Example

Here is an example using nc_open to open an existing netCDF dataset named foo.nc for read-only, non-shared access:

     #include <netcdf.h>
        ...
     int status;
     int ncid;
        ...
     status = nc_open("foo.nc", 0, &ncid);
     if (status != NC_NOERR) handle_error(status);