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

2.17 Set/Inquire Default Creation Format: ncmpi_set_default_format and ncmpi_inq_default_format

This function is intended for advanced users. (1.6.1 and later)

Starting from netCDF 3.6, a new file format named 64-bit offset format, or CDF-2, was introduced to relax the limitations on creating very large files. The older format is referred as CDF-1 format.

Users are warned that creating files in the 64-bit offset format makes them unreadable by the netCDF library prior to version 3.6.0. For reasons of compatibility, users should continue to create files in CDF-1 format.

In addition to 64-bit offset format, PnetCDF also supports the 64-bit data format, which allows variables to be defined with more than 4 billion array elements. This format is named CDF-5. Similarly, the files in 64-bite data format cannot be read by the netCDF library version 3.6.0 and all prior to version 3.6.0.

Users who do want to use 64-bit offset or 64-bit data format files can create them directly from ncmpi_create, using the proper cmode flag. (see ncmpi_create).

The function ncmpi_set_default_format allows the user to change the format of the netCDF file to be created by future calls to ncmpi_create without changing the cmode flag.

This allows the user to convert a program to use 64-bit offset or data formation without changing all calls the ncmpi_create. See Large File Support in The PnetCDF Users Guide.

Once the default format is set, all future created files will be in the desired format.

Constants are provided in the pnetcdf.h file to be used with this function, NC_FORMAT_CLASSIC (CDF-1 format), NC_FORMAT_CDF2 (or NC_FORMAT_64BIT), and NC_FORMAT_CDF5 (or NC_FORMAT_64BIT_DATA).

If a non-NULL pointer is provided, it is assumed to point to an integer, where the existing default format will be written.

Using ncmpi_create with a cmode including NC_64BIT_OFFSET or NC_64BIT_DATA overrides the default format, and creates a 64-bit offset (CDF-2) or 64-bit data (CDF-5) file.

Operational Mode

ncmpi_set_default_format is an independent subroutine, but is expected to be called by all processes that intend to create a file later.

ncmpi_inq_default_format is an independent subroutine.

Usage

int ncmpi_set_default_format(int  new_format,
                             int *old_formatp);

int ncmpi_inq_default_format(int *formatp);
new_format

NC_FORMAT_CLASSIC (the default setting), NC_FORMAT_CDF2 (NC_FORMAT_64BIT), or NC_FORMAT_CDF5 (NC_FORMAT_64BIT_DATA).

old_formatp

Either NULL (in which case it will be ignored), or a pointer to an int where the existing default format (i.e. before being changed to the new format) will be written. This allows you to get the existing default format while setting a new default format.

formatp

The current setting for default file format.

Return Error Codes

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

Example

Here is an example using ncmpi_set_default_format to create files in CDF-1, CDF-2, and CDF-5 formats with the same ncmpi_create call: 

#include <pnetcdf.h>
   ... 
int i, ncid;
int format[3] = {NC_FORMAT_CLASSIC, NC_FORMAT_CDF2, NC_FORMAT_CDF5};
   ... 
for (i=0; i<3; i++) {
    status = ncmpi_set_default_format(format[i], NULL);
    if (status != NC_NOERR) handle_error(status);

    status = ncmpi_create(MPI_COMM_WORLD, "foo.nc", NC_CLOBBER, MPI_INFO_NULL,  &ncid);
    if (status != NC_NOERR) handle_error(status);
   ... 
}

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