From 3fbbe847d87d35b3403882d31f787a0dc070ff05 Mon Sep 17 00:00:00 2001 From: Ed Hartnett Date: Fri, 3 Nov 2017 11:58:22 -0600 Subject: [PATCH] added v2 documentation --- libdispatch/dv2i.c | 564 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 544 insertions(+), 20 deletions(-) diff --git a/libdispatch/dv2i.c b/libdispatch/dv2i.c index 0110d35cc..951778990 100644 --- a/libdispatch/dv2i.c +++ b/libdispatch/dv2i.c @@ -13,6 +13,23 @@ See \ref copyright file for copying and redistribution conditions. #include #include "netcdf.h" #include "math.h" + +/** \defgroup v2_api The Version 2 API + +NetCDF's modern history began with the introduction of the V2 netCDF +API by Glenn Davis and Russ Rew in 1991. (The V1 API is lost to mists +of time.) + +The V2 API is still fully supported, but should not be used for new +development. + +All of the V2 functions have been reimplemented in terms of the V3 API +code; see the documentation for the related V3 functions to get more +documentation. + +The V2 API is tested in test directory nctest. +*/ + /* The subroutines in error.c emit no messages unless NC_VERBOSE bit * is on. They call exit() when NC_FATAL bit is on. */ int ncopts = (NC_FATAL | NC_VERBOSE) ; @@ -220,12 +237,29 @@ dimsizes(int ncid, int varid, size_t *sizes) return NC_NOERR; } +/** \ingroup v2_api -/* - * Retrieves the number of record variables, the record variable ids, and the - * record size of each record variable. If any pointer to info to be returned - * is null, the associated information is not returned. Returns -1 on error. - */ +Retrieves the number of record variables, the record variable ids, and the +record size of each record variable. If any pointer to info to be returned +is null, the associated information is not returned. Returns -1 on error. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 functions nc_inq_nvars(), +nc_inq_unlimdim(), nc_inq_dim(). + +\param ncid file ID +\param nrecvarsp pointer that will get the number of record variables +in the file. +\param recvarids pointer to array that will get the variable IDs of +all variables that use the record dimension. +\param recsizes pointer to array that will dimension size of the +record dimension for each variable. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad ncid. +\returns ::NC_ENOTVAR Invalid variable ID. +\returns ::NC_EINVAL Invalid input +*/ int nc_inq_rec( int ncid, @@ -273,13 +307,25 @@ nc_inq_rec( return NC_NOERR; } +/** \ingroup v2_api -/* - * Write one record's worth of data, except don't write to variables for which - * the address of the data to be written is NULL. Return -1 on error. This is - * the same as the ncrecput() in the library, except that can handle errors - * better. - */ +Write one record's worth of data, except don't write to variables for which +the address of the data to be written is NULL. Return -1 on error. This is +the same as the ncrecput() in the library, except that can handle errors +better. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_put_vara(). + +\param ncid file ID +\param recnum the record number to write. +\param datap pointer to one record's worth of data for all variables. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad ncid. +\returns ::NC_ENOTVAR Invalid variable ID. +\returns ::NC_EINVAL Invalid input +*/ int nc_put_rec( int ncid, @@ -320,12 +366,27 @@ nc_put_rec( } -/* - * Read one record's worth of data, except don't read from variables for which - * the address of the data to be read is null. Return -1 on error. This is - * the same as the ncrecget() in the library, except that can handle errors - * better. - */ +/** \ingroup v2_api + +Read one record's worth of data, except don't read from variables for which +the address of the data to be read is null. Return -1 on error. This is +the same as the ncrecget() in the library, except that can handle errors +better. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_get_vara(). + +\param ncid file ID +\param recnum the record number to read. +\param datap pointer memory to hold one record's worth of data for all +variables. + +\returns ::NC_NOERR No error. +\returns ::NC_EBADID Bad ncid. +\returns ::NC_ENOTVAR Invalid variable ID. +\returns ::NC_EINVAL Invalid input + +*/ int nc_get_rec( int ncid, @@ -364,8 +425,18 @@ nc_get_rec( return 0; } -/* - */ +/** \ingroup v2_api + +Show an error message and exit (based on ncopts). + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_strerror() + +\param routine_name +\param err error code +\param fmt pointer to a char array containing string format + +*/ void nc_advise(const char *routine_name, int err, const char *fmt,...) { @@ -399,6 +470,18 @@ nc_advise(const char *routine_name, int err, const char *fmt,...) /* End error handling */ +/** \ingroup v2_api + +Create a netCDF file. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_create(). + +\param path path and filename of the file to be created. +\param cmode see nc_create() for full discussion of the create mode. + +\returns the ncid of the created file. +*/ int nccreate(const char* path, int cmode) { @@ -412,7 +495,18 @@ nccreate(const char* path, int cmode) return ncid; } +/** \ingroup v2_api +Open a netCDF file. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_open(). + +\param path path and filename of the file to be created. +\param mode see nc_open() for full discussion of the open mode. + +\returns the ncid of the created file. +*/ int ncopen(const char *path, int mode) { @@ -426,7 +520,17 @@ ncopen(const char *path, int mode) return ncid; } +/** \ingroup v2_api +Put file in define mode. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_redef(). + +\param ncid file ID + +\returns 0 for success, -1 for failure. +*/ int ncredef(int ncid) { @@ -439,7 +543,17 @@ ncredef(int ncid) return 0; } +/** \ingroup v2_api +End define mode for file. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_enddef(). + +\param ncid file ID + +\returns 0 for success, -1 for failure. +*/ int ncendef(int ncid) { @@ -452,7 +566,17 @@ ncendef(int ncid) return 0; } +/** \ingroup v2_api +Close a file. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_close(). + +\param ncid file ID + +\returns 0 for success, -1 for failure. +*/ int ncclose(int ncid) { @@ -466,7 +590,22 @@ ncclose(int ncid) return 0; } +/** \ingroup v2_api +Learn about a file. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_inq(). + +\param ncid file ID +\param ndims pointer that will get number of dimensions. +\param nvars pointer that will get number of variables. +\param natts pointer that will get number of global attributes. +\param recdim pointer that will get dimension ID of record dimension, +or -1 if there is no record dimension. + +\returns 0 for success, -1 for failure. +*/ int ncinquire( int ncid, @@ -498,7 +637,17 @@ ncinquire( return ncid; } +/** \ingroup v2_api +Sync a file. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_sync(). + +\param ncid file ID + +\returns 0 for success, -1 for failure. +*/ int ncsync(int ncid) { @@ -512,7 +661,16 @@ ncsync(int ncid) return 0; } +/** \ingroup v2_api +Abort defining a file. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_abort(). + +\param ncid file ID +\returns 0 for success, -1 for failure. +*/ int ncabort(int ncid) { @@ -525,7 +683,20 @@ ncabort(int ncid) return 0; } +/** \ingroup v2_api +Define a dimension. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_def_dim(). + +\param ncid file ID +\param name name of dimension. +\param length length of the dimension, NC_UNLIMITED for a record +dimension. + +\returns dimid or -1 for failure. +*/ int ncdimdef( int ncid, @@ -549,7 +720,18 @@ ncdimdef( return dimid; } +/** \ingroup v2_api +Find dimension ID from name. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_inq_dimid(). + +\param ncid file ID +\param name name of dimension. + +\returns dimid or -1 for failure. +*/ int ncdimid(int ncid, const char* name) { @@ -563,7 +745,20 @@ ncdimid(int ncid, const char* name) return dimid; } +/** \ingroup v2_api +Learn about a dimension. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_inq_dim(). + +\param ncid file ID +\param dimid the dimension ID to learn about +\param name pointer that will get name of dimension. +\param length pointer that will get length of dimension. + +\returns dimid or -1 for failure. +*/ int ncdiminq( int ncid, @@ -588,7 +783,19 @@ ncdiminq( return dimid; } +/** \ingroup v2_api +Rename a dimension. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_rename_dim(). + +\param ncid file ID +\param dimid the dimension ID. +\param name the new name. + +\returns dimid or -1 for failure. +*/ int ncdimrename( int ncid, @@ -605,7 +812,21 @@ ncdimrename( return dimid; } +/** \ingroup v2_api +Define a variable. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_def_var(). + +\param ncid file ID +\param name the name of the variable. +\param datatype the data type of the variable. +\param ndims the number of dimensions. +\param dim array of dimension IDs. + +\returns varid or -1 for failure. +*/ int ncvardef( int ncid, @@ -625,7 +846,18 @@ ncvardef( return varid; } +/** \ingroup v2_api +Learn a variable ID from the name. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_inq_varid(). + +\param ncid file ID +\param name the name of the variable. + +\returns varid or -1 for failure. +*/ int ncvarid( int ncid, @@ -642,7 +874,23 @@ ncvarid( return varid; } +/** \ingroup v2_api +Learn about a variable. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_inq_var(). + +\param ncid file ID +\param varid the variable ID. +\param name pointer to array of char that will get name of variable. +\param datatype pointer that will get variable data type. +\param ndims pointer that will get number of dimensions. +\param dim pointer to array that will get dimension IDs. +\param natts pointer that will get number of variable attributes. + +\returns varid or -1 for failure. +*/ int ncvarinq( int ncid, @@ -674,7 +922,20 @@ ncvarinq( return varid; } +/** \ingroup v2_api +Write 1 data value. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_put_var1(). + +\param ncid file ID +\param varid the variable ID. +\param index pointer to array of index values. +\param value pointer to data. + +\returns 0 for success or -1 for failure. +*/ int ncvarput1( int ncid, @@ -698,7 +959,20 @@ ncvarput1( return 0; } +/** \ingroup v2_api +Read 1 data value. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_get_var1(). + +\param ncid file ID +\param varid the variable ID. +\param index pointer to array of index values. +\param value pointer that will get data. + +\returns 0 for success or -1 for failure. +*/ int ncvarget1( int ncid, @@ -722,7 +996,21 @@ ncvarget1( return 0; } +/** \ingroup v2_api +Write some data. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_put_vara(). + +\param ncid file ID +\param varid the variable ID. +\param start pointer to array of start values. +\param count pointer to array of count values. +\param value pointer to data. + +\returns 0 for success or -1 for failure. +*/ int ncvarput( int ncid, @@ -750,7 +1038,21 @@ ncvarput( return 0; } +/** \ingroup v2_api +Read some data. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_get_vara(). + +\param ncid file ID +\param varid the variable ID. +\param start pointer to array of start values. +\param count pointer to array of count values. +\param value pointer to data. + +\returns 0 for success or -1 for failure. +*/ int ncvarget( int ncid, @@ -778,7 +1080,22 @@ ncvarget( return 0; } +/** \ingroup v2_api +Write strided data. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_put_vars(). + +\param ncid file ID +\param varid the variable ID. +\param start pointer to array of start values. +\param count pointer to array of count values. +\param stride pointer to array of stride values. +\param value pointer to data. + +\returns 0 for success or -1 for failure. +*/ int ncvarputs( int ncid, @@ -816,7 +1133,22 @@ ncvarputs( } } +/** \ingroup v2_api +Read strided data. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_get_vars(). + +\param ncid file ID +\param varid the variable ID. +\param start pointer to array of start values. +\param count pointer to array of count values. +\param stride pointer to array of stride values. +\param value pointer to data. + +\returns 0 for success or -1 for failure. +*/ int ncvargets( int ncid, @@ -853,7 +1185,23 @@ ncvargets( } } +/** \ingroup v2_api +Write mapped data. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_get_varm(). + +\param ncid file ID +\param varid the variable ID. +\param start pointer to array of start values. +\param count pointer to array of count values. +\param stride pointer to array of stride values. +\param map pointer to array of map values. +\param value pointer to data. + +\returns 0 for success or -1 for failure. +*/ int ncvarputg( int ncid, @@ -910,7 +1258,23 @@ ncvarputg( } } +/** \ingroup v2_api +Read mapped data. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_get_varm(). + +\param ncid file ID +\param varid the variable ID. +\param start pointer to array of start values. +\param count pointer to array of count values. +\param stride pointer to array of stride values. +\param map pointer to array of map values. +\param value pointer to data. + +\returns 0 for success or -1 for failure. +*/ int ncvargetg( int ncid, @@ -967,7 +1331,19 @@ ncvargetg( } } +/** \ingroup v2_api +Rename a variable. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_rename_var(). + +\param ncid file ID +\param varid the variable ID. +\param name the new name. + +\returns varid or -1 for failure. +*/ int ncvarrename( int ncid, @@ -984,7 +1360,22 @@ ncvarrename( return varid; } +/** \ingroup v2_api +Write an attribute. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_put_att_int(), etc. + +\param ncid file ID +\param varid the variable ID or NC_GLOBAL. +\param name the name of the attribute. +\param datatype the type of the attribute. +\param len the length of the attribute. +\param value the attribute value. + +\returns dimid or -1 for failure. +*/ int ncattput( int ncid, @@ -1004,7 +1395,22 @@ ncattput( return 0; } +/** \ingroup v2_api +Learn about an attribute. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_inq_att(). + +\param ncid file ID +\param varid the variable ID. +\param name the name of the attribute. +\param datatype pointer that will get data type. +\param len pointer that will get length. + +\returns 1 for success or -1 for failure. (That's a delightful +artifact of a by-gone era of C programming, isn't it?) +*/ int ncattinq( int ncid, @@ -1028,10 +1434,22 @@ ncattinq( *len = (int) ll; return 1; - } +/** \ingroup v2_api +Read an attribute. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_get_att_int(), etc. + +\param ncid file ID. +\param varid the variable ID or NC_GLOBAL. +\param name the name of the attribute. +\param value pointer that will get the attribute data. + +\returns 1 for success or -1 for failure. +*/ int ncattget( int ncid, @@ -1049,7 +1467,21 @@ ncattget( return 1; } +/** \ingroup v2_api +Copy an attribute. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_get_att_int(), etc. + +\param ncid_in file ID to copy from. +\param varid_in the variable ID or NC_GLOBAL to copy from. +\param name the name of the attribute. +\param ncid_out file ID to copy to. +\param varid_out the variable ID or NC_GLOBAL to copy to. + +\returns 0 for success or -1 for failure. +*/ int ncattcopy( int ncid_in, @@ -1068,7 +1500,20 @@ ncattcopy( return 0; } +/** \ingroup v2_api +Learn attribute name from its number. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_inq_attname(). + +\param ncid file ID +\param varid the variable ID. +\param attnum the number of the attribute. +\param name the name of the attribute. + +\returns attnum for success or -1 for failure. +*/ int ncattname( int ncid, @@ -1086,7 +1531,20 @@ ncattname( return attnum; } +/** \ingroup v2_api +Rename an attribute. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_rename_att(). + +\param ncid file ID +\param varid the variable ID. +\param name the attribute name. +\param newname the new name. + +\returns 1 for success or -1 for failure. +*/ int ncattrename( int ncid, @@ -1104,7 +1562,19 @@ ncattrename( return 1; } +/** \ingroup v2_api +Delete an attribute. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_delete_att(). + +\param ncid file ID +\param varid the variable ID. +\param name the attribute name. + +\returns 1 for success or -1 for failure. +*/ int ncattdel( int ncid, @@ -1125,6 +1595,18 @@ ncattdel( #ifndef NO_NETCDF_2 +/** \ingroup v2_api + +Set the fill mode. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_set_fill(). + +\param ncid file ID +\param fillmode NC_FILL or NC_NOFILL. + +\returns oldmode for success or -1 for failure. +*/ int ncsetfill( int ncid, @@ -1141,7 +1623,20 @@ ncsetfill( return oldmode; } +/** \ingroup v2_api +Learn record variables and the lengths of the record dimension. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 functions nc_inq_var()/nc_inq_dim(). + +\param ncid file ID +\param nrecvars pointer that will get number of record variables. +\param recvarids pointer that will get array of record variable IDs. +\param recsizes pointer that will get array of record dimension length. + +\returns oldmode for success or -1 for failure. +*/ int ncrecinq( int ncid, @@ -1183,7 +1678,22 @@ ncrecinq( return (int) nrv; } +/** \ingroup v2_api +Read one record's worth of data, except don't read from variables for which +the address of the data to be read is null. Return -1 on error. This is +the same as the nc_get_rec(), with poorer error handling. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_get_vara(). + +\param ncid file ID +\param recnum the record number to read. +\param datap pointer memory to hold one record's worth of data for all +variables. + +\returns 0 for success, -1 for error. +*/ int ncrecget( int ncid, @@ -1200,7 +1710,21 @@ ncrecget( return 0; } +/** \ingroup v2_api +Write one record's worth of data, except don't write to variables for which +the address of the data to be written is NULL. Return -1 on error. This is +the same as the nc_put_rec(), but with poorer error handling. + +This is part of the legacy V2 API of netCDF. New code should be +written with the V3 API. See V3 function nc_put_vara(). + +\param ncid file ID +\param recnum the record number to write. +\param datap pointer to one record's worth of data for all variables. + +\returns 0 for success, -1 for error. +*/ int ncrecput( int ncid,