mirror/netcdf-c
2
0
Fork 0
mirror of https://github.com/Unidata/netcdf-c.git synced 2024-11-21 03:13:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'ejh_rename_docs' of https://github.com/NetCDF-World-Domination-Council/netcdf-c into v4.6.3-dev-branch.wif

Browse Source
This commit is contained in:
Ward Fisher 2019-02-27 14:38:46 -07:00
commit 62109e59e4
6 changed files with 1377 additions and 1341 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
RELEASE_NOTES.md
View File

@ -14,7 +14,7 @@ This file contains a high-level description of this package's evolution. Release
* Fix of --enable-benchmark benchmark tests [Github #1211](https://github.com/Unidata/netcdf-c/issues/1211)
* Update the license from the home-brewed NetCDF license to the standard 3-Clause BSD License. This change does not result in any new restrictions; it is merely the adoption of a standard, well-known and well-understood license in place of the historic NetCDF license written at Unidata. This is part of a broader push by Unidata to adopt modern, standardized licensing.
* [BugFix] Corrected DAP-releated issues on big-endian machines. See [Github #1321](https://github.com/Unidata/netcdf-c/issues/1321), [Github #1302](https://github.com/Unidata/netcdf-c/issues/1302) for more information.
* [BugFix][Enhancement] Various and sundry bugfixes and performance enhancements, thanks to @edhartnett, @gsjaardema, @t-b, @wkliao, and all of our other contributors.
* [BugFix][Enhancement] Various and sundry bugfixes and performance enhancements, thanks to \@edhartnett, \@gsjaardema, \@t-b, \@wkliao, and all of our other contributors.
* [Enhancement] Extended `nccopy -F` syntax to support multiple variables with a single invocation. See [Github #1311](https://github.com/Unidata/netcdf-c/issues/1311) for more information.
* [BugFix] Corrected an issue where DAP2 was incorrectly converting signed bytes, resulting in an erroneous error message under some circumstances. See [GitHub #1317](https://github.com/Unidata/netcdf-c/issues/1317) for more information. See [Github #1319](https://github.com/Unidata/netcdf-c/issues/1319) for related information.
* [BugFix][Enhancement] Modified `nccopy` so that `_NCProperties` is not copied over verbatim but is instead generated based on the version of `libnetcdf` used when copying the file. Additionally, `_NCProperties` are displayed if/when associated with a netcdf3 file, now. See [GitHub #803](https://github.com/Unidata/netcdf-c/issues/803) for more information.

12
docs/guide.dox
View File

@ -8,7 +8,6 @@
- \subpage netcdf_data_set_components
- \subpage netcdf_perf_chunking
- \subpage netcdf_utilities_guide
- \subpage compress
- \subpage BestPractices
- \subpage user_defined_formats
- \subpage users_guide_appendices
@ -48,7 +47,10 @@ web site (http://www.unidata.ucar.edu/netcdf), and with the netCDF
distribution.
The latest version of this document, and the language specific guides,
can be found at the netCDF web site (http://www.unidata.ucar.edu/netcdf/docs) along with extensive additional information about netCDF, including pointers to other software that works with netCDF data.
can be found at the netCDF web site
(http://www.unidata.ucar.edu/netcdf/docs) along with extensive
additional information about netCDF, including pointers to other
software that works with netCDF data.
Separate documentation of the Java netCDF library can be found at
http://www.unidata.ucar.edu/software/netcdf-java/.
@ -88,8 +90,10 @@ were written.
Unidata supports the netCDF interfaces for C (see <a
href="http://www.unidata.ucar.edu/netcdf/docs/" >NetCDF-C User's
Guide</a>), Fortran (see <a href="http://www.unidata.ucar.edu/netcdf/fortran/docs/" >NetCDF-Fortran User's Guide</a>)
and C++ (see <a href="http://www.unidata.ucar.edu/netcdf/documentation/historic/cxx4/index.html"
Guide</a>), Fortran (see <a
href="http://www.unidata.ucar.edu/netcdf/fortran/docs/"
>NetCDF-Fortran User's Guide</a>) and C++ (see <a
href="http://www.unidata.ucar.edu/netcdf/documentation/historic/cxx4/index.html"
>NetCDF C++ Interface Guide</a>).
The netCDF library is supported for various UNIX operating systems. A

650
libdispatch/ddim.c
View File

@ -1,125 +1,122 @@
/** \file
Dimension functions
/* Copyright 2018 University Corporation for Atmospheric
Research/Unidata. See COPYRIGHT file for more info. */
/**
@file
These functions define and inquire about dimensions.
Copyright 2018 University Corporation for Atmospheric
Research/Unidata. See COPYRIGHT file for more info.
The functions in this file define, inquire about, and rename
dimensions.
*/
#include "ncdispatch.h"
/*! \defgroup dimensions Dimensions
/**
@defgroup dimensions Dimensions
Dimensions are used to define the shape of data in netCDF.
Dimensions are used to define the shape of data in netCDF.
Dimensions for a netCDF dataset are defined when it is created, while
the netCDF dataset is in define mode. Additional dimensions may be
added later by reentering define mode. A netCDF dimension has a name
and a length. In a netCDF classic or 64-bit offset file, at most one
dimension can have the unlimited length, which means variables using
this dimension can grow along this dimension. In a netCDF-4 file
multiple unlimited dimensions are supported.
Dimensions for a netCDF dataset are defined when it is created,
while the netCDF dataset is in define mode. Additional dimensions
may be added later by reentering define mode. A netCDF dimension
has a name and a length. In a netCDF classic or 64-bit offset file,
at most one dimension can have the unlimited length, which means
variables using this dimension can grow along this dimension. In a
netCDF-4 file multiple unlimited dimensions are supported.
There is a suggested limit (1024) to the number of dimensions that can
be defined in a single netCDF dataset. The limit is the value of the
predefined macro NC_MAX_DIMS. The purpose of the limit is to make
writing generic applications simpler. They need only provide an array
of NC_MAX_DIMS dimensions to handle any netCDF dataset. The
implementation of the netCDF library does not enforce this advisory
maximum, so it is possible to use more dimensions, if necessary, but
netCDF utilities that assume the advisory maximums may not be able to
handle the resulting netCDF datasets.
There is a suggested limit (1024) to the number of dimensions that
can be defined in a single netCDF dataset. The limit is the value
of the predefined macro ::NC_MAX_DIMS. The purpose of the limit is
to make writing generic applications simpler. They need only
provide an array of ::NC_MAX_DIMS dimensions to handle any netCDF
dataset. The implementation of the netCDF library does not enforce
this advisory maximum, so it is possible to use more dimensions, if
necessary, but netCDF utilities that assume the advisory maximums
may not be able to handle the resulting netCDF datasets.
NC_MAX_VAR_DIMS, which must not exceed NC_MAX_DIMS, is the maximum
number of dimensions that can be used to specify the shape of a single
variable. It is also intended to simplify writing generic
applications.
::NC_MAX_VAR_DIMS, which must not exceed ::NC_MAX_DIMS, is the
maximum number of dimensions that can be used to specify the shape
of a single variable. It is also intended to simplify writing
generic applications.
Ordinarily, the name and length of a dimension are fixed when the
dimension is first defined. The name may be changed later, but the
length of a dimension (other than the unlimited dimension) cannot be
changed without copying all the data to a new netCDF dataset with a
redefined dimension length.
Ordinarily, the name and length of a dimension are fixed when the
dimension is first defined. The name may be changed later, but the
length of a dimension (other than the unlimited dimension) cannot
be changed without copying all the data to a new netCDF dataset
with a redefined dimension length.
Dimension lengths in the C interface are type size_t rather than type
int to make it possible to access all the data in a netCDF dataset on
a platform that only supports a 16-bit int data type, for example
MSDOS. If dimension lengths were type int instead, it would not be
possible to access data from variables with a dimension length greater
than a 16-bit int can accommodate.
Dimension lengths in the C interface are type size_t rather than
type int to make it possible to access all the data in a netCDF
dataset on a platform that only supports a 16-bit int data type,
for example MSDOS. If dimension lengths were type int instead, it
would not be possible to access data from variables with a
dimension length greater than a 16-bit int can accommodate.
A netCDF dimension in an open netCDF dataset is referred to by a small
integer called a dimension ID. In the C interface, dimension IDs are
0, 1, 2, ..., in the order in which the dimensions were defined.
Operations supported on dimensions are:
- Create a dimension, given its name and length.
- Get a dimension ID from its name.
- Get a dimension's name and length from its ID.
- Rename a dimension.
A netCDF dimension in an open netCDF dataset is referred to by a
small integer called a dimension ID. In the C interface, dimension
IDs are 0, 1, 2, ..., in the order in which the dimensions were
defined.
Operations supported on dimensions are:
- Create a dimension, given its name and length.
- Get a dimension ID from its name.
- Get a dimension's name and length from its ID.
- Rename a dimension.
*/
/*! \{*/ /* All these functions are part of the above defgroup... */
/** @{ */
/** \name Deleting and Renaming Dimensions
/**
Define a new dimension. The function nc_def_dim() adds a new
dimension to an open netCDF dataset in define mode. It returns (as an
argument) a dimension ID, given the netCDF ID, the dimension name, and
the dimension length. At most one unlimited length dimension, called
the record dimension, may be defined for each classic or 64-bit offset
netCDF dataset. NetCDF-4 datasets may have multiple unlimited
dimensions.
Functions to delete or rename an dimension. */
/*! \{ */ /* All these functions are part of this named group... */
@param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param name Name of the dimension to be created.
@param len Length of the dimension to be created. Use NC_UNLIMITED for
unlimited dimensions.
@param idp Pointer where dimension ID will be stored.
/*!
@return ::NC_NOERR No error.
@return ::NC_EBADID Not a valid ID.
@return ::NC_EMAXNAME Name is too long.
@return ::NC_EBADNAME Name breaks netCDF name rules.
@return ::NC_EINVAL Invalid input.
@return ::NC_ENOTINDEFINE Not in define mode.
@return ::NC_EDIMSIZE Invalid dimension size.
@return ::NC_EUNLIMIT NC_UNLIMITED size already in use
@return ::NC_EMAXDIMS NC_MAX_DIMS exceeded [not enforced after 4.5.0]
@return ::NC_ENAMEINUSE String match to name in use
@return ::NC_ENOMEM Memory allocation (malloc) failure
@return ::NC_EPERM Write to read only
Define a new dimension. The function nc_def_dim adds a new
dimension to an open netCDF dataset in define mode. It returns (as an
argument) a dimension ID, given the netCDF ID, the dimension name, and
the dimension length. At most one unlimited length dimension, called
the record dimension, may be defined for each classic or 64-bit offset
netCDF dataset. NetCDF-4 datasets may have multiple unlimited
dimensions.
@section nc_def_dim_example Example
\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
Here is an example using nc_def_dim() to create a dimension named lat of
length 18 and a unlimited dimension named rec in a new netCDF dataset
named foo.nc:
\param name Name of the dimension to be created.
@code
#include <netcdf.h>
...
int status, ncid, latid, recid;
...
status = nc_create("foo.nc", NC_NOCLOBBER, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_def_dim(ncid, "lat", 18L, &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_def_dim(ncid, "rec", NC_UNLIMITED, &recid);
if (status != NC_NOERR) handle_error(status);
@endcode
\param len Length of the dimension to be created. Use NC_UNLIMITED for
unlimited dimensions.
\param idp Pointer where dimension ID will be stored.
\retval ::NC_NOERR No error.
\returns ::NC_EBADID Not a valid ID.
\returns ::NC_ENOTINDEFINE Not in define mode.
\returns ::NC_EDIMSIZE Invalid dimension size.
\returns ::NC_EUNLIMIT NC_UNLIMITED size already in use
\returns ::NC_EMAXDIMS NC_MAX_DIMS exceeded [not enforced after 4.5.0]
\returns ::NC_ENAMEINUSE String match to name in use
\returns ::NC_ENOMEM Memory allocation (malloc) failure
\returns ::NC_EPERM Write to read only
\section nc_def_dim_example Example
Here is an example using nc_def_dim() to create a dimension named lat of
length 18 and a unlimited dimension named rec in a new netCDF dataset
named foo.nc:
\code
#include <netcdf.h>
...
int status, ncid, latid, recid;
...
status = nc_create("foo.nc", NC_NOCLOBBER, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_def_dim(ncid, "lat", 18L, &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_def_dim(ncid, "rec", NC_UNLIMITED, &recid);
if (status != NC_NOERR) handle_error(status);
\endcode
*/
@author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
Fisher
*/
int
nc_def_dim(int ncid, const char *name, size_t len, int *idp)
{
@ -130,26 +127,27 @@ nc_def_dim(int ncid, const char *name, size_t len, int *idp)
return ncp->dispatch->def_dim(ncid, name, len, idp);
}
/*!
Find the ID of a dimension from the name.
/**
Find the ID of a dimension from the name.
The function nc_inq_dimid returns (as an argument) the ID of a netCDF
dimension, given the name of the dimension. If ndims is the number of
dimensions defined for a netCDF dataset, each dimension has an ID
between 0 and ndims-1.
The function nc_inq_dimid returns (as an argument) the ID of a
netCDF dimension, given the name of the dimension. If ndims is the
number of dimensions defined for a netCDF dataset, each dimension
has an ID between 0 and ndims-1.
\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param name Name of the dimension.
@param idp Pointer where dimension ID will be stored.
\param name Name of the dimension.
@return ::NC_NOERR No error.
@return ::NC_EBADID Not a valid ID.
@return ::NC_EBADDIM Invalid dimension ID.
\param idp Pointer where dimension ID will be stored.
\returns ::NC_NOERR No error.
\returns ::NC_EBADID Not a valid ID.
\returns ::NC_EBADDIM Invalid dimension ID or name.
*/
@author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
Fisher
*/
int
nc_inq_dimid(int ncid, const char *name, int *idp)
{
@ -160,60 +158,60 @@ nc_inq_dimid(int ncid, const char *name, int *idp)
return ncp->dispatch->inq_dimid(ncid,name,idp);
}
/*!
Find the name and length of a dimension.
/**
Find the name and length of a dimension.
The length for the unlimited dimension, if any, is the number of
records written so far.
The length for the unlimited dimension, if any, is the number of
records written so far.
\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param dimid Dimension ID, from a previous call to nc_inq_dimid() or
nc_def_dim().
@param name Returned dimension name. The caller must allocate space
for the returned name. The maximum possible length, in characters, of
a dimension name is given by the predefined constant
::NC_MAX_NAME. (This doesn't include the null terminator, so declare
your array to be size NC_MAX_NAME+1). The returned character array
will be null-terminated.
@param lenp Pointer to location for returned length of dimension. For
the unlimited dimension, this is the number of records written so far.
\param dimid Dimension ID, from a previous call to nc_inq_dimid() or
nc_def_dim().
@return ::NC_NOERR No error.
@return ::NC_EBADID Not a valid ID.
@return ::NC_EBADDIM Invalid dimension ID or name.
\param name Returned dimension name. The caller must allocate space
for the returned name. The maximum possible length, in characters, of
a dimension name is given by the predefined constant
NC_MAX_NAME. (This doesn't include the null terminator, so declare
your array to be size NC_MAX_NAME+1). The returned character array
will be null-terminated.
@section nc_inq_dim_example Example
\param lenp Pointer to location for returned length of dimension. For
the unlimited dimension, this is the number of records written so far.
Here is an example using nc_inq_dim() to determine the length of a
dimension named lat, and the name and current maximum length of the
unlimited dimension for an existing netCDF dataset named foo.nc:
\returns ::NC_NOERR No error.
\returns ::NC_EBADID Not a valid ID.
\returns ::NC_EBADDIM Invalid dimension ID or name.
@code
#include <netcdf.h>
...
int status, ncid, latid, recid;
size_t latlength, recs;
char recname[NC_MAX_NAME+1];
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_unlimdim(ncid, &recid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_dimid(ncid, "lat", &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dimlen(ncid, latid, &latlength);
if (status != NC_NOERR) handle_error(status);
\section nc_inq_dim_example Example
status = nc_inq_dim(ncid, recid, recname, &recs);
if (status != NC_NOERR) handle_error(status);
@endcode
Here is an example using nc_inq_dim() to determine the length of a
dimension named lat, and the name and current maximum length of the
unlimited dimension for an existing netCDF dataset named foo.nc:
\code
#include <netcdf.h>
...
int status, ncid, latid, recid;
size_t latlength, recs;
char recname[NC_MAX_NAME+1];
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_unlimdim(ncid, &recid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_dimid(ncid, "lat", &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dimlen(ncid, latid, &latlength);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dim(ncid, recid, recname, &recs);
if (status != NC_NOERR) handle_error(status);
\endcode
*/
@author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
Fisher
*/
int
nc_inq_dim(int ncid, int dimid, char *name, size_t *lenp)
{
@ -224,59 +222,65 @@ nc_inq_dim(int ncid, int dimid, char *name, size_t *lenp)
return ncp->dispatch->inq_dim(ncid,dimid,name,lenp);
}
/*!
Rename a dimension.
/**
Rename a dimension.
This function renames an existing dimension in a netCDF dataset open
for writing. You cannot rename a dimension to have the same name as
another dimension.
This function renames an existing dimension in a netCDF dataset
open for writing. You cannot rename a dimension to have the same
name as another dimension.
For netCDF classic and 64-bit offset files, if the new name is longer
than the old name, the netCDF dataset must be in define mode.
For netCDF classic and 64-bit offset files, if the new name is
longer than the old name, which has been flushed to disk, the
netCDF dataset must be in define mode.
For netCDF-4 files the dataset is switched to define mode for the
rename, regardless of the name length.
For netCDF-4 files the length of the name is not checked against
the length of the old name, even for classic model files. This is
due to the difficulty of exactly reproducing classic library
behavior in this case.
\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param dimid Dimension ID, from a previous call to nc_inq_dimid()
or nc_def_dim().
@param name New name for dimension. Must be a null-terminated
string with length less than ::NC_MAX_NAME.
\param dimid Dimension ID, from a previous call to nc_inq_dimid() or
nc_def_dim().
@return ::NC_NOERR No error.
@return ::NC_EBADID Not a valid ID.
@return ::NC_EBADDIM Invalid dimension ID or name.
@return ::NC_ENAMEINUSE String match to name in use
@return ::NC_ENOMEM Memory allocation (malloc) failure
@return ::NC_EPERM Write to read only
@return ::NC_ENOTINDEFINE Not in define mode and new name is longer
than old.
\param name New name for dimension. Must be a null-terminated string
with length less than NC_MAX_NAME.
@section nc_rename_dim_example Example
\returns ::NC_NOERR No error.
\returns ::NC_EBADID Not a valid ID.
\returns ::NC_EBADDIM Invalid dimension ID or name.
\returns ::NC_ENAMEINUSE String match to name in use
\returns ::NC_ENOMEM Memory allocation (malloc) failure
\returns ::NC_EPERM Write to read only
\returns ::NC_ENOTINDEFINE Not in define mode and new name is longer than old.
\section nc_rename_dim_example Example
Here is an example using nc_rename_dim to rename the dimension lat
to latitude in an existing netCDF dataset named foo.nc:
Here is an example using nc_rename_dim to rename the dimension lat to
latitude in an existing netCDF dataset named foo.nc:
@code
#include <netcdf.h>
...
int status, ncid, latid;
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_redef(ncid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dimid(ncid, "lat", &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_rename_dim(ncid, latid, "latitude");
if (status != NC_NOERR) handle_error(status);
status = nc_enddef(ncid);
if (status != NC_NOERR) handle_error(status);
@endcode
\code
#include <netcdf.h>
...
int status, ncid, latid;
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_redef(ncid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dimid(ncid, "lat", &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_rename_dim(ncid, latid, "latitude");
if (status != NC_NOERR) handle_error(status);
status = nc_enddef(ncid);
if (status != NC_NOERR) handle_error(status);
\endcode
*/
@author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
Fisher
*/
int
nc_rename_dim(int ncid, int dimid, const char *name)
{
@ -287,27 +291,28 @@ nc_rename_dim(int ncid, int dimid, const char *name)
return ncp->dispatch->rename_dim(ncid,dimid,name);
}
/*!
Find the number of dimensions.
/**
Find the number of dimensions.
In a classic model netCDF file, this function returns the number of
defined dimensions. In a netCDF-4/HDF5 file, this function returns the
number of dimensions available in the group specified by ncid, which
may be less than the total number of dimensions in a file. In a
netCDF-4/HDF5 file, dimensions are in all sub-groups, sub-sub-groups,
etc.
In a classic model netCDF file, this function returns the number of
defined dimensions. In a netCDF-4/HDF5 file, this function returns
the number of dimensions available in the group specified by ncid,
which may be less than the total number of dimensions in a file. In
a netCDF-4/HDF5 file, dimensions are in all sub-groups,
sub-sub-groups, etc.
\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param ndimsp Pointer where number of dimensions will be
written. Ignored if NULL.
\param ndimsp Pointer where number of dimensions will be
written. Ignored if NULL.
@return ::NC_NOERR No error.
@return ::NC_EBADID Not a valid ID.
\returns ::NC_NOERR No error.
\returns ::NC_EBADID Not a valid ID.
*/
@author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
Fisher
*/
int
nc_inq_ndims(int ncid, int *ndimsp)
{
@ -319,26 +324,28 @@ nc_inq_ndims(int ncid, int *ndimsp)
return ncp->dispatch->inq(ncid,ndimsp,NULL,NULL,NULL);
}
/*!
Find the ID of the unlimited dimension.
/**
Find the ID of the unlimited dimension.
This function finds the ID of the unlimited dimension. For
netCDF-4/HDF5 files (which may have more than one unlimited
dimension), the ID of the first unlimited dimesnion is returned. For
these files, nc_inq_unlimdims() will return all the unlimited dimension IDs.
This function finds the ID of the unlimited dimension. For
netCDF-4/HDF5 files (which may have more than one unlimited
dimension), the ID of the first unlimited dimesnion is
returned. For these files, nc_inq_unlimdims() will return all the
unlimited dimension IDs.
\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param unlimdimidp Pointer where unlimited dimension ID will be
stored. If there is no unlimited dimension, -1 will be stored
here. Ignored if NULL.
\param unlimdimidp Pointer where unlimited dimension ID will be
stored. If there is no unlimited dimension, -1 will be stored
here. Ignored if NULL.
@return ::NC_NOERR No error.
@return ::NC_EBADID Not a valid ID.
\returns ::NC_NOERR No error.
\returns ::NC_EBADID Not a valid ID.
*/
@author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
Fisher
*/
int
nc_inq_unlimdim(int ncid, int *unlimdimidp)
{
@ -349,55 +356,55 @@ nc_inq_unlimdim(int ncid, int *unlimdimidp)
return ncp->dispatch->inq_unlimdim(ncid,unlimdimidp);
}
/*!
Find out the name of a dimension.
/**
Find out the name of a dimension.
\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param dimid Dimension ID, from a previous call to nc_inq_dimid()
or nc_def_dim().
@param name Returned dimension name. The caller must allocate space
for the returned name. The maximum possible length, in characters,
of a dimension name is given by the predefined constant
::NC_MAX_NAME. (This doesn't include the null terminator, so
declare your array to be size NC_MAX_NAME+1). The returned
character array will be null-terminated. Ignored if NULL.
\param dimid Dimension ID, from a previous call to nc_inq_dimid() or
nc_def_dim().
@return ::NC_NOERR No error.
@return ::NC_EBADID Not a valid ID.
@return ::NC_EBADDIM Invalid dimension ID or name.
\param name Returned dimension name. The caller must allocate space
for the returned name. The maximum possible length, in characters, of
a dimension name is given by the predefined constant
NC_MAX_NAME. (This doesn't include the null terminator, so declare
your array to be size NC_MAX_NAME+1). The returned character array
will be null-terminated. Ignored if NULL.
@section nc_inq_dim_example2 Example
\returns ::NC_NOERR No error.
\returns ::NC_EBADID Not a valid ID.
\returns ::NC_EBADDIM Invalid dimension ID or name.
Here is an example using nc_inq_dim() to determine the length of a
dimension named lat, and the name and current maximum length of the
unlimited dimension for an existing netCDF dataset named foo.nc:
\section nc_inq_dim_example2 Example
@code
#include <netcdf.h>
...
int status, ncid, latid, recid;
size_t latlength, recs;
char recname[NC_MAX_NAME+1];
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_unlimdim(ncid, &recid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_dimid(ncid, "lat", &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dimlen(ncid, latid, &latlength);
if (status != NC_NOERR) handle_error(status);
Here is an example using nc_inq_dim() to determine the length of a
dimension named lat, and the name and current maximum length of the
unlimited dimension for an existing netCDF dataset named foo.nc:
status = nc_inq_dim(ncid, recid, recname, &recs);
if (status != NC_NOERR) handle_error(status);
@endcode
\code
#include <netcdf.h>
...
int status, ncid, latid, recid;
size_t latlength, recs;
char recname[NC_MAX_NAME+1];
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_unlimdim(ncid, &recid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_dimid(ncid, "lat", &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dimlen(ncid, latid, &latlength);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dim(ncid, recid, recname, &recs);
if (status != NC_NOERR) handle_error(status);
\endcode
*/
@author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
Fisher
*/
int
nc_inq_dimname(int ncid, int dimid, char *name)
{
@ -409,52 +416,53 @@ nc_inq_dimname(int ncid, int dimid, char *name)
return ncp->dispatch->inq_dim(ncid,dimid,name,NULL);
}
/*!
Find the length of a dimension.
/**
Find the length of a dimension.
The length for the unlimited dimension, if any, is the number of
records written so far.
The length for the unlimited dimension, if any, is the number of
records written so far.
\param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param ncid NetCDF or group ID, from a previous call to nc_open(),
nc_create(), nc_def_grp(), or associated inquiry functions such as
nc_inq_ncid().
@param dimid Dimension ID, from a previous call to nc_inq_dimid()
or nc_def_dim().
@param lenp Pointer where the length will be stored.
\param dimid Dimension ID, from a previous call to nc_inq_dimid() or
nc_def_dim().
@return ::NC_NOERR No error.
@return ::NC_EBADID Not a valid ID.
@return ::NC_EBADDIM Invalid dimension ID or name.
\param lenp Pointer where the length will be stored.
@section nc_inq_dim_example3 Example
\returns ::NC_NOERR No error.
\returns ::NC_EBADID Not a valid ID.
\returns ::NC_EBADDIM Invalid dimension ID or name.
Here is an example using nc_inq_dim() to determine the length of a
dimension named lat, and the name and current maximum length of the
unlimited dimension for an existing netCDF dataset named foo.nc:
\section nc_inq_dim_example3 Example
@code
#include <netcdf.h>
...
int status, ncid, latid, recid;
size_t latlength, recs;
char recname[NC_MAX_NAME+1];
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_unlimdim(ncid, &recid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_dimid(ncid, "lat", &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dimlen(ncid, latid, &latlength);
if (status != NC_NOERR) handle_error(status);
Here is an example using nc_inq_dim() to determine the length of a
dimension named lat, and the name and current maximum length of the
unlimited dimension for an existing netCDF dataset named foo.nc:
status = nc_inq_dim(ncid, recid, recname, &recs);
if (status != NC_NOERR) handle_error(status);
@endcode
\code
#include <netcdf.h>
...
int status, ncid, latid, recid;
size_t latlength, recs;
char recname[NC_MAX_NAME+1];
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_unlimdim(ncid, &recid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_dimid(ncid, "lat", &latid);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dimlen(ncid, latid, &latlength);
if (status != NC_NOERR) handle_error(status);
status = nc_inq_dim(ncid, recid, recname, &recs);
if (status != NC_NOERR) handle_error(status);
\endcode
*/
@author Glenn Davis, Russ Rew, Ed Hartnett, Dennis Heimbigner, Ward
Fisher
*/
int
nc_inq_dimlen(int ncid, int dimid, size_t *lenp)
{
@ -466,6 +474,4 @@ nc_inq_dimlen(int ncid, int dimid, size_t *lenp)
return ncp->dispatch->inq_dim(ncid,dimid,NULL,lenp);
}
/*! \} */ /* End of named group ...*/
/*! \} */ /* End of defgroup. */
/** @} */

2043
libdispatch/dvar.c
View File

File diff suppressed because it is too large Load Diff

6
libdispatch/dvarget.c
View File

@ -107,6 +107,7 @@ NC_get_vara(int ncid, int varid,
}
/**
\internal
Get data for a variable.
\param ncid NetCDF or group ID.
@ -129,7 +130,6 @@ they are read.
\returns ::NC_EBADID Bad ncid.
\ingroup variables
\internal
\author Dennis Heimbigner
*/
static int
@ -547,6 +547,7 @@ NCDEFAULT_get_varm(int ncid, int varid, const size_t *start,
}
/**
\internal
Called by externally visible nc_get_vars_xxx routines.
\param ncid NetCDF or group ID.
@ -575,7 +576,6 @@ they are read.
\returns ::NC_EBADID Bad ncid.
\ingroup variables
\internal
\author Dennis Heimbigner, Ed Hartnett
*/
static int
@ -605,6 +605,7 @@ NC_get_vars(int ncid, int varid, const size_t *start,
}
/**
\internal
Called by externally visible nc_get_varm_xxx routines. Note that the
varm routines are deprecated. Use the vars routines instead for new
code.
@ -637,7 +638,6 @@ they are read.
\returns ::NC_EBADID Bad ncid.
\ingroup variables
\internal
\author Dennis Heimbigner, Ed Hartnett
*/
static int

5
libhdf5/hdf5dim.c
View File

@ -187,6 +187,11 @@ NC4_inq_dim(int ncid, int dimid, char *name, size_t *lenp)
/**
* @internal Rename a dimension, for those who like to prevaricate.
*
* @note If we're not in define mode, new name must be of equal or
* less size, if strict nc3 rules are in effect for this file. But we
* don't check this because reproducing the exact classic behavior
* would be too difficult. See github issue #1340.
*
* @param ncid File and group ID.
* @param dimid Dimension ID.
* @param name New dimension name.