mirror of
https://github.com/Unidata/netcdf-c.git
synced 2024-11-27 07:30:33 +08:00
1e9f243f85
Initial split of Guide from rest of documentation. Using 'tagfiles' to cross-reference from one documentation set to the other works, but then it drags all of the 'external' related pages into the index of the other. Modified visability of the external groups and pages. Adding proper section names to 'Example' sections, to avoid Doxygen warnings. Initial split of Guide from rest of documentation. Using 'tagfiles' to cross-reference from one documentation set to the other works, but then it drags all of the 'external' related pages into the index of the other. Modified visability of the external groups and pages. Adding proper section names to 'Example' sections, to avoid Doxygen warnings. Reorganizing documentation into two separate doxygen projects. Moved .texi documents into an old directory. Pulled the tutorial document into a separate document, similar to the guide document. Turned on treeview
403 lines
12 KiB
C
403 lines
12 KiB
C
/** \file
|
|
Dimension functions
|
|
|
|
These functions define and inquire about dimensions.
|
|
|
|
Copyright 2010 University Corporation for Atmospheric
|
|
Research/Unidata. See COPYRIGHT file for more info.
|
|
*/
|
|
|
|
#include "ncdispatch.h"
|
|
|
|
/**@{*/
|
|
|
|
/*!
|
|
|
|
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.
|
|
|
|
\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.
|
|
|
|
\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
|
|
\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
|
|
|
|
*/
|
|
int
|
|
nc_def_dim(int ncid, const char *name, size_t len, int *idp)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
return ncp->dispatch->def_dim(ncid, name, len, idp);
|
|
}
|
|
|
|
/*!
|
|
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.
|
|
|
|
\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.
|
|
|
|
\returns ::NC_NOERR No error.
|
|
\returns ::NC_EBADID Not a valid ID.
|
|
\returns ::NC_EBADDIM Invalid dimension ID or name.
|
|
*/
|
|
int
|
|
nc_inq_dimid(int ncid, const char *name, int *idp)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
return ncp->dispatch->inq_dimid(ncid,name,idp);
|
|
}
|
|
|
|
/*!
|
|
Find the name and length of a dimension.
|
|
|
|
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 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.
|
|
|
|
\returns ::NC_NOERR No error.
|
|
\returns ::NC_EBADID Not a valid ID.
|
|
\returns ::NC_EBADDIM Invalid dimension ID or name.
|
|
|
|
\section nc_inq_dim_example Example
|
|
|
|
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
|
|
*/
|
|
int
|
|
nc_inq_dim(int ncid, int dimid, char *name, size_t *lenp)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
return ncp->dispatch->inq_dim(ncid,dimid,name,lenp);
|
|
}
|
|
|
|
/*!
|
|
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.
|
|
|
|
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-4 files the dataset is switched to define more for the
|
|
rename, regardless of the name length.
|
|
|
|
\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.
|
|
|
|
\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
|
|
\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:
|
|
|
|
\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
|
|
*/
|
|
int
|
|
nc_rename_dim(int ncid, int dimid, const char *name)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
return ncp->dispatch->rename_dim(ncid,dimid,name);
|
|
}
|
|
|
|
/*!
|
|
Find the number of dimensions.
|
|
|
|
In a classic model netCDF file, this funtion 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 ndimsp Pointer where number of dimensions will be
|
|
written. Ignored if NULL.
|
|
|
|
\returns ::NC_NOERR No error.
|
|
\returns ::NC_EBADID Not a valid ID.
|
|
|
|
*/
|
|
int
|
|
nc_inq_ndims(int ncid, int *ndimsp)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
if(ndimsp == NULL) return NC_NOERR;
|
|
return ncp->dispatch->inq(ncid,ndimsp,NULL,NULL,NULL);
|
|
}
|
|
|
|
/*!
|
|
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.
|
|
|
|
\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.
|
|
|
|
\returns ::NC_NOERR No error.
|
|
\returns ::NC_EBADID Not a valid ID.
|
|
|
|
*/
|
|
int
|
|
nc_inq_unlimdim(int ncid, int *unlimdimidp)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
return ncp->dispatch->inq_unlimdim(ncid,unlimdimidp);
|
|
}
|
|
|
|
/*!
|
|
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 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.
|
|
|
|
\returns ::NC_NOERR No error.
|
|
\returns ::NC_EBADID Not a valid ID.
|
|
\returns ::NC_EBADDIM Invalid dimension ID or name.
|
|
|
|
\section nc_inq_dim_example2 Example
|
|
|
|
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
|
|
|
|
*/
|
|
int
|
|
nc_inq_dimname(int ncid, int dimid, char *name)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
if(name == NULL) return NC_NOERR;
|
|
return ncp->dispatch->inq_dim(ncid,dimid,name,NULL);
|
|
}
|
|
|
|
/*!
|
|
Find the length of a dimension.
|
|
|
|
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 dimid Dimension ID, from a previous call to nc_inq_dimid() or
|
|
nc_def_dim().
|
|
|
|
\param lenp Pointer where the length will be stored.
|
|
|
|
\returns ::NC_NOERR No error.
|
|
\returns ::NC_EBADID Not a valid ID.
|
|
\returns ::NC_EBADDIM Invalid dimension ID or name.
|
|
|
|
\section nc_inq_dim_example3 Example
|
|
|
|
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
|
|
*/
|
|
int
|
|
nc_inq_dimlen(int ncid, int dimid, size_t *lenp)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
if(lenp == NULL) return NC_NOERR;
|
|
return ncp->dispatch->inq_dim(ncid,dimid,NULL,lenp);
|
|
}
|
|
/**@}*/
|