From 6a3634b975747097a18b526bdfd43a3e0cb03e3e Mon Sep 17 00:00:00 2001 From: Edward Hartnett Date: Sat, 17 Aug 2024 06:14:10 -0600 Subject: [PATCH 1/3] added documentation about reading an unknown netCDF/HDF5 file in tutorial --- docs/tutorial.dox | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/tutorial.dox b/docs/tutorial.dox index 40369442a4..fe66337224 100644 --- a/docs/tutorial.dox +++ b/docs/tutorial.dox @@ -894,7 +894,7 @@ interest. Use ncdump to learn the structure of a file (use the -h option). -\page reading_unknown Reading NetCDF Files of Unknown Structure +\page reading_unknown Reading Classic Format NetCDF Files of Unknown Structure Perhaps you would like to write your software to handle more general cases, so that you don't have to adjust your source every time the @@ -946,6 +946,42 @@ num attributes. - nc_inq_format() Find file format: classic CDF-1, 64-bit offset CDF-2, or 64-bit data CDF-5 - nc_inq_libvers() Find the netCDF library version. +\page reading_unknown Reading NetCDF/HDF5 Format NetCDF Files of Unknown Structure + +When using netCDF/HDF5 files (i.e. NC_NETCDF4 without +NC_CLASSIC_MODEL), reading an unknown file is more complex, because +groups and multiple unilimited dimensions are permitted. User defined +types may also be present. + +To read an unknown netCDF/HDF5 file, start at the root group and then +read each group recursively. Within each group, start by scanning for +user-defined types. + +The follow additional inquiry functions support netCDF/HDF5 files. + +Files and Groups: +- nc_inq_ncid() +- nc_inq_grps() +- nc_inq_grpname() +- nc_inq_grpname_full() +- nc_inq_grpname_len() +- nc_inq_grp_parent() +- nc_inq_grp_ncid() +- nc_inq_grp_full_ncid() +- nc_inq_unlimdims() + +User Defined Types: +- nc_inq_type_equal() +- nc_inq_type() +- nc_inq_user_type() +- nc_inq_typeid() +- nc_inq_compound() +- nc_inq_compound_field() +- nc_inq_vlen() +- nc_inq_enum() +- nc_inq_enum_member() +- nc_inq_opaque() + \page accessing_subsets Reading and Writing Subsets of Data Usually users are interested in reading or writing subsets of From 971c60ccb71abe6bf05ce57bb8c02780c8fb253b Mon Sep 17 00:00:00 2001 From: Edward Hartnett Date: Sat, 17 Aug 2024 06:33:59 -0600 Subject: [PATCH 2/3] fixed some broken links --- docs/FAQ.md | 2 +- docs/install-fortran.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 1f442f07ad..37adc16d16 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -49,7 +49,7 @@ utility programs, is available from [the NetCDF Downloads page](https://downloads.unidata.ucar.edu/netcdf-c). Separate source distributions for the Java library, Fortran libraries, and C++ libraries are also available there. Installation instructions are available with the -distribution or [online](https://docs.unidata.ucar.edu/netcdf-c/current/building.html). +distribution or [online](https://docs.unidata.ucar.edu/netcdf-c/current/netCDF-CMake.html). Binary distributions of netCDF are available for various platforms from package management systems such as dpkg, RPM, fink, MacPorts, Homebrew, diff --git a/docs/install-fortran.md b/docs/install-fortran.md index 739ae787a6..37fb53a431 100644 --- a/docs/install-fortran.md +++ b/docs/install-fortran.md @@ -15,7 +15,7 @@ More recently, building netcdf-fortran as an automated step in the netcdf-c build is now possible (for non-MSVC builds) by using new options at configure time, so if you haven't built and installed the netCDF-C library yet, you may want to try the new netCDF-C Fortran-bootstrap procedure. In the example commands below, we assume use of a From 7eeb055a772c9dd012824247d6ce231dede0d48d Mon Sep 17 00:00:00 2001 From: Ward Fisher Date: Fri, 23 Aug 2024 11:13:01 -0600 Subject: [PATCH 3/3] Clean up doxygen syntax in release notes, fix incorrect version in CMakeLists.txt, and resolve duplicated doxygen tags in tutorial.dox --- CMakeLists.txt | 4 ++-- RELEASE_NOTES.md | 6 ++---- docs/tutorial.dox | 7 ++++--- 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 35f4292f23..27edd4d6ab 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -13,7 +13,7 @@ project(netCDF LANGUAGES C CXX HOMEPAGE_URL "https://www.unidata.ucar.edu/software/netcdf/" DESCRIPTION "NetCDF is a set of software libraries and machine-independent data formats that support the creation, access, and sharing of array-oriented scientific data." - VERSION 4.9.3 + VERSION 4.9.4 ) ##### @@ -27,7 +27,7 @@ project(netCDF # http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning ##### -set(NC_VERSION_NOTE "-rc1") +set(NC_VERSION_NOTE "-development") set(netCDF_VERSION ${PROJECT_VERSION}${NC_VERSION_NOTE}) set(VERSION ${netCDF_VERSION}) set(NC_VERSION ${netCDF_VERSION}) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index f96349383a..3d2f0d8216 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -10,7 +10,7 @@ This file contains a high-level description of this package's evolution. Release * Provide better documentation for the .rc file mechanism and API. See [Github #2956](https://github.com/Unidata/netcdf-c/pull/2956) for more information. * Convert NCZarr V2 to store all netcdf-4 specific info as attributes. This improves interoperability with other Zarr implementations by no longer using non-standard keys. The price to be paid is that lazy attribute reading cannot be supported. See [Github #2836](https://github.com/Unidata/netcdf-c/pull/2936) for more information. * Cleanup the option code for NETCDF_ENABLE_SET_LOG_LEVEL\[_FUNC\] See [Github #2931](https://github.com/Unidata/netcdf-c/pull/2931) for more information. -* + ### Release Candidate 1 - July 26, 2024 * Convert NCZarr V2 to store all netcdf-4 specific info as attributes. This improves interoperability with other Zarr implementations by no longer using non-standard keys. The price to be paid is that lazy attribute reading cannot be supported. See [Github #2836](https://github.com/Unidata/netcdf-c/issues/2936) for more information. @@ -661,12 +661,10 @@ Example Work Flow from netcdf-c source directory: * $ `make build-netcdf-fortran` * $ `make install-netcdf-fortran` -> These make targets are **only** valid after `make install` has been invoked. This cannot be enforced rigidly in the makefile for reasons we will expand on in the documentation, but in short: `make install` may require sudo, but using sudo will discard environmental variables required when attempting to build netcdf-fortran in this manner.

+> These make targets are **only** valid after `make install` has been invoked. This cannot be enforced rigidly in the makefile for reasons we will expand on in the documentation, but in short: `make install` may require sudo, but using sudo will discard environmental variables required when attempting to build netcdf-fortran in this manner. > It is important to note that this is functionality is for *convenience only*. It will remain possible to build `netcdf-c` and `netcdf-fortran` manually. These make targets should hopefully suffice for the majority of our users, but for corner cases it may still be required of the user to perform a manual build. [NCF-323](https://bugtracking.unidata.ucar.edu/browse/NCF-323) ----- - * Added a failure state if the `m4` utility is not found on non-Windows systems; previously, the build would fail when it reached the point of invoking m4. * Added an explicit check in the build systems (autotools, cmake) for the CURL-related option `CURLOPT_CHUNK_BGN_FUNCTION`. This option was introduced in libcurl version `7.21.0`. On installations which require libcurl and have this version, `CURLOPT_CHUNK_BGN_FUNCTION` will be available. Otherwise, it will not. diff --git a/docs/tutorial.dox b/docs/tutorial.dox index fe66337224..314bff3be6 100644 --- a/docs/tutorial.dox +++ b/docs/tutorial.dox @@ -15,7 +15,8 @@ This page contains references to various other NetCDF background and tutorial pa - \subpage tutorial_ncids - \subpage creating - \subpage reading_known -- \subpage reading_unknown +- \subpage reading_unknown_classic +- \subpage reading_unknown_nc4 - \subpage accessing_subsets \subsection background_further_reading Background and Further Reading @@ -894,7 +895,7 @@ interest. Use ncdump to learn the structure of a file (use the -h option). -\page reading_unknown Reading Classic Format NetCDF Files of Unknown Structure +\page reading_unknown_classic Reading Classic Format NetCDF Files of Unknown Structure Perhaps you would like to write your software to handle more general cases, so that you don't have to adjust your source every time the @@ -946,7 +947,7 @@ num attributes. - nc_inq_format() Find file format: classic CDF-1, 64-bit offset CDF-2, or 64-bit data CDF-5 - nc_inq_libvers() Find the netCDF library version. -\page reading_unknown Reading NetCDF/HDF5 Format NetCDF Files of Unknown Structure +\page reading_unknown_nc4 Reading NetCDF/HDF5 Format NetCDF Files of Unknown Structure When using netCDF/HDF5 files (i.e. NC_NETCDF4 without NC_CLASSIC_MODEL), reading an unknown file is more complex, because