From b5de20eeaf78524a7409709280465db2c8f9ff93 Mon Sep 17 00:00:00 2001 From: Dennis Heimbigner Date: Mon, 9 Jan 2023 14:54:21 -0700 Subject: [PATCH] Add documentation about how to modify NC_DISPATCH_VERSION re: Issue https://github.com/Unidata/netcdf-c/issues/2582 Update the file netcdf-c/docs/dispatch.md to include an appendix that discusses how to properly update the NC_DISPATCH_VERSION for the dispatch table. --- configure.ac | 2 +- docs/dispatch.md | 25 +++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/configure.ac b/configure.ac index 3a38069449..49a72d6bbb 100644 --- a/configure.ac +++ b/configure.ac @@ -2064,12 +2064,12 @@ AX_SET_META([NC_HAS_SZIP],[$enable_hdf5_szip],[yes]) AX_SET_META([NC_HAS_ZSTD],[$have_zstd],[yes]) AX_SET_META([NC_HAS_BLOSC],[$have_blosc],[yes]) AX_SET_META([NC_HAS_BZ2],[$have_bz2],[yes]) + # This is the version of the dispatch table. If the dispatch table is # changed, this should be incremented, so that user-defined format # applications like PIO can determine whether they have an appropriate # dispatch table to submit. If this is changed, make sure the value in # CMakeLists.txt also changes to match. - AC_SUBST([NC_DISPATCH_VERSION], [5]) AC_DEFINE_UNQUOTED([NC_DISPATCH_VERSION], [${NC_DISPATCH_VERSION}], [Dispatch table version.]) diff --git a/docs/dispatch.md b/docs/dispatch.md index 55346503f8..e7d9547e76 100644 --- a/docs/dispatch.md +++ b/docs/dispatch.md @@ -499,6 +499,31 @@ The code in *hdf4var.c* does an *nc_get_vara()* on the HDF4 SD dataset. This is all that is needed for all the nc_get_* functions to work. +# Appendix A. Changing NC_DISPATCH_VERSION + +When new entries are added to the *struct NC_Dispatch* type +-- located in *include/netcdf_dispatch.h.in -- it is necessary to +do two things. +1. Bump the NC_DISPATCH_VERSION number +2. Modify the existing dispatch tables to include the new entries. +It if often the case that the new entries do not mean anything for +a given dispatch table. In that case, the new entries may be set to +some variant of *NC_RO_XXX* or *NC_NOTNC4_XXX* *NC_NOTNC3_XXX*. + +Modifying the dispatch version requires two steps: +1. Modify the version number in *netcdf-c/configure.ac*, and +2. Modify the version number in *netcdf-c/CMakeLists.txt*. + +The two should agree in value. + +### NC_DISPATCH_VERSION Incompatibility + +When dynamically adding a dispatch table +-- in nc_def_user_format (see libdispatch/dfile.c) -- +the version of the new table is compared with that of the built-in +NC_DISPATCH_VERSION; if they differ, then an error is returned from +that function. + # Point of Contact {#dispatch_poc} *Author*: Dennis Heimbigner