diff --git a/doc/source/c_api.txt b/doc/source/c_api.txt index be71cb9d2dc..e9d3ed3f62e 100644 --- a/doc/source/c_api.txt +++ b/doc/source/c_api.txt @@ -32,8 +32,14 @@ - \ref PIO_def_var_c - \ref PIO_put_att_c \subsection putget_c Reading/Writing Data + - \ref PIO_get_vara_c - \ref PIO_get_var_c + - \ref PIO_get_var1_c + - \ref PIO_get_vars_c + - \ref PIO_put_vara_c - \ref PIO_put_var_c + - \ref PIO_put_var1_c + - \ref PIO_put_vars_c \subsection inqnc_c Learn about Files and Metadata - \ref PIO_inq_c - \ref PIO_get_att_c diff --git a/src/clib/pio_get_nc.c b/src/clib/pio_get_nc.c index 7b05fe5f607..589a3de11e2 100644 --- a/src/clib/pio_get_nc.c +++ b/src/clib/pio_get_nc.c @@ -12,8 +12,8 @@ #include /** - * @addtogroup PIO_get_var_c Read Data - * Read data from a variable in C. + * @addtogroup PIO_get_vars_c Read Strided Arrays + * Read strided arrays of data from a variable in C. * @{ */ @@ -345,6 +345,45 @@ int PIOc_get_vars_longlong(int ncid, int varid, const PIO_Offset *start, return PIOc_get_vars_tc(ncid, varid, start, count, stride, NC_INT64, buf); } +/** + * Get strided, muti-dimensional subset of a variable of the same type + * as the variable in the file. + * + * This routine is called collectively by all tasks in the + * communicator ios.union_comm. + * + * @param ncid identifies the netCDF file + * @param varid the variable ID number + * @param start an array of start indicies (must have same number of + * entries as variable has dimensions). If NULL, indices of 0 will be + * used. + * @param count an array of counts (must have same number of entries + * as variable has dimensions). If NULL, counts matching the size of + * the variable will be used. + * @param stride an array of strides (must have same number of + * entries as variable has dimensions). If NULL, strides of 1 will be + * used. + * @param buf pointer that will get the data. + * @return PIO_NOERR on success, error code otherwise. + * @author Ed Hartnett + */ +int PIOc_get_vars(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count, + const PIO_Offset *stride, void *buf) +{ + return PIOc_get_vars_tc(ncid, varid, start, count, stride, NC_NAT, buf); +} + +/** + * @} + */ + +/** + * @addtogroup PIO_get_vara_c Read Arrays + * Read arrays of data from a variable in C, specifying start and + * count arrays. + * @{ + */ + /** * Get a muti-dimensional subset of a text variable. * @@ -635,6 +674,41 @@ int PIOc_get_vara_longlong(int ncid, int varid, const PIO_Offset *start, return PIOc_get_vars_tc(ncid, varid, start, count, NULL, NC_INT64, buf); } +/** + * Get a muti-dimensional subset of a variable the same type + * as the variable in the file. + * + * This routine is called collectively by all tasks in the + * communicator ios.union_comm. + * + * @param ncid identifies the netCDF file + * @param varid the variable ID number + * @param start an array of start indicies (must have same number of + * entries as variable has dimensions). If NULL, indices of 0 will be + * used. + * @param count an array of counts (must have same number of entries + * as variable has dimensions). If NULL, counts matching the size of + * the variable will be used. + * @param buf pointer that will get the data. + * @return PIO_NOERR on success, error code otherwise. + * @author Ed Hartnett + */ +int PIOc_get_vara(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count, + void *buf) +{ + return PIOc_get_vars_tc(ncid, varid, start, count, NULL, NC_NAT, buf); +} + +/** + * @} + */ + +/** + * @addtogroup PIO_get_var_c Read Entire Variable + * Read the entire variable at one time into an array in C. + * @{ + */ + /** * Get all data of a text variable. * @@ -839,6 +913,34 @@ int PIOc_get_var_longlong(int ncid, int varid, long long *buf) return PIOc_get_var_tc(ncid, varid, NC_INT64, buf); } +/** + * Get all data from a variable the same type as the variable in the + * file. + * + * This routine is called collectively by all tasks in the + * communicator ios.union_comm. + * + * @param ncid identifies the netCDF file + * @param varid the variable ID number + * @param buf pointer that will get the data. + * @return PIO_NOERR on success, error code otherwise. + * @author Ed Hartnett + */ +int PIOc_get_var(int ncid, int varid, void *buf) +{ + return PIOc_get_var_tc(ncid, varid, NC_NAT, buf); +} + +/** + * @} + */ + +/** + * @addtogroup PIO_get_var1_c Read One Value + * Read one value from a variable in C. + * @{ + */ + /** * Get one value of a text variable. * @@ -1083,24 +1185,6 @@ int PIOc_get_var1_longlong(int ncid, int varid, const PIO_Offset *index, return PIOc_get_var1_tc(ncid, varid, index, NC_INT64, buf); } -/** - * Get all data from a variable the same type as the variable in the - * file. - * - * This routine is called collectively by all tasks in the - * communicator ios.union_comm. - * - * @param ncid identifies the netCDF file - * @param varid the variable ID number - * @param buf pointer that will get the data. - * @return PIO_NOERR on success, error code otherwise. - * @author Ed Hartnett - */ -int PIOc_get_var(int ncid, int varid, void *buf) -{ - return PIOc_get_var_tc(ncid, varid, NC_NAT, buf); -} - /** * Get one value from a variable the same type as the variable in the * file. @@ -1122,59 +1206,6 @@ int PIOc_get_var1(int ncid, int varid, const PIO_Offset *index, void *buf) return PIOc_get_var1_tc(ncid, varid, index, NC_NAT, buf); } -/** - * Get a muti-dimensional subset of a variable the same type - * as the variable in the file. - * - * This routine is called collectively by all tasks in the - * communicator ios.union_comm. - * - * @param ncid identifies the netCDF file - * @param varid the variable ID number - * @param start an array of start indicies (must have same number of - * entries as variable has dimensions). If NULL, indices of 0 will be - * used. - * @param count an array of counts (must have same number of entries - * as variable has dimensions). If NULL, counts matching the size of - * the variable will be used. - * @param buf pointer that will get the data. - * @return PIO_NOERR on success, error code otherwise. - * @author Ed Hartnett - */ -int PIOc_get_vara(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count, - void *buf) -{ - return PIOc_get_vars_tc(ncid, varid, start, count, NULL, NC_NAT, buf); -} - -/** - * Get strided, muti-dimensional subset of a variable of the same type - * as the variable in the file. - * - * This routine is called collectively by all tasks in the - * communicator ios.union_comm. - * - * @param ncid identifies the netCDF file - * @param varid the variable ID number - * @param start an array of start indicies (must have same number of - * entries as variable has dimensions). If NULL, indices of 0 will be - * used. - * @param count an array of counts (must have same number of entries - * as variable has dimensions). If NULL, counts matching the size of - * the variable will be used. - * @param stride an array of strides (must have same number of - * entries as variable has dimensions). If NULL, strides of 1 will be - * used. - * @param buf pointer that will get the data. - * @return PIO_NOERR on success, error code otherwise. - * @author Ed Hartnett - */ -int PIOc_get_vars(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count, - const PIO_Offset *stride, void *buf) -{ - return PIOc_get_vars_tc(ncid, varid, start, count, stride, NC_NAT, buf); -} - /** * @} */ diff --git a/src/clib/pio_get_vard.c b/src/clib/pio_get_vard.c index cccead9bc62..e0decf92dca 100644 --- a/src/clib/pio_get_vard.c +++ b/src/clib/pio_get_vard.c @@ -12,8 +12,8 @@ #include /** - * @addtogroup PIO_get_var_c Read Data - * Read data from a variable in C. + * @addtogroup PIO_read_darray_c + * Read distributed arrays from a variable in C. * @{ */ diff --git a/src/clib/pio_put_nc.c b/src/clib/pio_put_nc.c index 76aea931731..d6f87ae08f9 100644 --- a/src/clib/pio_put_nc.c +++ b/src/clib/pio_put_nc.c @@ -11,8 +11,8 @@ #include /** - * @addtogroup PIO_put_var_c Write Data - * Write data to a Variable in C. + * @addtogroup PIO_put_vars_c Write Strided Arrays + * Write strided arrays of data to a Variable in C. * @{ */ @@ -358,6 +358,43 @@ PIOc_put_vars_ulonglong(int ncid, int varid, const PIO_Offset *start, const PIO_ return PIOc_put_vars_tc(ncid, varid, start, count, stride, NC_UINT64, op); } +/** + * Write strided, muti-dimensional subset of a variable of any type. + * + * This routine is called collectively by all tasks in the + * communicator ios.union_comm. + * + * @param ncid identifies the netCDF file + * @param varid the variable ID number + * @param start an array of start indicies (must have same number of + * entries as variable has dimensions). If NULL, indices of 0 will be + * used. + * @param count an array of counts (must have same number of entries + * as variable has dimensions). If NULL, counts matching the size of + * the variable will be used. + * @param stride an array of strides (must have same number of + * entries as variable has dimensions). If NULL, strides of 1 will be + * used. + * @param op pointer to the data to be written. + * @return PIO_NOERR on success, error code otherwise. + * @author Ed Hartnett + */ +int +PIOc_put_vars(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count, + const PIO_Offset *stride, const void *op) +{ + return PIOc_put_vars_tc(ncid, varid, start, count, stride, NC_NAT, op); +} + +/** + * @} + */ +/** + * @addtogroup PIO_put_var1_c Write One Value + * Write one value to a variable in C. + * @{ + */ + /** * Put one value from an text variable. * @@ -618,6 +655,37 @@ PIOc_put_var1_longlong(int ncid, int varid, const PIO_Offset *index, return PIOc_put_var1_tc(ncid, varid, index, NC_INT64, op); } +/** + * Put one value from a variable of any type. + * + * This routine is called collectively by all tasks in the + * communicator ios.union_comm. + * + * @param ncid identifies the netCDF file + * @param varid the variable ID number + * @param index an array of indicies where the data value will be + * written (must have same number of entries as variable has + * dimensions). If NULL, indices of 0 will be used. + * @param op pointer to the data to be written. + * @return PIO_NOERR on success, error code otherwise. + * @author Ed Hartnett + */ +int +PIOc_put_var1(int ncid, int varid, const PIO_Offset *index, const void *op) +{ + return PIOc_put_var1_tc(ncid, varid, index, NC_NAT, op); +} + +/** + * @} + */ +/** + * @addtogroup PIO_put_vara_c Write Arrays + * Write arrays of data to a Variable in C, specifying start and count + * arrays. + * @{ + */ + /** * Put muti-dimensional subset of a text variable. * @@ -843,6 +911,31 @@ PIOc_put_vara_float(int ncid, int varid, const PIO_Offset *start, return PIOc_put_vars_float(ncid, varid, start, count, NULL, op); } +/** + * Put muti-dimensional subset of a 64-bit integer variable. + * + * This routine is called collectively by all tasks in the + * communicator ios.union_comm. + * + * @param ncid identifies the netCDF file + * @param varid the variable ID number + * @param start an array of start indicies (must have same number of + * entries as variable has dimensions). If NULL, indices of 0 will be + * used. + * @param count an array of counts (must have same number of entries + * as variable has dimensions). If NULL, counts matching the size of + * the variable will be used. + * @param op pointer to the data to be written. + * @return PIO_NOERR on success, error code otherwise. + * @author Ed Hartnett + */ +int +PIOc_put_vara_double(int ncid, int varid, const PIO_Offset *start, + const PIO_Offset *count, const double *op) +{ + return PIOc_put_vars_double(ncid, varid, start, count, NULL, op); +} + /** * Put muti-dimensional subset of an unsigned 64-bit integer variable. * @@ -894,7 +987,7 @@ PIOc_put_vara_longlong(int ncid, int varid, const PIO_Offset *start, } /** - * Put muti-dimensional subset of a 64-bit integer variable. + * Put muti-dimensional subset of a variable of any type. * * This routine is called collectively by all tasks in the * communicator ios.union_comm. @@ -912,12 +1005,21 @@ PIOc_put_vara_longlong(int ncid, int varid, const PIO_Offset *start, * @author Ed Hartnett */ int -PIOc_put_vara_double(int ncid, int varid, const PIO_Offset *start, - const PIO_Offset *count, const double *op) +PIOc_put_vara(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count, + const void *op) { - return PIOc_put_vars_double(ncid, varid, start, count, NULL, op); + return PIOc_put_vars_tc(ncid, varid, start, count, NULL, NC_NAT, op); } +/** + * @} + */ +/** + * @addtogroup PIO_put_var_c Write Entire Variable + * Write the entire variable in C. + * @{ + */ + /** * Put all data to a text variable. * @@ -1152,80 +1254,6 @@ PIOc_put_var(int ncid, int varid, const void *op) return PIOc_put_var_tc(ncid, varid, NC_NAT, op); } -/** - * Put one value from a variable of any type. - * - * This routine is called collectively by all tasks in the - * communicator ios.union_comm. - * - * @param ncid identifies the netCDF file - * @param varid the variable ID number - * @param index an array of indicies where the data value will be - * written (must have same number of entries as variable has - * dimensions). If NULL, indices of 0 will be used. - * @param op pointer to the data to be written. - * @return PIO_NOERR on success, error code otherwise. - * @author Ed Hartnett - */ -int -PIOc_put_var1(int ncid, int varid, const PIO_Offset *index, const void *op) -{ - return PIOc_put_var1_tc(ncid, varid, index, NC_NAT, op); -} - -/** - * Put muti-dimensional subset of a variable of any type. - * - * This routine is called collectively by all tasks in the - * communicator ios.union_comm. - * - * @param ncid identifies the netCDF file - * @param varid the variable ID number - * @param start an array of start indicies (must have same number of - * entries as variable has dimensions). If NULL, indices of 0 will be - * used. - * @param count an array of counts (must have same number of entries - * as variable has dimensions). If NULL, counts matching the size of - * the variable will be used. - * @param op pointer to the data to be written. - * @return PIO_NOERR on success, error code otherwise. - * @author Ed Hartnett - */ -int -PIOc_put_vara(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count, - const void *op) -{ - return PIOc_put_vars_tc(ncid, varid, start, count, NULL, NC_NAT, op); -} - -/** - * Write strided, muti-dimensional subset of a variable of any type. - * - * This routine is called collectively by all tasks in the - * communicator ios.union_comm. - * - * @param ncid identifies the netCDF file - * @param varid the variable ID number - * @param start an array of start indicies (must have same number of - * entries as variable has dimensions). If NULL, indices of 0 will be - * used. - * @param count an array of counts (must have same number of entries - * as variable has dimensions). If NULL, counts matching the size of - * the variable will be used. - * @param stride an array of strides (must have same number of - * entries as variable has dimensions). If NULL, strides of 1 will be - * used. - * @param op pointer to the data to be written. - * @return PIO_NOERR on success, error code otherwise. - * @author Ed Hartnett - */ -int -PIOc_put_vars(int ncid, int varid, const PIO_Offset *start, const PIO_Offset *count, - const PIO_Offset *stride, const void *op) -{ - return PIOc_put_vars_tc(ncid, varid, start, count, stride, NC_NAT, op); -} - /** * @} */ diff --git a/src/clib/pio_put_vard.c b/src/clib/pio_put_vard.c index ac30207727f..866fd40e84c 100644 --- a/src/clib/pio_put_vard.c +++ b/src/clib/pio_put_vard.c @@ -11,8 +11,8 @@ #include /** - * @addtogroup PIO_put_var_c Write Data - * Write data to a Variable in C. + * @addtogroup PIO_write_darray_c + * Write distributed arrays to a Variable in C. * @{ */