2.7 Open a NetCDF File for Access: ncmpi_open

The function ncmpi_open opens an existing netCDF file for access.

Operational Mode

This API is a collective routine: all processes must provide the same value for cmode, and all processes must provide filenames that reference the same file. (Values for info may vary.)

Usage

int ncmpi_open (MPI_Comm    comm,
                const char *path,
                int         omode,
                MPI_Info    info,
                int        *ncidp);

comm

An MPI communicator and must be an MPI intracommunicator.

path

File name for netCDF file to be opened.

omode

Either NC_NOWRITE or NC_WRITE.

• NC_NOWRITE specifies the default behavior: open the file with read-only access.
• NC_WRITE is to open the file 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 following modes available in netCDF are not yet supported: NC_DISKLESS, NC_MMAP, NC_CLASSIC_MODEL, NC_NETCDF4, NC_MPIPOSIX, and NC_INMEMORY.

The following modes available in netCDF are ignored: NC_SHARE and NC_MPIIO.

info

An MPI info object that provides information regarding file access patterns and file system specifics (see MPI user guide for further information).Starting from version 1.3.1, the following PnetCDF hints are available:

nc_header_read_chunk_size

PnetCDF reads the file headers in chunks. This hint indicates the chunk size (in bytes). The default is 256 KB.

The constant MPI_INFO_NULL can be used when no info needs to be specified.

ncidp

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

Return Error Codes

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

• NC_ENOENT: The specified netCDF file does not exist.
• NC_EBAD_FILE: Invalid file name, file name too long, or the directory does not exist.
• NC_EINVAL_OMODE: invalid value used in open mode.
• NC_EPERM: Attempting to create a netCDF file in a directory where you do not have permission to open files.
• NC_ESMALL: size of MPI_Offset on the running system is too small for the file format (CDF-2 or CDF-5) in request
• NC_ENOMEM: unable to allocate memory
• NC_ENFILE: Too many files open
• NC_EFILE: other unknown I/O error, including unable to clobber the file
• NC_EMULTIDEFINE_OMODE: inconsistent file open modes among processes.
• NC_EMULTIDEFINE_FNC_ARGS: one or more arguments are inconsistent among processes

Example

Below is an example using ncmpi_open to open an existing netCDF file named foo.nc for read-only.

#include <pnetcdf.h>
   ... 
int err, ncid;
MPI_Info info;
    ...
MPI_Info_create (&info);
MPI_Info_set (info, "romio_no_indep_rw", "true");
MPI_Info_set (info, "nc_header_read_chunk_size", "1024");
    ...
err = ncmpi_open(MPI_COMM_WORLD, "foo.nc", NC_NOWRITE, info,  &ncid);
if (err != NC_NOERR) printf("Error: %s\n",ncmpi_strerror(err));
MPI_Info_free(&info);