Next: , Previous: nc_open, Up: Datasets


2.9 Open a NetCDF Dataset for Access with Performance Tuning: nc__open

A function opens a netCDF dataset for access with an additional performance tuning parameter. When DAP support is enabled, it is possible to open a DAP data source through this interface, but it is deprecated because all of the performance tuning parameters are ignored. The standard nc_open interface should be used instead.

Usage

     int nc__open(const char *path, int mode, size_t *bufrsizehintp, int *ncidp);
path
File name for netCDF dataset to be opened.
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 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.

bufrsizehintp
The argument referenced by bufrsizehintp controls a space versus time tradeoff, memory allocated in the netcdf library versus number of system calls.

Because of internal requirements, the value may not be set to exactly the value requested. The actual value chosen is returned by reference.

Using the value NC_SIZEHINT_DEFAULT causes the library to choose a default. How the system chooses the default depends on the system. On many systems, the "preferred I/O block size" is available from the stat() system call, struct stat member st_blksize. If this is available it is used. Lacking that, twice the system pagesize is used.

Lacking a call to discover the system pagesize, we just set default bufrsize to 8192.

The bufrsize is a property of a given open netcdf descriptor ncid, it is not a persistent property of the netcdf dataset.

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

Errors

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

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;
     size_t bufrsize;
        ...
     *bufrsize = 1024;
     status = nc_open("foo.nc", 0, &bufrsize, &ncid);
     if (status != NC_NOERR) handle_error(status);