mirror of
https://github.com/Unidata/netcdf-c.git
synced 2024-11-21 03:13:42 +08:00
Merge pull request #652 from NetCDF-World-Domination-Council/ejh_all_docs
Ejh all documentation PRs combined
This commit is contained in:
Ward Fisher
GitHub
commit
c7365a5183
@ -140,6 +140,7 @@ else
|
||||
AC_SUBST([DOXYGEN_HEADER_FILE], [])
|
||||
AC_SUBST([DOXYGEN_SEARCHENGINE], ["YES"])
|
||||
fi
|
||||
AC_SUBST([DOXYGEN_SERVER_BASED_SEARCH], ["NO"])
|
||||
|
||||
AC_ARG_ENABLE([doxygen-pdf-output],
|
||||
[AS_HELP_STRING([--enable-doxygen-pdf-output],
|
||||
|
||||
@ -1866,8 +1866,8 @@ checking be used for all netCDF function calls.
|
||||
----------
|
||||
|
||||
|
||||
CMake {#cmake_faq}
|
||||
==============================================
|
||||
CMake-Related Frequently Asked Questions {#cmake_faq}
|
||||
========================================
|
||||
|
||||
Below are a list of commonly-asked questions regarding NetCDF and CMake.
|
||||
|
||||
|
||||
@ -4,14 +4,12 @@
|
||||
|
||||
|
||||
# These files will be included with the dist.
|
||||
EXTRA_DIST = netcdf.m4 DoxygenLayout.xml Doxyfile.in footer.html \
|
||||
mainpage.dox tutorial.dox \
|
||||
guide.dox types.dox cdl.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 cmake_faq.md credits.md \
|
||||
auth.md obsolete/fan_utils.html bestpractices.md filters.md
|
||||
EXTRA_DIST = netcdf.m4 DoxygenLayout.xml Doxyfile.in footer.html \
|
||||
mainpage.dox tutorial.dox guide.dox types.dox cdl.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 \
|
||||
obsolete/fan_utils.html bestpractices.md filters.md
|
||||
|
||||
# Turn off parallel builds in this directory.
|
||||
.NOTPARALLEL:
|
||||
|
||||
@ -1,69 +0,0 @@
|
||||
CMake-Related Frequently-Asked-Questions (FAQ) {#cmake_faq}
|
||||
==============================================
|
||||
|
||||
Below are a list of commonly-asked questions regarding NetCDF and CMake.
|
||||
|
||||
## How can I see the options available to CMake? {#listoptions}
|
||||
|
||||
$ cmake [path to source tree] -L - This will show the basic options.
|
||||
$ cmake [path to source tree] -LA - This will show the basic and advanced options.
|
||||
|
||||
|
||||
## How do I specify how to build a shared or static library? {#sharedstatic}
|
||||
|
||||
This is controlled with the internal `cmake` option, `BUILD_SHARED_LIBS`.
|
||||
|
||||
$ cmake [Source Directory] -DBUILD_SHARED_LIBS=[ON/OFF]
|
||||
|
||||
|
||||
## Can I build both shared and static libraries at the same time with cmake? {#sharedstaticboth}
|
||||
|
||||
Not at this time; it is required to instead build first one version, and then the other, if you need both.
|
||||
|
||||
## What if I want to link against multiple libraries in a non-standard location? {#nonstdloc}
|
||||
|
||||
You can specify the path to search when looking for dependencies and header files using the `CMAKE_PREFIX_PATH` variable:
|
||||
|
||||
* Windows:
|
||||
|
||||
$ cmake [Source Directory] -DCMAKE_PREFIX_PATH=c:\shared\libs\
|
||||
|
||||
|
||||
* Linux/Unix/OSX:
|
||||
|
||||
$ cmake [Source Directory] -DCMAKE_PREFIX_PATH=/usr/custom_library_locations/
|
||||
|
||||
|
||||
## How can I specify linking against a particular library? {#partlib}
|
||||
|
||||
It depends on the library. To specify a custom `ZLib`, for example, you would do the following:
|
||||
|
||||
$ cmake [Source Directory] -DZLIB_LIBRARY=/path/to/my/zlib.lib
|
||||
|
||||
|
||||
`HDF5` is more complex, since it requires both the `hdf5` and `hdf5_hl` libraries. You would specify custom `HDF5` libraries as follows:
|
||||
|
||||
$ cmake [Source Directory] -DHDF5_LIB=/path/to/hdf5.lib \
|
||||
-DHDF5_HL_LIB=/path/to/hdf5_hl.lib \
|
||||
-DHDF5_INCLUDE_DIR=/path/to/hdf5/include
|
||||
|
||||
|
||||
Alternatively, you may specify:
|
||||
|
||||
$ cmake [Source Directory] \
|
||||
-DHDF5_LIBRARIES="/path/to/hdf5.lib;/path/to/hdf5_hl.lib" \
|
||||
-DHDF5_INCLUDE_DIR=/path/to/hdf5/include/
|
||||
|
||||
|
||||
## How can I specify a Parallel Build using HDF5 {#parallelhdf}
|
||||
|
||||
If cmake is having problems finding the parallel `HDF5` install, you can specify the location manually:
|
||||
|
||||
|
||||
$ cmake [Source Directory] -DENABLE_PARALLEL=ON \
|
||||
-DHDF5_LIB=/usr/lib64/openmpi/lib/libhdf5.so \
|
||||
-DHDF5_HL_LIB=/usr/lib64/openmpi/lib/libhdf5.hl.so \
|
||||
-DHDF5_INCLUDE_DIR=/usr/include/openmpi-x86_64 \
|
||||
|
||||
|
||||
You will, of course, need to use the location of the libraries specific to your development environment.
|
||||
@ -417,13 +417,13 @@ The output of the configuration step is a project file based on the appropriate
|
||||
|
||||
| **Option** | **Autotools** | **CMake** |
|
||||
| :------- | :---- | :----- |
|
||||
Specify Install Location | --prefix=PREFIX | -D"CMAKE\_INSTALL\_PREFIX=PREFIX"
|
||||
Enable/Disable netCDF-4 | --enable-netcdf-4<br>--disable-netcdf-4 | -D"ENABLE\_NETCDF\_4=ON" <br> -D"ENABLE\_NETCDF\_4=OFF"
|
||||
Enable/Disable DAP | --enable-dap <br> --disable-dap | -D"ENABLE\_DAP=ON" <br> -D"ENABLE\_DAP=OFF"
|
||||
Enable/Disable Utilities | --enable-utilities <br> --disable-utilities | -D"BUILD\_UTILITIES=ON" <br> -D"BUILD\_UTILITIES=OFF"
|
||||
Specify shared/Static Libraries | --enable-shared <br> --enable-static | -D"BUILD\_SHARED\_LIBS=ON" <br> -D"BUILD\_SHARED\_LIBS=OFF"
|
||||
Enable/Disable Tests | --enable-testsets <br> --disable-testsets | -D"ENABLE\_TESTS=ON" <br> -D"ENABLE\_TESTS=OFF"
|
||||
Specify a custom library location | Use *CFLAGS* and *LDFLAGS* | -D"CMAKE\_PREFIX\_PATH=/usr/custom_libs/"
|
||||
Specify Install Location | --prefix=PREFIX | -D"CMAKE_INSTALL_PREFIX=PREFIX"
|
||||
Enable/Disable netCDF-4 | --enable-netcdf-4<br>--disable-netcdf-4 | -D"ENABLE_NETCDF_4=ON" <br> -D"ENABLE_NETCDF_4=OFF"
|
||||
Enable/Disable DAP | --enable-dap <br> --disable-dap | -D"ENABLE_DAP=ON" <br> -D"ENABLE_DAP=OFF"
|
||||
Enable/Disable Utilities | --enable-utilities <br> --disable-utilities | -D"BUILD_UTILITIES=ON" <br> -D"BUILD_UTILITIES=OFF"
|
||||
Specify shared/Static Libraries | --enable-shared <br> --enable-static | -D"BUILD_SHARED_LIBS=ON" <br> -D"BUILD_SHARED_LIBS=OFF"
|
||||
Enable/Disable Tests | --enable-testsets <br> --disable-testsets | -D"ENABLE_TESTS=ON" <br> -D"ENABLE_TESTS=OFF"
|
||||
Specify a custom library location | Use *CFLAGS* and *LDFLAGS* | -D"CMAKE_PREFIX_PATH=/usr/custom_libs/"
|
||||
|
||||
A full list of *basic* options can be found by invoking `cmake [Source Directory] -L`. To enable a list of *basic* and *advanced* options, one would invoke `cmake [Source Directory] -LA`.
|
||||
|
||||
@ -473,4 +473,5 @@ or
|
||||
|
||||
## See Also {#cmake_see_also}
|
||||
|
||||
For further information regarding netCDF and CMake, see \ref cmake_faq
|
||||
For further information regarding netCDF and CMake, see \ref cmake_faq.
|
||||
|
||||
|
||||
@ -7,8 +7,8 @@
|
||||
*
|
||||
* This header file is for the parallel I/O functions of netCDF.
|
||||
*
|
||||
* \author Ed Hartnett
|
||||
*/
|
||||
/* "$Id: netcdf_par.h,v 1.1 2010/06/01 15:46:49 ed Exp $" */
|
||||
|
||||
#ifndef NETCDF_PAR_H
|
||||
#define NETCDF_PAR_H 1
|
||||
@ -19,8 +19,9 @@
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/* Use these with nc_var_par_access(). */
|
||||
/** Use with nc_var_par_access() to set parallel access to independent. */
|
||||
#define NC_INDEPENDENT 0
|
||||
/** Use with nc_var_par_access() to set parallel access to collective. */
|
||||
#define NC_COLLECTIVE 1
|
||||
|
||||
/* Create a file and enable parallel I/O. */
|
||||
|
||||
@ -1,10 +1,9 @@
|
||||
/** \file
|
||||
Attribute functions
|
||||
Copyright 2010 University Corporation for Atmospheric
|
||||
Research/Unidata. See \ref copyright file for more info.
|
||||
|
||||
These functions read and write attributes.
|
||||
|
||||
Copyright 2010 University Corporation for Atmospheric
|
||||
Research/Unidata. See \ref copyright file for more info. */
|
||||
*/
|
||||
|
||||
#include "ncdispatch.h"
|
||||
|
||||
@ -16,11 +15,11 @@ Attributes hold metadata about data and files.
|
||||
|
||||
Attributes may be associated with a netCDF variable to specify such
|
||||
properties as units, special values, maximum and minimum valid values,
|
||||
scaling factors, and offsets.
|
||||
scaling factors, and offsets.
|
||||
|
||||
Attributes for a netCDF dataset are defined when the dataset is first
|
||||
created, while the netCDF dataset is in define mode. Additional
|
||||
attributes may be added later by reentering define mode.
|
||||
attributes may be added later by reentering define mode.
|
||||
|
||||
A netCDF attribute has a netCDF variable to which it is assigned, a
|
||||
name, a type, a length, and a sequence of one or more values.
|
||||
@ -38,9 +37,10 @@ more space than the attribute as originally defined.
|
||||
|
||||
It is also possible to have attributes that are not associated with
|
||||
any variable. These are called global attributes and are identified by
|
||||
using ::NC_GLOBAL as a variable pseudo-ID. Global attributes are usually
|
||||
related to the netCDF dataset as a whole and may be used for purposes
|
||||
such as providing a title or processing history for a netCDF dataset.
|
||||
using ::NC_GLOBAL as a variable pseudo-ID. Global attributes are
|
||||
usually related to the netCDF dataset as a whole and may be used for
|
||||
purposes such as providing a title or processing history for a netCDF
|
||||
dataset.
|
||||
|
||||
Operations supported on attributes are:
|
||||
- Create an attribute, given its variable ID, name, data type, length,
|
||||
@ -102,6 +102,20 @@ dataset named foo.nc:
|
||||
status = nc_rename_att(ncid, rh_id, "units", "Units");
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
\endcode
|
||||
|
||||
\returns NC_NOERR No error.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Bad varid.
|
||||
\returns ::NC_EBADNAME Bad name.
|
||||
\returns ::NC_EMAXNAME New name too long.
|
||||
\returns ::NC_EINVAL Name or new name not provided.
|
||||
\returns ::NC_ENAMEINUSE Name already in use.
|
||||
\returns ::NC_EPERM File was opened read only.
|
||||
\returns ::NC_ENOTINDEFINE File is not in define mode.
|
||||
\returns ::NC_ENOTATT Attribute not found.
|
||||
\returns ::NC_EHDFERR Failure at HDF5 layer.
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_rename_att(int ncid, int varid, const char *name, const char *newname)
|
||||
@ -153,6 +167,17 @@ Units for a variable rh in an existing netCDF dataset named foo.nc:
|
||||
status = nc_enddef(ncid);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
\endcode
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Bad varid.
|
||||
\returns ::NC_EBADNAME Bad name.
|
||||
\returns ::NC_EINVAL Name not provided.
|
||||
\returns ::NC_EPERM File was opened read only.
|
||||
\returns ::NC_ENOTINDEFINE File is not in define mode.
|
||||
\returns ::NC_ENOTATT Attribute not found.
|
||||
\returns ::NC_EATTMETA Failure at HDF5 layer.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_del_att(int ncid, int varid, const char *name)
|
||||
|
||||
@ -20,7 +20,7 @@ Get an attribute of any type.
|
||||
|
||||
The nc_get_att() functions works for any type of attribute, and must
|
||||
be used to get attributes of user-defined type. We recommend that they
|
||||
type safe versions of this function be used where possible.
|
||||
type safe versions of this function be used for atomic data types.
|
||||
|
||||
\param ncid NetCDF or group ID, from a previous call to nc_open(),
|
||||
nc_create(), nc_def_grp(), or associated inquiry functions such as
|
||||
@ -29,7 +29,7 @@ nc_inq_ncid().
|
||||
\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
||||
for a global attribute.
|
||||
|
||||
\param name Attribute \ref object_name.
|
||||
\param name Attribute name.
|
||||
|
||||
\param value Pointer to location for returned attribute value(s). All
|
||||
elements of the vector of attribute values are returned, so you must
|
||||
@ -37,8 +37,47 @@ allocate enough space to hold them. Before using the value as a C
|
||||
string, make sure it is null-terminated. Call nc_inq_attlen() first to
|
||||
find out the length of the attribute.
|
||||
|
||||
\note See documentation for nc_get_att_string() regarding a special case where memory must be explicitly released.
|
||||
\note See documentation for nc_get_att_string() regarding a special
|
||||
case where memory must be explicitly released.
|
||||
|
||||
\returns ::NC_NOERR for success.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Bad varid.
|
||||
\returns ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
\returns ::NC_EINVAL Invalid parameters.
|
||||
\returns ::NC_ENOTATT Can't find attribute.
|
||||
\returns ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
\returns ::NC_ERANGE Data convertion went out of range.
|
||||
|
||||
<h1>Example</h1>
|
||||
|
||||
Here is an example using nc_get_att() from nc_test4/tst_vl.c creates a
|
||||
VLEN attribute, then uses nc_get_att() to read it.
|
||||
|
||||
@code
|
||||
#define FILE_NAME "tst_vl.nc"
|
||||
#define VLEN_NAME "vlen_name"
|
||||
#define ATT_NAME "att_name"
|
||||
|
||||
int ncid, typeid;
|
||||
nc_vlen_t data[DIM_LEN], data_in[DIM_LEN];
|
||||
...
|
||||
|
||||
if (nc_create(FILE_NAME, NC_NETCDF4, &ncid)) ERR;
|
||||
if (nc_def_vlen(ncid, VLEN_NAME, NC_INT, &typeid)) ERR;
|
||||
...
|
||||
if (nc_put_att(ncid, NC_GLOBAL, ATT_NAME, typeid, DIM_LEN, data)) ERR;
|
||||
if (nc_close(ncid)) ERR;
|
||||
|
||||
...
|
||||
if (nc_open(FILE_NAME, NC_NOWRITE, &ncid)) ERR;
|
||||
if (nc_get_att(ncid, NC_GLOBAL, ATT_NAME, data_in)) ERR;
|
||||
...
|
||||
if (nc_close(ncid)) ERR;
|
||||
@endcode
|
||||
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_get_att(int ncid, int varid, const char *name, void *value)
|
||||
@ -77,7 +116,7 @@ nc_inq_ncid().
|
||||
\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
||||
for a global attribute.
|
||||
|
||||
\param name Attribute \ref object_name.
|
||||
\param name Attribute name.
|
||||
|
||||
\param value Pointer to location for returned attribute value(s). All
|
||||
elements of the vector of attribute values are returned, so you must
|
||||
@ -85,6 +124,16 @@ allocate enough space to hold them. If you don't know how much
|
||||
space to reserve, call nc_inq_attlen() first to find out the length of
|
||||
the attribute.
|
||||
|
||||
\returns ::NC_NOERR for success.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Bad varid.
|
||||
\returns ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
\returns ::NC_EINVAL Invalid parameters.
|
||||
\returns ::NC_ENOTATT Can't find attribute.
|
||||
\returns ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
\returns ::NC_ERANGE Data convertion went out of range.
|
||||
|
||||
<h1>Example</h1>
|
||||
|
||||
Here is an example using nc_get_att_double() to determine the values
|
||||
@ -130,6 +179,7 @@ the length of the attributes.
|
||||
title[t_len] = '\0';
|
||||
...
|
||||
\endcode
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
/*! \{ */
|
||||
|
||||
@ -268,9 +318,17 @@ nc_get_att_ulonglong(int ncid, int varid, const char *name, unsigned long long *
|
||||
\ingroup attributes
|
||||
Get a variable-length string attribute.
|
||||
|
||||
This function gets an attribute from netCDF file. Thhe nc_get_att() function works with any type of data including user defined types, but this function will retrieve attributes which are of type variable-length string.
|
||||
This function gets an attribute from netCDF file. The nc_get_att()
|
||||
function works with any type of data including user defined types, but
|
||||
this function will retrieve attributes which are of type
|
||||
variable-length string.
|
||||
|
||||
\note Note that unlike most other nc_get_att functions, nc_get_att_string() allocates a chunk of memory which is returned to the calling function. This chunk of memory must be specifically deallocated with nc_free_string() to avoid any memory leaks. Also note that you must still preallocate the memory needed for the array of pointers passed to nc_get_att_string().
|
||||
\note Note that unlike most other nc_get_att functions,
|
||||
nc_get_att_string() allocates a chunk of memory which is returned to
|
||||
the calling function. This chunk of memory must be specifically
|
||||
deallocated with nc_free_string() to avoid any memory leaks. Also
|
||||
note that you must still preallocate the memory needed for the array
|
||||
of pointers passed to nc_get_att_string().
|
||||
|
||||
\param ncid NetCDF or group ID, from a previous call to nc_open(),
|
||||
nc_create(), nc_def_grp(), or associated inquiry functions such as
|
||||
@ -279,7 +337,7 @@ nc_inq_ncid().
|
||||
\param varid Variable ID of the attribute's variable, or ::NC_GLOBAL
|
||||
for a global attribute.
|
||||
|
||||
\param name Attribute \ref object_name.
|
||||
\param name Attribute name.
|
||||
|
||||
\param value Pointer to location for returned attribute value(s). All
|
||||
elements of the vector of attribute values are returned, so you must
|
||||
@ -287,6 +345,16 @@ allocate enough space to hold them. If you don't know how much
|
||||
space to reserve, call nc_inq_attlen() first to find out the length of
|
||||
the attribute.
|
||||
|
||||
\returns ::NC_NOERR for success.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Bad varid.
|
||||
\returns ::NC_EBADNAME Bad name. See \ref object_name.
|
||||
\returns ::NC_EINVAL Invalid parameters.
|
||||
\returns ::NC_ENOTATT Can't find attribute.
|
||||
\returns ::NC_ECHAR Can't convert to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
\returns ::NC_ERANGE Data convertion went out of range.
|
||||
|
||||
\section nc_get_att_string_example Example
|
||||
|
||||
\code{.c}
|
||||
@ -333,8 +401,7 @@ int main(int argc, char ** argv) {
|
||||
return 0;
|
||||
}
|
||||
\endcode
|
||||
|
||||
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
|
||||
int
|
||||
|
||||
@ -67,6 +67,17 @@ foo.nc:
|
||||
status = nc_inq_att (ncid, NC_GLOBAL, "title", &t_type, &t_len);
|
||||
if (status != NC_NOERR) handle_error(status);
|
||||
\endcode
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_ENOTVAR bad varid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\returns ::NC_EBADNAME bad name.
|
||||
\returns ::NC_ENOTATT attribute not found.
|
||||
\returns ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM out of memory.
|
||||
\returns ::NC_ERANGE range error when converting data.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_att(int ncid, int varid, const char *name, nc_type *xtypep,
|
||||
@ -96,6 +107,55 @@ specifies which attribute this is for this variable (or which global
|
||||
attribute). If you already know the attribute name, knowing its number
|
||||
is not very useful, because accessing information about an attribute
|
||||
requires its name.
|
||||
|
||||
\section nc_inq_attid_example Example
|
||||
|
||||
Here is an example using nc_inq_attid() from nc_test4/tst_vars2.c. In
|
||||
this example three attributes are created in a file. Then it is
|
||||
re-opened, and their IDs are checked. They will be 0, 1, and 2, in
|
||||
the order that the attributes were written to the file.
|
||||
|
||||
|
||||
\code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
printf("**** testing fill value with three other attributes...");
|
||||
{
|
||||
#define NUM_LEADERS 3
|
||||
char leader[NUM_LEADERS][NC_MAX_NAME + 1] = {"hair_length_of_strategoi",
|
||||
"hair_length_of_Miltiades",
|
||||
"hair_length_of_Darius_I"};
|
||||
short hair_length[NUM_LEADERS] = {3, 11, 4};
|
||||
short short_in;
|
||||
int a;
|
||||
|
||||
if (nc_create(FILE_NAME, cmode, &ncid)) ERR;
|
||||
if (nc_def_dim(ncid, DIM1_NAME, DIM1_LEN, &dimids[0])) ERR;
|
||||
if (nc_def_var(ncid, VAR_NAME, NC_BYTE, NUM_DIMS, dimids, &varid)) ERR;
|
||||
for (a = 0; a < NUM_LEADERS; a++)
|
||||
if (nc_put_att_short(ncid, varid, leader[a], NC_SHORT, 1, &hair_length[a])) ERR;
|
||||
if (nc_put_att_schar(ncid, varid, _FillValue, NC_BYTE, 1, &fill_value)) ERR;
|
||||
if (nc_close(ncid)) ERR;
|
||||
|
||||
if (nc_open(FILE_NAME, NC_NOWRITE, &ncid)) ERR;
|
||||
for (a = 0; a < NUM_LEADERS; a++)
|
||||
{
|
||||
...
|
||||
if (nc_inq_attid(ncid, 0, leader[a], &attnum_in)) ERR;
|
||||
if (attnum_in != a) ERR;
|
||||
}
|
||||
|
||||
if (nc_close(ncid)) ERR;
|
||||
\endcode
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_ENOTVAR bad varid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\returns ::NC_EBADNAME bad name.
|
||||
\returns ::NC_ENOTATT attribute not found.
|
||||
\returns ::NC_ENOMEM out of memory.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_attid(int ncid, int varid, const char *name, int *idp)
|
||||
@ -124,6 +184,70 @@ nc_inq_varnatts().
|
||||
|
||||
\param name Pointer to the location for the returned attribute \ref
|
||||
object_name.
|
||||
|
||||
\section nc_inq_attname_example Example
|
||||
|
||||
Here is an example from nc_test4/tst_atts3.c a variable of every type
|
||||
is added to a file, with names from the 'names' array. Then the file
|
||||
is re-opened, and the names of the attributes are checked in a for
|
||||
loop.
|
||||
|
||||
|
||||
\code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
#define NUM_ATTS 8
|
||||
#define ATT_MAX_NAME 25
|
||||
int
|
||||
tst_att_ordering(int cmode)
|
||||
{
|
||||
int ncid;
|
||||
char name[NUM_ATTS][ATT_MAX_NAME + 1] = {"Gc", "Gb", "Gs", "Gi", "Gf",
|
||||
"Gd", "Gatt-name-dashes", "Gatt.name.dots"};
|
||||
int len[NUM_ATTS] = {0, 2, 3, 3, 3, 3, 1, 1};
|
||||
signed char b[2] = {-128, 127};
|
||||
short s[3] = {-32768, 0, 32767};
|
||||
int i[3] = {42, 0, -42};
|
||||
float f[3] = {42.0, -42.0, 42.0};
|
||||
double d[3] = {420.0, -420.0, 420.0};
|
||||
int att_name_dashes = -1, att_name_dots = -2;
|
||||
char name_in[NC_MAX_NAME];
|
||||
int j;
|
||||
|
||||
if (nc_create(FILE_NAME, cmode, &ncid)) ERR;
|
||||
...
|
||||
if (nc_put_att_text(ncid, NC_GLOBAL, name[0], len[0], NULL)) ERR;
|
||||
if (nc_put_att_schar(ncid, NC_GLOBAL, name[1], NC_BYTE, len[1], b)) ERR;
|
||||
if (nc_put_att_short(ncid, NC_GLOBAL, name[2], NC_SHORT, len[2], s)) ERR;
|
||||
if (nc_put_att_int(ncid, NC_GLOBAL, name[3], NC_INT, len[3], i)) ERR;
|
||||
if (nc_put_att_float(ncid, NC_GLOBAL, name[4], NC_FLOAT, len[4], f)) ERR;
|
||||
if (nc_put_att_double(ncid, NC_GLOBAL, name[5], NC_DOUBLE, len[5], d)) ERR;
|
||||
if (nc_put_att_int(ncid, NC_GLOBAL, name[6], NC_INT, len[6], &att_name_dashes)) ERR;
|
||||
if (nc_put_att_int(ncid, NC_GLOBAL, name[7], NC_INT, len[7], &att_name_dots)) ERR;
|
||||
if (nc_close(ncid)) ERR;
|
||||
|
||||
...
|
||||
if (nc_open(FILE_NAME, 0, &ncid)) ERR;
|
||||
for (j = 0; j < NUM_ATTS; j++)
|
||||
{
|
||||
if (nc_inq_attname(ncid, NC_GLOBAL, j, name_in)) ERR;
|
||||
if (strcmp(name_in, name[j])) ERR;
|
||||
}
|
||||
|
||||
if (nc_close(ncid)) ERR;
|
||||
|
||||
\endcode
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_ENOTVAR bad varid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\returns ::NC_EBADNAME bad name.
|
||||
\returns ::NC_ENOTATT attribute not found.
|
||||
\returns ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM out of memory.
|
||||
\returns ::NC_ERANGE range error when converting data.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_attname(int ncid, int varid, int attnum, char *name)
|
||||
@ -144,6 +268,33 @@ nc_inq_ncid().
|
||||
|
||||
\param nattsp Pointer where number of global or group attributes will be
|
||||
written. \ref ignored_if_null.
|
||||
|
||||
\section nc_inq_natts_example Example
|
||||
|
||||
Here is an example from
|
||||
|
||||
|
||||
\code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
int
|
||||
check_4D_example(char *file_name, int expected_format)
|
||||
{
|
||||
int ncid;
|
||||
int format, ndims_in, nvars_in, natts_in;
|
||||
...
|
||||
|
||||
if (nc_open(file_name, 0, &ncid)) ERR;
|
||||
...
|
||||
if (nc_inq_natts(ncid, &natts_in)) ERR;
|
||||
if (natts_in != 0) ERR;
|
||||
|
||||
\endcode
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_natts(int ncid, int *nattsp)
|
||||
@ -169,6 +320,39 @@ for a global or group attribute.
|
||||
\param name Attribute \ref object_name.
|
||||
|
||||
\param xtypep Pointer to location for returned attribute \ref data_type.
|
||||
|
||||
\section nc_inq_atttype_example Example
|
||||
|
||||
Here is an example from nc_test4/tst_h_refs.c. In this example, a file
|
||||
with an integer attribute is open. It's type is confirmed to be
|
||||
NC_INT.
|
||||
|
||||
|
||||
\code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
printf("*** Checking accessing file through netCDF-4 API...");
|
||||
{
|
||||
int ncid, varid, attid;
|
||||
nc_type type;
|
||||
|
||||
if (nc_open(FILE_NAME, NC_NOWRITE, &ncid)) ERR;
|
||||
...
|
||||
if (nc_inq_atttype(ncid, NC_GLOBAL, INT_ATT_NAME, &type)) ERR;
|
||||
if (type != NC_INT) ERR;
|
||||
|
||||
\endcode
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_ENOTVAR bad varid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\returns ::NC_EBADNAME bad name.
|
||||
\returns ::NC_ENOTATT attribute not found.
|
||||
\returns ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM out of memory.
|
||||
\returns ::NC_ERANGE range error when converting data.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_atttype(int ncid, int varid, const char *name, nc_type *xtypep)
|
||||
@ -195,6 +379,47 @@ for a global or group attribute.
|
||||
\param lenp Pointer to location for returned number of values
|
||||
currently stored in the attribute. Before using the value as a C
|
||||
string, make sure it is null-terminated. \ref ignored_if_null.
|
||||
|
||||
\section nc_inq_attlen_example Example
|
||||
|
||||
Here is an example from nc_test4/tst_h_scalar.c which checks the
|
||||
attributes of an already-open netCDF file. In this code, the length of
|
||||
two attributes are checked, and found to be 1.
|
||||
|
||||
|
||||
\code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
int
|
||||
check_attrs(int ncid, int obj)
|
||||
{
|
||||
int attid;
|
||||
int natts = 0;
|
||||
size_t len;
|
||||
nc_type type;
|
||||
char *vlstr;
|
||||
char fixstr[10];
|
||||
int x;
|
||||
|
||||
...
|
||||
if (nc_inq_attlen(ncid, obj, VSTR_ATT1_NAME, &len)) ERR_GOTO;
|
||||
if (len != 1) ERR_GOTO;
|
||||
...
|
||||
if (nc_inq_attlen(ncid, obj, VSTR_ATT2_NAME, &len)) ERR_GOTO;
|
||||
if (len != 1) ERR_GOTO;
|
||||
|
||||
\endcode
|
||||
|
||||
\returns ::NC_NOERR no error.
|
||||
\returns ::NC_EBADID bad ncid.
|
||||
\returns ::NC_ENOTVAR bad varid.
|
||||
\returns ::NC_EBADGRPID bad group ID.
|
||||
\returns ::NC_EBADNAME bad name.
|
||||
\returns ::NC_ENOTATT attribute not found.
|
||||
\returns ::NC_ECHAR illegal conversion to or from NC_CHAR.
|
||||
\returns ::NC_ENOMEM out of memory.
|
||||
\returns ::NC_ERANGE range error when converting data.
|
||||
\author Glenn Davis, Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_attlen(int ncid, int varid, const char *name, size_t *lenp)
|
||||
|
||||
@ -340,14 +340,10 @@ Note that nc_create(path,cmode,ncidp) is equivalent to the invocation of
|
||||
nc__create(path,cmode,NC_SIZEHINT_DEFAULT,NULL,ncidp).
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
|
||||
\returns ::NC_ENOMEM System out of memory.
|
||||
|
||||
\returns ::NC_EHDFERR HDF5 error (netCDF-4 files only).
|
||||
|
||||
\returns ::NC_EFILEMETA Error writing netCDF-4 file-level metadata in
|
||||
HDF5 file. (netCDF-4 files only).
|
||||
|
||||
\returns ::NC_EDISKLESS if there was an error in creating the
|
||||
in-memory file.
|
||||
|
||||
@ -490,6 +486,14 @@ stored.
|
||||
\note This function uses the same return codes as the nc_create()
|
||||
function.
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_ENOMEM System out of memory.
|
||||
\returns ::NC_EHDFERR HDF5 error (netCDF-4 files only).
|
||||
\returns ::NC_EFILEMETA Error writing netCDF-4 file-level metadata in
|
||||
HDF5 file. (netCDF-4 files only).
|
||||
\returns ::NC_EDISKLESS if there was an error in creating the
|
||||
in-memory file.
|
||||
|
||||
<h1>Examples</h1>
|
||||
|
||||
In this example we create a netCDF dataset named foo_large.nc; we want
|
||||
@ -511,7 +515,7 @@ and initial size for the file.
|
||||
\endcode
|
||||
|
||||
\ingroup datasets
|
||||
|
||||
\author Glenn Davis, Russ Rew, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc__create(const char *path, int cmode, size_t initialsz,
|
||||
|
||||
@ -1,17 +1,89 @@
|
||||
/** \file dparallel.c
|
||||
This file has the parallel I/O functions which correspond to the serial I/O functions.
|
||||
/** \file
|
||||
|
||||
This file has the parallel I/O functions which correspond to the
|
||||
serial I/O functions.
|
||||
|
||||
Copyright 2010 University Corporation for Atmospheric
|
||||
Research/Unidata. See COPYRIGHT file for more info.
|
||||
*/
|
||||
|
||||
#include "config.h"
|
||||
#include "ncdispatch.h"
|
||||
|
||||
/**
|
||||
Create a netCDF file for parallel I/O.
|
||||
|
||||
This function creates a file for use with parallel I/O.
|
||||
This function creates a new netCDF file for parallel I/O access.
|
||||
|
||||
Parallel I/O access is only available in library build which support
|
||||
parallel I/O. To support parallel I/O, netCDF must be built with
|
||||
netCDF-4 enabled, and with a HDF5 library that supports parallel I/O,
|
||||
or with support for the parallel-netcdf library via the
|
||||
enable-pnetcdf option.
|
||||
|
||||
See nc_create() for a fuller discussion of file creation.
|
||||
|
||||
\note When opening a netCDF-4 file HDF5 error reporting is turned off,
|
||||
if it is on. This doesn't stop the HDF5 error stack from recording the
|
||||
errors, it simply stops their display to the user through stderr.
|
||||
|
||||
\param path The file name of the new netCDF dataset.
|
||||
|
||||
\param cmode The creation mode flag. The following flags are available:
|
||||
NC_NOCLOBBER (do not overwrite existing file),
|
||||
NC_NETCDF4 (create netCDF-4/HDF5 file),
|
||||
NC_CLASSIC_MODEL (enforce netCDF classic mode on netCDF-4/HDF5 files),
|
||||
NC_PNETCDF.
|
||||
|
||||
\param comm the MPI communicator to be used.
|
||||
|
||||
\param info MPI info or MPI_INFO_NULL.
|
||||
|
||||
\param ncidp Pointer to location where returned netCDF ID is to be
|
||||
stored.
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_ENOPAR Library was not built with parallel I/O features.
|
||||
\returns ::NC_EINVAL Invalid input parameters.
|
||||
\returns ::NC_ENOMEM System out of memory.
|
||||
\returns ::NC_ENOTNC Binary format could not be determined.
|
||||
\returns ::NC_EHDFERR HDF5 error (netCDF-4 files only).
|
||||
\returns ::NC_EFILEMETA Error writing netCDF-4 file-level metadata in
|
||||
HDF5 file. (netCDF-4 files only).
|
||||
|
||||
<h1>Example</h1>
|
||||
|
||||
In this example from nc_test4/tst_parallel.c, a file is create for
|
||||
parallel I/O.
|
||||
|
||||
\code
|
||||
int mpi_size, mpi_rank;
|
||||
MPI_Comm comm = MPI_COMM_WORLD;
|
||||
MPI_Info info = MPI_INFO_NULL;
|
||||
int ncid, v1id, dimids[NDIMS];
|
||||
char file_name[NC_MAX_NAME + 1];
|
||||
|
||||
MPI_Init(&argc,&argv);
|
||||
MPI_Comm_size(MPI_COMM_WORLD, &mpi_size);
|
||||
MPI_Comm_rank(MPI_COMM_WORLD, &mpi_rank);
|
||||
|
||||
sprintf(file_name, "%s/%s", TEMP_LARGE, FILE);
|
||||
if ((res = nc_create_par(file_name, NC_NETCDF4|NC_MPIIO, comm,
|
||||
info, &ncid))) ERR;
|
||||
|
||||
if (nc_def_dim(ncid, "d1", DIMSIZE, dimids)) ERR;
|
||||
if (nc_def_dim(ncid, "d2", DIMSIZE, &dimids[1])) ERR;
|
||||
if (nc_def_dim(ncid, "d3", NUM_SLABS, &dimids[2])) ERR;
|
||||
|
||||
if ((res = nc_def_var(ncid, "v1", NC_INT, NDIMS, dimids, &v1id))) ERR;
|
||||
|
||||
if ((res = nc_enddef(ncid))) ERR;
|
||||
|
||||
...
|
||||
|
||||
if ((res = nc_close(ncid))) ERR;
|
||||
\endcode
|
||||
\author Ed Hartnett, Dennis Heimbigner
|
||||
\ingroup datasets
|
||||
*/
|
||||
int nc_create_par(const char *path, int cmode, MPI_Comm comm,
|
||||
MPI_Info info, int *ncidp)
|
||||
@ -33,7 +105,7 @@ int nc_create_par(const char *path, int cmode, MPI_Comm comm,
|
||||
#endif /* USE_PARALLEL */
|
||||
}
|
||||
|
||||
/** \ingroup datasets
|
||||
/**
|
||||
Open an existing netCDF file for parallel I/O.
|
||||
|
||||
This function opens an existing netCDF dataset for parallel I/O
|
||||
@ -58,7 +130,7 @@ path will return the same ncid value.
|
||||
if it is on. This doesn't stop the HDF5 error stack from recording the
|
||||
errors, it simply stops their display to the user through stderr.
|
||||
|
||||
\param path File name for netCDF dataset to be opened.
|
||||
\param path File name for netCDF dataset to be opened.
|
||||
|
||||
\param mode The mode flag may include NC_WRITE (for read/write
|
||||
access), NC_MPIIO or NC_MPIPOSIX (not both) for parallel netCDF-4 I/O,
|
||||
@ -77,15 +149,10 @@ occurred. Otherwise, the returned status indicates an error. Possible
|
||||
causes of errors include:
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
|
||||
\returns ::NC_EINVAL Invalid parameters.
|
||||
|
||||
\returns ::NC_ENOTNC Not a netCDF file.
|
||||
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
|
||||
\returns ::NC_EHDFERR HDF5 error. (NetCDF-4 files only.)
|
||||
|
||||
\returns ::NC_EDIMMETA Error in netCDF-4 dimension metadata. (NetCDF-4
|
||||
files only.)
|
||||
|
||||
@ -93,7 +160,7 @@ files only.)
|
||||
|
||||
Here is an example using nc_open_par() from examples/C/parallel_vara.c.
|
||||
|
||||
@code
|
||||
\code
|
||||
#include <mpi.h>
|
||||
#include <netcdf.h>
|
||||
#include <netcdf_par.h>
|
||||
@ -103,7 +170,9 @@ Here is an example using nc_open_par() from examples/C/parallel_vara.c.
|
||||
...
|
||||
omode = NC_PNETCDF | NC_NOWRITE;
|
||||
err = nc_open_par(filename, omode, MPI_COMM_WORLD, MPI_INFO_NULL, &ncid); FATAL_ERR
|
||||
@endcode
|
||||
\endcode
|
||||
\author Ed Hartnett, Dennis Heimbigner
|
||||
\ingroup datasets
|
||||
*/
|
||||
int
|
||||
nc_open_par(const char *path, int mode, MPI_Comm comm,
|
||||
@ -130,10 +199,39 @@ nc_open_par(const char *path, int mode, MPI_Comm comm,
|
||||
#endif /* USE_PARALLEL */
|
||||
}
|
||||
|
||||
/*! \ingroup datasets
|
||||
/**
|
||||
This is the same as nc_open_par(), but accepts the MPI comm/info as
|
||||
integers.
|
||||
|
||||
Fortran needs to pass MPI comm/info as integers.
|
||||
\param path File name for netCDF dataset to be opened.
|
||||
|
||||
\param mode The mode flag may include NC_WRITE (for read/write
|
||||
access), NC_MPIIO or NC_MPIPOSIX (not both) for parallel netCDF-4 I/O,
|
||||
or NC_PNETCDF for parallel-netcdf parallel I/O access for a netCDF
|
||||
classic or CDF5 file.
|
||||
|
||||
\param comm the MPI communicator to be used.
|
||||
|
||||
\param info MPI info or MPI_INFO_NULL.
|
||||
|
||||
\param ncidp Pointer to location where returned netCDF ID is to be
|
||||
stored.
|
||||
|
||||
nc_open_par() returns the value NC_NOERR if no errors
|
||||
occurred. Otherwise, the returned status indicates an error. Possible
|
||||
causes of errors include:
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_EINVAL Invalid parameters.
|
||||
\returns ::NC_ENOTNC Not a netCDF file.
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
\returns ::NC_EHDFERR HDF5 error. (NetCDF-4 files only.)
|
||||
\returns ::NC_EDIMMETA Error in netCDF-4 dimension metadata. (NetCDF-4
|
||||
files only.)
|
||||
|
||||
\author Ed Hartnett
|
||||
\ingroup datasets
|
||||
\internal
|
||||
*/
|
||||
int
|
||||
nc_open_par_fortran(const char *path, int mode, int comm,
|
||||
@ -159,7 +257,6 @@ nc_open_par_fortran(const char *path, int mode, int comm,
|
||||
#endif
|
||||
}
|
||||
|
||||
/* */
|
||||
/**\ingroup datasets
|
||||
|
||||
This function will change the parallel access of a variable from
|
||||
@ -174,13 +271,9 @@ nc_inq_ncid().
|
||||
\param par_access NC_COLLECTIVE or NC_INDEPENDENT.
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
|
||||
\returns ::NC_EBADID Invalid ncid passed.
|
||||
|
||||
\returns ::NC_ENOTVAR Invalid varid passed.
|
||||
|
||||
\returns ::NC_ENOPAR LFile was not opened with nc_open_par/nc_create_var.
|
||||
|
||||
\returns ::NC_EINVAL Invalid par_access specified.
|
||||
|
||||
<h1>Example</h1>
|
||||
@ -222,6 +315,8 @@ parallel access of a variable and then writes to it.
|
||||
err = nc_put_vara_int(ncid, varid, start, count, &buf[0][0]); ERR
|
||||
|
||||
\endcode
|
||||
\author Ed Hartnett, Dennis Heimbigner
|
||||
\ingroup datasets
|
||||
*/
|
||||
int
|
||||
nc_var_par_access(int ncid, int varid, int par_access)
|
||||
@ -240,7 +335,40 @@ nc_var_par_access(int ncid, int varid, int par_access)
|
||||
#endif
|
||||
}
|
||||
|
||||
/* when calling from fortran: convert MPI_Comm and MPI_Info to C */
|
||||
/**
|
||||
Create a netCDF file for parallel access from the Fortran API.
|
||||
|
||||
This function calls nc_create_par() after converting the MPI comm and
|
||||
info from Fortran to C, if necessary.
|
||||
|
||||
\param path The file name of the new netCDF dataset.
|
||||
|
||||
\param cmode The creation mode flag. The following flags are available:
|
||||
NC_NOCLOBBER (do not overwrite existing file),
|
||||
NC_NETCDF4 (create netCDF-4/HDF5 file),
|
||||
NC_CLASSIC_MODEL (enforce netCDF classic mode on netCDF-4/HDF5 files),
|
||||
NC_PNETCDF.
|
||||
|
||||
\param comm the MPI communicator to be used.
|
||||
|
||||
\param info MPI info or MPI_INFO_NULL.
|
||||
|
||||
\param ncidp Pointer to location where returned netCDF ID is to be
|
||||
stored.
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_ENOPAR Library was not built with parallel I/O features.
|
||||
\returns ::NC_EINVAL Invalid input parameters.
|
||||
\returns ::NC_ENOMEM System out of memory.
|
||||
\returns ::NC_ENOTNC Binary format could not be determined.
|
||||
\returns ::NC_EHDFERR HDF5 error (netCDF-4 files only).
|
||||
\returns ::NC_EFILEMETA Error writing netCDF-4 file-level metadata in
|
||||
HDF5 file. (netCDF-4 files only).
|
||||
|
||||
\author Ed Hartnett, Dennis Heimbigner
|
||||
\ingroup datasets
|
||||
\internal
|
||||
*/
|
||||
int
|
||||
nc_create_par_fortran(const char *path, int cmode, int comm,
|
||||
int info, int *ncidp)
|
||||
|
||||
@ -39,7 +39,7 @@ type). Read attributes of the new type with nc_get_att (see
|
||||
/** \{ */
|
||||
|
||||
|
||||
/** \internal
|
||||
/**
|
||||
\ingroup user_types
|
||||
Learn if two types are equal
|
||||
|
||||
@ -55,6 +55,7 @@ the two types are equal, a zero if they are not equal.
|
||||
\returns ::NC_EBADTYPE Bad type id.
|
||||
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
|
||||
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
|
||||
\author Dennis Heimbigner, Ward Fisher
|
||||
*/
|
||||
int
|
||||
nc_inq_type_equal(int ncid1, nc_type typeid1, int ncid2,
|
||||
@ -87,6 +88,7 @@ found.
|
||||
\returns ::NC_EBADTYPE Bad type id.
|
||||
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
|
||||
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
|
||||
\author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_typeid(int ncid, const char *name, nc_type *typeidp)
|
||||
@ -130,6 +132,7 @@ compound types. \ref ignored_if_null.
|
||||
\returns ::NC_EBADTYPE Bad type id.
|
||||
\returns ::NC_ENOTNC4 Not an netCDF-4 file, or classic model enabled.
|
||||
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
|
||||
\author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_user_type(int ncid, nc_type xtype, char *name, size_t *size,
|
||||
|
||||
@ -887,7 +887,10 @@ variable. Set to NC_FILL (the default) to turn on fill mode for the
|
||||
variable.
|
||||
|
||||
\param fill_value the fill value to be used for this variable. Must be
|
||||
the same type as the variable.
|
||||
the same type as the variable. This must point to enough free memory
|
||||
to hold one element of the data type of the variable. (For example, an
|
||||
NC_INT will require 4 bytes for it's fill value, which is also an
|
||||
NC_INT.)
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_EBADID Bad ID.
|
||||
|
||||
@ -102,8 +102,31 @@ NC_get_vara(int ncid, int varid,
|
||||
return stat;
|
||||
}
|
||||
|
||||
/** \ingroup variables
|
||||
/**
|
||||
Get data for a variable.
|
||||
|
||||
\param ncid NetCDF or group ID.
|
||||
|
||||
\param varid Variable ID
|
||||
|
||||
\param value Pointer where the data will be copied. Memory must be
|
||||
allocated by the user before this function is called.
|
||||
|
||||
\param memtype the NC type of the data after it is read into
|
||||
memory. Data are converted from the variable's type to the memtype as
|
||||
they are read.
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_ENOTVAR Variable not found.
|
||||
\returns ::NC_EINVALCOORDS Index exceeds dimension bound.
|
||||
\returns ::NC_EEDGE Start+count exceeds dimension bound.
|
||||
\returns ::NC_ERANGE One or more of the values are out of range.
|
||||
\returns ::NC_EINDEFINE Operation not allowed in define mode.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
|
||||
\ingroup variables
|
||||
\internal
|
||||
\author Dennis Heimbigner
|
||||
*/
|
||||
static int
|
||||
NC_get_var(int ncid, int varid, void *value, nc_type memtype)
|
||||
@ -529,9 +552,38 @@ NCDEFAULT_get_varm(int ncid, int varid, const size_t *start,
|
||||
return status;
|
||||
}
|
||||
|
||||
/** \ingroup variables
|
||||
/**
|
||||
Called by externally visible nc_get_vars_xxx routines.
|
||||
|
||||
\param ncid NetCDF or group ID.
|
||||
|
||||
\param varid Variable ID
|
||||
|
||||
\param start start indices.
|
||||
|
||||
\param edges count indices.
|
||||
|
||||
\param stride data strides.
|
||||
|
||||
\param value Pointer where the data will be copied. Memory must be
|
||||
allocated by the user before this function is called.
|
||||
|
||||
\param memtype the NC type of the data after it is read into
|
||||
memory. Data are converted from the variable's type to the memtype as
|
||||
they are read.
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_ENOTVAR Variable not found.
|
||||
\returns ::NC_EINVALCOORDS Index exceeds dimension bound.
|
||||
\returns ::NC_EEDGE Start+count exceeds dimension bound.
|
||||
\returns ::NC_ERANGE One or more of the values are out of range.
|
||||
\returns ::NC_EINDEFINE Operation not allowed in define mode.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
|
||||
\ingroup variables
|
||||
\internal
|
||||
Called by externally visible nc_get_vars_xxx routines */
|
||||
\author Dennis Heimbigner
|
||||
*/
|
||||
static int
|
||||
NC_get_vars(int ncid, int varid, const size_t *start,
|
||||
const size_t *edges, const ptrdiff_t *stride, void *value,
|
||||
@ -547,9 +599,41 @@ NC_get_vars(int ncid, int varid, const size_t *start,
|
||||
return ncp->dispatch->get_vars(ncid,varid,start,edges,stride,value,memtype);
|
||||
}
|
||||
|
||||
/** \ingroup variables
|
||||
/**
|
||||
Called by externally visible nc_get_varm_xxx routines. Note that the
|
||||
varm routines are deprecated. Use the vars routines instead for new
|
||||
code.
|
||||
|
||||
\param ncid NetCDF or group ID.
|
||||
|
||||
\param varid Variable ID
|
||||
|
||||
\param start start indices.
|
||||
|
||||
\param edges count indices.
|
||||
|
||||
\param stride data strides.
|
||||
|
||||
\param map mapping of dimensions.
|
||||
|
||||
\param value Pointer where the data will be copied. Memory must be
|
||||
allocated by the user before this function is called.
|
||||
|
||||
\param memtype the NC type of the data after it is read into
|
||||
memory. Data are converted from the variable's type to the memtype as
|
||||
they are read.
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_ENOTVAR Variable not found.
|
||||
\returns ::NC_EINVALCOORDS Index exceeds dimension bound.
|
||||
\returns ::NC_EEDGE Start+count exceeds dimension bound.
|
||||
\returns ::NC_ERANGE One or more of the values are out of range.
|
||||
\returns ::NC_EINDEFINE Operation not allowed in define mode.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
|
||||
\ingroup variables
|
||||
\internal
|
||||
Called by externally visible nc_get_varm_xxx routines
|
||||
\author Dennis Heimbigner
|
||||
*/
|
||||
static int
|
||||
NC_get_varm(int ncid, int varid, const size_t *start,
|
||||
|
||||
@ -11,6 +11,7 @@ Research/Unidata. See COPYRIGHT file for more info.
|
||||
#endif
|
||||
|
||||
#ifndef H5Z_FILTER_SZIP
|
||||
/** ID of HDF SZIP filter. */
|
||||
#define H5Z_FILTER_SZIP 4
|
||||
#endif
|
||||
|
||||
@ -180,7 +181,8 @@ nc_inq_vartype(int ncid, int varid, nc_type *typep)
|
||||
NULL, NULL);
|
||||
}
|
||||
|
||||
/** Learn how many dimensions are associated with a variable.
|
||||
/**
|
||||
Learn how many dimensions are associated with a variable.
|
||||
\ingroup variables
|
||||
|
||||
\param ncid NetCDF or group ID, from a previous call to nc_open(),
|
||||
@ -202,7 +204,8 @@ nc_inq_varndims(int ncid, int varid, int *ndimsp)
|
||||
return nc_inq_var(ncid, varid, NULL, NULL, ndimsp, NULL, NULL);
|
||||
}
|
||||
|
||||
/** Learn the dimension IDs associated with a variable.
|
||||
/**
|
||||
Learn the dimension IDs associated with a variable.
|
||||
\ingroup variables
|
||||
|
||||
\param ncid NetCDF or group ID, from a previous call to nc_open(),
|
||||
@ -225,7 +228,8 @@ nc_inq_vardimid(int ncid, int varid, int *dimidsp)
|
||||
dimidsp, NULL);
|
||||
}
|
||||
|
||||
/** Learn how many attributes are associated with a variable.
|
||||
/**
|
||||
Learn how many attributes are associated with a variable.
|
||||
\ingroup variables
|
||||
|
||||
\param ncid NetCDF or group ID, from a previous call to nc_open(),
|
||||
@ -522,7 +526,8 @@ nc_inq_var_endian(int ncid, int varid, int *endianp)
|
||||
NULL, NULL, NULL);
|
||||
}
|
||||
|
||||
/*! Return number and list of unlimited dimensions.
|
||||
/**
|
||||
Return number and list of unlimited dimensions.
|
||||
|
||||
In netCDF-4 files, it's possible to have multiple unlimited
|
||||
dimensions. This function returns a list of the unlimited dimension
|
||||
@ -531,18 +536,59 @@ ids visible in a group.
|
||||
Dimensions are visible in a group if they have been defined in that
|
||||
group, or any ancestor group.
|
||||
|
||||
\param ncid NetCDF group ID, from a previous call to nc_open, nc_create, nc_def_grp, etc.
|
||||
\param nunlimdimsp A pointer to an int which will get the number of visible unlimited dimensions. Ignored if NULL.
|
||||
\param unlimdimidsp A pointer to an already allocated array of int which will get the ids of all visible unlimited dimensions. Ignored if NULL. To allocate the correct length for this array, call nc_inq_unlimdims with a NULL for this parameter and use the nunlimdimsp parameter to get the number of visible unlimited dimensions.
|
||||
\param ncid NetCDF file and group ID, from a previous call to nc_open(),
|
||||
nc_create(), nc_def_grp(), etc.
|
||||
|
||||
\param nunlimdimsp A pointer to an int which will get the number of
|
||||
visible unlimited dimensions. Ignored if NULL.
|
||||
|
||||
\param unlimdimidsp A pointer to an already allocated array of int
|
||||
which will get the ids of all visible unlimited dimensions. Ignored if
|
||||
NULL. To allocate the correct length for this array, call
|
||||
nc_inq_unlimdims with a NULL for this parameter and use the
|
||||
nunlimdimsp parameter to get the number of visible unlimited
|
||||
dimensions.
|
||||
|
||||
\section nc_inq_unlimdims_example Example
|
||||
|
||||
Here is an example from nc_test4/tst_dims.c. In this example we create
|
||||
a file with two unlimited dimensions, and then call nc_inq_unlimdims()
|
||||
to check that there are 2 unlimited dimensions, and that they have
|
||||
dimids 0 and 1.
|
||||
|
||||
\code
|
||||
#include <netcdf.h>
|
||||
...
|
||||
#define ROMULUS "Romulus"
|
||||
#define REMUS "Remus"
|
||||
#define DIMS2 2
|
||||
printf("*** Testing file with two unlimited dimensions...");
|
||||
{
|
||||
int ncid, dimid[DIMS2];
|
||||
int unlimdimid_in[DIMS2];
|
||||
int nunlimdims_in;
|
||||
|
||||
if (nc_create(FILE_NAME, NC_NETCDF4, &ncid)) ERR;
|
||||
if (nc_def_dim(ncid, REMUS, NC_UNLIMITED, &dimid[0])) ERR;
|
||||
if (nc_def_dim(ncid, ROMULUS, NC_UNLIMITED, &dimid[1])) ERR;
|
||||
|
||||
...
|
||||
if (nc_inq_unlimdims(ncid, &nunlimdims_in, unlimdimid_in)) ERR;
|
||||
if (nunlimdims_in != 2 || unlimdimid_in[0] != 0 || unlimdimid_in[1] != 1) ERR;
|
||||
\endcode
|
||||
|
||||
This function will return one of the following values.
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_EBADID Bad group id.
|
||||
\returns ::NC_ENOTNC4 Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4 operations can only be performed on files defined with a create mode which includes flag HDF5. (see nc_open).
|
||||
\returns ::NC_ESTRICTNC3 This file was created with the strict netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see nc_open).
|
||||
\returns ::NC_ENOTNC4 Attempting a netCDF-4 operation on a netCDF-3
|
||||
file. NetCDF-4 operations can only be performed on files defined with
|
||||
a create mode which includes flag HDF5. (see nc_open).
|
||||
\returns ::NC_ESTRICTNC3 This file was created with the strict
|
||||
netcdf-3 flag, therefore netcdf-4 operations are not allowed. (see
|
||||
nc_open).
|
||||
\returns ::NC_EHDFERR An error was reported by the HDF5 layer.
|
||||
|
||||
\author Ed Hartnett, Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_unlimdims(int ncid, int *nunlimdimsp, int *unlimdimidsp)
|
||||
@ -559,7 +605,7 @@ nc_inq_unlimdims(int ncid, int *nunlimdimsp, int *unlimdimidsp)
|
||||
#endif
|
||||
}
|
||||
|
||||
/** \ingroup variables
|
||||
/**
|
||||
Find the filter (if any) associated with a variable.
|
||||
|
||||
This is a wrapper for nc_inq_var_all().
|
||||
@ -572,7 +618,8 @@ nc_inq_ncid().
|
||||
|
||||
\param idp Storage which will get the filter id.
|
||||
|
||||
\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. Note
|
||||
the caller must allocate and free.
|
||||
@ -582,6 +629,8 @@ the caller must allocate and free.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Invalid variable ID.
|
||||
\returns ::NC_EFILTER No filter defined.
|
||||
\ingroup variables
|
||||
\author Dennis Heimbigner
|
||||
*/
|
||||
int
|
||||
nc_inq_var_filter(int ncid, int varid, unsigned int* idp, size_t* nparamsp, unsigned int* params)
|
||||
@ -702,35 +751,52 @@ nc_inq_var_szip(int ncid, int varid, int *options_maskp, int *pixels_per_blockp)
|
||||
}
|
||||
|
||||
/*!
|
||||
Learn all about a variable.
|
||||
|
||||
Used in libdap2 and libdap4.
|
||||
|
||||
@param[in] ncid ncid for file.
|
||||
@param[in] varid varid for variable in question.
|
||||
@param[out] name Pointer to memory to contain the name of the variable.
|
||||
@param[out] xtypep Pointer to memory to contain the type of the variable.
|
||||
@param[out] ndimsp Pointer to memory to store the number of associated dimensions for the variable.
|
||||
@param[out] dimidsp Pointer to memory to store the dimids associated with the variable.
|
||||
@param[out] nattsp Pointer to memory to store the number of attributes associated with the variable.
|
||||
@param[out] shufflep Pointer to memory to store shuffle information associated with the variable.
|
||||
@param[out] deflatep Pointer to memory to store compression type associated with the variable.
|
||||
@param[out] deflate_levelp Pointer to memory to store compression level associated with the variable.
|
||||
@param[out] fletcher32p Pointer to memory to store compression information associated with the variable.
|
||||
@param[out] contiguousp Pointer to memory to store contiguous-data information associated with the variable.
|
||||
@param[out] chunksizesp Pointer to memory to store chunksize information associated with the variable.
|
||||
@param[out] no_fill Pointer to memory to store whether or not there is a fill value associated with the variable.
|
||||
@param[out] fill_valuep Pointer to memory to store the fill value (if one exists) for the variable.
|
||||
@param[out] endiannessp Pointer to memory to store endianness value. One of ::NC_ENDIAN_BIG ::NC_ENDIAN_LITTLE ::NC_ENDIAN_NATIVE
|
||||
@param[in] ncid ncid for file.
|
||||
@param[in] varid varid for variable in question.
|
||||
@param[out] name Pointer to memory to contain the name of the
|
||||
variable.
|
||||
@param[out] xtypep Pointer to memory to contain the type of the
|
||||
variable.
|
||||
@param[out] ndimsp Pointer to memory to store the number of associated
|
||||
dimensions for the variable.
|
||||
@param[out] dimidsp Pointer to memory to store the dimids associated
|
||||
with the variable.
|
||||
@param[out] nattsp Pointer to memory to store the number of attributes
|
||||
associated with the variable.
|
||||
@param[out] shufflep Pointer to memory to store shuffle information
|
||||
associated with the variable.
|
||||
@param[out] deflatep Pointer to memory to store compression type
|
||||
associated with the variable.
|
||||
@param[out] deflate_levelp Pointer to memory to store compression
|
||||
level associated with the variable.
|
||||
@param[out] fletcher32p Pointer to memory to store compression
|
||||
information associated with the variable.
|
||||
@param[out] contiguousp Pointer to memory to store contiguous-data
|
||||
information associated with the variable.
|
||||
@param[out] chunksizesp Pointer to memory to store chunksize
|
||||
information associated with the variable.
|
||||
@param[out] no_fill Pointer to memory to store whether or not there is
|
||||
a fill value associated with the variable.
|
||||
@param[out] fill_valuep Pointer to memory to store the fill value (if
|
||||
one exists) for the variable.
|
||||
@param[out] endiannessp Pointer to memory to store endianness
|
||||
value. One of ::NC_ENDIAN_BIG ::NC_ENDIAN_LITTLE ::NC_ENDIAN_NATIVE
|
||||
@param[out] idp Pointer to memory to store filter id.
|
||||
@param[out] nparamsp Pointer to memory to store filter parameter count.
|
||||
@param[out] params Pointer to vector of unsigned integers into which
|
||||
to store filter parameters.
|
||||
\note Expose access to nc_inq_var_all().
|
||||
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Bad varid.
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
\returns ::NC_EINVAL Invalid input.
|
||||
\author Ed Hartnett, Dennis Heimbigner
|
||||
\internal
|
||||
\ingroup variables
|
||||
|
||||
|
||||
*/
|
||||
int
|
||||
NC_inq_var_all(int ncid, int varid, char *name, nc_type *xtypep,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user