Next: , Previous: NF90_CREATE, Up: Datasets


2.6 NF90_OPEN

The function NF90_OPEN opens an existing netCDF dataset for access.

Usage

       function nf90_open(path, mode, ncid, bufrsize, cache_size, cache_nelems, &
                          cache_preemption, comm, info)
         implicit none
         character (len = *), intent(in) :: path
         integer, intent(in) :: mode
         integer, intent(out) :: ncid
         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_open
path
File name for netCDF dataset to be opened. This may be an OPeNDAP URL if DAP support is enabled.
mode
A zero value (or NF90_NOWRITE) specifies the default behavior: open the dataset with read-only access, buffering and caching accesses for efficiency

Otherwise, the open mode is NF90_WRITE, NF90_SHARE, or NF90_WRITE|NF90_SHARE. Setting the NF90_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 NF90_SHARE flag is appropriate when one process may be writing the dataset and one or more other processes reading the dataset concurrently (note that this is not the same as parallel I/O); 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.

ncid
Returned netCDF ID.

The following optional argument allows additional performance tuning.

bufrsize
This parameter applies only when opening classic format or 64-bit offset files. It is ignored for netCDF-4/HDF5 files.

It 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.

cache_size
If the cache_size is provided when opening 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 opening 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 opening 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 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 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_OPEN returns the value NF90_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

Example

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

      use netcdf
      implicit none
      integer :: ncid, status
      ...
      status = nf90_open(path = "foo.nc", mode = nf90_nowrite, ncid = ncid)
      if (status /= nf90_noerr) call handle_err(status)

Example

Here is an example using NF90_OPEN to open an existing netCDF dataset for parallel I/O access. (Note the use of the comm and info parameters). This example is from test program nf_test/f90tst_parallel.f90.

      use netcdf
      implicit none
      integer :: ncid, status
      ...
       ! Reopen the file.
       call handle_err(nf90_open(FILE_NAME, nf90_nowrite, ncid, comm = MPI_COMM_WORLD, &
            info = MPI_INFO_NULL))