Go to the previous, next section.

Get a Record

The function ncrecget reads a multi-variable record of values (or part of a record of values) from the record variables of an open netCDF file. The record is specified by giving a record number. The locations into which the data will be read are specified by an array of pointers, one for each record variable, to blocks of data. Each block of data 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 space for an entire record's worth of data of the appropriate type for the corresponding record variable. The values for each record variable will be ordered with the last dimension varying fastest. The netCDF file must be in data mode.

The ncrecget function is not strictly necessary, since the same data may be read with a sequence of calls to ncvarget, 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 NCVGT or NCVGTC instead.

To use ncrecget 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 ncrecget.

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

• The specified record number is less than zero.

• The specified netCDF file is in define mode rather than data mode.

• The specified netCDF ID does not refer to an open netCDF file.

ncrecget: C Interface

int ncrecget(int ncid, long recnum, 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 read. The first record is record number 0.

datap

Array of pointers to blocks of data into which the requested values will be read, one for each record variable. datap[i], if non-NULL, must point to enough space to hold an entire record's worth of data for the i-th record variable. For NULL pointers, no data will be read 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 ncrecget to read values into several C arrays and scalars 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];
    } rec[10];

    int ncid;           /* id of open netcdf file */
    long i;             /* number of record to read */
    void *datap[5];     /* array of address pointers for record vars */
    ...

    /* Get first 10 records of data */
    for(i=0; i<10; i++) {
        datap[0] = &rec[i].city[0];
        datap[1] = &rec[i].date;
        datap[2] = &rec[i].lat;
        datap[3] = &rec[i].lon;
        datap[4] = &rec[i].precip[0];
        ncrecget(ncid, i, datap);  /* instead of 5 calls to ncvarget */
    }

Go to the previous, next section.