Next: , Previous: NF90_INQ_LIBVERS, Up: Datasets


2.5 NF90_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

       function nf90_create(path, cmode, ncid, initialsize, bufrsize, cache_size, &
            cache_nelems, cache_preemption, comm, info)
         implicit none
         character (len = *), intent(in) :: path
         integer, intent(in) :: cmode
         integer, intent(out) :: ncid
         integer, optional, intent(in) :: initialsize
         integer, optional, intent(inout) :: bufrsize
         integer, optional, intent(in) :: cache_size, cache_nelems
         real, optional, intent(in) :: cache_preemption
         integer, optional, intent(in) :: comm, info
         integer :: nf90_create
path
The file name of the new netCDF dataset.
cmode
The creation mode flag. The following flags are available: NF90_NOCLOBBER, NF90_SHARE, NF90_64BIT_OFFSET, NF90_HDF5, and NF90_CLASSIC_MODEL.

A zero value (defined for convenience as NF90_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 NF90_NOCLOBBER means you do not want to clobber (overwrite) an existing dataset; an error (NF90_EEXIST) is returned if the specified dataset already exists.

The NF90_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 NF90_SHARE flag. (This only applies to netCDF-3 classic or 64-bit offset files.)

Setting NF90_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 the NF90_HDF5 flag causes netCDF to create a netCDF-4/HDF5 format output file.

Oring the NF90_CLASSIC_MODEL flag with the NF90_HDF5 flag causes the resulting netCDF-4/HDF5 file to restrict itself to the classic model - none of the new netCDF-4 data model features, such as groups or user-defined types, are allowed in such a file.

ncid
Returned netCDF ID.

The following optional arguments allow additional performance tuning.

initialsize
The initial size of the file (in bytes) at creation time. A value of 0 causes the file size to be computed when nf90_enddef is called. This is ignored for NetCDF-4/HDF5 files.
bufrsize
Controls a space versus time trade-off, 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.

The library chooses a system-dependent default value if NF90_SIZEHINT_DEFAULT is supplied as input. If the "preferred I/O block size" is available from the stat() system call as member st_blksize this value is used. Lacking that, twice the system pagesize is used. Lacking a call to discover the system pagesize, the default bufrsize is set to 8192 bytes.

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

This is ignored for NetCDF-4/HDF5 files.

cache_size
If the cache_size is provided when creating a netCDF-4/HDF5 file, it will be used instead of the default (32000000) as the size, in bytes, of the HDF5 chunk cache.
cache_nelems
If cache_nelems is provided when creating a netCDF-4/HDF5 file, it will be used instead of the default (1000) as the maximum number of elements in the HDF5 chunk cache.
cache_premtion
If cache_preemption is provided when creating a netCDF-4/HDF5 file, it will be used instead of the default (0.75) as the preemption value for the HDF5 chunk cache.
comm
If the comm and info parameters are provided the file is created and opened for parallel I/O. Set the comm parameter to the MPI communicator (of type MPI_Comm). If this parameter is provided the info parameter must also be provided.
info
If the comm and info parameters are provided the file is created and opened for parallel I/O. Set the comm parameter to the MPI information value (of type MPI_Info). If this parameter is provided the comm parameter must also be provided.

Errors

NF90_CREATE returns the value NF90_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:

      use netcdf
      implicit none
      integer :: ncid, status
      ...
      status = nf90_create(path = "foo.nc", cmode = nf90_noclobber, ncid = ncid)
      if (status /= nf90_noerr) call handle_err(status)