•         advanced

2.5 Create a NetCDF Dataset: nc_create

This function creates a new netCDF dataset, returning a netCDF ID that can subsequently be used to refer to the netCDF dataset in other netCDF function calls. The new netCDF dataset opened for write access and placed in define mode, ready for you to add dimensions, variables, and attributes.

A creation mode flag specifies:

• whether to overwrite any existing dataset with the same name,
• whether access to the dataset is shared,
• whether this file should be in netCDF classic format (the default), the new 64-bit offset format (use NC_64BIT_OFFSET), or NC_NETCDF4 for a netCDF-4/HDF5 file.

Usage

NOTE: When creating 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.

     int nc_create (const char* path, int cmode, int *ncidp);

path

The file name of the new netCDF dataset.

cmode

The creation mode flag. The following flags are available: NC_NOCLOBBER, NC_SHARE, NC_64BIT_OFFSET, NC_NETCDF4.

Setting NC_NOCLOBBER means you do not want to clobber (overwrite) an existing dataset; an error (NC_EEXIST) is returned if the specified dataset already exists.

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.

Setting NC_64BIT_OFFSET causes netCDF to create a 64-bit offset format file, instead of a netCDF classic format file. The 64-bit offset format imposes far fewer restrictions on very large (i.e. over 2 GB) data files. See Large File Support (The NetCDF Users Guide).

A zero value (defined for convenience as NC_CLOBBER) specifies the default behavior: overwrite any existing dataset with the same file name and buffer and cache accesses for efficiency. The dataset will be in netCDF classic format. See NetCDF Classic Format Limitations (The NetCDF Users Guide).

Setting NC_NETCDF4 causes netCDF to create a HDF5/NetCDF-4 file.

ncidp

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

Errors

nc_create returns the value NC_NOERR if no errors occurred. Possible causes of errors include:

• Passing a dataset name that includes a directory that does not exist.
• Specifying a dataset name of a file that exists and also specifying NC_NOCLOBBER.
• Specifying a meaningless value for the creation mode.
• Attempting to create a netCDF dataset in a directory where you don't have permission to create files.

Return Codes

NC_NOERR

No error.

NC_ENOMEM

System out of memory.

NC_EHDFERR

HDF5 error (netCDF-4 files only).

NC_EFILEMETA

Error writing netCDF-4 file-level metadata in HDF5 file. (netCDF-4 files only).

Examples

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

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

In this example we create a netCDF dataset named foo_large.nc. It will be in the 64-bit offset format.

     #include <netcdf.h>
        ...
     int status;
     int ncid;
        ...
     status = nc_create("foo_large.nc", NC_NOCLOBBER|NC_64BIT_OFFSET, &ncid);
     if (status != NC_NOERR) handle_error(status);

In this example we create a netCDF dataset named foo_HDF5.nc. It will be in the HDF5 format.

     #include <netcdf.h>
        ...
     int status;
     int ncid;
        ...
     status = nc_create("foo_HDF5.nc", NC_NOCLOBBER|NC_NETCDF4, &ncid);
     if (status != NC_NOERR) handle_error(status);

In this example we create a netCDF dataset named foo_HDF5_classic.nc. It will be in the HDF5 format, but will not allow the use of any netCDF-4 advanced features. That is, it will conform to the classic netCDF-3 data model.

     #include <netcdf.h>
        ...
     int status;
     int ncid;
        ...
     status = nc_create("foo_HDF5_classic.nc", NC_NOCLOBBER|NC_NETCDF4|NC_CLASSIC_MODEL, &ncid);
     if (status != NC_NOERR) handle_error(status);

A variant of nc_create, nc__create (note the double underscore) allows users to specify two tuning parameters for the file that it is creating. These tuning parameters are not written to the data file, they are only used for so long as the file remains open after an nc__create. See nc__create.

Contact Us   •   Site Map   •   Search   •   Terms and Conditions   •   Privacy Policy   •   Participation Policy

Unidata is a member of the UCAR Office of Programs, is managed by the University Corporation for Atmospheric Research, and is sponsored by the National Science Foundation. P.O. Box 3000   •   Boulder, CO 80307-3000 USA   •   Tel: 303-497-8643   •   Fax: 303-497-8690