From 837dccd217be44c081ad0dc98974a71f6de6a3ca Mon Sep 17 00:00:00 2001 From: edwardhartnett Date: Thu, 7 Nov 2019 07:09:54 -0700 Subject: [PATCH 01/11] changed format to match other docs, fixed file documentation --- libdispatch/dattget.c | 285 ++++++++++++++++++++++-------------------- 1 file changed, 146 insertions(+), 139 deletions(-) diff --git a/libdispatch/dattget.c b/libdispatch/dattget.c index 13a9575592..6c0c06279e 100644 --- a/libdispatch/dattget.c +++ b/libdispatch/dattget.c @@ -1,55 +1,59 @@ -/** \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. +/** + * @name Getting Attributes + * + * Functions to get the values of attributes. */ -/*! \{ */ - -/*! -\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. +/** \{ */ +/** + * @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. + * + * @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. + *

Example

Here is an example using nc_get_att() from nc_test4/tst_vl.c creates a @@ -77,7 +81,7 @@ VLEN attribute, then uses nc_get_att() to read it. if (nc_close(ncid)) ERR; @endcode -\author Glenn Davis, Ed Hartnett, Dennis Heimbigner +* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner */ int nc_get_att(int ncid, int varid, const char *name, void *value) @@ -96,43 +100,45 @@ 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. - -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. +/** \} */ + +/** + * @ingroup attributes + * Get an attribute. + * + * 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. + * + * @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.

Example

@@ -146,7 +152,7 @@ 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 ... int status; @@ -178,10 +184,11 @@ the length of the attributes. if (status != NC_NOERR) handle_error(status); title[t_len] = '\0'; ... -\endcode -\author Glenn Davis, Ed Hartnett, Dennis Heimbigner +@endcode + +* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner */ -/*! \{ */ +/** \{ */ int nc_get_att_text(int ncid, int varid, const char *name, char *value) @@ -312,52 +319,52 @@ 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 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. + * + * @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. + * + * @section nc_get_att_string_example Example + * +@code{.c} #include #include #include @@ -400,10 +407,10 @@ int main(int argc, char ** argv) { return 0; } -\endcode -\author Glenn Davis, Ed Hartnett, Dennis Heimbigner -*/ +@endcode +* @author Ed Hartnett, Dennis Heimbigner +*/ int nc_get_att_string(int ncid, int varid, const char *name, char **value) { @@ -413,4 +420,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); } -/*! \} */ +/** \} */ From d961f7b76e5d3a970aa4fef49e5c03c26603a248 Mon Sep 17 00:00:00 2001 From: edwardhartnett Date: Thu, 7 Nov 2019 09:31:04 -0700 Subject: [PATCH 02/11] cleanup of documentation format in attributes write code --- libdispatch/dattput.c | 308 +++++++++++++++++++++--------------------- 1 file changed, 154 insertions(+), 154 deletions(-) diff --git a/libdispatch/dattput.c b/libdispatch/dattput.c index 1a43b52321..b6bef82d63 100644 --- a/libdispatch/dattput.c +++ b/libdispatch/dattput.c @@ -1,51 +1,53 @@ -/** \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. +/** + * @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. + * + * @return ::NC_NOERR No error. + * @return ::NC_EINVAL More than one value for _FillValue or trying to + * set 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 Fill values must be written while the file + * is still in initial define mode. + * + * @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 +59,56 @@ 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). + * + * 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. + * + * @return ::NC_NOERR No error. + * @return ::NC_EINVAL More than one value for _FillValue or trying to set 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 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 #include ... int status; @@ -132,10 +134,8 @@ netCDF dataset named foo.nc: ... status = nc_enddef(ncid); if (status != NC_NOERR) handle_error(status); -\endcode +@endcode */ - - int nc_put_att_text(int ncid, int varid, const char *name, size_t len, const char *value) { @@ -145,60 +145,60 @@ int nc_put_att_text(int ncid, int varid, const char *name, return ncp->dispatch->put_att(ncid, varid, name, NC_CHAR, len, (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. + * + * 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. + * + * @return ::NC_NOERR No error. + * @return ::NC_EINVAL More than one value for _FillValue or trying to + * set 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 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 #include ... int status; @@ -224,9 +224,9 @@ netCDF dataset named foo.nc: ... status = nc_enddef(ncid); if (status != NC_NOERR) handle_error(status); -\endcode +@endcode */ -/*! \{*/ +/** \{*/ int nc_put_att(int ncid, int varid, const char *name, nc_type xtype, size_t len, const void *value) From ed8ef608552b89fdb95ef953b3612d2b95c75095 Mon Sep 17 00:00:00 2001 From: edwardhartnett Date: Thu, 7 Nov 2019 09:46:23 -0700 Subject: [PATCH 03/11] cleanup and minor fixes for attribute inq functions --- libdispatch/dattinq.c | 446 +++++++++++++++++++++--------------------- libdispatch/dattput.c | 3 + 2 files changed, 225 insertions(+), 224 deletions(-) diff --git a/libdispatch/dattinq.c b/libdispatch/dattinq.c index 025d5c8b75..2d878a5ca3 100644 --- a/libdispatch/dattinq.c +++ b/libdispatch/dattinq.c @@ -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... */ - /** -\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(). + * @name Learning about Attributes + * + * Functions to learn about the attributes in a file. */ +/** \{ */ /* All these functions are part of this named group... */ -\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 ... 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 ... 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 ... #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 ... 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 ... 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 ... 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 - -\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_attlen(int ncid, int varid, const char *name, size_t *lenp) diff --git a/libdispatch/dattput.c b/libdispatch/dattput.c index b6bef82d63..100d282208 100644 --- a/libdispatch/dattput.c +++ b/libdispatch/dattput.c @@ -135,6 +135,8 @@ nc_put_att_string(int ncid, int varid, const char *name, status = nc_enddef(ncid); if (status != NC_NOERR) handle_error(status); @endcode + +* @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) @@ -225,6 +227,7 @@ int nc_put_att_text(int ncid, int varid, const char *name, status = nc_enddef(ncid); if (status != NC_NOERR) handle_error(status); @endcode +* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner */ /** \{*/ int From f46679c8cc004f0972059717317ad7167473e378 Mon Sep 17 00:00:00 2001 From: edwardhartnett Date: Thu, 7 Nov 2019 09:53:43 -0700 Subject: [PATCH 04/11] cleanup and minor fixes for attribute rename/delete functions --- libdispatch/datt.c | 271 +++++++++++++++++++++++---------------------- 1 file changed, 137 insertions(+), 134 deletions(-) diff --git a/libdispatch/datt.c b/libdispatch/datt.c index d9896ed5e2..b4052fbc53 100644 --- a/libdispatch/datt.c +++ b/libdispatch/datt.c @@ -1,92 +1,94 @@ -/** \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. + * + * 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. */ -/*! \{*/ /* All these functions are part of the above defgroup... */ - - -/** \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. - -

Example

- -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 +/** \{*/ + +/** + * @name Deleting and Renaming Attributes + * + * Functions to delete or rename an attribute. */ +/** \{ */ + +/** + * 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. + * + *

Example

+ * + * 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 ... int status; @@ -101,21 +103,21 @@ dataset named foo.nc: ... status = nc_rename_att(ncid, rh_id, "units", "Units"); 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_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 +@endcode + + * @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 +129,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. - -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. - -

Example

- -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 +/** + * Delete an attribute. + * + * 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. + * + *

Example

+ * + * 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 #include ... int status; @@ -166,18 +169,18 @@ 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 - -\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 +@endcode + + * @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 +192,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 of defgroup. */ +/*! \} */ From 209da6563c35ed99f0ef1b82d7e6d15d301599b2 Mon Sep 17 00:00:00 2001 From: edwardhartnett Date: Thu, 7 Nov 2019 11:32:57 -0700 Subject: [PATCH 05/11] greater distinction between netCDF-4 and classic formats in attribute documentation --- libdispatch/datt.c | 52 ++++++++++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/libdispatch/datt.c b/libdispatch/datt.c index b4052fbc53..3c79e7d6e5 100644 --- a/libdispatch/datt.c +++ b/libdispatch/datt.c @@ -18,10 +18,11 @@ * 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 + * 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. + * mode. For netCDF-4/HDF5 netCDF files, attributes may be defined at + * any time. * * 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. @@ -33,21 +34,25 @@ * * 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. + * mode. 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 values may be + * changed at any time. * * 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. + * netCDF dataset. In netCDF-4/HDF5 files, global attributes are + * associated with a hierarchical group. * * 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. + * - 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. @@ -66,20 +71,19 @@ /** * 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. + * 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. * *

Example

@@ -88,7 +92,7 @@ * attribute units to Units for a variable rh in an existing netCDF * dataset named foo.nc: * -@code + @code #include ... int status; @@ -103,9 +107,9 @@ ... status = nc_rename_att(ncid, rh_id, "units", "Units"); if (status != NC_NOERR) handle_error(status); -@endcode + @endcode - * @return NC_NOERR No error. + * @return ::NC_NOERR No error. * @return ::NC_EBADID Bad ncid. * @return ::NC_ENOTVAR Bad varid. * @return ::NC_EBADNAME Bad name. @@ -117,6 +121,7 @@ * @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 @@ -133,15 +138,15 @@ nc_rename_att(int ncid, int varid, const char *name, const char *newname) * Delete an attribute. * * The function nc_del_att() deletes a netCDF attribute from an open - * netCDF dataset. The netCDF dataset must be in define mode. + * 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. * *

Example

@@ -180,6 +185,7 @@ nc_rename_att(int ncid, int varid, const char *name, const char *newname) * @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 From 3ecef5e7f08a1a742a27a910535d611e5f2d7b26 Mon Sep 17 00:00:00 2001 From: edwardhartnett Date: Thu, 7 Nov 2019 11:47:27 -0700 Subject: [PATCH 06/11] fixing documentation for attribute get functions --- libdispatch/datt.c | 4 +- libdispatch/dattget.c | 122 ++++++++++++++++++++---------------------- 2 files changed, 60 insertions(+), 66 deletions(-) diff --git a/libdispatch/datt.c b/libdispatch/datt.c index 3c79e7d6e5..ec4ececce0 100644 --- a/libdispatch/datt.c +++ b/libdispatch/datt.c @@ -37,8 +37,8 @@ * mode. 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 values may be - * changed at any time. + * originally defined. In netCDF-4/HDF5 files, attribute name, length, + * and value may be changed at any time. * * It is also possible to have attributes that are not associated with * any variable. These are called global attributes and are identified diff --git a/libdispatch/dattget.c b/libdispatch/dattget.c index 6c0c06279e..318e7561d3 100644 --- a/libdispatch/dattget.c +++ b/libdispatch/dattget.c @@ -20,20 +20,17 @@ * @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. + * 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. * * @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 @@ -44,21 +41,11 @@ * @note See documentation for nc_get_att_string() regarding a special * case where memory must be explicitly released. * - * @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. + *

Example

+ * + * 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. * -

Example

- -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" @@ -81,7 +68,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) @@ -106,51 +103,39 @@ nc_get_att(int ncid, int varid, const char *name, void *value) * @ingroup attributes * Get an attribute. * - * This function gets an attribute from the netCDF file. The - * nc_get_att() function works with any type of data, including user - * defined types. + * This function gets an attribute of an atomic type from the netCDF + * file. * * @note The netCDF library reads all attributes into memory when the - * file is opened with nc_open(). Getting an attribute copies the + * file is opened with nc_open(), or when the first attribute for that + * file or group (for global attributes) or variable is accessed by + * the user (after versuon 4.7.2). Getting an attribute copies the * value from the in-memory store, and does not incur any file I/O - * penalties. + * penalties after the attributes have been read. * * @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. * - * @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. - -

Example

- -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. + *

Example

+ * + * 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 #include @@ -186,7 +171,16 @@ the length of the attributes. ... @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 */ /** \{ */ @@ -352,16 +346,6 @@ nc_get_att_ulonglong(int ncid, int varid, const char *name, unsigned long long * * don't know how much space to reserve, call nc_inq_attlen() first to * find out the length of the attribute. * - * @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. - * * @section nc_get_att_string_example Example * @code{.c} @@ -409,8 +393,18 @@ int main(int argc, char ** argv) { } @endcode -* @author 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 Ed Hartnett, Dennis Heimbigner + */ int nc_get_att_string(int ncid, int varid, const char *name, char **value) { From 42df9b09e57fb7c2332dfed9a28fb28d5286c6ad Mon Sep 17 00:00:00 2001 From: edwardhartnett Date: Thu, 7 Nov 2019 11:58:41 -0700 Subject: [PATCH 07/11] fixing documentation for attribute put functions --- libdispatch/dattput.c | 45 ++++++++++++------------------------------- 1 file changed, 12 insertions(+), 33 deletions(-) diff --git a/libdispatch/dattput.c b/libdispatch/dattput.c index 100d282208..36d094394b 100644 --- a/libdispatch/dattput.c +++ b/libdispatch/dattput.c @@ -26,15 +26,11 @@ * @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. * * @return ::NC_NOERR No error. @@ -68,39 +64,30 @@ nc_put_att_string(int ncid, int varid, const char *name, * 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. + * Type conversion is not available with text 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 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. + * @param len The length of the text array. @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 value Pointer to the start of the character array. * * @return ::NC_NOERR No error. - * @return ::NC_EINVAL More than one value for _FillValue or trying to set global _FillValue. + * @return ::NC_EINVAL More than one value for _FillValue or trying to + * set 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 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 @@ -152,36 +139,28 @@ int nc_put_att_text(int ncid, int varid, const char *name, * @ingroup attributes * Write an attribute. * - * The function nc_put_att_ type adds or changes a variable attribute + * The function nc_put_att_ 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 + * 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. * * @return ::NC_NOERR No error. From 7919e2c052a61a2c5cac3a52ea07567337908c75 Mon Sep 17 00:00:00 2001 From: edwardhartnett Date: Thu, 7 Nov 2019 12:19:18 -0700 Subject: [PATCH 08/11] fixing documentation for attribute put functions --- libdispatch/datt.c | 7 +++ libdispatch/dattget.c | 122 ++++++++++++++++++++++++++++++------------ libdispatch/dattput.c | 12 +++-- 3 files changed, 103 insertions(+), 38 deletions(-) diff --git a/libdispatch/datt.c b/libdispatch/datt.c index ec4ececce0..dd80d34905 100644 --- a/libdispatch/datt.c +++ b/libdispatch/datt.c @@ -58,6 +58,13 @@ * - Get name of attribute from its number. * - Rename an attribute. * - Delete an attribute. + * + * @note The netCDF library reads all attributes into memory when the + * file is opened with nc_open(), or when the first attribute for that + * file or group (for global attributes) or variable is accessed by + * the user (after versuon 4.7.2). Getting an attribute copies the + * value from the in-memory store, and does not incur any file I/O + * penalties after the attributes have been read. */ /** \{*/ diff --git a/libdispatch/dattget.c b/libdispatch/dattget.c index 318e7561d3..7e275f2dd8 100644 --- a/libdispatch/dattget.c +++ b/libdispatch/dattget.c @@ -101,17 +101,10 @@ nc_get_att(int ncid, int varid, const char *name, void *value) /** * @ingroup attributes - * Get an attribute. + * Get a text attribute. * - * This function gets an attribute of an atomic type from the netCDF - * file. - * - * @note The netCDF library reads all attributes into memory when the - * file is opened with nc_open(), or when the first attribute for that - * file or group (for global attributes) or variable is accessed by - * the user (after versuon 4.7.2). Getting an attribute copies the - * value from the in-memory store, and does not incur any file I/O - * penalties after the attributes have been read. + * This function gets a text attribute from the netCDF + * file. Type conversions are not permitted. * * @param ncid NetCDF or group ID, from a previous call to nc_open(), * nc_create(), nc_def_grp(), or associated inquiry functions such as @@ -119,23 +112,27 @@ nc_get_att(int ncid, int varid, const char *name, void *value) * @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 + + * @param value Pointer to location for returned char array. If you * don't know how much space to reserve, call nc_inq_attlen() first to - * find out the length of the attribute. + * find out the length of the attribute. @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. * *

Example

* - * 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 + * 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, 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. + * 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). @code #include @@ -143,10 +140,8 @@ nc_get_att(int ncid, int varid, const char *name, void *value) 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); @@ -155,22 +150,16 @@ nc_get_att(int ncid, int varid, const char *name, void *value) 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 - + * * @return ::NC_NOERR for success. * @return ::NC_EBADID Bad ncid. * @return ::NC_ENOTVAR Bad varid. @@ -182,8 +171,6 @@ nc_get_att(int ncid, int varid, const char *name, void *value) * @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) { @@ -194,6 +181,75 @@ 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 atomic type. + * + * 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 to location for returned attribute + * value(s). 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. + * + *

Example

+ * + * 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 + ... + 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 +*/ +/** \{ */ + int nc_get_att_schar(int ncid, int varid, const char *name, signed char *value) { diff --git a/libdispatch/dattput.c b/libdispatch/dattput.c index 36d094394b..2d8f34203e 100644 --- a/libdispatch/dattput.c +++ b/libdispatch/dattput.c @@ -66,17 +66,19 @@ nc_put_att_string(int ncid, int varid, const char *name, * * Type conversion is not available with text 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 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 + * @param name Attribute @ref object_name. @ref attribute_conventions * may apply. - * @param len The length of the text array. @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 len The length of the text array. * @param value Pointer to the start of the character array. * * @return ::NC_NOERR No error. From 8b2630913ac423c91369ac28a56e1b616ba0b510 Mon Sep 17 00:00:00 2001 From: edwardhartnett Date: Fri, 8 Nov 2019 04:45:45 -0700 Subject: [PATCH 09/11] adding doxygen docs for every att function --- libdispatch/datt.c | 6 - libdispatch/dattget.c | 353 +++++++++++++++++++++++++++++++++------- libdispatch/dattput.c | 367 ++++++++++++++++++++++++++++++++++-------- 3 files changed, 598 insertions(+), 128 deletions(-) diff --git a/libdispatch/datt.c b/libdispatch/datt.c index dd80d34905..a0709b916e 100644 --- a/libdispatch/datt.c +++ b/libdispatch/datt.c @@ -59,12 +59,6 @@ * - Rename an attribute. * - Delete an attribute. * - * @note The netCDF library reads all attributes into memory when the - * file is opened with nc_open(), or when the first attribute for that - * file or group (for global attributes) or variable is accessed by - * the user (after versuon 4.7.2). Getting an attribute copies the - * value from the in-memory store, and does not incur any file I/O - * penalties after the attributes have been read. */ /** \{*/ diff --git a/libdispatch/dattget.c b/libdispatch/dattget.c index 7e275f2dd8..41e6b91e44 100644 --- a/libdispatch/dattget.c +++ b/libdispatch/dattget.c @@ -13,9 +13,20 @@ * @name Getting Attributes * * Functions to get the values of attributes. + * + * The netCDF library reads all attributes into memory when the + * file is opened with nc_open(), or when the first attribute for that + * file or group (for global attributes) or variable is accessed by + * the user (after versuon 4.7.2). Getting an attribute copies the + * value from the in-memory store, and does not incur any file I/O + * penalties after the attributes have been 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. @@ -25,18 +36,11 @@ * the 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 ncid NetCDF file or group ID. + * @param varid Variable ID, 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. + * @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. @@ -97,7 +101,6 @@ 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 @@ -106,20 +109,17 @@ nc_get_att(int ncid, int varid, const char *name, void *value) * This function gets a text attribute from the netCDF * file. Type conversions are not permitted. * - * @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 ncid NetCDF file or group ID. + * @param varid Variable ID, or ::NC_GLOBAL for a global attribute. * @param name Attribute name. - - * @param value Pointer to location for returned char array. If you - * don't know how much space to reserve, call nc_inq_attlen() first to - * find out the length of the attribute. @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. + * @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. * *

Example

* @@ -181,6 +181,37 @@ 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. + * + * @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) +{ + NC* ncp; + int stat = NC_check_id(ncid, &ncp); + if(stat != NC_NOERR) return stat; + TRACE(nc_get_att_schar); + return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_BYTE); +} + /** * @ingroup attributes * Get an attribute of an atomic type. @@ -194,11 +225,8 @@ nc_get_att_text(int ncid, int varid, const char *name, char *value) * @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 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. + * @param value Pointer that will get array of attribute value(s). Use + * nc_inq_attlen() to learn length. * *

Example

* @@ -248,18 +276,28 @@ nc_get_att_text(int ncid, int varid, const char *name, char *value) * @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) -{ - NC* ncp; - int stat = NC_check_id(ncid, &ncp); - if(stat != NC_NOERR) return stat; - TRACE(nc_get_att_schar); - return ncp->dispatch->get_att(ncid, varid, name, (void *)value, NC_BYTE); -} +/** + * @ingroup attributes + * Get an attribute of an signed char type. + * + * @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) { @@ -270,6 +308,27 @@ 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. + * + * @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) { @@ -280,6 +339,27 @@ 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. + * + * @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) { @@ -290,6 +370,27 @@ 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. + * + * @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) { @@ -300,6 +401,27 @@ 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. + * + * @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) { @@ -310,6 +432,27 @@ 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. + * + * @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) { @@ -320,6 +463,27 @@ 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. + * + * @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_ubyte(int ncid, int varid, const char *name, unsigned char *value) { @@ -330,6 +494,27 @@ 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. + * + * @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_ushort(int ncid, int varid, const char *name, unsigned short *value) { @@ -340,6 +525,27 @@ 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. + * + * @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_uint(int ncid, int varid, const char *name, unsigned int *value) { @@ -350,6 +556,27 @@ 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. + * + * @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_longlong(int ncid, int varid, const char *name, long long *value) { @@ -360,6 +587,27 @@ 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. + * + * @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_ulonglong(int ncid, int varid, const char *name, unsigned long long *value) { @@ -369,11 +617,10 @@ 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. + * 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, @@ -387,20 +634,11 @@ nc_get_att_ulonglong(int ncid, int varid, const char *name, unsigned long long * * 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 ncid NetCDF file or group ID. + * @param varid Variable ID, 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. + * @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 * @@ -470,4 +708,3 @@ 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); } -/** \} */ diff --git a/libdispatch/dattput.c b/libdispatch/dattput.c index 2d8f34203e..91ade4459f 100644 --- a/libdispatch/dattput.c +++ b/libdispatch/dattput.c @@ -11,8 +11,25 @@ /** * @name Writing Attributes * - * Functions to write attributes. */ -/** \{ */ + * Functions to write attributes. + * + * 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. + * +*/ /** * @ingroup attributes @@ -23,24 +40,18 @@ * 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 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 More than one value for _FillValue or trying to - * set global _FillValue. + * @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 Fill values must be written while the file - * is still in initial define mode. + * @return ::NC_ELATEFILL Too late to set fill value. * * @author Ed Hartnett, Dennis Heimbigner */ @@ -71,25 +82,12 @@ nc_put_att_string(int ncid, int varid, const char *name, * written, then all C programs must add the NULL character after * reading a text 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 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 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. * - * @return ::NC_NOERR No error. - * @return ::NC_EINVAL More than one value for _FillValue or trying to - * set 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 Fill values must be written while the file - * is still in initial define mode. - * * @section nc_put_att_text_example Example * * Here is an example using nc_put_att_double() to add a variable @@ -125,7 +123,14 @@ nc_put_att_string(int ncid, int varid, const char *name, if (status != NC_NOERR) handle_error(status); @endcode -* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner + * @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) @@ -136,44 +141,19 @@ int nc_put_att_text(int ncid, int varid, const char *name, return ncp->dispatch->put_att(ncid, varid, name, NC_CHAR, len, (void *)value, NC_CHAR); } -/** \} */ + /** * @ingroup attributes - * Write an attribute. - * - * The function nc_put_att_ 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. + * Write an attribute of any type. * - * @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 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 More than one value for _FillValue or trying to - * set 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 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 @@ -208,9 +188,16 @@ int nc_put_att_text(int ncid, int varid, const char *name, status = nc_enddef(ncid); if (status != NC_NOERR) handle_error(status); @endcode -* @author Glenn Davis, Ed Hartnett, Dennis Heimbigner + + * @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) @@ -222,6 +209,27 @@ nc_put_att(int ncid, int varid, const char *name, nc_type xtype, value, xtype); } +/** + * @ingroup attributes + * Write an attribute of type signed char. + * + * @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) @@ -233,6 +241,27 @@ nc_put_att_schar(int ncid, int varid, const char *name, (void *)value, NC_BYTE); } +/** + * @ingroup attributes + * Write an attribute of type unsigned char. + * + * @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) @@ -244,6 +273,27 @@ nc_put_att_uchar(int ncid, int varid, const char *name, (void *)value, NC_UBYTE); } +/** + * @ingroup attributes + * Write an attribute of type short. + * + * @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) @@ -255,6 +305,27 @@ nc_put_att_short(int ncid, int varid, const char *name, (void *)value, NC_SHORT); } +/** + * @ingroup attributes + * Write an attribute of type int. + * + * @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) @@ -266,6 +337,27 @@ nc_put_att_int(int ncid, int varid, const char *name, (void *)value, NC_INT); } +/** + * @ingroup attributes + * Write an attribute of type long. + * + * @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) @@ -277,6 +369,27 @@ nc_put_att_long(int ncid, int varid, const char *name, (void *)value, longtype); } +/** + * @ingroup attributes + * Write an attribute of type float. + * + * @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) @@ -288,6 +401,27 @@ nc_put_att_float(int ncid, int varid, const char *name, (void *)value, NC_FLOAT); } +/** + * @ingroup attributes + * Write an attribute of type double. + * + * @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) @@ -299,6 +433,27 @@ nc_put_att_double(int ncid, int varid, const char *name, (void *)value, NC_DOUBLE); } +/** + * @ingroup attributes + * Write an attribute of type unsigned char. + * + * @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) @@ -310,6 +465,27 @@ nc_put_att_ubyte(int ncid, int varid, const char *name, (void *)value, NC_UBYTE); } +/** + * @ingroup attributes + * Write an attribute of type unsigned short. + * + * @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) @@ -321,6 +497,27 @@ nc_put_att_ushort(int ncid, int varid, const char *name, (void *)value, NC_USHORT); } +/** + * @ingroup attributes + * Write an attribute of type unsigned int. + * + * @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) @@ -332,6 +529,27 @@ nc_put_att_uint(int ncid, int varid, const char *name, (void *)value, NC_UINT); } +/** + * @ingroup attributes + * Write an attribute of type long long. + * + * @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, @@ -344,6 +562,27 @@ 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. + * + * @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, From 09fe16c8470f4ff7c1fd32065424ab0551c472d2 Mon Sep 17 00:00:00 2001 From: edwardhartnett Date: Fri, 8 Nov 2019 04:47:57 -0700 Subject: [PATCH 10/11] cleanup --- libdispatch/datt.c | 8 ++++---- libdispatch/dattget.c | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/libdispatch/datt.c b/libdispatch/datt.c index a0709b916e..6aa7693c8d 100644 --- a/libdispatch/datt.c +++ b/libdispatch/datt.c @@ -61,13 +61,13 @@ * */ -/** \{*/ +/** @{*/ /** * @name Deleting and Renaming Attributes * * Functions to delete or rename an attribute. */ -/** \{ */ +/** @{ */ /** * Rename an attribute. @@ -199,6 +199,6 @@ nc_del_att(int ncid, int varid, const char *name) stat = ncp->dispatch->del_att(ncid, varid, name); return stat; } -/*! \} */ +/*! @} */ -/*! \} */ +/*! @} */ diff --git a/libdispatch/dattget.c b/libdispatch/dattget.c index 41e6b91e44..f0935e3568 100644 --- a/libdispatch/dattget.c +++ b/libdispatch/dattget.c @@ -482,7 +482,7 @@ nc_get_att_double(int ncid, int varid, const char *name, double *value) * @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 + * @author Ed Hartnett, Dennis Heimbigner */ int nc_get_att_ubyte(int ncid, int varid, const char *name, unsigned char *value) @@ -513,7 +513,7 @@ nc_get_att_ubyte(int ncid, int varid, const char *name, unsigned char *value) * @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 + * @author Ed Hartnett, Dennis Heimbigner */ int nc_get_att_ushort(int ncid, int varid, const char *name, unsigned short *value) @@ -544,7 +544,7 @@ nc_get_att_ushort(int ncid, int varid, const char *name, unsigned short *value) * @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 + * @author Ed Hartnett, Dennis Heimbigner */ int nc_get_att_uint(int ncid, int varid, const char *name, unsigned int *value) @@ -575,7 +575,7 @@ nc_get_att_uint(int ncid, int varid, const char *name, unsigned int *value) * @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 + * @author Ed Hartnett, Dennis Heimbigner */ int nc_get_att_longlong(int ncid, int varid, const char *name, long long *value) @@ -606,7 +606,7 @@ nc_get_att_longlong(int ncid, int varid, const char *name, long long *value) * @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 + * @author Ed Hartnett, Dennis Heimbigner */ int nc_get_att_ulonglong(int ncid, int varid, const char *name, unsigned long long *value) From c76dae1c5d50d113b1e8d4affcb61f251aa2720d Mon Sep 17 00:00:00 2001 From: edwardhartnett Date: Fri, 8 Nov 2019 05:19:51 -0700 Subject: [PATCH 11/11] added anchors for reading_attributes and writing_attributes, and refs to them, also changed order of files in Doxygen.in --- docs/Doxyfile.in | 6 ++--- libdispatch/datt.c | 40 +++++++++----------------------- libdispatch/dattget.c | 53 +++++++++++++++++++++++++++++++++++++------ libdispatch/dattput.c | 46 +++++++++++++++++++++++++++++++++++++ 4 files changed, 106 insertions(+), 39 deletions(-) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 12bca3c664..ef4980f2b3 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -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 \ diff --git a/libdispatch/datt.c b/libdispatch/datt.c index 6aa7693c8d..0da48756fd 100644 --- a/libdispatch/datt.c +++ b/libdispatch/datt.c @@ -18,39 +18,22 @@ * properties as units, special values, maximum and minimum valid * values, scaling factors, and offsets. * - * 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. - * - * 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. 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. - * * 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 + * 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. + * 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. @@ -58,7 +41,6 @@ * - Get name of attribute from its number. * - Rename an attribute. * - Delete an attribute. - * */ /** @{*/ @@ -67,7 +49,7 @@ * @name Deleting and Renaming Attributes * * Functions to delete or rename an attribute. */ -/** @{ */ +/**@{*/ /* Start doxygen member group. */ /** * Rename an attribute. @@ -199,6 +181,6 @@ nc_del_att(int ncid, int varid, const char *name) stat = ncp->dispatch->del_att(ncid, varid, name); return stat; } -/*! @} */ +/**@}*/ /* End doxygen member group. */ -/*! @} */ +/**@}*/ diff --git a/libdispatch/dattget.c b/libdispatch/dattget.c index f0935e3568..1f9510ab01 100644 --- a/libdispatch/dattget.c +++ b/libdispatch/dattget.c @@ -10,22 +10,28 @@ #include "ncdispatch.h" /** + * @anchor getting_attributes * @name Getting Attributes * * Functions to get the values of attributes. * - * The netCDF library reads all attributes into memory when the - * file is opened with nc_open(), or when the first attribute for that - * file or group (for global attributes) or variable is accessed by - * the user (after versuon 4.7.2). Getting an attribute copies the - * value from the in-memory store, and does not incur any file I/O - * penalties after the attributes have been read. + * 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. */ +/**@{*/ /* Start doxygen member group. */ /** * @ingroup attributes @@ -36,6 +42,8 @@ * 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. @@ -109,12 +117,14 @@ nc_get_att(int ncid, int varid, const char *name, void *value) * 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 @@ -185,6 +195,8 @@ nc_get_att_text(int ncid, int varid, const char *name, char *value) * @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. @@ -216,6 +228,8 @@ nc_get_att_schar(int ncid, int varid, const char *name, signed char *value) * @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. * @@ -281,6 +295,8 @@ nc_get_att_schar(int ncid, int varid, const char *name, signed char *value) * @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. @@ -312,6 +328,8 @@ nc_get_att_uchar(int ncid, int varid, const char *name, unsigned char *value) * @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. @@ -343,6 +361,8 @@ nc_get_att_short(int ncid, int varid, const char *name, short *value) * @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. @@ -374,6 +394,8 @@ nc_get_att_int(int ncid, int varid, const char *name, int *value) * @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. @@ -405,6 +427,8 @@ nc_get_att_long(int ncid, int varid, const char *name, long *value) * @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. @@ -436,6 +460,8 @@ nc_get_att_float(int ncid, int varid, const char *name, float *value) * @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. @@ -467,6 +493,8 @@ nc_get_att_double(int ncid, int varid, const char *name, double *value) * @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. @@ -498,6 +526,8 @@ nc_get_att_ubyte(int ncid, int varid, const char *name, unsigned char *value) * @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. @@ -529,6 +559,8 @@ nc_get_att_ushort(int ncid, int varid, const char *name, unsigned short *value) * @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. @@ -560,6 +592,8 @@ nc_get_att_uint(int ncid, int varid, const char *name, unsigned int *value) * @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. @@ -591,6 +625,8 @@ nc_get_att_longlong(int ncid, int varid, const char *name, long long *value) * @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. @@ -627,6 +663,8 @@ nc_get_att_ulonglong(int ncid, int varid, const char *name, unsigned long long * * 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 @@ -708,3 +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. */ diff --git a/libdispatch/dattput.c b/libdispatch/dattput.c index 91ade4459f..80fd01dff7 100644 --- a/libdispatch/dattput.c +++ b/libdispatch/dattput.c @@ -9,10 +9,23 @@ #include "ncdispatch.h" /** + * @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. @@ -31,6 +44,7 @@ * */ +/**@{*/ /* Start doxygen member group. */ /** * @ingroup attributes * Write a string attribute. @@ -40,6 +54,8 @@ * 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. @@ -77,6 +93,8 @@ nc_put_att_string(int ncid, int varid, const char *name, * * 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 @@ -146,6 +164,8 @@ int nc_put_att_text(int ncid, int varid, const char *name, * @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. @@ -213,6 +233,8 @@ nc_put_att(int ncid, int varid, const char *name, nc_type 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. @@ -245,6 +267,8 @@ nc_put_att_schar(int ncid, int varid, const char *name, * @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. @@ -277,6 +301,8 @@ nc_put_att_uchar(int ncid, int varid, const char *name, * @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. @@ -309,6 +335,8 @@ nc_put_att_short(int ncid, int varid, const char *name, * @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. @@ -341,6 +369,8 @@ nc_put_att_int(int ncid, int varid, const char *name, * @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. @@ -373,6 +403,8 @@ nc_put_att_long(int ncid, int varid, const char *name, * @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. @@ -405,6 +437,8 @@ nc_put_att_float(int ncid, int varid, const char *name, * @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. @@ -437,6 +471,8 @@ nc_put_att_double(int ncid, int varid, const char *name, * @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. @@ -469,6 +505,8 @@ nc_put_att_ubyte(int ncid, int varid, const char *name, * @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. @@ -501,6 +539,8 @@ nc_put_att_ushort(int ncid, int varid, const char *name, * @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. @@ -533,6 +573,8 @@ nc_put_att_uint(int ncid, int varid, const char *name, * @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. @@ -566,6 +608,8 @@ nc_put_att_longlong(int ncid, int varid, const char *name, * @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. @@ -594,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. */