mirror/netcdf-c
2
0
Fork 0
mirror of https://github.com/Unidata/netcdf-c.git synced 2025-04-12 18:10:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

Clarify docs for var_put and var_get simple interfaces with record variables.

Browse Source
This commit is contained in:
Russ Rew 2011-03-01 13:14:33 +00:00
parent 7d97bbadf9
commit 30add1a3c9
3 changed files with 77 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
man4/netcdf-c.texi
View File

@ -8106,13 +8106,16 @@ variable varies fastest in the C interface. The values are converted
to the external data type of the variable, if necessary.
Take care when using the simplest forms of this interface with record
variables when you don't specify how many records are to be
written. If you try to write all the values of a record variable into
a netCDF file that has no record data yet (hence has 0 records),
nothing will be written. Similarly, if you try to write all of a
record variable but there are more records in the file than you
assume, more data may be written to the file than you supply, which
may result in a segmentation violation.
variables (variables that use the NC_UNLIMITED dimension) when you
don't specify how many records are to be written. If you try to write
all the values of a record variable into a netCDF file that has no
record data yet (hence has 0 records), nothing will be
written. Similarly, if you try to write all the values of a record
variable but there are more records in the file than you assume, more
in-memory data will be accessed than you supply, which may result in a
segmentation violation. To avoid such problems, it is better to use
the nc_put_vara interfaces for variables that use the
NC_UNLIMITED dimension. @xref{nc_put_vara_ type}.
The functions for types ubyte, ushort, uint, longlong, ulonglong, and
string are only available for netCDF-4/HDF5 files.
@ -8195,19 +8198,18 @@ Bad variable ID.
Here is an example using nc_put_var_double to add or change all the
values of the variable named rh to 0.5 in an existing netCDF dataset
named foo.nc. For simplicity in this example, we assume that we know
that rh is dimensioned with time, lat, and lon, and that there are
three time values, five lat values, and ten lon values.
that rh is dimensioned with lat and lon, and that there are
five lat values and ten lon values.
@example
#include <netcdf.h>
...
#define TIMES 3
#define LATS 5
#define LONS 10
int status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
double rh_vals[TIMES*LATS*LONS]; /* array to hold values */
double rh_vals[LATS*LONS]; /* array to hold values */
int i;
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
@ -8216,7 +8218,7 @@ if (status != NC_NOERR) handle_error(status);
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
...
for (i = 0; i < TIMES*LATS*LONS; i++)
for (i = 0; i < LATS*LONS; i++)
rh_vals[i] = 0.5;
/* write values into netCDF variable */
status = nc_put_var_double(ncid, rh_id, rh_vals);
@ -9122,10 +9124,14 @@ once. The values are read into consecutive locations with the last
dimension varying fastest. The netCDF dataset must be in data mode.
Take care when using the simplest forms of this interface with record
variables when you don't specify how many records are to be read. If
you try to read all the values of a record variable into an array but
there are more records in the file than you assume, more data will be
read than you expect, which may cause a segmentation violation.
variables (variables that use the NC_UNLIMITED dimension) when you
don't specify how many records are to be read. If you try to read all
the values of a record variable into an array but there are more
records in the file than you assume, more data will be read than you
expect, which may cause a segmentation violation. To avoid such
problems, it is better to use the nc_get_vara interfaces for
variables that use the NC_UNLIMITED dimension. @xref{nc_get_vara_
type}.
The functions for types ubyte, ushort, uint, longlong, ulonglong, and
string are only available for netCDF-4/HDF5 files.
@ -9224,19 +9230,18 @@ Out of memory.
Here is an example using nc_get_var_double to read all the values of
the variable named rh from an existing netCDF dataset named
foo.nc. For simplicity in this example, we assume that we know that rh
is dimensioned with time, lat, and lon, and that there are three time
values, five lat values, and ten lon values.
is dimensioned with lat and lon, and that there are five lat values
and ten lon values.
@example
#include <netcdf.h>
...
#define TIMES 3
#define LATS 5
#define LONS 10
int status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
double rh_vals[TIMES*LATS*LONS]; /* array to hold values */
double rh_vals[LATS*LONS]; /* array to hold values */
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);

70
man4/netcdf-f77.texi
View File

@ -6591,17 +6591,12 @@ IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
@section Write a Single Data Value: NF_PUT_VAR1_ type
@findex NF_PUT_VAR1_ type
The functions NF_PUT_VAR1_ type put a single data value of the
specified type into a variable of an open netCDF dataset that is in
data mode. Inputs are the netCDF ID, the variable ID, an index that
specifies which value to add or alter, and the data value. The value
is converted to the external data type of the variable, if necessary.
Take care when using the simplest forms of this interface with record
variables when you don't specify how many records are to be read. If
you try to read all the values of a record variable into an array but
there are more records in the file than you assume, more data will be
read than you expect, which may cause a segmentation violation.
The functions NF_PUT_VAR1_type (for various types) put a single data
value of the specified type into a variable of an open netCDF dataset
that is in data mode. Inputs are the netCDF ID, the variable ID, an
index that specifies which value to add or alter, and the data
value. The value is converted to the external data type of the
variable, if necessary.
@heading Usage
@example
@ -6714,13 +6709,16 @@ variable varies fastest in the C interface. The values are converted
to the external data type of the variable, if necessary.
Take care when using the simplest forms of this interface with record
variables when you don't specify how many records are to be
written. If you try to write all the values of a record variable into
a netCDF file that has no record data yet (hence has 0 records),
nothing will be written. Similarly, if you try to write all of a
record variable but there are more records in the file than you
assume, more data may be written to the file than you supply, which
may result in a segmentation violation.
variables (variables that use the NF_UNLIMITED dimension) when you
don't specify how many records are to be written. If you try to write
all the values of a record variable into a netCDF file that has no
record data yet (hence has 0 records), nothing will be written.
Similarly, if you try to write all the values of a record variable
from an array but there are more records in the file than you assume,
more in-memory data will be accessed than you expect, which may cause
a segmentation violation. To avoid such problems, it is better to use
the NF_PUT_VARA_type interfaces for variables that use the
NF_UNLIMITED dimension. @xref{NF_PUT_VARA_ type}.
@heading Usage
@example
@ -6795,16 +6793,16 @@ The specified netCDF ID does not refer to an open netCDF dataset.
Here is an example using NF_PUT_VAR_DOUBLE to add or change all the
values of the variable named rh to 0.5 in an existing netCDF dataset
named foo.nc. For simplicity in this example, we assume that we know
that rh is dimensioned with lon, lat, and time, and that there are ten
lon values, five lat values, and three time values.
that rh is dimensioned with lon and lat, and that there are ten
lon values and five lat values.
@example
INCLUDE 'netcdf.inc'
...
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
INTEGER STATUS, NCID, TIMES
PARAMETER (LATS=5, LONS=10) ! dimension lengths
INTEGER STATUS, NCID
INTEGER RHID ! variable ID
DOUBLE RHVALS(LONS, LATS, TIMES)
DOUBLE RHVALS(LONS, LATS)
...
STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
@ -6813,8 +6811,7 @@ STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
DO 10 ILON = 1, LONS
DO 10 ILAT = 1, LATS
DO 10 ITIME = 1, TIMES
RHVALS(ILON, ILAT, ITIME) = 0.5
RHVALS(ILON, ILAT) = 0.5
10 CONTINUE
STATUS = NF_PUT_var_DOUBLE (NCID, RHID, RHVALS)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
@ -7455,12 +7452,15 @@ or when all the values of a multidimensional variable can be read at
once. The values are read into consecutive locations with the first
dimension varying fastest. The netCDF dataset must be in data mode.
Take care when using the simplest forms of this interface with
record variables when you don't specify how many records are to be
read. If you try to read all the values of a record variable into an
array but there are more records in the file than you assume, more
data will be read than you expect, which may cause a segmentation
violation.
Take care when using the simplest forms of this interface with record
variables (variables that use the NF_UNLIMITED dimension) when you
don't specify how many records are to be read. If you try to read all
the values of a record variable into an array but there are more
records in the file than you assume, more data will be read than you
expect, which may cause a segmentation violation. To avoid such
problems, it is better to use the NF_GET_VARA_type interfaces for
variables that use the NF_UNLIMITED dimension. @xref{NF_GET_VARA_
type}.
@heading Usage
@example
@ -7529,16 +7529,16 @@ The specified netCDF ID does not refer to an open netCDF dataset.
Here is an example using NF_GET_VAR_DOUBLE to read all the values of
the variable named rh from an existing netCDF dataset named
foo.nc. For simplicity in this example, we assume that we know that rh
is dimensioned with lon, lat, and time, and that there are ten lon
values, five lat values, and three time values.
is dimensioned with lon and lat, and that there are ten lon
values and five lat values.
@example
INCLUDE 'netcdf.inc'
...
PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
PARAMETER (LATS=5, LONS=10) ! dimension lengths
INTEGER STATUS, NCID
INTEGER RHID ! variable ID
DOUBLE RHVALS(LONS, LATS, TIMES)
DOUBLE RHVALS(LONS, LATS)
...
STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)

28
man4/netcdf-f90.texi
View File

@ -5246,13 +5246,16 @@ interface. Data values are converted to the external type of the variable,
if necessary.
Take care when using the simplest forms of this interface with record
variables when you don't specify how many records are to be
written. If you try to write all the values of a record variable into
a netCDF file that has no record data yet (hence has 0 records),
nothing will be written. Similarly, if you try to write all of a
record variable but there are more records in the file than you
assume, more data may be written to the file than you supply, which
may result in a segmentation violation.
variables (variables that use the NF90_UNLIMITED dimension) when you
don't specify how many records are to be written. If you try to write
all the values of a record variable into a netCDF file that has no
record data yet (hence has 0 records), nothing will be
written. Similarly, if you try to write all the values of a record
variable from an array but there are more records in the file than you
assume, more in-memory data will be accessed than you expect, which may
cause a segmentation violation. To avoid such problems, it is better
to specify start and count arguments for variables that use the
NF90_UNLIMITED dimension.
@heading Usage
@example
@ -5549,10 +5552,13 @@ variable varies fastest in the Fortran 90 interface. Data values are
converted from the external type of the variable, if necessary.
Take care when using the simplest forms of this interface with record
variables when you don't specify how many records are to be read. If
you try to read all the values of a record variable into an array but
there are more records in the file than you assume, more data will be
read than you expect, which may cause a segmentation violation.
variables (variables that use the NF90_UNLIMITED dimension) when you
don't specify how many records are to be read. If you try to read all
the values of a record variable into an array but there are more
records in the file than you assume, more data will be read than you
expect, which may cause a segmentation violation. To avoid such
problems, it is better to specify the optional start and count
arguments for variables that use the NF90_UNLIMITED dimension.
In netCDF classic model the maximum integer size is NF90_INT, the
4-byte signed integer. Reading variables into an eight-byte integer