Next: , Previous: , Up: Files   [Index]

2.5 Create a NetCDF File: ncmpi_create

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

A creation mode flag specifies:

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_create (MPI_Comm    comm,
                  const char *path,
                  int         cmode,
                  MPI_Info    info,
                  int        *ncidp);
comm

An MPI communicator and must be an MPI intracommunicator.

path

The file name of the new netCDF file.

cmode

The creation mode flag. The following flags are available: NC_NOCLOBBER, NC_64BIT_OFFSET, and NC_64BIT_DATA.

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

Setting NC_64BIT_OFFSET causes PnetCDF to create a 64-bit offset format file (CDF-2), instead of a netCDF classic format file. The 64-bit offset format imposes far fewer restrictions on large (i.e. over 2 GB) data files.

Setting NC_64BIT_DATA causes PnetCDF to create a 64-bit data format file (CDF-5). The 64-bit data format allows define variables with more than 4 billion array elements.

It is illegal to set a cmode with both NC_64BIT_OFFSET and NC_64BIT_DATA. Error code NC_EINVAL_CMODE will be returned in this case.

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

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 file access hints,including existing MPI hints as well as PnetCDF hints. For MPI hints, users are referred to MPI user guide for further information. Starting from version 1.3.1, the following PnetCDF hints are available:

nc_header_align_size

This hint allows some extra space between the end of the header describing the entire file and the first variable. If you have an application that periodically wishes to add more variables or attributes to an already existing file, expanding the file header size may result in an expensive move of the entire data file to make room for the definition of the new metadata. Hence, setting this hint to a value that is big enough to accommodate any additional variables means you may leave your application code as-is and yet still see tremendous performance improvements.

nc_var_align_size

If you are writing to a block-based parallel file system, such as IBM’s GPFS or Lustre, then an application’s write request will be divided into several blocks (file stripes) and each is sent to a file server based on the file striping setting. If a write straddles two blocks, then locks must be acquired for both blocks. Aligning the start of a variable to a block boundary, combined with collective I/O optimizations in the MPI-IO library can often eliminate all unaligned file system accesses. Starting from version 1.13.0, this hint will only align the starting offset of the entire data section, rather than individual fixed-size variables.

nc_record_align_size

This hint specifies the alignment size for the starting file offset of the record variable section. Note this is not the alignment for individual record variables.

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.

Note the alignment hints set in the run-time environment variable "PNETCDF_HINTS" have the highest priority, which overwrite the alignment hints set in ncmpi__enddef(), which overwrite the alignment hints set in this MPI_Info object.

ncidp

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

Return Error Codes

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

Examples

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

#include <pnetcdf.h>
   ... 
int err, ncid, cmode = NC_NOCLOBBER;
MPI_Info info;
   ...
MPI_Info_create (&info);
MPI_Info_set (info, "romio_no_indep_rw",    "true");
MPI_Info_set (info, "nc_header_align_size", "4194304");
MPI_Info_set (info, "nc_var_align_size",    "1048576");

err = ncmpi_create(MPI_COMM_WORLD, "foo.nc", cmode, info, &ncid);
if (err != NC_NOERR) printf("Error: %s\n",ncmpi_strerror(err));
MPI_Info_free(&info);

The following example creates a netCDF file named foo_large.nc. The new file will be in the 64-bit data format. 

#include <pnetcdf.h>
   ... 
int err, cmode = NC_NOCLOBBER | NC_64BIT_DATA;
MPI_Info info = MPI_INFO_NULL;
   ...
err = ncmpi_create(MPI_COMM_WORLD, "foo_large.nc", cmode, info, &ncid);
if (err != NC_NOERR) printf("Error: %s\n",ncmpi_strerror(err));

Next: , Previous: , Up: Files   [Index]