Next: , Previous: nc_set_fill, Up: Datasets


2.19 Set Default Creation Format: nc_set_default_format

This function is intended for advanced users.

Starting in version 3.6, netCDF introduced a new data format, the first change in the underlying binary data format since the netCDF interface was released. The new format, 64-bit offset format, was introduced to greatly relax the limitations on creating very large files.

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 netCDF classic format.

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

The function nc_set_default_format allows the user to change the format of the netCDF file to be created by future calls to nc_create (or nc__create) without changing the cmode flag.

This allows the user to convert a program to use 64-bit offset formation without changing all calls the nc_create. See Large File Support.

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

Two constants are provided in the netcdf.h file to be used with this function, NC_FORMAT_64BIT and NC_FORMAT_CLASSIC.

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

Using nc_create with a cmode including NC_64BIT_OFFSET overrides the default format, and creates a 64-bit offset file.

Usage

     int nc_set_default_format(int format, int *old_formatp);
format
Valid formats include NC_FORMAT_CLASSIC (the default), NC_FORMAT_64BIT, and, if –enable-netcdf-4 was used during configure, NC_FORMAT_NETCDF4 and NC_FORMAT_NETCDF4_CLASSIC
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.

Return Codes

NC_NOERR
No error.
NC_EINVAL
Invalid format. Valid formats include NC_FORMAT_CLASSIC, NC_FORMAT_64BIT, and, if –enable-netcdf-4 was used during configure, NC_FORMAT_NETCDF4 and NC_FORMAT_NETCDF4_CLASSIC. Trying to set the default format to something else will result in an invalid argument error.

Example

Here is an example using nc_set_default_format to create the same file in four formats with the same nc_create call (from libsrc4/tst_utf8.c):

     #include <netcdf.h>
        ...
           int ncid, varid, dimids[NDIMS];
           int f;
     
           for (f = NC_FORMAT_CLASSIC; f < NC_FORMAT_NETCDF4_CLASSIC; f++)
           {
              if (nc_set_default_format(f, NULL)) ERR;
              if (nc_create(FILE_NAME, NC_CLOBBER, &ncid)) ERR;
        ...