mirror of
https://github.com/Unidata/netcdf-c.git
synced 2025-03-01 17:06:03 +08:00
Merge branch 'sub_doc' of https://github.com/Unidata/netcdf-c into sub_doc
This commit is contained in:
Ward Fisher
commit
bd776b9523
@ -797,9 +797,9 @@ IF(ENABLE_DOXYGEN)
|
||||
|
||||
|
||||
# Option to turn on the TODO list in the doxygen-generated documentation.
|
||||
OPTION(ENABLE_DOXYGEN_TODO_LIST "Turn on todo list in documentation. This is of interest to developers only." OFF)
|
||||
IF(ENABLE_DOXYGEN_TODO_LIST)
|
||||
SET(SHOW_DOXYGEN_TODO_LIST YES CACHE STRING "")
|
||||
OPTION(ENABLE_DOXYGEN_TASKS "Turn on test, todo, bug lists in documentation. This is of interest to developers only." OFF)
|
||||
IF(ENABLE_DOXYGEN_TASKS)
|
||||
SET(SHOW_DOXYGEN_TAG_LIST YES CACHE STRING "")
|
||||
ELSE()
|
||||
SET(SHOW_DOXYGEN_TODO_LIST NO CACHE STRING "")
|
||||
ENDIF()
|
||||
|
||||
@ -39,7 +39,7 @@ doesn't if the attribute was stored without a trailing zero byte, for
|
||||
example from a FORTRAN program. Before using the value as a C string,
|
||||
make sure it is null-terminated. \ref ignored_if_null.
|
||||
|
||||
\section Example
|
||||
\section nc_inq_att_example Example
|
||||
|
||||
Here is an example using nc_inq_att() to find out the type and length of
|
||||
a variable attribute named valid_range for a netCDF variable named rh
|
||||
|
||||
@ -96,7 +96,7 @@ is still in initial define mode.
|
||||
_Fill_Value_ attribute, and will tell the HDF5 layer to use the
|
||||
specified fill value for that variable.
|
||||
|
||||
\section Example
|
||||
\section nc_put_att_text_example Example
|
||||
|
||||
Here is an example using nc_put_att_double() to add a variable
|
||||
attribute named valid_range for a netCDF variable named rh and
|
||||
@ -186,7 +186,7 @@ apply.
|
||||
\returns ::NC_ELATEFILL Fill values must be written while the file
|
||||
is still in initial define mode.
|
||||
|
||||
\section Example
|
||||
\section nc_put_att_double_example Example
|
||||
|
||||
Here is an example using nc_put_att_double() to add a variable
|
||||
attribute named valid_range for a netCDF variable named rh and
|
||||
|
||||
@ -37,7 +37,7 @@ you wish to insert into the compound type.
|
||||
\returns ::NC_EPERM Attempt to write to a read-only file.
|
||||
\returns ::NC_ENOTINDEFINE Not in define mode.
|
||||
|
||||
\section Example
|
||||
\section nc_def_compound_example Example
|
||||
|
||||
\code
|
||||
struct s1
|
||||
|
||||
@ -9,59 +9,11 @@ Research/Unidata. See COPYRIGHT file for more info.
|
||||
|
||||
#include "ncdispatch.h"
|
||||
|
||||
/*! \defgroup dimensions Dimensions
|
||||
|
||||
Dimensions are used to define the shape of data in netCDF.
|
||||
|
||||
Dimensions for a netCDF dataset are defined when it is created, while
|
||||
the netCDF dataset is in define mode. Additional dimensions may be
|
||||
added later by reentering define mode. A netCDF dimension has a name
|
||||
and a length. In a netCDF classic or 64-bit offset file, at most one
|
||||
dimension can have the unlimited length, which means variables using
|
||||
this dimension can grow along this dimension. In a netCDF-4 file
|
||||
multiple unlimited dimensions are supported.
|
||||
|
||||
There is a suggested limit (1024) to the number of dimensions that can
|
||||
be defined in a single netCDF dataset. The limit is the value of the
|
||||
predefined macro NC_MAX_DIMS. The purpose of the limit is to make
|
||||
writing generic applications simpler. They need only provide an array
|
||||
of NC_MAX_DIMS dimensions to handle any netCDF dataset. The
|
||||
implementation of the netCDF library does not enforce this advisory
|
||||
maximum, so it is possible to use more dimensions, if necessary, but
|
||||
netCDF utilities that assume the advisory maximums may not be able to
|
||||
handle the resulting netCDF datasets.
|
||||
|
||||
NC_MAX_VAR_DIMS, which must not exceed NC_MAX_DIMS, is the maximum
|
||||
number of dimensions that can be used to specify the shape of a single
|
||||
variable. It is also intended to simplify writing generic
|
||||
applications.
|
||||
|
||||
Ordinarily, the name and length of a dimension are fixed when the
|
||||
dimension is first defined. The name may be changed later, but the
|
||||
length of a dimension (other than the unlimited dimension) cannot be
|
||||
changed without copying all the data to a new netCDF dataset with a
|
||||
redefined dimension length.
|
||||
|
||||
Dimension lengths in the C interface are type size_t rather than type
|
||||
int to make it possible to access all the data in a netCDF dataset on
|
||||
a platform that only supports a 16-bit int data type, for example
|
||||
MSDOS. If dimension lengths were type int instead, it would not be
|
||||
possible to access data from variables with a dimension length greater
|
||||
than a 16-bit int can accommodate.
|
||||
|
||||
A netCDF dimension in an open netCDF dataset is referred to by a small
|
||||
integer called a dimension ID. In the C interface, dimension IDs are
|
||||
0, 1, 2, ..., in the order in which the dimensions were defined.
|
||||
|
||||
Operations supported on dimensions are:
|
||||
- Create a dimension, given its name and length.
|
||||
- Get a dimension ID from its name.
|
||||
- Get a dimension's name and length from its ID.
|
||||
- Rename a dimension.
|
||||
*/
|
||||
/**@{*/
|
||||
|
||||
/*! Define a new dimension. The function nc_def_dim adds a new
|
||||
/*!
|
||||
|
||||
Define a new dimension. The function nc_def_dim adds a new
|
||||
dimension to an open netCDF dataset in define mode. It returns (as an
|
||||
argument) a dimension ID, given the netCDF ID, the dimension name, and
|
||||
the dimension length. At most one unlimited length dimension, called
|
||||
@ -90,7 +42,7 @@ unlimited dimensions.
|
||||
\returns ::NC_ENOMEM Memory allocation (malloc) failure
|
||||
\returns ::NC_EPERM Write to read only
|
||||
|
||||
\section Example
|
||||
\section nc_def_dim_example Example
|
||||
|
||||
Here is an example using nc_def_dim() to create a dimension named lat of
|
||||
length 18 and a unlimited dimension named rec in a new netCDF dataset
|
||||
@ -176,7 +128,7 @@ the unlimited dimension, this is the number of records written so far.
|
||||
\returns ::NC_EBADID Not a valid ID.
|
||||
\returns ::NC_EBADDIM Invalid dimension ID or name.
|
||||
|
||||
\section Example
|
||||
\section nc_inq_dim_example Example
|
||||
|
||||
Here is an example using nc_inq_dim() to determine the length of a
|
||||
dimension named lat, and the name and current maximum length of the
|
||||
@ -241,7 +193,7 @@ with length less than NC_MAX_NAME.
|
||||
\returns ::NC_ENAMEINUSE String match to name in use
|
||||
\returns ::NC_ENOMEM Memory allocation (malloc) failure
|
||||
\returns ::NC_EPERM Write to read only
|
||||
\section Example
|
||||
\section nc_rename_dim_example Example
|
||||
|
||||
Here is an example using nc_rename_dim to rename the dimension lat to
|
||||
latitude in an existing netCDF dataset named foo.nc:
|
||||
@ -354,7 +306,7 @@ will be null-terminated. Ignored if NULL.
|
||||
\returns ::NC_EBADID Not a valid ID.
|
||||
\returns ::NC_EBADDIM Invalid dimension ID or name.
|
||||
|
||||
\section Example
|
||||
\section nc_inq_dim_example2 Example
|
||||
|
||||
Here is an example using nc_inq_dim() to determine the length of a
|
||||
dimension named lat, and the name and current maximum length of the
|
||||
@ -411,7 +363,7 @@ nc_def_dim().
|
||||
\returns ::NC_EBADID Not a valid ID.
|
||||
\returns ::NC_EBADDIM Invalid dimension ID or name.
|
||||
|
||||
\section Example
|
||||
\section nc_inq_dim_example3 Example
|
||||
|
||||
Here is an example using nc_inq_dim() to determine the length of a
|
||||
dimension named lat, and the name and current maximum length of the
|
||||
|
||||
@ -12,10 +12,6 @@ Research/Unidata. See COPYRIGHT file for more info.
|
||||
/* Tell the user the version of netCDF. */
|
||||
static const char nc_libvers[] = PACKAGE_VERSION " of "__DATE__" "__TIME__" $";
|
||||
|
||||
/** \defgroup lib_version Library Version
|
||||
Functions related to querying the library version.
|
||||
*/
|
||||
|
||||
/**
|
||||
\ingroup lib_version
|
||||
Return the library version.
|
||||
@ -54,9 +50,8 @@ status value.
|
||||
|
||||
*/
|
||||
|
||||
/**
|
||||
\ingroup error
|
||||
Given an error number, return an error message.
|
||||
/*! Given an error number, return an error message.
|
||||
\addtogroup error
|
||||
|
||||
This function returns a static reference to an error message string
|
||||
corresponding to an integer netCDF error status or to a system error
|
||||
@ -67,7 +62,7 @@ function. The error codes are defined in netcdf.h.
|
||||
|
||||
\returns short string containing error message.
|
||||
|
||||
\section Example
|
||||
\section handle_error_example nc_strerror Example
|
||||
|
||||
Here is an example of a simple error handling function that uses
|
||||
nc_strerror to print the error message corresponding to the netCDF
|
||||
|
||||
@ -168,7 +168,7 @@ element of the dimids array.
|
||||
\returns ::NC_ENAMEINUSE Name already in use.
|
||||
\returns ::NC_EPERM Attempt to create object in read-only file.
|
||||
|
||||
\section Example
|
||||
\section nc_def_var_example Example
|
||||
|
||||
Here is an example using nc_def_var to create a variable named rh of
|
||||
type double with three dimensions, time, lat, and lon in a new netCDF
|
||||
@ -250,7 +250,7 @@ nc_inq_ncid().
|
||||
\returns ::NC_ENAMEINUSE Name in use.
|
||||
\returns ::NC_ENOMEM Out of memory.
|
||||
|
||||
\section Example
|
||||
\section nc_rename_var_example Example
|
||||
|
||||
Here is an example using nc_rename_var to rename the variable rh to
|
||||
rel_hum in an existing netCDF dataset named foo.nc:
|
||||
|
||||
@ -586,7 +586,7 @@ allocated by the user before this function is called.
|
||||
\returns ::NC_EINDEFINE Operation not allowed in define mode.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
|
||||
\section Example
|
||||
\section nc_get_vara_double_example Example
|
||||
|
||||
Here is an example using nc_get_vara_double() to read all the values of
|
||||
the variable named rh from an existing netCDF dataset named
|
||||
|
||||
@ -31,7 +31,7 @@ ignored_if_null.
|
||||
\returns ::NC_NOERR No error.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
|
||||
\section Example
|
||||
\section nc_inq_varid_example4 Example
|
||||
|
||||
Here is an example using nc_inq_varid to find out the ID of a variable
|
||||
named rh in an existing netCDF dataset named foo.nc:
|
||||
@ -85,7 +85,7 @@ stored. \ref ignored_if_null.
|
||||
\returns ::NC_EBADID Bad ncid.
|
||||
\returns ::NC_ENOTVAR Invalid variable ID.
|
||||
|
||||
\section Example
|
||||
\section nc_inq_var_example5 Example
|
||||
|
||||
Here is an example using nc_inq_var() to find out about a variable named
|
||||
rh in an existing netCDF dataset named foo.nc:
|
||||
|
||||
@ -7,28 +7,64 @@ INCLUDE_DIRECTORIES(".")
|
||||
# Build doxygen documentation, if need be.
|
||||
#####
|
||||
IF(BUILD_DOCS)
|
||||
FIND_PACKAGE(Doxygen)
|
||||
IF(DOXYGEN_FOUND)
|
||||
FILE(GLOB COPY_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.html ${CMAKE_CURRENT_SOURCE_DIR}/images ${CMAKE_CURRENT_SOURCE_DIR}/*.doc ${CMAKE_CURRENT_SOURCE_DIR}/*.xml ${CMAKE_CURRENT_SOURCE_DIR}/*.m4 ${CMAKE_CURRENT_SOURCE_DIR}/*.texi)
|
||||
FILE(COPY ${COPY_FILES} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/)
|
||||
# Copy the image files used by markdown documentation
|
||||
# manually.
|
||||
FILE(GLOB IMG_FILES ${CMAKE_CURRENT_BINARY_DIR}/images/*.jpg)
|
||||
|
||||
# Set abs_top_srcdir to work with the autotools
|
||||
# doxyfile template.
|
||||
SET(abs_top_srcdir ${CMAKE_SOURCE_DIR})
|
||||
CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
|
||||
${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
|
||||
ADD_CUSTOM_TARGET(doc_all ALL
|
||||
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Generating API Documentation with Doxygen" VERBATIM
|
||||
)
|
||||
FILE(COPY ${IMG_FILES} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/html)
|
||||
ENDIF()
|
||||
FIND_PACKAGE(Doxygen)
|
||||
IF(DOXYGEN_FOUND)
|
||||
FILE(GLOB COPY_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.html ${CMAKE_CURRENT_SOURCE_DIR}/images ${CMAKE_CURRENT_SOURCE_DIR}/*.doc ${CMAKE_CURRENT_SOURCE_DIR}/*.xml ${CMAKE_CURRENT_SOURCE_DIR}/*.m4 ${CMAKE_CURRENT_SOURCE_DIR}/*.texi)
|
||||
FILE(COPY ${COPY_FILES} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/)
|
||||
# Copy the image files used by markdown documentation
|
||||
# manually.
|
||||
FILE(GLOB IMG_FILES ${CMAKE_CURRENT_BINARY_DIR}/images/*.jpg)
|
||||
|
||||
# Set abs_top_srcdir to work with the autotools
|
||||
# doxyfile template.
|
||||
SET(abs_top_srcdir ${CMAKE_SOURCE_DIR})
|
||||
|
||||
# Create general and guide doxyfiles.
|
||||
CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
|
||||
${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
|
||||
CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.guide.in
|
||||
${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.guide @ONLY)
|
||||
CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.tutorial.in
|
||||
${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.tutorial @ONLY)
|
||||
|
||||
# We need to loop through twice. First to generate tags.
|
||||
ADD_CUSTOM_TARGET(all_doc_tags ALL
|
||||
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Generating API Tags" VERBATIM
|
||||
)
|
||||
ADD_CUSTOM_TARGET(all_doc_tags_guide ALL
|
||||
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.guide
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Generating Guide Tags" VERBATIM
|
||||
)
|
||||
ADD_CUSTOM_TARGET(all_doc_tags_tutorial ALL
|
||||
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.tutorial
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Generating Tutorial Tags" VERBATIM
|
||||
)
|
||||
|
||||
# Second, generate documentation that uses the tags.
|
||||
ADD_CUSTOM_TARGET(doc_all ALL
|
||||
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Generating API Documentation" VERBATIM
|
||||
)
|
||||
ADD_CUSTOM_TARGET(doc_guide ALL
|
||||
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.guide
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Generating NetCDF Users Guide" VERBATIM
|
||||
)
|
||||
ADD_CUSTOM_TARGET(doc_tutorial ALL
|
||||
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.tutorial
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Generating Tutorial Tags" VERBATIM
|
||||
)
|
||||
|
||||
FILE(COPY ${IMG_FILES} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/html)
|
||||
ENDIF()
|
||||
ENDIF()
|
||||
|
||||
SET(CUR_EXTRA_DIST ${CUR_EXTRA_DIST} CMakeLists.txt Makefile.am netcdf.m4 DoxygenLayout.xml Doxyfile.in footer.html mainpage.doc tutorial.doc install.doc dispatch.doc guide.doc types.doc notes.doc cdl.doc architecture.doc internal.doc Doxyfile.in.cmake windows-binaries.md Building-with-CMake.md)
|
||||
SET(CUR_EXTRA_DIST ${CUR_EXTRA_DIST} CMakeLists.txt Makefile.am netcdf.m4 DoxygenLayout.xml Doxyfile.in Doxyfile.guide.in footer.html mainpage.dox tutorial.dox install.dox dispatch.dox guide.dox types.dox notes.dox cdl.dox architecture.dox internal.dox install-fortran.dox Doxyfile.in.cmake windows-binaries.md Building-with-CMake.md)
|
||||
|
||||
ADD_EXTRA_DIST("${CUR_EXTRA_DIST}")
|
||||
@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8
|
||||
# title of most generated pages and in a few other places.
|
||||
# The default value is: My Project.
|
||||
|
||||
PROJECT_NAME = NetCDF
|
||||
PROJECT_NAME = "The NetCDF User's Guide"
|
||||
|
||||
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
|
||||
# could be handy for archiving the generated documentation or if some version
|
||||
@ -769,7 +769,7 @@ FILE_PATTERNS =
|
||||
# be searched for input files as well.
|
||||
# The default value is: NO.
|
||||
|
||||
RECURSIVE = YES
|
||||
RECURSIVE = NO
|
||||
|
||||
# The EXCLUDE tag can be used to specify files and/or directories that should be
|
||||
# excluded from the INPUT source files. This way you can easily exclude a
|
||||
@ -811,7 +811,7 @@ EXCLUDE_SYMBOLS =
|
||||
# that contain example code fragments that are included (see the \include
|
||||
# command).
|
||||
|
||||
EXAMPLE_PATH = @abs_top_srcdir@/examples/C
|
||||
EXAMPLE_PATH =
|
||||
|
||||
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
|
||||
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
|
||||
@ -2003,13 +2003,14 @@ SKIP_FUNCTION_MACROS = YES
|
||||
# the path). If a tag file is not located in the directory in which doxygen is
|
||||
# run, you must also specify the path to the tagfile here.
|
||||
|
||||
TAGFILES =
|
||||
TAGFILES = @CMAKE_CURRENT_BINARY_DIR@/main.tag=../ "@CMAKE_CURRENT_BINARY_DIR@/tutorial.tag = ../html_tutorial"
|
||||
|
||||
|
||||
# When a file name is specified after GENERATE_TAGFILE, doxygen will create a
|
||||
# tag file that is based on the input files it reads. See section "Linking to
|
||||
# external documentation" for more information about the usage of tag files.
|
||||
|
||||
GENERATE_TAGFILE =
|
||||
GENERATE_TAGFILE = @CMAKE_CURRENT_BINARY_DIR@/guide.tag
|
||||
|
||||
# If the ALLEXTERNALS tag is set to YES all external class will be listed in the
|
||||
# class index. If set to NO only the inherited external classes will be listed.
|
||||
@ -2022,14 +2023,14 @@ ALLEXTERNALS = NO
|
||||
# listed.
|
||||
# The default value is: YES.
|
||||
|
||||
EXTERNAL_GROUPS = YES
|
||||
EXTERNAL_GROUPS = NO
|
||||
|
||||
# If the EXTERNAL_PAGES tag is set to YES all external pages will be listed in
|
||||
# the related pages index. If set to NO, only the current project's pages will
|
||||
# be listed.
|
||||
# The default value is: YES.
|
||||
|
||||
EXTERNAL_PAGES = YES
|
||||
EXTERNAL_PAGES = NO
|
||||
|
||||
# The PERL_PATH should be the absolute path and name of the perl script
|
||||
# interpreter (i.e. the result of 'which perl').
|
||||
|
||||
@ -416,7 +416,7 @@ EXTRACT_PACKAGE = NO
|
||||
# included in the documentation.
|
||||
# The default value is: NO.
|
||||
|
||||
EXTRACT_STATIC = NO
|
||||
EXTRACT_STATIC = YES
|
||||
|
||||
# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined
|
||||
# locally in source files will be included in the documentation. If set to NO
|
||||
@ -580,20 +580,20 @@ STRICT_PROTO_MATCHING = NO
|
||||
# documentation.
|
||||
# The default value is: YES.
|
||||
|
||||
GENERATE_TODOLIST = @SHOW_DOXYGEN_TODO_LIST@
|
||||
GENERATE_TODOLIST = @SHOW_DOXYGEN_TAG_LIST@
|
||||
|
||||
# The GENERATE_TESTLIST tag can be used to enable ( YES) or disable ( NO) the
|
||||
# test list. This list is created by putting \test commands in the
|
||||
# documentation.
|
||||
# The default value is: YES.
|
||||
|
||||
GENERATE_TESTLIST = YES
|
||||
GENERATE_TESTLIST = @SHOW_DOXYGEN_TAG_LIST@
|
||||
|
||||
# The GENERATE_BUGLIST tag can be used to enable ( YES) or disable ( NO) the bug
|
||||
# list. This list is created by putting \bug commands in the documentation.
|
||||
# The default value is: YES.
|
||||
|
||||
GENERATE_BUGLIST = YES
|
||||
GENERATE_BUGLIST = @SHOW_DOXYGEN_TAG_LIST@
|
||||
|
||||
# The GENERATE_DEPRECATEDLIST tag can be used to enable ( YES) or disable ( NO)
|
||||
# the deprecated list. This list is created by putting \deprecated commands in
|
||||
@ -746,31 +746,20 @@ WARN_LOGFILE =
|
||||
INPUT = \
|
||||
@abs_top_srcdir@/RELEASE_NOTES.md \
|
||||
@abs_top_srcdir@/COPYRIGHT \
|
||||
@abs_top_srcdir@/man4/groups.dox \
|
||||
@abs_top_srcdir@/man4/mainpage.dox \
|
||||
@abs_top_srcdir@/man4/install.md \
|
||||
@abs_top_srcdir@/man4/install-fortran.md \
|
||||
@abs_top_srcdir@/man4/dispatch.dox \
|
||||
@abs_top_srcdir@/man4/guide.dox \
|
||||
@abs_top_srcdir@/man4/types.dox \
|
||||
@abs_top_srcdir@/man4/notes.dox \
|
||||
@abs_top_srcdir@/man4/cdl.dox \
|
||||
@abs_top_srcdir@/man4/architecture.dox \
|
||||
@abs_top_srcdir@/man4/internal.dox \
|
||||
@abs_top_srcdir@/man4/tutorial.dox \
|
||||
@abs_top_srcdir@/man4/windows-binaries.md \
|
||||
@abs_top_srcdir@/man4/all-error-codes.md \
|
||||
@abs_top_srcdir@/man4/cmake_faq.md \
|
||||
@abs_top_srcdir@/include/netcdf.h \
|
||||
@abs_top_srcdir@/examples/C/simple_xy_wr.c \
|
||||
@abs_top_srcdir@/examples/C/simple_xy_rd.c \
|
||||
@abs_top_srcdir@/examples/C/sfc_pres_temp_wr.c \
|
||||
@abs_top_srcdir@/examples/C/sfc_pres_temp_rd.c \
|
||||
@abs_top_srcdir@/examples/C/pres_temp_4D_wr.c \
|
||||
@abs_top_srcdir@/examples/C/pres_temp_4D_rd.c \
|
||||
@abs_top_srcdir@/examples/C/simple_nc4_wr.c \
|
||||
@abs_top_srcdir@/examples/C/simple_nc4_rd.c \
|
||||
@abs_top_srcdir@/examples/C/simple_xy_nc4_wr.c \
|
||||
@abs_top_srcdir@/examples/C/simple_xy_nc4_rd.c \
|
||||
@abs_top_srcdir@/libdispatch/dfile.c \
|
||||
@abs_top_srcdir@/libdispatch/ddim.c \
|
||||
@abs_top_srcdir@/libdispatch/datt.c \
|
||||
@ -2052,13 +2041,13 @@ SKIP_FUNCTION_MACROS = YES
|
||||
# the path). If a tag file is not located in the directory in which doxygen is
|
||||
# run, you must also specify the path to the tagfile here.
|
||||
|
||||
TAGFILES =
|
||||
TAGFILES = @CMAKE_CURRENT_BINARY_DIR@/guide.tag=html_guide/ "@CMAKE_CURRENT_BINARY_DIR@/tutorial.tag = html_tutorial/"
|
||||
|
||||
# When a file name is specified after GENERATE_TAGFILE, doxygen will create a
|
||||
# tag file that is based on the input files it reads. See section "Linking to
|
||||
# external documentation" for more information about the usage of tag files.
|
||||
|
||||
GENERATE_TAGFILE =
|
||||
GENERATE_TAGFILE = @CMAKE_CURRENT_BINARY_DIR@/main.tag
|
||||
|
||||
# If the ALLEXTERNALS tag is set to YES all external class will be listed in the
|
||||
# class index. If set to NO only the inherited external classes will be listed.
|
||||
@ -2071,14 +2060,14 @@ ALLEXTERNALS = NO
|
||||
# listed.
|
||||
# The default value is: YES.
|
||||
|
||||
EXTERNAL_GROUPS = YES
|
||||
EXTERNAL_GROUPS = NO
|
||||
|
||||
# If the EXTERNAL_PAGES tag is set to YES all external pages will be listed in
|
||||
# the related pages index. If set to NO, only the current project's pages will
|
||||
# be listed.
|
||||
# The default value is: YES.
|
||||
|
||||
EXTERNAL_PAGES = YES
|
||||
EXTERNAL_PAGES = NO
|
||||
|
||||
# The PERL_PATH should be the absolute path and name of the perl script
|
||||
# interpreter (i.e. the result of 'which perl').
|
||||
|
||||
2344
man4/Doxyfile.tutorial.in
Normal file
2344
man4/Doxyfile.tutorial.in
Normal file
File diff suppressed because it is too large
Load Diff
58
man4/groups.dox
Normal file
58
man4/groups.dox
Normal file
@ -0,0 +1,58 @@
|
||||
/*! \defgroup dimensions Dimensions
|
||||
|
||||
Dimensions are used to define the shape of data in netCDF.
|
||||
|
||||
Dimensions for a netCDF dataset are defined when it is created, while
|
||||
the netCDF dataset is in define mode. Additional dimensions may be
|
||||
added later by reentering define mode. A netCDF dimension has a name
|
||||
and a length. In a netCDF classic or 64-bit offset file, at most one
|
||||
dimension can have the unlimited length, which means variables using
|
||||
this dimension can grow along this dimension. In a netCDF-4 file
|
||||
multiple unlimited dimensions are supported.
|
||||
|
||||
There is a suggested limit (1024) to the number of dimensions that can
|
||||
be defined in a single netCDF dataset. The limit is the value of the
|
||||
predefined macro NC_MAX_DIMS. The purpose of the limit is to make
|
||||
writing generic applications simpler. They need only provide an array
|
||||
of NC_MAX_DIMS dimensions to handle any netCDF dataset. The
|
||||
implementation of the netCDF library does not enforce this advisory
|
||||
maximum, so it is possible to use more dimensions, if necessary, but
|
||||
netCDF utilities that assume the advisory maximums may not be able to
|
||||
handle the resulting netCDF datasets.
|
||||
|
||||
NC_MAX_VAR_DIMS, which must not exceed NC_MAX_DIMS, is the maximum
|
||||
number of dimensions that can be used to specify the shape of a single
|
||||
variable. It is also intended to simplify writing generic
|
||||
applications.
|
||||
|
||||
Ordinarily, the name and length of a dimension are fixed when the
|
||||
dimension is first defined. The name may be changed later, but the
|
||||
length of a dimension (other than the unlimited dimension) cannot be
|
||||
changed without copying all the data to a new netCDF dataset with a
|
||||
redefined dimension length.
|
||||
|
||||
Dimension lengths in the C interface are type size_t rather than type
|
||||
int to make it possible to access all the data in a netCDF dataset on
|
||||
a platform that only supports a 16-bit int data type, for example
|
||||
MSDOS. If dimension lengths were type int instead, it would not be
|
||||
possible to access data from variables with a dimension length greater
|
||||
than a 16-bit int can accommodate.
|
||||
|
||||
A netCDF dimension in an open netCDF dataset is referred to by a small
|
||||
integer called a dimension ID. In the C interface, dimension IDs are
|
||||
0, 1, 2, ..., in the order in which the dimensions were defined.
|
||||
|
||||
Operations supported on dimensions are:
|
||||
- Create a dimension, given its name and length.
|
||||
- Get a dimension ID from its name.
|
||||
- Get a dimension's name and length from its ID.
|
||||
- Rename a dimension.
|
||||
|
||||
/** \defgroup lib_version Library Version
|
||||
Functions related to querying the library version.
|
||||
*/
|
||||
|
||||
|
||||
|
||||
*/
|
||||
|
||||
207
man4/guide.dox
207
man4/guide.dox
@ -1,13 +1,22 @@
|
||||
/*! \file
|
||||
/*! \file guide.dox The NetCDF User's Guide
|
||||
|
||||
NetCDF Users Guide
|
||||
\brief The NetCDF User's Guide
|
||||
|
||||
The NetCDF Users Guide
|
||||
|
||||
\page user_guide The NetCDF Users Guide
|
||||
\mainpage
|
||||
|
||||
\tableofcontents
|
||||
|
||||
\section user_guide The NetCDF User's Guide
|
||||
|
||||
- \ref mainpage_netcdf
|
||||
- \subpage netcdf_summary
|
||||
- \subpage netcdf_introduction
|
||||
- \subpage file_structure_and_performance
|
||||
- \subpage netcdf_data_set_components
|
||||
- \subpage netcdf_perf_chunking
|
||||
- \subpage netcdf_utilities_guide
|
||||
- \subpage file_format_specifications
|
||||
|
||||
Data
|
||||
- \ref external_types
|
||||
- \ref classic_structures
|
||||
@ -17,46 +26,7 @@ Data
|
||||
- \ref remote_client
|
||||
- \ref type_conversion
|
||||
|
||||
File Structure and Performance
|
||||
- \ref classic_file_parts
|
||||
- \ref parts_of_netcdf4
|
||||
- \ref xdr_layer
|
||||
- \ref large_file_support
|
||||
- \ref offset_format_limitations
|
||||
- \ref classic_format_limitations
|
||||
- \ref netcdf_3_io
|
||||
- \ref parallel_access
|
||||
- \ref interoperability_with_hdf5
|
||||
- \ref creating_self
|
||||
- \ref dap_support
|
||||
|
||||
Improving Performance with Chunking
|
||||
- \ref chunk_cache
|
||||
- \ref default_chunking_4_1
|
||||
- default_chunking_4_0_1
|
||||
- \ref chunking_parallel_io
|
||||
- \ref bm_file
|
||||
|
||||
NetCDF Utilities
|
||||
- \ref cdl_syntax
|
||||
- \ref cdl_data_types
|
||||
- \ref cdl_constants
|
||||
- \ref guide_ncgen
|
||||
- \ref guide_ncdump
|
||||
- \ref guide_nccopy
|
||||
- \ref guide_ncgen3
|
||||
|
||||
File Format Specification
|
||||
- \ref classic_format_spec
|
||||
- \ref computing_offsets
|
||||
- \ref offset_examples
|
||||
- \ref offset_format_spec
|
||||
- \ref netcdf_4_spec
|
||||
- \ref netcdf_4_classic_spec
|
||||
- \ref hdf4_sd_format
|
||||
|
||||
|
||||
\section netcdf_summary Summary
|
||||
\section netcdf_summary The Purpose of NetCDF
|
||||
|
||||
The purpose of the Network Common Data Form (netCDF) interface is to
|
||||
allow you to create, access, and share array-oriented data in a form
|
||||
@ -97,9 +67,11 @@ software that works with netCDF data.
|
||||
Separate documentation of the Java netCDF library can be found at
|
||||
http://www.unidata.ucar.edu/software/netcdf-java.
|
||||
|
||||
\section netcdf_introduction An Introduction to NetCDF
|
||||
\page netcdf_introduction An Introduction to NetCDF
|
||||
|
||||
\subsection netcdf_interface The NetCDF Interface
|
||||
\tableofcontents
|
||||
|
||||
\section netcdf_interface The NetCDF Interface
|
||||
|
||||
The Network Common Data Form, or netCDF, is an interface to a library
|
||||
of data access functions for storing and retrieving data in the form
|
||||
@ -149,7 +121,7 @@ its widespread use.
|
||||
For detailed installation instructions, see <a
|
||||
href="http://www.unidata.ucar.edu/netcdf/docs/building.html" >Building NetCDF</a>.
|
||||
|
||||
\subsection netcdf_format The netCDF File Format
|
||||
\section netcdf_format The netCDF File Format
|
||||
|
||||
Until version 3.6.0, all versions of netCDF employed only one binary
|
||||
data format, now referred to as netCDF classic format. NetCDF classic
|
||||
@ -189,7 +161,7 @@ using the format specification to develop independent low-level
|
||||
software for reading and writing netCDF files, because this could lead
|
||||
to compatibility problems if the format is ever modified.
|
||||
|
||||
\subsubsection select_format How to Select the Format
|
||||
\subsection select_format How to Select the Format
|
||||
|
||||
With three different base formats, care must be taken in creating data
|
||||
files to choose the correct base format.
|
||||
@ -217,7 +189,7 @@ It is also possible to change the default creation format, to convert
|
||||
a large body of code without changing every create call. C programmers
|
||||
see nc_set_default_format. Fortran programs see NF_SET_DEFAULT_FORMAT.
|
||||
|
||||
\subsubsection classic_format NetCDF Classic Format
|
||||
\subsection classic_format NetCDF Classic Format
|
||||
|
||||
The original netCDF format is identified using four bytes in the file
|
||||
header. All files in this format have “CDF\001” at the beginning of
|
||||
@ -243,7 +215,7 @@ beginning of the file. In this documentation this format is called
|
||||
Since 64-bit offset format was introduced in version 3.6.0, earlier
|
||||
versions of the netCDF library can't read 64-bit offset files.
|
||||
|
||||
\subsubsection netcdf_4_format NetCDF-4 Format
|
||||
\subsection netcdf_4_format NetCDF-4 Format
|
||||
|
||||
In version 4.0, netCDF included another new underlying format: HDF5.
|
||||
|
||||
@ -266,7 +238,7 @@ better).
|
||||
|
||||
For more discussion of format issues see The NetCDF Tutorial.
|
||||
|
||||
\subsection performance What about Performance?
|
||||
\section performance What about Performance?
|
||||
|
||||
One of the goals of netCDF is to support efficient access to small
|
||||
subsets of large datasets. To support this goal, netCDF uses direct
|
||||
@ -295,7 +267,7 @@ operations, less so in data access operations. We continue to study
|
||||
the challenge of implementing netCDF-4/HDF5 format without
|
||||
compromising performance.
|
||||
|
||||
\subsection creating_self Creating Self-Describing Data conforming to Conventions
|
||||
\section creating_self Creating Self-Describing Data conforming to Conventions
|
||||
|
||||
The mere use of netCDF is not sufficient to make data
|
||||
"self-describing" and meaningful to both humans and machines. The
|
||||
@ -319,7 +291,7 @@ conventions are often needed for local use. These should be
|
||||
contributed to the above netCDF conventions site if likely to interest
|
||||
other users in similar areas.
|
||||
|
||||
\subsection limitations Limitations of NetCDF
|
||||
\section limitations Limitations of NetCDF
|
||||
|
||||
The netCDF classic data model is widely applicable to data that can be
|
||||
organized into a collection of named array variables with named
|
||||
@ -426,9 +398,11 @@ http://hdfgroup.org/HDF5/.
|
||||
For more information about parallel-netcdf, see their web site:
|
||||
http://www.mcs.anl.gov/parallel-netcdf.
|
||||
|
||||
\section netcdf_data_set_components The Components of a NetCDF Data Set
|
||||
\page netcdf_data_set_components The Components of a NetCDF Data Set
|
||||
|
||||
\subsection data_model The Data Model
|
||||
\tableofcontents
|
||||
|
||||
\section data_model The Data Model
|
||||
|
||||
A netCDF dataset contains dimensions, variables, and attributes, which
|
||||
all have both a name and an ID number by which they are
|
||||
@ -438,7 +412,7 @@ dataset. The netCDF library allows simultaneous access to multiple
|
||||
netCDF datasets which are identified by dataset ID numbers, in
|
||||
addition to ordinary file names.
|
||||
|
||||
\subsubsection Enhanced Data Model in NetCDF-4/HDF5 Files
|
||||
\subsection Enhanced Data Model in NetCDF-4/HDF5 Files
|
||||
|
||||
Files created with the netCDF-4 format have access to an enhanced data
|
||||
model, which includes named groups. Groups, like directories in a Unix
|
||||
@ -474,7 +448,7 @@ Groups and user-defined types are only available in files created in
|
||||
the netCDF-4/HDF5 format. They are not available for classic or 64-bit
|
||||
offset format files.
|
||||
|
||||
\subsection dimensions Dimensions
|
||||
\section dimensions Dimensions
|
||||
|
||||
A dimension may be used to represent a real physical dimension, for
|
||||
example, time, latitude, longitude, or height. A dimension might also
|
||||
@ -536,7 +510,7 @@ data whose dimensions correspond to those of physical space/time
|
||||
should have a shape comprising different dimensions, even if some of
|
||||
these have the same length.
|
||||
|
||||
\subsection variables Variables
|
||||
\section variables Variables
|
||||
|
||||
Variables are used to store the bulk of the data in a netCDF
|
||||
dataset. A variable represents an array of values of the same type. A
|
||||
@ -591,7 +565,7 @@ product is variable because it involves the length of the unlimited
|
||||
dimension, which can vary. The length of the unlimited dimension is
|
||||
the number of records.
|
||||
|
||||
\subsection coordinate_variables Coordinate Variables
|
||||
\section coordinate_variables Coordinate Variables
|
||||
|
||||
It is legal for a variable to have the same name as a dimension. Such
|
||||
variables have no special meaning to the netCDF library. However there
|
||||
@ -633,7 +607,7 @@ use of coordinate variables commonly assume they are numeric vectors
|
||||
and strictly monotonic (all values are different and either increasing
|
||||
or decreasing).
|
||||
|
||||
\subsection attributes Attributes
|
||||
\section attributes Attributes
|
||||
|
||||
NetCDF attributes are used to store data about the data (ancillary
|
||||
data or metadata), similar in many ways to the information stored in
|
||||
@ -721,7 +695,7 @@ attributes. However adding new attributes to an existing classic or
|
||||
64-bit offset format dataset can incur the same expense as copying the
|
||||
dataset. For a more extensive discussion see Structure.
|
||||
|
||||
\subsection differences_atts_vars Differences between Attributes and Variables
|
||||
\section differences_atts_vars Differences between Attributes and Variables
|
||||
|
||||
In contrast to variables, which are intended for bulk data, attributes
|
||||
are intended for ancillary data, or information about the data. The
|
||||
@ -750,9 +724,9 @@ defined netCDF dimensions to index their values, or require a
|
||||
significant amount of storage, that data should be represented using
|
||||
variables rather than attributes.
|
||||
|
||||
\subsection object_name NetCDF Names
|
||||
\section object_name NetCDF Names
|
||||
|
||||
\subsubsection Permitted Characters in NetCDF Names
|
||||
\subsection Permitted Characters in NetCDF Names
|
||||
|
||||
The names of dimensions, variables and attributes (and, in netCDF-4
|
||||
files, groups, user-defined types, compound member names, and
|
||||
@ -770,7 +744,7 @@ Names that have trailing space characters are also not permitted.
|
||||
|
||||
Case is significant in netCDF names.
|
||||
|
||||
\subsubsection Name Length
|
||||
\subsection Name Length
|
||||
|
||||
A zero-length name is not allowed.
|
||||
|
||||
@ -782,12 +756,12 @@ All netCDF inquiry functions will return names of maximum size
|
||||
terminating NULL, space should be reserved for NC_MAX_NAME + 1
|
||||
characters.
|
||||
|
||||
\subsubsection NetCDF Conventions
|
||||
\subsection NetCDF Conventions
|
||||
|
||||
Some widely used conventions restrict names to only alphanumeric
|
||||
characters or underscores.
|
||||
|
||||
\subsection archival Is NetCDF a Good Archive Format?
|
||||
\section archival Is NetCDF a Good Archive Format?
|
||||
|
||||
NetCDF classic or 64-bit offset formats can be used as a
|
||||
general-purpose archive format for storing arrays. Compression of data
|
||||
@ -805,7 +779,7 @@ others not. In this case the compression and decompression of data
|
||||
happen transparently to the user, and the data may be stored, read,
|
||||
and written compressed.
|
||||
|
||||
\subsection attribute_conventions Attribute Conventions
|
||||
\section attribute_conventions Attribute Conventions
|
||||
|
||||
Attribute conventions are assumed by some netCDF generic applications,
|
||||
e.g., ‘units’ as the name for a string attribute that gives the units
|
||||
@ -821,7 +795,7 @@ character data.
|
||||
\note Attribute names commencing with underscore ('_') are reserved
|
||||
for use by the netCDF library.
|
||||
|
||||
\subsubsection units Units
|
||||
\subsection units Units
|
||||
|
||||
A character string that specifies the units used for the variable's
|
||||
data. Unidata has developed a freely-available library of routines to
|
||||
@ -832,13 +806,13 @@ recommended units syntax permits data represented in conformable units
|
||||
to be automatically converted to common units for arithmetic
|
||||
operations. For more information see Units.
|
||||
|
||||
\subsubsection long_name Long Name
|
||||
\subsection long_name Long Name
|
||||
|
||||
A long descriptive name. This could be used for labeling plots, for
|
||||
example. If a variable has no long_name attribute assigned, the
|
||||
variable name should be used as a default.
|
||||
|
||||
\subsubsection _FillValue FillValue
|
||||
\subsection _FillValue FillValue
|
||||
|
||||
The _FillValue attribute specifies the fill value used to pre-fill
|
||||
disk space allocated to the variable. Such pre-fill occurs unless
|
||||
@ -863,7 +837,7 @@ and therefore treated as missing when read by generic applications. It
|
||||
is legal (but not recommended) for the fill value to be within the
|
||||
valid range.
|
||||
|
||||
\subsubsection missing_value Missing Value
|
||||
\subsection missing_value Missing Value
|
||||
|
||||
This attribute is not treated in any special way by the library or
|
||||
conforming generic applications, but is often useful documentation and
|
||||
@ -906,7 +880,7 @@ If the variable is packed using scale_factor and add_offset attributes
|
||||
(see below), the _FillValue, missing_value, valid_range, valid_min, or
|
||||
valid_max attributes should have the data type of the packed data.
|
||||
|
||||
\subsubsection scale_factor Scale Factor
|
||||
\subsection scale_factor Scale Factor
|
||||
|
||||
If present for a variable, the data are to be multiplied by this
|
||||
factor after the data are read by the application that accesses the
|
||||
@ -918,7 +892,7 @@ specified in the domain of the data in the file (the packed data), so
|
||||
that they can be interpreted before the scale_factor and add_offset
|
||||
are applied.
|
||||
|
||||
\subsubsection add_offset Add Offset
|
||||
\subsection add_offset Add Offset
|
||||
|
||||
If present for a variable, this number is to be added to the data
|
||||
after it is read by the application that accesses the data. If both
|
||||
@ -937,7 +911,7 @@ short, whereas the unpacked values are intended to be of type float or
|
||||
double. The attributes scale_factor and add_offset should both be of
|
||||
the type intended for the unpacked data, e.g. float or double.
|
||||
|
||||
\subsubsection coordinates Coordinates
|
||||
\subsection coordinates Coordinates
|
||||
|
||||
Following the CF (Climate and Forecast) conventions for netCDF
|
||||
metadata, we define an <em>auxiliary coordinate variable</em> as any netCDF
|
||||
@ -951,7 +925,7 @@ names of auxiliary coordinate variables and (optionally) coordinate
|
||||
variables. There is no restriction on the order in which the variable
|
||||
names appear in the coordinates attribute string.
|
||||
|
||||
\subsubsection signedness Signedness
|
||||
\subsection signedness Signedness
|
||||
|
||||
Deprecated attribute, originally designed to indicate whether byte
|
||||
values should be treated as signed or unsigned. The attributes
|
||||
@ -960,7 +934,7 @@ you intend that a byte variable store only non-negative values, you
|
||||
can use valid_min = 0 and valid_max = 255. This attribute is ignored
|
||||
by the netCDF library.
|
||||
|
||||
\subsubsection C_format C Format
|
||||
\subsection C_format C Format
|
||||
|
||||
\tableofcontents
|
||||
|
||||
@ -973,19 +947,19 @@ defined. The format applies to the scaled (internal) type and value,
|
||||
regardless of the presence of the scaling attributes scale_factor and
|
||||
add_offset.
|
||||
|
||||
\subsubsection FORTRAN_format FORTRAN format
|
||||
\subsection FORTRAN_format FORTRAN format
|
||||
|
||||
A character array providing the format that should be used by FORTRAN
|
||||
applications to print values for this variable. For example, if you
|
||||
know a variable is only accurate to three significant digits, it would
|
||||
be appropriate to define the FORTRAN_format attribute as "(G10.3)".
|
||||
|
||||
\subsubsection title Title
|
||||
\subsection title Title
|
||||
|
||||
A global attribute that is a character array providing a succinct
|
||||
description of what is in the dataset.
|
||||
|
||||
\subsubsection history History
|
||||
\subsection history History
|
||||
|
||||
A global attribute for an audit trail. This is a character array with
|
||||
a line for each invocation of a program that has modified the
|
||||
@ -993,7 +967,7 @@ dataset. Well-behaved generic netCDF applications should append a line
|
||||
containing: date, time of day, user name, program name and command
|
||||
arguments.
|
||||
|
||||
\subsubsection Conventions Conventions
|
||||
\subsection Conventions Conventions
|
||||
|
||||
If present, 'Conventions' is a global attribute that is a character
|
||||
array for the name of the conventions followed by the
|
||||
@ -1038,7 +1012,7 @@ Typical conventions web sites will include references to documents in
|
||||
some form agreed upon by the community that supports the conventions
|
||||
and examples of netCDF file structures that follow the conventions.
|
||||
|
||||
\subsection background Background and Evolution of the NetCDF Interface
|
||||
\section background Background and Evolution of the NetCDF Interface
|
||||
|
||||
The development of the netCDF interface began with a modest goal
|
||||
related to Unidata's needs: to provide a common interface between
|
||||
@ -1263,12 +1237,12 @@ application is also included that provides a graphical user interface
|
||||
to capabilities similar to the C-based ncdump and ncgen utilities, as
|
||||
well as CF-compliance checking and many other features.
|
||||
|
||||
\subsection remote_client The Remote Data Access Client
|
||||
\section remote_client The Remote Data Access Client
|
||||
|
||||
Starting with version 4.1.1 the netCDF C libraries and utilities have
|
||||
supported remote data access.
|
||||
|
||||
\subsection data_access Data Access
|
||||
\section data_access Data Access
|
||||
|
||||
To access (read or write) netCDF data you specify an open netCDF
|
||||
dataset, a netCDF variable, and information (e.g., indices)
|
||||
@ -1297,7 +1271,7 @@ Similarly, a variable is not specified by name for every data access
|
||||
either, but by a variable ID, a small integer used to identify each
|
||||
variable in a netCDF dataset.
|
||||
|
||||
\subsection forms_of_data_access Forms of Data Access
|
||||
\section forms_of_data_access Forms of Data Access
|
||||
|
||||
The netCDF interface supports several forms of direct access to data
|
||||
values in an open netCDF dataset. We describe each of these forms of
|
||||
@ -1344,7 +1318,7 @@ The use of mapped array sections is discussed more fully below, but
|
||||
first we present an example of the more commonly used array-section
|
||||
access.
|
||||
|
||||
\subsection c_array_section_access A C Example of Array-Section Access
|
||||
\section c_array_section_access A C Example of Array-Section Access
|
||||
|
||||
Assume that in our earlier example of a netCDF dataset (see Network
|
||||
Common Data Form Language (CDL)), we wish to read a cross-section of
|
||||
@ -1476,11 +1450,13 @@ required. If you do not need these more general forms of access, you
|
||||
may ignore these capabilities and use single value access or regular
|
||||
array section access instead.
|
||||
|
||||
\section file_structure_and_performance File Structure and Performance
|
||||
\page file_structure_and_performance File Structure and Performance
|
||||
|
||||
\tableofcontents
|
||||
|
||||
\todo Indent the following part below this.
|
||||
|
||||
\section classic_file_parts Parts of a NetCDF Classic File
|
||||
\section classic_file_parts Parts of a NetCDF Classic File
|
||||
|
||||
A netCDF classic or 64-bit offset dataset is stored as a single file
|
||||
comprising two parts:
|
||||
@ -2081,7 +2057,7 @@ within grids are left out in order to mimic the behavior of libnc-dap.
|
||||
lon
|
||||
\endcode
|
||||
|
||||
\subsubsection var_dim_trans Variable Dimension Translation
|
||||
\subsection var_dim_trans Variable Dimension Translation
|
||||
|
||||
A variable's rank is determined from three sources.
|
||||
- The variable has the dimensions associated with the field it
|
||||
@ -2175,7 +2151,7 @@ dimensions:
|
||||
S1.FS2.f2_0 = 2 ;
|
||||
\endcode
|
||||
|
||||
\subsubsection var_name_trans Variable Name Translation
|
||||
\subsection var_name_trans Variable Name Translation
|
||||
|
||||
The steps for variable name translation are as follows.
|
||||
|
||||
@ -2523,6 +2499,10 @@ entries should have same value, which is the file path for the
|
||||
certificate produced by MyProxyLogon. The HTTP.SSL.CAPATH entry should
|
||||
be the path to the "certificates" directory produced by MyProxyLogon.
|
||||
|
||||
\page netcdf_perf_chunking Improving Performance with Chunking
|
||||
|
||||
\tableofcontents
|
||||
|
||||
\section chunk_cache The Chunk Cache
|
||||
|
||||
When data are first read or written to a netCDF-4/HDF5 variable, the
|
||||
@ -2674,7 +2654,11 @@ The bm_file program is controlled with command line options.
|
||||
file Name of netCDF file
|
||||
</pre>
|
||||
|
||||
\section netcdf_utilities_guide Netcdf Utilities
|
||||
\page netcdf_utilities_guide NetCDF Utilities
|
||||
|
||||
\tableofcontents
|
||||
|
||||
\section cdl_guide CDL Guide
|
||||
|
||||
\subsection cdl_syntax CDL Syntax
|
||||
|
||||
@ -3000,11 +2984,11 @@ extended as necessary.
|
||||
The ncgen man-page reference has more details about CDL representation
|
||||
of constants of user-defined types.
|
||||
|
||||
\subsection guide_ncdump ncdump
|
||||
\section guide_ncdump ncdump
|
||||
|
||||
\brief Convert netCDF file to text form (CDL)
|
||||
Convert NetCDF file to text form (CDL)
|
||||
|
||||
\subsubsection ncdump_SYNOPSIS ncdump synopsis
|
||||
\subsection ncdump_SYNOPSIS ncdump synopsis
|
||||
|
||||
\code
|
||||
ncdump [-chistxw] [-v var1,...] [-b lang] [-f lang]
|
||||
@ -3014,7 +2998,7 @@ ncdump [-chistxw] [-v var1,...] [-b lang] [-f lang]
|
||||
ncdump -k file
|
||||
\endcode
|
||||
|
||||
\subsubsection ncdump_DESCRIPTION ncdump description
|
||||
\subsection ncdump_DESCRIPTION ncdump description
|
||||
|
||||
The \b ncdump utility generates a text representation of a specified
|
||||
netCDF file on standard output, optionally excluding some or all of
|
||||
@ -3061,7 +3045,7 @@ be appropriate to use the variable attribute
|
||||
Z:C_format = "%.3g"
|
||||
\endcode
|
||||
|
||||
\subsubsection ncdump_OPTIONS ncdump options
|
||||
\subsection ncdump_OPTIONS ncdump options
|
||||
|
||||
@par -c
|
||||
Show the values of \e coordinate \e variables (1D variables with the
|
||||
@ -3212,7 +3196,7 @@ with client-side caching of entire variables.
|
||||
Output XML (NcML) instead of CDL. The NcML does not include data values.
|
||||
The NcML output option currently only works for netCDF classic model data.
|
||||
|
||||
\subsubsection ncdump_EXAMPLES ncdump examples
|
||||
\subsection ncdump_EXAMPLES ncdump examples
|
||||
|
||||
Look at the structure of the data in the netCDF file foo.nc:
|
||||
|
||||
@ -3257,26 +3241,26 @@ performance-related characterisitics of a netCDF-4 file:
|
||||
ncdump -h -s nc4file.nc
|
||||
\endcode
|
||||
|
||||
\subsubsection see_also_ncdump SEE ALSO
|
||||
\subsection see_also_ncdump SEE ALSO
|
||||
|
||||
ncgen(1), netcdf(3)
|
||||
|
||||
- \ref guide_ncgen
|
||||
- \ref guide_nccopy
|
||||
|
||||
\subsubsection ncdump_string_note NOTE ON STRING OUTPUT
|
||||
\subsection ncdump_string_note NOTE ON STRING OUTPUT
|
||||
|
||||
For classic, 64-bit offset or netCDF-4 classic model data, \b ncdump
|
||||
generates line breaks after embedded newlines in displaying character
|
||||
data. This is not done for netCDF-4 files, because netCDF-4 supports
|
||||
arrays of real strings of varying length.
|
||||
|
||||
\subsection guide_nccopy nccopy
|
||||
\section guide_nccopy nccopy
|
||||
|
||||
\brief Copy a netCDF file, optionally changing format, compression, or chunking in the output.
|
||||
Copy a netCDF file, optionally changing format, compression, or chunking in the output.
|
||||
|
||||
|
||||
\subsubsection nccopy_SYNOPSIS nccopy synopsis
|
||||
\subsection nccopy_SYNOPSIS nccopy synopsis
|
||||
|
||||
\code
|
||||
nccopy [-k kind] [-d n] [-s] [-c chunkspec] [-u] [-w] [-[v|V] var1,...]
|
||||
@ -3284,7 +3268,7 @@ nccopy [-k kind] [-d n] [-s] [-c chunkspec] [-u] [-w] [-[v|V] var1,...]
|
||||
[-r] infile outfile
|
||||
\endcode
|
||||
|
||||
\subsubsection nccopy_DESCRIPTION nccopy description
|
||||
\subsection nccopy_DESCRIPTION nccopy description
|
||||
|
||||
The \b nccopy utility copies an input netCDF file in any supported
|
||||
format variant to an output netCDF file, optionally converting the
|
||||
@ -3307,7 +3291,7 @@ If DAP support was enabled when \b nccopy was built, the file name may
|
||||
specify a DAP URL. This may be used to convert data on DAP servers to
|
||||
local netCDF files.
|
||||
|
||||
\subsubsection nccopy_OPTIONS nccopy options
|
||||
\subsection nccopy_OPTIONS nccopy options
|
||||
|
||||
\par -k \e kind
|
||||
Specifies the kind of file to be created (that is, the format variant)
|
||||
@ -3508,7 +3492,7 @@ file in memory before copying. Requires that input file be small
|
||||
enough to fit into memory. For \b nccopy, this doesn't seem to provide
|
||||
any significant speedup, so may not be a useful option.
|
||||
|
||||
\subsubsection nccopy_EXAMPLES nccopy examples
|
||||
\subsection nccopy_EXAMPLES nccopy examples
|
||||
|
||||
<H4> Simple Copy </H4>
|
||||
Make a copy of foo1.nc, a netCDF file of any type, to
|
||||
@ -3582,11 +3566,11 @@ memory before writing it to disk on close:
|
||||
nccopy -w -c time/1000,lat/40,lon/40 slow.nc fast.nc
|
||||
\endcode
|
||||
|
||||
\subsubsection see_also_nccopy SEE ALSO
|
||||
\subsection see_also_nccopy SEE ALSO
|
||||
|
||||
ncdump(1), ncgen(1), netcdf(3)
|
||||
|
||||
\subsection guide_ncgen ncgen
|
||||
\section guide_ncgen ncgen
|
||||
|
||||
The ncgen tool generates a netCDF file or a C or FORTRAN program that
|
||||
creates a netCDF dataset. If no options are specified in invoking
|
||||
@ -3688,7 +3672,7 @@ dataset:
|
||||
ncgen -l c foo.cdl > foo.c
|
||||
\endcode
|
||||
|
||||
\subsection guide_ncgen3 ncgen3
|
||||
\section guide_ncgen3 ncgen3
|
||||
|
||||
The ncgen3 tool is the new name for the older, original ncgen utility.
|
||||
|
||||
@ -3753,8 +3737,11 @@ faster, but it will also eliminate the possibility of detecting the
|
||||
inadvertent reading of values that haven't been written.
|
||||
</pre>
|
||||
|
||||
\page file_format_specifications File Format Specifications
|
||||
|
||||
\section file_format_spec_guide NetCDF File Format Specification
|
||||
\tableofcontents
|
||||
|
||||
\todo Wrap the following group of pages into this. From NetCDF Classic Format Spec through HDF4 SD Format.
|
||||
|
||||
\section classic_format_spec The NetCDF Classic Format Specification
|
||||
|
||||
@ -4063,7 +4050,7 @@ A special case: Where there is exactly one record variable, we drop
|
||||
the requirement that each record be four-byte aligned, so in this case
|
||||
there is no record padding.
|
||||
|
||||
\section offset_examples Examples
|
||||
\subsection offset_examples Examples
|
||||
|
||||
By using the grammar above, we can derive the smallest valid netCDF
|
||||
file, having no dimensions, no variables, no attributes, and hence, no
|
||||
|
||||
@ -25,7 +25,7 @@ The NetCDF homepage may be found at <a href="http://www.unidata.ucar.edu/netcdf"
|
||||
|
||||
\subsection learn-more Learn more about using NetCDF-C
|
||||
|
||||
- \ref tutorial
|
||||
- \ref sec_tut
|
||||
- \ref user_guide
|
||||
- \ref netcdf_working_with_netcdf_files
|
||||
- <a class="el" href="http://www.unidata.ucar.edu/software/netcdf/docs/index-413.html">Older Documentation, plus details regarding netcdf-fortran and netcdf-cxx.</a>
|
||||
|
||||
@ -1,6 +1,8 @@
|
||||
/*!
|
||||
/*! \file tutorial.dox The NetCDF-C Tutorial
|
||||
|
||||
\page tutorial NetCDF Tutorials
|
||||
\brief The NetCDF-C Tutorial
|
||||
|
||||
\mainpage
|
||||
|
||||
\tableofcontents
|
||||
|
||||
@ -349,7 +351,7 @@ information about the CF conventions, see http://cf-pcmdi.llnl.gov.
|
||||
|
||||
\page error_handling Error Handling
|
||||
|
||||
\ingroup error
|
||||
\addtogroup error
|
||||
|
||||
Each netCDF function in the C, Fortran 77, and Fortran 90 APIs returns
|
||||
0 on success, in the tradition of C.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user