Next: , Previous: NF_ENDDEF, Up: Datasets


2.11 NF__ENDDEF

The function NF__ENDDEF takes an open netCDF dataset out of define mode. The changes made to the netCDF dataset while it was in define mode are checked and committed to disk if no problems occurred. Non-record variables may be initialized to a "fill value" as well (see NF_SET_FILL). The netCDF dataset is then placed in data mode, so variable data can be read or written.

This call may involve copying data under some circumstances. See File Structure and Performance.

Caution: this function exposes internals of the netcdf version 1 file format. Users should use nc_enddef in most circumstances. This function may not be available on future netcdf implementations.

The current netcdf file format has three sections, the "header" section, the data section for fixed size variables, and the data section for variables which have an unlimited dimension (record variables).

The header begins at the beginning of the file. The index (offset) of the beginning of the other two sections is contained in the header. Typically, there is no space between the sections. This causes copying overhead to accrue if one wishes to change the size of the sections, as may happen when changing names of things, text attribute values, adding attributes or adding variables. Also, for buffered i/o, there may be advantages to aligning sections in certain ways.

The minfree parameters allow one to control costs of future calls to nc_redef, nc_enddef by requesting that minfree bytes be available at the end of the section.

The align parameters allow one to set the alignment of the beginning of the corresponding sections. The beginning of the section is rounded up to an index which is a multiple of the align parameter. The flag value ALIGN_CHUNK tells the library to use the chunksize (see above) as the align parameter.

The file format requires mod 4 alignment, so the align parameters are silently rounded up to multiples of 4. The usual call,

     nc_enddef(ncid);

is equivalent to

     nc_enddef(ncid, 0, 4, 0, 4);

The file format does not contain a "record size" value, this is calculated from the sizes of the record variables. This unfortunate fact prevents us from providing minfree and alignment control of the "records" in a netcdf file. If you add a variable which has an unlimited dimension, the third section will always be copied with the new variable added.

Usage

     INTEGER FUNCTION NF_ENDDEF(INTEGER NCID, INTEGER H_MINFREE, INTEGER V_ALIGN,
                    INTEGER V_MINFREE, INTEGER R_ALIGN)
NCID
NetCDF ID, from a previous call to NF_OPEN or NF_CREATE.
H_MINFREE
Sets the pad at the end of the "header" section.
V_ALIGN
Controls the alignment of the beginning of the data section for fixed size variables.
V_MINFREE
Sets the pad at the end of the data section for fixed size variables.
R_ALIGN
Controls the alignment of the beginning of the data section for variables which have an unlimited dimension (record variables).

Errors

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

Example

Here is an example using NF__ENDDEF to finish the definitions of a new netCDF dataset named foo.nc and put it into data mode:

     INCLUDE 'netcdf.inc'
        ...
     INTEGER NCID, STATUS, H_MINFREE, V_ALIGN, V_MINFREE, R_ALIGN
        ...
     STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
     IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
     
        ...   ! create dimensions, variables, attributes
     
     H_MINFREE = 512
     V_ALIGN = 512
     V_MINFREE = 512
     R_ALIGN = 512
     STATUS = NF_ENDDEF(NCID, H_MINFREE, V_ALIGN, V_MINFREE, R_ALIGN)
     IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)