mirror of
https://github.com/Unidata/netcdf-c.git
synced 2024-12-03 08:01:25 +08:00
203 lines
5.6 KiB
C
203 lines
5.6 KiB
C
/** \file
|
|
Attribute inquiry functions
|
|
|
|
These functions find out about attributes.
|
|
|
|
Copyright 2011 University Corporation for Atmospheric
|
|
Research/Unidata. See \ref copyright file for more info. */
|
|
|
|
#include "ncdispatch.h"
|
|
|
|
/** \name Learning about Attributes
|
|
|
|
Functions to learn about the attributes in a file. */
|
|
/*! \{ */ /* All these functions are part of this named group... */
|
|
|
|
/**
|
|
\ingroup attributes
|
|
Return information about a netCDF attribute.
|
|
|
|
The function nc_inq_att returns the attribute's type and length.
|
|
|
|
\param ncid NetCDF ID, from a previous call to nc_open() or
|
|
nc_create().
|
|
|
|
\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
|
for a global attribute.
|
|
|
|
\param name Pointer to the location for the returned attribute \ref
|
|
object_name. \ref ignored_if_null.
|
|
|
|
\param xtypep Pointer to location for returned attribute \ref
|
|
data_type. \ref ignored_if_null.
|
|
|
|
\param lenp Pointer to location for returned number of values
|
|
currently stored in the attribute. For attributes of type ::NC_CHAR,
|
|
you should not assume that this includes a trailing zero byte; it
|
|
doesn't if the attribute was stored without a trailing zero byte, for
|
|
example from a FORTRAN program. Before using the value as a C string,
|
|
make sure it is null-terminated. \ref ignored_if_null.
|
|
|
|
\section Example
|
|
|
|
Here is an example using nc_inq_att() to find out the type and length of
|
|
a variable attribute named valid_range for a netCDF variable named rh
|
|
and a global attribute named title in an existing netCDF dataset named
|
|
foo.nc:
|
|
|
|
\code
|
|
#include <netcdf.h>
|
|
...
|
|
int status;
|
|
int ncid;
|
|
int rh_id;
|
|
nc_type vr_type, t_type;
|
|
size_t vr_len, t_len;
|
|
|
|
...
|
|
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
|
|
if (status != NC_NOERR) handle_error(status);
|
|
...
|
|
status = nc_inq_varid (ncid, "rh", &rh_id);
|
|
if (status != NC_NOERR) handle_error(status);
|
|
...
|
|
status = nc_inq_att (ncid, rh_id, "valid_range", &vr_type, &vr_len);
|
|
if (status != NC_NOERR) handle_error(status);
|
|
status = nc_inq_att (ncid, NC_GLOBAL, "title", &t_type, &t_len);
|
|
if (status != NC_NOERR) handle_error(status);
|
|
\endcode
|
|
*/
|
|
int
|
|
nc_inq_att(int ncid, int varid, const char *name, nc_type *xtypep,
|
|
size_t *lenp)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
return ncp->dispatch->inq_att(ncid, varid, name, xtypep, lenp);
|
|
}
|
|
|
|
/**
|
|
\ingroup attributes
|
|
Find an attribute ID.
|
|
|
|
\param ncid NetCDF ID, from a previous call to nc_open() or
|
|
nc_create().
|
|
|
|
\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL for
|
|
a global attribute.
|
|
|
|
\param name Attribute \ref object_name.
|
|
|
|
\param idp Pointer to location for returned attribute number that
|
|
specifies which attribute this is for this variable (or which global
|
|
attribute). If you already know the attribute name, knowing its number
|
|
is not very useful, because accessing information about an attribute
|
|
requires its name.
|
|
*/
|
|
int
|
|
nc_inq_attid(int ncid, int varid, const char *name, int *idp)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
return ncp->dispatch->inq_attid(ncid, varid, name, idp);
|
|
}
|
|
|
|
/**
|
|
\ingroup attributes
|
|
Find the name of an attribute.
|
|
|
|
\param ncid NetCDF ID, from a previous call to nc_open() or
|
|
nc_create().
|
|
|
|
\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
|
for a global attribute.
|
|
|
|
\param attnum Attribute number. The attributes for each variable are
|
|
numbered from 0 (the first attribute) to natts-1, where natts is the
|
|
number of attributes for the variable, as returned from a call to
|
|
nc_inq_varnatts().
|
|
|
|
\param name Pointer to the location for the returned attribute \ref
|
|
object_name.
|
|
*/
|
|
int
|
|
nc_inq_attname(int ncid, int varid, int attnum, char *name)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
return ncp->dispatch->inq_attname(ncid, varid, attnum, name);
|
|
}
|
|
|
|
/**
|
|
\ingroup attributes
|
|
Find number of global attributes.
|
|
|
|
\param ncid NetCDF ID, from a previous call to nc_open() or
|
|
nc_create().
|
|
|
|
\param nattsp Pointer where number of global attributes will be
|
|
written. \ref ignored_if_null.
|
|
*/
|
|
int
|
|
nc_inq_natts(int ncid, int *nattsp)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
if(nattsp == NULL) return NC_NOERR;
|
|
return ncp->dispatch->inq(ncid, NULL, NULL, nattsp, NULL);
|
|
}
|
|
|
|
/**
|
|
\ingroup attributes
|
|
Find the type of an attribute.
|
|
|
|
\param ncid NetCDF ID, from a previous call to nc_open() or
|
|
nc_create().
|
|
|
|
\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
|
for a global attribute.
|
|
|
|
\param name Attribute \ref object_name.
|
|
|
|
\param xtypep Pointer to location for returned attribute \ref data_type.
|
|
*/
|
|
int
|
|
nc_inq_atttype(int ncid, int varid, const char *name, nc_type *xtypep)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
return ncp->dispatch->inq_att(ncid, varid, name, xtypep, NULL);
|
|
}
|
|
|
|
/**
|
|
\ingroup attributes
|
|
Find the length of an attribute.
|
|
|
|
\param ncid NetCDF ID, from a previous call to nc_open() or
|
|
nc_create().
|
|
|
|
\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
|
for a global attribute.
|
|
|
|
\param name Attribute \ref object_name.
|
|
|
|
\param lenp Pointer to location for returned number of values
|
|
currently stored in the attribute. Before using the value as a C
|
|
string, make sure it is null-terminated. \ref ignored_if_null.
|
|
*/
|
|
int
|
|
nc_inq_attlen(int ncid, int varid, const char *name, size_t *lenp)
|
|
{
|
|
NC* ncp;
|
|
int stat = NC_check_id(ncid, &ncp);
|
|
if(stat != NC_NOERR) return stat;
|
|
return ncp->dispatch->inq_att(ncid, varid, name, NULL, lenp);
|
|
}
|
|
|
|
/*! \} */ /* End of named group ...*/
|