mirror of
https://github.com/Unidata/netcdf-c.git
synced 2024-11-21 03:13:42 +08:00
Merge pull request #1515 from NetCDF-World-Domination-Council/ejh_att_docs
update for attribute documentation
This commit is contained in:
Ward Fisher
GitHub
commit
e4003be502
@ -778,11 +778,11 @@ INPUT = \
|
||||
@abs_top_srcdir@/libdispatch/dvar.c \
|
||||
@abs_top_srcdir@/libdispatch/dvarget.c \
|
||||
@abs_top_srcdir@/libdispatch/dvarinq.c \
|
||||
@abs_top_srcdir@/libdispatch/dvarput.c \
|
||||
@abs_top_srcdir@/libdispatch/datt.c \
|
||||
@abs_top_srcdir@/libdispatch/dattget.c \
|
||||
@abs_top_srcdir@/libdispatch/dattinq.c \
|
||||
@abs_top_srcdir@/libdispatch/dattget.c \
|
||||
@abs_top_srcdir@/libdispatch/dvarput.c \
|
||||
@abs_top_srcdir@/libdispatch/dattput.c \
|
||||
@abs_top_srcdir@/libdispatch/datt.c \
|
||||
@abs_top_srcdir@/libdispatch/dgroup.c \
|
||||
@abs_top_srcdir@/libdispatch/dtype.c \
|
||||
@abs_top_srcdir@/libdispatch/dcompound.c \
|
||||
|
||||
@ -1,92 +1,81 @@
|
||||
/** \file
|
||||
Copyright 2018 University Corporation for Atmospheric
|
||||
Research/Unidata. See \ref copyright file for more info.
|
||||
|
||||
These functions read and write attributes.
|
||||
/*Copyright 2018 University Corporation for Atmospheric
|
||||
Research/Unidata. See copyright file for more info. */
|
||||
/**
|
||||
* @file
|
||||
*
|
||||
* These functions in this file rename and delete attributes.
|
||||
*/
|
||||
|
||||
#include "ncdispatch.h"
|
||||
|
||||
/** \defgroup attributes Attributes
|
||||
|
||||
Attributes hold metadata about data and files.
|
||||
|
||||
\image html ncatts.png "Attributes store metadata."
|
||||
|
||||
Attributes may be associated with a netCDF variable to specify such
|
||||
properties as units, special values, maximum and minimum valid values,
|
||||
scaling factors, and offsets.
|
||||
|
||||
Attributes for a netCDF dataset are defined when the dataset is first
|
||||
created, while the netCDF dataset is in define mode. Additional
|
||||
attributes may be added later by reentering define mode.
|
||||
|
||||
A netCDF attribute has a netCDF variable to which it is assigned, a
|
||||
name, a type, a length, and a sequence of one or more values.
|
||||
|
||||
An attribute is designated by its variable ID and name. When an
|
||||
attribute name is not known, it may be designated by its variable ID
|
||||
and number in order to determine its name, using the function
|
||||
nc_inq_attname().
|
||||
|
||||
The attributes associated with a variable are typically defined
|
||||
immediately after the variable is created, while still in define
|
||||
mode. The data type, length, and value of an attribute may be changed
|
||||
even when in data mode, as long as the changed attribute requires no
|
||||
more space than the attribute as originally defined.
|
||||
|
||||
It is also possible to have attributes that are not associated with
|
||||
any variable. These are called global attributes and are identified by
|
||||
using ::NC_GLOBAL as a variable pseudo-ID. Global attributes are
|
||||
usually related to the netCDF dataset as a whole and may be used for
|
||||
purposes such as providing a title or processing history for a netCDF
|
||||
dataset.
|
||||
|
||||
Operations supported on attributes are:
|
||||
- Create an attribute, given its variable ID, name, data type, length,
|
||||
and value.
|
||||
- Get attribute's data type and length from its variable ID and name.
|
||||
- Get attribute's value from its variable ID and name.
|
||||
- Copy attribute from one netCDF variable to another.
|
||||
- Get name of attribute from its number.
|
||||
- Rename an attribute.
|
||||
- Delete an attribute.
|
||||
/**
|
||||
* @defgroup attributes Attributes
|
||||
*
|
||||
* Attributes hold metadata about data and files.
|
||||
*
|
||||
* @image html ncatts.png "Attributes store metadata."
|
||||
*
|
||||
* Attributes may be associated with a netCDF variable to specify such
|
||||
* properties as units, special values, maximum and minimum valid
|
||||
* values, scaling factors, and offsets.
|
||||
*
|
||||
* It is also possible to have attributes that are not associated with
|
||||
* any variable. These are called global attributes and are identified
|
||||
* by using ::NC_GLOBAL as a variable pseudo-ID. Global attributes are
|
||||
* related to the netCDF dataset as a whole and may be used for
|
||||
* purposes such as providing a title or processing history for a
|
||||
* netCDF dataset. In netCDF-4/HDF5 files, global attributes are
|
||||
* associated with a hierarchical group.
|
||||
*
|
||||
* An attribute is designated by its variable ID and name. When an
|
||||
* attribute name is not known, it may be designated by its variable
|
||||
* ID and number in order to determine its name, using the function
|
||||
* nc_inq_attname().
|
||||
*
|
||||
* Operations supported on attributes are:
|
||||
* - Create an attribute, given its variable ID, name, data type,
|
||||
* length, and value.
|
||||
* - Get attribute's data type and length from its variable ID and
|
||||
name.
|
||||
* - Get attribute's value from its variable ID and name.
|
||||
* - Copy attribute from one netCDF variable to another.
|
||||
* - Get name of attribute from its number.
|
||||
* - Rename an attribute.
|
||||
* - Delete an attribute.
|
||||
*/
|
||||
|
||||
/*! \{*/ /* All these functions are part of the above defgroup... */
|
||||
/** @{*/
|
||||
|
||||
/**
|
||||
* @name Deleting and Renaming Attributes
|
||||
*
|
||||
* Functions to delete or rename an attribute. */
|
||||
/**@{*/ /* Start doxygen member group. */
|
||||
|
||||
/** \name Deleting and Renaming Attributes
|
||||
|
||||
Functions to delete or rename an attribute. */
|
||||
/*! \{ */ /* All these functions are part of this named group... */
|
||||
|
||||
/*!
|
||||
Rename an attribute.
|
||||
|
||||
The function nc_rename_att() changes the name of an attribute. If the
|
||||
new name is longer than the original name, the netCDF dataset must be
|
||||
in define mode. You cannot rename an attribute to have the same name
|
||||
as another attribute of the same variable.
|
||||
|
||||
\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 varid Variable ID of the attribute's variable, or ::NC_GLOBAL for
|
||||
a global attribute.
|
||||
|
||||
\param name Attribute \ref object_name.
|
||||
|
||||
\param newname The new attribute \ref object_name.
|
||||
|
||||
<h1>Example</h1>
|
||||
|
||||
Here is an example using nc_rename_att() to rename the variable
|
||||
attribute units to Units for a variable rh in an existing netCDF
|
||||
dataset named foo.nc:
|
||||
|
||||
\code
|
||||
/**
|
||||
* Rename an attribute.
|
||||
*
|
||||
* The function nc_rename_att() changes the name of an attribute. In
|
||||
* classic formats, if the new name is longer than the original name,
|
||||
* the netCDF dataset must be in define mode. In netCDF-4/HDF5 files,
|
||||
* attributes may be renamed at any time. You cannot rename an
|
||||
* attribute to have the same name as another attribute of the same
|
||||
* variable.
|
||||
*
|
||||
* @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 varid Variable ID of the attribute's variable, or
|
||||
* ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute \ref object_name.
|
||||
* @param newname The new attribute \ref object_name.
|
||||
*
|
||||
* <h1>Example</h1>
|
||||
*
|
||||
* Here is an example using nc_rename_att() to rename the variable
|
||||
* attribute units to Units for a variable rh in an existing netCDF
|
||||
* dataset named foo.nc:
|
||||
*
|
||||
@code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
int status;
|
||||
@ -101,21 +90,22 @@ dataset named foo.nc:
|
||||
...
|
||||
status = nc_rename_att(ncid, rh_id, "units", "Units");
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
\endcode
|
||||
@endcode
|
||||
|
||||
\returns NC_NOERR No error.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Bad varid.
|
||||
\returns ::NC_EBADNAME Bad name.
|
||||
\returns ::NC_EMAXNAME New name too long.
|
||||
\returns ::NC_EINVAL Name or new name not provided.
|
||||
\returns ::NC_ENAMEINUSE Name already in use.
|
||||
\returns ::NC_EPERM File was opened read only.
|
||||
\returns ::NC_ENOTINDEFINE File is not in define mode.
|
||||
\returns ::NC_ENOTATT Attribute not found.
|
||||
\returns ::NC_EHDFERR Failure at HDF5 layer.
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name.
|
||||
* @return ::NC_EMAXNAME New name too long.
|
||||
* @return ::NC_EINVAL Name or new name not provided.
|
||||
* @return ::NC_ENAMEINUSE Name already in use.
|
||||
* @return ::NC_EPERM File was opened read only.
|
||||
* @return ::NC_ENOTINDEFINE File is not in define mode.
|
||||
* @return ::NC_ENOTATT Attribute not found.
|
||||
* @return ::NC_EHDFERR Failure at HDF5 layer.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_rename_att(int ncid, int varid, const char *name, const char *newname)
|
||||
@ -127,27 +117,28 @@ nc_rename_att(int ncid, int varid, const char *name, const char *newname)
|
||||
return ncp->dispatch->rename_att(ncid, varid, name, newname);
|
||||
}
|
||||
|
||||
/*!
|
||||
Delete an attribute.
|
||||
/**
|
||||
* Delete an attribute.
|
||||
*
|
||||
* The function nc_del_att() deletes a netCDF attribute from an open
|
||||
* netCDF dataset. For classic netCDF formats, the dataset must be in
|
||||
* define mode to delete an attribute. In netCDF-4/HDF5 files,
|
||||
* attributes may be deleted at any time.
|
||||
*
|
||||
* @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 varid Variable ID of the attribute's variable, or
|
||||
* ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
*
|
||||
* <h1>Example</h1>
|
||||
*
|
||||
* Here is an example using nc_del_att() to delete the variable
|
||||
* attribute Units for a variable rh in an existing netCDF dataset
|
||||
* named foo.nc:
|
||||
|
||||
The function nc_del_att() deletes a netCDF attribute from an open
|
||||
netCDF dataset. The netCDF dataset must be in define mode.
|
||||
|
||||
\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 varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
||||
for a global attribute.
|
||||
|
||||
\param name Attribute name.
|
||||
|
||||
<h1>Example</h1>
|
||||
|
||||
Here is an example using nc_del_att() to delete the variable attribute
|
||||
Units for a variable rh in an existing netCDF dataset named foo.nc:
|
||||
|
||||
\code
|
||||
@code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
int status;
|
||||
@ -166,18 +157,19 @@ Units for a variable rh in an existing netCDF dataset named foo.nc:
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
status = nc_enddef(ncid);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
\endcode
|
||||
@endcode
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Bad varid.
|
||||
\returns ::NC_EBADNAME Bad name.
|
||||
\returns ::NC_EINVAL Name not provided.
|
||||
\returns ::NC_EPERM File was opened read only.
|
||||
\returns ::NC_ENOTINDEFINE File is not in define mode.
|
||||
\returns ::NC_ENOTATT Attribute not found.
|
||||
\returns ::NC_EATTMETA Failure at HDF5 layer.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name.
|
||||
* @return ::NC_EINVAL Name not provided.
|
||||
* @return ::NC_EPERM File was opened read only.
|
||||
* @return ::NC_ENOTINDEFINE File is not in define mode.
|
||||
* @return ::NC_ENOTATT Attribute not found.
|
||||
* @return ::NC_EATTMETA Failure at HDF5 layer.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_del_att(int ncid, int varid, const char *name)
|
||||
@ -189,6 +181,6 @@ nc_del_att(int ncid, int varid, const char *name)
|
||||
stat = ncp->dispatch->del_att(ncid, varid, name);
|
||||
return stat;
|
||||
}
|
||||
/*! \} */ /* End of named group ...*/
|
||||
/**@}*/ /* End doxygen member group. */
|
||||
|
||||
/*! \} */ /* End of defgroup. */
|
||||
/**@}*/
|
||||
|
||||
@ -1,60 +1,63 @@
|
||||
/** \file
|
||||
Attribute functions
|
||||
|
||||
These functions read and write attributes.
|
||||
|
||||
Copyright 2018 University Corporation for Atmospheric
|
||||
Research/Unidata. See \ref copyright file for more info. */
|
||||
/* Copyright 2018 University Corporation for Atmospheric
|
||||
Research/Unidata. See copyright file for more info. */
|
||||
/**
|
||||
* @file
|
||||
* Attribute functions
|
||||
*
|
||||
* These functions in this file read attributes.
|
||||
*/
|
||||
|
||||
#include "ncdispatch.h"
|
||||
|
||||
/** \name Getting Attributes
|
||||
|
||||
Functions to get the values of attributes.
|
||||
/**
|
||||
* @anchor getting_attributes
|
||||
* @name Getting Attributes
|
||||
*
|
||||
* Functions to get the values of attributes.
|
||||
*
|
||||
* For classic format files, the netCDF library reads all attributes
|
||||
* into memory when the file is opened with nc_open().
|
||||
*
|
||||
* For netCDF-4/HDF5 files, since version 4.7.2, attributes are not
|
||||
* read on file open. Instead, when the first read of a variable
|
||||
* attribute is done, all attributes for that variable are
|
||||
* read. Subsequent access to other attributes of that variable will
|
||||
* not incur a disk read. Similarly, when the first NC_GLOBAL
|
||||
* attribute is read in a group, all NC_GLOBAL attributes for that
|
||||
* group will be read.
|
||||
*
|
||||
* @note All elements attribute data array are returned, so you must
|
||||
* allocate enough space to hold them. If you don't know how much
|
||||
* space to reserve, call nc_inq_attlen() first to find out the length
|
||||
* of the attribute.
|
||||
*/
|
||||
/*! \{ */
|
||||
|
||||
/*!
|
||||
\ingroup attributes
|
||||
Get an attribute of any type.
|
||||
|
||||
The nc_get_att() functions works for any type of attribute, and must
|
||||
be used to get attributes of user-defined type. We recommend that they
|
||||
type safe versions of this function be used for atomic data types.
|
||||
|
||||
\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 varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
||||
for a global attribute.
|
||||
|
||||
\param name Attribute name.
|
||||
|
||||
\param value Pointer to location for returned attribute value(s). All
|
||||
elements of the vector of attribute values are returned, so you must
|
||||
allocate enough space to hold them. Before using the value as a C
|
||||
string, make sure it is null-terminated. Call nc_inq_attlen() first to
|
||||
find out the length of the attribute.
|
||||
|
||||
\note See documentation for nc_get_att_string() regarding a special
|
||||
case where memory must be explicitly released.
|
||||
|
||||
\returns ::NC_NOERR for success.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Bad varid.
|
||||
\returns ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
\returns ::NC_EINVAL Invalid parameters.
|
||||
\returns ::NC_ENOTATT Can't find attribute.
|
||||
\returns ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
\returns ::NC_ERANGE Data conversion went out of range.
|
||||
|
||||
<h1>Example</h1>
|
||||
|
||||
Here is an example using nc_get_att() from nc_test4/tst_vl.c creates a
|
||||
VLEN attribute, then uses nc_get_att() to read it.
|
||||
/**@{*/ /* Start doxygen member group. */
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute of any type.
|
||||
*
|
||||
* The nc_get_att() function works for any type of attribute, and must
|
||||
* be used to get attributes of user-defined type. We recommend that
|
||||
* the type safe versions of this function be used for atomic data
|
||||
* types.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @note See documentation for nc_get_att_string() regarding a special
|
||||
* case where memory must be explicitly released.
|
||||
*
|
||||
* <h1>Example</h1>
|
||||
*
|
||||
* Here is an example using nc_get_att() from nc_test4/tst_vl.c
|
||||
* creates a VLEN attribute, then uses nc_get_att() to read it.
|
||||
*
|
||||
@code
|
||||
#define FILE_NAME "tst_vl.nc"
|
||||
#define VLEN_NAME "vlen_name"
|
||||
@ -77,7 +80,17 @@ VLEN attribute, then uses nc_get_att() to read it.
|
||||
if (nc_close(ncid)) ERR;
|
||||
@endcode
|
||||
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att(int ncid, int varid, const char *name, void *value)
|
||||
@ -96,66 +109,49 @@ nc_get_att(int ncid, int varid, const char *name, void *value)
|
||||
TRACE(nc_get_att);
|
||||
return ncp->dispatch->get_att(ncid, varid, name, value, xtype);
|
||||
}
|
||||
/*! \} */
|
||||
|
||||
/*!
|
||||
\ingroup attributes
|
||||
Get an attribute.
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get a text attribute.
|
||||
*
|
||||
* This function gets a text attribute from the netCDF
|
||||
* file. Type conversions are not permitted.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @note The handling of NULL terminators is not specified by
|
||||
* netCDF. C programs can write attributes with or without NULL
|
||||
* terminators. It is up to the reader to know whether NULL
|
||||
* terminators have been used, and, if not, to add a NULL terminator
|
||||
* when reading text attributes.
|
||||
*
|
||||
* <h1>Example</h1>
|
||||
*
|
||||
* Here is an example using nc_get_att_text() to read a global
|
||||
* attribute named title in an existing netCDF dataset named foo.nc.
|
||||
*
|
||||
* In this example we learn the length of the attribute, so that an
|
||||
* array may be allocated, adding 1 in case a NULL terminator is
|
||||
* needed. We then take the precaution of setting the last element of
|
||||
* the array to 0, to NULL terminate the string. If a NULL terminator
|
||||
* was written with this attribute, strlen(title) will show the
|
||||
* correct length (the number of chars before the first NULL
|
||||
* terminator).
|
||||
|
||||
This function gets an attribute from the netCDF file. The nc_get_att()
|
||||
function works with any type of data, including user defined types.
|
||||
|
||||
\note The netCDF library reads all attributes into memory when the
|
||||
file is opened with nc_open(). Getting an attribute copies the value
|
||||
from the in-memory store, and does not incur any file I/O penalties.
|
||||
|
||||
\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 varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
||||
for a global attribute.
|
||||
|
||||
\param name Attribute name.
|
||||
|
||||
\param value Pointer to location for returned attribute value(s). All
|
||||
elements of the vector of attribute values are returned, so you must
|
||||
allocate enough space to hold them. If you don't know how much
|
||||
space to reserve, call nc_inq_attlen() first to find out the length of
|
||||
the attribute.
|
||||
|
||||
\returns ::NC_NOERR for success.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Bad varid.
|
||||
\returns ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
\returns ::NC_EINVAL Invalid parameters.
|
||||
\returns ::NC_ENOTATT Can't find attribute.
|
||||
\returns ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
\returns ::NC_ERANGE Data conversion went out of range.
|
||||
|
||||
<h1>Example</h1>
|
||||
|
||||
Here is an example using nc_get_att_double() to determine the values
|
||||
of a variable attribute named valid_range for a netCDF variable named
|
||||
rh and using nc_get_att_text() to read a global attribute named title
|
||||
in an existing netCDF dataset named foo.nc.
|
||||
|
||||
In this example, it is assumed that we don't know how many values will
|
||||
be returned, but that we do know the types of the attributes. Hence,
|
||||
to allocate enough space to store them, we must first inquire about
|
||||
the length of the attributes.
|
||||
|
||||
\code
|
||||
@code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
int status;
|
||||
int ncid;
|
||||
int rh_id;
|
||||
int vr_len, t_len;
|
||||
double *vr_val;
|
||||
int t_len;
|
||||
char *title;
|
||||
extern char *malloc()
|
||||
|
||||
...
|
||||
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
|
||||
@ -164,25 +160,27 @@ the length of the attributes.
|
||||
status = nc_inq_varid (ncid, "rh", &rh_id);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
...
|
||||
status = nc_inq_attlen (ncid, rh_id, "valid_range", &vr_len);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
status = nc_inq_attlen (ncid, NC_GLOBAL, "title", &t_len);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
|
||||
vr_val = (double *) malloc(vr_len * sizeof(double));
|
||||
title = (char *) malloc(t_len + 1);
|
||||
|
||||
status = nc_get_att_double(ncid, rh_id, "valid_range", vr_val);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
status = nc_get_att_text(ncid, NC_GLOBAL, "title", title);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
title[t_len] = '\0';
|
||||
...
|
||||
\endcode
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
@endcode
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
/*! \{ */
|
||||
|
||||
int
|
||||
nc_get_att_text(int ncid, int varid, const char *name, char *value)
|
||||
{
|
||||
@ -193,6 +191,29 @@ nc_get_att_text(int ncid, int varid, const char *name, char *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_CHAR);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute of an signed char type.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_schar(int ncid, int varid, const char *name, signed char *value)
|
||||
{
|
||||
@ -203,6 +224,96 @@ nc_get_att_schar(int ncid, int varid, const char *name, signed char *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_BYTE);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute of an atomic type.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* This function gets an attribute of an atomic type from the netCDF
|
||||
* file.
|
||||
*
|
||||
* @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 varid Variable ID of the attribute's variable, or
|
||||
* ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* <h1>Example</h1>
|
||||
*
|
||||
* Here is an example using nc_get_att_double() to determine the
|
||||
* values of a variable attribute named valid_range for a netCDF
|
||||
* variable named rh from a netCDF dataset named foo.nc.
|
||||
*
|
||||
* In this example, it is assumed that we don't know how many values
|
||||
* will be returned, but that we do know the types of the
|
||||
* attributes. Hence, to allocate enough space to store them, we must
|
||||
* first inquire about the length of the attributes.
|
||||
|
||||
@code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
int status;
|
||||
int ncid;
|
||||
int rh_id;
|
||||
int vr_len;
|
||||
double *vr_val;
|
||||
|
||||
...
|
||||
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_attlen (ncid, rh_id, "valid_range", &vr_len);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
|
||||
vr_val = (double *) malloc(vr_len * sizeof(double));
|
||||
|
||||
status = nc_get_att_double(ncid, rh_id, "valid_range", vr_val);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
...
|
||||
@endcode
|
||||
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute of an signed char type.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_uchar(int ncid, int varid, const char *name, unsigned char *value)
|
||||
{
|
||||
@ -213,6 +324,29 @@ nc_get_att_uchar(int ncid, int varid, const char *name, unsigned char *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_UBYTE);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute array of type short.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_short(int ncid, int varid, const char *name, short *value)
|
||||
{
|
||||
@ -223,6 +357,29 @@ nc_get_att_short(int ncid, int varid, const char *name, short *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_SHORT);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute array of type int.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_int(int ncid, int varid, const char *name, int *value)
|
||||
{
|
||||
@ -233,6 +390,29 @@ nc_get_att_int(int ncid, int varid, const char *name, int *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_INT);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute array of type long.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_long(int ncid, int varid, const char *name, long *value)
|
||||
{
|
||||
@ -243,6 +423,29 @@ nc_get_att_long(int ncid, int varid, const char *name, long *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, longtype);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute array of type float.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_float(int ncid, int varid, const char *name, float *value)
|
||||
{
|
||||
@ -253,6 +456,29 @@ nc_get_att_float(int ncid, int varid, const char *name, float *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_FLOAT);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute array of type double.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_double(int ncid, int varid, const char *name, double *value)
|
||||
{
|
||||
@ -263,6 +489,29 @@ nc_get_att_double(int ncid, int varid, const char *name, double *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_DOUBLE);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute array of type unsigned char.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_ubyte(int ncid, int varid, const char *name, unsigned char *value)
|
||||
{
|
||||
@ -273,6 +522,29 @@ nc_get_att_ubyte(int ncid, int varid, const char *name, unsigned char *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_UBYTE);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute array of type unsigned short.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_ushort(int ncid, int varid, const char *name, unsigned short *value)
|
||||
{
|
||||
@ -283,6 +555,29 @@ nc_get_att_ushort(int ncid, int varid, const char *name, unsigned short *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_USHORT);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute array of type unsigned int.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_uint(int ncid, int varid, const char *name, unsigned int *value)
|
||||
{
|
||||
@ -293,6 +588,29 @@ nc_get_att_uint(int ncid, int varid, const char *name, unsigned int *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_UINT);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute array of type long long.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_longlong(int ncid, int varid, const char *name, long long *value)
|
||||
{
|
||||
@ -303,6 +621,29 @@ nc_get_att_longlong(int ncid, int varid, const char *name, long long *value)
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_INT64);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute array of type unsigned long long.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_ulonglong(int ncid, int varid, const char *name, unsigned long long *value)
|
||||
{
|
||||
@ -312,52 +653,34 @@ nc_get_att_ulonglong(int ncid, int varid, const char *name, unsigned long long *
|
||||
TRACE(nc_get_att_ulonglong);
|
||||
return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_UINT64);
|
||||
}
|
||||
/*! \} */
|
||||
|
||||
/*!
|
||||
\ingroup attributes
|
||||
Get a variable-length string attribute.
|
||||
|
||||
This function gets an attribute from netCDF file. The nc_get_att()
|
||||
function works with any type of data including user defined types, but
|
||||
this function will retrieve attributes which are of type
|
||||
variable-length string.
|
||||
|
||||
\note Note that unlike most other nc_get_att functions,
|
||||
nc_get_att_string() allocates a chunk of memory which is returned to
|
||||
the calling function. This chunk of memory must be specifically
|
||||
deallocated with nc_free_string() to avoid any memory leaks. Also
|
||||
note that you must still preallocate the memory needed for the array
|
||||
of pointers passed to nc_get_att_string().
|
||||
|
||||
\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 varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
||||
for a global attribute.
|
||||
|
||||
\param name Attribute name.
|
||||
|
||||
\param value Pointer to location for returned attribute value(s). All
|
||||
elements of the vector of attribute values are returned, so you must
|
||||
allocate enough space to hold them. If you don't know how much
|
||||
space to reserve, call nc_inq_attlen() first to find out the length of
|
||||
the attribute.
|
||||
|
||||
\returns ::NC_NOERR for success.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Bad varid.
|
||||
\returns ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
\returns ::NC_EINVAL Invalid parameters.
|
||||
\returns ::NC_ENOTATT Can't find attribute.
|
||||
\returns ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
\returns ::NC_ERANGE Data conversion went out of range.
|
||||
|
||||
\section nc_get_att_string_example Example
|
||||
|
||||
\code{.c}
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Get an attribute array of type string.
|
||||
*
|
||||
* This function gets an attribute from netCDF file. The nc_get_att()
|
||||
* function works with any type of data including user defined types,
|
||||
* but this function will retrieve attributes which are of type
|
||||
* variable-length string.
|
||||
*
|
||||
* Also see @ref getting_attributes "Getting Attributes"
|
||||
*
|
||||
* @note Note that unlike most other nc_get_att functions,
|
||||
* nc_get_att_string() allocates a chunk of memory which is returned
|
||||
* to the calling function. This chunk of memory must be specifically
|
||||
* deallocated with nc_free_string() to avoid any memory leaks. Also
|
||||
* note that you must still preallocate the memory needed for the
|
||||
* array of pointers passed to nc_get_att_string().
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute name.
|
||||
* @param value Pointer that will get array of attribute value(s). Use
|
||||
* nc_inq_attlen() to learn length.
|
||||
*
|
||||
* @section nc_get_att_string_example Example
|
||||
*
|
||||
@code{.c}
|
||||
#include <stdlib.h>
|
||||
#include <stdio.h>
|
||||
#include <string.h>
|
||||
@ -400,10 +723,20 @@ int main(int argc, char ** argv) {
|
||||
|
||||
return 0;
|
||||
}
|
||||
\endcode
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
@endcode
|
||||
|
||||
* @return ::NC_NOERR for success.
|
||||
* @return ::NC_EBADID Bad ncid.
|
||||
* @return ::NC_ENOTVAR Bad varid.
|
||||
* @return ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
* @return ::NC_EINVAL Invalid parameters.
|
||||
* @return ::NC_ENOTATT Can't find attribute.
|
||||
* @return ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM Out of memory.
|
||||
* @return ::NC_ERANGE Data conversion went out of range.
|
||||
*
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att_string(int ncid, int varid, const char *name, char **value)
|
||||
{
|
||||
@ -413,4 +746,4 @@ nc_get_att_string(int ncid, int varid, const char *name, char **value)
|
||||
TRACE(nc_get_att_string);
|
||||
return ncp->dispatch->get_att(ncid,varid,name,(void*)value, NC_STRING);
|
||||
}
|
||||
/*! \} */
|
||||
/**@}*/ /* End doxygen member group. */
|
||||
|
||||
@ -1,52 +1,54 @@
|
||||
/** \file
|
||||
Attribute inquiry functions
|
||||
|
||||
These functions find out about attributes.
|
||||
|
||||
Copyright 2018 University Corporation for Atmospheric
|
||||
/* Copyright 2018 University Corporation for Atmospheric
|
||||
Research/Unidata. See \ref copyright file for more info. */
|
||||
|
||||
/**
|
||||
* @file
|
||||
* Attribute inquiry functions
|
||||
*
|
||||
* These functions find out about attributes.
|
||||
*/
|
||||
#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... */
|
||||
/**
|
||||
* @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 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 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 nc_inq_att_example 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
|
||||
* @ingroup attributes
|
||||
* Return information about a netCDF attribute.
|
||||
*
|
||||
* The function nc_inq_att returns the attribute's type and 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 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 nc_inq_att_example 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;
|
||||
@ -66,18 +68,18 @@ foo.nc:
|
||||
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
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_ENOTVAR bad varid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\returns ::NC_EBADNAME bad name.
|
||||
\returns ::NC_ENOTATT attribute not found.
|
||||
\returns ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM out of memory.
|
||||
\returns ::NC_ERANGE range error when converting data.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
@endcode
|
||||
*
|
||||
* @return ::NC_NOERR no error.
|
||||
* @return ::NC_EBADID bad ncid.
|
||||
* @return ::NC_ENOTVAR bad varid.
|
||||
* @return ::NC_EBADGRPID bad group ID.
|
||||
* @return ::NC_EBADNAME bad name.
|
||||
* @return ::NC_ENOTATT attribute not found.
|
||||
* @return ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM out of memory.
|
||||
* @return ::NC_ERANGE range error when converting data.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_att(int ncid, int varid, const char *name, nc_type *xtypep,
|
||||
@ -90,33 +92,33 @@ nc_inq_att(int ncid, int varid, const char *name, nc_type *xtypep,
|
||||
}
|
||||
|
||||
/**
|
||||
\ingroup attributes
|
||||
Find an attribute ID.
|
||||
|
||||
\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 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.
|
||||
|
||||
\section nc_inq_attid_example Example
|
||||
|
||||
Here is an example using nc_inq_attid() from nc_test4/tst_vars2.c. In
|
||||
this example three attributes are created in a file. Then it is
|
||||
re-opened, and their IDs are checked. They will be 0, 1, and 2, in
|
||||
the order that the attributes were written to the file.
|
||||
|
||||
|
||||
\code
|
||||
* @ingroup attributes
|
||||
* Find an attribute ID.
|
||||
*
|
||||
* @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 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.
|
||||
*
|
||||
* @section nc_inq_attid_example Example
|
||||
*
|
||||
* Here is an example using nc_inq_attid() from
|
||||
* nc_test4/tst_vars2.c. In this example three attributes are created
|
||||
* in a file. Then it is re-opened, and their IDs are checked. They
|
||||
* will be 0, 1, and 2, in the order that the attributes were written
|
||||
* to the file.
|
||||
*
|
||||
@code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
printf("**** testing fill value with three other attributes...");
|
||||
@ -146,16 +148,16 @@ the order that the attributes were written to the file.
|
||||
}
|
||||
|
||||
if (nc_close(ncid)) ERR;
|
||||
\endcode
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_ENOTVAR bad varid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\returns ::NC_EBADNAME bad name.
|
||||
\returns ::NC_ENOTATT attribute not found.
|
||||
\returns ::NC_ENOMEM out of memory.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
@endcode
|
||||
*
|
||||
* @return ::NC_NOERR no error.
|
||||
* @return ::NC_EBADID bad ncid.
|
||||
* @return ::NC_ENOTVAR bad varid.
|
||||
* @return ::NC_EBADGRPID bad group ID.
|
||||
* @return ::NC_EBADNAME bad name.
|
||||
* @return ::NC_ENOTATT attribute not found.
|
||||
* @return ::NC_ENOMEM out of memory.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_attid(int ncid, int varid, const char *name, int *idp)
|
||||
@ -167,33 +169,32 @@ nc_inq_attid(int ncid, int varid, const char *name, int *idp)
|
||||
}
|
||||
|
||||
/**
|
||||
\ingroup attributes
|
||||
Find the name of an attribute.
|
||||
|
||||
\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 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.
|
||||
|
||||
\section nc_inq_attname_example Example
|
||||
|
||||
Here is an example from nc_test4/tst_atts3.c a variable of every type
|
||||
is added to a file, with names from the 'names' array. Then the file
|
||||
is re-opened, and the names of the attributes are checked in a for
|
||||
loop.
|
||||
|
||||
|
||||
\code
|
||||
* @ingroup attributes
|
||||
* Find the name of an attribute.
|
||||
*
|
||||
* @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 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.
|
||||
*
|
||||
* @section nc_inq_attname_example Example
|
||||
*
|
||||
* Here is an example from nc_test4/tst_atts3.c a variable of every
|
||||
* type is added to a file, with names from the 'names' array. Then
|
||||
* the file is re-opened, and the names of the attributes are checked
|
||||
* in a for loop.
|
||||
*
|
||||
@code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
#define NUM_ATTS 8
|
||||
@ -236,18 +237,18 @@ tst_att_ordering(int cmode)
|
||||
|
||||
if (nc_close(ncid)) ERR;
|
||||
|
||||
\endcode
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_ENOTVAR bad varid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\returns ::NC_EBADNAME bad name.
|
||||
\returns ::NC_ENOTATT attribute not found.
|
||||
\returns ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM out of memory.
|
||||
\returns ::NC_ERANGE range error when converting data.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
@endcode
|
||||
*
|
||||
* @return ::NC_NOERR no error.
|
||||
* @return ::NC_EBADID bad ncid.
|
||||
* @return ::NC_ENOTVAR bad varid.
|
||||
* @return ::NC_EBADGRPID bad group ID.
|
||||
* @return ::NC_EBADNAME bad name.
|
||||
* @return ::NC_ENOTATT attribute not found.
|
||||
* @return ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM out of memory.
|
||||
* @return ::NC_ERANGE range error when converting data.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_attname(int ncid, int varid, int attnum, char *name)
|
||||
@ -259,22 +260,21 @@ nc_inq_attname(int ncid, int varid, int attnum, char *name)
|
||||
}
|
||||
|
||||
/**
|
||||
\ingroup attributes
|
||||
Find number of global or group attributes.
|
||||
|
||||
\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 nattsp Pointer where number of global or group attributes will be
|
||||
written. \ref ignored_if_null.
|
||||
|
||||
\section nc_inq_natts_example Example
|
||||
|
||||
Here is an example from
|
||||
|
||||
|
||||
\code
|
||||
* @ingroup attributes
|
||||
* Find number of global or group attributes.
|
||||
*
|
||||
* @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 nattsp Pointer where number of global or group attributes
|
||||
* will be written. \ref ignored_if_null.
|
||||
*
|
||||
* @section nc_inq_natts_example Example
|
||||
*
|
||||
* Here is an example from nc_test4/tst_vars.c:
|
||||
*
|
||||
@code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
int
|
||||
@ -288,13 +288,12 @@ check_4D_example(char *file_name, int expected_format)
|
||||
...
|
||||
if (nc_inq_natts(ncid, &natts_in)) ERR;
|
||||
if (natts_in != 0) ERR;
|
||||
@endcode
|
||||
|
||||
\endcode
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
* @return ::NC_NOERR no error.
|
||||
* @return ::NC_EBADID bad ncid.
|
||||
* @return ::NC_EBADGRPID bad group ID.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_natts(int ncid, int *nattsp)
|
||||
@ -307,28 +306,28 @@ nc_inq_natts(int ncid, int *nattsp)
|
||||
}
|
||||
|
||||
/**
|
||||
\ingroup attributes
|
||||
Find the type of an attribute.
|
||||
|
||||
\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 varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
||||
for a global or group attribute.
|
||||
|
||||
\param name Attribute \ref object_name.
|
||||
|
||||
\param xtypep Pointer to location for returned attribute \ref data_type.
|
||||
|
||||
\section nc_inq_atttype_example Example
|
||||
|
||||
Here is an example from nc_test4/tst_h_refs.c. In this example, a file
|
||||
with an integer attribute is open. It's type is confirmed to be
|
||||
NC_INT.
|
||||
|
||||
|
||||
\code
|
||||
* @ingroup attributes
|
||||
* Find the type of an attribute.
|
||||
*
|
||||
* @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 varid Variable ID of the attribute's variable, or
|
||||
* ::NC_GLOBAL for a global or group attribute.
|
||||
*
|
||||
* @param name Attribute \ref object_name.
|
||||
*
|
||||
* @param xtypep Pointer to location for returned attribute \ref
|
||||
* data_type.
|
||||
*
|
||||
* @section nc_inq_atttype_example Example
|
||||
*
|
||||
* Here is an example from nc_test4/tst_h_refs.c. In this example, a
|
||||
* file with an integer attribute is open. It's type is confirmed to
|
||||
* be NC_INT.
|
||||
*
|
||||
@code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
printf("*** Checking accessing file through netCDF-4 API...");
|
||||
@ -341,18 +340,18 @@ NC_INT.
|
||||
if (nc_inq_atttype(ncid, NC_GLOBAL, INT_ATT_NAME, &type)) ERR;
|
||||
if (type != NC_INT) ERR;
|
||||
|
||||
\endcode
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_ENOTVAR bad varid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\returns ::NC_EBADNAME bad name.
|
||||
\returns ::NC_ENOTATT attribute not found.
|
||||
\returns ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM out of memory.
|
||||
\returns ::NC_ERANGE range error when converting data.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
@endcode
|
||||
*
|
||||
* @return ::NC_NOERR no error.
|
||||
* @return ::NC_EBADID bad ncid.
|
||||
* @return ::NC_ENOTVAR bad varid.
|
||||
* @return ::NC_EBADGRPID bad group ID.
|
||||
* @return ::NC_EBADNAME bad name.
|
||||
* @return ::NC_ENOTATT attribute not found.
|
||||
* @return ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM out of memory.
|
||||
* @return ::NC_ERANGE range error when converting data.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_atttype(int ncid, int varid, const char *name, nc_type *xtypep)
|
||||
@ -364,30 +363,29 @@ nc_inq_atttype(int ncid, int varid, const char *name, nc_type *xtypep)
|
||||
}
|
||||
|
||||
/**
|
||||
\ingroup attributes
|
||||
Find the length of an attribute.
|
||||
|
||||
\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 varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
||||
for a global or group 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.
|
||||
|
||||
\section nc_inq_attlen_example Example
|
||||
|
||||
Here is an example from nc_test4/tst_h_scalar.c which checks the
|
||||
attributes of an already-open netCDF file. In this code, the length of
|
||||
two attributes are checked, and found to be 1.
|
||||
|
||||
|
||||
\code
|
||||
* @ingroup attributes
|
||||
* Find the length of an attribute.
|
||||
*
|
||||
* @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 varid Variable ID of the attribute's variable, or
|
||||
* ::NC_GLOBAL for a global or group 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.
|
||||
*
|
||||
* @section nc_inq_attlen_example Example
|
||||
*
|
||||
* Here is an example from nc_test4/tst_h_scalar.c which checks the
|
||||
* attributes of an already-open netCDF file. In this code, the length
|
||||
* of two attributes are checked, and found to be 1.
|
||||
*
|
||||
@code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
int
|
||||
@ -408,18 +406,18 @@ check_attrs(int ncid, int obj)
|
||||
if (nc_inq_attlen(ncid, obj, VSTR_ATT2_NAME, &len)) ERR_GOTO;
|
||||
if (len != 1) ERR_GOTO;
|
||||
|
||||
\endcode
|
||||
@endcode
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_ENOTVAR bad varid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\returns ::NC_EBADNAME bad name.
|
||||
\returns ::NC_ENOTATT attribute not found.
|
||||
\returns ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM out of memory.
|
||||
\returns ::NC_ERANGE range error when converting data.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
* @return ::NC_NOERR no error.
|
||||
* @return ::NC_EBADID bad ncid.
|
||||
* @return ::NC_ENOTVAR bad varid.
|
||||
* @return ::NC_EBADGRPID bad group ID.
|
||||
* @return ::NC_EBADNAME bad name.
|
||||
* @return ::NC_ENOTATT attribute not found.
|
||||
* @return ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
* @return ::NC_ENOMEM out of memory.
|
||||
* @return ::NC_ERANGE range error when converting data.
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_attlen(int ncid, int varid, const char *name, size_t *lenp)
|
||||
|
||||
@ -1,51 +1,76 @@
|
||||
/** \file
|
||||
Functions to write attributes.
|
||||
|
||||
These functions read and write attributes.
|
||||
|
||||
Copyright 2018 University Corporation for Atmospheric
|
||||
Research/Unidata. See \ref copyright file for more info. */
|
||||
|
||||
/* Copyright 2018 University Corporation for Atmospheric
|
||||
Research/Unidata. See copyright file for more info. */
|
||||
/**
|
||||
* @file
|
||||
* Functions to write attributes.
|
||||
*
|
||||
* These functions write attributes.
|
||||
*/
|
||||
#include "ncdispatch.h"
|
||||
|
||||
/** \name Writing Attributes
|
||||
|
||||
Functions to write attributes. */
|
||||
/*! \{ */
|
||||
|
||||
/*!
|
||||
\ingroup attributes
|
||||
Write a string attribute.
|
||||
|
||||
The function nc_put_att_string adds or changes a variable attribute or
|
||||
global attribute of an open netCDF dataset. The string type is only
|
||||
available in netCDF-4/HDF5 files, when ::NC_CLASSIC_MODEL has not been
|
||||
used in nc_create().
|
||||
|
||||
\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 varid Variable ID of the variable to which the attribute will
|
||||
be assigned or ::NC_GLOBAL for a global or group attribute.
|
||||
|
||||
\param name Attribute \ref object_name. \ref attribute_conventions may
|
||||
apply.
|
||||
|
||||
\param len Number of values provided for the attribute.
|
||||
|
||||
\param value Pointer to one or more values.
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_EINVAL More than one value for _FillValue or trying to set global _FillValue.
|
||||
\returns ::NC_ENOTVAR Couldn't find varid.
|
||||
\returns ::NC_EBADTYPE Fill value and var must be same type.
|
||||
\returns ::NC_ENOMEM Out of memory
|
||||
\returns ::NC_ELATEFILL Fill values must be written while the file
|
||||
is still in initial define mode.
|
||||
/**
|
||||
* @anchor writing_attributes
|
||||
* @name Writing Attributes
|
||||
*
|
||||
* Functions to write attributes.
|
||||
*
|
||||
* For netCDF classic formats, attributes are defined when the dataset
|
||||
* is first created, while the netCDF dataset is in define
|
||||
* mode. Additional attributes may be added later by reentering define
|
||||
* mode. For netCDF-4/HDF5 netCDF files, attributes may be defined at
|
||||
* any time.
|
||||
*
|
||||
* In classic format files, the data type, length, and value of an
|
||||
* attribute may be changed even when in data mode, as long as the
|
||||
* changed attribute requires no more space than the attribute as
|
||||
* originally defined. In netCDF-4/HDF5 files, attribute name, length,
|
||||
* and value may be changed at any time.
|
||||
*
|
||||
* Attribute data conversion automatically takes place when the type
|
||||
* of the data does not match the xtype argument. All attribute data
|
||||
* values are converted to xtype before being written to the file.
|
||||
*
|
||||
* If writing a new attribute, or if the space required to store
|
||||
* the attribute is greater than before, the netCDF dataset must be in
|
||||
* define mode for classic formats (or netCDF-4/HDF5 with
|
||||
* NC_CLASSIC_MODEL).
|
||||
*
|
||||
* @note With netCDF-4 files, nc_put_att will notice if you are
|
||||
* writing a _FillValue attribute, and will tell the HDF5 layer to use
|
||||
* the specified fill value for that variable. With either classic or
|
||||
* netCDF-4 files, a _FillValue attribute will be checked for
|
||||
* validity, to make sure it has only one value and that its type
|
||||
* matches the type of the associated variable.
|
||||
*
|
||||
*/
|
||||
|
||||
|
||||
/**@{*/ /* Start doxygen member group. */
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write a string attribute.
|
||||
*
|
||||
* The function nc_put_att_string adds or changes a variable attribute
|
||||
* or global attribute of an open netCDF dataset. The string type is
|
||||
* only available in netCDF-4/HDF5 files, when ::NC_CLASSIC_MODEL has
|
||||
* not been used in nc_create().
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_string(int ncid, int varid, const char *name,
|
||||
size_t len, const char** value)
|
||||
@ -57,56 +82,38 @@ nc_put_att_string(int ncid, int varid, const char *name,
|
||||
len, (void*)value, NC_STRING);
|
||||
}
|
||||
|
||||
/*!
|
||||
\ingroup attributes
|
||||
Write a text attribute.
|
||||
|
||||
Add or change a text attribute. If this attribute is new, or if the
|
||||
space required to store the attribute is greater than before, the
|
||||
netCDF dataset must be in define mode for classic formats (or
|
||||
netCDF-4/HDF5 with NC_CLASSIC_MODEL).
|
||||
|
||||
Although it's possible to create attributes of all types, text and
|
||||
double attributes are adequate for most purposes.
|
||||
|
||||
Use the nc_put_att function to create attributes of any type,
|
||||
including user-defined types. We recommend using the type safe
|
||||
versions of this function whenever possible.
|
||||
|
||||
\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 varid Variable ID of the variable to which the attribute will
|
||||
be assigned or ::NC_GLOBAL for a global attribute.
|
||||
|
||||
\param name Attribute \ref object_name. \ref attribute_conventions may
|
||||
apply.
|
||||
|
||||
\param len Number of values provided for the attribute.
|
||||
|
||||
\param value Pointer to one or more values.
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_EINVAL More than one value for _FillValue or trying to set global _FillValue.
|
||||
\returns ::NC_ENOTVAR Couldn't find varid.
|
||||
\returns ::NC_EBADTYPE Fill value and var must be same type.
|
||||
\returns ::NC_ENOMEM Out of memory
|
||||
\returns ::NC_ELATEFILL Fill values must be written while the file
|
||||
is still in initial define mode.
|
||||
|
||||
\note With netCDF-4 files, nc_put_att will notice if you are writing a
|
||||
_Fill_Value_ attribute, and will tell the HDF5 layer to use the
|
||||
specified fill value for that variable.
|
||||
|
||||
\section nc_put_att_text_example Example
|
||||
|
||||
Here is an example using nc_put_att_double() to add a variable
|
||||
attribute named valid_range for a netCDF variable named rh and
|
||||
nc_put_att_text() to add a global attribute named title to an existing
|
||||
netCDF dataset named foo.nc:
|
||||
|
||||
\code
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write a text attribute.
|
||||
*
|
||||
* Add or change a text attribute. If this attribute is new, or if the
|
||||
* space required to store the attribute is greater than before, the
|
||||
* netCDF dataset must be in define mode for classic formats (or
|
||||
* netCDF-4/HDF5 with NC_CLASSIC_MODEL).
|
||||
*
|
||||
* Type conversion is not available with text attributes.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @note Whether or not this length includes the NULL character in C
|
||||
* char arrays is a user decision. If the NULL character is not
|
||||
* written, then all C programs must add the NULL character after
|
||||
* reading a text attribute.
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param len The length of the text array.
|
||||
* @param value Pointer to the start of the character array.
|
||||
*
|
||||
* @section nc_put_att_text_example Example
|
||||
*
|
||||
* Here is an example using nc_put_att_double() to add a variable
|
||||
* attribute named valid_range for a netCDF variable named rh and
|
||||
* nc_put_att_text() to add a global attribute named title to an
|
||||
* existing netCDF dataset named foo.nc:
|
||||
*
|
||||
@code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
int status;
|
||||
@ -132,10 +139,17 @@ netCDF dataset named foo.nc:
|
||||
...
|
||||
status = nc_enddef(ncid);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
\endcode
|
||||
@endcode
|
||||
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
|
||||
|
||||
int nc_put_att_text(int ncid, int varid, const char *name,
|
||||
size_t len, const char *value)
|
||||
{
|
||||
@ -146,59 +160,28 @@ int nc_put_att_text(int ncid, int varid, const char *name,
|
||||
(void *)value, NC_CHAR);
|
||||
}
|
||||
|
||||
/*! \} */
|
||||
/*!
|
||||
\ingroup attributes
|
||||
Write an attribute.
|
||||
|
||||
The function nc_put_att_ type adds or changes a variable attribute or
|
||||
global attribute of an open netCDF dataset. If this attribute is new,
|
||||
or if the space required to store the attribute is greater than
|
||||
before, the netCDF dataset must be in define mode for classic formats
|
||||
(or netCDF-4/HDF5 with NC_CLASSIC_MODEL).
|
||||
|
||||
With netCDF-4 files, nc_put_att will notice if you are writing a
|
||||
_FillValue attribute, and will tell the HDF5 layer to use the
|
||||
specified fill value for that variable. With either classic or
|
||||
netCDF-4 files, a _FillValue attribute will be checked for validity,
|
||||
to make sure it has only one value and that its type matches the type
|
||||
of the associated variable.
|
||||
|
||||
Although it's possible to create attributes of all types, text and
|
||||
double attributes are adequate for most purposes.
|
||||
|
||||
\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 varid Variable ID of the variable to which the attribute will
|
||||
be assigned or ::NC_GLOBAL for a global or group attribute.
|
||||
|
||||
\param name Attribute \ref object_name. \ref attribute_conventions may
|
||||
apply.
|
||||
|
||||
\param xtype \ref data_type of the attribute.
|
||||
|
||||
\param len Number of values provided for the attribute.
|
||||
|
||||
\param value Pointer to one or more values.
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_EINVAL More than one value for _FillValue or trying to set global _FillValue.
|
||||
\returns ::NC_ENOTVAR Couldn't find varid.
|
||||
\returns ::NC_EBADTYPE Fill value and var must be same type.
|
||||
\returns ::NC_ENOMEM Out of memory
|
||||
\returns ::NC_ELATEFILL Fill values must be written while the file
|
||||
is still in initial define mode.
|
||||
|
||||
\section nc_put_att_double_example Example
|
||||
|
||||
Here is an example using nc_put_att_double() to add a variable
|
||||
attribute named valid_range for a netCDF variable named rh and
|
||||
nc_put_att_text() to add a global attribute named title to an existing
|
||||
netCDF dataset named foo.nc:
|
||||
|
||||
\code
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of any type.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @section nc_put_att_double_example Example
|
||||
*
|
||||
* Here is an example using nc_put_att_double() to add a variable
|
||||
* attribute named valid_range for a netCDF variable named rh and
|
||||
* nc_put_att_text() to add a global attribute named title to an
|
||||
* existing netCDF dataset named foo.nc:
|
||||
*
|
||||
@code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
int status;
|
||||
@ -224,9 +207,17 @@ netCDF dataset named foo.nc:
|
||||
...
|
||||
status = nc_enddef(ncid);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
\endcode
|
||||
@endcode
|
||||
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
/*! \{*/
|
||||
int
|
||||
nc_put_att(int ncid, int varid, const char *name, nc_type xtype,
|
||||
size_t len, const void *value)
|
||||
@ -238,6 +229,29 @@ nc_put_att(int ncid, int varid, const char *name, nc_type xtype,
|
||||
value, xtype);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type signed char.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_schar(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len, const signed char *value)
|
||||
@ -249,6 +263,29 @@ nc_put_att_schar(int ncid, int varid, const char *name,
|
||||
(void *)value, NC_BYTE);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type unsigned char.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_uchar(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len, const unsigned char *value)
|
||||
@ -260,6 +297,29 @@ nc_put_att_uchar(int ncid, int varid, const char *name,
|
||||
(void *)value, NC_UBYTE);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type short.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_short(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len, const short *value)
|
||||
@ -271,6 +331,29 @@ nc_put_att_short(int ncid, int varid, const char *name,
|
||||
(void *)value, NC_SHORT);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type int.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_int(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len, const int *value)
|
||||
@ -282,6 +365,29 @@ nc_put_att_int(int ncid, int varid, const char *name,
|
||||
(void *)value, NC_INT);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type long.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_long(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len, const long *value)
|
||||
@ -293,6 +399,29 @@ nc_put_att_long(int ncid, int varid, const char *name,
|
||||
(void *)value, longtype);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type float.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_float(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len, const float *value)
|
||||
@ -304,6 +433,29 @@ nc_put_att_float(int ncid, int varid, const char *name,
|
||||
(void *)value, NC_FLOAT);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type double.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_double(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len, const double *value)
|
||||
@ -315,6 +467,29 @@ nc_put_att_double(int ncid, int varid, const char *name,
|
||||
(void *)value, NC_DOUBLE);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type unsigned char.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_ubyte(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len, const unsigned char *value)
|
||||
@ -326,6 +501,29 @@ nc_put_att_ubyte(int ncid, int varid, const char *name,
|
||||
(void *)value, NC_UBYTE);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type unsigned short.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_ushort(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len, const unsigned short *value)
|
||||
@ -337,6 +535,29 @@ nc_put_att_ushort(int ncid, int varid, const char *name,
|
||||
(void *)value, NC_USHORT);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type unsigned int.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_uint(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len, const unsigned int *value)
|
||||
@ -348,6 +569,29 @@ nc_put_att_uint(int ncid, int varid, const char *name,
|
||||
(void *)value, NC_UINT);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type long long.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_longlong(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len,
|
||||
@ -360,6 +604,29 @@ nc_put_att_longlong(int ncid, int varid, const char *name,
|
||||
(void *)value, NC_INT64);
|
||||
}
|
||||
|
||||
/**
|
||||
* @ingroup attributes
|
||||
* Write an attribute of type unsigned long long.
|
||||
*
|
||||
* Also see @ref writing_attributes "Writing Attributes"
|
||||
*
|
||||
* @param ncid NetCDF file or group ID.
|
||||
* @param varid Variable ID, or ::NC_GLOBAL for a global attribute.
|
||||
* @param name Attribute @ref object_name.
|
||||
* @param xtype The type of attribute to write. Data will be converted
|
||||
* to this type.
|
||||
* @param len Number of values provided for the attribute.
|
||||
* @param value Pointer to one or more values.
|
||||
*
|
||||
* @return ::NC_NOERR No error.
|
||||
* @return ::NC_EINVAL Invalid or global _FillValue.
|
||||
* @return ::NC_ENOTVAR Couldn't find varid.
|
||||
* @return ::NC_EBADTYPE Fill value and var must be same type.
|
||||
* @return ::NC_ENOMEM Out of memory
|
||||
* @return ::NC_ELATEFILL Too late to set fill value.
|
||||
*
|
||||
* @author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_put_att_ulonglong(int ncid, int varid, const char *name,
|
||||
nc_type xtype, size_t len,
|
||||
@ -371,3 +638,5 @@ nc_put_att_ulonglong(int ncid, int varid, const char *name,
|
||||
return ncp->dispatch->put_att(ncid, varid, name, xtype, len,
|
||||
(void *)value, NC_UINT64);
|
||||
}
|
||||
|
||||
/**@}*/ /* End doxygen member group. */
|
||||
|
||||
Loading…
Reference in New Issue
Block a user