From 1b0ca07a3c6aba4f85d00a11dda490d3f3be25f7 Mon Sep 17 00:00:00 2001 From: Edward Hartnett Date: Tue, 3 May 2022 08:56:02 -0600 Subject: [PATCH 1/6] added nc4cache.c to list of doxygen input files --- docs/Doxyfile.in | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index fcb2b33680..8d7f950022 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -789,6 +789,7 @@ INPUT = \ @abs_top_srcdir@/libsrc4/ncfunc.c \ @abs_top_srcdir@/libsrc4/nc4dim.c \ @abs_top_srcdir@/libsrc4/nc4attr.c \ + @abs_top_srcdir@/libsrc4/nc4cache.c \ @abs_top_srcdir@/libhdf5/nc4info.c \ @abs_top_srcdir@/libsrc4/nc4dispatch.c \ @abs_top_srcdir@/libnczarr/zarr.c \ From 14e80b4673454719b2d709e16b3f63afb7accf60 Mon Sep 17 00:00:00 2001 From: Edward Hartnett Date: Tue, 3 May 2022 09:41:45 -0600 Subject: [PATCH 2/6] fixing doxygen warnings --- docs/notes.md | 41 +++++++++++++++++++++++++++++++++++++++++ include/netcdf.h | 6 ++++++ libdispatch/dvar.c | 8 +++++--- 3 files changed, 52 insertions(+), 3 deletions(-) diff --git a/docs/notes.md b/docs/notes.md index 133670b13b..73ae15703f 100644 --- a/docs/notes.md +++ b/docs/notes.md @@ -107,3 +107,44 @@ that is returned by nc_open() and nc_create().) For netCDF-4/HDF5 files, netCDF IDs can come not just from nc_open() and nc_create(), but also from nc_def_grp(), nc_inq_grps(), nc_inq_ncid(), nc_inq_grp_parent(), and nc_inq_grp_full_ncid(). + +# NetCDF Names {#object_name} + +## Permitted Characters in NetCDF Names + +The names of dimensions, variables and attributes (and, in netCDF-4 +files, groups, user-defined types, compound member names, and +enumeration symbols) consist of arbitrary sequences of alphanumeric +characters, underscore '_', period '.', plus '+', hyphen '-', or at +sign '@', but beginning with an alphanumeric character or +underscore. However names commencing with underscore are reserved for +system use. + +Beginning with versions 3.6.3 and 4.0, names may also include UTF-8 +encoded Unicode characters as well as other special characters, except +for the character '/', which may not appear in a name. + +Names that have trailing space characters are also not permitted. + +Case is significant in netCDF names. + +## Name Length + +A zero-length name is not allowed. + +Names longer than ::NC_MAX_NAME will not be accepted any netCDF define +function. An error of ::NC_EMAXNAME will be returned. + +All netCDF inquiry functions will return names of maximum size +::NC_MAX_NAME for netCDF files. Since this does not include the +terminating NULL, space should be reserved for ::NC_MAX_NAME + 1 +characters. + +## NetCDF Conventions + +Some widely used conventions restrict names to only alphanumeric +characters or underscores. + +Note that, when using the DAP2 protocol to access netCDF data, there +are reserved keywords, the use of which may result in undefined +behavior. See DAP2 Reserved Keywords for more information. diff --git a/include/netcdf.h b/include/netcdf.h index 47e1394d7c..35ef6f8cc2 100644 --- a/include/netcdf.h +++ b/include/netcdf.h @@ -334,21 +334,27 @@ there. */ #define NC_QUANTIZE_GRANULARBR 2 /**< Use Granular BitRound quantization. */ #define NC_QUANTIZE_BITROUND 3 /**< Use BitRound quantization. */ +/**@{*/ /** When quantization is used for a variable, an attribute of the * appropriate name is added. */ #define NC_QUANTIZE_BITGROOM_ATT_NAME "_QuantizeBitGroomNumberOfSignificantDigits" #define NC_QUANTIZE_GRANULARBR_ATT_NAME "_QuantizeGranularBitRoundNumberOfSignificantDigits" #define NC_QUANTIZE_BITROUND_ATT_NAME "_QuantizeBitRoundNumberOfSignificantBits" +/**@}*/ +/**@{*/ /** For quantization, the allowed value of number of significant * decimal and binary digits, respectively, for float. */ #define NC_QUANTIZE_MAX_FLOAT_NSD (7) #define NC_QUANTIZE_MAX_FLOAT_NSB (23) +/**@}*/ +/**@{*/ /** For quantization, the allowed value of number of significant * decimal and binary digits, respectively, for double. */ #define NC_QUANTIZE_MAX_DOUBLE_NSD (15) #define NC_QUANTIZE_MAX_DOUBLE_NSB (52) +/**@}*/ /** The netcdf version 3 functions all return integer error status. * These are the possible values, in addition to certain values from diff --git a/libdispatch/dvar.c b/libdispatch/dvar.c index 8ed6c46bbf..fe029f44c6 100644 --- a/libdispatch/dvar.c +++ b/libdispatch/dvar.c @@ -148,7 +148,9 @@ nc_create(), nc_def_grp(), or associated inquiry functions such as nc_inq_ncid(). @param name Variable @ref object_name. - @param xtype @ref data_type of the variable. + @param xtype (Data + type)[https://docs.unidata.ucar.edu/nug/current/md_types.html#data_type] + of the variable. @param ndims Number of dimensions for the variable. For example, 2 specifies a matrix, 1 specifies a vector, and 0 means the variable is a scalar with no dimensions. Must not be negative or greater than the @@ -488,7 +490,7 @@ nc_def_var_deflate(int ncid, int varid, int shuffle, int deflate, int deflate_le types return an error (NC_EINVAL). Variables that use quantize will have added an attribute with name - ::NC_QUANTIZE_[ALGORITHM_NAME]_ATT_NAME, which will contain the + NC_QUANTIZE_[ALGORITHM_NAME]_ATT_NAME, which will contain the number of significant digits. Users should not delete or change this attribute. This is the only record that quantize has been applied to the data. @@ -640,7 +642,7 @@ nc_def_var_fletcher32(int ncid, int varid, int fletcher32) @note Scalar variables may have a storage of NC_CONTIGUOUS or NC_COMPACT. Attempts to set chunking on a scalare variable will - cause ::NC_EINVEL to be returned. Only non-scalar variables can + cause ::NC_EINVAL to be returned. Only non-scalar variables can have chunking. @param ncid NetCDF ID, from a previous call to nc_open() or From 6849f448961aea7fa3fd8fa70a760868e8a687fb Mon Sep 17 00:00:00 2001 From: Edward Hartnett Date: Tue, 3 May 2022 12:54:14 -0600 Subject: [PATCH 3/6] more doxygen warning fixes --- docs/Doxyfile.in | 2 +- docs/FAQ.md | 6 +++--- docs/nczarr.md | 2 +- docs/tutorial.dox | 28 ++++++++++++++++------------ libdispatch/dattinq.c | 9 +++++---- 5 files changed, 26 insertions(+), 21 deletions(-) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 8d7f950022..0f5d3324f3 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -2037,7 +2037,7 @@ SKIP_FUNCTION_MACROS = YES # TAGFILES = html/guide.tag=./html_guide "html/tutorial.tag = ./html_tutorial" #TAGFILES = ../../NUG/html/nug.tag=../../../NUG/html -TAGFILES = ../../NUG/html/nug.tag=https://docs.unidata.ucar.edu/nug +#TAGFILES = ../../NUG/html/nug.tag=https://docs.unidata.ucar.edu/nug # When a file name is specified after GENERATE_TAGFILE, doxygen will create a # tag file that is based on the input files it reads. See section "Linking to diff --git a/docs/FAQ.md b/docs/FAQ.md index 380dfda7e0..ba4a99aeef 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -67,7 +67,7 @@ that is part of the netCDF software distribution. It is a command line tool that provides a text representation of a netCDF file's data, just its metadata, or just the data for specified variables, depending on what arguments you use. For more information, -see the \ref ncdump_guide documentation. +see the [ncdump User's Guide](https://docs.unidata.ucar.edu/nug/current/netcdf_utilities_guide.html#ncdump_guide) documentation. Another good tool for conversion of netCDF data to text is the ["ncks" program](http://nco.sourceforge.net/nco.html#ncks-netCDF-Kitchen-Sink) that's one of the utility programs in the [NCO (NetCDF Operators)](software.html#NCO) package. Similar capabilities are available using programs from the [CDO (Climate Data Operators)](software.html#CDO) software, commands from [NCL (NCAR Command Language)](software.html#NCL), or various other packages such as [ANAX](http://science.arm.gov/~cflynn/ARM_Tested_Tools/), cdf2asc, and NOESYS, all "third party" netCDF utilities developed and supported by other organizations. You can find more information about these third-party packages on the [Software for Manipulating or Displaying NetCDF Data](software.html) page. @@ -322,7 +322,7 @@ We test releases on the following operating systems with various compilers: - Solaris - Windows (some versions, see below) -The [NetCDF Installation and Porting Guide](@ref getting_and_building_netcdf) explains how to build netCDF from source on various platforms. Often, it's as easy as running +The [NetCDF Installation and Porting Guide](https://docs.unidata.ucar.edu/nug/current/getting_and_building_netcdf.html) explains how to build netCDF from source on various platforms. Often, it's as easy as running ~~~~ {.boldcode} ./configure @@ -483,7 +483,7 @@ How do I build and install netCDF for a specific development environment? {#How- You have to build and install the netCDF C library first, before you build and install other language libraries that depend on it, such as Fortran, C++, or Python netCDF libraries. The netCDF Java library is mostly independent of the netCDF C library, unless you need to write netCDF-4 files from Java, in which case you will also need an installed netCDF C library. For more details, see -[NetCDF Installation and Porting Guide](@ref getting_and_building_netcdf). +[NetCDF Installation and Porting Guide](https://docs.unidata.ucar.edu/nug/current/getting_and_building_netcdf.html). ---------- diff --git a/docs/nczarr.md b/docs/nczarr.md index af10387c60..19546d55ff 100644 --- a/docs/nczarr.md +++ b/docs/nczarr.md @@ -190,7 +190,7 @@ be a prefix of any other key. There several other concepts of note. 1. __Dataset__ - a dataset is the complete tree contained by the key defining the root of the dataset. -Technically, the root of the tree is the key /.zgroup, where .zgroup can be considered the _superblock_ of the dataset. +Technically, the root of the tree is the key \/.zgroup, where .zgroup can be considered the _superblock_ of the dataset. 2. __Object__ - equivalent of the S3 object; Each object has a unique key and "contains" data in the form of an arbitrary sequence of 8-bit bytes. diff --git a/docs/tutorial.dox b/docs/tutorial.dox index cc500cc8cc..40369442a4 100644 --- a/docs/tutorial.dox +++ b/docs/tutorial.dox @@ -68,7 +68,7 @@ The utility ncdump can be used to show the contents of netCDF files. By default, ncdump shows the CDL description of the file. This CDL description can be fed into ncgen to create the data file. -See also: \ref ncdump_guide +See also: [The ncdump User's Guide](https://docs.unidata.ucar.edu/nug/current/netcdf_utilities_guide.html#ncdump_guide) \subsection netcdf_utilities_ncgen ncgen @@ -76,15 +76,15 @@ The ncgen utility can take an ASCII input file, in CDL format, and generate a binary netCDF file. It is the opposite of ncdump. See also: -- \ref guide_ncgen -- \ref guide_ncgen3 +- [ncgen](https://docs.unidata.ucar.edu/nug/current/netcdf_utilities_guide.html#guide_ncgen) +- [ncgen3](https://docs.unidata.ucar.edu/nug/current/netcdf_utilities_guide.html#guide_ncgen3) \subsection netcdf_utilities_nccopy nccopy The nccopy utility can copy a netCDF file, changing binary format, chunk sizes, compression, and other storage settings. -See also: \ref guide_nccopy +See also: [nccopy](https://docs.unidata.ucar.edu/nug/current/netcdf_utilities_guide.html#guide_nccopy) \section external_netcdf_tools Tools for Manipulating NetCDF Files @@ -262,8 +262,9 @@ opaque types. These features may only be used when working with a netCDF-4/HDF5 -file. Files created in classic formats cannot support -groups or user-defined types (see \ref netcdf_format). +file. Files created in classic formats cannot support groups or +user-defined types (see [NetCDF File +Formats](https://docs.unidata.ucar.edu/nug/current/netcdf_introduction.html#netcdf_format)).

\image html nc4-model.png @@ -455,7 +456,8 @@ of netCDF-4. - \ref example_simple_xy_nc4 The examples are built and run with the “make check” command. (See -\ref building). +[Building +netCDF-C](https://docs.unidata.ucar.edu/nug/current/getting_and_building_netcdf.html#building)). The corresponding examples in each language create identical netCDF data files. For example, the C program sfc_pres_temp_wr.c produces the @@ -812,11 +814,13 @@ with nc_get_vara()/nc_put_vara(). \page parallel_io Parallel I/O with NetCDF-4 -NetCDF-4 provides parallel file access to both classic and netCDF-4/HDF5 files. -The parallel I/O to netCDF-4 files is achieved through the HDF5 library while -the parallel I/O to classic files is through PnetCDF. A few functions have been -added to the netCDF C API to handle parallel I/O. You must build netCDF-4 -properly to take advantage of parallel features (see \ref build_parallel). +NetCDF-4 provides parallel file access to both classic and +netCDF-4/HDF5 files. The parallel I/O to netCDF-4 files is achieved +through the HDF5 library while the parallel I/O to classic files is +through PnetCDF. A few functions have been added to the netCDF C API +to handle parallel I/O. You must build netCDF-4 properly to take +advantage of parallel features (see [Building with Parallel I/O +Support](https://docs.unidata.ucar.edu/nug/current/getting_and_building_netcdf.html#build_parallel)). The nc_open_par() and nc_create_par() functions are used to create/open a netCDF file with parallel access. diff --git a/libdispatch/dattinq.c b/libdispatch/dattinq.c index 2d878a5ca3..baba2840bc 100644 --- a/libdispatch/dattinq.c +++ b/libdispatch/dattinq.c @@ -30,8 +30,9 @@ Research/Unidata. See \ref copyright file for more info. */ * @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 xtypep Pointer to location for returned attribute [data + * type](https://docs.unidata.ucar.edu/nug/current/md_types.html#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 @@ -318,8 +319,8 @@ nc_inq_natts(int ncid, int *nattsp) * * @param name Attribute \ref object_name. * - * @param xtypep Pointer to location for returned attribute \ref - * data_type. + * @param xtypep Pointer to location for returned attribute [data + * type](https://docs.unidata.ucar.edu/nug/current/md_types.html#data_type). * * @section nc_inq_atttype_example Example * From 0d7cbf1911e5de874539d5196d60a6be4b51dc1b Mon Sep 17 00:00:00 2001 From: Edward Hartnett Date: Wed, 4 May 2022 08:04:54 -0600 Subject: [PATCH 4/6] doxygen for filter functions --- docs/Doxyfile.in | 1 + libdispatch/dfilter.c | 217 ++++++++++++++++++++++++++++++++---------- 2 files changed, 169 insertions(+), 49 deletions(-) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 0f5d3324f3..5411ff5e70 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -781,6 +781,7 @@ INPUT = \ @abs_top_srcdir@/libdispatch/derror.c \ @abs_top_srcdir@/libdispatch/dv2i.c \ @abs_top_srcdir@/libdispatch/dcopy.c \ + @abs_top_srcdir@/libdispatch/dfilter.c \ @abs_top_srcdir@/libsrc4/nc4var.c \ @abs_top_srcdir@/libhdf5/nc4hdf.c \ @abs_top_srcdir@/libsrc4/nc4internal.c \ diff --git a/libdispatch/dfilter.c b/libdispatch/dfilter.c index f953402bce..3780019e69 100644 --- a/libdispatch/dfilter.c +++ b/libdispatch/dfilter.c @@ -2,6 +2,10 @@ * Copyright 2018, University Corporation for Atmospheric Research * See netcdf/COPYRIGHT file for copying and redistribution conditions. */ +/** + * @file + * Functions for working with filters. + */ #include "config.h" #include @@ -35,21 +39,20 @@ Unified filter related code Find the set of filters (if any) associated with a variable. Assumes HDF5 format using unsigned ints. -\param ncid NetCDF or group ID, from a previous call to nc_open(), +@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 -\param nfilters return no. of filters; may be zero -\param ids return the filter ids (caller allocates) - -\returns ::NC_NOERR No error. -\returns ::NC_ENOTNC4 Not a netCDF-4 file. -\returns ::NC_EBADID Bad ncid -\returns ::NC_ENOTVAR Invalid variable ID. -\returns ::NC_EINVAL Invalid arguments -\ingroup variables -\author Dennis Heimbigner +@param varid Variable ID +@param nfiltersp Pointer that gets the number of filters; may be zero. +@param ids return the filter ids (caller allocates) + +@returns ::NC_NOERR No error. +@returns ::NC_ENOTNC4 Not a netCDF-4 file. +@returns ::NC_EBADID Bad ncid +@returns ::NC_ENOTVAR Invalid variable ID. +@returns ::NC_EINVAL Invalid arguments +@ingroup variables +@author Dennis Heimbigner */ EXTERNL int nc_inq_var_filter_ids(int ncid, int varid, size_t* nfiltersp, unsigned int* ids) @@ -69,23 +72,23 @@ Find the the param info about filter (if any) associated with a variable and with specified id. Assumes HDF5 format using unsigned ints. -\param ncid NetCDF or group ID, from a previous call to nc_open(), +@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 -\param id The filter id of interest -\param nparamsp (Out) Storage which will get the number of parameters to the filter -\param params (Out) Storage which will get associated parameters. +@param varid Variable ID +@param id The filter id of interest +@param nparamsp (Out) Storage which will get the number of parameters to the filter +@param params (Out) Storage which will get associated parameters. Note: the caller must allocate and free. -\returns ::NC_NOERR No error. -\returns ::NC_ENOTNC4 Not a netCDF-4 file. -\returns ::NC_EBADID Bad ncid. -\returns ::NC_ENOTVAR Invalid variable ID. -\returns ::NC_ENOFILTER Specified filter not defined for this variable. -\ingroup variables -\author Dennis Heimbigner +@returns ::NC_NOERR No error. +@returns ::NC_ENOTNC4 Not a netCDF-4 file. +@returns ::NC_EBADID Bad ncid. +@returns ::NC_ENOTVAR Invalid variable ID. +@returns ::NC_ENOFILTER Specified filter not defined for this variable. +@ingroup variables +@author Dennis Heimbigner */ EXTERNL int nc_inq_var_filter_info(int ncid, int varid, unsigned int id, size_t* nparamsp, unsigned int* params) @@ -109,7 +112,7 @@ nc_inq_var_filter_info(int ncid, int varid, unsigned int id, size_t* nparamsp, u @param varid Variable ID. @param id Filter ID. @param nparams Number of filter parameters. - @param parms Filter parameters. + @param params Filter parameters. @return ::NC_NOERR No error. @return ::NC_EINVAL Variable must be chunked. @@ -141,28 +144,28 @@ nc_def_var_filter(int ncid, int varid, unsigned int id, size_t nparams, const un Find the first filter (if any) associated with a variable. Assumes HDF5 format using unsigned int. -\param ncid NetCDF or group ID, from a previous call to nc_open(), +@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 +@param varid Variable ID -\param idp Storage which will get the filter id; a return value of zero means variable has no filters. +@param idp Storage which will get the filter id; a return value of zero means variable has no filters. -\param nparamsp Storage which will get the number of parameters to the filter +@param nparamsp Storage which will get the number of parameters to the filter -\param params Storage which will get associated parameters (call allocates and frees). +@param params Storage which will get associated parameters (call allocates and frees). This is redundant over the multi-filter API, so it can be implemented in terms of those functions. -\returns ::NC_NOERR No error. -\returns ::NC_ENOTNC4 Not a netCDF-4 file. -\returns ::NC_EBADID Bad ncid. -\returns ::NC_ENOTVAR Invalid variable ID. +@returns ::NC_NOERR No error. +@returns ::NC_ENOTNC4 Not a netCDF-4 file. +@returns ::NC_EBADID Bad ncid. +@returns ::NC_ENOTVAR Invalid variable ID. -\ingroup variables -\author Dennis Heimbigner +@ingroup variables +@author Dennis Heimbigner */ EXTERNL int nc_inq_var_filter(int ncid, int varid, unsigned int* idp, size_t* nparamsp, unsigned int* params) @@ -193,15 +196,17 @@ nc_inq_var_filter(int ncid, int varid, unsigned int* idp, size_t* nparamsp, unsi return stat; } -/**************************************************/ -/* Test if filter is available. Would prefer - returning a list of all available filters, but HDF5 - does not support that capability. - @param file for which filter list is desired - @param id filter id of interest - @return NC_NOERR if the filter is available - @return NC_EBADID if ncid is invalid - @return NC_ENOFILTER if filter is not available. +/** Test if filter is available. Would prefer + * returning a list of all available filters, but HDF5 + * does not support that capability. + * + * @param ncid ID of file for which filter list is desired + * @param id filter id of interest + * + * @return NC_NOERR if the filter is available + * @return NC_EBADID if ncid is invalid + * @return NC_ENOFILTER if filter is not available. + * @author Dennis Heimbigner */ EXTERNL int @@ -222,7 +227,17 @@ nc_inq_filter_avail(int ncid, unsigned id) #ifdef ENABLE_CLIENTSIDE_FILTERS -/* Use void* to avoid having to include hdf.h*/ +/** Register filer client. + * @note Use void* to avoid having to include hdf.h + * + * @param id Filter ID + * @param info Pointer that gets info. + * + * @return NC_NOERR if the filter is available + * @return NC_EBADID if ncid is invalid + * @return NC_ENOFILTER if filter is not available. + * @author Dennis Heimbigner +*/ EXTERNL int nc_filter_client_register(unsigned int id, void* info) { @@ -244,6 +259,14 @@ nc_filter_client_register(unsigned int id, void* info) return stat; } +/** Unregister filer client. + * @note Use void* to avoid having to include hdf.h + * + * @param id Filter ID + * + * @return NC_NOERR if the filter is available + * @author Dennis Heimbigner +*/ EXTERNL int nc_filter_client_unregister(unsigned int id) { @@ -256,7 +279,15 @@ int stat = NC_NOERR; return stat; } -/* Use void* to avoid having to include hdf.h*/ +/** Inquire about filer client. + * @note Use void* to avoid having to include hdf.h + * + * @param id Filter ID + * @param infop Pointer that gets info. + * + * @return NC_NOERR if the filter is available + * @author Dennis Heimbigner +*/ EXTERNL int nc_filter_client_inq(unsigned int id, void* infop) { @@ -286,6 +317,17 @@ int stat = NC_NOERR; /**************************************************/ /* Functions for accessing standardized filters */ +/** + * Turn on bzip2 compression for a variable. + * + * @param ncid File ID. + * @param varid Variable ID. + * @param level From 1 to 9. Set the block size to 100k, 200k ... 900k + * when compressing. (bzip2 default level is 9). + * + * @return 0 for success, error code otherwise. + * @author Dennis Heimbigner, Ed Hartnett + */ int nc_def_var_bzip2(int ncid, int varid, int level) { @@ -303,6 +345,20 @@ nc_def_var_bzip2(int ncid, int varid, int level) return stat; } +/** + * Learn whether bzip2 compression is on for a variable, and, if so, + * the level setting. + * + * @param ncid File ID. + * @param varid Variable ID. + * @param hasfilterp Pointer that gets a 0 if bzip2 is not in use for this + * var, and a 1 if it is. Ignored if NULL. + * @param levelp Pointer that gets the level setting (from 1 to 9), if + * bzip2 is in use. Ignored if NULL. + * + * @return 0 for success, error code otherwise. + * @author Dennis Heimbigner, Ed Hartnett + */ int nc_inq_var_bzip2(int ncid, int varid, int* hasfilterp, int *levelp) { @@ -326,6 +382,20 @@ nc_inq_var_bzip2(int ncid, int varid, int* hasfilterp, int *levelp) return stat; } +/** + * Turn on Zstandard compression for a variable. + * + * @param ncid File ID. + * @param varid Variable ID. + * @param level From -131072 to 22 (depends on Zstandard version). + * when compressing. Regular compression levels are from 1 up to 19. + * Use levels >= 20, labeled `--ultra`, cautiously: they require more memory. + * Negative compression levels that extend the range of speed vs. ratio preferences. + * The lower the level, the faster the speed (at the cost of compression). + * + * @return 0 for success, error code otherwise. + * @author Charlie Zender, Dennis Heimbigner, Ed Hartnett + */ int nc_def_var_zstandard(int ncid, int varid, int level) { @@ -348,6 +418,20 @@ nc_def_var_zstandard(int ncid, int varid, int level) #endif /*HAVE_ZSTD*/ } +/** + * Learn whether Zstandard compression is on for a variable, and, if so, + * the level setting. + * + * @param ncid File ID. + * @param varid Variable ID. + * @param hasfilterp Pointer that gets a 0 if Zstandard is not in use for this + * var, and a 1 if it is. Ignored if NULL. + * @param levelp Pointer that gets the level setting (from -131072 to 22), if + * Zstandard is in use. Ignored if NULL. + * + * @return 0 for success, error code otherwise. + * @author Charlie Zender, Dennis Heimbigner, Ed Hartnett + */ int nc_inq_var_zstandard(int ncid, int varid, int* hasfilterp, int *levelp) { @@ -375,6 +459,20 @@ nc_inq_var_zstandard(int ncid, int varid, int* hasfilterp, int *levelp) #endif /*HAVE_ZSTD*/ } +/** + * Turn on blosc for a variable. + * + * @param ncid File ID. + * @param varid Variable ID. + * @param subcompressor The subcompressor. + * @param level The level setting. + * @param blocksize The block size. + * @param addshuffle If non-zero, turn on shuffle. + * + * @return 0 for success, error code otherwise. + * @author Dennis Heimbigner + * @ingroup variables + */ int nc_def_var_blosc(int ncid, int varid, unsigned subcompressor, unsigned level, unsigned blocksize, unsigned addshuffle) { @@ -405,8 +503,29 @@ nc_def_var_blosc(int ncid, int varid, unsigned subcompressor, unsigned level, un #endif } +/** + * Learn whether Blosc compression is on for a variable, and, if so, + * the settings. + * + * @param ncid File ID. + * @param varid Variable ID. + * @param hasfilterp Pointer that gets a 0 if blosc is not in use for this + * var, and a 1 if it is. Ignored if NULL. + * @param subcompressorp Pointer that gets the subcompressor, if + * blosc is in use. Ignored if NULL. + * @param levelp Pointer that gets the level setting, if + * blosc is in use. Ignored if NULL. + * @param blocksizep Pointer that gets the block size, if + * blosc is in use. Ignored if NULL. + * @param addshufflep Pointer that gets non-zero value if shuffle is + * in use, if blosc is in use. Ignored if NULL. + * + * @return 0 for success, error code otherwise. + * @author Dennis Heimbigner + */ int -nc_inq_var_blosc(int ncid, int varid, int* hasfilterp, unsigned* subcompressorp, unsigned* levelp, unsigned* blocksizep, unsigned* addshufflep) +nc_inq_var_blosc(int ncid, int varid, int* hasfilterp, unsigned* subcompressorp, + unsigned* levelp, unsigned* blocksizep, unsigned* addshufflep) { #ifdef HAVE_BLOSC int stat = NC_NOERR; From 955b77f831b54ea3c6c8c8e3311c09cf969e3786 Mon Sep 17 00:00:00 2001 From: Edward Hartnett Date: Wed, 4 May 2022 10:05:38 -0600 Subject: [PATCH 5/6] removed all-error-codes.md --- docs/CMakeLists.txt | 2 +- docs/Doxyfile.in | 1 - docs/Makefile.am | 16 ++-- docs/all-error-codes.md | 188 ---------------------------------------- 4 files changed, 7 insertions(+), 200 deletions(-) delete mode 100644 docs/all-error-codes.md diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 2f510e7778..beb8bfa735 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -90,7 +90,7 @@ netcdf.m4 DoxygenLayout.xml Doxyfile.in footer.html mainpage.dox tutorial.dox guide.dox types.dox architecture.dox internal.dox windows-binaries.md building-with-cmake.md CMakeLists.txt groups.dox install.md notes.md -install-fortran.md all-error-codes.md credits.md auth.md +install-fortran.md credits.md auth.md obsolete/fan_utils.html bestpractices.md filters.md indexing.md inmemory.md DAP2.dox FAQ.md known_problems.md diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 5411ff5e70..efefe09f79 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -747,7 +747,6 @@ INPUT = \ @abs_top_srcdir@/docs/byterange.dox \ @abs_top_srcdir@/docs/nczarr.md \ @abs_top_srcdir@/docs/notes.md \ - @abs_top_srcdir@/docs/all-error-codes.md \ @abs_top_srcdir@/docs/building-with-cmake.md \ @abs_top_srcdir@/docs/FAQ.md \ @abs_top_srcdir@/docs/known_problems.md \ diff --git a/docs/Makefile.am b/docs/Makefile.am index 9f851abc9d..9c54bd2d82 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -8,16 +8,12 @@ # These files will be included with the dist. EXTRA_DIST = netcdf.m4 DoxygenLayout.xml Doxyfile.in footer.html \ -mainpage.dox tutorial.dox \ -architecture.dox internal.dox windows-binaries.md \ -building-with-cmake.md CMakeLists.txt groups.dox notes.md \ -install-fortran.md all-error-codes.md credits.md auth.md filters.md \ -obsolete/fan_utils.html indexing.dox \ -inmemory.md FAQ.md \ -known_problems.md COPYRIGHT.md \ -inmeminternal.dox \ -testserver.dox byterange.dox \ -nczarr.md +mainpage.dox tutorial.dox architecture.dox internal.dox \ +windows-binaries.md building-with-cmake.md CMakeLists.txt groups.dox \ +notes.md install-fortran.md credits.md auth.md filters.md \ +obsolete/fan_utils.html indexing.dox inmemory.md FAQ.md \ +known_problems.md COPYRIGHT.md inmeminternal.dox testserver.dox \ +byterange.dox nczarr.md # Turn off parallel builds in this directory. .NOTPARALLEL: diff --git a/docs/all-error-codes.md b/docs/all-error-codes.md deleted file mode 100644 index 78829c2ab4..0000000000 --- a/docs/all-error-codes.md +++ /dev/null @@ -1,188 +0,0 @@ -NetCDF Error Code Listing {#nc-error-codes} -================== - -\tableofcontents - -# NetCDF-3 Error Codes {#nc3-error-codes} - -~~~~ -#define NC_NOERR 0 // No Error -#define NC_EBADID (-33) // Not a netcdf id -#define NC_ENFILE (-34) // Too many netcdfs open -#define NC_EEXIST (-35) // netcdf file exists && NC_NOCLOBBER -#define NC_EINVAL (-36) // Invalid Argument -#define NC_EPERM (-37) // Write to read only -#define NC_ENOTINDEFINE (-38) // Operation not allowed in data mode -#define NC_EINDEFINE (-39) // Operation not allowed in define mode -#define NC_EINVALCOORDS (-40) // Index exceeds dimension bound -#define NC_EMAXDIMS (-41) // NC_MAX_DIMS exceeded [not enforced after 4.5.0] -#define NC_ENAMEINUSE (-42) // String match to name in use -#define NC_ENOTATT (-43) // Attribute not found -#define NC_EMAXATTS (-44) // NC_MAX_ATTRS exceeded [not enforced after 4.5.0] -#define NC_EBADTYPE (-45) // Not a netcdf data type -#define NC_EBADDIM (-46) // Invalid dimension id or name -#define NC_EUNLIMPOS (-47) // NC_UNLIMITED in the wrong index -#define NC_EMAXVARS (-48) // NC_MAX_VARS exceeded [not enforced after 4.5.0] -#define NC_ENOTVAR (-49) // Variable not found -#define NC_EGLOBAL (-50) // Action prohibited on NC_GLOBAL varid -#define NC_ENOTNC (-51) // Not a netcdf file -#define NC_ESTS (-52) // In Fortran, string too short -#define NC_EMAXNAME (-53) // NC_MAX_NAME exceeded -#define NC_EUNLIMIT (-54) // NC_UNLIMITED size already in use -#define NC_ENORECVARS (-55) // nc_rec op when there are no record vars -#define NC_ECHAR (-56) // Attempt to convert between text & numbers -#define NC_EEDGE (-57) // Edge+start exceeds dimension bound -#define NC_ESTRIDE (-58) // Illegal stride -#define NC_EBADNAME (-59) // Attribute or variable name contains illegal characters - -// N.B. following must match value in ncx.h - -#define NC_ERANGE (-60) // Math result not representable -#define NC_ENOMEM (-61) // Memory allocation (malloc) failure -#define NC_EVARSIZE (-62) // One or more variable sizes violate format constraints -#define NC_EDIMSIZE (-63) // Invalid dimension size -#define NC_ETRUNC (-64) // File likely truncated or possibly corrupted -#define NC_EAXISTYPE (-65) // Unknown axis type -~~~~ - -# DAP Error Codes {#dap-error-codes} - -If the DAP client is enabled, then the following additional error codes -may occur. - -~~~~ -#define NC_EDAP (-66) // Generic DAP error -#define NC_ECURL (-67) // Generic libcurl error -#define NC_EIO (-68) // Generic IO error -#define NC_ENODATA (-69) // Attempt to access variable with no data -#define NC_EDAPSVC (-70) // DAP Server side error -#define NC_EDAS (-71) // Malformed or inaccessible DAS -#define NC_EDDS (-72) // Malformed or inaccessible DDS -#define NC_EDATADDS (-73) // Malformed or inaccessible DATADDS -#define NC_EDAPURL (-74) // Malformed DAP URL -#define NC_EDAPCONSTRAINT (-75) // Malformed DAP Constraint -#define NC_ETRANSLATION (-76) // Untranslatable construct -#define NC_EACCESS (-77) // Access Failure -#define NC_EAUTH (-78) // Authorization Failure -~~~~ - -# Misc. additional errors -~~~~ -#define NC_ENOTFOUND (-90) // No such file -#define NC_ECANTREMOVE (-91) // Cannot remove file -#define NC_EINTERNAL (-92) // NetCDF Library Internal Error -#define NC_EPNETCDF (-93) // Error at PnetCDF layer -~~~~ - -# NetCDF-4 Error Codes {#nc4-error-codes} - -NetCDF-4 uses all error codes from NetCDF-3 (see section [NetCDF-3 Error -Codes](#NetCDF_002d3-Error-Codes)). The following additional error codes -were added for new errors unique to netCDF-4. - -~~~~ -#define NC_EHDFERR (-101) // Error at HDF5 layer. -#define NC_ECANTREAD (-102) // Cannot read. -#define NC_ECANTWRITE (-103) // Cannot write. -#define NC_ECANTCREATE (-104) // Cannot create. -#define NC_EFILEMETA (-105) // Problem with file metadata. -#define NC_EDIMMETA (-106) // Problem with dimension metadata. -#define NC_EATTMETA (-107) // Problem with attribute metadata. -#define NC_EVARMETA (-108) // Problem with variable metadata. -#define NC_ENOCOMPOUND (-109) // Not a compound type. -#define NC_EATTEXISTS (-110) // Attribute already exists. -#define NC_ENOTNC4 (-111) // Attempting netcdf-4 operation on netcdf-3 file. -#define NC_ESTRICTNC3 (-112) // Attempting netcdf-4 operation on strict nc3 netcdf-4 file. -#define NC_ENOTNC3 (-113) // Attempting netcdf-3 operation on netcdf-4 file. -#define NC_ENOPAR (-114) // Parallel operation on file opened for non-parallel access. -#define NC_EPARINIT (-115) // Error initializing for parallel access. -#define NC_EBADGRPID (-116) // Bad group ID. -#define NC_EBADTYPID (-117) // Bad type ID. -#define NC_ETYPDEFINED (-118) // Type has already been defined and may not be edited. -#define NC_EBADFIELD (-119) // Bad field ID. -#define NC_EBADCLASS (-120) // Bad class. -#define NC_EMAPTYPE (-121) // Mapped access for atomic types only. -#define NC_ELATEFILL (-122) // Attempt to define fill value when data already exists. -#define NC_ELATEDEF (-123) // Attempt to define var properties, like deflate, after enddef. -#define NC_EDIMSCALE (-124) // Problem with HDF5 dimscales. -#define NC_ENOGRP (-125) // No group found. -#define NC_ESTORAGE (-126) // Cannot specify both contiguous and chunking. -#define NC_EBADCHUNK (-127) // Bad chunksize. -#define NC_ENOTBUILT (-128) // Attempt to use feature that was not turned on when netCDF was built. -#define NC_EDISKLESS (-129) // Error in using diskless access. -#define NC_ECANTEXTEND (-130) // Attempt to extend dataset during ind. I/O operation. -#define NC_EMPI (-131) // MPI operation failed. -#define NC_EFILTER (-132) // Filter operation failed. -#define NC_ERCFILE (-133) // RC file failure -#define NC_ENULLPAD (-134) // Header Bytes not Null-Byte padded -#define NC_EINMEMORY (-135) // In-memory file error -~~~~ - -# PnetCDF Error Codes {#pnetcdf-error-codes} - -~~~~ -#define NC_ESMALL (-201) // size of MPI_Offset too small for format -#define NC_ENOTINDEP (-202) // Operation not allowed in collective data mode -#define NC_EINDEP (-203) // Operation not allowed in independent data mode -#define NC_EFILE (-204) // Unknown error in file operation -#define NC_EREAD (-205) // Unknown error in reading file -#define NC_EWRITE (-206) // Unknown error in writing to file -#define NC_EOFILE (-207) // file open/creation failed -#define NC_EMULTITYPES (-208) // Multiple etypes used in MPI datatype -#define NC_EIOMISMATCH (-209) // Input/Output data amount mismatch -#define NC_ENEGATIVECNT (-210) // Negative count is specified -#define NC_EUNSPTETYPE (-211) // Unsupported etype in memory MPI datatype -#define NC_EINVAL_REQUEST (-212) // invalid nonblocking request ID -#define NC_EAINT_TOO_SMALL (-213) // MPI_Aint not large enough to hold requested value -#define NC_ENOTSUPPORT (-214) // feature is not yet supported -#define NC_ENULLBUF (-215) // trying to attach a NULL buffer -#define NC_EPREVATTACHBUF (-216) // previous attached buffer is found -#define NC_ENULLABUF (-217) // no attached buffer is found -#define NC_EPENDINGBPUT (-218) // pending bput is found, cannot detach buffer -#define NC_EINSUFFBUF (-219) // attached buffer is too small -#define NC_ENOENT (-220) // File does not exist -#define NC_EINTOVERFLOW (-221) // Overflow when type cast to 4-byte integer -#define NC_ENOTENABLED (-222) // feature is not enabled -#define NC_EBAD_FILE (-223) // Invalid file name (e.g., path name too long) -#define NC_ENO_SPACE (-224) // Not enough space -#define NC_EQUOTA (-225) // Quota exceeded -#define NC_ENULLSTART (-226) // argument start is a NULL pointer -#define NC_ENULLCOUNT (-227) // argument count is a NULL pointer -#define NC_EINVAL_CMODE (-228) // Invalid file create mode -#define NC_ETYPESIZE (-229) // MPI derived data type size error (bigger than the variable size) -#define NC_ETYPE_MISMATCH (-230) // element type of the MPI derived data type mismatches the variable type -#define NC_ETYPESIZE_MISMATCH (-231) // file type size mismatches buffer type size -#define NC_ESTRICTCDF2 (-232) // Attempting CDF-5 operation on CDF-2 file -#define NC_ENOTRECVAR (-233) // Attempting operation only for record variables -#define NC_ENOTFILL (-234) // Attempting to fill a variable when its fill mode is off -#define NC_EINVAL_OMODE (-235) // Invalid file open mode -#define NC_EPENDING (-236) // Pending nonblocking request is found at file close -#define NC_EMAX_REQ (-237) // Size of I/O request exceeds INT_MAX -#define NC_EBADLOG (-238) // Unrecognized log file format -#define NC_EFLUSHED (-239) // Nonblocking request has already been flushed to the PFS. It is too late to cancel -#define NC_EMULTIDEFINE (-250) // NC definitions inconsistent among processes -#define NC_EMULTIDEFINE_OMODE (-251) // inconsistent file open modes among processes -#define NC_EMULTIDEFINE_DIM_NUM (-252) // inconsistent number of dimensions -#define NC_EMULTIDEFINE_DIM_SIZE (-253) // inconsistent size of dimension -#define NC_EMULTIDEFINE_DIM_NAME (-254) // inconsistent dimension names -#define NC_EMULTIDEFINE_VAR_NUM (-255) // inconsistent number of variables -#define NC_EMULTIDEFINE_VAR_NAME (-256) // inconsistent variable name -#define NC_EMULTIDEFINE_VAR_NDIMS (-257) // inconsistent variable number of dimensions -#define NC_EMULTIDEFINE_VAR_DIMIDS (-258) // inconsistent variable dimension IDs -#define NC_EMULTIDEFINE_VAR_TYPE (-259) // inconsistent variable data type -#define NC_EMULTIDEFINE_VAR_LEN (-260) // inconsistent variable size -#define NC_EMULTIDEFINE_NUMRECS (-261) // inconsistent number of records -#define NC_EMULTIDEFINE_VAR_BEGIN (-262) // inconsistent variable file begin offset (internal use) -#define NC_EMULTIDEFINE_ATTR_NUM (-263) // inconsistent number of attributes -#define NC_EMULTIDEFINE_ATTR_SIZE (-264) // inconsistent memory space used by attribute (internal use) -#define NC_EMULTIDEFINE_ATTR_NAME (-265) // inconsistent attribute name -#define NC_EMULTIDEFINE_ATTR_TYPE (-266) // inconsistent attribute type -#define NC_EMULTIDEFINE_ATTR_LEN (-267) // inconsistent attribute length -#define NC_EMULTIDEFINE_ATTR_VAL (-268) // inconsistent attribute value -#define NC_EMULTIDEFINE_FNC_ARGS (-269) // inconsistent function arguments used in collective API -#define NC_EMULTIDEFINE_FILL_MODE (-270) // inconsistent dataset fill mode -#define NC_EMULTIDEFINE_VAR_FILL_MODE (-271) // inconsistent variable fill mode -#define NC_EMULTIDEFINE_VAR_FILL_VALUE (-272) // inconsistent variable fill value -#define NC_EMULTIDEFINE_CMODE (-273) // inconsistent file create modes among processes -~~~~ - From 7a61c9a8d4388e7e3faf99fb0d8510a19bf590cd Mon Sep 17 00:00:00 2001 From: Edward Hartnett Date: Wed, 4 May 2022 13:12:48 -0600 Subject: [PATCH 6/6] added netcdf_filter.h to doxygen build --- docs/Doxyfile.in | 1 + include/netcdf_filter.h | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index efefe09f79..cabec71218 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -760,6 +760,7 @@ INPUT = \ @abs_top_srcdir@/include/netcdf.h \ @abs_top_srcdir@/include/netcdf_mem.h \ @abs_top_srcdir@/include/netcdf_par.h \ + @abs_top_srcdir@/include/netcdf_filter.h \ @abs_top_srcdir@/libdispatch/dfile.c \ @abs_top_srcdir@/libdispatch/ddim.c \ @abs_top_srcdir@/libdispatch/dvar.c \ diff --git a/include/netcdf_filter.h b/include/netcdf_filter.h index 8b52b73039..3c3c88c79b 100644 --- a/include/netcdf_filter.h +++ b/include/netcdf_filter.h @@ -1,5 +1,6 @@ /* Copyright 2018, UCAR/Unidata and OPeNDAP, Inc. See the COPYRIGHT file for more information. */ +/*! @file */ /* * In order to use any of the netcdf_XXX.h files, it is necessary