Unidata

2.6 NF90_CREATE_PAR

This function is a variant of nf90_create; nf90_create_par allows users to open a file on a MPI/IO or MPI/Posix parallel file system.

This function is only available if the netCDF library was built with a HDF5 library for which –enable-parallel was used, and which was linked (like HDF5) to MPI libraries.

The parallel parameters are not written to the data file, they are only used for so long as the file remains open after an nf90_create_par.

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.

This function is only available for netCDF-4 files. The creation mode flag must include NF90_NETCDF4.

When a netCDF-4 file is created for parallel access, collective operations are the default. To use independent access on a variable, See NF90_VAR_PAR_ACCESS.

Usage

       function nf90_create_par(path, cmode, comm, info, ncid)
         character (len = *), intent(in) :: path
         integer, intent(in) :: cmode
         integer, intent(in) :: comm
         integer, intent(in) :: info
         integer, intent(out) :: ncid
         integer :: nf90_create_par
       end function nf90_create_par

PATH

The file name of the new netCDF dataset.

CMODE

The creation mode flag. The following flags are available: NF90_NOCLOBBER, NF90_NETCDF4 and NF90_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 NF90_NOCLOBBER and NF90_NETCDF4, you could provide the argument OR(NF90_NOCLOBBER, NF90_NETCDF4).

Setting NF90_NETCDF4 causes netCDF to create a netCDF-4/HDF5 format file. Oring NF90_CLASSIC_MODEL with NF90_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.

Only netCDF-4/HDF5 files may be used with parallel I/O.

MPI_COMM

The MPI communicator.

MPI_INFO

The MPI info.

ncid

Returned netCDF ID.

Errors

NF90_CREATE returns the value NF90_NOERR if no errors occurred. Possible causes of errors include:

• Passing a dataset name that includes a directory that does not exist.
• Specifying a dataset name of a file that exists and also specifying NF90_NOCLOBBER.
• Specifying a meaningless value for the creation mode.
• Attempting to create a netCDF dataset in a directory where you don't have permission to create files.

Example

This example comes from the test program nf_test/f90tst_parallel.c, which is only run if –enable-parallel-tests is used with configure.

       call MPI_Init(ierr)
       call MPI_Comm_rank(MPI_COMM_WORLD, my_rank, ierr)
       call MPI_Comm_size(MPI_COMM_WORLD, p, ierr)
     
       ! Create the netCDF file.
       mode_flag = IOR(nf90_netcdf4, nf90_classic_model)
       retval = nf90_create_par(FILE_NAME, mode_flag, MPI_COMM_WORLD, &
            MPI_INFO_NULL, ncid)
       if (retval /= nf90_noerr) call handle_err(retval)