Next: , Previous: NF_INQ_LIBVERS, Up: Datasets


2.5 NF_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 and whether access to the dataset is shared.

Usage

     INTEGER FUNCTION NF_CREATE (CHARACTER*(*) PATH, INTEGER CMODE,
                                 INTEGER ncid)
PATH
The file name of the new netCDF dataset.
CMODE
The creation mode flag. The following flags are available: NF_NOCLOBBER, NF_SHARE, NF_64BIT_OFFSET, NF_NETCDF4 and NF_CLASSIC_MODEL. You can combine the affect of multiple flags in a single argument by using the bitwise OR operator. For example, to specify both NF_NOCLOBBER and NF_SHARE, you could provide the argument OR(NF_NOCLOBBER, NF_SHARE).

A zero value (defined for convenience as NF_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.

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

The NF_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 NF_SHARE flag. This only applied to classic and 64-bit offset format files.

Setting NF_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.

Setting NF_NETCDF4 causes netCDF to create a netCDF-4/HDF5 format file. Oring NF_CLASSIC_MODEL with NF_NETCDF4 causes the netCDF library to create a netCDF-4/HDF5 data file, with the netCDF classic model enforced - none of the new features of the netCDF-4 data model may be usedin such a file, for example groups and user-defined types.

ncid
Returned netCDF ID.

Errors

NF_CREATE returns the value NF_NOERR if no errors occurred. Possible causes of errors include:

Example

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.inc'
       ...
     INTEGER NCID, STATUS
     ...
     STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
     IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)