Go to the previous, next section.

Put a Record

The function ncrecput writes a multi-variable record of values (or part of a record of values) into the record variables of an open netCDF file. The record is specified by giving a record number. The values to be written are specified by an array of pointers, one for each record variable, to blocks of values. Each block of values should be of the appropriate size and type for a record's worth of data for the corresponding record variable. Each such pointer must be either NULL, to indicate that no data is to be written for that variable, or must point to an entire record's worth of data of the appropriate type for the corresponding record variable. The values for each record variable are assumed to be ordered with the last dimension varying fastest. The netCDF file must be in data mode.

The ncrecput function is not strictly necessary, since the same data may be written with a sequence of calls to ncvarput, one for each record variable for which a non-NULL pointer is specified. This function is provided in the C interface for convenience only; no corresponding Fortran interface is available, so Fortran users should use multiple calls to NCVPT or NCVPTC instead.

To use ncrecput properly, you must know the number, order, and types of record variables in the netCDF file, information that can be determined with a call to ncrecinq. If your assumptions about the number, order, or types of record variables in the file is incorrect, calling this function may lead to incorrect results or even a segmentation violation. Warning: neither the compiler nor the netCDF software can detect errors with the pointer array argument to ncrecput.

In case of a detected error, ncrecput returns -1. Possible causes of detectable errors include:

ncrecput: C Interface

int ncrecput(int ncid, long recnum, const void *datap[]);

ncid
NetCDF ID, returned from a previous call to ncopen or nccreate.

recnum
Record number, specifying the value of the unlimited dimension for which data is to be written. The first record is record number 0. Note that if you specify a value for recnum that is larger than the current size of the unlimited dimension, intervening records will be written with fill values before the data is written in the specified record, unless ncsetfill has been called to specify no prefilling.

datap
Array of pointers to blocks of data values to be written, one for each record variable. datap[i], if non-NULL, must point to an entire record's worth of data for the i-th record variable. For NULL pointers, no data will be written for the corresponding record variables. This permits you to specify an arbitrary subset of record variables. The data pointed to should be of the appropriate type for each record variable. Warning: neither the compiler nor the netCDF software can detect whether the wrong type of data is used.

Here is an example using ncrecput to write the value of a C struct into a netCDF file with a single call. This example assumes that record variables of the appropriate shapes and types have previously been created in the netCDF file. 

#include "netcdf.h"
   ... 
    static struct {
    char city[20];
    long date;
    float lat;
    float lon;
    float precip[24];           /* hourly precipitation */
    } rec = {
        "Pocatello", 
        930228, 
        42.92, 
        -112.60, 
        {0,0,.1,.2,.2,.3,.2,0,0,0,0,0,0,0,0,0,.3,1.1,0,0,0,0,0,0}
    };

    int ncid;                   /* id of open netcdf file */
    long recnum;                /* number of record to write */
    void *datap[5];             /* array of address pointers for record
vars */
    ...
    datap[0] = &rec.city[0];
    datap[1] = &rec.date;
    datap[2] = &rec.lat;
    datap[3] = &rec.lon;
    datap[4] = &rec.precip[0];

    ncrecput(ncid, recnum, datap);  /* instead of 5 calls to ncvarget */

Go to the previous, next section.