diff options
Diffstat (limited to 'doxygen')
211 files changed, 21280 insertions, 13008 deletions
diff --git a/doxygen/CMakeLists.txt b/doxygen/CMakeLists.txt index c1a2071..86d34a3 100644 --- a/doxygen/CMakeLists.txt +++ b/doxygen/CMakeLists.txt @@ -7,11 +7,12 @@ project (HDF5_DOXYGEN C) if (DOXYGEN_FOUND) set (DOXYGEN_PACKAGE ${HDF5_PACKAGE_NAME}) set (DOXYGEN_VERSION_STRING ${HDF5_PACKAGE_VERSION_STRING}) + set (DOXYGEN_DIR ${HDF5_DOXYGEN_DIR}) set (DOXYGEN_INCLUDE_ALIASES_PATH ${HDF5_DOXYGEN_DIR}) set (DOXYGEN_INCLUDE_ALIASES aliases) set (DOXYGEN_VERBATIM_VARS DOXYGEN_INCLUDE_ALIASES) set (DOXYGEN_PROJECT_LOGO ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png) - set (DOXYGEN_PROJECT_BRIEF "C-API Reference") + set (DOXYGEN_PROJECT_BRIEF "API Reference") set (DOXYGEN_INPUT_DIRECTORY "${HDF5_SOURCE_DIR} ${HDF5_DOXYGEN_DIR}/dox ${HDF5_GENERATED_SOURCE_DIR}") set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) set (DOXYGEN_MACRO_EXPANSION YES) @@ -28,7 +29,7 @@ if (DOXYGEN_FOUND) set (DOXYGEN_SEARCHENGINE_URL) set (DOXYGEN_STRIP_FROM_PATH ${HDF5_SOURCE_DIR}) set (DOXYGEN_STRIP_FROM_INC_PATH ${HDF5_SOURCE_DIR}) - set (DOXYGEN_PREDEFINED "H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD H5_HAVE_SUBFILING_VFD H5_HAVE_IOC_VFD") + set (DOXYGEN_PREDEFINED "H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD H5_DOXYGEN_FORTRAN H5_HAVE_SUBFILING_VFD H5_HAVE_IOC_VFD") # This configure and individual custom targets work together # Replace variables inside @@ with the current values diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 7657fa5..08f5545 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -280,13 +280,13 @@ OPTIMIZE_OUTPUT_FOR_C = YES # qualified scopes will look different, etc. # The default value is: NO. -OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_OUTPUT_JAVA = YES # Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran # sources. Doxygen will then generate output that is tailored for Fortran. # The default value is: NO. -OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_FOR_FORTRAN = YES # Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL # sources. Doxygen will then generate output that is tailored for VHDL. @@ -875,7 +875,11 @@ FILE_PATTERNS = H5*public.h \ H5VLconnector.h \ H5VLconnector_passthru.h \ H5VLnative.h \ + H5Zdevelop.h \ H5version.h \ + H5*.java \ + HDF*.java \ + *.F90 \ *.dox # The RECURSIVE tag can be used to specify whether or not subdirectories should @@ -944,7 +948,7 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = @HDF5_DOXYGEN_DIR@/img +IMAGE_PATH = @DOXYGEN_DIR@/img # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program diff --git a/doxygen/aliases b/doxygen/aliases index 6730be5..5ee60d5 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -379,4 +379,4 @@ ALIASES += obj_info_fields="<table><tr><th>Flag</th><th>Purpose</th></tr><tr><td ALIASES += fortran_error="Returns 0 if successful and -1 if it fails." ALIASES += fortran_approved="The preferred API, Fortran 2003 version." -ALIASES += fortran_obsolete="Obsolete API, use the Fortran 2003 version instead."
\ No newline at end of file +ALIASES += fortran_obsolete="Obsolete API, use the Fortran 2003 version instead." diff --git a/doxygen/dox/DDLBNF110.dox b/doxygen/dox/DDLBNF110.dox index f7e4267..6d6b67e 100644 --- a/doxygen/dox/DDLBNF110.dox +++ b/doxygen/dox/DDLBNF110.dox @@ -126,7 +126,7 @@ This section contains a brief explanation of the symbols used in the DDL. <reference> ::= H5T_REFERENCE { <ref_type> } -<ref_type> ::= H5T_STD_REF_OBJECT | H5T_STD_REF_DSETREG | H5T_STD_REF | UNDEFINED +<ref_type> ::= H5T_STD_REF_OBJECT | H5T_STD_REF_DSETREG <compound_type> ::= H5T_COMPOUND { <member_type_def>+ diff --git a/doxygen/dox/FileFormatSpec.dox b/doxygen/dox/FileFormatSpec.dox new file mode 100644 index 0000000..fc10574 --- /dev/null +++ b/doxygen/dox/FileFormatSpec.dox @@ -0,0 +1,23 @@ +/** \page FMT3 HDF5 File Format Specification Version 3.0 + +\htmlinclude H5.format.html + +*/ + +/** \page FMT2 HDF5 File Format Specification Version 2.0 + +\htmlinclude H5.format.2.0.html + +*/ + +/** \page FMT11 HDF5 File Format Specification Version 1.1 + +\htmlinclude H5.format.1.1.html + +*/ + +/** \page FMT1 HDF5 File Format Specification Version 1.0 + +\htmlinclude H5.format.1.0.html + +*/
\ No newline at end of file diff --git a/doxygen/dox/GettingStarted.dox b/doxygen/dox/GettingStarted.dox index 880491d..29c5033 100644 --- a/doxygen/dox/GettingStarted.dox +++ b/doxygen/dox/GettingStarted.dox @@ -1,3 +1,100 @@ -/** \page GettingStarted \Code{Hello, HDF5!} +/** @page GettingStarted Getting Started with HDF5 - */
\ No newline at end of file +Navigate back: \ref index "Main" +<hr> + +\section sec_learn Learning HDF5 +There are several resources for learning about HDF5. The HDF Group provides an on-line HDF5 tutorial, +documentation, examples, and videos. There are also tutorials provided by other organizations that are very useful for learning about HDF5. + +\subsection subsec_learn_intro The HDF Group Resources +For a quick introduction to HDF5 see the following: +<table> +<tr> +<td style="background-color:#F5F5F5"> +@ref IntroHDF5 +</td> +<td> +A very brief introduction to HDF5 and the HDF5 programming model and APIs +</td> +</tr> +<tr> +<td style="background-color:#F5F5F5"> +@ref LearnHDFView +</td> +<td> +A tutorial for learning how to use HDFView. NO programming involved! +</td> +</tr> +<tr> +<td style="background-color:#F5F5F5"> +@ref LearnBasics +</td> +<td> +Step by step instructions for learning HDF5 that include programming examples +</td> +</tr> +</table> + +\subsection subsec_learn_tutor The HDF Group Tutorials and Examples +These tutorials and examples are available for learning about the HDF5 High Level APIs, tools, +Parallel HDF5, and the HDF5-1.10 VDS and SWMR new features: +<table> +<tr> +<td style="background-color:#F5F5F5"> +<a href="https://portal.hdfgroup.org/display/HDF5/Introduction+to+the+HDF5+High+Level+APIs">Using the High Level APIs</a> +</td> +<td> +\ref H5LT \ref H5IM \ref H5TB \ref H5PT \ref H5DS +</td> +</tr> +<tr> +<td style="background-color:#F5F5F5"> +<a href="https://portal.hdfgroup.org/display/HDF5/Introduction+to+Parallel+HDF5">Introduction to Parallel HDF5</a> +</td> +<td> +A brief introduction to Parallel HDF5. If you are new to HDF5 please see the @ref LearnBasics topic first. +</td> +</tr> +<tr> +<td style="background-color:#F5F5F5"> +\ref ViewTools +</td> +<td> +\li @ref LearnHDFView +\li @ref ViewToolsCommand +\li @ref ViewToolsJPSS +</td> +</tr> +<tr> +<td style="background-color:#F5F5F5"> +HDF5-1.10 New Features +</td> +<td> +\li <a href="https://portal.hdfgroup.org/display/HDF5/Introduction+to+the+Virtual+Dataset++-+VDS">Introduction to the Virtual Dataset - VDS</a> +\li <a href="https://portal.hdfgroup.org/pages/viewpage.action?pageId=48812567">Introduction to Single-Writer/Multiple-Reader (SWMR)</a> +</td> +</tr> +<tr> +<td style="background-color:#F5F5F5"> +Example Programs +</td> +<td> +\ref HDF5Examples +</td> +</tr> +<tr> +<td style="background-color:#F5F5F5"> +Videos +</td> +<td> +\li <a href="https://www.youtube.com/watch?v=BAjsCldRMMc">Introduction to HDF5</a> +\li <a href="https://www.youtube.com/watch?v=qrI27pI0P1E">Parallel HDF5</a> +</td> +</tr> +</table> + +<hr> +Navigate back: \ref index "Main" + +*/ diff --git a/doxygen/dox/IntroHDF5.dox b/doxygen/dox/IntroHDF5.dox new file mode 100644 index 0000000..ec46217 --- /dev/null +++ b/doxygen/dox/IntroHDF5.dox @@ -0,0 +1,627 @@ +/** @page IntroHDF5 Introduction to HDF5 + +Navigate back: \ref index "Main" / \ref GettingStarted +<hr> + +\section sec_intro_desc HDF5 Description +HDF5 consists of a file format for storing HDF5 data, a data model for logically organizing and accessing +HDF5 data from an application, and the software (libraries, language interfaces, and tools) for working with this format. + +\subsection subsec_intro_desc_file File Format +HDF5 consists of a file format for storing HDF5 data, a data model for logically organizing and accessing HDF5 data from an application, +and the software (libraries, language interfaces, and tools) for working with this format. + +\subsection subsec_intro_desc_dm Data Model +The HDF5 Data Model, also known as the HDF5 Abstract (or Logical) Data Model consists of +the building blocks for data organization and specification in HDF5. + +An HDF5 file (an object in itself) can be thought of as a container (or group) that holds +a variety of heterogeneous data objects (or datasets). The datasets can be images, tables, +graphs, and even documents, such as PDF or Excel: + +<table> +<tr> +<td> +\image html fileobj.png +</td> +</tr> +</table> + +The two primary objects in the HDF5 Data Model are groups and datasets. + +There are also a variety of other objects in the HDF5 Data Model that support groups and datasets, +including datatypes, dataspaces, properties and attributes. + +\subsubsection subsec_intro_desc_dm_group Groups +HDF5 groups (and links) organize data objects. Every HDF5 file contains a root group that can +contain other groups or be linked to objects in other files. + +<table> +<caption>There are two groups in the HDF5 file depicted above: Viz and SimOut. +Under the Viz group are a variety of images and a table that is shared with the SimOut group. +The SimOut group contains a 3-dimensional array, a 2-dimensional array and a link to a 2-dimensional +array in another HDF5 file.</caption> +<tr> +<td> +\image html group.png +</td> +</tr> +</table> + +Working with groups and group members is similar in many ways to working with directories and files +in UNIX. As with UNIX directories and files, objects in an HDF5 file are often described by giving +their full (or absolute) path names. +\li / signifies the root group. +\li /foo signifies a member of the root group called foo. +\li /foo/zoo signifies a member of the group foo, which in turn is a member of the root group. + +\subsubsection subsec_intro_desc_dm_dset Datasets +HDF5 datasets organize and contain the “raw” data values. A dataset consists of metadata +that describes the data, in addition to the data itself: + +<table> +<caption>In this picture, the data is stored as a three dimensional dataset of size 4 x 5 x 6 with an integer datatype. +It contains attributes, Time and Pressure, and the dataset is chunked and compressed.</caption> +<tr> +<td> +\image html dataset.png +</td> +</tr> +</table> + +Datatypes, dataspaces, properties and (optional) attributes are HDF5 objects that describe a dataset. +The datatype describes the individual data elements. + +\subsection subsec_intro_desc_props Datatypes, Dataspaces, Properties and Attributes + +\subsubsection subsec_intro_desc_prop_dtype Datatypes +The datatype describes the individual data elements in a dataset. It provides complete information for +data conversion to or from that datatype. + +<table> +<caption>In the dataset depicted, each element of the dataset is a 32-bit integer.</caption> +<tr> +<td> +\image html datatype.png +</td> +</tr> +</table> + +Datatypes in HDF5 can be grouped into: +<ul> +<li> +<b>Pre-Defined Datatypes</b>: These are datatypes that are created by HDF5. They are actually opened (and closed) +by HDF5 and can have different values from one HDF5 session to the next. There are two types of pre-defined datatypes: +<ul> +<li> +Standard datatypes are the same on all platforms and are what you see in an HDF5 file. Their names are of the form +H5T_ARCH_BASE where ARCH is an architecture name and BASE is a programming type name. For example, #H5T_IEEE_F32BE +indicates a standard Big Endian floating point type. +</li> +<li> +Native datatypes are used to simplify memory operations (reading, writing) and are NOT the same on different platforms. +For example, #H5T_NATIVE_INT indicates an int (C). +</li> +</ul> +</li> +<li> +<b>Derived Datatypes</b>: These are datatypes that are created or derived from the pre-defined datatypes. +An example of a commonly used derived datatype is a string of more than one character. Compound datatypes +are also derived types. A compound datatype can be used to create a simple table, and can also be nested, +in which it includes one more other compound datatypes. +<table> +<caption>This is an example of a dataset with a compound datatype. Each element in the dataset consists +of a 16-bit integer, a character, a 32-bit integer, and a 2x3x2 array of 32-bit floats (the datatype). +It is a 2-dimensional 5 x 3 array (the dataspace). The datatype should not be confused with the dataspace. +</caption> +<tr> +<td> +\image html cmpnddtype.png +</td> +</tr> +</table> +</li> +</ul> + +\subsubsection subsec_intro_desc_prop_dspace Dataspaces +A dataspace describes the layout of a dataset’s data elements. It can consist of no elements (NULL), +a single element (scalar), or a simple array. + +<table> +<caption>This image illustrates a dataspace that is an array with dimensions of 5 x 3 and a rank (number of dimensions) of 2.</caption> +<tr> +<td> +\image html dataspace1.png +</td> +</tr> +</table> + +A dataspace can have dimensions that are fixed (unchanging) or unlimited, which means they can grow +in size (i.e. they are extendible). + +There are two roles of a dataspace: +\li It contains the spatial information (logical layout) of a dataset stored in a file. This includes the rank and dimensions of a dataset, which are a permanent part of the dataset definition. +\li It describes an application’s data buffers and data elements participating in I/O. In other words, it can be used to select a portion or subset of a dataset. + +<table> +<caption>The dataspace is used to describe both the logical layout of a dataset and a subset of a dataset.</caption> +<tr> +<td> +\image html dataspace.png +</td> +</tr> +</table> + +\subsubsection subsec_intro_desc_prop_property Properties +A property is a characteristic or feature of an HDF5 object. There are default properties which +handle the most common needs. These default properties can be modified using the HDF5 Property +List API to take advantage of more powerful or unusual features of HDF5 objects. + +<table> +<tr> +<td> +\image html properties.png +</td> +</tr> +</table> + +For example, the data storage layout property of a dataset is contiguous by default. For better +performance, the layout can be modified to be chunked or chunked and compressed: + +\subsubsection subsec_intro_desc_prop_attr Attributes +Attributes can optionally be associated with HDF5 objects. They have two parts: a name and a value. +Attributes are accessed by opening the object that they are attached to so are not independent objects. +Typically an attribute is small in size and contains user metadata about the object that it is attached to. + +Attributes look similar to HDF5 datasets in that they have a datatype and dataspace. However, they +do not support partial I/O operations, and they cannot be compressed or extended. + +\subsection subsec_intro_desc_soft HDF5 Software +The HDF5 software is written in C and includes optional wrappers for C++, FORTRAN (90 and F2003), +and Java. The HDF5 binary distribution consists of the HDF5 libraries, include files, command-line +utilities, scripts for compiling applications, and example programs. + +\subsubsection subsec_intro_desc_soft_apis HDF5 APIs and Libraries +There are APIs for each type of object in HDF5. For example, all C routines in the HDF5 library +begin with a prefix of the form H5*, where * is one or two uppercase letters indicating the type +of object on which the function operates: +\li @ref H5A <b>A</b>ttribute Interface +\li @ref H5D <b>D</b>ataset Interface +\li @ref H5F <b>F</b>ile Interface + +The HDF5 High Level APIs simplify many of the steps required to create and access objects, as well +as providing templates for storing objects. Following is a list of the High Level APIs: +\li @ref H5LT – simplifies steps in creating datasets and attributes +\li @ref H5IM – defines a standard for storing images in HDF5 +\li @ref H5TB – condenses the steps required to create tables +\li @ref H5DS – provides a standard for dimension scale storage +\li @ref H5PT – provides a standard for storing packet data + +\subsubsection subsec_intro_desc_soft_tools Tools +Useful tools for working with HDF5 files include: +\li h5dump: A utility to dump or display the contents of an HDF5 File +\li h5cc, h5c++, h5fc: Unix scripts for compiling applications +\li HDFView: A java browser to view HDF (HDF4 and HDF5) files + +<h4>h5dump</h4> +The h5dump utility displays the contents of an HDF5 file in Data Description Language (\ref DDLBNF110). +Below is an example of h5dump output for an HDF5 file that contains no objects: +\code +$ h5dump file.h5 + HDF5 "file.h5" { + GROUP "/" { + } + } +\endcode + +With large files and datasets the output from h5dump can be overwhelming. +There are options that can be used to examine specific parts of an HDF5 file. +Some useful h5dump options are included below: +\code + -H, --header Display header information only (no data) + -d <name> Display a dataset with a specified path and name + -p Display properties + -n Display the contents of the file +\endcode + +<h4>h5cc, h5fc, h5c++</h4> +The built HDF5 binaries include the h5cc, h5fc, h5c++ compile scripts for compiling applications. +When using these scripts there is no need to specify the HDF5 libraries and include files. +Compiler options can be passed to the scripts. + +<h4>HDFView</h4> +The HDFView tool allows browsing of data in HDF (HDF4 and HDF5) files. + +\section sec_intro_pm Introduction to the HDF5 Programming Model and APIs +The HDF5 Application Programming Interface is extensive, but a few functions do most of the work. + +To introduce the programming model, examples in Python and C are included below. The Python examples +use the HDF5 Python APIs (h5py). See the Examples from "Learning the Basics" page for complete examples +that can be downloaded and run for C, FORTRAN, C++, Java and Python. + +The general paradigm for working with objects in HDF5 is to: +\li Open the object. +\li Access the object. +\li Close the object. + +The library imposes an order on the operations by argument dependencies. For example, a file must be +opened before a dataset because the dataset open call requires a file handle as an argument. Objects +can be closed in any order. However, once an object is closed it no longer can be accessed. + +Keep the following in mind when looking at the example programs included in this section: +<ul> +<li> +<ul> +<li> +C routines begin with the prefix “H5*” where * is a single letter indicating the object on which the +operation is to be performed. +</li> +<li> +FORTRAN routines are similar; they begin with “h5*” and end with “_f”. +</li> +<li> +Java routines are similar; the routine names begin with “H5*” and are prefixed with “H5.” as the class. Constants are +in the HDF5Constants class and are prefixed with "HDF5Constants.". The function arguments +are usually similar, @see @ref HDF5LIB +</li> +</ul> +For example: +<ul> +<li> +File Interface:<ul><li>#H5Fopen (C)</li><li>h5fopen_f (FORTRAN)</li><li>H5.H5Fopen (Java)</li></ul> +</li> +<li> +Dataset Interface:<ul><li>#H5Dopen (C)</li><li>h5dopen_f (FORTRAN)</li><li>H5.H5Dopen (Java)</li></ul> +</li> +<li> +Dataspace interface:<ul><li>#H5Sclose (C)</li><li>h5sclose_f (FORTRAN)</li><li>H5.H5Sclose (Java)</li></ul> +</li> +</ul> +The HDF5 Python APIs use methods associated with specific objects. +</li> +<li> +For portability, the HDF5 library has its own defined types. Some common types that you will see +in the example code are: +<ul> +<li> +#hid_t is used for object handles +</li> +<li> +hsize_t is used for dimensions +</li> +<li> +#herr_t is used for many return values +</li> +</ul> +</li> +<li> +Language specific files must be included in applications: +<ul> +<li> +Python: Add <code>"import h5py / import numpy"</code> +</li> +<li> +C: Add <code>"#include hdf5.h"</code> +</li> +<li> +FORTRAN: Add <code>"USE HDF5"</code> and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface +</li> +<li> +Java: Add <code>"import hdf.hdf5lib.H5; + import hdf.hdf5lib.HDF5Constants;"</code> +</li> +</ul> +</li> +</ul> + +\subsection subsec_intro_pm_file Steps to create a file +To create an HDF5 file you must: +\li Specify property lists (or use the defaults). +\li Create the file. +\li Close the file (and property lists if needed). + +Example: +<table> +<caption>The following Python and C examples create a file, file.h5, and then close it. +The resulting HDF5 file will only contain a root group:</caption> +<tr> +<td> +\image html crtf-pic.png +</td> +</tr> +</table> + +Calling h5py.File with ‘w’ for the file access flag will create a new HDF5 file and overwrite +an existing file with the same name. “file” is the file handle returned from opening the file. +When finished with the file, it must be closed. When not specifying property lists, the default +property lists are used: + +<table> +<tr> +<td> +<em>Python</em> +\code + import h5py + file = h5py.File (‘file.h5’, ‘w’) + file.close () +\endcode +</td> +</tr> +</table> + +The H5Fcreate function creates an HDF5 file. #H5F_ACC_TRUNC is the file access flag to create a new +file and overwrite an existing file with the same name, and #H5P_DEFAULT is the value specified to +use a default property list. + +<table> +<tr> +<td> +<em>C</em> +\code + #include “hdf5.h” + + int main() { + hid_t file_id; + herr_t status; + + file_id = H5Fcreate ("file.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + status = H5Fclose (file_id); + } +\endcode +</td> +</tr> +</table> + +\subsection subsec_intro_pm_dataset Steps to create a dataset +As described previously, an HDF5 dataset consists of the raw data, as well as the metadata that +describes the data (datatype, spatial information, and properties). To create a dataset you must: +\li Define the dataset characteristics (datatype, dataspace, properties). +\li Decide which group to attach the dataset to. +\li Create the dataset. +\li Close the dataset handle from step 3. + +Example: +<table> +<caption>The code excerpts below show the calls that need to be made to create a 4 x 6 integer dataset dset +in a file dset.h5. The dataset will be located in the root group:</caption> +<tr> +<td> +\image html crtdset.png +</td> +</tr> +</table> + +With Python, the creation of the dataspace is included as a parameter in the dataset creation method. +Just one call will create a 4 x 6 integer dataset dset. A pre-defined Big Endian 32-bit integer datatype +is specified. The create_dataset method creates the dataset in the root group (the file object). +The dataset is close by the Python interface. + +<table> +<tr> +<td> +<em>Python</em> +\code + dataset = file.create_dataset("dset",(4, 6), h5py.h5t.STD_I32BE) +\endcode +</td> +</tr> +</table> + +To create the same dataset in C, you must specify the dataspace with the #H5Screate_simple function, +create the dataset by calling #H5Dcreate, and then close the dataspace and dataset with calls to #H5Dclose +and #H5Sclose. #H5P_DEFAULT is specified to use a default property list. Note that the file identifier +(file_id) is passed in as the first parameter to #H5Dcreate, which creates the dataset in the root group. + +<table> +<tr> +<td> +<em>C</em> +\code + // Create the dataspace for the dataset. + dims[0] = 4; + dims[1] = 6; + + dataspace_id = H5Screate_simple(2, dims, NULL); + + // Create the dataset. + dataset_id = H5Dcreate (file_id, "/dset", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + + // Close the dataset and dataspace + status = H5Dclose(dataset_id); + status = H5Sclose(dataspace_id); +\endcode +</td> +</tr> +</table> + +\subsection subsec_intro_pm_write Writing to or reading from a dataset +Once you have created or opened a dataset you can write to it: + +<table> +<tr> +<td> +<em>Python</em> +\code + data = np.zeros((4,6)) + for i in range(4): + for j in range(6): + data[i][j]= i*6+j+1 + + dataset[...] = data <-- Write data to dataset + data_read = dataset[...] <-- Read data from dataset +\endcode +</td> +</tr> +</table> + +#H5S_ALL is passed in for the memory and file dataspace parameters to indicate that the entire dataspace +of the dataset is specified. These two parameters can be modified to allow subsetting of a dataset. +The native predefined datatype, #H5T_NATIVE_INT, is used for reading and writing so that HDF5 will do +any necessary integer conversions: + +<table> +<tr> +<td> +<em>C</em> +\code + status = H5Dwrite (dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_data); + status = H5Dread (dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, dset_data); +\endcode +</td> +</tr> +</table> + +\subsection subsec_intro_pm_group Steps to create a group +An HDF5 group is a structure containing zero or more HDF5 objects. Before you can create a group you must +obtain the location identifier of where the group is to be created. Following are the steps that are required: +\li Decide where to put the group – in the “root group” (or file identifier) or in another group. Open the group if it is not already open. +\li Define properties or use the default. +\li Create the group. +\li Close the group. + +<table> +<caption>Creates attributes that are attached to the dataset dset</caption> +<tr> +<td> +\image html crtgrp.png +</td> +</tr> +</table> + +The code below opens the dataset dset.h5 with read/write permission and creates a group MyGroup in the root group. +Properties are not specified so the defaults are used: + +<table> +<tr> +<td> +<em>Python</em> +\code + import h5py + file = h5py.File('dset.h5', 'r+') + group = file.create_group ('MyGroup') + file.close() +\endcode +</td> +</tr> +</table> + +To create the group MyGroup in the root group, you must call #H5Gcreate, passing in the file identifier returned +from opening or creating the file. The default property lists are specified with #H5P_DEFAULT. The group is then +closed: + +<table> +<tr> +<td> +<em>C</em> +\code + group_id = H5Gcreate (file_id, "MyGroup", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + status = H5Gclose (group_id); +\endcode +</td> +</tr> +</table> + +\subsection subsec_intro_pm_attr Steps to create and write to an attribute +To create an attribute you must open the object that you wish to attach the attribute to. Then you can create, +access, and close the attribute as needed: +\li Open the object that you wish to add an attribute to. +\li Create the attribute +\li Write to the attribute +\li Close the attribute and the object it is attached to. + +<table> +<caption>Creates attributes that are attached to the dataset dset</caption> +<tr> +<td> +\image html crtatt.png +</td> +</tr> +</table> + +The dataspace, datatype, and data are specified in the call to create an attribute in Python: + +<table> +<tr> +<td> +<em>Python</em> +\code + dataset.attrs["Units"] = “Meters per second” <-- Create string + attr_data = np.zeros((2,)) + attr_data[0] = 100 + attr_data[1] = 200 + dataset.attrs.create("Speed", attr_data, (2,), “i”) <-- Create Integer +\endcode +</td> +</tr> +</table> + +To create an integer attribute in C, you must create the dataspace, create the attribute, write +to it and then close it in separate steps: + +<table> +<tr> +<td> +<em>C</em> +\code + hid_t attribute_id, dataspace_id; // identifiers + hsize_t dims; + int attr_data[2]; + herr_t status; + + ... + + // Initialize the attribute data. + attr_data[0] = 100; + attr_data[1] = 200; + + // Create the data space for the attribute. + dims = 2; + dataspace_id = H5Screate_simple(1, &dims, NULL); + + // Create a dataset attribute. + attribute_id = H5Acreate2 (dataset_id, "Units", H5T_STD_I32BE, + dataspace_id, H5P_DEFAULT, H5P_DEFAULT); + + // Write the attribute data. + status = H5Awrite(attribute_id, H5T_NATIVE_INT, attr_data); + + // Close the attribute. + status = H5Aclose(attribute_id); + + // Close the dataspace. + status = H5Sclose(dataspace_id); +\endcode +</td> +</tr> +</table> + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted + + +@page HDF5Examples HDF5 Examples +Example programs of how to use HDF5 are provided below. +For HDF-EOS specific examples, see the <a href="http://hdfeos.org/zoo/index.php">examples</a> +of how to access and visualize NASA HDF-EOS files using IDL, MATLAB, and NCL on the +<a href="http://hdfeos.org/">HDF-EOS Tools and Information Center</a> page. + +\section secHDF5Examples Examples +\li \ref LBExamples +\li <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> +\li <a href="https://portal.hdfgroup.org/display/HDF5/Examples+in+the+Source+Code">Examples in the Source Code</a> +\li <a href="https://portal.hdfgroup.org/display/HDF5/Other+Examples">Other Examples</a> + +\section secHDF5ExamplesCompile How To Compile +For information on compiling in C, C++ and Fortran, see: \ref LBCompiling + +\section secHDF5ExamplesOther Other Examples +<a href="http://hdfeos.org/zoo/index.php">IDL, MATLAB, and NCL Examples for HDF-EOS</a> +Examples of how to access and visualize NASA HDF-EOS files using IDL, MATLAB, and NCL. + +<a href="https://support.hdfgroup.org/ftp/HDF5/examples/misc-examples/">Miscellaneous Examples</a> +These (very old) examples resulted from working with users, and are not fully tested. Most of them are in C, with a few in Fortran and Java. + +<a href="https://support.hdfgroup.org/ftp/HDF5/examples/special_values_HDF5_example.tar">Using Special Values</a> +These examples show how to create special values in an HDF5 application. + +*/ diff --git a/doxygen/dox/LearnBasics.dox b/doxygen/dox/LearnBasics.dox new file mode 100644 index 0000000..298672d --- /dev/null +++ b/doxygen/dox/LearnBasics.dox @@ -0,0 +1,183 @@ +/** @page LearnBasics Learning the Basics + +Navigate back: \ref index "Main" / \ref GettingStarted +<hr> + +\section secIntro Introduction +The following topics cover the basic features in HDF5. The topics build on each other and are +intended to be completed in order. Some sections use files created in earlier sections. The +examples used can also be found on the \ref LBExamples +page and in the HDF5 source code (C, C++, Fortran). + +\section Topics Topics +\li @subpage LBFileOrg +\li @subpage LBAPI +\li @subpage LBProg +\li @subpage LBFileCreate +\li @subpage LBDsetCreate +\li @subpage LBDsetRW +\li @subpage LBAttrCreate +\li @subpage LBGrpCreate +\li @subpage LBGrpCreateNames +\li @subpage LBGrpDset +\li @subpage LBDsetSubRW +\li @subpage LBDatatypes +\li @subpage LBPropsList +\li @subpage LBDsetLayout +\li @subpage LBExtDset +\li @subpage LBComDset +\li @subpage LBContents +\li @subpage LBQuiz +\li @subpage LBQuizAnswers +\li @subpage LBCompiling +\li @subpage LBTraining + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted + + +@page LBExamples Examples from Learning the Basics + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBExamples +These examples are used in the \ref LearnBasics topic. See \ref LBCompiling for details on compiling them. +PLEASE NOTE that the example programs are listed in the order they are expected to be run. Some example +programs use files created in earlier examples. + +\section secLBExamplesSrc HDF5 Source Code Examples +These examples (C, C++, Fortran) are provided in the HDF5 source code and (Unix) binaries. +<table> +<tr> +<th>Feature +</th> +<th>Examples +</th> +<th>Comments +</th> +<tr> +<td>Create a file +</td> +<td>C Fortran C++ <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/java/examples/intro/H5_CreateFile.java">Java</a> Python +</td> +<td> +</td> +</tr> +<tr> +<td>Create a dataset +</td> +<td><a href="https://raw.githubusercontent.com//HDFGroup/hdf5/hdf5_1_10/examples/h5_crtdat.c">C</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/fortran/examples/h5_crtdat.f90">Fortran</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/c++/examples/h5tutr_crtdat.cpp">C++</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/java/examples/intro/H5_CreateDataset.java">Java</a> <a href="https://support.hdfgroup.org/ftp/HDF5/examples/Py/h5_crtdat.py">Python</a> +</td> +<td> +</td> +</tr> +<tr> +<td>Read and write to a dataset +</td> +<td><a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/examples/h5_rdwt.c">C</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/fortran/examples/h5_rdwt.f90">Fortran</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/c++/examples/h5tutr_rdwt.cpp">C++</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/java/examples/intro/H5_ReadWrite.java">Java</a> <a href="https://support.hdfgroup.org/ftp/HDF5/examples/Py/h5_rdwt.py">Python</a> +</td> +<td> +</td> +</tr> +<tr> +<td>Create an attribute +</td> +<td><a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/examples/h5_crtatt.c">C</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/fortran/examples/h5_crtatt.f90">Fortran</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/c++/examples/h5tutr_crtatt.cpp">C++</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/java/examples/intro/H5_CreateAttribute.java">Java</a> <a href="https://support.hdfgroup.org/ftp/HDF5/examples/Py/h5_crtatt.py">Python</a> +</td> +<td> +</td> +</tr> +<tr> +<td>Create a group +</td> +<td><a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/examples/h5_crtgrp.c">C</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/fortran/examples/h5_crtgrp.f90">Fortran</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/c++/examples/h5tutr_crtgrp.cpp">C++</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/java/examples/intro/H5_CreateGroup.java">Java</a> <a href="https://support.hdfgroup.org/ftp/HDF5/examples/Py/h5_crtgrp.py">Python</a> +</td> +<td> +</td> +</tr> +<tr> +<td>Create groups in a file using absolute and relative paths +</td> +<td><a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/examples/h5_crtgrpar.c">C</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/fortran/examples/h5_crtgrpar.f90">Fortran</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/c++/examples/h5tutr_crtgrpar.cpp">C++</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/java/examples/intro/H5_CreateGroupAbsoluteRelative.java">Java</a> <a href="https://support.hdfgroup.org/ftp/HDF5/examples/Py/h5_crtgrpar.py">Python</a> +</td> +<td> +</td> +</tr> +<tr> +<td>Create datasets in a group +</td> +<td><a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/examples/h5_crtgrpd.c">C</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/fortran/examples/h5_crtgrpd.f90">Fortran</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/c++/examples/h5tutr_crtgrpd.cpp">C++</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/java/examples/intro/H5_CreateGroupDataset.java">Java</a> <a href="https://support.hdfgroup.org/ftp/HDF5/examples/Py/h5_crtgrpd.py">Python</a> +</td> +<td> +</td> +</tr> +<tr> +<td>Create a file and dataset and select/read a subset from the dataset +</td> +<td><a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/examples/h5_subset.c">C</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/fortran/examples/h5_subset.f90">Fortran</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/c++/examples/h5tutr_subset.cpp">C++</a> Java Python +</td> +<td>Also see examples to Write by row (and column) below. +</td> +</tr> +<tr> +<td>Create an extendible (unlimited dimension) dataset +</td> +<td><a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/examples/h5_extend.c">C</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/fortran/examples/h5_extend.f90">Fortran</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/c++/examples/h5tutr_extend.cpp">C++</a> Java Python +</td> +<td>Also see examples to Extend by row (and column) below +</td> +</tr> +<tr> +<td>Create a chunked and compressed dataset +</td> +<td><a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/examples/h5_cmprss.c">C</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/fortran/examples/h5_cmprss.f90">Fortran</a> <a href="https://raw.githubusercontent.com/HDFGroup/hdf5/hdf5_1_10/c++/examples/h5tutr_cmprss.cpp">C++</a> Java <a href="https://support.hdfgroup.org/ftp/HDF5/examples/Py/h5_cmprss.py">Python</a> +</td> +<td> +</td> +</tr> +</table> + +*See <a href="https://github.com/scotmartin1234/HDF5Mathematica">HDF5Mathematica</a> for user-contributed +HDF5 Mathematica Wrappers and Introductory Tutorial Examples. The examples use P/Invoke. + +\section secLBExamplesAddl Additional Examples +These examples make minor changes to the tutorial examples. +<table> +<tr> +<th>Feature +</th> +<th>Examples +</th> +</tr> +<tr> +<td>Write by row +</td> +<td><a href="">C</a> <a href="">Fortran</a> +</td> +</tr> +<tr> +<td>Write by column +</td> +<td><a href="">C</a> <a href="">Fortran</a> +</td> +</tr> +<tr> +<td>Extend by row +</td> +<td><a href="">C</a> <a href="">Fortran</a> +</td> +</tr> +<tr> +<td>Extend by column +</td> +<td><a href="">C</a> <a href="">Fortran</a> +</td> +</tr> +</table> + + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +*/ diff --git a/doxygen/dox/LearnBasics1.dox b/doxygen/dox/LearnBasics1.dox new file mode 100644 index 0000000..a9b6d0e --- /dev/null +++ b/doxygen/dox/LearnBasics1.dox @@ -0,0 +1,1023 @@ +/** @page LBFileOrg HDF5 File Organization + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBFileOrg HDF5 file +An HDF5 file is a container for storing a variety of scientific data and is composed of two primary types of objects: groups and datasets. + +\li HDF5 group: a grouping structure containing zero or more HDF5 objects, together with supporting metadata +\li HDF5 dataset: a multidimensional array of data elements, together with supporting metadata + +Any HDF5 group or dataset may have an associated attribute list. An HDF5 attribute is a user-defined HDF5 structure +that provides extra information about an HDF5 object. + +Working with groups and datasets is similar in many ways to working with directories and files in UNIX. As with UNIX +directories and files, an HDF5 object in an HDF5 file is often referred to by its full path name (also called an absolute path name). + +\li <code style="background-color:whitesmoke;">/</code> signifies the root group. + +\li <code style="background-color:whitesmoke;">/foo</code> signifies a member of the root group called foo. + +\li <code style="background-color:whitesmoke;">/foo/zoo</code> signifies a member of the group foo, which in turn is a member of the root group. + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBAPI The HDF5 API + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBAPI HDF5 C API +The HDF5 library provides several interfaces, or APIs. These APIs provide routines for creating, +accessing, and manipulating HDF5 files and objects. + +The library itself is implemented in C. To facilitate the work of FORTRAN 90, C++ and Java programmers, +HDF5 function wrappers have been developed in each of these languages. This tutorial discusses the use +of the C functions and the FORTRAN wrappers. + +All C routines in the HDF5 library begin with a prefix of the form H5*, where * is one or two uppercase +letters indicating the type of object on which the function operates. +The FORTRAN wrappers come in the form of subroutines that begin with h5 and end with _f. +Java routine names begin with “H5*” and are prefixed with “H5.” as the class. Constants are +in the HDF5Constants class and are prefixed with "HDF5Constants.". +The APIs are listed below: +<table> +<tr> +<th><strong>API</strong> +</th> +<th><strong>DESCRIPTION</strong> +</th> +</tr> +<tr> +<th><strong>H5</strong> +</th> +<td>Library Functions: general-purpose H5 functions +</td> +</tr> +<tr> +<th><strong>H5A</strong> +</th> +<td>Annotation Interface: attribute access and manipulation routines +</td> +</tr> +<tr> +<th><strong>H5D</strong> +</th> +<td>Dataset Interface: dataset access and manipulation routines +</td> +</tr> +<tr> +<th><strong>H5E</strong> +</th> +<td>Error Interface: error handling routines +</td> +</tr> +<tr> +<th><strong>H5F</strong> +</th> +<td>File Interface: file access routines +</td> +</tr> +<tr> +<th><strong>H5G</strong> +</th> +<td>Group Interface: group creation and operation routines +</td> +</tr> +<tr> +<th><strong>H5I</strong> +</th> +<td>Identifier Interface: identifier routines +</td> +</tr> +<tr> +<th><strong>H5L</strong> +</th> +<td>Link Interface: link routines +</td> +</tr> +<tr> +<th><strong>H5O</strong> +</th> +<td>Object Interface: object routines +</td> +</tr> +<tr> +<th><strong>H5P</strong> +</th> +<td>Property List Interface: object property list manipulation routines +</td> +</tr> +<tr> +<th><strong>H5R</strong> +</th> +<td>Reference Interface: reference routines +</td> +</tr> +<tr> +<th><strong>H5S</strong> +</th> +<td>Dataspace Interface: dataspace definition and access routines +</td> +</tr> +<tr> +<th><strong>H5T</strong> +</th> +<td>Datatype Interface: datatype creation and manipulation routines +</td> +</tr> +<tr> +<th><strong>H5Z</strong> +</th> +<td>Compression Interface: compression routine(s) +</td> +</tr> +</table> + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBProg Programming Issues + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +Keep the following in mind when looking at the example programs included in this tutorial: + +\section LBProgAPI APIs vary with different languages +\li C routines begin with the prefix “H5*” where * is a single letter indicating the object on which the operation is to be performed: +<table> +<tr> +<td>File Interface: </td> +<td>#H5Fopen</td> +</tr><tr> +<td>Dataset Interface:</td> +<td>#H5Dopen</td> +</tr> +</table> + +\li FORTRAN routines begin with “h5*” and end with “_f”: +<table> +<tr> +<td>File Interface: </td> +<td>h5fopen_f</td> +</tr><tr> +<td>Dataset Interface:</td> +<td>h5dopen_f</td> +</tr> +</table> + +\li Java routine names begin with “H5*” and are prefixed with “H5.” as the class. Constants are +in the HDF5Constants class and are prefixed with "HDF5Constants.".: +<table> +<tr> +<td>File Interface: </td> +<td>H5.H5Fopen</td> +</tr><tr> +<td>Dataset Interface:</td> +<td>H5.H5Dopen</td> +</tr> +</table> + +\li APIS for languages like C++, Java, and Python use methods associated with specific objects. + +\section LBProgTypes HDF5 library has its own defined types +\li #hid_t is used for object handles +\li hsize_t is used for dimensions +\li #herr_t is used for many return values + +\section LBProgLang Language specific files must be included in applications +<ul> +<li> +Python: Add <code>"import h5py / import numpy"</code> +</li> +<li> +C: Add <code>"#include hdf5.h"</code> +</li> +<li> +FORTRAN: Add <code>"USE HDF5"</code> and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface +</li> +<li> +Java: Add <code>"import hdf.hdf5lib.H5; + import hdf.hdf5lib.HDF5Constants;"</code> +</li> +</ul> + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBFileCreate Creating an HDF5 File + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +An HDF5 file is a binary file containing scientific data and supporting metadata. +\section secLBFileCreate HDF5 File Access +To create an HDF5 file, an application must specify not only a file name, but a file access mode, +a file creation property list, and a file access property list. These terms are described below: +<ul> +<li><strong>File access mode:</strong><br /> +When creating a file, the file access mode specifies the action to take if the file already exists: +<ul> +<li>#H5F_ACC_TRUNC specifies that if the file already exists, the current contents will be deleted so +that the application can rewrite the file with new data. +</li> +<li>#H5F_ACC_EXCL specifies that the open will fail if the file already exists. If the file does not +already exist, the file access parameter is ignored. +</li> +</ul> +In either case, the application has both read and write access to the successfully created file. +<br /> +Note that there are two different access modes for opening existing files: +<ul> +<li>#H5F_ACC_RDONLY specifies that the application has read access but will not be allowed to write any data. +</li> +<li>#H5F_ACC_RDWR specifies that the application has read and write access. +</li> +</ul> +</li> +<li><strong>File creation property list:</strong><br />The file creation property list is used to +control the file metadata. File metadata contains information about the size of the user-block*, +the size of various file data structures used by the HDF5 library, etc. In this tutorial, the +default file creation property list, #H5P_DEFAULT, is used.<br /> + *The user-block is a fixed-length block of data located at the beginning of the file which is +ignored by the HDF5 library. The user-block may be used to store any data or information found +to be useful to applications. +</li> +<li><strong>File access property list:</strong><br />The file access property list is used to +control different methods of performing I/O on files. It also can be used to control how a file +is closed (whether or not to delay the actual file close until all objects in a file are closed). +The default file access property list, #H5P_DEFAULT, is used in this tutorial. +</li> +</ul> + +Please refer to the \ref sec_file section of the \ref UG and \ref H5F section in the \ref RM for +detailed information regarding file access/creation property lists and access modes. + +The steps to create and close an HDF5 file are as follows: +<ol> +<li>Specify the file creation and access property lists, if necessary.</li> +<li>Create the file.</li> +<li>Close the file, and if necessary, close the property lists.</li> +</ol> + +\section secLBFileExample Programming Example + +\subsection subsecLBFileExampleDesc Description +The following example code demonstrates how to create and close an HDF5 file. + +<em>C</em> +\code +#include "hdf5.h" + #define FILE "file.h5" + + int main() { + + hid_t file_id; /* file identifier */ + herr_t status; + + /* Create a new file using default properties. */ + file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + + /* Terminate access to the file. */ + status = H5Fclose(file_id); + } +\endcode + +<em>Fortran</em> +\code + PROGRAM FILEEXAMPLE + + USE HDF5 ! This module contains all necessary modules + + IMPLICIT NONE + + CHARACTER(LEN=8), PARAMETER :: filename = "filef.h5" ! File name + INTEGER(HID_T) :: file_id ! File identifier + + INTEGER :: error ! Error flag + +! +! Initialize FORTRAN interface. +! + CALL h5open_f (error) + ! + ! Create a new file using default properties. + ! + CALL h5fcreate_f(filename, H5F_ACC_TRUNC_F, file_id, error) + + ! + ! Terminate access to the file. + ! + CALL h5fclose_f(file_id, error) +! +! Close FORTRAN interface. +! + CALL h5close_f(error) + END PROGRAM FILEEXAMPLE +\endcode + +See \ref LBExamples for the examples used in the Learning the Basics tutorial. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection subsecLBFileExampleRem Remarks +\li <strong>In C</strong>: The include file <code style="background-color:whitesmoke;">hdf5.h</code> contains definitions and declarations and must be included +in any program that uses the HDF5 library. +<br /> +<strong>In FORTRAN</strong>: The module <code style="background-color:whitesmoke;">HDF5</code> contains definitions and declarations and must be used in any +program that uses the HDF5 library. Also note that #H5open MUST be called at the beginning of an HDF5 Fortran +application (prior to any HDF5 calls) to initialize the library and variables. The #H5close call MUST be at +the end of the HDF5 Fortran application. +\li #H5Fcreate creates an HDF5 file and returns the file identifier.<br /> +For Fortran, the file creation property list and file access property list are optional. They can be omitted if the +default values are to be used.<br /> +The root group is automatically created when a file is created. Every file has a root group and the path name of +the root group is always <code style="background-color:whitesmoke;">/</code>. +\li #H5Fclose terminates access to an HDF5 file.<br /> +When an HDF5 file is no longer accessed by a program, #H5Fclose must be called to release the resources used by the file. +This call is mandatory.<br /> +Note that if #H5Fclose is called for a file, but one or more objects within the file remain open, those objects will +remain accessible until they are individually closed. This can cause access problems for other users, if objects were +inadvertently left open. A File Access property controls how the file is closed. + +\subsection subsecLBFileExampleCont File Contents +The HDF Group has developed tools for examining the contents of HDF5 files. The tool used throughout the HDF5 tutorial +is the HDF5 dumper, <code style="background-color:whitesmoke;">h5dump</code>, which displays the file contents in human-readable form. The output of <code style="background-color:whitesmoke;">h5dump</code> is an ASCII +display formatted according to the HDF5 DDL grammar. This grammar is defined, using Backus-Naur Form, in the +\ref DDLBNF110. + +To view the HDF5 file contents, simply type: +\code +h5dump <filename> +\endcode + +<table> +<caption>Describe the file contents of file.h5 using a directed graph.</caption> +<tr> +<td> +\image html imgLBFile.gif +</td> +</tr> +</table> + +The text description of <code style="background-color:whitesmoke;">file.h5</code>, as generated by <code style="background-color:whitesmoke;">h5dump</code>. The HDF5 file called <code style="background-color:whitesmoke;">file.h5</code> +contains a group called <code style="background-color:whitesmoke;">/</code>, or the root group. (The file called <code style="background-color:whitesmoke;">filef.h5</code>, created by the FORTRAN version of the example, +has the same output except that the filename shown is <code style="background-color:whitesmoke;">filef.h5</code>.) +\code +HDF5 "file.h5" { + GROUP "/" { + } + } +\endcode + +\subsection subsecLBFileExampleDDL File Definition in DDL +The simplified DDL file definition for creating an HDF5 file. For simplicity, a simplified DDL is used in this tutorial. A +complete and more rigorous DDL can be found in the \ref DDLBNF110. + +The following symbol definitions are used in the DDL: +\code + ::= defined as + <tname> a token with the name tname + <a> | <b> one of <a> or <b> + <a>* zero or more occurrences of <a> +\endcode + +The simplified DDL for file definition is as follows: +\code + <file> ::= HDF5 "<file_name>" { <root_group> } + + <root_group> ::= GROUP "/" { <group_attribute>* + <group_member>* } + + <group_attribute> ::= <attribute> + + <group_member> ::= <group> | <dataset> +\endcode + +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBDsetCreate Creating a Dataset +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +A dataset is a multidimensional array of data elements, together with supporting metadata. To create +a dataset, the application program must specify the location at which to create the dataset, the +dataset name, the datatype and dataspace of the data array, and the property lists. + +\section secLBDsetCreateDtype Datatypes +A datatype is a collection of properties, all of which can be stored on disk, and which, when taken as +a whole, provide complete information for data conversion to or from that datatype. + +There are two categories of datatypes in HDF5: +<ul> +<li><strong>Pre-defined</strong>: These datatypes are opened and closed by HDF5.<br /> +Pre-defined datatypes can be atomic or composite: +<ul><li>Atomic datatypes cannot be decomposed into smaller datatype units at the API level. For example: integer, float, reference, string.</li> +<li>Composite datatypes are aggregations of one or more datatypes. For example: array, variable length, enumeration, compound.</li></ul> +</li> +<li><strong>Derived</strong>: These datatypes are created or derived from the pre-defined types.<br /> +A simple example of creating a derived datatype is using the string datatype, H5T_C_S1, to create strings of more than one character:<br /> +\code + hid_t strtype; // Datatype ID + herr_t status; + + strtype = H5Tcopy (H5T_C_S1); + status = H5Tset_size (strtype, 5); // create string of length 5 +\endcode +</li> +</ul> + +Shown below is the HDF5 pre-defined datatypes. +\code + +-- integer + +-- floating point + +---- atomic ----+-- date and time + | +-- character string + HDF5 datatypes --| +-- bitfield + | +-- opaque + | + +---- compound +\endcode + +Some of the HDF5 predefined atomic datatypes are listed below. + +<table> +<caption>Examples of HDF5 predefined datatypes</caption> +<tr> +<th><strong>Datatype</strong></th> +<th><strong>Description</strong></th> +</tr> +<tr> +<th><strong>H5T_STD_I32LE</strong></th> +<td>Four-byte, little-endian, signed, two's complement integer</td> +</tr> +<tr> +<th><strong>H5T_STD_U16BE</strong></th> +<td>Two-byte, big-endian, unsigned integer</td> +</tr> +<tr> +<th><strong>H5T_IEEE_F32BE</strong></th> +<td>Four-byte, big-endian, IEEE floating point</td> +</tr> +<tr> +<th><strong>H5T_IEEE_F64LE</strong></th> +<td>Eight-byte, little-endian, IEEE floating point</td> +</tr> +<tr> +<th><strong>H5T_C_S1</strong></th> +<td>One-byte, null-terminated string of eight-bit characters</td> +</tr> +</table> + +<table> +<caption>Examples of HDF5 predefined native datatypes</caption> +<tr> +<th><strong>Native Datatype</strong></th> +<th><strong>Corresponding C or FORTRAN Type</strong></th> +</tr> +<tr> +<th span="2"><strong>C</strong></th> +</tr> +<tr> +<th><strong>H5T_NATIVE_INT</strong></th> +<td>int</td> +</tr> +<tr> +<th><strong>H5T_NATIVE_FLOAT</strong></th> +<td>float</td> +</tr> +<tr> +<th><strong>H5T_NATIVE_CHAR</strong></th> +<td>char</td> +</tr> +<tr> +<th><strong>H5T_NATIVE_DOUBLE</strong></th> +<td>double</td> +</tr> +<tr> +<th><strong>H5T_NATIVE_LDOUBLE</strong></th> +<td>long double</td> +</tr> +<tr> +<th span="2"><strong>Fortran</strong></th> +</tr> +<tr> +<th><strong>H5T_NATIVE_INTEGER</strong></th> +<td>integer</td> +</tr> +<tr> +<th><strong>H5T_NATIVE_REAL</strong></th> +<td>real</td> +</tr> +<tr> +<th><strong>H5T_NATIVE_DOUBLE</strong></th> +<td>double precision</td> +</tr> +<tr> +<th><strong>H5T_NATIVE_CHARACTER</strong></th> +<td>character</td> +</tr> +</table> + +In this tutorial, we consider only HDF5 predefined integers. + +For further information on datatypes, see \ref sec_datatype in the \ref UG, in addition to the \ref LBDatatypes tutorial topic. + +\section secLBDsetCreateDspace Datasets and Dataspaces +A dataspace describes the dimensionality of the data array. A dataspace is either a regular N-dimensional +array of data points, called a simple dataspace, or a more general collection of data points organized +in another manner, called a complex dataspace. In this tutorial, we only consider simple dataspaces. + +<em>HDF5 dataspaces</em> +\code + +-- simple + HDF5 dataspaces --| + +-- complex +\endcode +The dimensions of a dataset can be fixed (unchanging), or they may be unlimited, which means that they are +extensible. A dataspace can also describe a portion of a dataset, making it possible to do partial +I/O operations on selections. + +\section secLBDsetCreateProp Property Lists +Property lists are a mechanism for modifying the default behavior when creating or accessing objects. For +more information on property lists see the \ref LBPropsList tutorial topic. + +The following property lists can be specified when creating a dataset: +\li Dataset Creation Property List<br /> +When creating a dataset, HDF5 allows the user to specify how raw data is organized and/or compressed on +disk. This information is stored in a dataset creation property list and passed to the dataset interface. +The raw data on disk can be stored contiguously (in the same linear way that it is organized in memory), +partitioned into chunks, stored externally, etc. In this tutorial, we use the default dataset creation +property list (contiguous storage layout and no compression). For more information about dataset creation +property lists, see \ref sec_dataset in the \ref UG. +\li Link Creation Property List<br /> +The link creation property list governs creation of the link(s) by which a new dataset is accessed and the +creation of any intermediate groups that may be missing. +\li Dataset Access Property List<br /> +Dataset access property lists are properties that can be specified when accessing a dataset. + +\section secLBDsetCreateSteps Steps to Create a Dataset +To create an empty dataset (no data written) the following steps need to be taken: +<ol> +<li>Obtain the location identifier where the dataset is to be created.</li> +<li>Define or specify the dataset characteristics: +<ol> +<li>Define a datatype or specify a pre-defined datatype.</li> +<li>Define a dataspace.</li> +<li>Specify the property list(s) or use the default.</li> +</ol></li> +<li>Create the dataset.</li> +<li>Close the datatype, the dataspace, and the property list(s) if necessary.</li> +<li>Close the dataset.</li> +</ol> +In HDF5, datatypes and dataspaces are independent objects which are created separately from any dataset +that they might be attached to. Because of this, the creation of a dataset requires the definition of +the datatype and dataspace. In this tutorial, we use the HDF5 predefined datatypes (integer) and consider +only simple dataspaces. Hence, only the creation of dataspace objects is needed. + +\section secLBDsetCreateHL High Level APIs +The High Level \ref H5LT include functions that simplify and condense the steps for +creating datasets in HDF5. The examples in the following section use the standard APIs. For a +quick start you may prefer to look at the \ref H5LT at this time. + +If you plan to work with images, please look at the High Level \ref H5IM, as well. + +\section secLBDsetCreateProg Programming Example + +\subsection subsecLBDsetCreateProgDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example shows how to create an empty dataset. It creates a file called <code style="background-color:whitesmoke;">dset.h5</code> +in the C version (<code style="background-color:whitesmoke;">dsetf.h5</code> in Fortran), defines the dataset dataspace, creates a +dataset which is a 4x6 integer array, and then closes the dataspace, the dataset, and the file. + +For details on compiling an HDF5 application: [ \ref LBCompiling ] + +\subsection subsecLBDsetCreateProgRem Remarks +#H5Screate_simple creates a new simple dataspace and returns a dataspace identifier. +#H5Sclose releases and terminates access to a dataspace. + +<em>C</em> +\code + dataspace_id = H5Screate_simple (rank, dims, maxdims); + status = H5Sclose (dataspace_id ); +\endcode + +<em>FORTRAN</em> +\code + CALL h5screate_simple_f (rank, dims, dataspace_id, hdferr, maxdims=max_dims) + or + CALL h5screate_simple_f (rank, dims, dataspace_id, hdferr) + + CALL h5sclose_f (dataspace_id, hdferr) +\endcode + +#H5Dcreate creates an empty dataset at the specified location and returns a dataset identifier. +#H5Dclose closes the dataset and releases the resource used by the dataset. This call is mandatory. + +<em>C</em> +\code + dataset_id = H5Dcreate(file_id, "/dset", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + status = H5Dclose (dataset_id); +\endcode + +<em>FORTRAN</em> +\code + CALL h5dcreate_f (loc_id, name, type_id, dataspace_id, dset_id, hdferr) + CALL h5dclose_f (dset_id, hdferr) +\endcode + +Note that if using the pre-defined datatypes in FORTRAN, then a call must be made to initialize and terminate access to the pre-defined datatypes: +\code + CALL h5open_f (hdferr) + CALL h5close_f (hdferr) +\endcode + +H5open must be called before any HDF5 library subroutine calls are made; +H5close must be called after the final HDF5 library subroutine call. + +See the programming example for an illustration of the use of these calls. + +\subsection subsecLBDsetCreateContent File Contents +The contents of the file dset.h5 (dsetf.h5 for FORTRAN) are shown below: +<table> +<caption>Contents of dset.h5 ( dsetf.h5)</caption> +<tr> +<td> +\image html imgLBDsetCreate.gif +</td> +</tr> +</table> +<table> +<tr> +<th>dset.h5 in DDL</th> +<th>dsetf.h5 in DDL</th> +<tr> +<td> +\code +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) } + DATA { + 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0 + } + } +} +} +\endcode +</td> +<td> +\code +HDF5 "dsetf.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 6, 4 ) / ( 6, 4 ) } + DATA { + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0, + 0, 0, 0, 0 + } + } +} +} +\endcode +</td> +</tr> +</table> +Note in above that #H5T_STD_I32BE, a 32-bit Big Endian integer, is an HDF atomic datatype. + +\subsection subsecLBDsetCreateProgDDL Dataset Definition in DDL +The following is the simplified DDL dataset definition: +\code + <dataset> ::= DATASET "<dataset_name>" { <datatype> + <dataspace> + <data> + <dataset_attribute>* } + + <datatype> ::= DATATYPE { <atomic_type> } + + <dataspace> ::= DATASPACE { SIMPLE <current_dims> / <max_dims> } + + <dataset_attribute> ::= <attribute> +\endcode + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBDsetRW Reading From and Writing To a Dataset +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBDsetRW Dataset I/O Operation +During a dataset I/O operation, the library transfers raw data between memory and the file. The data in memory +can have a datatype different from that of the file and can also be of a different size (i.e., the data in +memory is a subset of the dataset elements, or vice versa). Therefore, to perform read or write operations, +the application program must specify: +\li The dataset +\li The dataset's datatype in memory +\li The dataset's dataspace in memory +\li The dataset's dataspace in the file +\li The dataset transfer property list<br /> +<ul> +<li>(The dataset transfer property list controls various aspects of the I/O operations, such as the number +of processes participating in a collective I/O request or hints to the library to control caching of raw +data. In this tutorial, we use the default dataset transfer property list.)</li> +</ul> +\li The data buffer + +The steps to read from or write to a dataset are as follows: +<ol> +<li>Obtain the dataset identifier.</li> +<li>Specify the memory datatype.</li> +<li>Specify the memory dataspace.</li> +<li>Specify the file dataspace.</li> +<li>Specify the transfer properties.</li> +<li>Perform the desired operation on the dataset.</li> +<li>Close the dataset.</li> +<li>Close the dataspace, datatype, and property list if necessary.</li> +</ol> + +To read from or write to a dataset, the #H5Dread and #H5Dwrite routines are used. + +<em>C</em> +\code + status = H5Dread (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf ); + status = H5Dwrite (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf); +\endcode + +<em>Fortran</em> +\code + CALL h5dread_f(dset_id, mem_type_id, buf, dims, error, & + mem_space_id=mspace_id, file_space_id=fspace_id, & + xfer_prp=xfer_plist_id) + or + CALL h5dread_f(dset_id, mem_type_id, buf, dims, error) + + + CALL h5dwrite_f(dset_id, mem_type_id, buf, dims, error, & + mem_space_id=mspace_id, file_space_id=fspace_id, & + xfer_prp=xfer_plist_id) + or + CALL h5dwrite_f(dset_id, mem_type_id, buf, dims, error) +\endcode + +\section secLBDsetRWHL High Level APIs +The High Level \ref H5LT include functions that simplify and condense the steps for creating and +reading datasets. Please be sure to review them, in addition to this tutorial. + +\section secLBDsetRWEx Programming Example + +\subsection secLBDsetRWExDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example shows how to read and write an existing dataset. It opens the file created in the previous example, +obtains the dataset identifier for the dataset <code style="background-color:whitesmoke;">/dset</code>, writes the dataset to the file, then reads +the dataset back. It then closes the dataset and file. + +Note that #H5S_ALL is passed in for both the memory and file dataspace parameters in the read and write calls. +This indicates that the entire dataspace of the dataset will be read or written to. #H5S_ALL by itself does not +necessarily have this meaning. See the \ref RM entry for #H5Dread or #H5Dwrite for more information on using #H5S_ALL. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection secLBDsetRWExRem Remarks +#H5Fopen opens an existing file and returns a file identifier. + +#H5Dopen opens an existing dataset with the specified name and location. + +#H5Dwrite writes raw data from an application buffer to the specified dataset, converting from the datatype and +dataspace of the dataset in memory to the datatype and dataspace of the dataset in the file. Specifying #H5S_ALL +for both the memory and file dataspaces indicates that the entire dataspace of the dataset is to be written to. +#H5S_ALL by itself does not necessarily have this meaning. See the \ref RM entry for #H5Dwrite for more information +on using #H5S_ALL. + +#H5Dread reads raw data from the specified dataset to an application buffer, converting from the file datatype and +dataspace to the memory datatype and dataspace. Specifying #H5S_ALL for both the memory and file dataspaces +indicates that the entire dataspace of the dataset is to be read. #H5S_ALL by itself does not necessarily have +this meaning. See the \ref RM entry for #H5Dread for more information on using #H5S_ALL. + +\subsection secLBDsetRWExCont File Contents + +Shown below is the contents of dset.h5 (created by the C program). + +<em>dset.h5 in DDL</em> +\code + HDF5 "dset.h5" { + GROUP "/" { + DATASET "dset" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) } + DATA { + 1, 2, 3, 4, 5, 6, + 7, 8, 9, 10, 11, 12, + 13, 14, 15, 16, 17, 18, + 19, 20, 21, 22, 23, 24 + } + } + } + } +\endcode + +Shown below is the contents of dsetf.h5 (created by the FORTRAN program). + +<em>dsetf.h5 in DDL</em> +\code + HDF5 "dsetf.h5" { + GROUP "/" { + DATASET "dset" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 6, 4 ) / ( 6, 4 ) } + DATA { + 1, 7, 13, 19, + 2, 8, 14, 20, + 3, 9, 15, 21, + 4, 10, 16, 22, + 5, 11, 17, 23, + 6, 12, 18, 24 + } + } + } + } +\endcode + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBAttrCreate Creating an Attribute +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +Attributes are small datasets that can be used to describe the nature and/or the intended usage of +the object they are attached to. In this section, we show how to create, read, and write an attribute. + +\section secLBAttrCreate Creating an attribute +Creating an attribute is similar to creating a dataset. To create an attribute, the application must +specify the object which the attribute is attached to, the datatype and dataspace of the attribute +data, and the attribute creation property list. + +The steps to create an attribute are as follows: +<ol> +<li>Obtain the object identifier that the attribute is to be attached to.</li> +<li>Define the characteristics of the attribute and specify the attribute creation property list. +<ul> +<li>Define the datatype.</li> +<li>Define the dataspace.</li> +<li>Specify the attribute creation property list.</li> +</ul></li> +<li>Create the attribute.</li> +<li>Close the attribute and datatype, dataspace, and attribute creation property list, if necessary.</li> +</ol> + +To create and close an attribute, the calling program must use #H5Acreate and #H5Aclose. For example: + +<em>C</em> +\code + attr_id = H5Acreate (dataset_id, "Units", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT, H5P_DEFAULT) + status = H5Aclose (attr_id); +\endcode + +<em>Fortran</em> +\code + CALL h5acreate_f (dset_id, attr_nam, type_id, space_id, attr_id, & + hdferr, creation_prp=creat_plist_id) + or + CALL h5acreate_f (dset_id, attr_nam, type_id, space_id, attr_id, hdferr) + + CALL h5aclose_f (attr_id, hdferr) +\endcode + +\section secLBAttrCreateRW Reading/Writing an attribute +Attributes may only be read or written as an entire object; no partial I/O is supported. Therefore, +to perform I/O operations on an attribute, the application needs only to specify the attribute and +the attribute's memory datatype. + +The steps to read or write an attribute are as follows. +<ol> +<li>Obtain the attribute identifier.</li> +<li>Specify the attribute's memory datatype.</li> +<li>Perform the desired operation.</li> +<li>Close the memory datatype if necessary.</li> +</ol> + +To read and/or write an attribute, the calling program must contain the #H5Aread and/or +#H5Awrite routines. For example: + +<em>C</em> +\code + status = H5Aread (attr_id, mem_type_id, buf); + status = H5Awrite (attr_id, mem_type_id, buf); +\endcode + +<em>Fortran</em> +\code + CALL h5awrite_f (attr_id, mem_type_id, buf, dims, hdferr) + CALL h5aread_f (attr_id, mem_type_id, buf, dims, hdferr) +\endcode + +\section secLBAttrCreateHL High Level APIs +The High Level \ref H5LT include functions that simplify and condense the steps for creating and +reading datasets. Please be sure to review them, in addition to this tutorial. + +\section secLBAttrCreateRWEx Programming Example + +\subsection secLBAttrCreateRWExDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example shows how to create and write a dataset attribute. It opens an existing file <code style="background-color:whitesmoke;">dset.h5</code> +in C (<code style="background-color:whitesmoke;">dsetf.h5</code> in FORTRAN), obtains the identifier of the dataset <code style="background-color:whitesmoke;">/dset</code>, defines +the attribute's dataspace, creates the dataset attribute, writes the attribute, and then closes the attribute's +dataspace, attribute, dataset, and file. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection secLBAttrCreateRWExRem Remarks +#H5Acreate creates an attribute which is attached to the object specified by the first parameter, and returns an identifier. + +#H5Awrite writes the entire attribute, and returns the status of the write. + +When an attribute is no longer accessed by a program, #H5Aclose must be called to release the attribute from use. +An #H5Aclose/h5aclose_f call is mandatory. + +\subsection secLBAttrCreateRWExCont File Contents + +Shown below is the contents and the attribute definition of <code style="background-color:whitesmoke;">dset.h5</code> (created by the C program). + +<em>dset.h5 in DDL</em> +\code +HDF5 "dset.h5" { +GROUP "/" { +DATASET "dset" { +DATATYPE { H5T_STD_I32BE } +DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) } +DATA { + 1, 2, 3, 4, 5, 6, + 7, 8, 9, 10, 11, 12, + 13, 14, 15, 16, 17, 18, + 19, 20, 21, 22, 23, 24 +} +ATTRIBUTE "attr" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 2 ) / ( 2 ) } + DATA { + 100, 200 + } +} +} +} +} +\endcode + +Shown below is the contents and the attribute definition of <code style="background-color:whitesmoke;">dsetf.h5</code> (created by the FORTRAN program). + +<em>dsetf.h5 in DDL</em> +\code +HDF5 "dsetf.h5" { +GROUP "/" { +DATASET "dset" { +DATATYPE { H5T_STD_I32BE } +DATASPACE { SIMPLE ( 6, 4 ) / ( 6, 4 ) } +DATA { + 1, 7, 13, 19, + 2, 8, 14, 20, + 3, 9, 15, 21, + 4, 10, 16, 22, + 5, 11, 17, 23, + 6, 12, 18, 24 +} +ATTRIBUTE "attr" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 2 ) / ( 2 ) } + DATA { + 100, 200 + } +} +} +} +} +\endcode + +\subsection secLBAttrCreateRWExDDL Attribute Definition in DDL + +<em>HDF5 Attribute Definition</em> +\code +<attribute> ::= ATTRIBUTE "<attr_name>" { <datatype> + <dataspace> + <data> } +\endcode + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +*/ diff --git a/doxygen/dox/LearnBasics2.dox b/doxygen/dox/LearnBasics2.dox new file mode 100644 index 0000000..ffcb971 --- /dev/null +++ b/doxygen/dox/LearnBasics2.dox @@ -0,0 +1,1159 @@ +/** @page LBGrpCreate Creating an Group +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBGrpCreate Creating an group +An HDF5 group is a structure containing zero or more HDF5 objects. The two primary HDF5 objects are groups and datasets. To create a group, the calling program must: +<ol> +<li>Obtain the location identifier where the group is to be created.</li> +<li>Create the group.</li> +<li>Close the group.</li> +</ol> + +To create a group, the calling program must call #H5Gcreate. +To close the group, #H5Gclose must be called. The close call is mandatory. + +For example: + +<em>C</em> +\code + group_id = H5Gcreate(file_id, "/MyGroup", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + status = H5Gclose (group_id); +\endcode + +<em>Fortran</em> +\code + CALL h5gcreate_f (loc_id, name, group_id, error) + CALL h5gclose_f (group_id, error) +\endcode + +\section secLBGrpCreateRWEx Programming Example + +\subsection secLBGrpCreateRWExDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example shows how to create and close a group. It creates a file called <code style="background-color:whitesmoke;">group.h5</code> in C +(<code style="background-color:whitesmoke;">groupf.h5</code> for FORTRAN), creates a group called MyGroup in the root group, and then closes the group and file. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection secLBGrpCreateRWExCont File Contents + +Shown below is the contents and the definition of the group of <code style="background-color:whitesmoke;">group.h5</code> (created by the C program). +(The FORTRAN program creates the HDF5 file <code style="background-color:whitesmoke;">groupf.h5</code> and the resulting DDL shows the filename +<code style="background-color:whitesmoke;">groupf.h5</code> in the first line.) +<table> +<caption>The Contents of group.h5.</caption> +<tr> +<td> +\image html imggrpcreate.gif +</td> +</tr> +</table> + +<em>group.h5 in DDL</em> +\code +HDF5 "group.h5" { +GROUP "/" { + GROUP "MyGroup" { + } +} +} +\endcode + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBGrpCreateNames Creating Groups using Absolute and Relative Names +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +Recall that to create an HDF5 object, we have to specify the location where the object is to be created. +This location is determined by the identifier of an HDF5 object and the name of the object to be created. +The name of the created object can be either an absolute name or a name relative to the specified identifier. +In the previous example, we used the file identifier and the absolute name <code style="background-color:whitesmoke;">/MyGroup</code> to create a group. + +In this section, we discuss HDF5 names and show how to use absolute and relative names. + +\section secLBGrpCreateNames Names +HDF5 object names are a slash-separated list of components. There are few restrictions on names: component +names may be any length except zero and may contain any character except slash (<code style="background-color:whitesmoke;">/</code>) and the null terminator. +A full name may be composed of any number of component names separated by slashes, with any of the component +names being the special name <code style="background-color:whitesmoke;">.</code> (a dot or period). A name which begins with a slash is an <em>absolute name</em> which +is accessed beginning with the root group of the file; all other names are <em>relative names</em> and and the named +object is accessed beginning with the specified group. A special case is the name <code style="background-color:whitesmoke;">/</code> (or equivalent) which +refers to the root group. + +Functions which operate on names generally take a location identifier, which can be either a file identifier +or a group identifier, and perform the lookup with respect to that location. Several possibilities are +described in the following table: + +<table> +<tr> +<th><strong>Location Type</strong></th> +<th><strong>Object Name</strong></th> +<th><strong>Description</strong></th> +</tr> +<tr> +<th><strong>File identifier</strong></th> +<td>/foo/bar</td> +<td>The object bar in group foo in the root group.</td> +</tr> +<tr> +<th><strong>Group identifier</strong></th> +<td>/foo/bar</td> +<td>The object bar in group foo in the root group of the file containing the specified group. +In other words, the group identifier's only purpose is to specify a file.</td> +</tr> +<tr> +<th><strong>File identifier</strong></th> +<td>/</td> +<td>The root group of the specified file.</td> +</tr> +<tr> +<th><strong>Group identifier</strong></th> +<td>/</td> +<td>The root group of the file containing the specified group.</td> +</tr> +<tr> +<th><strong>Group identifier</strong></th> +<td>foo/bar</td> +<td>The object bar in group foo in the specified group.</td> +</tr> +<tr> +<th><strong>File identifier</strong></th> +<td>.</td> +<td>The root group of the file.</td> +</tr> +<tr> +<th><strong>Group identifier</strong></th> +<td>.</td> +<td>The specified group.</td> +</tr> +<tr> +<th><strong>Other identifier</strong></th> +<td>.</td> +<td>The specified object.</td> +</tr> +</table> + +\section secLBGrpCreateNamesEx Programming Example + +\subsection secLBGrpCreateNamesExDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example code shows how to create groups using absolute and relative names. It creates three groups: the first two groups are created using +the file identifier and the group absolute names while the third group is created using a group identifier and a name relative to the specified group. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection secLBGrpCreateNamesExRem Remarks +#H5Gcreate creates a group at the location specified by a location identifier and a name. The location identifier +can be a file identifier or a group identifier and the name can be relative or absolute. + +The first #H5Gcreate/h5gcreate_f creates the group <code style="background-color:whitesmoke;">MyGroup</code> in the root group of the specified file. + +The second #H5Gcreate/h5gcreate_f creates the group <code style="background-color:whitesmoke;">Group_A</code> in the group <code style="background-color:whitesmoke;">MyGroup</code> in the root group of the specified +file. Note that the parent group (<code style="background-color:whitesmoke;">MyGroup</code>) already exists. + +The third #H5Gcreate/h5gcreate_f creates the group <code style="background-color:whitesmoke;">Group_B</code> in the specified group. + +\subsection secLBGrpCreateNamesExCont File Contents + +Shown below is the contents and the definition of the group of <code style="background-color:whitesmoke;">groups.h5</code> (created by the C program). +(The FORTRAN program creates the HDF5 file <code style="background-color:whitesmoke;">groupsf.h5</code> and the resulting DDL shows the filename +<code style="background-color:whitesmoke;">groupsf.h5</code> in the first line.) +<table> +<caption>The Contents of groups.h5.</caption> +<tr> +<td> +\image html imggrps.gif +</td> +</tr> +</table> + +<em>groups.h5 in DDL</em> +\code +HDF5 "groups.h5" { +GROUP "/" { + GROUP "MyGroup" { + GROUP "Group_A" { + } + GROUP "Group_B" { + } + } +} +} +\endcode + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBGrpDset Creating Datasets in Groups +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBGrpDset Datasets in Groups +We have shown how to create groups, datasets, and attributes. In this section, we show how to create +datasets in groups. Recall that #H5Dcreate creates a dataset at the location specified by a location +identifier and a name. Similar to #H5Gcreate, the location identifier can be a file identifier or a +group identifier and the name can be relative or absolute. The location identifier and the name +together determine the location where the dataset is to be created. If the location identifier and +name refer to a group, then the dataset is created in that group. + +\section secLBGrpDsetEx Programming Example + +\subsection secLBGrpDsetExDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example shows how to create a dataset in a particular group. It opens the file created in the previous example and creates two datasets: + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection secLBGrpDsetExCont File Contents + +Shown below is the contents and the definition of the group of <code style="background-color:whitesmoke;">groups.h5</code> (created by the C program). +(The FORTRAN program creates the HDF5 file <code style="background-color:whitesmoke;">groupsf.h5</code> and the resulting DDL shows the filename +<code style="background-color:whitesmoke;">groupsf.h5</code> in the first line.) +<table> +<caption>The contents of the file groups.h5 (groupsf.h5 for FORTRAN)</caption> +<tr> +<td> +\image html imggrpdsets.gif +</td> +</tr> +</table> + +<em>groups.h5 in DDL</em> +\code +HDF5 "groups.h5" { +GROUP "/" { +GROUP "MyGroup" { +GROUP "Group_A" { + DATASET "dset2" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 2, 10 ) / ( 2, 10 ) } + DATA { + 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, + 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 + } + } +} +GROUP "Group_B" { +} +DATASET "dset1" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 3, 3 ) / ( 3, 3 ) } + DATA { + 1, 2, 3, + 1, 2, 3, + 1, 2, 3 + } +} +} +} +} +\endcode + +<em>groupsf.h5 in DDL</em> +\code +HDF5 "groupsf.h5" { +GROUP "/" { +GROUP "MyGroup" { +GROUP "Group_A" { + DATASET "dset2" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 10, 2 ) / ( 10, 2 ) } + DATA { + 1, 1, + 2, 2, + 3, 3, + 4, 4, + 5, 5, + 6, 6, + 7, 7, + 8, 8, + 9, 9, + 10, 10 + } + } +} +GROUP "Group_B" { +} +DATASET "dset1" { + DATATYPE { H5T_STD_I32BE } + DATASPACE { SIMPLE ( 3, 3 ) / ( 3, 3 ) } + DATA { + 1, 1, 1, + 2, 2, 2, + 3, 3, 3 + } +} +} +} +} +\endcode + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBDsetSubRW Reading From or Writing To a Subset of a Dataset +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBDsetSubRW Dataset Subsets +There are two ways that you can select a subset in an HDF5 dataset and read or write to it: +<ul><li> +<strong>Hyperslab Selection</strong>: The #H5Sselect_hyperslab call selects a logically contiguous +collection of points in a dataspace, or a regular pattern of points or blocks in a dataspace. +</li><li> +<strong>Element Selection</strong>: The #H5Sselect_elements call selects elements in an array. +</li></ul> + +HDF5 allows you to read from or write to a portion or subset of a dataset by: +\li Selecting a Subset of the Dataset's Dataspace, +\li Selecting a Memory Dataspace, +\li Reading From or Writing to a Dataset Subset. + +\section secLBDsetSubRWSel Selecting a Subset of the Dataset's Dataspace +First you must obtain the dataspace of a dataset in a file by calling #H5Dget_space. + +Then select a subset of that dataspace by calling #H5Sselect_hyperslab. The <em>offset</em>, <em>count</em>, <em>stride</em> +and <em>block</em> parameters of this API define the shape and size of the selection. They must be arrays +with the same number of dimensions as the rank of the dataset's dataspace. These arrays <strong>ALL</strong> work +together to define a selection. A change to one of these arrays can affect the others. +\li \em offset: An array that specifies the offset of the starting element of the specified hyperslab. +\li \em count: An array that determines how many blocks to select from the dataspace in each dimension. If the block +size for a dimension is one then the count is the number of elements along that dimension. +\li \em stride: An array that allows you to sample elements along a dimension. For example, a stride of one (or NULL) +will select every element along a dimension, a stride of two will select every other element, and a stride of three +will select an element after every two elements. +\li \em block: An array that determines the size of the element block selected from a dataspace. If the block size +is one or NULL then the block size is a single element in that dimension. + +\section secLBDsetSubRWMem Selecting a Memory Dataspace +You must select a memory dataspace in addition to a file dataspace before you can read a subset from or write a subset +to a dataset. A memory dataspace can be specified by calling #H5Screate_simple. + +The memory dataspace passed to the read or write call must contain the same number of elements as the file dataspace. +The number of elements in a dataspace selection can be determined with the #H5Sget_select_npoints API. + +\section secLBDsetSubRWSub Reading From or Writing To a Dataset Subset +To read from or write to a dataset subset, the #H5Dread and #H5Dwrite routines are used. The memory and file dataspace +identifiers from the selections that were made are passed into the read or write call. For example (C): +\code + status = H5Dwrite (.., .., memspace_id, dataspace_id, .., ..); +\endcode + +\section secLBDsetSubRWProg Programming Example + +\subsection subsecLBDsetSubRWProgDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example creates an 8 x 10 integer dataset in an HDF5 file. It then selects and writes to a 3 x 4 subset +of the dataset created with the dimensions offset by 1 x 2. (If using Fortran, the dimensions will be swapped. +The dataset will be 10 x 8, the subset will be 4 x 3, and the offset will be 2 x 1.) + +PLEASE NOTE that the examples and images below were created using C. + +The following image shows the dataset that gets written originally, and the subset of data that gets modified +afterwards. Dimension 0 is vertical and Dimension 1 is horizontal as shown below: +<table> +<tr> +<td> +\image html LBDsetSubRWProg.png +</td> +</tr> +</table> + +The subset on the right above is created using these values for offset, count stride, and block: +\code +offset = {1, 2} + +count = {3, 4} + +stride = {1, 1} + +block = {1, 1} +\endcode + +\subsection subsecLBDsetSubRWProgExper Experiments with Different Selections +Following are examples of changes that can be made to the example code provided to better understand +how to make selections. + +\subsubsection subsubsecLBDsetSubRWProgExperOne Example 1 +By default the example code will select and write to a 3 x 4 subset. You can modify the count +parameter in the example code to select a different subset, by changing the value of +DIM0_SUB (C, C++) / dim0_sub (Fortran) near the top. Change its value to 7 to create a 7 x 4 subset: +<table> +<tr> +<td> +\image html imgLBDsetSubRW11.png +</td> +</tr> +</table> + +If you were to change the subset to 8 x 4, the selection would be beyond the extent of the dimension: +<table> +<tr> +<td> +\image html imgLBDsetSubRW12.png +</td> +</tr> +</table> + +The write will fail with the error: "<strong>file selection+offset not within extent</strong>" + +\subsubsection subsubsecLBDsetSubRWProgExperTwo Example 2 +In the example code provided, the memory and file dataspaces passed to the H5Dwrite call have the +same size, 3 x 4 (DIM0_SUB x DIM1_SUB). Change the size of the memory dataspace to be 4 x 4 so that +they do not match, and then compile: +\code + dimsm[0] = DIM0_SUB + 1; + dimsm[1] = DIM1_SUB; + memspace_id = H5Screate_simple (RANK, dimsm, NULL); +\endcode +The code will fail with the error: "<strong>src and dest data spaces have different sizes</strong>" + +How many elements are in the memory and file dataspaces that were specified above? Add these lines: +\code + hssize_t size; + + /* Just before H5Dwrite call the following */ + size = H5Sget_select_npoints (memspace_id); + printf ("\nmemspace_id size: %i\n", size); + size = H5Sget_select_npoints (dataspace_id); + printf ("dataspace_id size: %i\n", size); +\endcode + +You should see these lines followed by the error: +\code + memspace_id size: 16 + dataspace_id size: 12 +\endcode + +\subsubsection subsubsecLBDsetSubRWProgExperThree Example 3 +This example shows the selection that occurs if changing the values of the <em>offset</em>, <em>count</em>, +<em>stride</em> and <em>block</em> parameters in the example code. + +This will select two blocks. The <em>count</em> array specifies the number of blocks. The <em>block</em> array +specifies the size of a block. The <em>stride</em> must be modified to accommodate the block <em>size</em>. +<table> +<tr> +<td> +\image html imgLBDsetSubRW31.png +</td> +</tr> +</table> + +Now try modifying the count as shown below. The write will fail because the selection goes beyond the extent of the dimension: +<table> +<tr> +<td> +\image html imgLBDsetSubRW32.png +</td> +</tr> +</table> + +If the offset were 1x1 (instead of 1x2), then the selection can be made: +<table> +<tr> +<td> +\image html imgLBDsetSubRW33.png +</td> +</tr> +</table> + +The selections above were tested with the +<a href="https://support.hdfgroup.org/ftp/HDF5/examples/howto/subset/h5_subsetbk.c">h5_subsetbk.c</a> +example code. The memory dataspace was defined as one-dimensional. + +\subsection subsecLBDsetSubRWProgRem Remarks +\li In addition to #H5Sselect_hyperslab, this example introduces the #H5Dget_space call to obtain the dataspace of a dataset. +\li If using the default values for the stride and block parameters of #H5Sselect_hyperslab, then, for C you can specify NULL +for these parameters, rather than passing in an array for each, and for Fortran 90 you can omit these parameters. + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBDatatypes Datatype Basics +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBDtype What is a Datatype? +A datatype is a collection of datatype properties which provide complete information for data conversion to or from that datatype. + +Datatypes in HDF5 can be grouped as follows: +\li <strong>Pre-Defined Datatypes</strong>: These are datatypes that are created by HDF5. They are actually opened +(and closed) by HDF5, and can have a different value from one HDF5 session to the next. +\li <strong>Derived Datatypes</strong>: These are datatypes that are created or derived from the pre-defined datatypes. +Although created from pre-defined types, they represent a category unto themselves. An example of a commonly used derived +datatype is a string of more than one character. + +\section secLBDtypePre Pre-defined Datatypes +The properties of pre-defined datatypes are: +\li Pre-defined datatypes are opened and closed by HDF5. +\li A pre-defined datatype is a handle and is NOT PERSISTENT. Its value can be different from one HDF5 session to the next. +\li Pre-defined datatypes are Read-Only. +\li As mentioned, other datatypes can be derived from pre-defined datatypes. + +There are two types of pre-defined datatypes, standard (file) and native. + +<h4>Standard</h4> +A standard (or file) datatype can be: +<ul> +<li><strong>Atomic</strong>: A datatype which cannot be decomposed into smaller datatype units at the API level. +The atomic datatypes are: +<ul> +<li>integer</li> +<li>float</li> +<li>string (1-character)</li> +<li>date and time</li> +<li>bitfield</li> +<li>reference</li> +<li>opaque</li> +</ul> +</li> +<li><strong>Composite</strong>: An aggregation of one or more datatypes. +Composite datatypes include: +<ul> +<li>array</li> +<li>variable length</li> +<li>enumeration</li> +<li>compound datatypes</li> +</ul> +Array, variable length, and enumeration datatypes are defined in terms of a single atomic datatype, +whereas a compound datatype is a datatype composed of a sequence of datatypes. +</li> +</ul> + +<table> +<tr> +<th><strong>Notes</strong></th> +</tr> +<tr> +<td> +\li Standard pre-defined datatypes are the SAME on all platforms. +\li They are the datatypes that you see in an HDF5 file. +\li They are typically used when creating a dataset. +</td> +</tr> +</table> + +<h4>Native</h4> +Native pre-defined datatypes are used for memory operations, such as reading and writing. They are +NOT THE SAME on different platforms. They are similar to C type names, and are aliased to the +appropriate HDF5 standard pre-defined datatype for a given platform. + +For example, when on an Intel based PC, #H5T_NATIVE_INT is aliased to the standard pre-defined type, +#H5T_STD_I32LE. On a MIPS machine, it is aliased to #H5T_STD_I32BE. +<table> +<tr> +<th><strong>Notes</strong></th> +</tr> +<tr> +<td> +\li Native datatypes are NOT THE SAME on all platforms. +\li Native datatypes simplify memory operations (read/write). The HDF5 library automatically converts as needed. +\li Native datatypes are NOT in an HDF5 File. The standard pre-defined datatype that a native datatype corresponds +to is what you will see in the file. +</td> +</tr> +</table> + +<h4>Pre-Defined</h4> +The following table shows the native types and the standard pre-defined datatypes they correspond +to. (Keep in mind that HDF5 can convert between datatypes, so you can specify a buffer of a larger +type for a dataset of a given type. For example, you can read a dataset that has a short datatype +into a long integer buffer.) + +<table> +<caption>Some HDF5 pre-defined native datatypes and corresponding standard (file) type</caption> +<tr> +<th><strong>C Type</strong></th> +<th><strong>HDF5 Memory Type</strong></th> +<th><strong>HDF5 File Type*</strong></th> +</tr> +<tr> +<th span="3"><strong>Integer</strong></th> +</tr> +<tr> +<td>int</td> +<td>#H5T_NATIVE_INT</td> +<td>#H5T_STD_I32BE or #H5T_STD_I32LE</td> +</tr> +<tr> +<td>short</td> +<td>#H5T_NATIVE_SHORT</td> +<td>#H5T_STD_I16BE or #H5T_STD_I16LE</td> +</tr> +<tr> +<td>long</td> +<td>#H5T_NATIVE_LONG</td> +<td>#H5T_STD_I32BE, #H5T_STD_I32LE, + #H5T_STD_I64BE or #H5T_STD_I64LE</td> +</tr> +<tr> +<td>long long</td> +<td>#H5T_NATIVE_LLONG</td> +<td>#H5T_STD_I64BE or #H5T_STD_I64LE</td> +</tr> +<tr> +<td>unsigned int</td> +<td>#H5T_NATIVE_UINT</td> +<td>#H5T_STD_U32BE or #H5T_STD_U32LE</td> +</tr> +<tr> +<td>unsigned short</td> +<td>#H5T_NATIVE_USHORT</td> +<td>#H5T_STD_U16BE or #H5T_STD_U16LE</td> +</tr> +<tr> +<td>unsigned long</td> +<td>#H5T_NATIVE_ULONG</td> +<td>#H5T_STD_U32BE, #H5T_STD_U32LE, + #H5T_STD_U64BE or #H5T_STD_U64LE</td> +</tr> +<tr> +<td>unsigned long long</td> +<td>#H5T_NATIVE_ULLONG</td> +<td>#H5T_STD_U64BE or #H5T_STD_U64LE</td> +</tr> +<tr> +<th span="3"><strong>Float</strong></th> +</tr> +<tr> +<td>float</td> +<td>#H5T_NATIVE_FLOAT</td> +<td>#H5T_IEEE_F32BE or #H5T_IEEE_F32LE</td> +</tr> +<tr> +<td>double</td> +<td>#H5T_NATIVE_DOUBLE</td> +<td>#H5T_IEEE_F64BE or #H5T_IEEE_F64LE</td> +</tr> +</table> + +<table> +<caption>Some HDF5 pre-defined native datatypes and corresponding standard (file) type</caption> +<tr> +<th><strong>F90 Type</strong></th> +<th><strong>HDF5 Memory Type</strong></th> +<th><strong>HDF5 File Type*</strong></th> +</tr> +<tr> +<td>integer</td> +<td>H5T_NATIVE_INTEGER</td> +<td>#H5T_STD_I32BE(8,16) or #H5T_STD_I32LE(8,16)</td> +</tr> +<tr> +<td>real</td> +<td>H5T_NATIVE_REAL</td> +<td>#H5T_IEEE_F32BE or #H5T_IEEE_F32LE</td> +</tr> +<tr> +<td>double-precision</td> +<td>#H5T_NATIVE_DOUBLE</td> +<td>#H5T_IEEE_F64BE or #H5T_IEEE_F64LE</td> +</tr> +</table> + +<table> +<tr> +<td>* Note that the HDF5 File Types listed are those that are most commonly created. + The file type created depends on the compiler switches and platforms being + used. For example, on the Cray an integer is 64-bit, and using #H5T_NATIVE_INT (C) + or H5T_NATIVE_INTEGER (F90) would result in an #H5T_STD_I64BE file type.</td> +</tr> +</table> + +The following code is an example of when you would use standard pre-defined datatypes vs. native types: +\code + #include "hdf5.h" + + main() { + + hid_t file_id, dataset_id, dataspace_id; + herr_t status; + hsize_t dims[2]={4,6}; + int i, j, dset_data[4][6]; + + for (i = 0; i < 4; i++) + for (j = 0; j < 6; j++) + dset_data[i][j] = i * 6 + j + 1; + + file_id = H5Fcreate ("dtypes.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + + dataspace_id = H5Screate_simple (2, dims, NULL); + + dataset_id = H5Dcreate (file_id, "/dset", H5T_STD_I32BE, dataspace_id, + H5P_DEFAULT); + + status = H5Dwrite (dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, + H5P_DEFAULT, dset_data); + + status = H5Dclose (dataset_id); + + status = H5Fclose (file_id); + } +\endcode +By using the native types when reading and writing, the code that reads from or writes to a dataset +can be the same for different platforms. + +Can native types also be used when creating a dataset? Yes. However, just be aware that the resulting +datatype in the file will be one of the standard pre-defined types and may be different than expected. + +What happens if you do not use the correct native datatype for a standard (file) datatype? Your data +may be incorrect or not what you expect. + +\section secLBDtypeDer Derived Datatypes +ANY pre-defined datatype can be used to derive user-defined datatypes. + +To create a datatype derived from a pre-defined type: +<ol> +<li>Make a copy of the pre-defined datatype: +\code + tid = H5Tcopy (H5T_STD_I32BE); +\endcode +</li> +<li>Change the datatype.</li> +</ol> + +There are numerous datatype functions that allow a user to alter a pre-defined datatype. See +\ref subsecLBDtypeSpecStr below for a simple example. + +Refer to the \ref H5T in the \ref RM. Example functions are #H5Tset_size and #H5Tset_precision. + +\section secLBDtypeSpec Specific Datatypes +On the <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> +page under <a href="https://confluence.hdfgroup.org/display/HDF5/Examples+by+API#ExamplesbyAPI-datatypes">Datatypes</a> +you will find many example programs for creating and reading datasets with different datatypes. + +Below is additional information on some of the datatypes. See +the <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> +page for examples of these datatypes. + +\subsection subsecLBDtypeSpec Array Datatype vs Array Dataspace +#H5T_ARRAY is a datatype, and it should not be confused with the dataspace of a dataset. The dataspace +of a dataset can consist of a regular array of elements. For example, the datatype for a dataset +could be an atomic datatype like integer, and the dataset could be an N-dimensional appendable array, +as specified by the dataspace. See #H5Screate and #H5Screate_simple for details. + +Unlimited dimensions and subsetting are not supported when using the #H5T_ARRAY datatype. + +The #H5T_ARRAY datatype was primarily created to address the simple case of a compound datatype +when all members of the compound datatype are of the same type and there is no need to subset by +compound datatype members. Creation of such a datatype is more efficient and I/O also requires +less work, because there is no alignment involved. + +\subsection subsecLBDtypeSpecArr Array Datatype +The array class of datatypes, #H5T_ARRAY, allows the construction of true, homogeneous, +multi-dimensional arrays. Since these are homogeneous arrays, each element of the array +will be of the same datatype, designated at the time the array is created. + +Users may be confused by this datatype, as opposed to a dataset with a simple atomic +datatype (eg. integer) that is an array. See subsecLBDtypeSpec for more information. + +Arrays can be nested. Not only is an array datatype used as an element of an HDF5 dataset, +but the elements of an array datatype may be of any datatype, including another array datatype. + +Array datatypes <strong>cannot be subdivided for I/O</strong>; the entire array must be transferred from one +dataset to another. + +Within certain limitations, outlined in the next paragraph, array datatypes may be N-dimensional +and of any dimension size. <strong>Unlimited dimensions, however, are not supported</strong>. Functionality similar +to unlimited dimension arrays is available through the use of variable-length datatypes. + +The maximum number of dimensions, i.e., the maximum rank, of an array datatype is specified by +the HDF5 library constant #H5S_MAX_RANK. The minimum rank is 1 (one). All dimension sizes must +be greater than 0 (zero). + +One array datatype may only be converted to another array datatype if the number of dimensions +and the sizes of the dimensions are equal and the datatype of the first array's elements can be +converted to the datatype of the second array's elements. + +\subsubsection subsubsecLBDtypeSpecArrAPI Array Datatype APIs +There are three functions that are specific to array datatypes: one, #H5Tarray_create, for creating +an array datatype, and two, #H5Tget_array_ndims and #H5Tget_array_dims +for working with existing array datatypes. + +<h4>Creating</h4> +The function #H5Tarray_create creates a new array datatype object. Parameters specify +\li the base datatype of each element of the array, +\li the rank of the array, i.e., the number of dimensions, +\li the size of each dimension, and +\li the dimension permutation of the array, i.e., whether the elements of the array are listed in C or FORTRAN order. + +<h4>Working with existing array datatypes</h4> +When working with existing arrays, one must first determine the the rank, or number of dimensions, of the array. + +The function #H5Tget_array_dims returns the rank of a specified array datatype. + +In many instances, one needs further information. The function #H5Tget_array_dims retrieves the +permutation of the array and the size of each dimension. + +\subsection subsecLBDtypeSpecCmpd Compound + +\subsubsection subsubsecLBDtypeSpecCmpdProp Properties of compound datatypes +A compound datatype is similar to a struct in C or a common block in Fortran. It is a collection of +one or more atomic types or small arrays of such types. To create and use of a compound datatype +you need to refer to various properties of the data compound datatype: +\li It is of class compound. +\li It has a fixed total size, in bytes. +\li It consists of zero or more members (defined in any order) with unique names and which occupy non-overlapping regions within the datum. +\li Each member has its own datatype. +\li Each member is referenced by an index number between zero and N-1, where N is the number of members in the compound datatype. +\li Each member has a name which is unique among its siblings in a compound datatype. +\li Each member has a fixed byte offset, which is the first byte (smallest byte address) of that member in a compound datatype. +\li Each member can be a small array of up to four dimensions. + +Properties of members of a compound datatype are defined when the member is added to the compound type and cannot be subsequently modified. + +\subsubsection subsubsecLBDtypeSpecCmpdDef Defining compound datatypes +Compound datatypes must be built out of other datatypes. First, one creates an empty compound +datatype and specifies its total size. Then members are added to the compound datatype in any order. + +Member names. Each member must have a descriptive name, which is the key used to uniquely identify +the member within the compound datatype. A member name in an HDF5 datatype does not necessarily +have to be the same as the name of the corresponding member in the C struct in memory, although +this is often the case. Nor does one need to define all members of the C struct in the HDF5 +compound datatype (or vice versa). + +Offsets. Usually a C struct will be defined to hold a data point in memory, and the offsets of the +members in memory will be the offsets of the struct members from the beginning of an instance of the +struct. The library defines the macro to compute the offset of a member within a struct: +\code + HOFFSET(s,m) +\endcode +This macro computes the offset of member m within a struct variable s. + +Here is an example in which a compound datatype is created to describe complex numbers whose type +is defined by the complex_t struct. +\code +typedef struct { + double re; /*real part */ + double im; /*imaginary part */ +} complex_t; + +complex_t tmp; /*used only to compute offsets */ +hid_t complex_id = H5Tcreate (H5T_COMPOUND, sizeof tmp); +H5Tinsert (complex_id, "real", HOFFSET(tmp,re), H5T_NATIVE_DOUBLE); +H5Tinsert (complex_id, "imaginary", HOFFSET(tmp,im), H5T_NATIVE_DOUBLE); +\endcode + +\subsection subsecLBDtypeSpecRef Reference +There are two types of Reference datatypes in HDF5: +\li \ref subsubsecLBDtypeSpecRefObj +\li \ref subsubsecLBDtypeSpecRefDset + +\subsubsection subsubsecLBDtypeSpecRefObj Reference to objects +In HDF5, objects (i.e. groups, datasets, and named datatypes) are usually accessed by name. +There is another way to access stored objects -- by reference. + +An object reference is based on the relative file address of the object header in the file +and is constant for the life of the object. Once a reference to an object is created and +stored in a dataset in the file, it can be used to dereference the object it points to. +References are handy for creating a file index or for grouping related objects by storing +references to them in one dataset. + +<h4>Creating and storing references to objects</h4> +The following steps are involved in creating and storing file references to objects: +<ol> +<li>Create the objects or open them if they already exist in the file.</li> +<li>Create a dataset to store the objects' references, by specifying #H5T_STD_REF_OBJ as the datatype</li> +<li>Create and store references to the objects in a buffer, using #H5Rcreate.</li> +<li>Write a buffer with the references to the dataset, using #H5Dwrite with the #H5T_STD_REF_OBJ datatype.</li> +</ol> + +<h4>Reading references and accessing objects using references</h4> +The following steps are involved: +<ol> +<li>Open the dataset with the references and read them. The #H5T_STD_REF_OBJ datatype must be used to describe the memory datatype.</li> +<li>Use the read reference to obtain the identifier of the object the reference points to using #H5Rdereference.</li> +<li>Open the dereferenced object and perform the desired operations.</li> +<li>Close all objects when the task is complete.</li> +</ol> + +\subsubsection subsubsecLBDtypeSpecRefDset Reference to a dataset region +A dataset region reference points to a dataset selection in another dataset. +A reference to the dataset selection (region) is constant for the life of the dataset. + +<h4>Creating and storing references to dataset regions</h4> +The following steps are involved in creating and storing references to a dataset region: +\li Create a dataset to store the dataset region (selection), by passing in #H5T_STD_REF_DSETREG for the datatype when calling #H5Dcreate. +\li Create selection(s) in existing dataset(s) using #H5Sselect_hyperslab and/or #H5Sselect_elements. +\li Create reference(s) to the selection(s) using #H5Rcreate and store them in a buffer. +\li Write the references to the dataset regions in the file. +\li Close all objects. + +<h4>Reading references to dataset regions</h4> +The following steps are involved in reading references to dataset regions and referenced dataset regions (selections). +<ol> +<li>Open and read the dataset containing references to the dataset regions. +The datatype #H5T_STD_REF_DSETREG must be used during read operation.</li> +<li>Use #H5Rdereference to obtain the dataset identifier from the read dataset region reference. + OR + Use #H5Rget_region to obtain the dataspace identifier for the dataset containing the selection from the read dataset region reference. +</li> +<li>With the dataspace identifier, the \ref H5S interface functions, H5Sget_select_*, +can be used to obtain information about the selection.</li> +<li>Close all objects when they are no longer needed.</li> +</ol> + +The dataset with the region references was read by #H5Dread with the #H5T_STD_REF_DSETREG datatype specified. + +The read reference can be used to obtain the dataset identifier by calling #H5Rdereference or by obtaining +obtain spacial information (dataspace and selection) with the call to #H5Rget_region. + +The reference to the dataset region has information for both the dataset itself and its selection. In both functions: +\li The first parameter is an identifier of the dataset with the region references. +\li The second parameter specifies the type of reference stored. In this example, a reference to the dataset region is stored. +\li The third parameter is a buffer containing the reference of the specified type. + +This example introduces several H5Sget_select_* functions used to obtain information about selections: +<table> +<caption>Examples of HDF5 predefined datatypes</caption> +<tr> +<th><strong>Function</strong></th> +<th><strong>Description</strong></th> +</tr> +<tr> +<td>#H5Sget_select_npoints</td> +<td>Returns the number of elements in the hyperslab</td> +</tr> +<tr> +<td>#H5Sget_select_hyper_nblocks</td> +<td>Returns the number of blocks in the hyperslab</td> +</tr> +<tr> +<td>#H5Sget_select_hyper_blocklist</td> +<td>Returns the "lower left" and "upper right" coordinates of the blocks in the hyperslab selection</td> +</tr> +<tr> +<td>#H5Sget_select_bounds</td> +<td>Returns the coordinates of the "minimal" block containing a hyperslab selection</td> +</tr> +<tr> +<td>#H5Sget_select_elem_npoints</td> +<td>Returns the number of points in the element selection</td> +</tr> +<tr> +<td>#H5Sget_select_elem_pointlist</td> +<td>Returns the coordinates of points in the element selection</td> +</tr> +</table> + +\subsection subsecLBDtypeSpecStr String +A simple example of creating a derived datatype is using the string datatype, +#H5T_C_S1 (#H5T_FORTRAN_S1) to create strings of more than one character. Strings +can be stored as either fixed or variable length, and may have different rules +for padding of unused storage. + +\subsubsection subsecLBDtypeSpecStrFix Fixed Length 5-character String Datatype +\code + hid_t strtype; /* Datatype ID */ + herr_t status; + + strtype = H5Tcopy (H5T_C_S1); + status = H5Tset_size (strtype, 5); /* create string of length 5 */ +\endcode + +\subsubsection subsecLBDtypeSpecStrVar Variable Length String Datatype +\code + strtype = H5Tcopy (H5T_C_S1); + status = H5Tset_size (strtype, H5T_VARIABLE); +\endcode + +The ability to derive datatypes from pre-defined types allows users to create any number of datatypes, +from simple to very complex. + +As the term implies, variable length strings are strings of varying lengths. They are stored internally +in a heap, potentially impacting efficiency in the following ways: +\li Heap storage requires more space than regular raw data storage. +\li Heap access generally reduces I/O efficiency because it requires individual read or write operations +for each data element rather than one read or write per dataset or per data selection. +\li A variable length dataset consists of pointers to the heaps of data, not the actual data. Chunking +and filters, including compression, are not available for heaps. + +See \ref subsubsec_datatype_other_strings in the \ref UG, for more information on how fixed and variable +length strings are stored. + +\subsection subsecLBDtypeSpecVL Variable Length +Variable-length (VL) datatypes are sequences of an existing datatype (atomic, VL, or compound) +which are not fixed in length from one dataset location to another. In essence, they are similar +to C character strings -- a sequence of a type which is pointed to by a particular type of +pointer -- although they are implemented more closely to FORTRAN strings by including an explicit +length in the pointer instead of using a particular value to terminate the sequence. + +VL datatypes are useful to the scientific community in many different ways, some of which are listed below: +<ul> +<li>Ragged arrays: Multi-dimensional ragged arrays can be implemented with the last (fastest changing) +dimension being ragged by using a VL datatype as the type of the element stored. (Or as a field in a compound datatype.) +</li> +<li>Fractal arrays: If a compound datatype has a VL field of another compound type with VL fields +(a nested VL datatype), this can be used to implement ragged arrays of ragged arrays, to whatever +nesting depth is required for the user. +</li> +<li>Polygon lists: A common storage requirement is to efficiently store arrays of polygons with +different numbers of vertices. VL datatypes can be used to efficiently and succinctly describe an +array of polygons with different numbers of vertices. +</li> +<li>Character strings: Perhaps the most common use of VL datatypes will be to store C-like VL character +strings in dataset elements or as attributes of objects. +</li> +<li>Indices: An array of VL object references could be used as an index to all the objects in a file +which contain a particular sequence of dataset values. Perhaps an array something like the following: +\code + Value1: Object1, Object3, Object9 + Value2: Object0, Object12, Object14, Object21, Object22 + Value3: Object2 + Value4: <none> + Value5: Object1, Object10, Object12 + . + . +\endcode +</li> +<li>Object Tracking: An array of VL dataset region references can be used as a method of tracking +objects or features appearing in a sequence of datasets. Perhaps an array of them would look like: +\code + Feature1: Dataset1:Region, Dataset3:Region, Dataset9:Region + Feature2: Dataset0:Region, Dataset12:Region, Dataset14:Region, + Dataset21:Region, Dataset22:Region + Feature3: Dataset2:Region + Feature4: <none> + Feature5: Dataset1:Region, Dataset10:Region, Dataset12:Region + . + . +\endcode +</li> +</ul> + +\subsubsection subsubsecLBDtypeSpecVLMem Variable-length datatype memory management +With each element possibly being of different sequence lengths for a dataset with a VL datatype, +the memory for the VL datatype must be dynamically allocated. Currently there are two methods +of managing the memory for VL datatypes: the standard C malloc/free memory allocation routines +or a method of calling user-defined memory management routines to allocate or free memory. Since +the memory allocated when reading (or writing) may be complicated to release, an HDF5 routine is +provided to traverse a memory buffer and free the VL datatype information without leaking memory. + +\subsubsection subsubsecLBDtypeSpecVLDiv Variable-length datatypes cannot be divided +VL datatypes are designed so that they cannot be subdivided by the library with selections, etc. +This design was chosen due to the complexities in specifying selections on each VL element of a +dataset through a selection API that is easy to understand. Also, the selection APIs work on +dataspaces, not on datatypes. At some point in time, we may want to create a way for dataspaces +to have VL components to them and we would need to allow selections of those VL regions, but +that is beyond the scope of this document. + +\subsubsection subsubsecLBDtypeSpecVLErr What happens if the library runs out of memory while reading? +It is possible for a call to #H5Dread to fail while reading in VL datatype information if the memory +required exceeds that which is available. In this case, the #H5Dread call will fail gracefully and any +VL data which has been allocated prior to the memory shortage will be returned to the system via the +memory management routines detailed below. It may be possible to design a partial read API function +at a later date, if demand for such a function warrants. + +\subsubsection subsubsecLBDtypeSpecVLStr Strings as variable-length datatypes +Since character strings are a special case of VL data that is implemented in many different ways on +different machines and in different programming languages, they are handled somewhat differently from +other VL datatypes in HDF5. + +HDF5 has native VL strings for each language API, which are stored the same way on disk, but are +exported through each language API in a natural way for that language. When retrieving VL strings +from a dataset, users may choose to have them stored in memory as a native VL string or in HDF5's +#hvl_t struct for VL datatypes. + +VL strings may be created in one of two ways: by creating a VL datatype with a base type of +#H5T_C_S1 and setting its length to #H5T_VARIABLE. The second method is used to access native VL strings in memory. The +library will convert between the two types, but they are stored on disk using different datatypes +and have different memory representations. + +Multi-byte character representations, such as \em UNICODE or \em wide characters in C/C++, will need the +appropriate character and string datatypes created so that they can be described properly through +the datatype API. Additional conversions between these types and the current ASCII characters +will also be required. + +Variable-width character strings (which might be compressed data or some other encoding) are not +currently handled by this design. We will evaluate how to implement them based on user feedback. + +\subsubsection subsubsecLBDtypeSpecVLAPIs Variable-length datatype APIs + +<h4>Creation</h4> +VL datatypes are created with the #H5Tvlen_create function as follows: +\code +type_id = H5Tvlen_create(hid_t base_type_id); +\endcode +The base datatype will be the datatype that the sequence is composed of, characters for character +strings, vertex coordinates for polygon lists, etc. The base datatype specified for the VL datatype +can be of any HDF5 datatype, including another VL datatype, a compound datatype, or an atomic datatype. + +<h4>Querying base datatype of VL datatype</h4> +It may be necessary to know the base datatype of a VL datatype before memory is allocated, etc. +The base datatype is queried with the #H5Tget_super function, described in the \ref H5T documentation. + +<h4>Querying minimum memory required for VL information</h4> +It order to predict the memory usage that #H5Dread may need to allocate to store VL data while +reading the data, the #H5Dvlen_get_buf_size function is provided: +\code +herr_t H5Dvlen_get_buf_size(hid_t dataset_id, hid_t type_id, hid_t space_id, hsize_t *size) +\endcode +This routine checks the number of bytes required to store the VL data from the dataset, using +the \em space_id for the selection in the dataset on disk and the \em type_id for the memory representation +of the VL data in memory. The *\em size value is modified according to how many bytes are required +to store the VL data in memory. + +<h4>Specifying how to manage memory for the VL datatype</h4> +The memory management method is determined by dataset transfer properties passed into the +#H5Dread and #H5Dwrite functions with the dataset transfer property list. + +Default memory management is set by using #H5P_DEFAULT for the dataset transfer +property list identifier. If #H5P_DEFAULT is used with #H5Dread, the system \em malloc and \em free +calls will be used for allocating and freeing memory. In such a case, #H5P_DEFAULT should +also be passed as the property list identifier to #H5Dvlen_reclaim. + +The rest of this subsection is relevant only to those who choose not to use default memory management. + +The user can choose whether to use the system \em malloc and \em free calls or user-defined, or custom, +memory management functions. If user-defined memory management functions are to be used, the +memory allocation and free routines must be defined via #H5Pset_vlen_mem_manager(), as follows: +\code +herr_t H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc, void *alloc_info, H5MM_free_t free, void *free_info) +\endcode +The \em alloc and \em free parameters identify the memory management routines to be used. If the user +has defined custom memory management routines, \em alloc and/or \em free should be set to make those +routine calls (i.e., the name of the routine is used as the value of the parameter); if the user +prefers to use the system's \em malloc and/or \em free, the \em alloc and \em free parameters, respectively, should be set to \em NULL + +The prototypes for the user-defined functions would appear as follows: +\code +typedef void *(*H5MM_allocate_t)(size_t size, void *info) ; typedef void (*H5MM_free_t)(void *mem, void *free_info) ; +\endcode +The \em alloc_info and \em free_info parameters can be used to pass along any required information to +the user's memory management routines. + +In summary, if the user has defined custom memory management routines, the name(s) of the routines +are passed in the \em alloc and \em free parameters and the custom routines' parameters are passed in the +\em alloc_info and \em free_info parameters. If the user wishes to use the system \em malloc and \em free functions, +the \em alloc and/or \em free parameters are set to \em NULL and the \em alloc_info and \em free_info parameters are ignored. + +<h4>Recovering memory from VL buffers read in</h4> +The complex memory buffers created for a VL datatype may be reclaimed with the #H5Dvlen_reclaim +function call, as follows: +\code +herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void *buf); +\endcode + +The \em type_id must be the datatype stored in the buffer, \em space_id describes the selection for the +memory buffer to free the VL datatypes within, \em plist_id is the dataset transfer property list +which was used for the I/O transfer to create the buffer, and \em buf is the pointer to the buffer +to free the VL memory within. The VL structures (#hvl_t) in the user's buffer are modified to zero +out the VL information after it has been freed. + +If nested VL datatypes were used to create the buffer, this routine frees them from the bottom up, +releasing all the memory without creating memory leaks. + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +*/ diff --git a/doxygen/dox/LearnBasics3.dox b/doxygen/dox/LearnBasics3.dox new file mode 100644 index 0000000..2fe0f52 --- /dev/null +++ b/doxygen/dox/LearnBasics3.dox @@ -0,0 +1,1015 @@ +/** @page LBPropsList Property Lists Basics +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBPList What is a Property (or Property List)? +In HDF5, a property or property list is a characteristic or feature associated with an HDF5 object. +There are default properties which handle the most common needs. These default properties are +specified by passing in #H5P_DEFAULT for the Property List parameter of a function. Default properties +can be modified by use of the \ref H5P interface and function parameters. + +The \ref H5P API allows a user to take advantage of the more powerful features in HDF5. It typically +supports unusual cases when creating or accessing HDF5 objects. There is a programming model for +working with Property Lists in HDF5 (see below). + +For examples of modifying a property list, see these tutorial topics: +\li \see \ref LBDsetLayout +\li \see \ref LBExtDset +\li \see \ref LBComDset + +There are many Property Lists associated with creating and accessing objects in HDF5. See the +\ref H5P Interface documentation in the HDF5 \ref RM for a list of the different +properties associated with HDF5 interfaces. + +In summary: +\li Properties are features of HDF5 objects, that can be changed by use of the Property List API and function parameters. +\li Property lists provide a mechanism for adding functionality to HDF5 calls without increasing the number of arguments used for a given call. +\li The Property List API supports unusual cases when creating and accessing HDF5 objects. + +\section secLBPListProg Programming Model +Default properties are specified by simply passing in #H5P_DEFAULT (C) / H5P_DEFAULT_F (F90) for +the property list parameter in those functions for which properties can be changed. + +The programming model for changing a property list is as follows: +\li Create a copy or "instance" of the desired pre-defined property type, using the #H5Pcreate call. This +will return a property list identifier. Please see the \ref RM entry for #H5Pcreate, for a comprehensive +list of the property types. +\li With the property list identifier, modify the property, using the \ref H5P APIs. +\li Modify the object feature, by passing the property list identifier into the corresponding HDF5 object function. +\li Close the property list when done, using #H5Pclose. + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBDsetLayout Dataset Storage Layout +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBDsetLayoutDesc Description of a Dataset + +\section secLBDsetLayout Dataset Storage Layout +The storage information, or storage layout, defines how the raw data values in the dataset are +physically stored on disk. There are three ways that a dataset can be stored: +\li contiguous +\li chunked +\li compact + +See the #H5Pset_layout/#H5Pget_layout APIs for details. + +\subsection subsecLBDsetLayoutCont Contiguous +If the storage layout is contiguous, then the raw data values will be stored physically adjacent +to each other in the HDF5 file (in one contiguous block). This is the default layout for a dataset. +In other words, if you do not explicitly change the storage layout for the dataset, then it will +be stored contiguously. +<table> +<tr> +<td> +\image html tutr-locons.png +</td> +</tr> +</table> + +\subsection subsecLBDsetLayoutChunk Chunked +With a chunked storage layout the data is stored in equal-sized blocks or chunks of +a pre-defined size. The HDF5 library always writes and reads the entire chunk: +<table> +<tr> +<td> +\image html tutr-lochk.png +</td> +</tr> +</table> + +Each chunk is stored as a separate contiguous block in the HDF5 file. There is a chunk index +which keeps track of the chunks associated with a dataset: +<table> +<tr> +<td> +\image html tutr-lochks.png +</td> +</tr> +</table> + + +\subsubsection susubsecLBDsetLayoutChunkWhy Why Chunking ? +Chunking is required for enabling compression and other filters, as well as for creating extendible +or unlimited dimension datasets. + +It is also commonly used when subsetting very large datasets. Using the chunking layout can +greatly improve performance when subsetting large datasets, because only the chunks required +will need to be accessed. However, it is easy to use chunking without considering the consequences +of the chunk size, which can lead to strikingly poor performance. + +Note that a chunk always has the same rank as the dataset and the chunk's dimensions do not need +to be factors of the dataset dimensions. + +Writing or reading a chunked dataset is transparent to the application. You would use the same +set of operations that you would use for a contiguous dataset. For example: +\code + H5Dopen (...); + H5Sselect_hyperslab (...); + H5Dread (...); +\endcode + +\subsubsection susubsecLBDsetLayoutChunkProb Problems Using Chunking +Issues that can cause performance problems with chunking include: +\li Chunks are too small. +If a very small chunk size is specified for a dataset it can cause the dataset to be excessively +large and it can result in degraded performance when accessing the dataset. The smaller the chunk +size the more chunks that HDF5 has to keep track of, and the more time it will take to search for a chunk. +\li Chunks are too large. +An entire chunk has to be read and uncompressed before performing an operation. There can be a +performance penalty for reading a small subset, if the chunk size is substantially larger than +the subset. Also, a dataset may be larger than expected if there are chunks that only contain a +small amount of data. +\li A chunk does not fit in the Chunk Cache. +Every chunked dataset has a chunk cache associated with it that has a default size of 1 MB. The +purpose of the chunk cache is to improve performance by keeping chunks that are accessed frequently +in memory so that they do not have to be accessed from disk. If a chunk is too large to fit in the +chunk cache, it can significantly degrade performance. However, the size of the chunk cache can be +increased by calling #H5Pset_chunk_cache. + +It is a good idea to: +\li Avoid very small chunk sizes, and be aware of the 1 MB chunk cache size default. +\li Test the data with different chunk sizes to determine the optimal chunk size to use. +\li Consider the chunk size in terms of the most common access patterns that will be used once the dataset has been created. + +\subsection subsecLBDsetLayoutCom Compact +A compact dataset is one in which the raw data is stored in the object header of the dataset. +This layout is for very small datasets that can easily fit in the object header. + +The compact layout can improve storage and access performance for files that have many very tiny +datasets. With one I/O access both the header and data values can be read. The compact layout reduces +the size of a file, as the data is stored with the header which will always be allocated for a dataset. +However, the object header is 64 KB in size, so this layout can only be used for very small datasets. + +\section secLBDsetLayoutProg Programming Model to Modify the Storage Layout +To modify the storage layout, the following steps must be done: +\li Create a Dataset Creation Property list. (See #H5Pcreate) +\li Modify the property list. +To use chunked storage layout, call: #H5Pset_chunk +To use the compact storage layout, call: #H5Pset_layout +\li Create a dataset with the modified property list. (See #H5Dcreate) +\li Close the property list. (See #H5Pclose) +For example code, see the \ref HDF5Examples page. +Specifically look at the <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a>. +There are examples for different languages. + +The C example to create a chunked dataset is: +<a href="https://support.hdfgroup.org/ftp/HDF5/examples/examples-by-api/hdf5-examples/1_8/C/H5D/h5ex_d_chunk.c">h5ex_d_chunk.c</a> +The C example to create a compact dataset is: +<a href="https://support.hdfgroup.org/ftp/HDF5/examples/examples-by-api/hdf5-examples/1_8/C/H5D/h5ex_d_compact.c">h5ex_d_compact.c</a> + +\section secLBDsetLayoutChange Changing the Layout after Dataset Creation +The dataset layout is a Dataset Creation Property List. This means that once the dataset has been +created the dataset layout cannot be changed. The h5repack utility can be used to write a file +to a new with a new layout. + +\section secLBDsetLayoutSource Sources of Information +<a href="https://confluence.hdfgroup.org/display/HDF5/Chunking+in+HDF5">Chunking in HDF5</a> +(See the documentation on <a href="https://confluence.hdfgroup.org/display/HDF5/Advanced+Topics+in+HDF5">Advanced Topics in HDF5</a>) +\see \ref sec_plist in the HDF5 \ref UG. + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + + +@page LBExtDset Extendible Datasets +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBExtDsetCreate Creating an Extendible Dataset +An extendible dataset is one whose dimensions can grow. HDF5 allows you to define a dataset to have +certain initial dimensions, then to later increase the size of any of the initial dimensions. + +HDF5 requires you to use chunking to define extendible datasets. This makes it possible to extend +datasets efficiently without having to excessively reorganize storage. (To use chunking efficiently, +be sure to see the advanced topic, <a href="https://confluence.hdfgroup.org/display/HDF5/Chunking+in+HDF5">Chunking in HDF5</a>.) + +The following operations are required in order to extend a dataset: +\li Declare the dataspace of the dataset to have unlimited dimensions for all dimensions that might eventually be extended. +\li Set dataset creation properties to enable chunking. +\li Create the dataset. +\li Extend the size of the dataset. + +\section secLBExtDsetProg Programming Example + +\subsection subsecLBExtDsetProgDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example shows how to create a 3 x 3 extendible dataset, write to that dataset, extend the dataset +to 10x3, and write to the dataset again. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection subsecLBExtDsetProgRem Remarks +\li An unlimited dimension dataspace is specified with the #H5Screate_simple call, by passing in +#H5S_UNLIMITED as an element of the maxdims array. +\li The #H5Pcreate call creates a new property as an instance of a property list class. For creating +an extendible array dataset, pass in #H5P_DATASET_CREATE for the property list class. +\li The #H5Pset_chunk call modifies a Dataset Creation Property List instance to store a chunked +layout dataset and sets the size of the chunks used. +\li To extend an unlimited dimension dataset use the the #H5Dset_extent call. Please be aware that +after this call, the dataset's dataspace must be refreshed with #H5Dget_space before more data can be accessed. +\li The #H5Pget_chunk call retrieves the size of chunks for the raw data of a chunked layout dataset. +\li Once there is no longer a need for a Property List instance, it should be closed with the #H5Pclose call. + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBComDset Compressed Datasets +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBComDsetCreate Creating a Compressed Dataset +HDF5 requires you to use chunking to create a compressed dataset. (To use chunking efficiently, +be sure to see the advanced topic, <a href="https://confluence.hdfgroup.org/display/HDF5/Chunking+in+HDF5">Chunking in HDF5</a>.) + +The following operations are required in order to create a compressed dataset: +\li Create a dataset creation property list. +\li Modify the dataset creation property list instance to enable chunking and to enable compression. +\li Create the dataset. +\li Close the dataset creation property list and dataset. + +For more information on compression, see the FAQ question on <a href="https://confluence.hdfgroup.org/display/HDF5/Using+Compression+in+HDF5">Using Compression in HDF5</a>. + +\section secLBComDsetProg Programming Example + +\subsection subsecLBComDsetProgDesc Description +See \ref LBExamples for the examples used in the \ref LearnBasics tutorial. + +The example creates a chunked and ZLIB compressed dataset. It also includes comments for what needs +to be done to create an SZIP compressed dataset. The example then reopens the dataset, prints the +filter information, and reads the dataset. + +For details on compiling an HDF5 application: +[ \ref LBCompiling ] + +\subsection subsecLBComDsetProgRem Remarks +\li The #H5Pset_chunk call modifies a Dataset Creation Property List instance to store a chunked layout +dataset and sets the size of the chunks used. +\li The #H5Pset_deflate call modifies the Dataset Creation Property List instance to use ZLIB or DEFLATE +compression. The #H5Pset_szip call modifies it to use SZIP compression. There are different compression +parameters required for each compression method. +\li SZIP compression can only be used with atomic datatypes that are integer, float, or char. It cannot be +applied to compound, array, variable-length, enumerations, or other user-defined datatypes. The call +to #H5Dcreate will fail if attempting to create an SZIP compressed dataset with a non-allowed datatype. +The conflict can only be detected when the property list is used. + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBContents Discovering the Contents of an HDF5 File +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBContents Discovering what is in an HDF5 file +HDFView and h5dump are standalone tools which cannot be called within an application, and using +#H5Dopen and #H5Dread require that you know the name of the HDF5 dataset. How would an application +that has no prior knowledge of an HDF5 file be able to determine or discover the contents of it, +much like HDFView and h5dump? + +The answer is that there are ways to discover the contents of an HDF5 file, by using the +\ref H5G, \ref H5L and \ref H5O APIs: +\li The \ref H5G interface (covered earlier) consists of routines for working with groups. A group is +a structure that can be used to organize zero or more HDF5 objects, not unlike a Unix directory. +\li The \ref H5L interface consists of link routines. A link is a path between groups. The \ref H5L interface +allows objects to be accessed by use of these links. +\li The \ref H5O interface consists of routines for working with objects. Datasets, groups, and committed +datatypes are all objects in HDF5. + +Interface routines that simplify the process: +\li #H5Literate traverses the links in a specified group, in the order of the specified index, using a +user-defined callback routine. (A callback function is one that will be called when a certain condition +is met, at a certain point in the future.) +\li #H5Ovisit / #H5Lvisit recursively visit all objects/links accessible from a specified object/group. + + +\section secLBContentsProg Programming Example + +\subsection subsecLBContentsProgUsing Using #H5Literate, #H5Lvisit and #H5Ovisit +For example code, see the \ref HDF5Examples page. +Specifically look at the <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a>. +There are examples for different languages, where examples of using #H5Literate and #H5Ovisit/#H5Lvisit are included. + +The h5ex_g_traverse example traverses a file using H5Literate: +\li C: <a href="https://support.hdfgroup.org/ftp/HDF5/examples/examples-by-api/hdf5-examples/1_8/C/H5G/h5ex_g_traverse.c">h5ex_g_traverse.c</a> +\li F90: <a href="https://support.hdfgroup.org/ftp/HDF5/examples/examples-by-api/hdf5-examples/1_8/FORTRAN/H5G/h5ex_g_traverse_F03.f90">h5ex_g_traverse_F03.f90</a> + +The h5ex_g_visit example traverses a file using H5Ovisit and H5Lvisit: +\li C: <a href="https://support.hdfgroup.org/ftp/HDF5/examples/examples-by-api/hdf5-examples/1_8/C/H5G/h5ex_g_visit.c">h5ex_g_visit.c</a> +\li F90: <a href="https://support.hdfgroup.org/ftp/HDF5/examples/examples-by-api/hdf5-examples/1_8/FORTRAN/H5G/h5ex_g_visit_F03.f90">h5ex_g_visit_F03.f90</a> + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBQuiz Learning the basics QUIZ +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\ref LBFileOrg +<ol> +<li>Name and describe the two primary objects that can be stored in an HDF5 file. +</li> +<li>What is an attribute? +</li> +<li>Give the path name for an object called <code style="background-color:whitesmoke;">harry</code> that is a member of a group called <code style="background-color:whitesmoke;">dick</code>, which, in turn, is a member of the root group. +</li> +</ol> + +\ref LBAPI +<ol> +<li>Describe the purpose of each of the following HDF5 APIs: +\code + H5A, H5D, H5E, H5F, H5G, H5T, H5Z +\endcode +</li> +</ol> + +\ref LBFileCreate +<ol> +<li>What two HDF5 routines must be called to create an HDF5 file? +</li> +<li>What include file must be included in any file that uses the HDF5 library? +</li> +<li>An HDF5 file is never completely empty because as soon as it is created, it automatically contains a certain primary object. What is that object? +</li> +</ol> + +\ref LBDsetCreate +<ol> +<li>Name and describe two major datatype categories. +</li> +<li>List the HDF5 atomic datatypes. Give an example of a predefined datatype. How would you create a string dataset? +</li> +<li>What does the dataspace describe? What are the major characteristics of the simple dataspace? +</li> +<li>What information needs to be passed to the #H5Dcreate function, i.e., what information is needed to describe a dataset at creation time? +</li> +</ol> + + +\ref LBDsetRW +<ol> +<li>What are six pieces of information which need to be specified for reading and writing a dataset? +</li> +<li>Why are both the memory dataspace and file dataspace needed for read/write operations, while only the memory datatype is required? +</li> +<li>In Figure 6.1, what does this line mean? +\code +DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } +\endcode +</li> +</ol> + + +\ref LBAttrCreate +<ol> +<li>What is an attribute? +</li> +<li>Can partial I/O operations be performed on attributes? +</li> +</ol> + + +\ref LBGrpCreate +<ol> +<li>What are the two primary objects that can be included in a group? +</li> +</ol> + + +\ref LBGrpCreateNames +<ol> +<li>Group names can be specified in two ways. What are these two types of group names? +</li> +<li>You have a dataset named <code style="background-color:whitesmoke;">moo</code> in the group <code style="background-color:whitesmoke;">boo</code>, which is in the group <code style="background-color:whitesmoke;">foo</code>, which, in turn, +is in the <code style="background-color:whitesmoke;">root</code> group. How would you specify an absolute name to access this dataset? +</li> +</ol> + + +\ref LBGrpDset +<ol> +<li>Describe a way to access the dataset moo described in the previous section +(question 2) using a relative name. Describe a way to access the same dataset using an absolute name. +</li> +</ol> + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBQuizAnswers Learning the basics QUIZ with Answers +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\ref LBFileOrg +<ol> +<li>Name and describe the two primary objects that can be stored in an HDF5 file. +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>Group: A grouping structure containing zero or more HDF5 objects, together with supporting metadata.<br /> +Dataset: A multidimensional array of data elements, together with supporting metadata. +</td> +</tr> +</table> +</li> +<li>What is an attribute? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>An HDF5 attribute is a user-defined HDF5 structure that provides extra information about an HDF5 object. +</td> +</tr> +</table> +</li> +<li>Give the path name for an object called <code style="background-color:whitesmoke;">harry</code> that is a member of a group called <code style="background-color:whitesmoke;">dick</code>, which, in turn, is a member of the root group. +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>/dick/harry +</td> +</tr> +</table> +</li> +</ol> + +\ref LBAPI +<ol> +<li>Describe the purpose of each of the following HDF5 APIs: +\code + H5A, H5D, H5E, H5F, H5G, H5T, H5Z +\endcode +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>H5A: Attribute access and manipulation routines +<br /> +H5D: Dataset access and manipulation routines +<br /> +H5E: Error handling routines H5F: File access routines +<br /> +H5G: Routines for creating and operating on groups +<br /> +H5T: Routines for creating and manipulating the datatypes of dataset elements +<br /> +H5Z: Data compression routines +</td> +</tr> +</table> +</li> +</ol> + +\ref LBFileCreate +<ol> +<li>What two HDF5 routines must be called to create an HDF5 file? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>#H5Fcreate and #H5Fclose. +</td> +</tr> +</table> +</li> +<li>What include file must be included in any file that uses the HDF5 library? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>hdf5.h must be included because it contains definitions and declarations used by the library. +</td> +</tr> +</table> +</li> +<li>An HDF5 file is never completely empty because as soon as it is created, it automatically contains a certain primary object. What is that object? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>The root group. +</td> +</tr> +</table> +</li> +</ol> + +\ref LBDsetCreate +<ol> +<li>Name and describe two major datatype categories. +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>Atomic datatype: An atomic datatype cannot be decomposed into smaller units at the API level. +<br /> +Compound datatype: A compound datatype is a collection of atomic and compound datatypes, or small arrays of such types. +</td> +</tr> +</table> +</li> +<li>List the HDF5 atomic datatypes. Give an example of a predefined datatype. How would you create a string dataset? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>There are six HDF5 atomic datatypes: integer, floating point, date and time, character string, bit field, and opaque. +<br /> +Examples of predefined datatypes include the following:<br /> +\li #H5T_IEEE_F32LE - 4-byte little-endian, IEEE floating point +\li #H5T_NATIVE_INT - native integer + +You would create a string dataset with the #H5T_C_S1 datatype, and set the size of the string with the #H5Tset_size call. +</td> +</tr> +</table> +</li> +<li>What does the dataspace describe? What are the major characteristics of the simple dataspace? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>The dataspace describes the dimensionality of the dataset. A simple dataspace is characterized by its rank and dimension sizes. +</td> +</tr> +</table> +</li> +<li>What information needs to be passed to the #H5Dcreate function, i.e., what information is needed to describe a dataset at creation time? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>The dataset location, name, dataspace, datatype, and dataset creation property list. +</td> +</tr> +</table> +</li> +</ol> + + +\ref LBDsetRW +<ol> +<li>What are six pieces of information which need to be specified for reading and writing a dataset? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>The dataset identifier, the dataset's datatype and dataspace in memory, the dataspace in the file, +the dataset transfer property list, and a data buffer. +</td> +</tr> +</table> +</li> +<li>Why are both the memory dataspace and file dataspace needed for read/write operations, while only the memory datatype is required? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>A dataset's file datatype is not required for a read/write operation because the file datatype is specified +when the dataset is created and cannot be changed. Both file and memory dataspaces are required for dataset +subsetting and for performing partial I/O operations. +</td> +</tr> +</table> +</li> +<li>In Figure 6.1, what does this line mean? +\code +DATASPACE { SIMPLE (4 , 6 ) / ( 4 , 6 ) } +\endcode +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>It means that the dataset dset has a simple dataspace with the current dimensions (4,6) and the maximum size of the dimensions (4,6). +</td> +</tr> +</table> +</li> +</ol> + + +\ref LBAttrCreate +<ol> +<li>What is an attribute? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>An attribute is a dataset attached to an object. It describes the nature and/or the intended usage of the object. +</td> +</tr> +</table> +</li> +<li>Can partial I/O operations be performed on attributes? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>No. +</td> +</tr> +</table> +</li> +</ol> + + +\ref LBGrpCreate +<ol> +<li>What are the two primary objects that can be included in a group? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>A group and a dataset. +</td> +</tr> +</table> +</li> +</ol> + + +\ref LBGrpCreateNames +<ol> +<li>Group names can be specified in two ways. What are these two types of group names? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>Relative and absolute. +</td> +</tr> +</table> +</li> +<li>You have a dataset named <code style="background-color:whitesmoke;">moo</code> in the group <code style="background-color:whitesmoke;">boo</code>, which is in the group <code style="background-color:whitesmoke;">foo</code>, which, in turn, +is in the <code style="background-color:whitesmoke;">root</code> group. How would you specify an absolute name to access this dataset? +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>/foo/boo/moo +</td> +</tr> +</table> +</li> +</ol> + + +\ref LBGrpDset +<ol> +<li>Describe a way to access the dataset moo described in the previous section +(question 2) using a relative name. Describe a way to access the same dataset using an absolute name. +<table> +<tr> +<th><strong>Answer</strong> +</th> +<td>Access the group /foo and get the group ID. Access the group boo using the group ID obtained in Step 1. +Access the dataset moo using the group ID obtained in Step 2. +\code +gid = H5Gopen (file_id, "/foo", 0); /* absolute path */ +gid1 = H5Gopen (gid, "boo", 0); /* relative path */ +did = H5Dopen (gid1, "moo"); /* relative path */ +\endcode +Access the group /foo and get the group ID. Access the dataset boo/moo with the group ID just obtained. +\code +gid = H5Gopen (file_id, "/foo", 0); /* absolute path */ +did = H5Dopen (gid, "boo/moo"); /* relative path */ +\endcode +Access the dataset with an absolute path. +\code +did = H5Dopen (file_id, "/foo/boo/moo"); /* absolute path */ +\endcode +</td> +</tr> +</table> +</li> +</ol> + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBCompiling Compiling HDF5 Applications +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +\section secLBCompiling Tools and Instructions on Compiling +Compiling applications to use the HDF5 Library can be as simple as executing: +\code +h5cc -o myprog myprog.c +\endcode + +As an application's file base evolves, there are better solutions using autotools and makefiles or +CMake and CMakeLists.txt files. Many tutorials and references can be found with a simple search. + +This tutorial section will discuss the use of compile scripts on Linux. +See the \ref secLBCompilingVS section for compiling with Visual Studio. + +\section secLBCompilingLinux Compile Scripts +When the library is built, the following compile scripts are included: +\li h5cc: compile script for HDF5 C programs +\li h5fc: compile script for HDF5 F90 programs +\li h5c++: compile script for HDF5 C++ programs + +These scripts are easilye used to compile single file applications, such as those included in the tutorial. +<table> +<tr> +<th><strong>Warning</strong> +</th> +<td>The h5cc/h5fc/h5c++ compile scripts are included when building with configure. Versions of +these compile scripts have also been added to CMake for Linux ONLY. The CMake versions rely on pkgconfig files. +</td> +</tr> +</table> + +<h4>Examples of Using the Unix Compile Scripts:</h4> +Following are examples of compiling and running an application with the Unix compile scripts: +\code + h5fc myprog.f90 + ./a.out + + h5cc -o myprog myprog.c + ./myprog +\endcode + +To see how the libraries linked in with a compile script were configured and built, use the +-showconfig option. For example, if using h5cc type: +\code + h5cc -showconfig +\endcode + +<h4>Detailed Description of Unix Compile Scripts:</h4> +The h5cc, h5c++, and h5fc compile scripts come with the HDF5 binary distributions (include files, +libraries, and utilities) for the platforms we support. The h5c++ and h5fc utilities are ONLY present +if the library was built with C++ and Fortran. + +\section secLBCompilingVS Using Visual Studio + + 1. If you are building on 64-bit Windows, find the "Platform" dropdown + and select "x64". Also select the correct Configuration (Debug, Release, RelWithDebInfo, etc) + + 2. Set up path for external headers + + The HDF5 install path settings will need to be in the project property sheets per project. + Go to "Project" and select "Properties", find "Configuration Properties", + and then "C/C++". + + 2.1 Add the header path to the "Additional Include Directories" setting. Under "C/C++" + find "General" and select "Additional Include Directories". Select "Edit" from the dropdown + and add the HDF5 install/include path to the list. + (Ex: "C:\Program Files\HDF_Group\HDF5\1.10.9\include") + + 2.2 Building applications with the dynamic/shared hdf5 libraries requires + that the "H5_BUILT_AS_DYNAMIC_LIB" compile definition be used. Under "C/C++" + find "Preprocessor" and select "Preprocessor Definitions". Select "Edit" from the dropdown + and add "H5_BUILT_AS_DYNAMIC_LIB" to the list. + + 3. Set up path for external libraries + + The HDF5 install path/lib settings will need to be in the project property sheets per project. + Go to "Project" and select "Properties", find "Configuration Properties", + and then "Linker". + + 3.1 Add the libraries to the "Additional Dependencies" setting. Under "Linker" + find "Input" and select "Additional Dependencies". Select "Edit" from the dropdown + and add the required HDF5 install/lib path to the list. + (Ex: "C:\Program Files\HDF_Group\HDF5\1.10.9\lib\hdf5.lib") + + 3.2 For static builds, the external libraries should be added. + For example, to compile a C++ application, enter: + libhdf5_cpp.lib libhdf5.lib libz.lib libszaec.lib libaec.lib + +\section secLBCompilingLibs HDF5 Libraries +Following are the libraries included with HDF5. Whether you are using the Unix compile scripts or +Makefiles, or are compiling on Windows, these libraries are or may need to be specified. The order +they are specified is important on Linux: + +<table> +<caption>HDF5 Static Libraries</caption> +<tr> +<th>Library</th> +<th>Linux Name</th> +<th>Mac Name</th> +<th>Windows Name</th> +</tr> +<tr> +<td> +\code +HDF5 High Level C++ APIs +HDF5 C++ Library +HDF5 High Level Fortran APIs +HDF5 Fortran Library +HDF5 High Level C APIs +HDF5 C Library +\endcode +</td> +<td> +\code +libhdf5_hl_cpp.a +libhdf5_cpp.a +libhdf5hl_fortran.a +libhdf5_fortran.a +libhdf5_hl.a +libhdf5.a +\endcode +</td> +<td> +\code +libhdf5_hl_cpp.a +libhdf5_cpp.a +libhdf5hl_fortran.a +libhdf5_fortran.a +libhdf5_hl.a +libhdf5.a +\endcode +</td> +<td> +<em>Windows</em> +\code +libhdf5_hl_cpp.lib +libhdf5_cpp.lib +libhdf5hl_fortran.lib +libhdf5_fortran.lib +libhdf5_hl.lib +libhdf5.lib +\endcode +</tr> +</table> + +<table> +<caption>HDF5 Shared Libraries</caption> +<tr> +<th>Library</th> +<th>Linux Name</th> +<th>Mac Name</th> +<th>Windows Name</th> +</tr> +<tr> +<td> +\code +HDF5 High Level C++ APIs +HDF5 C++ Library +HDF5 High Level Fortran APIs +HDF5 Fortran Library +HDF5 High Level C APIs +HDF5 C Library +\endcode +</td> +<td> +\code +libhdf5_hl_cpp.so +libhdf5_cpp.so +libhdf5hl_fortran.so +libhdf5_fortran.so +libhdf5_hl.so +libhdf5.so +\endcode +</td> +<td> +\code +libhdf5_hl_cpp.dylib +libhdf5_cpp.dylib +libhdf5hl_fortran.dylib +libhdf5_fortran.dylib +libhdf5_hl.dylib +libhdf5.dylib +\endcode +</td> +<td> +\code +hdf5_hl_cpp.lib +hdf5_cpp.lib +hdf5hl_fortran.lib +hdf5_fortran.lib +hdf5_hl.lib +hdf5.lib +\endcode +</tr> +</table> + +<table> +<caption>External Libraries</caption> +<tr> +<th>Library</th> +<th>Linux Name</th> +<th>Mac Name</th> +<th>Windows Name</th> +</tr> +<tr> +<td> +\code +SZIP Compression Library +SZIP Compression Library +ZLIB or DEFLATE Compression Library +\endcode +</td> +<td> +\code +libszaec.a +libaec.a +libz.a +\endcode +</td> +<td> +\code +libszaec.a +libaec.a +libz.a +\endcode +</td> +<td> +\code +libszaec.lib +libaec.lib +libz.lib +\endcode +</td> +</tr> +</table> + +The pre-compiled binaries, in particular, are built (if at all possible) with these libraries as well as with +SZIP and ZLIB. If using shared libraries you may need to add the path to the library to LD_LIBRARY_PATH on Linux +or on WINDOWS you may need to add the path to the bin folder to PATH. + +\section secLBCompilingCMake Compiling an Application with CMake + +\subsection subsecLBCompilingCMakeScripts CMake Scripts for Building Applications +Simple scripts are provided for building applications with different languages and options. +See <a href="https://confluence.hdfgroup.org/display/support/CMake+Scripts+for+Building+Applications">CMake Scripts for Building Applications</a>. + +For a more complete script (and to help resolve issues) see the script provided with the HDF5 Examples project. + +\subsection subsecLBCompilingCMakeExamples HDF5 Examples +The installed HDF5 can be verified by compiling the HDF5 Examples project, included with the CMake built HDF5 binaries +in the share folder or you can go to the <a href="https://github.com/HDFGroup/hdf5_examples">HDF5 Examples</a> github repository. + +Go into the share directory and follow the instructions in USING_CMake_examples.txt to build the examples. + +In general, users must first set the HDF5_ROOT environment variable to the installed location of the CMake +configuration files for HDF5. For example, on Windows the following path might be set: + +\code + HDF5_ROOT=C:/Program Files/HDF_Group/HDF5/1.N.N +\endcode + +\subsection subsecLBCompilingCMakeTroubless Troubleshooting CMake +<h4>How do you use find_package with HDF5?</h4> +To use find_package you will first need to make sure that HDF5_ROOT is set correctly. For setting this +environment variable see the Preconditions in the USING_HDF5_CMake.txt file in the share directory. + +See the CMakeLists.txt file provided with these examples for how to use find_package with HDF5. + +Please note that the find_package invocation changed to require "shared" or "static": +\code + FIND_PACKAGE(HDF5 COMPONENTS C HL NO_MODULE REQUIRED shared) + FIND_PACKAGE(HDF5 COMPONENTS C HL NO_MODULE REQUIRED static) +\endcode + +Previously, the find_package invocation was: +\code + FIND_PACKAGE(HDF5 COMPONENTS C HL NO_MODULE REQUIRED) +\endcode + +<h4>My platform/compiler is not included. Can I still use the configuration files?</h4> +Yes, you can but you will have to edit the HDF5_Examples.cmake file and update the variable: +\code + CTEST_CMAKE_GENERATOR +\endcode + +The generators for your platform can be seen by typing: +\code + cmake --help +\endcode + +<h4>What do I do if the build fails?</h4> +I received an error during the build and the application binary is not in the +build directory as I expected. How do I determine what the problem is? + +If the error is not clear, then the first thing you may want to do is replace the -V (Dash Uppercase Vee) +option for ctest in the build script to -VV (Dash Uppercase Vee Uppercase Vee). Then remove the build +directory and re-run the build script. The output should be more verbose. + +If the error is still not clear, then check the log files. You will find those in the build directory. +For example, on Unix the log files will be in: +\code + build/Testing/Temporary/ +\endcode +There are log files for the configure, test, and build. + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +@page LBTraining Training Videos +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics +<hr> + +<a href="https://confluence.hdfgroup.org/display/HDF5/Training+Videos">Training Videos</a> + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref LearnBasics + +*/ diff --git a/doxygen/dox/LearnHDFView.dox b/doxygen/dox/LearnHDFView.dox new file mode 100644 index 0000000..b1f632c --- /dev/null +++ b/doxygen/dox/LearnHDFView.dox @@ -0,0 +1,472 @@ +/** @page LearnHDFView Learning HDF5 with HDFView + +Navigate back: \ref index "Main" / \ref GettingStarted +<hr> + +This tutorial enables you to get a feel for HDF5 by using the HDFView browser. It does NOT require +any programming experience. + +\section sec_learn_hv_install HDFView Installation +\li Download and install HDFView. It can be downloaded from the <a href="https://portal.hdfgroup.org/display/support/Download+HDFView">Download HDFView</a> page. +\li Obtain the <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a> text file, used in the tutorial. + +\section sec_learn_hv_begin Begin Tutorial +Once you have HDFView installed, bring it up and you are ready to begin the tutorial. + +<table style="background-color:#FAFAD2"> +<caption> +Unable to complete tutorial because fields are greyed out? +</caption> +<tr> +<td> +This tutorial requires that the default HDFView File Access Mode be Read / Write. If fields are greyed out so that you cannot select them, then the File Access Mode is Read Only. + +To change the File Access Mode follow these steps: +<ul> +<li>Bring up HDFView</li> +<li>Left-mouse click on the Tools pull-down menu and select User Options.</li> +<li>A Preferences window pops up with the General Settings tab selected. +About half-way down you will see Default File Access Mode. +Select Read / Write.</li> +<li>Click on Apply and Close at the bottom of the window.</li> +<li>Close down HDFView.</li> +<li>Bring HDFView back up and try the tutorial again.</li> +PLEASE BE AWARE that selecting a File Access Mode of Read / Write can result in changes to the timestamp of HDF files that are viewed with HDFView. In general, a File Access Mode +of Read Only should be used to ensure that this does not occur. +</ul> +</td> +</tr> +</table> + +\subsection subsec_learn_hv_begin_topics Topics Covered +Following are the topics covered in the tutorial. The first topic creates the file that is used in +the subsequent topics. +<ul> +<li>@ref subsec_learn_hv_topics_file</li> +<li>@ref subsec_learn_hv_topics_image</li> +<li>@ref subsec_learn_hv_topics_attr</li> +<li>@ref subsec_learn_hv_topics_compress</li> +<li>@ref subsec_learn_hv_topics_subset</li> +<li>@ref subsec_learn_hv_topics_table</li> +</ul> + +\section sec_learn_hv_topics Topics + +\subsection subsec_learn_hv_topics_file Creating a New HDF5 File with a Contiguous Dataset +The steps below describe how to create a file (storm.h5), group (/Data), and a contiguous dataset +(/Data/Storm) using HDFView. A group is an HDF5 object that allows objects to be collected together. +A dataset is an array of data values. A contiguous dataset is one that is stored as a single block +in the HDF5 file. +<ul> +<li>Select the <em>File</em> pull-down menu at the top left, and then select <em>New -> HDF5</em>.</li> +<li>Specify a location and type in <em>storm.h5</em> for the name of your file, and click on the <em>Save</em> button. +You will see the <em>storm.h5</em> file in the TableView: +<table> +<tr> +<td> +\image html storm.png +</td> +</tr> +</table> +</li> +<li>Right click on <em>storm.h5</em>, and select <em>New -> Group</em>.</li> +<li>Enter <em>Data</em> for the name of the group and then click the <em>Ok</em> button. You will see the group <em>Data</em> in the TableView. +<table> +<tr> +<td> +\image html DataGroup.png +</td> +</tr> +</table> +</li> +<li>Right click on the group <em>Data</em> and select <em>New -> Dataset</em>.</li> +<li>A window pops up on the right. Fill in the information as follows, and then click <em>Ok</em> (leave the +Datatype information as is): +<table> +<tr> +<th>Dataset Name +</th> +<td><em>Storm</em> +</td> +</tr> +<tr> +<th>Under Dataspace, Current size +</th> +<td>57x57 +</td> +</tr> +<tr> +<th>Layout +</th> +<td><em>Contiguous</em> (default) +</td> +</tr> +</table> +</li> +<li>Click to expand the <em>Data</em> group in the tree view to see the <em>Storm</em> dataset: +<table> +<tr> +<td> +\image html StormDataset.png +</td> +</tr> +</table> +</li> +<li>Double left click on the <em>Storm</em> dataset in the tree view. A window with an empty spreadsheet pops open.</li> +<li>Copy the data from the <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a> file into the dataset. + +If you downloaded <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a>, +then click on the <em>Import/Export Data</em> menu and select <em>Import Data from -> Text File</em>. +Specify a location, select <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a> +and click on the <em>Open</em> button. Answer <em>Yes</em> in the dialog box that +pops up (which asks if you wish to paste the selected data). + +Alternately, you can copy/paste directly. Select and copy the data in a separate window. Position your +cursor at (0,0) in your table, and select <em>Paste</em> from the <em>Table</em> menu. + +The values will be entered into the spreadsheet. +<table> +<tr> +<td> +\image html datasetwdata.png +</td> +</tr> +</table> +</li> +<li><em>Table -> Close</em> the dataset, and save the data.</li> +</ul> + +\subsection subsec_learn_hv_topics_image Displaying a Dataset as an Image +Any dataset can be viewed as an image in HDFView. Below are the steps that demonstrate this. +<ul> +<li>Right click on <em>Storm</em> in the tree view, and select <em>Open As</em>.</li> +<li>Select the <em>Image</em> button under <em>Display As</em> (near the top) in the Dataset Selection window that pops +up. Then click <em>OK</em> at the bottom of the window to display the image. +<table> +<tr> +<td> +\image html showasimage.png +</td> +</tr> +</table> +</li> +<li>The rainbow icon brings you to the Image Palette window. Click on that to play with the palette +(GrayWave probably is the best choice). Close.</li> +</ul> + +\subsection subsec_learn_hv_topics_attr Creating Attributes +Additional information to describe an object can be stored in attributes. An attribute can be +added to a group or dataset with HDFView. + +The following illustrates how to add an attribute to the group <em>/Data</em>: +<ul> +<li>Click on the <em>/Data</em> folder in the tree view. You will see two tabs, <em>Object Attribute Info</em> and +<em>General Object Info</em>, in the pane on the right site of the HDFView window. +<table> +<tr> +<td> +\image html noattrs.png +</td> +</tr> +</table> +</li> +<li>With the left mouse button, select the <em>Add Attribute</em> button.</li> +<li>Select the <em>Add Attribute</em> button to add an attribute with these values:</li> +<table> +<tr> +<th>Name +</th> +<td><em>BatchID</em> +</td> +</tr> +<tr> +<th>Type +</th> +<td>INTEGER +</td> +</tr> +<tr> +<th>Size (bits) +</th> +<td>32 +</td> +</table> +<li>Select the <em>Ok</em> button. The attribute will show up under the <em>Object Attribute Info</em> tab.</li> +<li>Double-click the BatchID attribute line to open the data table for BatchID.</li> +<li>Click in the first cell and enter <em>3343</em> followed by the enter key.</li> +<li><em>Table -> Close</em>, answer <em>Yes</em> in the dialog box that +pops up (which asks if you wish to paste the selected data).</li> +</ul> +Adding an attribute to a dataset is very similar to adding an attribute to a group. For example, +the following adds an attribute to the <em>/Storm</em> dataset: +<ul> +<li>Left mouse click on the <em>/Storm</em> dataset in the tree view. You will see the <em>Object Attribute +Info</em> and <em>General Object Info</em> tabs on the right</li> +<li>In the <em>Object Attribute Info</em> pane select the <em>Add Attribute</em> button and enter an attribute with +these values. (Be sure to add a <em>String Length</em> or the string will be truncated to one character!):</li> +<table> +<tr> +<th>Name +</th> +<td><em>Units</em> +</td> +</tr> +<tr> +<th>Type +</th> +<td>STRING +</td> +</tr> +<tr> +<th>String Length +</th> +<td>3 +</td> +</table> +<li>Select the <em>Ok</em> button. The attribute will show up under the <em>Object Attribute Info</em> tab.</li> +<li>Double-click the Units attribute line to open the data table for Units.</li> +<li>Click in the first cell and enter <em>m/s</em> followed by the enter key.</li> +<li><em>Table -> Close</em>, answer <em>Yes</em> in the dialog box that +pops up (which asks if you wish to paste the selected data). +<table> +<tr> +<td> +\image html scarletletter.png +</td> +</tr> +</table> +</li> +</ul> + +\subsection subsec_learn_hv_topics_compress Creating a Compressed and Chunked Dataset +A chunked and compressed dataset can be created using HDFView. A compressed dataset is a dataset +whose size has been compressed to take up less space. In order to compress an HDF5 dataset, the +dataset must be stored with a chunked dataset layout (as multiple <em>chunks</em> that are stored separately +in the file). + +Please note that the chunk sizes used in this topic are for demonstration purposes only. For +information on chunking and specifying an appropriate chunk size, see the +<a href="https://confluence.hdfgroup.org/display/HDF5/Chunking+in+HDF5">Chunking in HDF5</a> documentation. + +Also see the HDF5 Tutorial topic on \ref secLBComDsetCreate. +<ul> +<li>Right click on storm.h5. Select <em>New -> Group</em>.</li> +<li>Enter <em>Image</em> for the name of the group, and click the <em>OK</em> button to create the group. +<table> +<tr> +<td> +\image html newgroupimage.png +</td> +</tr> +</table> +</li> +<li>Right click on the <em>Image</em> group, and select <em>New -> Dataset</em>.</li> +<li>Enter the following information for the dataset. Leave the <em>Datatype</em> as is (INTEGER): +<table> +<tr> +<th>Dataset name +</th> +<td><em>Another Storm</em> +</td> +</tr> +<tr> +<th>Under Dataspace, Current size +</th> +<td>57x57 +</td> +</tr> +<tr> +<th>Storage Layout +</th> +<td>Chunked +</td> +</tr> +<tr> +<th>Chunk Size +</th> +<td>20x20 +</td> +</tr> +<tr> +<th>Compression +</th> +<td>gzip +</td> +</tr> +<tr> +<th>Compression Level +</th> +<td>9 +</td> +</table> +You will see the <em>Another Storm</em> dataset in the <em>Image</em> group: +<table> +<tr> +<td> +\image html hdfview-anthrstrm.png +</td> +</tr> +</table> +</li> +<li>Double left-mouse click on the <em>Another Storm</em> dataset to display the spreadsheet: +<table> +<tr> +<td> +\image html hdfview-anthrstrm-sprdsht.png +</td> +</tr> +</table> +</li> +<li>Copy the data from the <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a> file into the dataset. (See the previous topic for copying +<a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a> into a dataset.)</li> +<li><em>Table -> Close</em>, and save the data.</li> +<li>Right click on <em>Another Storm</em>, and select <em>Open As</em>.</li> +<li>Select the <em>Image</em> button in the Dataset Selection window that pops up. Click the <em>Ok</em> button at the +bottom of the window to view the dataset as an image. +<table> +<tr> +<td> +\image html hdfview-anthrstrm-img.png +</td> +</tr> +</table> +</li> +</ul> + +\subsection subsec_learn_hv_topics_subset Creating an Image and a Subset +A previous topic demonstrated how to view any dataset as an image in HDFView. With HDFView you can also +create an image to begin with, as is shown below. +<ul> +<li>Right click on the <em>Data</em> group and select <em>New -> Image</em>.</li> +<li>A window pops up on the right. Enter the following and then click <em>Ok</em>:</li> +<table> +<tr> +<th>Image name +</th> +<td><em>Storm Image</em> +</td> +</tr> +<tr> +<th>Height +</th> +<td>57 +</td> +</tr> +<tr> +<th>Width +</th> +<td>57 +</td> +</table> + +<li>Close the dataset.</li> +<li>Expand the <em>Data</em> group to see its contents. You will see the <em>Storm Image</em> dataset. +<table> +<tr> +<td> +\image html hdfview-imgicon.png +</td> +</tr> +</table> +</li> +<li> +Add data to the <em>Storm Image</em> dataset as was shown previously: +<ul> +<li>Right click on <em>Storm Image</em>, and select <em>Open As</em> to open the Dataset Selection window.</li> +<li>Click on the <em>Spreadsheet</em> button at the top left of the Dataset Selection window to view the image +as a spreadsheet.</li> +<li>Copy the data from the <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/storm1.txt">storm1.txt</a> file into the dataset.</li> +<li>Close the dataset and save the data.</li> +</ul> +</li> +<li>Left double click on <em>Storm Image</em> to see the image. Close the dataset.</li> +<li>Right click on <em>Storm Image</em> and select <em>Open As</em> to bring up the Data Selection window.</li> +<li>Select a subset by clicking the left mouse on the image in the window and dragging the mouse. +Notice that the Height and Width values change. Select to display it as an image. Click <em>Ok</em>. +<table> +<tr> +<td> +\image html hdfview-imgsubset.png +</td> +</tr> +</table> +</li> +<li>Position the cursor in the middle of the image. Press Shift+Left Mouse button and hold, and then +drag the mouse to select another subset.</li> +<li>Select <em>Image->Write Selection to Image</em>. Enter <em>Subset</em> for the new image name. Click <em>Ok</em>. The <em>Subset</em> +image will appear in the tree view on the left.</li> +<li>Left double click on the image <em>Subset</em> to bring it up on the right. +<table> +<tr> +<td> +\image html hdfview-newimgsubset.png +</td> +</tr> +</table> +</li> +<li>Close the <em>Subset</em> image.</li> +</ul> + +\subsection subsec_learn_hv_topics_table Creating a Table (Compound Dataset) +A dataset with a compound datatype contains data elements that consist of multiple fields. If the +dataspace for the compound dataset is one-dimensional, then the dataset can be viewed as a table in +HDFView, as is shown below. +<ul> +<li>Right button click on the group <em>Data</em>. Select <em>New -> Compound DS</em>.</li> +<li>A window pops up. Only fill in the following fields: +<table> +<tr> +<th>Dataset name +</th> +<td>Table +</td> +</tr> +<tr> +<th>Dataspace (Current size only) +</th> +<td>4 +</td> +</tr> +<tr> +<th>Compound Datatype Properties: +<br />Number of Members +</th> +<td>3 +</td> +</tr> +<tr> +<th>Compound Datatype Properties: +<br /><em>Name</em> / Datatype / Size +</th> +<td><em>Description</em> / string / 4 +<br /><em>Temperature</em> / float / 1 +<br /><em>Pressure</em> / double / 1 +</td> +</tr> +</table> + +<table> +<tr> +<td> +\image html hdfview-newcmpd.png +</td> +</tr> +</table> +</li> +<li>Click Ok at the bottom.</li> +<li>Open the Data group (if it is not open) and double left click on the Table object. +<table> +<tr> +<td> +\image html hdfview-table.png +</td> +</tr> +</table> +</li> +<li>Close the dataset.</li> +</ul> + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted + +*/ diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox index df0c747..7900925 100644 --- a/doxygen/dox/ReferenceManual.dox +++ b/doxygen/dox/ReferenceManual.dox @@ -1,53 +1,32 @@ /** \page RM HDF5 Reference Manual -The functions provided by the HDF5 C-API are grouped into the following +The functions provided by the HDF5 API are grouped into the following \Emph{modules}: <table> <tr><th>Modules</th></tr> <tr valign="top"> <td> - <table> <tr valign="top"><td style="border: none;"> -\li \ref H5A "Attributes (H5A)" -\li \ref H5D "Datasets (H5D)" -\li \ref H5S "Dataspaces (H5S)" -\li \ref H5T "Datatypes (H5T)" -\li \ref H5E "Error Handling (H5E)" -\li \ref H5ES "Event Sets (H5ES)" -\li \ref H5F "Files (H5F)" -\li \ref H5Z "Filters (H5Z)" -\li \ref H5G "Groups (H5G)" -</td><td style="border: none;"> -\li \ref H5I "Identifiers (H5I)" -\li \ref H5 "Library General (H5)" -\li \ref H5L "Links (H5L)" -\li \ref H5M "Maps (H5M)" -\li \ref H5O "Objects (H5O)" -\li \ref H5P "Property Lists (H5P)" -\li \ref H5PL "Dynamically-loaded Plugins (H5PL)" -\li \ref H5R "References (H5R)" -\li \ref H5VL "Virtual Object Layer (H5VL)" -</td><td style="border: none;"> -\li \ref high_level - <ul> - <li>\ref H5LT "Lite (H5LT, H5LD)" - <li>\ref H5IM "Images (H5IM)" - <li>\ref H5TB "Table (H5TB)" - <li>\ref H5PT "Packet Table (H5PT)" - <li>\ref H5DS "Dimension Scale (H5DS)" - <li>\ref H5DO "Optimizations (H5DO)" - <li>\ref H5LR "Extensions (H5LR, H5LT)" - </ul> -</td></tr> -<tr><td colspan="3" style="border: none;"> -\a Core \a library: \ref H5 \ref H5A \ref H5D \ref H5E \ref H5ES \ref H5F \ref H5G \ref H5I \ref H5L -\ref H5M \ref H5O \ref H5P \ref H5PL \ref H5R \ref H5S \ref H5T \ref H5VL \ref H5Z -</td></tr> -<tr><td colspan="3" style="border: none;"> -\a High-level \a library: \ref H5LT \ref H5IM \ref H5TB \ref H5PT \ref H5DS \ref H5DO \ref H5LR -</td></tr> +\include{doc} core_menu.md +</td> +</tr> +<tr valign="top"><td style="border: none;"> +<!-- High-level library --> +\include{doc} high_level_menu.md +</td> +</tr> +<tr valign="top"><td style="border: none;"> +<!-- Fortran library --> +\include{doc} fortran_menu.md +</td> +</tr> +<tr valign="top"><td style="border: none;"> +<!-- Java library --> +\include{doc} java_menu.md +</td> +</tr> <tr> <td><a href="./deprecated.html">Deprecated functions</a></td> <td>Functions with \ref ASYNC</td> diff --git a/doxygen/dox/Specifications.dox b/doxygen/dox/Specifications.dox index 5a36d61..e352f40 100644 --- a/doxygen/dox/Specifications.dox +++ b/doxygen/dox/Specifications.dox @@ -2,20 +2,20 @@ \section DDL -\li \ref DDLBNF110 "DDL in BNF through HDF5 1.10" -\li \ref DDLBNF112 "DDL in BNF for HDF5 1.12 and above" +\li \ref DDLBNF110 +\li \ref DDLBNF112 \section File Format -\li \ref FMT1 "HDF5 File Format Specification Version 1.0" -\li \ref FMT11 "HDF5 File Format Specification Version 1.1" -\li \ref FMT2 "HDF5 File Format Specification Version 2.0" -\li \ref FMT3 "HDF5 File Format Specification Version 3.0" +\li \ref FMT1 +\li \ref FMT11 +\li \ref FMT2 +\li \ref FMT3 \section Other -\li \ref IMG "HDF5 Image and Palette Specification Version 1.2" -\li \ref TBL "HDF5 Table Specification Version 1.0" +\li \ref IMG +\li \ref TBL \li <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf"> HDF5 Dimension Scale Specification</a> diff --git a/doxygen/dox/TechnicalNotes.dox b/doxygen/dox/TechnicalNotes.dox index 9bd2802..bca81e4 100644 --- a/doxygen/dox/TechnicalNotes.dox +++ b/doxygen/dox/TechnicalNotes.dox @@ -1,13 +1,13 @@ /** \page TN Technical Notes -\li \link api-compat-macros API Compatibility Macros \endlink -\li \ref APPDBG "Debugging HDF5 Applications" -\li \ref FMTDISC "File Format Walkthrough" -\li \ref FILTER "Filters" -\li \ref IOFLOW "HDF5 Raw I/O Flow Notes" -\li \ref TNMDC "Metadata Caching in HDF5" -\li \ref MT "Thread Safe library" -\li \ref VFL "Virtual File Layer" +\li \ref api-compat-macros +\li \ref APPDBG +\li \ref FMTDISC +\li \ref FILTER +\li \ref IOFLOW +\li \ref TNMDC +\li \ref MT +\li \ref VFL */ diff --git a/doxygen/dox/UsersGuide.dox b/doxygen/dox/UsersGuide.dox new file mode 100644 index 0000000..dbb6053 --- /dev/null +++ b/doxygen/dox/UsersGuide.dox @@ -0,0 +1,403 @@ +/** \page UG HDF5 User Guide + +<center> +HDF5 Release 1.14 + +\image html HDFG-logo.png "The HDF Group" + +</center> + +\ref sec_data_model +\li \ref subsec_data_model_intro +\li \ref subsec_data_model_abstract + <ul> + <li> \ref subsubsec_data_model_abstract_file + <li> \ref subsubsec_data_model_abstract_group + <li> \ref subsubsec_data_model_abstract_dataset + <li> \ref subsubsec_data_model_abstract_space + <li> \ref subsubsec_data_model_abstract_type + <li> \ref subsubsec_data_model_abstract_attr + <li> \ref subsubsec_data_model_abstract_plist + <li> \ref subsubsec_data_model_abstract_link + </ul> +\li \ref subsec_data_model_storage + <ul> + <li> \ref subsubsec_data_model_storage_spec + <li> \ref subsubsec_data_model_storage_imple + </ul> +\li \ref subsec_data_model_structure + <ul> + <li> \ref subsubsec_data_model_structure_file + <li> \ref subsubsec_data_model_structure_path + <li> \ref subsubsec_data_model_structure_example + </ul> + +\ref sec_program +\li \ref subsec_program_intro +\li \ref subsec_program_model + <ul> + <li> \ref subsubsec_program_model_create + <li> \ref subsubsec_program_model_dset + <li> \ref subsubsec_program_model_close + <li> \ref subsubsec_program_model_data + <li> \ref subsubsec_program_model_partial + <li> \ref subsubsec_program_model_info + <li> \ref subsubsec_program_model_compound + <li> \ref subsubsec_program_model_extend + <li> \ref subsubsec_program_model_group + <li> \ref subsubsec_program_model_attr + </ul> +\li \ref subsec_program_transfer_pipeline + +\ref sec_file +\li \ref subsec_file_intro +\li \ref subsec_file_access_modes +\li \ref subsec_file_creation_access +\li \ref subsec_file_drivers +\li \ref subsec_file_program_model + <ul> + <li> \ref subsubsec_file_program_model_create + <li> \ref subsubsec_file_program_model_open + <li> \ref subsubsec_file_program_model_close + </ul> +\li \ref subsec_file_h5dump +\li \ref subsec_file_summary +\li \ref subsec_file_create +\li \ref subsec_file_closes +\li \ref subsec_file_property_lists + <ul> + <li> \ref subsubsec_file_property_lists_create + <li> \ref subsubsec_file_property_lists_props + <li> \ref subsubsec_file_property_lists_access + </ul> +\li \ref subsec_file_alternate_drivers + <ul> + <li> \ref subsubsec_file_alternate_drivers_id + <li> \ref subsubsec_file_alternate_drivers_sec2 + <li> \ref subsubsec_file_alternate_drivers_direct + <li> \ref subsubsec_file_alternate_drivers_log + <li> \ref subsubsec_file_alternate_drivers_win + <li> \ref subsubsec_file_alternate_drivers_stdio + <li> \ref subsubsec_file_alternate_drivers_mem + <li> \ref subsubsec_file_alternate_drivers_family + <li> \ref subsubsec_file_alternate_drivers_multi + <li> \ref subsubsec_file_alternate_drivers_split + <li> \ref subsubsec_file_alternate_drivers_par + </ul> +\li \ref subsec_file_examples + <ul> + <li> \ref subsubsec_file_examples_trunc + <li> \ref subsubsec_file_examples_props + <li> \ref subsubsec_file_examples_access + </ul> +\li \ref subsec_file_multiple + +\ref sec_group +\li \ref subsec_group_intro +\li \ref subsec_group_descr + <ul> + <li> \ref subsubsec_group_descr_object + <li> \ref subsubsec_group_descr_model + <li> \ref subsubsec_group_descr_path + <li> \ref subsubsec_group_descr_impl + </ul> +\li \ref subsec_group_h5dump +\li \ref subsec_group_function +\li \ref subsec_group_program + <ul> + <li> \ref subsubsec_group_program_create + <li> \ref subsubsec_group_program_open + <li> \ref subsubsec_group_program_dataset + <li> \ref subsubsec_group_program_close + <li> \ref subsubsec_group_program_links + <li> \ref subsubsec_group_program_info + <li> \ref subsubsec_group_program_objs + <li> \ref subsubsec_group_program_all + </ul> +\li \ref subsec_group_examples + +\ref sec_dataset +\li \ref subsec_dataset_intro +\li \ref subsec_dataset_function +\li \ref subsec_dataset_program + <ul> + <li> \ref subsubsec_dataset_program_general + <li> \ref subsubsec_dataset_program_create + <li> \ref subsubsec_dataset_program_transfer + <li> \ref subsubsec_dataset_program_read + </ul> +\li \ref subsec_dataset_transfer Data Transfer + <ul> + <li> \ref subsubsec_dataset_transfer_pipe + <li> \ref subsubsec_dataset_transfer_filter + <li> \ref subsubsec_dataset_transfer_drive + <li> \ref subsubsec_dataset_transfer_props + <li> \ref subsubsec_dataset_transfer_store + <li> \ref subsubsec_dataset_transfer_partial + </ul> +\li \ref subsec_dataset_allocation + <ul> + <li> \ref subsubsec_dataset_allocation_store + <li> \ref subsubsec_dataset_allocation_delete + <li> \ref subsubsec_dataset_allocation_release + <li> \ref subsubsec_dataset_allocation_ext + </ul> +\li \ref subsec_dataset_filters + <ul> + <li> \ref subsubsec_dataset_filters_nbit + <li> \ref subsubsec_dataset_filters_scale + <li> \ref subsubsec_dataset_filters_szip + </ul> + +\ref sec_datatype +\li \ref subsec_datatype_intro +\li \ref subsec_datatype_model + <ul> + <li> \ref subsubsec_datatype_model_class + <li> \ref subsubsec_datatype_model_predefine + </ul> +\li \ref subsec_datatype_usage + <ul> + <li> \ref subsubsec_datatype_usage_object + <li> \ref subsubsec_datatype_usage_create + <li> \ref subsubsec_datatype_usage_transfer + <li> \ref subsubsec_datatype_usage_discover + <li> \ref subsubsec_datatype_usage_user + </ul> +\li \ref subsec_datatype_function +\li \ref subsec_datatype_program + <ul> + <li> \ref subsubsec_datatype_program_discover + <li> \ref subsubsec_datatype_program_define + </ul> +\li \ref subsec_datatype_other + <ul> + <li> \ref subsubsec_datatype_other_strings + <li> \ref subsubsec_datatype_other_refs + <li> \ref subsubsec_datatype_other_enum + <li> \ref subsubsec_datatype_other_opaque + <li> \ref subsubsec_datatype_other_bitfield + </ul> +\li \ref subsec_datatype_fill +\li \ref subsec_datatype_complex + <ul> + <li> \ref subsubsec_datatype_complex_create + <li> \ref subsubsec_datatype_complex_analyze + </ul> +\li \ref subsec_datatype_life +\li \ref subsec_datatype_transfer +\li \ref subsec_datatype_text + +\ref sec_dataspace +\li \ref subsec_dataspace_intro +\li \ref subsec_dataspace_function +\li \ref subsec_dataspace_program + <ul> + <li> \ref subsubsec_dataspace_program_object + <li> \ref subsubsec_dataspace_program_model + </ul> +\li \ref subsec_dataspace_transfer + <ul> + <li> \ref subsubsec_dataspace_transfer_select + <li> \ref subsubsec_dataspace_transfer_model + </ul> +\li \ref subsec_dataspace_select +\li \ref subsec_dataspace_refer + <ul> + <li> \ref subsubsec_dataspace_refer_use + <li> \ref subsubsec_dataspace_refer_create + <li> \ref subsubsec_dataspace_refer_read + </ul> +\li \ref subsec_dataspace_sample + +\ref sec_attribute +\li \ref subsec_attribute_intro +\li \ref subsec_attribute_program + <ul> + <li> <!-- \subsubsection subsubsec_attribute_program_exist --> To Open and Read or Write an Existing Attribute </li> + </ul> +\li \ref subsec_error_H5A +\li \ref subsec_attribute_work + <ul> + <li> \ref subsubsec_attribute_work_struct + <li> \ref subsubsec_attribute_work_create + <li> \ref subsubsec_attribute_work_access + <li> \ref subsubsec_attribute_work_info + <li> \ref subsubsec_attribute_work_iterate + <li> \ref subsubsec_attribute_work_delete + <li> \ref subsubsec_attribute_work_close + </ul> +\li \ref subsec_attribute_special + +\ref sec_error +\li \ref subsec_error_intro +\li \ref subsec_error_program +\li \ref subsec_error_H5E +\li \ref subsec_error_ops + <ul> + <li> \ref subsubsec_error_ops_stack + <li> \ref subsubsec_error_ops_print + <li> \ref subsubsec_error_ops_mute + <li> \ref subsubsec_error_ops_custom_print + <li> \ref subsubsec_error_ops_walk + <li> \ref subsubsec_error_ops_travers + </ul> +\li \ref subsec_error_adv + <ul> + <li> \ref subsubsec_error_adv_more + <li> \ref subsubsec_error_adv_app + </ul> + +\ref sec_plist +\li \ref subsec_plist_intro +\li \ref subsec_plist_class + <ul> + <li> \ref subsubsec_plist_class + <li> \ref subsubsec_plist_lists + <li> \ref subsubsec_plist_props + </ul> +\li \ref subsec_plist_program + <ul> + <li> \ref subsubsec_plist_default + <li> \ref subsubsec_plist_basic + <li> \ref subsubsec_plist_additional + </ul> +\li \ref subsec_plist_generic +\li \ref subsec_plist_H5P +\li \ref subsec_plist_resources +\li \ref subsec_plist_notes + +\ref sec_vol +\li \ref subsec_vol_intro +\li \ref subsec_vol_abstract_layer +\li \ref subsec_vol_connect +\li \ref subsec_vol_use + +\ref sec_async +\li \ref subsec_async_intro + +\ref sec_map + +\ref sec_addition + +\page AR_UG Additional Resources + +\section sec_addition Additional Resources +These documents provide additional information for the use and tuning of specific HDF5 features. + <table style=" border-spacing:0; padding-left:6.00pt; padding-top:6.00pt; padding-right:6.00pt; padding-bottom:6.00pt; float:aligncenter; width:100%; max-width:432.00pt;" cellspacing="0"> + <caption x-list-start="1" style="font-size: 12.0pt;">Table of Additional resources</caption> + <tr style="height: 23.00pt;"> + <th style="width: 234.000pt; border-top-style: solid; border-top-width: 1px; border-top-color: #228a22; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align : top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Document</p> +</th> + <th style="width: 198.000pt; border-top-style: solid; border-top-width: 1px; border-top-color: #228a22; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align : top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Comments</p> +</th> +</tr> + <tr style="height: 23.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span>@ref HDF5Examples</span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Code examples by API. </p> +</td> +</tr> + <tr style="height: 36.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/Chunking/index.html">Chunking in HDF5</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Structuring the use of chunking and tuning it for performance.</p> +</td> +</tr> + <tr style="height: 36.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span class="FM_LT_LinkText"><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/DirectChunkWrite/UsingDirectChunkWrite.pdf">Using the Direct Chunk Write Function</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes another way that chunks can be written to datasets.</p> +</td> +</tr> + <tr style="height: 88.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/CommittedDatatypeCopying/CopyingCommittedDatatypesWithH5Ocopy.pdf">Copying Committed Datatypes with H5Ocopy</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how to copy to another file a dataset that uses a committed datatype or an object with an attribute that uses a committed datatype so that the committed datatype in the destination file can be used by multiple objects.</p> +</td> +</tr> + <tr style="height: 36.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/MetadataCache/index.html">Metadata Caching in HDF5</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Managing the HDF5 metadata cache and tuning it for performance.</p> +</td> +</tr> + <tr style="height: 49.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/DynamicallyLoadedFilters/HDF5DynamicallyLoadedFilters.pdf">HDF5 Dynamically Loaded Filters</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how an HDF5 application can apply a filter that is not registered with the HDF5 Library.</p> +</td> +</tr> + <tr style="height: 62.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/FileImageOperations/HDF5FileImageOperations.pdf">HDF5 File Image Operations</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how to work with HDF5 files in memory. Disk I/O is not required when file images are opened, created, read from, or written to.</p> +</td> +</tr> + <tr style="height: 62.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/ModifiedRegionWrites/ModifiedRegionWrites.pdf">Modified Region Writes</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how to set write operations for in-memory files so that only modified regions are written to storage. Available when the Core (Memory) VFD is used.</p> +</td> +</tr> + <tr style="height: 36.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/UsingIdentifiers/index.html">Using Identifiers</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how identifiers behave and how they should be treated.</p> +</td> +</tr> + <tr style="height: 36.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/UsingUnicode/index.html">Using UTF-8 Encoding in HDF5 Applications</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes the use of UTF-8 Unicode character encodings in HDF5 applications.</p> +</td> +</tr> + <tr style="height: 49.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Advanced/FreeingMemory/FreeingMemoryAllocatedByTheHdf5Library.pdf">Freeing Memory Allocated by the HDF5 Library</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>Describes how inconsistent memory management can cause heap corruption or resource leaks and possible solutions.</p> +</td> +</tr> + <tr style="height: 23.00pt;"> + <td style="width: 234.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p style="font-style: italic; color: #0000ff;"><span><a href="http://www.hdfgroup.org/HDF5/doc/Glossary.html">HDF5 Glossary</a></span></p> +</td> + <td style="width: 198.000pt; border-bottom-style: solid; border-bottom-width: 1px; border-bottom-color: #228a22; vertical-align: top;padding-left: 6.00pt; padding-top: 3.00pt; padding-right: 6.00pt; padding-bottom: 3.00pt;"> + <p>A glossary of terms.</p> +</td> +</tr> + </table> + +Previous Chapter \ref sec_plist + +\par Don't like what you see? - You can help to improve this User Guide + Complete the survey linked near the top of this page!\n + We treat documentation like code: Fork the + <a href="https://github.com/HDFGroup/hdf5">HDF5 repo</a>, make changes, and create a + <a href="https://github.com/HDFGroup/hdf5/pulls">pull request</a> !\n + +*/
\ No newline at end of file diff --git a/doxygen/dox/ViewTools.dox b/doxygen/dox/ViewTools.dox new file mode 100644 index 0000000..0b685a0 --- /dev/null +++ b/doxygen/dox/ViewTools.dox @@ -0,0 +1,1198 @@ +/** @page ViewTools Tools for Viewing and Editing HDF5 Files + +Navigate back: \ref index "Main" / \ref GettingStarted +<hr> + +\section secToolsBasic Basic Facts about HDF5 +The following are basic facts about HDF5 files to keep in mind while completing these tutorial topics: +\li All HDF5 files contain a root group "/". +\li There are two primary objects in HDF5, a group and a dataset:<br /> + Groups allow objects to be organized into a group structure, such as a tree.<br /> + Datasets contain raw data values. +\li Additional information about an HDF5 object may optionally be stored in attributes attached to the object. + +\section secToolsTopics Tutorial Topics +<table> +<tr> +<th>Tutorial Topic</th> +<th>Description</th> +</tr> +<tr> +<td> +@ref LearnHDFView +</td> +<td>Use HDFView to create, edit and view files. +</td> +</tr> +<tr> +<td> +@ref ViewToolsCommand +</td> +<td>Use the HDF5 command-line tools for viewing, editing, and comparing HDF5 files. +</td> +</tr> +<tr> +<td>@ref ViewToolsJPSS +</td> +<td>Use HDF5 tools to examine and work with JPSS NPP files. +</td> +</tr> +</table> + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted + +@page ViewToolsCommand Command-line Tools +Navigate back: \ref index "Main" / \ref GettingStarted +<hr> + +\section secViewToolsCommandObtain Obtain Tools and Files (Optional) +Pre-built binaries for Linux and Windows are distributed within the respective HDF5 binary release +packages, which can be obtained from the <a href="https://portal.hdfgroup.org/display/support/Download+HDF5">Download HDF5</a> page. + +HDF5 files can be obtained from various places such as \ref HDF5Examples and <a href="http://www.hdfeos.org/">HDF-EOS and Tools and +Information Center</a>. Specifically, the following examples are used in this tutorial topic: +\li HDF5 Files created from compiling the \ref LBExamples +\li HDF5 Files on the <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page +\li NPP JPSS files, <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5.gz">SVM01_npp.. (gzipped)</a> +and <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5.gz">SVM09_npp.. (gzipped)</a> +\li HDF-EOS <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/OMI-Aura.he5">OMI-Aura file</a> + +\section secViewToolsCommandTutor Tutorial Topics +A variety of command-line tools are included in the HDF5 binary distribution. There are tools to view, +edit, convert and compare HDF5 files. This tutorial discusses the tools by their functionality. It +does not cover all of the HDF5 tools. + +<table> +<tr> +<th>Tool Category</th> +<th>Topic</th> +<th>Tools Used</th> +</tr> +<tr> +<td><strong>@ref ViewToolsView</strong></td> +<td>@ref secViewToolsViewContent</td> +<td>h5dump and h5ls +</td> +</tr> +<tr> +<td></td> +<td>@ref secViewToolsViewDset</td> +<td>h5dump and h5ls +</td> +</tr> +<tr> +<td></td> +<td>@ref secViewToolsViewGrps</td> +<td>h5dump and h5ls +</td> +</tr> +<tr> +<td></td> +<td>@ref secViewToolsViewAttr</td> +<td>h5dump +</td> +</tr> +<tr> +<td></td> +<td>@ref secViewToolsViewSub</td> +<td>h5dump +</td> +</tr> +<tr> +<td></td> +<td>@ref secViewToolsViewDtypes</td> +<td>h5dump +</td> +</tr> +<tr> +<td>@ref ViewToolsEdit</td> +<td>@ref secViewToolsEditRemove</td> +<td>h5repack +</td> +</tr> +<tr> +<td></td> +<td>@ref secViewToolsEditChange</td> +<td>h5repack +</td> +</tr> +<tr> +<td></td> +<td>@ref secViewToolsEditApply</td> +<td>h5repack +</td> +</tr> +<tr> +<td></td> +<td>@ref secViewToolsEditCopy</td> +<td>h5copy +</td> +</tr> +<tr> +<td></td> +<td>@ref secViewToolsEditAdd</td> +<td>h5jam and h5unjam +</td> +</tr> +<tr> +<td>@ref ViewToolsConvert</td> +<td>@ref secViewToolsConvertASCII</td> +<td>h5dump +</td> +</tr> +<tr> +<td></td> +<td>@ref secViewToolsConvertBinary</a></td> +<td>h5dump +</td> +</tr> +<tr> +<td></td> +<td>@ref secViewToolsConvertExport</td> +<td>h5dump and h5import +</td> +</tr> +</table> + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted + +@page ViewToolsView Command-line Tools For Viewing HDF5 Files +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand +<hr> + +\section secViewToolsViewTOC Contents +<ul> +<li>\ref secViewToolsViewContent</li> +<li>\ref secViewToolsViewDset</li> +<li>\ref secViewToolsViewGrps</li> +<li>\ref secViewToolsViewAttr</li> +<li>\ref secViewToolsViewSub</li> +<li>\ref secViewToolsViewDtypes</li> +</ul> + +\section secViewToolsViewContent File Content and Structure +The h5dump and h5ls tools can both be used to view the contents of an HDF5 file. The tools are discussed below: +<ul> +<li>\ref subsecViewToolsViewContent_h5dump</li> +<li>\ref subsecViewToolsViewContent_h5ls</li> +</ul> + +\subsection subsecViewToolsViewContent_h5dump h5dump +The h5dump tool dumps or displays the contents of an HDF5 file (textually). By default if you specify no options, +h5dump will display the entire contents of a file. There are many h5dump options for examining specific details +of a file. To see all of the available h5dump options, specify the <code style="background-color:whitesmoke;">-h</code> +or <code style="background-color:whitesmoke;">--help</code> option: +\code +h5dump -h +\endcode + +The following h5dump options can be helpful in viewing the content and structure of a file: +<table> +<tr> +<th>Option</th> +<th>Description</th> +<th>Comment</th> +</tr> +<tr> +<td>-n, --contents +</td> +<td>Displays a list of the objects in a file +</td> +<td>See @ref subsubsecViewToolsViewContent_h5dumpEx1 +</td> +</tr> +<tr> +<td>-n 1, --contents=1 +</td> +<td>Displays a list of the objects and attributes in a file +</td> +<td>See @ref subsubsecViewToolsViewAttr_h5dumpEx6 +</td> +</tr> +<tr> +<td>-H, --header +</td> +<td>Displays header information only (no data) +</td> +<td>See @ref subsubsecViewToolsViewContent_h5dumpEx2 +</td> +</tr> +<tr> +<td>-A 0, --onlyattr=0 +</td> +<td>Suppresses the display of attributes +</td> +<td>See @ref subsubsecViewToolsViewContent_h5dumpEx2 +</td> +</tr> +<tr> +<td>-N P, --any_path=P +</td> +<td>Displays any object or attribute that matches path P +</td> +<td>See @ref subsubsecViewToolsViewAttr_h5dumpEx6 +</td> +</tr> +</table> + +\subsubsection subsubsecViewToolsViewContent_h5dumpEx1 Example 1 +The following command displays a list of the objects in the file OMI-Aura.he5 (an HDF-EOS5 file): +\code +h5dump -n OMI-Aura.he5 +\endcode + +As shown in the output below, the objects (groups, datasets) are listed to the left, followed by their +names. You can see that this file contains two root groups, HDFEOS and HDFEOS INFORMATION: +\code +HDF5 "OMI-Aura.he5" { +FILE_CONTENTS { + group / + group /HDFEOS + group /HDFEOS/ADDITIONAL + group /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES + group /HDFEOS/GRIDS + group /HDFEOS/GRIDS/OMI Column Amount O3 + group /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields + dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/ColumnAmountO3 + dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/RadiativeCloudFraction + dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle + dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/ViewingZenithAngle + group /HDFEOS INFORMATION + dataset /HDFEOS INFORMATION/StructMetadata.0 + } +} +\endcode + +\subsubsection subsubsecViewToolsViewContent_h5dumpEx2 Example 2 +The file structure of the OMI-Aura.he5 file can be seen with the following command. The -A 0 option suppresses the display of attributes: +\code +h5dump -H -A 0 OMI-Aura.he5 +\endcode + +Output of this command is shown below: +\code +HDF5 "OMI-Aura.he5" { +GROUP "/" { + GROUP "HDFEOS" { + GROUP "ADDITIONAL" { + GROUP "FILE_ATTRIBUTES" { + } + } + GROUP "GRIDS" { + GROUP "OMI Column Amount O3" { + GROUP "Data Fields" { + DATASET "ColumnAmountO3" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "RadiativeCloudFraction" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "SolarZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "ViewingZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + } + } + } + } + GROUP "HDFEOS INFORMATION" { + DATASET "StructMetadata.0" { + DATATYPE H5T_STRING { + STRSIZE 32000; + STRPAD H5T_STR_NULLTERM; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SCALAR + } + } +} +} +\endcode + +\subsection subsecViewToolsViewContent_h5ls h5ls +The h5ls tool by default just displays the objects in the root group. It will not display +items in groups beneath the root group unless specified. Useful h5ls options for viewing +file content and structure are: +<table> +<tr> +<th>Option</th> +<th>Description</th> +<th>Comment</th> +</tr> +<tr> +<td>-r +</td> +<td>Lists all groups and objects recursively +</td> +<td>See @ref subsubsecViewToolsViewContent_h5lsEx3 +</td> +</tr> +<tr> +<td>-v +</td> +<td>Generates verbose output (lists dataset properties, attributes +and attribute values, but no dataset values) +</td> +<td> +</td> +</tr> +</table> + +\subsubsection subsubsecViewToolsViewContent_h5lsEx3 Example 3 +The following command shows the contents of the HDF-EOS5 file OMI-Aura.he5. The output is similar to h5dump, except that h5ls also shows dataspace information for each dataset: +\code +h5ls -r OMI-Aura.he5 +\endcode + +The output is shown below: +\code +/ Group +/HDFEOS Group +/HDFEOS/ADDITIONAL Group +/HDFEOS/ADDITIONAL/FILE_ATTRIBUTES Group +/HDFEOS/GRIDS Group +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3 Group +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields Group +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ColumnAmountO3 Dataset {720, 1440} +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/RadiativeCloudFraction Dataset {720, 1440} +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/SolarZenithAngle Dataset {720, 1440} +/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ViewingZenithAngle Dataset {720, 1440} +/HDFEOS\ INFORMATION Group +/HDFEOS\ INFORMATION/StructMetadata.0 Dataset {SCALAR} +\endcode + +\section secViewToolsViewDset Datasets and Dataset Properties +Both h5dump and h5ls can be used to view specific datasets. +<ul> +<li>\ref subsecViewToolsViewDset_h5dump</li> +<li>\ref subsecViewToolsViewDset_h5ls</li> +</ul> + +\subsection subsecViewToolsViewDset_h5dump h5dump +Useful h5dump options for examining specific datasets include: +<table> +<tr> +<th>Option</th> +<th>Description</th> +<th>Comment</th> +</tr> +<tr> +<td>-d D, --dataset=D +</td> +<td>Displays dataset D +</td> +<td>See @ref subsubsecViewToolsViewDset_h5dumpEx4 +</td> +</tr> +<tr> +<td> -H, --header +</td> +<td>Displays header information only +</td> +<td>See @ref subsubsecViewToolsViewDset_h5dumpEx4 +</td> +</tr> +<tr> +<td>-p, --properties +</td> +<td>Displays dataset filters, storage layout, and fill value properties +</td> +<td>See @ref subsubsecViewToolsViewDset_h5dumpEx5 +</td> +</tr> +<tr> +<td>-A 0, --onlyattr=0 +</td> +<td>Suppresses the display of attributes +</td> +<td>See @ref subsubsecViewToolsViewContent_h5dumpEx2 +</td> +</tr> +<tr> +<td>-N P, --any_path=P +</td> +<td>Displays any object or attribute that matches path P +</td> +<td>See @ref subsubsecViewToolsViewAttr_h5dumpEx6 +</td> +</tr> +</table> + +\subsubsection subsubsecViewToolsViewDset_h5dumpEx4 Example 4 +A specific dataset can be viewed with <code style="background-color:whitesmoke;">h5dump</code> using the <code style="background-color:whitesmoke;">-d D</code> option and specifying the entire +path and name of the dataset for <code style="background-color:whitesmoke;">D</code>. The path is important in identifying the correct dataset, +as there can be multiple datasets with the same name. The path can be determined by looking at +the objects in the file with <code style="background-color:whitesmoke;">h5dump -n</code>. + +The following example uses the <code style="background-color:whitesmoke;">groups.h5</code> file that is created by the +\ref LBExamples +example <code style="background-color:whitesmoke;">h5_crtgrpar.c</code>. To display <code style="background-color:whitesmoke;">dset1</code> in the <code style="background-color:whitesmoke;">groups.h5</code> file below, specify dataset +<code style="background-color:whitesmoke;">/MyGroup/dset1</code>. The <code style="background-color:whitesmoke;">-H</code> option is used to suppress printing of the data values: + +<em>Contents of groups.h5</em> +\code + $ h5dump -n groups.h5 + HDF5 "groups.h5" { + FILE_CONTENTS { + group / + group /MyGroup + group /MyGroup/Group_A + dataset /MyGroup/Group_A/dset2 + group /MyGroup/Group_B + dataset /MyGroup/dset1 + } + } +\endcode + +<em>Display dataset "dset1"</em> +\code + $ h5dump -d "/MyGroup/dset1" -H groups.h5 + HDF5 "groups.h5" { + DATASET "/MyGroup/dset1" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) } + } + } +\endcode + +\subsubsection subsubsecViewToolsViewDset_h5dumpEx5 Example 5 +The <code style="background-color:whitesmoke;">-p</code> option is used to examine the the dataset filters, storage layout, and fill value properties of a dataset. + +This option can be useful for checking how well compression works, or even for analyzing performance +and dataset size issues related to chunking. (The smaller the chunk size, the more chunks that HDF5 +has to keep track of, which increases the size of the file and potentially affects performance.) + +In the file shown below the dataset <code style="background-color:whitesmoke;">/DS1</code> is both chunked and compressed: +\code + $ h5dump -H -p -d "/DS1" h5ex_d_gzip.h5 + HDF5 "h5ex_d_gzip.h5" { + DATASET "/DS1" { + DATATYPE H5T_STD_I32LE + DATASPACE SIMPLE { ( 32, 64 ) / ( 32, 64 ) } + STORAGE_LAYOUT { + CHUNKED ( 4, 8 ) + SIZE 5278 (1.552:1 COMPRESSION) + } + FILTERS { + COMPRESSION DEFLATE { LEVEL 9 } + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 0 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_INCR + } + } + } +\endcode + +You can obtain the <code style="background-color:whitesmoke;">h5ex_d_gzip.c</code> program that created this file, as well as the file created, +from the <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page. + +\subsection subsecViewToolsViewDset_h5ls h5ls +Specific datasets can be specified with <code style="background-color:whitesmoke;">h5ls</code> by simply adding the dataset path and dataset after the +file name. As an example, this command displays dataset <code style="background-color:whitesmoke;">dset2</code> in the <code style="background-color:whitesmoke;">groups.h5</code> +file used in @ref subsubsecViewToolsViewDset_h5dumpEx4 : +\code +h5ls groups.h5/MyGroup/Group_A/dset2 +\endcode + +Just the dataspace information gets displayed: +\code +dset2 Dataset {2, 10} +\endcode + +The following options can be used to see detailed information about a dataset. +<table> +<tr> +<th>Option</th> +<th>Description</th> +</tr> +<tr> +<td>-v, --verbose +</td> +<td>Generates verbose output (lists dataset properties, attributes +and attribute values, but no dataset values) +</td> +</tr> +<tr> +<td>-d, --data +</td> +<td>Displays dataset values +</td> +</tr> +</table> + +The output of using <code style="background-color:whitesmoke;">-v</code> is shown below: +\code + $ h5ls -v groups.h5/MyGroup/Group_A/dset2 + Opened "groups.h5" with sec2 driver. + dset2 Dataset {2/2, 10/10} + Location: 1:3840 + Links: 1 + Storage: 80 logical bytes, 80 allocated bytes, 100.00% utilization + Type: 32-bit big-endian integer +\endcode + +The output of using <code style="background-color:whitesmoke;">-d</code> is shown below: +\code + $ h5ls -d groups.h5/MyGroup/Group_A/dset2 + dset2 Dataset {2, 10} + Data: + (0,0) 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 +\endcode + +\section secViewToolsViewGrps Groups +Both h5dump and h5ls can be used to view specific groups in a file. +<ul> +<li>\ref subsecViewToolsViewGrps_h5dump</li> +<li>\ref subsecViewToolsViewGrps_h5ls</li> +</ul> + +\subsection subsecViewToolsViewGrps_h5dump h5dump +The <code style="background-color:whitesmoke;">h5dump</code> options that are useful for examining groups are: +<table> +<tr> +<th>Option</th> +<th>Description</th> +</tr> +<tr> +<td>-g G, --group=G +</td> +<td>Displays group G and its members +</td> +</tr> +<tr> +<td>-H, --header +</td> +<td>Displays header information only +</td> +</tr> +<tr> +<td>-A 0, --onlyattr=0 +</td> +<td>Suppresses the display of attributes +</td> +</tr> +</table> + +To view the contents of the <code style="background-color:whitesmoke;">HDFEOS</code> group in the OMI file mentioned previously, you can specify the path and name of the group as follows: +\code +h5dump -g "/HDFEOS" -H -A 0 OMI-Aura.he5 +\endcode + +The <code style="background-color:whitesmoke;">-A 0</code> option suppresses attributes and <code style="background-color:whitesmoke;">-H</code> suppresses printing of data values: +\code + HDF5 "OMI-Aura.he5" { + GROUP "/HDFEOS" { + GROUP "ADDITIONAL" { + GROUP "FILE_ATTRIBUTES" { + } + } + GROUP "GRIDS" { + GROUP "OMI Column Amount O3" { + GROUP "Data Fields" { + DATASET "ColumnAmountO3" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "RadiativeCloudFraction" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "SolarZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + DATASET "ViewingZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + } + } + } + } + } + } +\endcode + +\subsection subsecViewToolsViewGrps_h5ls h5ls +You can view the contents of a group with <code style="background-color:whitesmoke;">h5ls</code>/ by specifying the group after the file name. +To use <code style="background-color:whitesmoke;">h5ls</code> to view the contents of the <code style="background-color:whitesmoke;">/HDFEOS</code> group in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type: +\code +h5ls -r OMI-Aura.he5/HDFEOS +\endcode + +The output of this command is: +\code + /ADDITIONAL Group + /ADDITIONAL/FILE_ATTRIBUTES Group + /GRIDS Group + /GRIDS/OMI\ Column\ Amount\ O3 Group + /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields Group + /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ColumnAmountO3 Dataset {720, 1440} + /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/RadiativeCloudFraction Dataset {720, 1440} + /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/SolarZenithAngle Dataset {720, 1440} + /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ViewingZenithAngle Dataset {720, 1440} +\endcode + +If you specify the <code style="background-color:whitesmoke;">-v</code> option, you can also see the attributes and properties of the datasets. + +\section secViewToolsViewAttr Attributes + +\subsection subsecViewToolsViewAttr_h5dump h5dump +Attributes are displayed by default if using <code style="background-color:whitesmoke;">h5dump</code>. Some files contain many attributes, which +can make it difficult to examine the objects in the file. Shown below are options that can help +when using <code style="background-color:whitesmoke;">h5dump</code> to work with files that have attributes. + +\subsubsection subsubsecViewToolsViewAttr_h5dumpEx6 Example 6 +The <code style="background-color:whitesmoke;">-a</code> A option will display an attribute. However, the path to the attribute must be included +when specifying this option. For example, to see the <code style="background-color:whitesmoke;">ScaleFactor</code> attribute in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type: +\code +h5dump -a "/HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle/ScaleFactor" OMI-Aura.he5 +\endcode + +This command displays: +\code + HDF5 "OMI-Aura.he5" { + ATTRIBUTE "ScaleFactor" { + DATATYPE H5T_IEEE_F64LE + DATASPACE SIMPLE { ( 1 ) / ( 1 ) } + DATA { + (0): 1 + } + } + } +\endcode + +How can you determine the path to the attribute? This can be done by looking at the file contents with the <code style="background-color:whitesmoke;">-n 1</code> option: +\code +h5dump -n 1 OMI-Aura.he5 +\endcode + +Below is a portion of the output for this command: +\code + HDF5 "OMI-Aura.he5" { + FILE_CONTENTS { + group / + group /HDFEOS + group /HDFEOS/ADDITIONAL + group /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/EndUTC + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleDay + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleDayOfYear + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleMonth + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleYear + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/InstrumentName + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/OrbitNumber + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/OrbitPeriod + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/PGEVersion + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/Period + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/ProcessLevel + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/StartUTC + attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/TAI93At0zOfGranule + + ... +\endcode + +There can be multiple objects or attributes with the same name in a file. How can you make sure +you are finding the correct object or attribute? You can first determine how many attributes +there are with a specified name, and then examine the paths to them. + +The <code style="background-color:whitesmoke;">-N</code> option can be used to display all objects or attributes with a given name. +For example, there are four attributes with the name <code style="background-color:whitesmoke;">ScaleFactor</code> in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, +as can be seen below with the <code style="background-color:whitesmoke;">-N</code> option: +\code +h5dump -N ScaleFactor OMI-Aura.he5 +\endcode + +It outputs: +\code +HDF5 "OMI-Aura.he5" { +ATTRIBUTE "ScaleFactor" { + DATATYPE H5T_IEEE_F64LE + DATASPACE SIMPLE { ( 1 ) / ( 1 ) } + DATA { + (0): 1 + } +} +ATTRIBUTE "ScaleFactor" { + DATATYPE H5T_IEEE_F64LE + DATASPACE SIMPLE { ( 1 ) / ( 1 ) } + DATA { + (0): 1 + } +} +ATTRIBUTE "ScaleFactor" { + DATATYPE H5T_IEEE_F64LE + DATASPACE SIMPLE { ( 1 ) / ( 1 ) } + DATA { + (0): 1 + } +} +ATTRIBUTE "ScaleFactor" { + DATATYPE H5T_IEEE_F64LE + DATASPACE SIMPLE { ( 1 ) / ( 1 ) } + DATA { + (0): 1 + } +} +} +\endcode + +\subsection subsecViewToolsViewAttr_h5ls h5ls +If you include the <code style="background-color:whitesmoke;">-v</code> (verbose) option for <code style="background-color:whitesmoke;">h5ls</code>, you will see all of the attributes for the +specified file, dataset or group. You cannot display individual attributes. + +\section secViewToolsViewSub Dataset Subset + +\subsection subsecViewToolsViewSub_h5dump h5dump +If you have a very large dataset, you may wish to subset or see just a portion of the dataset. +This can be done with the following <code style="background-color:whitesmoke;">h5dump</code> options. +<table> +<tr> +<th>Option</th> +<th>Description</th> +</tr> +<tr> +<td>-d D, --dataset=D +</td> +<td>Dataset D +</td> +</tr> +<tr> +<td>-s START, --start=START +</td> +<td>Offset or start of subsetting selection +</td> +</tr> +<tr> +<td>-S STRIDE, --stride=STRIDE +</td> +<td>Stride (sampling along a dimension). The default (unspecified, or 1) selects +every element along a dimension, a value of 2 selects every other element, +a value of 3 selects every third element, ... +</td> +</tr> +<tr> +<td>-c COUNT, --count=COUNT +</td> +<td>Number of blocks to include in the selection +</td> +</tr> +<tr> +<td>-k BLOCK, --block=BLOCK +</td> +<td>Size of the block in a hyperslab. The default (unspecified, or 1) is for +the block size to be the size of a single element. +</td> +</tr> +</table> + +The <code style="background-color:whitesmoke;">START (s)</code>, <code style="background-color:whitesmoke;">STRIDE (S)</code>, <code style="background-color:whitesmoke;">COUNT (c)</code>, and <code style="background-color:whitesmoke;">BLOCK (k)</code> options +define the shape and size of the selection. They are arrays with the same number of dimensions as the rank +of the dataset's dataspace, and they all work together to define the selection. A change to one of +these arrays can affect the others. + +When specifying these h5dump options, a comma is used as the delimiter for each dimension in the +option value. For example, with a 2-dimensional dataset, the option value is specified as "H,W", +where H is the height and W is the width. If the offset is 0 for both dimensions, then +<code style="background-color:whitesmoke;">START</code> would be specified as follows: +\code +-s "0,0" +\endcode + +There is also a shorthand way to specify these options with brackets at the end of the dataset name: +\code +-d DATASETNAME[s;S;c;k] +\endcode + +Multiple dimensions are separated by commas. For example, a subset for a 2-dimensional dataset would be specified as follows: +\code +-d DATASETNAME[s,s;S,S;c,c;k,k] +\endcode + +For a detailed understanding of how selections works, see the #H5Sselect_hyperslab API in the \ref RM. + +The dataset SolarZenithAngle in the OMI-Aura.he5 file can be used to illustrate these options. This +dataset is a 2-dimensional dataset of size 720 (height) x 1440 (width). Too much data will be displayed +by simply viewing the specified dataset with the <code style="background-color:whitesmoke;">-d</code> option: +\code +h5dump -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" OMI-Aura.he5 +\endcode +Subsetting narrows down the output that is displayed. In the following example, the first +15x10 elements (-c "15,10") are specified, beginning with position (0,0) (-s "0,0"): +\code + h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" -s "0,0" -c "15,10" -w 0 OMI-Aura.he5 +\endcode + +If using the shorthand method, specify: +\code + h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle[0,0;;15,10;]" -w 0 OMI-Aura.he5 +\endcode + +Where, +\par The <code style="background-color:whitesmoke;">-d</code> option must be specified + +before +\par subsetting options (if not using the shorthand method). + +The <code style="background-color:whitesmoke;">-A 0</code> option suppresses the printing of attributes. + +The <code style="background-color:whitesmoke;">-w 0</code> option sets the number of columns of output to the maximum allowed value (65535). +This ensures that there are enough columns specified for displaying the data. + +Either command displays: +\code + HDF5 "OMI-Aura.he5" { + DATASET "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + SUBSET { + START ( 0, 0 ); + STRIDE ( 1, 1 ); + COUNT ( 15, 10 ); + BLOCK ( 1, 1 ); + DATA { + (0,0): 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, + (1,0): 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, + (2,0): 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, + (3,0): 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, + (4,0): 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, + (5,0): 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, + (6,0): 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, + (7,0): 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, + (8,0): 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, + (9,0): 77.658, 77.658, 77.658, 77.307, 77.307, 77.307, 77.307, 77.307, 77.307, 77.307, + (10,0): 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.102, 77.102, + (11,0): 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 77.102, 77.102, + (12,0): 76.34, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, + (13,0): 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 77.195, + (14,0): 78.005, 78.005, 78.005, 78.005, 78.005, 78.005, 76.991, 76.991, 76.991, 76.991 + } + } + } + } +\endcode + +What if we wish to read three rows of three elements at a time (-c "3,3"), where each element +is a 2 x 3 block (-k "2,3") and we wish to begin reading from the second row (-s "1,0")? + +You can do that with the following command: +\code + h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" + -s "1,0" -S "2,3" -c "3,3" -k "2,3" -w 0 OMI-Aura.he5 +\endcode + +In this case, the stride must be specified as 2 by 3 (or larger) to accommodate the reading of 2 by 3 blocks. +If it is smaller, the command will fail with the error, +\code +h5dump error: wrong subset selection; blocks overlap. +\endcode + +The output of the above command is shown below: +\code + HDF5 "OMI-Aura.he5" { + DATASET "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" { + DATATYPE H5T_IEEE_F32LE + DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) } + SUBSET { + START ( 1, 0 ); + STRIDE ( 2, 3 ); + COUNT ( 3, 3 ); + BLOCK ( 2, 3 ); + DATA { + (1,0): 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, + (2,0): 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, + (3,0): 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, + (4,0): 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, + (5,0): 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, + (6,0): 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021 + } + } + } + } +\endcode + +\section secViewToolsViewDtypes Datatypes + +\subsection subsecViewToolsViewDtypes_h5dump h5dump +The following datatypes are discussed, using the output of <code style="background-color:whitesmoke;">h5dump</code> with HDF5 files from the +<a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page: +<ul> +<li>@ref subsubsecViewToolsViewDtypes_array</li> +<li>@ref subsubsecViewToolsViewDtypes_objref</li> +<li>@ref subsubsecViewToolsViewDtypes_regref</li> +<li>@ref subsubsecViewToolsViewDtypes_string</li> +</ul> + +\subsubsection subsubsecViewToolsViewDtypes_array Array +Users have been confused by the difference between an Array datatype (#H5T_ARRAY) and a dataset that +(has a dataspace that) is an array. + +Typically, these users want a dataset that has a simple datatype (like integer or float) that is an +array, like the following dataset <code style="background-color:whitesmoke;">/DS1</code>. It has a datatype of #H5T_STD_I32LE (32-bit Little-Endian Integer) +and is a 4 by 7 array: +\code +$ h5dump h5ex_d_rdwr.h5 +HDF5 "h5ex_d_rdwr.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_STD_I32LE + DATASPACE SIMPLE { ( 4, 7 ) / ( 4, 7 ) } + DATA { + (0,0): 0, -1, -2, -3, -4, -5, -6, + (1,0): 0, 0, 0, 0, 0, 0, 0, + (2,0): 0, 1, 2, 3, 4, 5, 6, + (3,0): 0, 2, 4, 6, 8, 10, 12 + } + } +} +} +\endcode + +Contrast that with the following dataset that has both an Array datatype and is an array: +\code +$ h5dump h5ex_t_array.h5 +HDF5 "h5ex_t_array.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_ARRAY { [3][5] H5T_STD_I64LE } + DATASPACE SIMPLE { ( 4 ) / ( 4 ) } + DATA { + (0): [ 0, 0, 0, 0, 0, + 0, -1, -2, -3, -4, + 0, -2, -4, -6, -8 ], + (1): [ 0, 1, 2, 3, 4, + 1, 1, 1, 1, 1, + 2, 1, 0, -1, -2 ], + (2): [ 0, 2, 4, 6, 8, + 2, 3, 4, 5, 6, + 4, 4, 4, 4, 4 ], + (3): [ 0, 3, 6, 9, 12, + 3, 5, 7, 9, 11, + 6, 7, 8, 9, 10 ] + } + } +} +} +\endcode + +In this file, dataset <code style="background-color:whitesmoke;">/DS1</code> has a datatype of +\code +H5T_ARRAY { [3][5] H5T_STD_I64LE } +\endcode +and it also has a dataspace of +\code +SIMPLE { ( 4 ) / ( 4 ) } +\endcode +In other words, it is an array of four elements, in which each element is a 3 by 5 array of #H5T_STD_I64LE. + +This dataset is much more complex. Also note that subsetting cannot be done on Array datatypes. + +See this <a href="https://portal.hdfgroup.org/display/knowledge/H5T_ARRAY+Datatype">FAQ</a> for more information on the Array datatype. + +\subsubsection subsubsecViewToolsViewDtypes_objref Object Reference +An Object Reference is a reference to an entire object (dataset, group, or named datatype). +A dataset with an Object Reference datatype consists of one or more Object References. +An Object Reference dataset can be used as an index to an HDF5 file. + +The <code style="background-color:whitesmoke;">/DS1</code> dataset in the following file (<code style="background-color:whitesmoke;">h5ex_t_objref.h5</code>) is an Object Reference dataset. +It contains two references, one to group <code style="background-color:whitesmoke;">/G1</code> and the other to dataset <code style="background-color:whitesmoke;">/DS2</code>: +\code +$ h5dump h5ex_t_objref.h5 +HDF5 "h5ex_t_objref.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_OBJECT } + DATASPACE SIMPLE { ( 2 ) / ( 2 ) } + DATA { + (0): GROUP 1400 /G1 , DATASET 800 /DS2 + } + } + DATASET "DS2" { + DATATYPE H5T_STD_I32LE + DATASPACE NULL + DATA { + } + } + GROUP "G1" { + } +} +} +\endcode + +\subsubsection subsubsecViewToolsViewDtypes_regref Region Reference +A Region Reference is a reference to a selection within a dataset. A selection can be either +individual elements or a hyperslab. In <code style="background-color:whitesmoke;">h5dump</code> you will see the name of the dataset along with +the elements or slab that is selected. A dataset with a Region Reference datatype consists of +one or more Region References. + +An example of a Region Reference dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.h5</code>) can be found on the +<a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page, +under Datatypes. If you examine this dataset with <code style="background-color:whitesmoke;">h5dump</code> you will see that <code style="background-color:whitesmoke;">/DS1</code> is a +Region Reference dataset as indicated by its datatype, highlighted in bold below: +\code +$ h5dump h5ex_t_regref.h5 +HDF5 "h5ex_t_regref.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 2 ) / ( 2 ) } + DATA { + DATASET /DS2 {(0,1), (2,11), (1,0), (2,4)}, + DATASET /DS2 {(0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)} + } + } + DATASET "DS2" { + DATATYPE H5T_STD_I8LE + DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) } + DATA { + (0,0): 84, 104, 101, 32, 113, 117, 105, 99, 107, 32, 98, 114, 111, 119, + (0,14): 110, 0, + (1,0): 102, 111, 120, 32, 106, 117, 109, 112, 115, 32, 111, 118, 101, + (1,13): 114, 32, 0, + (2,0): 116, 104, 101, 32, 53, 32, 108, 97, 122, 121, 32, 100, 111, 103, + (2,14): 115, 0 + } + } +} +} +\endcode + +It contains two Region References: +\li A selection of four individual elements in dataset <code style="background-color:whitesmoke;">/DS2 : (0,1), (2,11), (1,0), (2,4)</code> +See the #H5Sselect_elements API in the \ref UG for information on selecting individual elements. +\li A selection of these blocks in dataset <code style="background-color:whitesmoke;">/DS2 : (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)</code> +See the #H5Sselect_hyperslab API in the \ref UG for how to do hyperslab selection. + + +If you look at the code that creates the dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.c</code>) you will see that the +first reference is created with these calls: +\code + status = H5Sselect_elements (space, H5S_SELECT_SET, 4, coords[0]); + status = H5Rcreate (&wdata[0], file, DATASET2, H5R_DATASET_REGION, space); +\endcode + +where the buffer containing the coordinates to select is: +\code + coords[4][2] = { {0, 1}, + {2, 11}, + {1, 0}, + {2, 4} }, +\endcode + +The second reference is created by calling, +\code + status = H5Sselect_hyperslab (space, H5S_SELECT_SET, start, stride, count, block); + status = H5Rcreate (&wdata[1], file, DATASET2, H5R_DATASET_REGION, space); +\endcode +where start, stride, count, and block have these values: +\code + start[2] = {0, 0}, + stride[2] = {2, 11}, + count[2] = {2, 2}, + block[2] = {1, 3}; +\endcode + +These start, stride, count, and block values will select the elements shown in bold in the dataset: +\code +84 104 101 32 113 117 105 99 107 32 98 114 111 119 110 0 +102 111 120 32 106 117 109 112 115 32 111 118 101 114 32 0 +116 104 101 32 53 32 108 97 122 121 32 100 111 103 115 0 +\endcode + +If you use <code style="background-color:whitesmoke;">h5dump</code> to select a subset of dataset +<code style="background-color:whitesmoke;">/DS2</code> with these start, stride, count, and block values, you will see that the same elements are selected: +\code +$ h5dump -d "/DS2" -s "0,0" -S "2,11" -c "2,2" -k "1,3" h5ex_t_regref.h5 +HDF5 "h5ex_t_regref.h5" { +DATASET "/DS2" { + DATATYPE H5T_STD_I8LE + DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) } + SUBSET { + START ( 0, 0 ); + STRIDE ( 2, 11 ); + COUNT ( 2, 2 ); + BLOCK ( 1, 3 ); + DATA { + (0,0): 84, 104, 101, 114, 111, 119, + (2,0): 116, 104, 101, 100, 111, 103 + } + } +} +} +\endcode + +For more information on selections, see the tutorial topic on +@ref LBDsetSubRW. Also see the +\ref secViewToolsViewSub tutorial topic on using <code style="background-color:whitesmoke;">h5dump</code> to view a subset. + +\subsubsection subsubsecViewToolsViewDtypes_string String +There are two types of string data, fixed length strings and variable length strings. + +Below is the <code style="background-color:whitesmoke;">h5dump</code> output for two files that have the same strings written to them. In one file, +the strings are fixed in length, and in the other, the strings have different sizes (and are variable in size). + +<em>Dataset of Fixed Length Strings</em> +\code +HDF5 "h5ex_t_string.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_STRING { + STRSIZE 7; + STRPAD H5T_STR_SPACEPAD; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SIMPLE { ( 4 ) / ( 4 ) } + DATA { + (0): "Parting", "is such", "sweet ", "sorrow." + } + } +} +} +\endcode + +<em>Dataset of Variable Length Strings</em> +\code +HDF5 "h5ex_t_vlstring.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_STRING { + STRSIZE H5T_VARIABLE; + STRPAD H5T_STR_SPACEPAD; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SIMPLE { ( 4 ) / ( 4 ) } + DATA { + (0): "Parting", "is such", "sweet", "sorrow." + } + } +} +} +\endcode + +You might wonder which to use. Some comments to consider are included below. +\li In general, a variable length string dataset is more complex than a fixed length string. If you don't +specifically need a variable length type, then just use the fixed length string. +\li A variable length dataset consists of pointers to heaps in different locations in the file. For this +reason, a variable length dataset cannot be compressed. (Basically, the pointers get compressed and +not the actual data!) If compression is needed, then do not use variable length types. +\li If you need to create an array of of different length strings, you can either use fixed length strings +along with compression, or use a variable length string. + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand + +*/ diff --git a/doxygen/dox/ViewTools2.dox b/doxygen/dox/ViewTools2.dox new file mode 100644 index 0000000..4d8788a --- /dev/null +++ b/doxygen/dox/ViewTools2.dox @@ -0,0 +1,786 @@ +/** @page ViewToolsEdit Command-line Tools For Editing HDF5 Files +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand +<hr> + +\section secViewToolsEditTOC Contents +<ul> +<li>\ref secViewToolsEditRemove</li> +<li>\ref secViewToolsEditChange</li> +<li>\ref secViewToolsEditApply</li> +<li>\ref secViewToolsEditCopy</li> +<li>\ref secViewToolsEditAdd</li> +</ul> + +\section secViewToolsEditRemove Remove Inaccessible Objects and Unused Space in a File +HDF5 files may accumulate unused space when they are read and rewritten to or if objects are deleted within +them. With many edits and deletions this unused space can add up to a sizable amount. + +The <code style="background-color:whitesmoke;">h5repack</code> tool can be used to remove unused space in an HDF5 +file. If no options other than the input and output HDF5 files are specified on the +<code style="background-color:whitesmoke;">h5repack</code> command line, it will write the file to the new +file, getting rid of the unused space: +\code +h5repack <input file> <output file> +\endcode + +\section secViewToolsEditChange Change a Dataset's Storage Layout +The <code style="background-color:whitesmoke;">h5repack</code> utility can be used to change a dataset's storage +layout. By default, the storage layout of a dataset is defined at creation time and it cannot be changed. +However, with h5repack you can write an HDF5 file to a new file and change the layout for objects in the new file. + +The <code style="background-color:whitesmoke;">-l</code> option in <code style="background-color:whitesmoke;">h5repack</code> +is used to change the layout for an object. The string following the <code style="background-color:whitesmoke;">-l</code> +option defines the layout type and parameters for specified objects (or all objects): +\code +h5repack -l [list of objects:]<layout type>=<layout parameters> <input file> <output file> +\endcode + +If no object is specified, then everything in the input file will be written to the output file with the specified +layout type and parameters. If objects are specified then everything in the input file will be written to the +output file as is, except for those specified objects. They will be written to the output file with the given +layout type and parameters. + +Following is a description of the dataset layouts and the <code style="background-color:whitesmoke;">h5repack</code> +options to use to change a dataset: +<table> +<tr> +<th>Storage Layout</th><th>h5repack Option</th><th>Description</th> +</tr> +<tr> +<td>Contiguous +</td> +<td>CONTI +</td> +<td>Data is stored physically together +</td> +</tr> +<tr> +<td>Chunked +</td> +<td>CHUNK=DIM[xDIM...xDIM] +</td> +<td>Data is stored in DIM[xDIM...xDIM] chunks +</td> +</tr> +<tr> +<td>Compact +</td> +<td>COMPA +</td> +<td>Data is stored in the header of the object (less I/O) +</td> +</tr> +</table> + +If you type <code style="background-color:whitesmoke;">h5repack -h</code> on the command line, you will see +a detailed usage statement with examples of modifying the layout. + +In the following example, the dataset <code style="background-color:whitesmoke;">/dset</code> in the file +dset.h5 is contiguous, as shown by the <code style="background-color:whitesmoke;">h5dump -pH</code> command. +The <code style="background-color:whitesmoke;">h5repack</code> utility writes dset.h5 to a new file, dsetrpk.h5, +where the dataset <code style="background-color:whitesmoke;">dset</code> is chunked. This can be seen by examining +the resulting dsetrpk.h5 file with <code style="background-color:whitesmoke;">h5dump</code>, as shown: +\code +$ h5dump -pH dset.h5 +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + STORAGE_LAYOUT { + CONTIGUOUS + SIZE 96 + OFFSET 1400 + } + FILTERS { + NONE + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 0 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_LATE + } + } +} +} + +$ h5repack -l dset:CHUNK=4x6 dset.h5 dsetrpk.h5 + +$ h5dump -pH dsetrpk.h5 +HDF5 "dsetrpk.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + STORAGE_LAYOUT { + CHUNKED ( 4, 6 ) + SIZE 96 + } + FILTERS { + NONE + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 0 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_INCR + } + } +} +} +\endcode + +There can be many reasons that the storage layout needs to be changed for a dataset. For example, +there may be a performance issue with a dataset due to a small chunk size. + +\section secViewToolsEditApply Apply Compression Filter to a Dataset +The <code style="background-color:whitesmoke;">h5repack</code> utility can be used to compress or +remove compression from a dataset in a file. By default, compression cannot be added to or removed +from a dataset once it has been created. However, with <code style="background-color:whitesmoke;">h5repack</code> +you can write a file to a new file and specify a compression filter to apply to a dataset or datasets in the new file. + +To apply a filter to an object in an HDF5 file, specify the <code style="background-color:whitesmoke;">-f</code> option, +where the string following the <code style="background-color:whitesmoke;">-f</code> option defines the filter and +its parameters (if there are any) to apply to a given object or objects: +\code +h5repack -f [list of objects:]<name of filter>=<filter parameters> <input file> <output file> +\endcode + +If no objects are specified then everything in the input file will be written to the output file with +the filter and parameters specified. If objects are specified, then everything in the input file will +be written to the output file as is, except for the specified objects. They will be written to the +output file with the filter and parameters specified. + +If you type <code style="background-color:whitesmoke;">h5repack --help</code> on the command line, +you will see a detailed usage statement with examples of modifying a filter. There are actually +numerous filters that you can apply to a dataset: +<table> +<tr> +<th>Filter<th></th>Options</th> +</tr> +<tr> +<td>GZIP compression (levels 1-9) +<td>GZIP=<deflation level> +</td> +</tr> +<tr> +<td>SZIP compression +<td>SZIP=<pixels per block,coding> +</td> +</tr> +<tr> +<td>Shuffle filter +<td>SHUF +</td> +</tr> +<tr> +<td>Checksum filter +<td>FLET +</td> +</tr> +<tr> +<td>NBIT compression +<td>NBIT +</td> +</tr> +<tr> +<td>HDF5 Scale/Offset filter +<td>SOFF=<scale_factor,scale_type> +</td> +</tr> +<tr> +<td>User defined filter +<td>UD=<filter_number,cd_value_count,value_1[,value_2,...,value_N]> +</td> +</tr> +<tr> +<td>Remove ALL filters +</td> +<td>NONE +</td> +</tr> +</table> + +Be aware that a dataset must be chunked to apply compression to it. If the dataset is not already chunked, +then <code style="background-color:whitesmoke;">h5repack</code> will apply chunking to it. Both chunking +and compression cannot be applied to a dataset at the same time with <code style="background-color:whitesmoke;">h5repack</code>. + +In the following example, +\li <em>h5dump</em> lists the properties for the objects in <em>dset.h5</em>. Note that the dataset <em>dset</em> is contiguous. +\li <em>h5repack</em> writes dset.h5 into a new file <em>dsetrpk.h5</em>, applying GZIP Level 5 compression to the dataset <em>/dset</em> in dsetrpk.h5. +\li <em>h5dump</em> lists the properties for the new <em>dsetrpk.h5</em> file. Note that <em>/dset</em> is both compressed and chunked. + +<em>Example</em> +\code +$ h5dump -pH dset.h5 +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 12, 18 ) / ( 12, 18 ) } + STORAGE_LAYOUT { + CONTIGUOUS + SIZE 864 + OFFSET 1400 + } + FILTERS { + NONE + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 0 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_LATE + } + } +} +} + +$ h5repack -f dset:GZIP=5 dset.h5 dsetrpk.h5 + +$ h5dump -pH dsetrpk.h5 +HDF5 "dsetrpk.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 12, 18 ) / ( 12, 18 ) } + STORAGE_LAYOUT { + CHUNKED ( 12, 18 ) + SIZE 160 (5.400:1 COMPRESSION) + } + FILTERS { + COMPRESSION DEFLATE { LEVEL 5 } + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 0 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_INCR + } + } +} +} +\endcode + +\section secViewToolsEditCopy Copy Objects to Another File +The <code style="background-color:whitesmoke;">h5copy</code> utility can be used to copy an object or +objects from one HDF5 file to another or to a different location in the same file. It uses the +#H5Ocopy and #H5Lcopy APIs in HDF5. + +Following are some of the options that can be used with <code style="background-color:whitesmoke;">h5copy</code>. +<table> +<tr> +<th>h5copy Options</th><th>Description</th> +</tr> +<tr> +<td>-i, --input +</td> +<td>Input file name +</td> +</tr> +<tr> +<td>-o, --output +</td> +<td>Output file name +</td> +</tr> +<tr> +<td>-s, --source +</td> +<td>Source object name +</td> +</tr> +<tr> +<td>-d, --destination +</td> +<td>Destination object name +</td> +</tr> +<tr> +<td>-p, --parents +</td> +<td>Make parent groups as needed +</td> +</tr> +<tr> +<td>-v, --verbose +</td> +<td>Verbose mode +</td> +</tr> +<tr> +<td>-f, --flag +</td> +<td>Flag type +</td> +</tr> +</table> + +For a complete list of options and information on using <code style="background-color:whitesmoke;">h5copy</code>, type: +\code +h5copy --help +\endcode + +In the example below, the dataset <code style="background-color:whitesmoke;">/MyGroup/Group_A/dset2</code> +in <code style="background-color:whitesmoke;">groups.h5</code> gets copied to the root +("<code style="background-color:whitesmoke;">/</code>") group of a new file, +<code style="background-color:whitesmoke;">newgroup.h5</code>, with the name +<code style="background-color:whitesmoke;">dset3</code>: +\code +$h5dump -H groups.h5 +HDF5 "groups.h5" { +GROUP "/" { + GROUP "MyGroup" { + GROUP "Group_A" { + DATASET "dset2" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 2, 10 ) / ( 2, 10 ) } + } + } + GROUP "Group_B" { + } + DATASET "dset1" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) } + } + } +} +} + +$ h5copy -i groups.h5 -o newgroup.h5 -s /MyGroup/Group_A/dset2 -d /dset3 + +$ h5dump -H newgroup.h5 +HDF5 "newgroup.h5" { +GROUP "/" { + DATASET "dset3" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 2, 10 ) / ( 2, 10 ) } + } +} +} +\endcode + +There are also <code style="background-color:whitesmoke;">h5copy</code> flags that can be specified +with the <code style="background-color:whitesmoke;">-f</code> option. In the example below, the +<code style="background-color:whitesmoke;">-f shallow</code> option specifies to copy only the +immediate members of the group <code style="background-color:whitesmoke;">/MyGroup</code> from +the <code style="background-color:whitesmoke;">groups.h5</code> file mentioned above to a new +file <code style="background-color:whitesmoke;">mygrouponly.h5</code>: +\code +h5copy -v -i groups.h5 -o mygrouponly.h5 -s /MyGroup -d /MyGroup -f shallow +\endcode + +The output of the above command is shown below. The verbose option <code style="background-color:whitesmoke;">-v</code> +describes the action that was taken, as shown in the highlighted text. +\code +Copying file <groups.h5> and object </MyGroup> to file <mygrouponly.h5> and object </MyGroup> +Using shallow flag + +$ h5dump -H mygrouponly.h5 +HDF5 "mygrouponly.h5" { +GROUP "/" { + GROUP "MyGroup" { + GROUP "Group_A" { + } + GROUP "Group_B" { + } + DATASET "dset1" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) } + } + } +} +} +\endcode + +\section secViewToolsEditAdd Add or Remove User Block from File +The user block is a space in an HDF5 file that is not interpreted by the HDF5 library. It is a property +list that can be added when creating a file. See the #H5Pset_userblock API in the \ref RM for more +information regarding this property. + +Once created in a file, the user block cannot be removed. However, you can use the +<code style="background-color:whitesmoke;">h5jam</code> and <code style="background-color:whitesmoke;">h5unjam</code> +utilities to add or remove a user block from a file into a new file. + +These two utilities work similarly, except that <code style="background-color:whitesmoke;">h5jam</code> +adds a user block to a file and <code style="background-color:whitesmoke;">h5unjam</code> removes the user +block. You can also overwrite or delete a user block in a file. + +Specify the <code style="background-color:whitesmoke;">-h</code> option to see a complete list of options +that can be used with <code style="background-color:whitesmoke;">h5jam</code> and +<code style="background-color:whitesmoke;">h5unjam</code>. For example: +\code + h5jam -h + h5unjam -h +\endcode + +Below are the basic options for adding or removing a user block with <code style="background-color:whitesmoke;">h5jam</code> +and <code style="background-color:whitesmoke;">h5unjam</code>: + +<table> +<tr> +<th>h5copy Options</th><th>Description</th> +</tr> +<tr> +<td>-i +</td> +<td>Input File +</td> +</tr> +<tr> +<td>-o +</td> +<td>Output File +</td> +</tr> +<tr> +<td>-u +</td> +<td>File to add or remove from user block +</td> +</tr> +</table> + +Let's say you wanted to add the program that creates an HDF5 file to its user block. As an example, you +can take the <code style="background-color:whitesmoke;">h5_crtgrpar.c</code> program from the +\ref LBExamples +and add it to the file it creates, <code style="background-color:whitesmoke;">groups.h5</code>. This can +be done with <code style="background-color:whitesmoke;">h5jam</code>, as follows: +\code +h5jam -i groups.h5 -u h5_crtgrpar.c -o groupsub.h5 +\endcode + +You can actually view the file with more <code style="background-color:whitesmoke;">groupsub.h5</code> +to see that the <code style="background-color:whitesmoke;">h5_crtgrpar.c</code> file is indeed included. + +To remove the user block that was just added, type: +\code +h5unjam -i groupsub.h5 -u h5_crtgrparNEW.c -o groups-noub.h5 +\endcode + +This writes the user block in the file <code style="background-color:whitesmoke;">groupsub.h5</code> +into <code style="background-color:whitesmoke;">h5_crtgrparNEW.c</code>. The new HDF5 file, +<code style="background-color:whitesmoke;">groups-noub.h5</code>, will not contain a user block. + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand + +*/ + +/** @page ViewToolsConvert Command-line Tools For Converting HDF5 Files +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand +<hr> + +\section secViewToolsConvertTOC Contents +<ul> +<li>\ref secViewToolsConvertASCII</li> +<li>\ref secViewToolsConvertBinary</li> +<li>\ref secViewToolsConvertExport</li> +</ul> + +\section secViewToolsConvertASCII Output HDF5 Dataset into an ASCII File (to Import into Excel and Other Applications) +The <code style="background-color:whitesmoke;">h5dump</code> utility can be used to convert an HDF5 dataset +into an ASCII file, which can then be imported into Excel and other applications. The following options are used: +<table> +<tr> +<th>Options</th><th>Description</th> +</tr> +<tr> +<td> -d D, --dataset=D +</td> +<td>Display dataset D +</td> +</tr> +<tr> +<td> -o F, --output=F +</td> +<td>Output raw data into file F +</td> +</tr> +<tr> +<td> -y, --noindex +</td> +<td>Suppress printing of array indices with the data +</td> +</tr> +<tr> +<td> -w N, --width=N +</td> +<td>Set N number of columns of output. A value of 0 +sets the number to 65535 (the maximum) +</td> +</tr> +</table> + +As an example, <code style="background-color:whitesmoke;">h5_crtdat.c</code> from the \ref LBDsetCreate +HDF5 Tutorial topic, creates the file <code style="background-color:whitesmoke;">dset.h5</code> with +a dataset <code style="background-color:whitesmoke;">/dset</code> that is a 4 x 6 integer array. The +following is displayed when viewing <code style="background-color:whitesmoke;">dset.h5</code> with +<code style="background-color:whitesmoke;">h5dump</code>: +\code +$ h5dump dset.h5 +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + (0,0): 1, 2, 3, 4, 5, 6, + (1,0): 7, 8, 9, 10, 11, 12, + (2,0): 13, 14, 15, 16, 17, 18, + (3,0): 19, 20, 21, 22, 23, 24 + } + } +} +} +\endcode + +The following command will output the values of the <code style="background-color:whitesmoke;">/dset</code> +dataset to the ASCII file <code style="background-color:whitesmoke;">dset.asci</code>: +\code +h5dump -d /dset -o dset.asci -y -w 50 dset.h5 +\endcode + +In particular, note that: +\li The default behavior of <code style="background-color:whitesmoke;">h5dump</code> is to print indices, +and the <code style="background-color:whitesmoke;">-y</code> option suppresses this. +\li The <code style="background-color:whitesmoke;">-w 50</code> option tells +<code style="background-color:whitesmoke;">h5dump</code> to allow 50 columns for outputting the data. The +value specified must be large enough to accommodate the dimension size of the dataset multiplied by the +number of positions and spaces needed to print each value. If the value is not large enough, the output +will wrap to the next line, and the data will not display as expected in Excel or other applications. To +ensure that the output does not wrap to the next line, you can also specify 0 (zero) for the +<code style="background-color:whitesmoke;">-w</code> option. + +In addition to creating the ASCII file <code style="background-color:whitesmoke;">dset.asci</code>, the +above command outputs the metadata of the specified dataset: +\code +HDF5 "dset.h5" { +DATASET "/dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + } +} +} +\endcode + +The <code style="background-color:whitesmoke;">dset.asci</code> file will contain the values for the dataset: +\code + 1, 2, 3, 4, 5, 6, + 7, 8, 9, 10, 11, 12, + 13, 14, 15, 16, 17, 18, + 19, 20, 21, 22, 23, 24 +\endcode + +\section secViewToolsConvertBinary Output HDF5 Dataset into Binary File +The <code style="background-color:whitesmoke;">h5dump</code> utility can be used to convert an +HDF5 dataset to a binary file with the following options: +<table> +<tr> +<th>Options</th><th>Description</th> +</tr> +<tr> +<td>-d D, --dataset=D +</td> +<td>Display dataset D +</td> +</tr> +<tr> +<td>-o F, --output=F +</td> +<td>Output raw data into file F +</td> +</tr> +<tr> +<td>-b B, --binary=B +</td> +<td>Binary file output of form B. +Valid values are: LE, BE, NATIVE, FILE +</td> +</tr> +</table> + +As an example, <code style="background-color:whitesmoke;">h5_crtdat.c</code> from the +\ref LBDsetCreate HDF5 Tutorial topic, creates the file dset.h5 with a dataset +<code style="background-color:whitesmoke;">/dset</code> that is a 4 x 6 integer array. The +following is displayed when viewing <code style="background-color:whitesmoke;">dset.h5</code> +with <code style="background-color:whitesmoke;">h5dump</code>: +\code +$ h5dump -d /dset/ dset.h5 +HDF5 "dset.h5" { +DATASET "/dset/" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + (0,0): 1, 2, 3, 4, 5, 6, + (1,0): 7, 8, 9, 10, 11, 12, + (2,0): 13, 14, 15, 16, 17, 18, + (3,0): 19, 20, 21, 22, 23, 24 + } +} +} +\endcode + +As specified by the <code style="background-color:whitesmoke;">-d</code> and +<code style="background-color:whitesmoke;">-o</code> options, the following +<code style="background-color:whitesmoke;">h5dump</code> command will output the values of the dataset +<code style="background-color:whitesmoke;">/dset </code>to a file called +<code style="background-color:whitesmoke;">dset.bin</code>. The <code style="background-color:whitesmoke;">-b</code> +option specifies that the output will be binary in Little Endian format (LE). + +\code +h5dump -d /dset -b LE -o dset.bin dset.h5 +\endcode + +This command outputs the metadata for the dataset, as well as creating the binary file +<code style="background-color:whitesmoke;">dset.bin</code>: +\code +HDF5 "dset.h5" { +DATASET "/dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + } +} +} +\endcode + +If you look at the resulting <code style="background-color:whitesmoke;">dset.bin</code> file with +a binary editor, you will see that it contains the dataset's values. For example (on Linux) you will see: +\code +$ od -t d dset.bin +0000000 1 2 3 4 +0000020 5 6 7 8 +0000040 9 10 11 12 +0000060 13 14 15 16 +0000100 17 18 19 20 +0000120 21 22 23 24 +0000140 +\endcode + +\section secViewToolsConvertExport Export from h5dump and Import into HDF5 +The <code style="background-color:whitesmoke;">h5import</code> utility can use the output of +<code style="background-color:whitesmoke;">h5dump</code> as input to create a dataset or file. + +The <code style="background-color:whitesmoke;">h5dump</code> utility must first create two files: +\li A DDL file, which will be used as an <code style="background-color:whitesmoke;">h5import</code> configuration file +\li A raw data file containing the data to be imported + +The DDL file must be generated with the <code style="background-color:whitesmoke;">h5dump -p</code> option, to generate properties. + +The raw data file that can be imported into HDF5 using this method may contain either numeric or string data with the following restrictions: +\li Numeric data requires the use of the <code style="background-color:whitesmoke;">h5dump -b</code> option to produce a binary data file. +\li String data must be written with the <code style="background-color:whitesmoke;">h5dump -y</code> and +<code style="background-color:whitesmoke;">--width=1</code> options, generating a single column of strings without indices. + +Two examples follow: the first imports a dataset with a numeric datatype. Note that numeric data requires +the use of the <code style="background-color:whitesmoke;">h5dump -b</code> option to produce a binary data +file. The example program (<code style="background-color:whitesmoke;">h5_crtdat.c</code>) that creates this +file is included with the \ref IntroHDF5 tutorial and can be obtained from the \ref LBExamples page: +\code +h5dump -p -d "/dset" --ddl=dsetbin.dmp -o dset.bin -b dset.h5 +h5import dset.bin -c dsetbin.dmp -o new-dset.h5 +\endcode + +The output before and after running these commands is shown below: +\code +$ h5dump dset.h5 +HDF5 "dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + (0,0): 1, 2, 3, 4, 5, 6, + (1,0): 7, 8, 9, 10, 11, 12, + (2,0): 13, 14, 15, 16, 17, 18, + (3,0): 19, 20, 21, 22, 23, 24 + } + } +} +} +$ h5dump -p -d "/dset" --ddl=dsetbin.dmp -o dset.bin -b dset.h5 + +$ h5import dset.bin -c dsetbin.dmp -o new-dset.h5 + +$ h5dump new-dset.h5 +HDF5 "new-dset.h5" { +GROUP "/" { + DATASET "dset" { + DATATYPE H5T_STD_I32BE + DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) } + DATA { + (0,0): 1, 2, 3, 4, 5, 6, + (1,0): 7, 8, 9, 10, 11, 12, + (2,0): 13, 14, 15, 16, 17, 18, + (3,0): 19, 20, 21, 22, 23, 24 + } + } +} +} +\endcode + +The second example imports string data. The example program that creates this file can be downloaded +from the <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page. + +Note that string data requires use of the <code style="background-color:whitesmoke;">h5dump -y</code> +option to exclude indexes and the <code style="background-color:whitesmoke;">h5dump --width=1</code> +option to generate a single column of strings. The <code style="background-color:whitesmoke;">-o</code> +option outputs the data into an ASCII file. +\code +h5dump -p -d "/DS1" -O vlstring.dmp -o vlstring.ascii -y --width=1 h5ex_t_vlstring.h5 +h5import vlstring.ascii -c vlstring.dmp -o new-vlstring.h5 +\endcode + +The output before and after running these commands is shown below: +\code +$ h5dump h5ex_t_vlstring.h5 +HDF5 "h5ex_t_vlstring.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_STRING { + STRSIZE H5T_VARIABLE; + STRPAD H5T_STR_SPACEPAD; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SIMPLE { ( 4 ) / ( 4 ) } + DATA { + (0): "Parting", "is such", "sweet", "sorrow." + } + } +} +} + +$ h5dump -p -d "/DS1" -O vlstring.dmp -o vlstring.ascii -y --width=1 h5ex_t_vlstring.h5 + +$ h5import vlstring.ascii -c vlstring.dmp -o new-vlstring.h5 + +$ h5dump new-vlstring.h5 +HDF5 "new-vlstring.h5" { +GROUP "/" { + DATASET "DS1" { + DATATYPE H5T_STRING { + STRSIZE H5T_VARIABLE; + STRPAD H5T_STR_NULLTERM; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SIMPLE { ( 4 ) / ( 4 ) } + DATA { + (0): "Parting", "is such", "sweet", "sorrow." + } + } +} +\endcode + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand + +*/ diff --git a/doxygen/dox/ViewToolsJPSS.dox b/doxygen/dox/ViewToolsJPSS.dox new file mode 100644 index 0000000..9c15395 --- /dev/null +++ b/doxygen/dox/ViewToolsJPSS.dox @@ -0,0 +1,763 @@ +/** @page ViewToolsJPSS Use Case: Examining a JPSS NPP File With HDF5 Tools +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand +<hr> + +\section secViewToolsJPSSTOC Contents +<ul> +<li>\ref secViewToolsJPSSDeter</li> +<li>\ref secViewToolsJPSSView</li> +<li>\ref secViewToolsJPSSExam</li> +</ul> + +This tutorial illustrates how to use the HDF5 tools to examine NPP files from the JPSS project. The following files are discussed: +\code +SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 (<a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5.gz">gzipped file</a>) +SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 (<a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5.gz">gzipped file</a>) +\endcode + +\section secViewToolsJPSSDeter Determining File Contents +The first thing you may want to do is determine what is in your file. You can use the command-line tools or HDFView to do this: +\li @ref subsecViewToolsJPSSDeter_h5dump +\li @ref subsecViewToolsJPSSDeter_h5ls +\li @ref subsecViewToolsJPSSDeter_HDFView + +JPSS NPP files all contain two root level groups: +<table> +<tr> +<th>Group</th><th>Description</th> +</tr> +<tr> +<td>/All_Data +</td> +<td>Contains the raw data and optional geo-location information. +</td> +</tr> +<tr> +<td>/Data_Products +</td> +<td>Contains a dataset ending in <code style="background-color:whitesmoke;">Aggr</code> with +references to objects in the <code style="background-color:whitesmoke;">/All_Data</code> group. +Contains granules (datasets with a name ending in <code style="background-color:whitesmoke;">Gran_#</code>) +with references to selected regions in datasets under <code style="background-color:whitesmoke;">/All_Data</code>. +</td> +</tr> +</table> + +\subsection subsecViewToolsJPSSDeter_h5dump h5dump +With <code style="background-color:whitesmoke;">h5dump</code> you can see a list of the objects +in the file using the <code style="background-color:whitesmoke;">-n</code> option: +\code +h5dump -n <file> +\endcode + +For example: +\code +$ h5dump -n SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 +HDF5 "SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5" { +FILE_CONTENTS { + group / + group /All_Data + group /All_Data/VIIRS-M9-SDR_All + dataset /All_Data/VIIRS-M9-SDR_All/ModeGran + dataset /All_Data/VIIRS-M9-SDR_All/ModeScan + dataset /All_Data/VIIRS-M9-SDR_All/NumberOfBadChecksums + dataset /All_Data/VIIRS-M9-SDR_All/NumberOfDiscardedPkts + dataset /All_Data/VIIRS-M9-SDR_All/NumberOfMissingPkts + dataset /All_Data/VIIRS-M9-SDR_All/NumberOfScans + dataset /All_Data/VIIRS-M9-SDR_All/PadByte1 + dataset /All_Data/VIIRS-M9-SDR_All/QF1_VIIRSMBANDSDR + dataset /All_Data/VIIRS-M9-SDR_All/QF2_SCAN_SDR + dataset /All_Data/VIIRS-M9-SDR_All/QF3_SCAN_RDR + dataset /All_Data/VIIRS-M9-SDR_All/QF4_SCAN_SDR + dataset /All_Data/VIIRS-M9-SDR_All/QF5_GRAN_BADDETECTOR + dataset /All_Data/VIIRS-M9-SDR_All/Radiance + dataset /All_Data/VIIRS-M9-SDR_All/RadianceFactors + dataset /All_Data/VIIRS-M9-SDR_All/Reflectance + dataset /All_Data/VIIRS-M9-SDR_All/ReflectanceFactors + group /Data_Products + group /Data_Products/VIIRS-M9-SDR + dataset /Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Aggr + dataset /Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0 + dataset /Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_1 + dataset /Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_2 + dataset /Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_3 + } +} +\endcode + +In the output above you can see that there are four granules (ending in +<code style="background-color:whitesmoke;">Gran_#</code>) in the +<code style="background-color:whitesmoke;">/Data_Products/VIIRS-M9-SDR/</code> group. + +\subsection subsecViewToolsJPSSDeter_h5ls h5ls +With <code style="background-color:whitesmoke;">h5ls</code> you can see a list of the objects in the +file using the <code style="background-color:whitesmoke;">-lr</code> +options. The <code style="background-color:whitesmoke;">h5ls</code> utility also shows shape and size +(dataspace) information about datasets. +\code +h5ls -lr <file> +\endcode + +For example: +\code +$ h5ls -lr SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 +/ Group +/All_Data Group +/All_Data/VIIRS-M9-SDR_All Group +/All_Data/VIIRS-M9-SDR_All/ModeGran Dataset {4/Inf} +/All_Data/VIIRS-M9-SDR_All/ModeScan Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/NumberOfBadChecksums Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/NumberOfDiscardedPkts Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/NumberOfMissingPkts Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/NumberOfScans Dataset {4/Inf} +/All_Data/VIIRS-M9-SDR_All/PadByte1 Dataset {12/Inf} +/All_Data/VIIRS-M9-SDR_All/QF1_VIIRSMBANDSDR Dataset {3072/Inf, 3200/Inf} +/All_Data/VIIRS-M9-SDR_All/QF2_SCAN_SDR Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/QF3_SCAN_RDR Dataset {192/Inf} +/All_Data/VIIRS-M9-SDR_All/QF4_SCAN_SDR Dataset {3072/Inf} +/All_Data/VIIRS-M9-SDR_All/QF5_GRAN_BADDETECTOR Dataset {64/Inf} +/All_Data/VIIRS-M9-SDR_All/Radiance Dataset {3072/Inf, 3200/Inf} +/All_Data/VIIRS-M9-SDR_All/RadianceFactors Dataset {8/Inf} +/All_Data/VIIRS-M9-SDR_All/Reflectance Dataset {3072/Inf, 3200/Inf} +/All_Data/VIIRS-M9-SDR_All/ReflectanceFactors Dataset {8/Inf} +/Data_Products Group +/Data_Products/VIIRS-M9-SDR Group +/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Aggr Dataset {16/Inf} +/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0 Dataset {16/Inf} +/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_1 Dataset {16/Inf} +/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_2 Dataset {16/Inf} +/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_3 Dataset {16/Inf} +\endcode +Note that the <code style="background-color:whitesmoke;">Inf</code> indicates that those datasets are appendable or unlimited in size. + +\subsection subsecViewToolsJPSSDeter_HDFView HDFView +If you open the file in HDFView, it will display the file and the root level groups within +it in the TreeView on the left. An HDF5 file is a folder with a "5" in the middle, followed +by the file name. There are two folders (groups) within the JPSS file +(<code style="background-color:whitesmoke;">All_Data/</code> and <code style="background-color:whitesmoke;">Data Products/</code>), +which you can select to see their contents: +<table> +<tr> +<td> +\image html hdfview-tree.png +</td> +</tr> +</table> + +If you click twice with the left-mouse button on a folder or group in the TreeView, the contents +of the folder will be listed. If you click twice on an object such as a dataset, a window with +the object's values will be displayed. + +Underneath the <code style="background-color:whitesmoke;">VIIRS-M1-SDR</code> folder are what HDF5 +calls datasets. The scarlet letter <code style="background-color:whitesmoke;">"A"</code> attached +to the group and datasets under <code style="background-color:whitesmoke;">Data_Products/</code> +indicates that there are attributes associated with them. + +\section secViewToolsJPSSView Viewing the User Block +All JPSS files contain a user block in XML with information about the file. The user block is an +optional space allocated at the beginning of an HDF5 file that is not interpreted by the HDF5 +library. Its size is a multiple of 512. + +Since the user block in JPSS files is stored in ASCII and it is stored at the beginning of an +HDF5 file, you could use a text editor or viewer to examine it. However, there are HDF5 utilities +that can help with this: +<table> +<tr> +<th>Utility</th><th>Description</th> +</tr> +<tr> +<td>h5unjam +</td> +<td>Extracts a user block from an HDF5 file +</td> +</tr> +<tr> +<td>h5dump +</td> +<td>The -B (--superblock) option displays the size of the user block in an HDF5 file +</td> +</tr> +</table> + +\subsection subsecViewToolsJPSSView_h5unjam h5unjam +The \ref secViewToolsEditAdd tutorial topic discusses the use of the +<code style="background-color:whitesmoke;">h5jam</code> and <code style="background-color:whitesmoke;">h5unjam</code> +utilities for adding or removing a user block from a file. An input HDF5 file +(<code style="background-color:whitesmoke;">-i</code>), output HDF5 file +(<code style="background-color:whitesmoke;">-o</code>), and user block text file +(<code style="background-color:whitesmoke;">-u</code>) can be specified with these tools. You can use the +<code style="background-color:whitesmoke;">h5unjam</code> tool to extract and view the user block in a JPSS file: +\code +h5unjam -i <Input HDF5 File> -o <Output HDF5 File> -u <User Block File> +\endcode + +For example this command will extract the user block into the file UB.xml: +\code +$ h5unjam -i SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 + -o svm09-noUB.h5 -u UB.xml +\endcode + +The input HDF5 file remains unchanged. The output HDF5 file will not contain the user block. +The <code style="background-color:whitesmoke;">UB.xml</code> file contains the user block +which can be viewed with a browser. + +\subsection subsecViewToolsJPSSView_h5dump h5dump +The h5dump utility has the <code style="background-color:whitesmoke;">-B (--superblock)</code> option for displaying the superblock in an HDF5 file. +The superblock contains information about the file such as the file signature, file consistency flags, +the number of bytes to store addresses and size of an object, as well as the size of the user block: +\code +h5dump -B (--superblock) +\endcode + +Below is an example (Unix): +\code +$ h5dump -B -H SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 | more +HDF5 "SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5" { +SUPER_BLOCK { + SUPERBLOCK_VERSION 0 + FREELIST_VERSION 0 + SYMBOLTABLE_VERSION 0 + OBJECTHEADER_VERSION 0 + OFFSET_SIZE 8 + LENGTH_SIZE 8 + BTREE_RANK 16 + BTREE_LEAF 4 + ISTORE_K 32 + USER_BLOCK { + USERBLOCK_SIZE 1024 + } +} +\endcode + +Once you have the size of the user block, you can extract it from the file using system commands. +For example, on Unix platforms you can use the head command-line tool: +\code +head -c <USERBLOCK_SIZE> <JPSS File> >& USERBLOCK.xml +\endcode + +There are Unix tools for Windows that may work, such as <a href="http://gnuwin32.sourceforge.net/packages/coreutils.htm">CoreUtils for Windows</a>. + +\section secViewToolsJPSSExam Examining a Granule +<ul> +<li>@ref subsecViewToolsJPSSExam_h5dump<br /> +<ul> +<li>@ref subsubsecViewToolsJPSSExam_h5dumpRegRef</li> +<li>@ref subsubsecViewToolsJPSSExam_h5dumpQuality</li> +<li>@ref subsubsecViewToolsJPSSExam_h5dumpProps</li> +</ul></li> +<li>@ref subsecViewToolsJPSSExamr_HDFView</li> +</ul> + +\subsection subsecViewToolsJPSSExam_h5dump h5dump +There are several options that you may first want to use when examining a granule with h5dump: +<table> +<tr> +<th>Option</th><th>Description</th> +</tr> +<tr> +<td>-H, --header +</td> +<td>Prints header (metadata) information only +</td> +</tr> +<tr> +<td>-d D, --dataset=D +</td> +<td>Specifies the granule dataset +</td> +</tr> +<tr> +<td>-A 0, --onlyattr=0 +</td> +<td>Suppresses attributes +</td> +</tr> +<tr> +<td>-p, --properties +</td> +<td>Show properties of datasets +(See Properties) +</td> +</tr> +</table> + +You would specify the dataset (<code style="background-color:whitesmoke;">-d D</code>) and the +<code style="background-color:whitesmoke;">-H</code> options to view the metadata associated with +a specific granule. There are many attributes associated with a granule and +<code style="background-color:whitesmoke;">-A 0</code> can be used to suppress those. + +For example: +\code +h5dump -H -A 0 -d "/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0" + SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 +\endcode + +This command displays: +\code + HDF5 "SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5" { + DATASET "/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } + } + } +\endcode + +To see the actual contents of the granule remove the <code style="background-color:whitesmoke;">-H</code> option: +\code +h5dump -A 0 -d "/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0" + SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5 +\endcode + +The above command displays: +\code +HDF5 "SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5" { +DATASET "/Data_Products/VIIRS-M9-SDR/VIIRS-M9-SDR_Gran_0" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } + DATA { + DATASET /All_Data/VIIRS-M9-SDR_All/Radiance {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M9-SDR_All/Reflectance {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M9-SDR_All/ModeScan {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/ModeGran {(0)-(0)}, + DATASET /All_Data/VIIRS-M9-SDR_All/PadByte1 {(0)-(2)}, + DATASET /All_Data/VIIRS-M9-SDR_All/NumberOfScans {(0)-(0)}, + DATASET /All_Data/VIIRS-M9-SDR_All/NumberOfMissingPkts {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/NumberOfBadChecksums {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/NumberOfDiscardedPkts {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/QF1_VIIRSMBANDSDR {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M9-SDR_All/QF2_SCAN_SDR {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/QF3_SCAN_RDR {(0)-(47)}, + DATASET /All_Data/VIIRS-M9-SDR_All/QF4_SCAN_SDR {(0)-(767)}, + DATASET /All_Data/VIIRS-M9-SDR_All/QF5_GRAN_BADDETECTOR {(0)-(15)}, + DATASET /All_Data/VIIRS-M9-SDR_All/RadianceFactors {(0)-(1)}, + DATASET /All_Data/VIIRS-M9-SDR_All/ReflectanceFactors {(0)-(1)} + } +} +} +\endcode + +As you can see in the output above, the datatype for this dataset is: +\code +DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } +\endcode + +This indicates that it is a dataset specifically for storing references to regions (or subsets) +in other datasets. The dataset contains 16 such references, and more can be added to it, as +indicated by the dataspace (in other words it is unlimited): +\code +DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } +\endcode + +\subsubsection subsubsecViewToolsJPSSExam_h5dumpRegRef Viewing a Region Reference +What if we wanted to look at the <code style="background-color:whitesmoke;">NumberOfScans</code> data for a specific granule in a file? + +First, we may be interested in determining whether the scans were done at night or in the day. If a scan was at night, there will be no data. + +The attribute <code style="background-color:whitesmoke;">N_Day_Night_Flag</code> is used to determine when the scan was done. If you don't know where this attribute is located, you can use the <code style="background-color:whitesmoke;">-N</code> option to search for it in the file. If you were to run this command on the <code style="background-color:whitesmoke;">SVM09</code> file used above, you would see that the <code style="background-color:whitesmoke;">N_Day_Night_Flag</code> attribute has a value of <code style="background-color:whitesmoke;">Night</code> for the four granules in the file. Indeed, if you actually examine the <code style="background-color:whitesmoke;">NumberOfScans</code> data, you will see that only fill values are written. + +For that reason we will examine the <code style="background-color:whitesmoke;">NumberOfScans</code> data for the <code style="background-color:whitesmoke;">SVMO1</code> file below, as it was obtained during the day: +\code +h5dump -N N_Day_Night_Flag SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +\endcode + +It displays: +\code +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +ATTRIBUTE "N_Day_Night_Flag" { + DATATYPE H5T_STRING { + STRSIZE 4; + STRPAD H5T_STR_NULLTERM; + CSET H5T_CSET_ASCII; + CTYPE H5T_C_S1; + } + DATASPACE SIMPLE { ( 1, 1 ) / ( 1, 1 ) } + DATA { + (0,0): "Day" + } +} +} +\endcode + +There is just one granule in this <code style="background-color:whitesmoke;">SVM01</code> file, as shown below: +\code +$ h5dump -n SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +FILE_CONTENTS { + group / + group /All_Data + group /All_Data/VIIRS-M1-SDR_All + dataset /All_Data/VIIRS-M1-SDR_All/ModeGran + dataset /All_Data/VIIRS-M1-SDR_All/ModeScan + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfBadChecksums + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfDiscardedPkts + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfMissingPkts + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfScans + dataset /All_Data/VIIRS-M1-SDR_All/PadByte1 + dataset /All_Data/VIIRS-M1-SDR_All/QF1_VIIRSMBANDSDR + dataset /All_Data/VIIRS-M1-SDR_All/QF2_SCAN_SDR + dataset /All_Data/VIIRS-M1-SDR_All/QF3_SCAN_RDR + dataset /All_Data/VIIRS-M1-SDR_All/QF4_SCAN_SDR + dataset /All_Data/VIIRS-M1-SDR_All/QF5_GRAN_BADDETECTOR + dataset /All_Data/VIIRS-M1-SDR_All/Radiance + dataset /All_Data/VIIRS-M1-SDR_All/RadianceFactors + dataset /All_Data/VIIRS-M1-SDR_All/Reflectance + dataset /All_Data/VIIRS-M1-SDR_All/ReflectanceFactors + group /Data_Products + group /Data_Products/VIIRS-M1-SDR + dataset /Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Aggr + dataset /Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0 + } +} +\endcode + +Now examine the references in the <code style="background-color:whitesmoke;">VIIRS-M1-SDR_Gran_0</code> granule +\code +$ h5dump -A 0 -d "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" + SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +DATASET "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } + DATA { + DATASET /All_Data/VIIRS-M1-SDR_All/Radiance {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M1-SDR_All/Reflectance {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M1-SDR_All/ModeScan {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/ModeGran {(0)-(0)}, + DATASET /All_Data/VIIRS-M1-SDR_All/PadByte1 {(0)-(2)}, + DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfScans {(0)-(0)}, + DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfMissingPkts {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfBadChecksums {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfDiscardedPkts {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/QF1_VIIRSMBANDSDR {(0,0)-(767,3199)}, + DATASET /All_Data/VIIRS-M1-SDR_All/QF2_SCAN_SDR {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/QF3_SCAN_RDR {(0)-(47)}, + DATASET /All_Data/VIIRS-M1-SDR_All/QF4_SCAN_SDR {(0)-(767)}, + DATASET /All_Data/VIIRS-M1-SDR_All/QF5_GRAN_BADDETECTOR {(0)-(15)}, + DATASET /All_Data/VIIRS-M1-SDR_All/RadianceFactors {(0)-(1)}, + DATASET /All_Data/VIIRS-M1-SDR_All/ReflectanceFactors {(0)-(1)} + } +} +} +\endcode + +In the output above, you can see that the <code style="background-color:whitesmoke;">NumberOfScans</code> +reference is the sixth reference in the granule counting from the top. + +The list of references shown above is a 0-based index to the dataset. Therefore, to specify +<code style="background-color:whitesmoke;">NumberOfScans</code>, enter a start offset of +<code style="background-color:whitesmoke;">5</code> for the <code style="background-color:whitesmoke;">-s</code> +option (the sixth reference minus 1). To see the region reference data, use the <code style="background-color:whitesmoke;">-R</code> option. + +This command will display the data in the <code style="background-color:whitesmoke;">NumberOfScans</code> region reference: +\code +h5dump -A 0 -d "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" -s 5 -R + SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +\endcode + +It displays the number of scans (48): +\code +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +DATASET "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } + SUBSET { + START ( 5 ); + STRIDE ( 1 ); + COUNT ( 1 ); + BLOCK ( 1 ); + DATA { + (5): DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfScans { + (5): REGION_TYPE BLOCK (0)-(0) + (5): DATATYPE H5T_STD_I32BE + (5): DATASPACE SIMPLE { ( 1 ) / ( H5S_UNLIMITED ) } + (5): DATA { + (0): 48 + (5): } + (5): } + } + } +} +} +\endcode + +The <code style="background-color:whitesmoke;">-s</code> option may be familiar as one of the options +that was described in the \ref secViewToolsViewSub tutorial topic. The other subsetting options are not included, +indicating that the default values are used. + +If you leave off the <code style="background-color:whitesmoke;">-R</code> option, you will see the subset selection, but not the data: +\code +$ h5dump -A 0 -d "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" -s 5 + SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +DATASET "/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0" { + DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG } + DATASPACE SIMPLE { ( 16 ) / ( H5S_UNLIMITED ) } + SUBSET { + START ( 5 ); + STRIDE ( 1 ); + COUNT ( 1 ); + BLOCK ( 1 ); + DATA { + DATASET /All_Data/VIIRS-M1-SDR_All/NumberOfScans {(0)-(0)} + } + } +} +} +\endcode + +\subsubsection subsubsecViewToolsJPSSExam_h5dumpQuality Viewing a Quality Flag +The quality flags in an NPP file can be viewed with h5dump using the <code style="background-color:whitesmoke;">-M</code> +option. Quality flags are packed into each integer value in a quality flag dataset. Quality flag datasets in NPP +files begin with the letters <code style="background-color:whitesmoke;">QF</code>. + +In the following NPP file, there are five Quality Flag datasets +(<code style="background-color:whitesmoke;">/All_Data/VIIRS-M1-SDR_All/QF*</code>): +\code +$ h5dump -n SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +FILE_CONTENTS { + group / + group /All_Data + group /All_Data/VIIRS-M1-SDR_All + dataset /All_Data/VIIRS-M1-SDR_All/ModeGran + dataset /All_Data/VIIRS-M1-SDR_All/ModeScan + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfBadChecksums + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfDiscardedPkts + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfMissingPkts + dataset /All_Data/VIIRS-M1-SDR_All/NumberOfScans + dataset /All_Data/VIIRS-M1-SDR_All/PadByte1 + dataset /All_Data/VIIRS-M1-SDR_All/QF1_VIIRSMBANDSDR + dataset /All_Data/VIIRS-M1-SDR_All/QF2_SCAN_SDR + dataset /All_Data/VIIRS-M1-SDR_All/QF3_SCAN_RDR + dataset /All_Data/VIIRS-M1-SDR_All/QF4_SCAN_SDR + dataset /All_Data/VIIRS-M1-SDR_All/QF5_GRAN_BADDETECTOR + dataset /All_Data/VIIRS-M1-SDR_All/Radiance + dataset /All_Data/VIIRS-M1-SDR_All/RadianceFactors + dataset /All_Data/VIIRS-M1-SDR_All/Reflectance + dataset /All_Data/VIIRS-M1-SDR_All/ReflectanceFactors + group /Data_Products + group /Data_Products/VIIRS-M1-SDR + dataset /Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Aggr + dataset /Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0 + } +} +\endcode + +The flags in this particular dataset happen to be stored in every two bits of each quality flag dataset +element, and the values range from 0 to 2. In other words, to see the quality flag values for this +dataset, these bits would be examined: 0 and 1, 2 and 3, 4 and 5, or 6 and 7 (This information was +obtained from the Product Profile XML File.) + +For example, bits 0 and 1 in the <code style="background-color:whitesmoke;">VQF1_VIIRSMBANDSDR</code> dataset specify the flag that +"Indicates calibration quality due to bad space view offsets, OBC view offsets, etc or use of a +previous calibration view". It has 3 values: Good (0), Poor (1), or No Calibration (2). + +The <code style="background-color:whitesmoke;">-M</code> option is used to specify the quality +flag bit offset (<code style="background-color:whitesmoke;">O</code>) and length (<code style="background-color:whitesmoke;">L</code>): +\code +h5dump -d DATASET -M O,L FILE +\endcode + +To view the first quality flag (0-1) in a 5 x 6 subset of the <code style="background-color:whitesmoke;">QF1_VIIRSMBANDSDR</code> dataset, specify: +\code +h5dump -d "/All_Data/VIIRS-M1-SDR_All/QF1_VIIRSMBANDSDR[0,0;;5,6;]" + -M 0,2 SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +\endcode + +This outputs: +\code +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +DATASET "/All_Data/VIIRS-M1-SDR_All/QF1_VIIRSMBANDSDR" { + DATATYPE H5T_STD_U8BE + DATASPACE SIMPLE { ( 768, 3200 ) / ( H5S_UNLIMITED, H5S_UNLIMITED ) } + PACKED_BITS OFFSET=0 LENGTH=2 + SUBSET { + START ( 0, 0 ); + STRIDE ( 1, 1 ); + COUNT ( 5, 6 ); + BLOCK ( 1, 1 ); + DATA { + (0,0): 2, 2, 2, 2, 2, 2, + (1,0): 2, 2, 2, 2, 2, 2, + (2,0): 0, 0, 0, 0, 0, 0, + (3,0): 0, 0, 0, 0, 0, 0, + (4,0): 0, 0, 0, 0, 0, 0 + } + } +} +} +\endcode + +To view more than one quality flag at a time simply add the bit offset and length values to +<code style="background-color:whitesmoke;">-M</code>, separated by commas. For example, this +<code style="background-color:whitesmoke;">-M</code> option specifies bits 0-1 and 2-3: +\code +h5dump -d DATASET -M 0,2,2,2 FILE +\endcode + +\subsubsection subsubsecViewToolsJPSSExam_h5dumpProps Properties +To view properties of a specific dataset with <code style="background-color:whitesmoke;">h5dump</code> +use the <code style="background-color:whitesmoke;">-p</code> option along with the +<code style="background-color:whitesmoke;">-d</code> option. Depending on the number of attributes +and the amount of data, the <code style="background-color:whitesmoke;">-A 0</code> and +<code style="background-color:whitesmoke;">-H</code> options can also be specified to suppress +printing of attributes and data values: +\code +h5dump -p -H -A 0 -d DATASET +\endcode + +The <code style="background-color:whitesmoke;">-p</code> option shows any compression filters +associated with a dataset, as well as layout and fill value information. This option can be helpful +in diagnosing performance and other issues. + +As an example, examine the <code style="background-color:whitesmoke;">/All_Data/VIIRS-M1-SDR_All/Radiance</code> +dataset in the <code style="background-color:whitesmoke;">SVM01</code> file: +\code +$ h5dump -p -H -A 0 -d "/All_Data/VIIRS-M1-SDR_All/Radiance" + SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +HDF5 "SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5" { +DATASET "/All_Data/VIIRS-M1-SDR_All/Radiance" { + DATATYPE H5T_STD_U16BE + DATASPACE SIMPLE { ( 768, 3200 ) / ( H5S_UNLIMITED, H5S_UNLIMITED ) } + STORAGE_LAYOUT { + CHUNKED ( 768, 3200 ) + SIZE 4915200 + } + FILTERS { + NONE + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 65529 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_INCR + } +} +} +\endcode + +We can see that the chunk size for this dataset is 768 x 3200, and the storage size is 4915200. + +What if the chunk size were smaller? + +The dataset was modified to have a chunk size of 1 x 10, using the +<code style="background-color:whitesmoke;">h5repack</code> utility, as shown below. +\code +$ h5repack -l /All_Data/VIIRS-M1-SDR_All/Radiance:CHUNK=1x10 + SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 SVM01repack.h5 + +$ h5dump -p -H -A 0 -d "/All_Data/VIIRS-M1-SDR_All/Radiance" SVM01repack.h5 +HDF5 "SVM01repack.h5" { +DATASET "/All_Data/VIIRS-M1-SDR_All/Radiance" { + DATATYPE H5T_STD_U16BE + DATASPACE SIMPLE { ( 768, 3200 ) / ( H5S_UNLIMITED, H5S_UNLIMITED ) } + STORAGE_LAYOUT { + CHUNKED ( 1, 10 ) + SIZE 4915200 + } + FILTERS { + NONE + } + FILLVALUE { + FILL_TIME H5D_FILL_TIME_IFSET + VALUE 65529 + } + ALLOCATION_TIME { + H5D_ALLOC_TIME_INCR + } +} +} +\endcode + +In this case, the storage size of the dataset is the same, but the size of the file almost doubled!: +\code +$ ls -1sh +total 35M +12M SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5 +23M SVM01repack.h5 +\endcode + +In general, the smaller the chunk size, the more chunks that HDF5 has to keep track of, which increases +the size of the file and can affect performance. + +\subsection subsecViewToolsJPSSExamr_HDFView HDFView +As mentioned previously, the structure of an HDF5 file is displayed in the TreeView on the left side of the HDFView screen, +and you can click on objects and have metadata information displayed on the right side. + +To discover more about the granule <code style="background-color:whitesmoke;">/Data_Products/VIIRS-M1-SDR/VIIRS-M1-SDR_Gran_0</code> +in the <code style="background-color:whitesmoke;">SVM01</code> file shown below in the TreeView, position +the mouse over the granule and click to select. Properties for the object is displayed on the right side of the HDFView screen. +You can see Datatype and Dataspace information on the <code style="background-color:whitesmoke;">General Object Info</code> +tab, any Attributes associated with the granulewill be on the +<code style="background-color:whitesmoke;">Object Attribute Info</code> tab. In the +<code style="background-color:whitesmoke;">General Object Info</code>, you can see that the dataset is a +Region Reference dataset, and that there are sixteen Region References in this dataset: +<table> +<tr> +<td> +\image html hdfview-prop.png +</td> +</tr> +</table> + +To examine the data in the granule, click twice on it with the left mouse button in the TreeView, +and it will open in a new window.: +<table> +<tr> +<td> +\image html hdfview-regref.png +</td> +</tr> +</table> + +If you click twice with the left mouse button on the fifth Region Reference +<code style="background-color:whitesmoke;">/All_Data/VIIRS-M1-SDR_All/NumberOfScans</code> a window +will pop up with the value(s) of the reference: +<table> +<tr> +<td> +\image html hdfview-regref2.png +</td> +</tr> +</table> + +You can also set a user option to automatically show the value(s) in a Region Reference. Under the +<code style="background-color:whitesmoke;">Tools</code> pull-down menu, select +<code style="background-color:whitesmoke;">User Options</code> and then select +<code style="background-color:whitesmoke;">HDF Settings</code> and then select +<code style="background-color:whitesmoke;">Show RegRef Values</code> in the +<code style="background-color:whitesmoke;">Data</code> section (see the middle of the image below): +<table> +<tr> +<td> +\image html hdfview-regrefval.png +</td> +</tr> +</table> + +Then you will automatically see the values of the Region Reference when you open it and select an entry: +<table> +<tr> +<td> +\image html hdfview-regref1.png +</td> +</tr> +</table> + +You can view and set quality flags by clicking the right mouse button over a quality flags dataset under +<code style="background-color:whitesmoke;">All_Data</code> and selecting +<code style="background-color:whitesmoke;">Open As</code> from the pop-up menu. In the middle of +the window that pops up, you will see where you can specify <code style="background-color:whitesmoke;">Bitmask</code> options. +<table> +<tr> +<td> +\image html hdfview-qf.png +</td> +</tr> +</table> + +<hr> +Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand + +*/ diff --git a/doxygen/dox/high_level/extension.dox b/doxygen/dox/high_level/extension.dox index c81ac6e..d754b96 100644 --- a/doxygen/dox/high_level/extension.dox +++ b/doxygen/dox/high_level/extension.dox @@ -1,60 +1,51 @@ /** \defgroup H5LR Extensions * - * <em>Working with region references, hyperslab selections, + * <em>Working with region references, hyperslab selections, * and bit-fields (H5LR, H5LT)</em> * - * The following reference manual entries describe high-level HDF5 C and Fortran APIs - * for working with region references, hyperslab selections, and bit-fields. - * These functions were created as part of a project supporting + * The following reference manual entries describe high-level HDF5 C and Fortran APIs + * for working with region references, hyperslab selections, and bit-fields. + * These functions were created as part of a project supporting * NPP/NPOESS Data Production and Exploitation ( * <a href="https://support.hdfgroup.org/projects/jpss/documentation"> - * project </a>, - * <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> - * software </a>). - * While they were written to facilitate access to NPP, NPOESS, and JPSS - * data in the HDF5 format, these functions may be useful to anyone working + * project</a>, <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> + * software </a>). + * While they were written to facilitate access to NPP, NPOESS, and JPSS + * data in the HDF5 format, these functions may be useful to anyone working * with region references, hyperslab selections, or bit-fields. * * Note that these functions are not part of the standard HDF5 distribution; - * the - * <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> - * software </a> + * the <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> + * software </a> * must be separately downloaded and installed. * - * A comprehensive guide to this library, - * <a href="https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf"> + * A comprehensive guide to this library, + * <a href="https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf"> * <em>User Guide to the HDF5 High-level Library for Handling Region References and Hyperslab Selections</em></a> - * is available at + * is available at * https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf. * * - \ref H5LRcopy_reference - * \n Copies data from the specified dataset to a new location and - * creates a reference to it. + * \n Copies data from the specified dataset to a new location and creates a reference to it. * - \ref H5LRcopy_region - * \n Copies data from a referenced region to a region in a - * destination dataset. + * \n Copies data from a referenced region to a region in a destination dataset. * - \ref H5LRcreate_ref_to_all - * \n Creates a dataset with the region references to the data in all - * datasets located under a specified group in a file or creates a - * dataset with object references to all objects (groups or datasets) + * \n Creates a dataset with the region references to the data in all datasets located under a + * specified group in a file or creates a dataset with object references to all objects (groups or datasets) * located under a specified group in a file. * - \ref H5LRcreate_region_references - * \n Creates an array of region references using an array of paths to + * \n Creates an array of region references using an array of paths to * datasets and an array of corresponding hyperslab descriptions. * - \ref H5LRget_region_info * \n Retrieves information about the data a region reference points to. * - \ref H5LRmake_dataset - * \n Creates and writes a dataset containing a list of - * region references. + * \n Creates and writes a dataset containing a list of region references. * - \ref H5LRread_region - * \n Retrieves raw data pointed to by a region reference to - * an application buffer. + * \n Retrieves raw data pointed to by a region reference to an application buffer. * - \ref H5LTcopy_region - * \n Copies data from a specified region in a source dataset - * to a specified region in a destination dataset. + * \n Copies data from a specified region in a source dataset to a specified region in a destination dataset. * - \ref H5LTread_bitfield_value - * \n Retrieves the values of quality flags for each element - * to the application provided buffer. + * \n Retrieves the values of quality flags for each element to the application provided buffer. * - \ref H5LTread_region * \n Reads selected data to an application buffer. * @@ -77,24 +68,24 @@ * \param[in] path Path to the dataset being created * \param[in] type_id Datatype of the dataset * \param[in] buf_size Size of the \p loc_id_ref and \p buf arrays - * \param[in] loc_id_ref Array of object identifiers; each identifier - * describes to which HDF5 file the corresponding + * \param[in] loc_id_ref Array of object identifiers; each identifier + * describes to which HDF5 file the corresponding * region reference belongs to * \param[in] buf Array of region references * * \return \herr_t * - * \details Given an array of size \p buf_size of region references \p buf, - * the function will create a dataset with path \p path, at location - * specified by \p loc_id and of a datatype specified by \p type_id, - * and will write data associated with each region reference in the order - * corresponding to the order of the region references in the buffer. - * It is assumed that all referenced hyperslabs have the same dimensionality, - * and only the size of the slowest changing dimension may differ. - * Each reference in the \p buf array belongs to the file identified + * \details Given an array of size \p buf_size of region references \p buf, + * the function will create a dataset with path \p path, at location + * specified by \p loc_id and of a datatype specified by \p type_id, + * and will write data associated with each region reference in the order + * corresponding to the order of the region references in the buffer. + * It is assumed that all referenced hyperslabs have the same dimensionality, + * and only the size of the slowest changing dimension may differ. + * Each reference in the \p buf array belongs to the file identified * by the corresponding object identifiers in the array \p loc_id_ref. * - * If \p path does not exist in \p loc_id then the function will + * If \p path does not exist in \p loc_id then the function will * create the path specified by \p path automatically. * * \version 1.1 Fortran wrapper introduced in this release. @@ -103,10 +94,10 @@ * */ H5_HLRDLL herr_t H5LRmake_dataset(hid_t loc_id, - const char *path, - hid_t type_id, const size_t buf_size, - const hid_t *loc_id_ref, - const hdset_reg_ref_t *buf); + const char *path, + hid_t type_id, const size_t buf_size, + const hid_t *loc_id_ref, + const hdset_reg_ref_t *buf); /*------------------------------------------------------------------------- * @@ -119,49 +110,46 @@ H5_HLRDLL herr_t H5LRmake_dataset(hid_t loc_id, * -------------------------------------------------------------------------- * \ingroup H5LR * - * \brief Creates an array of region references using an array of paths to + * \brief Creates an array of region references using an array of paths to * datasets and an array of corresponding hyperslab descriptions. * * \param[in] obj_id File identifier for the HDF5 file containing * the referenced regions or an object identifier * for any object in that file - * \param[in] num_elem Number of elements in the \p path and - * \p buf arrays - * \param[in] path Array of pointers to strings, which contain - * the paths to the target datasets for the - * region references + * \param[in] num_elem Number of elements in the \p path and \p buf arrays + * \param[in] path Array of pointers to strings, which contain + * the paths to the target datasets for the region references * \param[in] block_coord Array of hyperslab coordinate - * \param[out] buf Buffer for returning an array of region - * references + * \param[out] buf Buffer for returning an array of region references * * \return \herr_t * * \note **Motivation:** - * \note H5LRcreate_region_references() is useful when creating + * \note H5LRcreate_region_references() is useful when creating * large numbers of similar region references. * - * \details H5LRcreate_region_references() creates a list of region references - * given an array of paths to datasets and another array listing the + * \details H5LRcreate_region_references() creates a list of region references + * given an array of paths to datasets and another array listing the * corner coordinates of the corresponding hyperslabs. * * \p path parameter is an array of pointers to strings. * - * \p num_elem specifies the number of region references to be created, + * \p num_elem specifies the number of region references to be created, * thus specifying the size of the \p path and \p _buf arrays. * - * Buffer \p block_coord has size 2*rank and is the coordinates of the - * starting point following by the coordinates of the ending point of - * the hyperslab, repeated \p num_elem times for each hyperslab. - * For example, creating two region references to two hyperslabs, - * one with a rectangular hyperslab region starting at element (2,2) - * to element (5,4) and the second rectangular region starting at - * element (7,7) to element (9,10), results in \p block_coord + * Buffer \p block_coord has size 2*rank and is the coordinates of the + * starting point following by the coordinates of the ending point of + * the hyperslab, repeated \p num_elem times for each hyperslab. + * For example, creating two region references to two hyperslabs, + * one with a rectangular hyperslab region starting at element (2,2) + * to element (5,4) and the second rectangular region starting at + * element (7,7) to element (9,10), results in \p block_coord * being {2,2,5,4, 7,7,9,10}. * - * The rank of the hyperslab will be the same as the rank of the - * target dataset. H5LRcreate_region_references() will retrieve - * the rank for each dataset and will use those values to interpret - * the values in the buffer. Please note that rank may vary from one + * The rank of the hyperslab will be the same as the rank of the + * target dataset. H5LRcreate_region_references() will retrieve + * the rank for each dataset and will use those values to interpret + * the values in the buffer. Please note that rank may vary from one * dataset to another. * * \version 1.1 Fortran wrapper introduced in this release. @@ -170,43 +158,39 @@ H5_HLRDLL herr_t H5LRmake_dataset(hid_t loc_id, * */ H5_HLRDLL herr_t H5LRcreate_region_references(hid_t obj_id, - size_t num_elem, - const char **path, - const hsize_t *block_coord, - hdset_reg_ref_t *buf); + size_t num_elem, + const char **path, + const hsize_t *block_coord, + hdset_reg_ref_t *buf); /** * -------------------------------------------------------------------------- * \ingroup H5LR * - * \brief Copies data from the specified dataset to a new location and - * creates a reference to it. + * \brief Copies data from the specified dataset to a new location and creates a reference to it. * - * \param[in] obj_id Identifier of any object in a file an - * HDF5 reference belongs to + * \param[in] obj_id Identifier of any object in a file an HDF5 reference belongs to * \param[in] ref Reference to the datasets region - * \param[in] file Name of the destination file + * \param[in] file Name of the destination file * \param[in] path Full path to the destination dataset - * \param[in] block_coord Hyperslab coordinates in the destination - * dataset - * \param[out] ref_new Region reference to the new location of - * data + * \param[in] block_coord Hyperslab coordinates in the destination dataset + * \param[out] ref_new Region reference to the new location of data * * \return \herr_t * - * \details Given a data set pointed to by a region reference, the function - * H5LRcopy_reference() will copy the hyperslab data referenced by - * a datasets region reference into existing dataset specified by - * its path \p path in the file with the name \p file, and to location - * specified by the hyperslab coordinates \p block_coord. It will - * create the region reference \p ref_new to point to the new location. - * The number of elements in the old and newly specified regions has + * \details Given a data set pointed to by a region reference, the function + * H5LRcopy_reference() will copy the hyperslab data referenced by + * a datasets region reference into existing dataset specified by + * its path \p path in the file with the name \p file, and to location + * specified by the hyperslab coordinates \p block_coord. It will + * create the region reference \p ref_new to point to the new location. + * The number of elements in the old and newly specified regions has * to be the same. * - * Buffer \p block_coord has size 2*rank and is the coordinates of - * the starting point following by the coordinates of the ending - * point of the hyperslab. For example, to extract a rectangular - * hyperslab region starting at element (2,2) to element (5,4) + * Buffer \p block_coord has size 2*rank and is the coordinates of + * the starting point following by the coordinates of the ending + * point of the hyperslab. For example, to extract a rectangular + * hyperslab region starting at element (2,2) to element (5,4) * then \p block_coord would be {2, 2, 5, 4}. * * \version 1.1 Fortran wrapper introduced in this release. @@ -215,41 +199,39 @@ H5_HLRDLL herr_t H5LRcreate_region_references(hid_t obj_id, * */ H5_HLRDLL herr_t H5LRcopy_reference(hid_t obj_id, hdset_reg_ref_t *ref, const char *file, - const char *path, const hsize_t *block_coord, - hdset_reg_ref_t *ref_new); + const char *path, const hsize_t *block_coord, + hdset_reg_ref_t *ref_new); /** * -------------------------------------------------------------------------- * \ingroup H5LR * - * \brief Copies data from a referenced region to a region in a - * destination dataset. + * \brief Copies data from a referenced region to a region in a destination dataset. * - * \param[in] obj_id Identifier of any object in a file + * \param[in] obj_id Identifier of any object in a file * dataset region reference belongs to * \param[in] ref Dataset region reference - * \param[in] file Name of the destination file + * \param[in] file Name of the destination file * \param[in] path Full path to the destination dataset - * \param[in] block_coord Hyperslab coordinates in the destination - * dataset + * \param[in] block_coord Hyperslab coordinates in the destination dataset * * \return \herr_t * - * \details Given a dataset region reference \p ref in a source file - * specified by an identifier of any object in that file - * \p obj_id, the function will write data to the existing - * dataset \p path in file \p file to the simple hyperslab + * \details Given a dataset region reference \p ref in a source file + * specified by an identifier of any object in that file + * \p obj_id, the function will write data to the existing + * dataset \p path in file \p file to the simple hyperslab * specified by \p block_coord. * - * Buffer \p block_coord has size 2*rank and is the coordinates - * of the starting point following by the coordinates of the - * ending point of the hyperslab. For example, to specify a - * rectangular hyperslab destination region starting at element + * Buffer \p block_coord has size 2*rank and is the coordinates + * of the starting point following by the coordinates of the + * ending point of the hyperslab. For example, to specify a + * rectangular hyperslab destination region starting at element * (2,2) to element (5,4) then \p block_coord would be {2, 2, 5, 4}. * - * If \p path does not exist in the destination file (as may be - * the case when writing to a new file) then the dataset will be - * copied directly to the \p path and \p block_coord will be + * If \p path does not exist in the destination file (as may be + * the case when writing to a new file) then the dataset will be + * copied directly to the \p path and \p block_coord will be * disregarded. * * \version 1.1 Fortran wrapper introduced in this release. @@ -258,71 +240,66 @@ H5_HLRDLL herr_t H5LRcopy_reference(hid_t obj_id, hdset_reg_ref_t *ref, const ch * */ H5_HLRDLL herr_t H5LRcopy_region(hid_t obj_id, - hdset_reg_ref_t *ref, - const char *file, - const char *path, - const hsize_t *block_coord); + hdset_reg_ref_t *ref, + const char *file, + const char *path, + const hsize_t *block_coord); /** * -------------------------------------------------------------------------- * \ingroup H5LR * - * \brief Creates a dataset with the region references to the data - * in all datasets located under a specified group in a file - * or creates a dataset with object references to all objects + * \brief Creates a dataset with the region references to the data + * in all datasets located under a specified group in a file + * or creates a dataset with object references to all objects * (groups or datasets) located under a specified group in a file. * * \fg_loc_id - * \param[in] group_path Absolute or relative path to the group - * at which traversal starts - * \param[in] ds_path Absolute or relative path to the dataset - * with region references to be created - * \param[in] index_type Index_type; - * see valid values below in description - * \param[in] order Order in which index is traversed; - * see valid values below in description - * \param[in] ref_type Reference type; - * see valid values below in description + * \param[in] group_path Absolute or relative path to the group at which traversal starts + * \param[in] ds_path Absolute or relative path to the dataset with region references to be created + * \param[in] index_type Index_type; see valid values below in description + * \param[in] order Order in which index is traversed; see valid values below in description + * \param[in] ref_type Reference type; see valid values below in description * * \return \herr_t * - * \details H5LRcreate_ref_to_all() creates a dataset with the - * region references to the data in all datasets located - * under a specified group in a file or creates a dataset with - * object references to all objects (groups or datasets) located + * \details H5LRcreate_ref_to_all() creates a dataset with the + * region references to the data in all datasets located + * under a specified group in a file or creates a dataset with + * object references to all objects (groups or datasets) located * under a specified group in a file. * - * Given a dataset path \p ds_path in a file specified by the - * \p loc_id identifier, the function H5LRcreate_ref_to_all() - * will create a contiguous one-dimensional dataset with the - * region references or object references depending on the value - * of the \p ref_type parameter. When \p ref_type is - * #H5R_DATASET_REGION, each region reference points to all data - * in a dataset encountered by an internally called H5Lvisit() - * routine, which starts at the group specified by the \p loc_id + * Given a dataset path \p ds_path in a file specified by the + * \p loc_id identifier, the function H5LRcreate_ref_to_all() + * will create a contiguous one-dimensional dataset with the + * region references or object references depending on the value + * of the \p ref_type parameter. When \p ref_type is + * #H5R_DATASET_REGION, each region reference points to all data + * in a dataset encountered by an internally called H5Lvisit() + * routine, which starts at the group specified by the \p loc_id * and \p group_path parameters. In a like manner, when - * \p ref_type is #H5R_OBJECT, each object reference points to + * \p ref_type is #H5R_OBJECT, each object reference points to * an object (a group or a dataset) encountered by H5Lvisit(). * - * If \p ds_path does not exist in \p loc_id then the function + * If \p ds_path does not exist in \p loc_id then the function * will create the path specified by \p ds_path automatically. * - * \p index_type specifies the index to be used. + * \p index_type specifies the index to be used. * Valid values include the following: * - #H5_INDEX_NAME Alphanumeric index on name * - #H5_INDEX_CRT_ORDER Index on creation order * - * \p order specifies the order in which objects are to be - * inspected along the index specified in \p index_type. + * \p order specifies the order in which objects are to be + * inspected along the index specified in \p index_type. * Valid values include the following: * - #H5_ITER_INC Increasing order * - #H5_ITER_DEC Decreasing order * - #H5_ITER_NATIVE Fastest available order * - * For more detailed information on these two parameters, - * see H5Lvisit(). + * For more detailed information on these two parameters, + * @see H5Lvisit(). * - * \p ref_type specifies the type of the reference to be used. + * \p ref_type specifies the type of the reference to be used. * Valid values include the following: * - #H5R_DATASET_REGION Dataset region reference * - #H5R_OBJECT Object reference @@ -333,7 +310,7 @@ H5_HLRDLL herr_t H5LRcopy_region(hid_t obj_id, * */ H5_HLRDLL herr_t H5LRcreate_ref_to_all(hid_t loc_id, const char *group_path, - const char *ds_path, H5_index_t index_type, H5_iter_order_t order, H5R_type_t ref_type); + const char *ds_path, H5_index_t index_type, H5_iter_order_t order, H5R_type_t ref_type); /*------------------------------------------------------------------------- * @@ -352,30 +329,27 @@ H5_HLRDLL herr_t H5LRcreate_ref_to_all(hid_t loc_id, const char *group_path, * \param[in] obj_id File identifier for the HDF5 file containing * the dataset with the referenced region or an * object identifier for any object in that file - * \param[in] ref Region reference specifying data to be read - * in - * \param[in] mem_type Memory datatype of data read from referenced + * \param[in] ref Region reference specifying data to be read in + * \param[in] mem_type Memory datatype of data read from referenced * region into the application buffer - * \param[in,out] numelem Number of elements to be read into buffer - * \p buf - * \param[out] buf Buffer in which data is returned to the - * application + * \param[in,out] numelem Number of elements to be read into buffer \p buf + * \param[out] buf Buffer in which data is returned to the application * * \return \herr_t * - * \details H5LRread_region() reads data pointed to by the region + * \details H5LRread_region() reads data pointed to by the region * reference \p ref into the buffer \p buf. * - * \p numelem specifies the number of elements to be read - * into \p buf. When the size of the reference region is unknown, - * H5LRread_region() can be called with \p buf set to NULL; - * the number of elements in the referenced region will be returned + * \p numelem specifies the number of elements to be read + * into \p buf. When the size of the reference region is unknown, + * H5LRread_region() can be called with \p buf set to NULL; + * the number of elements in the referenced region will be returned * in \p numelem. * - * The buffer buf must be big enough to hold \p numelem elements - * of type \p mem_type. For example, if data is read from the referenced - * region into an integer buffer, \p mem_type should be #H5T_NATIVE_INT - * and the buffer must be at least \c sizeof(int) * \p numelem bytes + * The buffer buf must be big enough to hold \p numelem elements + * of type \p mem_type. For example, if data is read from the referenced + * region into an integer buffer, \p mem_type should be #H5T_NATIVE_INT + * and the buffer must be at least \c sizeof(int) * \p numelem bytes * in size. This buffer must be allocated by the application. * * \version 1.1 Fortran wrapper introduced in this release. @@ -384,10 +358,10 @@ H5_HLRDLL herr_t H5LRcreate_ref_to_all(hid_t loc_id, const char *group_path, * */ H5_HLRDLL herr_t H5LRread_region(hid_t obj_id, - const hdset_reg_ref_t *ref, - hid_t mem_type, - size_t *numelem, - void *buf ); + const hdset_reg_ref_t *ref, + hid_t mem_type, + size_t *numelem, + void *buf ); /*------------------------------------------------------------------------- * @@ -400,40 +374,33 @@ H5_HLRDLL herr_t H5LRread_region(hid_t obj_id, * -------------------------------------------------------------------------- * \ingroup H5LR * - * \brief Retrieves information about the data a region reference - * points to. + * \brief Retrieves information about the data a region reference points to. * - * \param[in] obj_id Identifier of any object in an HDF5 file - * the region reference belongs to. + * \param[in] obj_id Identifier of any object in an HDF5 file the region reference belongs to. * \param[in] ref Region reference to query - * \param[in,out] len Size of the buffer to store \p path in. - * NOTE: if \p *path is not NULL then \p *len - * must be the appropriate length + * \param[in,out] len Size of the buffer to store \p path in. + * NOTE: if \p *path is not NULL then \p *len must be the appropriate length * \param[out] path Full path that a region reference points to * \param[out] rank The number of dimensions of the dataset - * dimensions of the dataset pointed by - * region reference. - * \param[out] dtype Datatype of the dataset pointed by the - * region reference. + * dimensions of the dataset pointed by region reference. + * \param[out] dtype Datatype of the dataset pointed by the region reference. * \param[out] sel_type Type of the selection (point or hyperslab) - * \param[in,out] numelem Number of coordinate blocks or - * selected elements. - * \param[out] buf Buffer containing description of the region - * pointed by region reference + * \param[in,out] numelem Number of coordinate blocks or selected elements. + * \param[out] buf Buffer containing description of the region pointed by region reference * * \return \herr_t * - * \details H5LRget_region_info() queries information about the data - * pointed by a region reference \p ref. It returns one of the - * absolute paths to a dataset, length of the path, dataset’s rank - * and datatype, description of the referenced region and type of - * the referenced region. Any output argument can be NULL if that + * \details H5LRget_region_info() queries information about the data + * pointed by a region reference \p ref. It returns one of the + * absolute paths to a dataset, length of the path, dataset’s rank + * and datatype, description of the referenced region and type of + * the referenced region. Any output argument can be NULL if that * argument does not need to be returned. * - * The parameter \p obj_id is an identifier for any object in the - * HDF5 file containing the referenced object. For example, it can - * be an identifier of a dataset the region reference belongs to - * or an identifier of an HDF5 file the dataset with region references + * The parameter \p obj_id is an identifier for any object in the + * HDF5 file containing the referenced object. For example, it can + * be an identifier of a dataset the region reference belongs to + * or an identifier of an HDF5 file the dataset with region references * is stored in. * * The parameter \p ref is a region reference to query. @@ -442,36 +409,36 @@ H5_HLRDLL herr_t H5LRread_region(hid_t obj_id, * buffer of size \p len+1 to return an absolute path to a dataset * the region reference points to. * - * The parameter \p len is a length of absolute path string plus - * the \0 string terminator. If path parameter is NULL, actual - * length of the path (+1 for \0 string terminator) is returned to - * application and can be used to allocate buffer path of an + * The parameter \p len is a length of absolute path string plus + * the \0 string terminator. If path parameter is NULL, actual + * length of the path (+1 for \0 string terminator) is returned to + * application and can be used to allocate buffer path of an * appropriate length \p len. * * The parameter \p sel_type describes the type of the selected - * region. Possible values can be #H5S_SEL_POINTS for point + * region. Possible values can be #H5S_SEL_POINTS for point * selection and #H5S_SEL_HYPERSLABS for hyperslab selection. * - * The parameter \p numelem describes how many elements will be - * placed in the buffer \p buf. The number should be interpreted + * The parameter \p numelem describes how many elements will be + * placed in the buffer \p buf. The number should be interpreted * using the value of \p sel_type. * - * If value of \p sel_type is #H5S_SEL_HYPERSLABS, the parameter - * \p buf contains \p numelem blocks of the coordinates for each - * simple hyperslab of the referenced region. Each block has - * length \c 2*\p rank and is organized as follows: <"start" coordinate>, - * immediately followed by <"opposite" corner coordinate>. - * The total size of the buffer to hold the description of the - * region will be \c 2*\p rank*\p numelem. If region reference - * points to a contiguous sub-array, then the value of \p numelem - * is 1 and the block contains coordinates of the upper left and + * If value of \p sel_type is #H5S_SEL_HYPERSLABS, the parameter + * \p buf contains \p numelem blocks of the coordinates for each + * simple hyperslab of the referenced region. Each block has + * length \c 2*\p rank and is organized as follows: <"start" coordinate>, + * immediately followed by <"opposite" corner coordinate>. + * The total size of the buffer to hold the description of the + * region will be \c 2*\p rank*\p numelem. If region reference + * points to a contiguous sub-array, then the value of \p numelem + * is 1 and the block contains coordinates of the upper left and * lower right corners of the sub-array (or simple hyperslab). * - * If value of \p sel_type is #H5S_SEL_POINTS, the parameter \p buf - * contains \p numelem blocks of the coordinates for each selected - * point of the referenced region. Each block has length \p rank - * and contains coordinates of the element. The total size of the - * buffer to hold the description of the region will be + * If value of \p sel_type is #H5S_SEL_POINTS, the parameter \p buf + * contains \p numelem blocks of the coordinates for each selected + * point of the referenced region. Each block has length \p rank + * and contains coordinates of the element. The total size of the + * buffer to hold the description of the region will be * \p rank* \p numelem. * * @@ -481,14 +448,14 @@ H5_HLRDLL herr_t H5LRread_region(hid_t obj_id, * */ H5_HLRDLL herr_t H5LRget_region_info(hid_t obj_id, - const hdset_reg_ref_t *ref, - size_t *len, - char *path, - int *rank, - hid_t *dtype, - H5S_sel_type *sel_type, - size_t *numelem, - hsize_t *buf ); + const hdset_reg_ref_t *ref, + size_t *len, + char *path, + int *rank, + hid_t *dtype, + H5S_sel_type *sel_type, + size_t *numelem, + hsize_t *buf ); @@ -503,35 +470,33 @@ H5_HLRDLL herr_t H5LRget_region_info(hid_t obj_id, * -------------------------------------------------------------------------- * \ingroup H5LR * - * \brief Copies data from a specified region in a source dataset + * \brief Copies data from a specified region in a source dataset * to a specified region in a destination dataset * * \param[in] file_src Name of the source file * \param[in] path_src Full path to the source dataset - * \param[in] block_coord_src Hyperslab coordinates in the - * source dataset + * \param[in] block_coord_src Hyperslab coordinates in the source dataset * \param[in] file_dest Name of the destination file * \param[in] path_dest Full path to the destination dataset - * \param[in] block_coord_dset Hyperslab coordinates in the - * destination dataset + * \param[in] block_coord_dset Hyperslab coordinates in the destination dataset * * \return \herr_t * - * \details Given a path to a dataset \p path_src in a file with the - * name \p file_src, and description of a simple hyperslab of - * the source \p block_coord_src, the function will write data - * to the dataset \p path_dest in file \p file_dest to the - * simple hyperslab specified by \p block_coord_dset. - * The arrays \p block_coord_src and \p block_coord_dset have - * a length of 2*rank and are the coordinates of the starting - * point following by the coordinates of the ending point of the - * hyperslab. For example, to specify a rectangular hyperslab - * destination region starting at element (2,2) to element (5,4) + * \details Given a path to a dataset \p path_src in a file with the + * name \p file_src, and description of a simple hyperslab of + * the source \p block_coord_src, the function will write data + * to the dataset \p path_dest in file \p file_dest to the + * simple hyperslab specified by \p block_coord_dset. + * The arrays \p block_coord_src and \p block_coord_dset have + * a length of 2*rank and are the coordinates of the starting + * point following by the coordinates of the ending point of the + * hyperslab. For example, to specify a rectangular hyperslab + * destination region starting at element (2,2) to element (5,4) * then \p block_coord_dset would be {2, 2, 5, 4}. * - * If \p path_dest does not exist in the destination file - * (as may be the case when writing to a new file) then the - * dataset will be copied directly to the \p path_dest and + * If \p path_dest does not exist in the destination file + * (as may be the case when writing to a new file) then the + * dataset will be copied directly to the \p path_dest and * \p block_coord_dset will be disregarded. * * \version 1.1 Fortran wrapper introduced in this release. @@ -540,11 +505,11 @@ H5_HLRDLL herr_t H5LRget_region_info(hid_t obj_id, * */ H5_HLRDLL herr_t H5LTcopy_region(const char *file_src, - const char *path_src, - const hsize_t *block_coord_src, - const char *file_dest, - const char *path_dest, - const hsize_t *block_coord_dset); + const char *path_src, + const hsize_t *block_coord_src, + const char *file_dest, + const char *path_dest, + const hsize_t *block_coord_dset); /*------------------------------------------------------------------------- * @@ -562,27 +527,25 @@ H5_HLRDLL herr_t H5LTcopy_region(const char *file_src, * \param[in] file Name of file * \param[in] path Full path to a dataset * \param[in] block_coord Hyperslab coordinates - * \param[in] mem_type Memory datatype, describing the buffer - * the referenced data will be read into - * \param[out] buf Buffer containing data from the - * referenced region + * \param[in] mem_type Memory datatype, describing the buffer the referenced data will be read into + * \param[out] buf Buffer containing data from the referenced region * * \return \herr_t * - * \details H5LTread_region() reads data from a region described by - * the hyperslab coordinates in \p block_coord, located in - * the dataset specified by its absolute path \p path in a - * file specified by its name \p file. Data is read into a - * buffer \p buf of the datatype that corresponds to the + * \details H5LTread_region() reads data from a region described by + * the hyperslab coordinates in \p block_coord, located in + * the dataset specified by its absolute path \p path in a + * file specified by its name \p file. Data is read into a + * buffer \p buf of the datatype that corresponds to the * HDF5 datatype specified by \p mem_type. * - * Buffer \p block_coord has size 2*rank and is the coordinates - * of the starting point following by the coordinates of the - * ending point of the hyperslab. For example, to extract a - * rectangular hyperslab region starting at element (2,2) to + * Buffer \p block_coord has size 2*rank and is the coordinates + * of the starting point following by the coordinates of the + * ending point of the hyperslab. For example, to extract a + * rectangular hyperslab region starting at element (2,2) to * element (5,4) then \p block_coord would be {2, 2, 5, 4}. * - * Buffer \p buf should be big enough to hold selected elements + * Buffer \p buf should be big enough to hold selected elements * of the type that corresponds to the \p mem_type * * \version 1.1 Fortran wrapper introduced in this release. @@ -591,57 +554,55 @@ H5_HLRDLL herr_t H5LTcopy_region(const char *file_src, * */ H5_HLRDLL herr_t H5LTread_region(const char *file, - const char *path, - const hsize_t *block_coord, - hid_t mem_type, - void *buf ); + const char *path, + const hsize_t *block_coord, + hid_t mem_type, + void *buf ); /** * -------------------------------------------------------------------------- * \ingroup H5LR * - * \brief Retrieves the values of quality flags for each element + * \brief Retrieves the values of quality flags for each element * to the application provided buffer. * * \param[in] dset_id Identifier of the dataset with bit-field values * \param[in] num_values Number of the values to be extracted - * \param[in] offset Array of staring bits to be extracted from + * \param[in] offset Array of staring bits to be extracted from * the element; valid values: 0 (zero) through 7 - * \param[in] lengths Array of the number of bits to be extracted - * for each value - * \param[in] space Dataspace identifier, describing the elements - * to be read from the dataset with bit-field - * values + * \param[in] lengths Array of the number of bits to be extracted for each value + * \param[in] space Dataspace identifier, describing the elements + * to be read from the dataset with bit-field values * \param[out] buf Buffer to read the values in * * \return \herr_t * - * \details H5LTread_bitfield_value() reads selected elements from a - * dataset specified by its identifier \p dset_id, and unpacks + * \details H5LTread_bitfield_value() reads selected elements from a + * dataset specified by its identifier \p dset_id, and unpacks * the bit-field values to a buffer \p buf. * - * The parameter \p space is a space identifier that indicates + * The parameter \p space is a space identifier that indicates * which elements of the dataset should be read. * - * The parameter \p offset is an array of length \p num_values; + * The parameter \p offset is an array of length \p num_values; * the i<sup>th</sup> element of the array holds the value of the - * starting bit of the i<sup>th</sup> bit-field value. + * starting bit of the i<sup>th</sup> bit-field value. * Valid values are: 0 (zero) through 7. * - * The parameter \p lengths is an array of length \p num_values; - * the i<sup>th</sup> element of the array holds the number of - * bits to be extracted for the i<sup>th</sup> bit-field value. - * Extracted bits will be interpreted as a base-2 integer value. - * Each value will be converted to the base-10 integer value and - * stored in the application buffer. - * - * Buffer \p buf is allocated by the application and should be big - * enough to hold \c num_sel_elem * \p num_values elements of the - * specified type, where \c num_sel_elem is a number of the elements - * to be read from the dataset. Data in the buffer is organized - * as \p num_values values for the first element, followed by the - * \p num_values values for the second element, ... , followed by - * the \p num_values values for the + * The parameter \p lengths is an array of length \p num_values; + * the i<sup>th</sup> element of the array holds the number of + * bits to be extracted for the i<sup>th</sup> bit-field value. + * Extracted bits will be interpreted as a base-2 integer value. + * Each value will be converted to the base-10 integer value and + * stored in the application buffer. + * + * Buffer \p buf is allocated by the application and should be big + * enough to hold \c num_sel_elem * \p num_values elements of the + * specified type, where \c num_sel_elem is a number of the elements + * to be read from the dataset. Data in the buffer is organized + * as \p num_values values for the first element, followed by the + * \p num_values values for the second element, ... , followed by + * the \p num_values values for the * \c num_selected_elem<sup>th</sup> element. * * \version 1.1 Fortran wrapper introduced in this release. @@ -650,5 +611,5 @@ H5_HLRDLL herr_t H5LTread_region(const char *file, * */ H5_HLRDLL herr_t H5LTread_bitfield_value(hid_t dset_id, int num_values, const unsigned *offset, - const unsigned *lengths, hid_t space, int *buf); + const unsigned *lengths, hid_t space, int *buf); diff --git a/doxygen/dox/high_level/high_level.dox b/doxygen/dox/high_level/high_level.dox deleted file mode 100644 index c53d298..0000000 --- a/doxygen/dox/high_level/high_level.dox +++ /dev/null @@ -1,29 +0,0 @@ -/** \page high_level High-level library - * The high-level HDF5 library includes several sets of convenience and standard-use APIs to - * facilitate common HDF5 operations. - * - * <ul> - * <li>\ref H5LT "Lite (H5LT, H5LD)" - * \n - * Functions to simplify creating and manipulating datasets, attributes and other features - * <li>\ref H5IM "Image (H5IM)" - * \n - * Creating and manipulating HDF5 datasets intended to be interpreted as images - * <li>\ref H5TB "Table (H5TB)" - * \n - * Creating and manipulating HDF5 datasets intended to be interpreted as tables - * <li>\ref H5PT "Packet Table (H5PT)" - * \n - * Creating and manipulating HDF5 datasets to support append- and read-only operations on table data - * <li>\ref H5DS "Dimension Scale (H5DS)" - * \n - * Creating and manipulating HDF5 datasets that are associated with the dimension of another HDF5 dataset - * <li>\ref H5DO "Optimizations (H5DO)" - * \n - * Bypassing default HDF5 behavior in order to optimize for specific use cases - * <li>\ref H5LR "Extensions (H5LR, H5LT)" - * \n - * Working with region references, hyperslab selections, and bit-fields - * </ul> - * - */ diff --git a/doxygen/dox/rm-template.dox b/doxygen/dox/rm-template.dox index bd81f64..1e9f2d7 100644 --- a/doxygen/dox/rm-template.dox +++ b/doxygen/dox/rm-template.dox @@ -96,4 +96,4 @@ the <a href="https://www.oreilly.com/library/view/97-things-every/9780596809515/ * \version 1.MAJOR.MINOR Function was deprecated in this release \endverbatim -*/
\ No newline at end of file +*/ diff --git a/doxygen/examples/H5.format.1.0.html b/doxygen/examples/H5.format.1.0.html index ff21315..4eb0548 100644 --- a/doxygen/examples/H5.format.1.0.html +++ b/doxygen/examples/H5.format.1.0.html @@ -139,7 +139,7 @@ <p>This document describes the lower-level data objects; the higher-level objects and their properties are described - in the <a href="H5.user.html"><cite>HDF5 User's Guide</cite></a>. + in the <a href="H5.user.html"><cite>HDF5 User Guide</cite></a>. <!-- diff --git a/doxygen/examples/H5.format.1.1.html b/doxygen/examples/H5.format.1.1.html index 0ae31df..9d03a76 100644 --- a/doxygen/examples/H5.format.1.1.html +++ b/doxygen/examples/H5.format.1.1.html @@ -172,7 +172,7 @@ TABLE.list TD { border:none; } <p>This document describes the lower-level data objects; the higher-level objects and their properties are described - in the <a href="H5.user.html"><cite>HDF5 User's Guide</cite></a>. + in the <a href="H5.user.html"><cite>HDF5 User Guide</cite></a>. <P>Three levels of information comprise the file format. Level 0 contains basic information for identifying and diff --git a/doxygen/examples/H5.format.2.0.html b/doxygen/examples/H5.format.2.0.html index c16a3cc..d2979e1 100644 --- a/doxygen/examples/H5.format.2.0.html +++ b/doxygen/examples/H5.format.2.0.html @@ -1,289 +1,392 @@ <!DOCTYPE HTML> <html> - <head> - <title> - HDF5 File Format Specification Version 2.0 - </title> - -<style> -h1 { display: block; - margin-top: 24px; - margin-bottom: 24px; - margin-left: 0px; - margin-right: 0px; - text-indent: 0px; - } - -h2 { display: block; - margin-top: 8x; - margin-bottom: 8px; - margin-left: 0px; - margin-right: 0px; - text-indent: 0px; - } -<!-- A horizontal rule (<hr />) should be placed on the line above +<head> +<title>HDF5 File Format Specification Version 2.0</title> + +<style type="text/css"> +h1 { + display: block; + margin-top: 24px; + margin-bottom: 24px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; +} + +h2 { + display: block; + margin-top: 8x; + margin-bottom: 8px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; +} + +<!-- +A horizontal rule ( <hr />) should be placed on the line above each h2 tag. The h2 tags are used on the main sections along with -the hr tags. --> - -h3 { display: block; - margin-top: 8px; - margin-bottom: 8px; - margin-left: 0px; - margin-right: 0px; - text-indent: 0px; - } - -h4 { display: block; - margin-top: 8px; - margin-bottom: 8px; - margin-left: 0px; - margin-right: 0px; - text-indent: 0px; - } - -p { display: block; +the hr tags. -->h3 { + display: block; margin-top: 8px; margin-bottom: 8px; margin-left: 0px; margin-right: 0px; text-indent: 0px; - } +} + +h4 { + display: block; + margin-top: 8px; + margin-bottom: 8px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; +} + +p { + display: block; + margin-top: 8px; + margin-bottom: 8px; + margin-left: 0px; + margin-right: 0px; + text-indent: 0px; +} + +<!-- +p.item { + margin-left: 2em; + text-indent: -2em +} + +--> <!-- -p.item { margin-left: 2em; - text-indent: -2em - } --> -<!-- p.item2 { margin-left: 2em; text-indent: 2em} --> - -table.format { border:solid; - border-collapse:collapse; - caption-side:top; - text-align:center; - width:80%; - } -table.format th { border:ridge; - padding:4px; - width:25%; - } -table.format td { border:ridge; - padding:4px; - } -table.format caption { font-weight:bold; - font-size:larger; - } - -table.note {border:none; - text-align:right; - width:80%; - } - -table.desc { border:solid; - border-collapse:collapse; - caption-size:top; - text-align:left; - width:80%; - } -table.desc tr { vertical-align:top; - } -table.desc th { border-style:ridge; - font-size:larger; - padding:4px; - <!-- text-decoration:underline; --> - } -table.desc td { border-style:ridge; - <!-- padding: 4px; --> - vertical-align:text-top; - } -table.desc caption { font-weight:bold; - font-size:larger; - } - -table.list { border:none; - width:100% - } -table.list tr { vertical-align:text-top; - } -table.list th { border:none; - text-decoration:underline; - vertical-align:text-top; - } -table.list td { border:none; - vertical-align:text-top; - } - -table.msgdesc { border:none; - text-align:left; - width: 80% - } -table.msgdesc tr { vertical-align:text-top; - border-spacing:0; - padding:0; } -table.msgdesc th { border:none; - text-decoration:underline; - vertical-align:text-top; } -table.msgdesc td { border:none; - vertical-align:text-top; - } - -table.list80 { border:none; - width:80% - } -table.list80 tr { vertical-align:text-top; - } -table.list80 th { border:none; - text-decoration:underline; - vertical-align:text-top; - } -table.list80 td { border:none; - vertical-align:text-top; - } - -table.glossary { border:none; - text-align:left; - width: 80% - } -table.glossary tr { vertical-align:text-top; - border-spacing:0; - padding:0; } -table.glossary th { border:none; - text-align:left; - text-decoration:underline; - vertical-align:text-top; } -table.glossary td { border:none; - text-align:left; - vertical-align:text-top; - } - -div { page-break-inside:avoid; - page-break-after:auto - } +p.item2 { + margin-left: 2em; + text-indent: 2em +} +--> +table.format { + border: solid; + border-collapse: collapse; + caption-side: top; + text-align: center; + width: 80%; +} + +table.format th { + border: ridge; + padding: 4px; + width: 25%; +} + +table.format td { + border: ridge; + padding: 4px; +} + +table.format caption { + font-weight: bold; + font-size: larger; +} + +table.note { + border: none; + text-align: right; + width: 80%; +} + +table.desc { + border: solid; + border-collapse: collapse; + caption-size: top; + text-align: left; + width: 80%; +} + +table.desc tr { + vertical-align: top; +} + +table.desc th { + border-style: ridge; + font-size: larger; + padding: 4px; <!-- + text-decoration: underline; + --> +} + +table.desc td { + border-style: ridge; <!-- + padding: 4px; --> + vertical-align: text-top; +} + +table.desc caption { + font-weight: bold; + font-size: larger; +} + +table.list { + border: none; + width: 100% +} + +table.list tr { + vertical-align: text-top; +} + +table.list th { + border: none; + text-decoration: underline; + vertical-align: text-top; +} + +table.list td { + border: none; + vertical-align: text-top; +} + +table.msgdesc { + border: none; + text-align: left; + width: 80% +} + +table.msgdesc tr { + vertical-align: text-top; + border-spacing: 0; + padding: 0; +} + +table.msgdesc th { + border: none; + text-decoration: underline; + vertical-align: text-top; +} + +table.msgdesc td { + border: none; + vertical-align: text-top; +} + +table.list80 { + border: none; + width: 80% +} + +table.list80 tr { + vertical-align: text-top; +} + +table.list80 th { + border: none; + text-decoration: underline; + vertical-align: text-top; +} + +table.list80 td { + border: none; + vertical-align: text-top; +} + +table.glossary { + border: none; + text-align: left; + width: 80% +} + +table.glossary tr { + vertical-align: text-top; + border-spacing: 0; + padding: 0; +} + +table.glossary th { + border: none; + text-align: left; + text-decoration: underline; + vertical-align: text-top; +} + +table.glossary td { + border: none; + text-align: left; + vertical-align: text-top; +} + +div { + page-break-inside: avoid; + page-break-after: auto +} </style> - <center> +<center> <table border="0" width="90%"> - <tr> - <td valign="top"> - <ol type="I"> - <li><a href="#Intro">Introduction</a></li> - <font size="-1"> - <ol type="A"> - <li><a href="#ThisDocument">This Document</a></li> - <li><a href="#ChangesForHdf5_1_10">Changes for HDF5 1.10</a></li> - </ol> - </font> - - <li><a href="#FileMetaData">Disk Format: Level 0 - File Metadata</a></li> - <font size="-1"> - <ol type="A"> - <li><a href="#Superblock">Disk Format: Level 0A - Format Signature and Superblock</a></li> - <li><a href="#DriverInfo">Disk Format: Level 0B - File Driver Info</a></li> - <li><a href="#SuperblockExt">Disk Format: Level 0C - Superblock Extension</a></li> - </ol> - </font> - <li><a href="#FileInfra">Disk Format: Level 1 - File Infrastructure</a></li> - <font size="-1"> - <ol type="A"> - <li><a href="#Btrees">Disk Format: Level 1A - B-trees and B-tree - Nodes</a></li> - <ol type="1"> - <li><a href="#V1Btrees">Disk Format: Level 1A1 - Version 1 - B-trees (B-link Trees)</a></li> - <li><a href="#V2Btrees">Disk Format: Level 1A2 - Version 2 - B-trees</a></li> - </ol> - <li><a href="#SymbolTable">Disk Format: Level 1B - Group Symbol Table Nodes</a></li> - <li><a href="#SymbolTableEntry">Disk Format: Level 1C - Symbol Table Entry</a></li> - <li><a href="#LocalHeap">Disk Format: Level 1D - Local Heaps</a></li> - <li><a href="#GlobalHeap">Disk Format: Level 1E - Global Heap</a></li> - <li><a href="#FractalHeap">Disk Format: Level 1F - Fractal Heap</a></li> - <li><a href="#FreeSpaceManager">Disk Format: Level 1G - Free-space Manager</a></li> - <li><a href="#SOHMTable">Disk Format: Level 1H - Shared Object Header Message Table</a></li> - </ol> - </font> - <li><a href="#DataObject">Disk Format: Level 2 - Data Objects</a></li> - <font size="-1"> - <ol type="A"> - <li><a href="#ObjectHeader">Disk Format: Level 2A - Data Object Headers</a></li> - <ol type="1"> - <li><a href="#ObjectHeaderPrefix">Disk Format: Level 2A1 - Data Object Header Prefix</a></li> - <ol type="a"> - <li><a href="#V1ObjectHeaderPrefix">Version 1 Data Object Header Prefix</a></li> - <li><a href="#V2ObjectHeaderPrefix">Version 2 Data Object Header Prefix</a></li> - </ol> - <li><a href="#ObjectHeaderMessages">Disk Format: Level 2A2 - Data Object Header Messages</a></li> - <ol type="a"> - <li><a href="#NILMessage">The NIL Message</a></li> <!-- 0x0000 --> - <li><a href="#DataspaceMessage">The Dataspace Message</a></li> <!-- 0x0001 --> - <li><a href="#LinkInfoMessage">The Link Info Message</a></li> <!-- 0x0002 --> + <tr> + <td valign="top"> + <ol type="I"> + <li><a href="#Intro">Introduction</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#ThisDocument">This Document</a></li> + <li><a href="#ChangesForHdf5_1_10">Changes for HDF5 1.10</a></li> + </ol> + </font> + + <li><a href="#FileMetaData">Disk Format: Level 0 - File + Metadata</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#Superblock">Disk Format: Level 0A - Format + Signature and Superblock</a></li> + <li><a href="#DriverInfo">Disk Format: Level 0B - File + Driver Info</a></li> + <li><a href="#SuperblockExt">Disk Format: Level 0C - + Superblock Extension</a></li> + </ol> + </font> + <li><a href="#FileInfra">Disk Format: Level 1 - File + Infrastructure</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#Btrees">Disk Format: Level 1A - B-trees + and B-tree Nodes</a></li> + <ol type="1"> + <li><a href="#V1Btrees">Disk Format: Level 1A1 - + Version 1 B-trees (B-link Trees)</a></li> + <li><a href="#V2Btrees">Disk Format: Level 1A2 - + Version 2 B-trees</a></li> + </ol> + <li><a href="#SymbolTable">Disk Format: Level 1B - Group + Symbol Table Nodes</a></li> + <li><a href="#SymbolTableEntry">Disk Format: Level 1C - + Symbol Table Entry</a></li> + <li><a href="#LocalHeap">Disk Format: Level 1D - Local + Heaps</a></li> + <li><a href="#GlobalHeap">Disk Format: Level 1E - Global + Heap</a></li> + <li><a href="#FractalHeap">Disk Format: Level 1F - + Fractal Heap</a></li> + <li><a href="#FreeSpaceManager">Disk Format: Level 1G - + Free-space Manager</a></li> + <li><a href="#SOHMTable">Disk Format: Level 1H - Shared + Object Header Message Table</a></li> + </ol> + </font> + <li><a href="#DataObject">Disk Format: Level 2 - Data + Objects</a></li> + <font size="-1"> + <ol type="A"> + <li><a href="#ObjectHeader">Disk Format: Level 2A - Data + Object Headers</a></li> + <ol type="1"> + <li><a href="#ObjectHeaderPrefix">Disk Format: Level + 2A1 - Data Object Header Prefix</a></li> + <ol type="a"> + <li><a href="#V1ObjectHeaderPrefix">Version 1 Data + Object Header Prefix</a></li> + <li><a href="#V2ObjectHeaderPrefix">Version 2 Data + Object Header Prefix</a></li> + </ol> + <li><a href="#ObjectHeaderMessages">Disk Format: Level + 2A2 - Data Object Header Messages</a></li> + <ol type="a"> + <li><a href="#NILMessage">The NIL Message</a></li> + <!-- 0x0000 --> + <li><a href="#DataspaceMessage">The Dataspace Message</a></li> + <!-- 0x0001 --> + <li><a href="#LinkInfoMessage">The Link Info Message</a></li> + <!-- 0x0002 --> + </ol> + </ol> + </ol> + </font> </ol> - </ol> - </ol> - </font> - </ol> - </td> - - <td> </td> - - <td valign="top"> - <ol type="I" start="4"> - <li><a href="#DataObject">Disk Format: Level 2 - Data - Objects</a><font size="-1"><i> (Continued)</i></li> - <ol type="A"> - <li><a href="#ObjectHeader">Disk Format: Level 2A - Data Object - Headers</a><i> (Continued)</i></li> - <ol type="1" start="2"> - <li><a href="#ObjectHeaderMessages">Disk Format: Level 2A2 - - Data Object Header Messages</a><i> (Continued)</i></li> - <ol type="a" start="4"> - <li><a href="#DatatypeMessage">The Datatype Message</a></li> <!-- 0x0003 --> - <li><a href="#OldFillValueMessage">The Data Storage - - Fill Value (Old) Message</a></li> <!-- 0x0004 --> - <li><a href="#FillValueMessage">The Data Storage - - Fill Value Message</a></li> <!-- 0x0005 --> - <li><a href="#LinkMessage">The Link Message</a></li> <!-- 0x0006 --> - <li><a href="#ExternalFileListMessage">The Data Storage - - External Data Files Message</a></li> <!-- 0x0007 --> - <li><a href="#LayoutMessage">The Data Storage - - Layout Message</a></li> <!-- 0x0008 --> - <li><a href="#BogusMessage">The Bogus Message</a></li> <!-- 0x0009 --> - <li><a href="#GroupInfoMessage">The Group Info - Message</a></li> <!-- 0x000a --> - <li><a href="#FilterMessage">The Data Storage - - Filter Pipeline Message</a></li> <!-- 0x000b --> - <li><a href="#AttributeMessage">The Attribute - Message</a></li> <!-- 0x000c --> - <li><a href="#CommentMessage">The Object Comment - Message</a></li> <!-- 0x000d --> - <li><a href="#OldModificationTimeMessage">The Object - Modification Time (Old) Message</a></li> <!-- 0x000e --> - <li><a href="#SOHMTableMessage">The Shared Message - Table Message</a></li> <!-- 0x000f --> - <li><a href="#ContinuationMessage">The Object Header - Continuation Message</a></li> <!-- 0x0010 --> - <li><a href="#SymbolTableMessage">The Symbol - Table Message</a></li> <!-- 0x0011 --> - <li><a href="#ModificationTimeMessage">The Object - Modification Time Message</a></li> <!-- 0x0012 --> - <li><a href="#BtreeKValuesMessage">The B-tree - ‘K’ Values Message</a></li> <!-- 0x0013 --> - <li><a href="#DrvInfoMessage">The Driver Info - Message</a></li> <!-- 0x0014 --> - <li><a href="#AinfoMessage">The Attribute Info - Message</a></li> <!-- 0x0015 --> - <li><a href="#RefCountMessage">The Object Reference - Count Message</a></li> <!-- 0x0016 --> - <li><a href="#FsinfoMessage">The File Space Info - Message</a></li> <!-- 0x0018 --> + </td> + + <td> </td> + + <td valign="top"> + <ol type="I" start="4"> + <li><a href="#DataObject">Disk Format: Level 2 - Data + Objects</a><font size="-1"><i> (Continued)</i></font></li> + <ol type="A"> + <li><a href="#ObjectHeader">Disk Format: Level 2A - Data + Object Headers</a><i> (Continued)</i></li> + <ol type="1" start="2"> + <li><a href="#ObjectHeaderMessages">Disk Format: Level + 2A2 - Data Object Header Messages</a><i> (Continued)</i></li> + <ol type="a" start="4"> + <li><a href="#DatatypeMessage">The Datatype Message</a></li> + <!-- 0x0003 --> + <li><a href="#OldFillValueMessage">The Data Storage - + Fill Value (Old) Message</a></li> + <!-- 0x0004 --> + <li><a href="#FillValueMessage">The Data Storage - Fill + Value Message</a></li> + <!-- 0x0005 --> + <li><a href="#LinkMessage">The Link Message</a></li> + <!-- 0x0006 --> + <li><a href="#ExternalFileListMessage">The Data Storage + - External Data Files Message</a></li> + <!-- 0x0007 --> + <li><a href="#LayoutMessage">The Data Storage - Layout + Message</a></li> + <!-- 0x0008 --> + <li><a href="#BogusMessage">The Bogus Message</a></li> + <!-- 0x0009 --> + <li><a href="#GroupInfoMessage">The Group Info Message</a></li> + <!-- 0x000a --> + <li><a href="#FilterMessage">The Data Storage - Filter + Pipeline Message</a></li> + <!-- 0x000b --> + <li><a href="#AttributeMessage">The Attribute Message</a></li> + <!-- 0x000c --> + <li><a href="#CommentMessage">The Object Comment + Message</a></li> + <!-- 0x000d --> + <li><a href="#OldModificationTimeMessage">The Object + Modification Time (Old) Message</a></li> + <!-- 0x000e --> + <li><a href="#SOHMTableMessage">The Shared Message + Table Message</a></li> + <!-- 0x000f --> + <li><a href="#ContinuationMessage">The Object Header + Continuation Message</a></li> + <!-- 0x0010 --> + <li><a href="#SymbolTableMessage">The Symbol Table + Message</a></li> + <!-- 0x0011 --> + <li><a href="#ModificationTimeMessage">The Object + Modification Time Message</a></li> + <!-- 0x0012 --> + <li><a href="#BtreeKValuesMessage">The B-tree + ‘K’ Values Message</a></li> + <!-- 0x0013 --> + <li><a href="#DrvInfoMessage">The Driver Info Message</a></li> + <!-- 0x0014 --> + <li><a href="#AinfoMessage">The Attribute Info Message</a></li> + <!-- 0x0015 --> + <li><a href="#RefCountMessage">The Object Reference + Count Message</a></li> + <!-- 0x0016 --> + <li><a href="#FsinfoMessage">The File Space Info + Message</a></li> + <!-- 0x0018 --> + </ol> + </ol> + <li><a href="#DataStorage">Disk Format: Level 2B - Data + Object Data Storage</a></li> + </ol> + <font></font> + <li><a href="#AppendixA">Appendix A: Definitions</a></li> + <li><a href="#AppendixB">Appendix B: File Memory + Allocation Types</a></li> </ol> - </ol> - <li><a href="#DataStorage">Disk Format: Level 2B - Data Object Data Storage</a></li> - </ol> - </font> - <li><a href="#AppendixA">Appendix A: Definitions</a></li> - <li><a href="#AppendixB">Appendix B: File Memory Allocation Types</a></li> - </ol> -</td></tr> -</table> + </td> + </tr> + </table> </center> @@ -293,949 +396,984 @@ div { page-break-inside:avoid; <hr /> <a name="Intro"><h2>I. Introduction</h2></a> - <table align="right" width="100"> - <tr><td> </td><td align="center"> - <hr /> - <img src="FF-IH_FileGroup.gif" alt="HDF5 Groups" hspace="15" vspace="15"> - </td><td> </td></tr> - <tr><td> </td><td align="center"> - <strong>Figure 1:</strong> Relationships among the HDF5 root group, other groups, and objects - <hr /> - </td><td> </td></tr> - - <tr><td> </td><td align="center"> - <img src="FF-IH_FileObject.gif" alt="HDF5 Objects" hspace="15" vspace="15"> - </td><td> </td></tr> - <tr><td> </td><td align="center"> - <strong>Figure 2:</strong> HDF5 objects -- datasets, datatypes, or dataspaces - <hr /> - </td><td> </td></tr> - </table> - - - <p>The format of an HDF5 file on disk encompasses several - key ideas of the HDF4 and AIO file formats as well as - addressing some shortcomings therein. The new format is - more self-describing than the HDF4 format and is more - uniformly applied to data objects in the file.</p> - - <p>An HDF5 file appears to the user as a directed graph. - The nodes of this graph are the higher-level HDF5 objects - that are exposed by the HDF5 APIs:</p> - - <ul> - <li>Groups</li> - <li>Datasets</li> - <li>Committed (formerly Named) datatypes</li> - </ul> - - <p>At the lowest level, as information is actually written to the disk, - an HDF5 file is made up of the following objects:</p> - <ul> - <li>A superblock</li> - <li>B-tree nodes</li> - <li>Heap blocks</li> - <li>Object headers</li> - <li>Object data</li> - <li>Free space</li> - </ul> - - <p>The HDF5 Library uses these low-level objects to represent the - higher-level objects that are then presented to the user or - to applications through the APIs. For instance, a group is an - object header that contains a message that points to a local - heap (for storing the links to objects in the group) and to a - B-tree (which indexes the links). A dataset is an object header - that contains messages that describe datatype, dataspace, layout, - filters, external files, fill value, and other elements with the - layout message pointing to either a raw data chunk or to a - B-tree that points to raw data chunks.</p> +<table align="right" width="100"> + <tr> + <td> </td> + <td align="center"> + <hr /> <img src="FF-IH_FileGroup.gif" alt="HDF5 Groups" hspace="15" + vspace="15"> + </td> + <td> </td> + </tr> + <tr> + <td> </td> + <td align="center"><strong>Figure 1:</strong> Relationships among + the HDF5 root group, other groups, and objects + <hr /></td> + <td> </td> + </tr> + + <tr> + <td> </td> + <td align="center"><img src="FF-IH_FileObject.gif" + alt="HDF5 Objects" hspace="15" vspace="15"></td> + <td> </td> + </tr> + <tr> + <td> </td> + <td align="center"><strong>Figure 2:</strong> HDF5 objects -- + datasets, datatypes, or dataspaces + <hr /></td> + <td> </td> + </tr> +</table> + + +<p>The format of an HDF5 file on disk encompasses several key ideas + of the HDF4 and AIO file formats as well as addressing some + shortcomings therein. The new format is more self-describing than the + HDF4 format and is more uniformly applied to data objects in the file.</p> + +<p>An HDF5 file appears to the user as a directed graph. The nodes + of this graph are the higher-level HDF5 objects that are exposed by the + HDF5 APIs:</p> + +<ul> + <li>Groups</li> + <li>Datasets</li> + <li>Committed (formerly Named) datatypes</li> +</ul> + +<p>At the lowest level, as information is actually written to the + disk, an HDF5 file is made up of the following objects:</p> +<ul> + <li>A superblock</li> + <li>B-tree nodes</li> + <li>Heap blocks</li> + <li>Object headers</li> + <li>Object data</li> + <li>Free space</li> +</ul> + +<p>The HDF5 Library uses these low-level objects to represent the + higher-level objects that are then presented to the user or to + applications through the APIs. For instance, a group is an object + header that contains a message that points to a local heap (for storing + the links to objects in the group) and to a B-tree (which indexes the + links). A dataset is an object header that contains messages that + describe datatype, dataspace, layout, filters, external files, fill + value, and other elements with the layout message pointing to either a + raw data chunk or to a B-tree that points to raw data chunks.</p> <br /> <a name="ThisDocument"><h3>I.A. This Document</h3></a> - <p>This document describes the lower-level data objects; - the higher-level objects and their properties are described - in the <a href="UG/HDF5_Users_Guide-Responsive HTML5/index.html"><cite>HDF5 User’s Guide</cite></a>.</p> - - <p>Three levels of information comprise the file format. - Level 0 contains basic information for identifying and - defining information about the file. Level 1 information contains - the information about the pieces of a file shared by many objects - in the file (such as a B-trees and heaps). Level 2 is the rest - of the file and contains all of the data objects, with each object - partitioned into header information, also known as - <em>metadata</em>, and data.</p> - - <p>The sizes of various fields in the following layout tables are - determined by looking at the number of columns the field spans - in the table. There are three exceptions: (1) The size may be - overridden by specifying a size in parentheses, (2) the size of - addresses is determined by the <em>Size of Offsets</em> field - in the superblock and is indicated in this document with a - superscripted ‘O’, and (3) the size of length fields is determined - by the <em>Size of Lengths</em> field in the superblock and is - indicated in this document with a superscripted ‘L’.</p> - - <p>Values for all fields in this document should be treated as unsigned - integers, unless otherwise noted in the description of a field. - Additionally, all metadata fields are stored in little-endian byte - order. - </p> - - <p>All checksums used in the format are computed with the - <a href="http://www.burtleburtle.net/bob/hash/doobs.html">Jenkins’ - lookup3</a> algorithm. - </p> - - <p>Whenever a bit flag or field is mentioned for an entry, bits are - numbered from the lowest bit position in the entry. - </p> - - <p>Various tables in this document aligned with “This space inserted - only to align table nicely”. These entries in the table are just - to make the table presentation nicer and do not represent any values - or padding in the file. - </p> +<p> + This document describes the lower-level data objects; the higher-level + objects and their properties are described in the <a + href="UG/HDF5_User_Guide-Responsive HTML5/index.html"><cite>HDF5 + User Guide</cite></a>. +</p> + +<p> + Three levels of information comprise the file format. Level 0 contains + basic information for identifying and defining information about the + file. Level 1 information contains the information about the pieces of + a file shared by many objects in the file (such as a B-trees and + heaps). Level 2 is the rest of the file and contains all of the data + objects, with each object partitioned into header information, also + known as <em>metadata</em>, and data. +</p> + +<p> + The sizes of various fields in the following layout tables are + determined by looking at the number of columns the field spans in the + table. There are three exceptions: (1) The size may be overridden by + specifying a size in parentheses, (2) the size of addresses is + determined by the <em>Size of Offsets</em> field in the superblock and + is indicated in this document with a superscripted ‘O’, and + (3) the size of length fields is determined by the <em>Size of + Lengths</em> field in the superblock and is indicated in this document with + a superscripted ‘L’. +</p> + +<p>Values for all fields in this document should be treated as + unsigned integers, unless otherwise noted in the description of a + field. Additionally, all metadata fields are stored in little-endian + byte order.</p> + +<p> + All checksums used in the format are computed with the <a + href="http://www.burtleburtle.net/bob/hash/doobs.html">Jenkins’ + lookup3</a> algorithm. +</p> + +<p>Whenever a bit flag or field is mentioned for an entry, bits are + numbered from the lowest bit position in the entry.</p> + +<p>Various tables in this document aligned with “This space + inserted only to align table nicely”. These entries in the table + are just to make the table presentation nicer and do not represent any + values or padding in the file.</p> <br /> <a name="ChangesForHdf5_1_10"><h3>I.B. Changes for HDF5 1.10</h3></a> - <p>As of October 2015, changes in the file format for HDF5 1.10 - have not yet been finalized.</p> +<p>As of October 2015, changes in the file format for HDF5 1.10 have + not yet been finalized.</p> <br /> <br /> <hr /> -<h2><a name="FileMetaData"> -II. Disk Format: Level 0 - File Metadata</a></h2> - -<br /> -<h3><a name="Superblock"> -II.A. Disk Format: Level 0A - Format Signature and Superblock</a></h3> - - <p>The superblock may begin at certain predefined offsets within - the HDF5 file, allowing a block of unspecified content for - users to place additional information at the beginning (and - end) of the HDF5 file without limiting the HDF5 Library’s - ability to manage the objects within the file itself. This - feature was designed to accommodate wrapping an HDF5 file in - another file format or adding descriptive information to an HDF5 - file without requiring the modification of the actual file’s - information. The superblock is located by searching for the - HDF5 format signature at byte offset 0, byte offset 512, and at - successive locations in the file, each a multiple of two of - the previous location; in other words, at these byte offsets: - 0, 512, 1024, 2048, and so on.</p> - - <p>The superblock is composed of the format signature, followed by a - superblock version number and information that is specific to each - version of the superblock. - Currently, there are three versions of the superblock format. - Version 0 is the default format, while version 1 is basically the same - as version 0 with additional information when a non-default B-tree ‘K’ - value is stored. Version 2 is the latest format, with some fields - eliminated or compressed and with superblock extension and checksum - support.</p> - - <p>Version 0 and 1 of the superblock are described below:</p> - - - <div align="center"> - <table class="format"> - <caption> - Superblock (Versions 0 and 1) - </caption> - - <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> - - <tr> - <td colspan="4"><br />Format Signature (8 bytes)<br /><br /></td> - </tr> - - <tr> - <td>Version # of Superblock</td> - <td>Version # of File’s Free Space Storage</td> - <td>Version # of Root Group Symbol Table Entry</td> - <td>Reserved (zero)</td> - </tr> - - <tr> - <td>Version # of Shared Header Message Format</td> - <td>Size of Offsets</td> - <td>Size of Lengths</td> - <td>Reserved (zero)</td> - </tr> - - <tr> - <td colspan="2">Group Leaf Node K</td> - <td colspan="2">Group Internal Node K</td> - </tr> - - <tr> - <td colspan="4">File Consistency Flags</td> - </tr> - - <tr> - <td colspan="2" style="border:dotted;">Indexed Storage Internal Node K<sup>1</sup></td> - <td colspan="2" style="border:dotted;">Reserved (zero)<sup>1</sup></td> - </tr> - - <tr> - <td colspan="4"><br />Base Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Address of File Free space Info<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />End of File Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Driver Information Block Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4">Root Group Symbol Table Entry</td> - </tr> - </table> +<h2> + <a name="FileMetaData"> II. Disk Format: Level 0 - File Metadata</a> +</h2> + +<br /> +<h3> + <a name="Superblock"> II.A. Disk Format: Level 0A - Format + Signature and Superblock</a> +</h3> + +<p>The superblock may begin at certain predefined offsets within the + HDF5 file, allowing a block of unspecified content for users to place + additional information at the beginning (and end) of the HDF5 file + without limiting the HDF5 Library’s ability to manage the objects + within the file itself. This feature was designed to accommodate + wrapping an HDF5 file in another file format or adding descriptive + information to an HDF5 file without requiring the modification of the + actual file’s information. The superblock is located by searching + for the HDF5 format signature at byte offset 0, byte offset 512, and at + successive locations in the file, each a multiple of two of the + previous location; in other words, at these byte offsets: 0, 512, 1024, + 2048, and so on.</p> + +<p>The superblock is composed of the format signature, followed by a + superblock version number and information that is specific to each + version of the superblock. Currently, there are three versions of the + superblock format. Version 0 is the default format, while version 1 is + basically the same as version 0 with additional information when a + non-default B-tree ‘K’ value is stored. Version 2 is the + latest format, with some fields eliminated or compressed and with + superblock extension and checksum support.</p> + +<p>Version 0 and 1 of the superblock are described below:</p> + + +<div align="center"> + <table class="format"> + <caption>Superblock (Versions 0 and 1)</caption> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are - of the size specified in “Size of Offsets.”) - </td></tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + <tr> - <td> </td> - <td> - (Items marked with a ‘1’ in the above table are - new in version 1 of the superblock) - </td></tr> - </table> - </div> + <td colspan="4"><br />Format Signature (8 bytes)<br /> + <br /></td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Format Signature</p></td> - <td><p>This field contains a constant value and can be used to - quickly identify a file as being an HDF5 file. The - constant value is designed to allow easy identification of - an HDF5 file and to allow certain types of data corruption - to be detected. The file signature of an HDF5 file always - contains the following values:</p> - <center> - <table border align="center" cellpadding="4"> - <tr align="center"> - <td align="right">Decimal:</td> - <td width="8%">137</td> - <td width="8%">72</td> - <td width="8%">68</td> - <td width="8%">70</td> - <td width="8%">13</td> - <td width="8%">10</td> - <td width="8%">26</td> - <td width="8%">10</td> - </tr> - - <tr align="center"> - <td align="right">Hexadecimal:</td> - <td>89</td> - <td>48</td> - <td>44</td> - <td>46</td> - <td>0d</td> - <td>0a</td> - <td>1a</td> - <td>0a</td> - </tr> - - <tr align="center"> - <td align="right">ASCII C Notation:</td> - <td>\211</td> - <td>H</td> - <td>D</td> - <td>F</td> - <td>\r</td> - <td>\n</td> - <td>\032</td> - <td>\n</td> - </tr> - </table> - </center> - <p>This signature both identifies the file as an HDF5 file - and provides for immediate detection of common - file-transfer problems. The first two bytes distinguish - HDF5 files on systems that expect the first two bytes to - identify the file type uniquely. The first byte is - chosen as a non-ASCII value to reduce the probability - that a text file may be misrecognized as an HDF5 file; - also, it catches bad file transfers that clear bit - 7. Bytes two through four name the format. The CR-LF - sequence catches bad file transfers that alter newline - sequences. The control-Z character stops file display - under MS-DOS. The final line feed checks for the inverse - of the CR-LF translation problem. (This is a direct - descendent of the - <a href="http://www.libpng.org/pub/png/spec/iso/index-object.html#5PNG-file-signature">PNG</a> file - signature.)</p> - <p><em>This field is present in version 0+ of the superblock.</em> - </p></td> - </tr> - - <tr> - <td><p>Version Number of the Superblock</p></td> - <td><p>This value is used to determine the format of the - information in the superblock. When the format of the - information in the superblock is changed, the version number - is incremented to the next integer and can be used to - determine how the information in the superblock is - formatted.</p> - - <p>Values of 0, 1 and 2 are defined for this field. (The format - of version 2 is described below, not here) - </p> - - <p><em>This field is present in version 0+ of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>Version Number of the File’s Free Space - Information</p></td> - <td> - <p>This value is used to determine the format of the - file’s free space information. - </p> - <p>The only value currently valid in this field is ‘0’, which - indicates that the file’s free space is as described - <a href="#FreeSpaceManager">below</a>. - </p> - - <p><em>This field is present in version 0 and 1 of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>Version Number of the Root Group Symbol Table - Entry</p></td> - <td><p>This value is used to determine the format of the - information in the Root Group Symbol Table Entry. When the - format of the information in that field is changed, the - version number is incremented to the next integer and can be - used to determine how the information in the field - is formatted.</p> - <p>The only value currently valid in this field is ‘0’, - which indicates that the root group symbol table entry is - formatted as described <a href="#SymbolTableEntry">below</a>.</p> - <p><em>This field is present in version 0 and 1 of the - superblock.</em></p> - </td> - </tr> - - <tr> - <td><p>Version Number of the Shared Header Message Format</p></td> - <td><p>This value is used to determine the format of the - information in a shared object header message. Since the format - of the shared header messages differs from the other private - header messages, a version number is used to identify changes - in the format. - </p> - <p>The only value currently valid in this field is ‘0’, which - indicates that shared header messages are formatted as - described <a href="#ObjectHeaderMessages">below</a>. - </p> - - <p><em>This field is present in version 0 and 1 of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>Size of Offsets</p></td> - <td><p>This value contains the number of bytes used to store - addresses in the file. The values for the addresses of - objects in the file are offsets relative to a base address, - usually the address of the superblock signature. This - allows a wrapper to be added after the file is created - without invalidating the internal offset locations. - </p> - - <p><em>This field is present in version 0+ of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>Size of Lengths</p></td> - <td><p>This value contains the number of bytes used to store - the size of an object. - </p> - <p><em>This field is present in version 0+ of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>Group Leaf Node K</p></td> - <td> - <p>Each leaf node of a group B-tree will have at - least this many entries but not more than twice this - many. If a group has a single leaf node then it - may have fewer entries. - </p> - <p>This value must be greater than zero. - </p> - <p>See the <a href="#Btrees">description</a> of B-trees below. - </p> - - <p><em>This field is present in version 0 and 1 of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>Group Internal Node K</p></td> - <td> - <p>Each internal node of a group B-tree will have at - least this many entries but not more than twice this - many. If the group has only one internal - node then it might have fewer entries. - </p> - <p>This value must be greater than zero. - </p> - <p>See the <a href="#Btrees">description</a> of B-trees below. - </p> - - <p><em>This field is present in version 0 and 1 of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>File Consistency Flags</p></td> - <td> - <p>This value contains flags to indicate information - about the consistency of the information contained - within the file. Currently, the following bit flags are - defined: - <ul> - <li>Bit 0 set indicates that the file is opened for - write-access.</li> - <li>Bit 1 set indicates that the file has - been verified for consistency and is guaranteed to be - consistent with the format defined in this document.</li> - <li>Bits 2-31 are reserved for future use.</li> - </ul> - Bit 0 should be - set as the first action when a file is opened for write - access and should be cleared only as the final action - when closing a file. Bit 1 should be cleared during - normal access to a file and only set after the file’s - consistency is guaranteed by the library or a - consistency utility. - </p> - - <p><em>This field is present in version 0+ of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>Indexed Storage Internal Node K</p></td> - <td> - <p>Each internal node of an indexed storage B-tree will have at - least this many entries but not more than twice this - many. If the index storage B-tree has only one internal - node then it might have fewer entries. - </p> - <p>This value must be greater than zero. - </p> - <p>See the <a href="#Btrees">description</a> of B-trees below. - </p> - - <p><em>This field is present in version 1 of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>Base Address</p></td> - <td> - <p>This is the absolute file address of the first byte of - the HDF5 data within the file. The library currently - constrains this value to be the absolute file address - of the superblock itself when creating new files; - future versions of the library may provide greater - flexibility. When opening an existing file and this address does - not match the offset of the superblock, the library assumes - that the entire contents of the HDF5 file have been adjusted in - the file and adjusts the base address and end of file address to - reflect their new positions in the file. Unless otherwise noted, - all other file addresses are relative to this base - address. - </p> - - <p><em>This field is present in version 0+ of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>Address of Global Free-space Index</p></td> - <td> - <p>The file’s free space is not persistent for version 0 and 1 of - the superblock. - Currently this field always contains the - <a href="#UndefinedAddress">undefined address</a>. - </p> - - <p><em>This field is present in version 0 and 1 of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>End of File Address</p></td> - <td> - <p>This is the absolute file address of the first byte past - the end of all HDF5 data. It is used to determine whether a - file has been accidentally truncated and as an address where - file data allocation can occur if space from the free list is - not used. - </p> - - <p><em>This field is present in version 0+ of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>Driver Information Block Address</p></td> - <td> - <p>This is the relative file address of the file driver - information block which contains driver-specific - information needed to reopen the file. If there is no - driver information block then this entry should be the - <a href="#UndefinedAddress">undefined address</a>. - </p> - - <p><em>This field is present in version 0 and 1 of the superblock.</em> - </p> - </td> - </tr> - - <tr> - <td><p>Root Group Symbol Table Entry</p></td> - <td> - <p>This is the <a href="#SymbolTableEntry">symbol table entry</a> - of the root group, which serves as the entry point into - the group graph for the file. - </p> - - <p><em>This field is present in version 0 and 1 of the superblock.</em> - </p> - </td> + <tr> + <td>Version # of Superblock</td> + <td>Version # of File’s Free Space Storage</td> + <td>Version # of Root Group Symbol Table Entry</td> + <td>Reserved (zero)</td> </tr> - </table> - </div> - <br /> - <p>Version 2 of the superblock is described below:</p> - - <div align="center"> - <table class="format"> - <caption> - Superblock (Version 2) - </caption> - - <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> - - <tr> - <td colspan="4"><br />Format Signature (8 bytes)<br /><br /></td> - </tr> - - <tr> - <td>Version # of Superblock</td> - <td>Size of Offsets</td> - <td>Size of Lengths</td> - <td>File Consistency Flags</td> - </tr> - - <tr> - <td colspan="4"><br />Base Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Superblock Extension Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />End of File Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Root Group Object Header Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4">Superblock Checksum</td> - </tr> - </table> + <tr> + <td>Version # of Shared Header Message Format</td> + <td>Size of Offsets</td> + <td>Size of Lengths</td> + <td>Reserved (zero)</td> + </tr> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are - of the size specified in “Size of Offsets.”) - </td></tr> - </table> + <td colspan="2">Group Leaf Node K</td> + <td colspan="2">Group Internal Node K</td> + </tr> - </div> + <tr> + <td colspan="4">File Consistency Flags</td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Format Signature</p></td> - <td> - <p>This field is the same as described for versions 0 and 1 of the - superblock. - </p></td> - </tr> - - <tr> - <td><p>Version Number of the Superblock</p></td> - <td> - <p>This field has a value of 2 and has the same meaning as for - versions 0 and 1. - </p> - </td> - </tr> - - <tr> - <td><p>Size of Offsets</p></td> - <td> - <p>This field is the same as described for versions 0 and 1 of the - superblock. - </p> - </td> - </tr> - - <tr> - <td><p>Size of Lengths</p></td> - <td> - <p>This field is the same as described for versions 0 and 1 of the - superblock. - </p> - </td> - </tr> - - <tr> - <td><p>File Consistency Flags</p></td> - <td> - <p>This field is the same as described for versions 0 and 1 except - that it is smaller (the number of reserved bits has been reduced - from 30 to 6). - </p> - </td> - </tr> - - <tr> - <td><p>Base Address</p></td> - <td> - <p>This field is the same as described for versions 0 and 1 of the - superblock. - </p> - </td> - </tr> - - <tr> - <td><p>Superblock Extension Address</p></td> - <td> - <p>The field is the address of the object header for the - <a href="#SuperblockExt">superblock extension</a>. - If there is no extension then this entry should be the - <a href="#UndefinedAddress">undefined address</a>. - </p> - </td> - </tr> - - <tr> - <td><p>End of File Address</p></td> - <td> - <p>This field is the same as described for versions 0 and 1 of the - superblock. - </p> - </td> - </tr> - - <tr> - <td><p>Root Group Object Header Address</p></td> - <td> - <p>This is the address of - the <a href="#DataObject">root group object header</a>, - which serves as the entry point into the group graph for the file. - </p> - </td> - </tr> - - <tr> - <td><p>Superblock Checksum</p></td> - <td> - <p>The checksum for the superblock. - </p> - </td> + <tr> + <td colspan="2" style="border: dotted;">Indexed Storage Internal + Node K<sup>1</sup> + </td> + <td colspan="2" style="border: dotted;">Reserved (zero)<sup>1</sup></td> </tr> - </table> - </div> + <tr> + <td colspan="4"><br />Base Address<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of File Free space Info<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of File Address<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Driver Information Block Address<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4">Root Group Symbol Table Entry</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets.”)</td> + </tr> + <tr> + <td> </td> + <td>(Items marked with a ‘1’ in the above table are + new in version 1 of the superblock)</td> + </tr> + </table> +</div> <br /> -<h3><a name="DriverInfo"> -II.B. Disk Format: Level 0B - File Driver Info</a></h3> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Format Signature</p></td> + <td><p>This field contains a constant value and can be used + to quickly identify a file as being an HDF5 file. The constant + value is designed to allow easy identification of an HDF5 file and + to allow certain types of data corruption to be detected. The file + signature of an HDF5 file always contains the following values:</p> + <center> + <table border align="center" cellpadding="4"> + <tr align="center"> + <td align="right">Decimal:</td> + <td width="8%">137</td> + <td width="8%">72</td> + <td width="8%">68</td> + <td width="8%">70</td> + <td width="8%">13</td> + <td width="8%">10</td> + <td width="8%">26</td> + <td width="8%">10</td> + </tr> + + <tr align="center"> + <td align="right">Hexadecimal:</td> + <td>89</td> + <td>48</td> + <td>44</td> + <td>46</td> + <td>0d</td> + <td>0a</td> + <td>1a</td> + <td>0a</td> + </tr> - <p>The <b>driver information block</b> is an optional region of the - file which contains information needed by the file driver - to reopen a file. The format is described below:</p> + <tr align="center"> + <td align="right">ASCII C Notation:</td> + <td>\211</td> + <td>H</td> + <td>D</td> + <td>F</td> + <td>\r</td> + <td>\n</td> + <td>\032</td> + <td>\n</td> + </tr> + </table> + </center> + <p> + This signature both identifies the file as an HDF5 file and + provides for immediate detection of common file-transfer problems. + The first two bytes distinguish HDF5 files on systems that expect + the first two bytes to identify the file type uniquely. The first + byte is chosen as a non-ASCII value to reduce the probability that + a text file may be misrecognized as an HDF5 file; also, it catches + bad file transfers that clear bit 7. Bytes two through four name + the format. The CR-LF sequence catches bad file transfers that + alter newline sequences. The control-Z character stops file display + under MS-DOS. The final line feed checks for the inverse of the + CR-LF translation problem. (This is a direct descendent of the <a + href="http://www.libpng.org/pub/png/spec/iso/index-object.html#5PNG-file-signature">PNG</a> + file signature.) + </p> + <p> + <em>This field is present in version 0+ of the superblock.</em> + </p></td> + </tr> + <tr> + <td><p>Version Number of the Superblock</p></td> + <td><p>This value is used to determine the format of the + information in the superblock. When the format of the information + in the superblock is changed, the version number is incremented to + the next integer and can be used to determine how the information + in the superblock is formatted.</p> - <div align="center"> - <table class="format"> - <caption> - Driver Information Block - </caption> + <p>Values of 0, 1 and 2 are defined for this field. (The format + of version 2 is described below, not here)</p> + + <p> + <em>This field is present in version 0+ of the superblock.</em> + </p></td> + </tr> + + <tr> + <td><p>Version Number of the File’s Free Space + Information</p></td> + <td> + <p>This value is used to determine the format of the + file’s free space information.</p> + <p> + The only value currently valid in this field is ‘0’, + which indicates that the file’s free space is as described <a + href="#FreeSpaceManager">below</a>. + </p> + + <p> + <em>This field is present in version 0 and 1 of the + superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Version Number of the Root Group Symbol Table Entry</p></td> + <td><p>This value is used to determine the format of the + information in the Root Group Symbol Table Entry. When the format + of the information in that field is changed, the version number is + incremented to the next integer and can be used to determine how + the information in the field is formatted.</p> + <p> + The only value currently valid in this field is ‘0’, + which indicates that the root group symbol table entry is formatted + as described <a href="#SymbolTableEntry">below</a>. + </p> + <p> + <em>This field is present in version 0 and 1 of the + superblock.</em> + </p></td> + </tr> + + <tr> + <td><p>Version Number of the Shared Header Message Format</p></td> + <td><p>This value is used to determine the format of the + information in a shared object header message. Since the format of + the shared header messages differs from the other private header + messages, a version number is used to identify changes in the + format.</p> + <p> + The only value currently valid in this field is ‘0’, + which indicates that shared header messages are formatted as + described <a href="#ObjectHeaderMessages">below</a>. + </p> + + <p> + <em>This field is present in version 0 and 1 of the + superblock.</em> + </p></td> + </tr> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> + <td><p>Size of Offsets</p></td> + <td><p>This value contains the number of bytes used to store + addresses in the file. The values for the addresses of objects in + the file are offsets relative to a base address, usually the + address of the superblock signature. This allows a wrapper to be + added after the file is created without invalidating the internal + offset locations.</p> + + <p> + <em>This field is present in version 0+ of the superblock.</em> + </p></td> + </tr> <tr> - <td>Version</td> - <td colspan="3">Reserved</td> + <td><p>Size of Lengths</p></td> + <td><p>This value contains the number of bytes used to store + the size of an object.</p> + <p> + <em>This field is present in version 0+ of the superblock.</em> + </p></td> </tr> <tr> - <td colspan="4">Driver Information Size</td> + <td><p>Group Leaf Node K</p></td> + <td> + <p>Each leaf node of a group B-tree will have at least this many + entries but not more than twice this many. If a group has a single + leaf node then it may have fewer entries.</p> + <p>This value must be greater than zero.</p> + <p> + See the <a href="#Btrees">description</a> of B-trees below. + </p> + + <p> + <em>This field is present in version 0 and 1 of the + superblock.</em> + </p> + </td> </tr> <tr> - <td colspan="4"><br />Driver Identification (8 bytes)<br /><br /></td> + <td><p>Group Internal Node K</p></td> + <td> + <p>Each internal node of a group B-tree will have at least this + many entries but not more than twice this many. If the group has + only one internal node then it might have fewer entries.</p> + <p>This value must be greater than zero.</p> + <p> + See the <a href="#Btrees">description</a> of B-trees below. + </p> + + <p> + <em>This field is present in version 0 and 1 of the + superblock.</em> + </p> + </td> </tr> <tr> - <td colspan="4"><br /><br />Driver Information (<em>variable size</em>)<br /><br /><br /></td> + <td><p>File Consistency Flags</p></td> + <td> + <p>This value contains flags to indicate information about the + consistency of the information contained within the file. + Currently, the following bit flags are defined:</p> + <ul> + <li>Bit 0 set indicates that the file is opened for + write-access.</li> + <li>Bit 1 set indicates that the file has been verified for + consistency and is guaranteed to be consistent with the format + defined in this document.</li> + <li>Bits 2-31 are reserved for future use.</li> + </ul> Bit 0 should be set as the first action when a file is opened for + write access and should be cleared only as the final action when + closing a file. Bit 1 should be cleared during normal access to a + file and only set after the file’s consistency is guaranteed + by the library or a consistency utility. + <p></p> + + <p> + <em>This field is present in version 0+ of the superblock.</em> + </p> + </td> </tr> - </table> - </div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <tr> + <td><p>Indexed Storage Internal Node K</p></td> + <td> + <p>Each internal node of an indexed storage B-tree will have at + least this many entries but not more than twice this many. If the + index storage B-tree has only one internal node then it might have + fewer entries.</p> + <p>This value must be greater than zero.</p> + <p> + See the <a href="#Btrees">description</a> of B-trees below. + </p> + + <p> + <em>This field is present in version 1 of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Base Address</p></td> + <td> + <p>This is the absolute file address of the first byte of the + HDF5 data within the file. The library currently constrains this + value to be the absolute file address of the superblock itself when + creating new files; future versions of the library may provide + greater flexibility. When opening an existing file and this address + does not match the offset of the superblock, the library assumes + that the entire contents of the HDF5 file have been adjusted in the + file and adjusts the base address and end of file address to + reflect their new positions in the file. Unless otherwise noted, + all other file addresses are relative to this base address.</p> + + <p> + <em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Address of Global Free-space Index</p></td> + <td> + <p> + The file’s free space is not persistent for version 0 and 1 + of the superblock. Currently this field always contains the <a + href="#UndefinedAddress">undefined address</a>. + </p> + + <p> + <em>This field is present in version 0 and 1 of the + superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>End of File Address</p></td> + <td> + <p>This is the absolute file address of the first byte past the + end of all HDF5 data. It is used to determine whether a file has + been accidentally truncated and as an address where file data + allocation can occur if space from the free list is not used.</p> + + <p> + <em>This field is present in version 0+ of the superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Driver Information Block Address</p></td> + <td> + <p> + This is the relative file address of the file driver information + block which contains driver-specific information needed to reopen + the file. If there is no driver information block then this entry + should be the <a href="#UndefinedAddress">undefined address</a>. + </p> + + <p> + <em>This field is present in version 0 and 1 of the + superblock.</em> + </p> + </td> + </tr> + + <tr> + <td><p>Root Group Symbol Table Entry</p></td> + <td> + <p> + This is the <a href="#SymbolTableEntry">symbol table entry</a> of + the root group, which serves as the entry point into the group + graph for the file. + </p> + + <p> + <em>This field is present in version 0 and 1 of the + superblock.</em> + </p> + </td> + </tr> + </table> +</div> + +<br /> +<p>Version 2 of the superblock is described below:</p> + +<div align="center"> + <table class="format"> + <caption>Superblock (Version 2)</caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td><p>Version</p></td> - <td> - <p>The version number of the Driver Information Block. - This document describes version 0. - </p> - </td> + <td colspan="4"><br />Format Signature (8 bytes)<br /> + <br /></td> </tr> <tr> - <td><p>Driver Information Size</p></td> - <td> - <p>The size in bytes of the <em>Driver Information</em> field. - </p> - </td> + <td>Version # of Superblock</td> + <td>Size of Offsets</td> + <td>Size of Lengths</td> + <td>File Consistency Flags</td> </tr> <tr> - <td><p>Driver Identification</p></td> - <td> - <p>This is an eight-byte ASCII string without null - termination which identifies the driver and/or version number - of the Driver Information Block. The predefined driver encoded - in this field by the HDF5 Library is identified by the - letters <code>NCSA</code> followed by the first four characters of - the driver name. If the Driver Information block is not - the original version then the last letter(s) of the - identification will be replaced by a version number in - ASCII, starting with 0. - </p> - <p> - Identification for user-defined drivers is also eight-byte long. - It can be arbitrary but should be unique to avoid - the four character prefix “NCSA”. - </p> - </td> + <td colspan="4"><br />Base Address<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Superblock Extension Address<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of File Address<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Root Group Object Header Address<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4">Superblock Checksum</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets.”)</td> + </tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Format Signature</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of + the superblock.</p> + </td> + </tr> + + <tr> + <td><p>Version Number of the Superblock</p></td> + <td> + <p>This field has a value of 2 and has the same meaning as for + versions 0 and 1.</p> + </td> + </tr> + + <tr> + <td><p>Size of Offsets</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of + the superblock.</p> + </td> + </tr> + + <tr> + <td><p>Size of Lengths</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of + the superblock.</p> + </td> + </tr> + + <tr> + <td><p>File Consistency Flags</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 + except that it is smaller (the number of reserved bits has been + reduced from 30 to 6).</p> + </td> + </tr> + + <tr> + <td><p>Base Address</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of + the superblock.</p> + </td> + </tr> + + <tr> + <td><p>Superblock Extension Address</p></td> + <td> + <p> + The field is the address of the object header for the <a + href="#SuperblockExt">superblock extension</a>. If there is no + extension then this entry should be the <a href="#UndefinedAddress">undefined + address</a>. + </p> + </td> + </tr> + + <tr> + <td><p>End of File Address</p></td> + <td> + <p>This field is the same as described for versions 0 and 1 of + the superblock.</p> + </td> + </tr> + + <tr> + <td><p>Root Group Object Header Address</p></td> + <td> + <p> + This is the address of the <a href="#DataObject">root group + object header</a>, which serves as the entry point into the group + graph for the file. + </p> + </td> + </tr> + + <tr> + <td><p>Superblock Checksum</p></td> + <td> + <p>The checksum for the superblock.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<h3> + <a name="DriverInfo"> II.B. Disk Format: Level 0B - File Driver + Info</a> +</h3> + +<p> + The <b>driver information block</b> is an optional region of the file + which contains information needed by the file driver to reopen a file. + The format is described below: +</p> + + +<div align="center"> + <table class="format"> + <caption>Driver Information Block</caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved</td> + </tr> + + <tr> + <td colspan="4">Driver Information Size</td> + </tr> + + <tr> + <td colspan="4"><br />Driver Identification (8 bytes)<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br /> + <br />Driver Information (<em>variable size</em>)<br /> + <br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number of the Driver Information Block. This + document describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Driver Information Size</p></td> + <td> + <p> + The size in bytes of the <em>Driver Information</em> field. + </p> + </td> + </tr> + + <tr> + <td><p>Driver Identification</p></td> + <td> + <p> + This is an eight-byte ASCII string without null termination which + identifies the driver and/or version number of the Driver + Information Block. The predefined driver encoded in this field by + the HDF5 Library is identified by the letters + <code>NCSA</code> + followed by the first four characters of the driver name. If the + Driver Information block is not the original version then the last + letter(s) of the identification will be replaced by a version + number in ASCII, starting with 0. + </p> + <p>Identification for user-defined drivers is also eight-byte + long. It can be arbitrary but should be unique to avoid the four + character prefix “NCSA”.</p> + </td> </tr> <tr valign="top"> - <td><p>Driver Information</p></td> - <td>Driver information is stored in a format defined by the - file driver (see description below).</td> + <td><p>Driver Information</p></td> + <td>Driver information is stored in a format defined by the file + driver (see description below).</td> </tr> - </table> - </div> + </table> +</div> + +<br /> The two drivers encoded in the +<em>Driver Identification</em> field are as follows: +<ul> + <li>Multi driver: + <p>The identifier for this driver is “NCSAmulti”. This + driver provides a mechanism for segregating raw data and different + types of metadata into multiple files. These files are viewed by the + library as a single virtual HDF5 file with a single file address. A + maximum of 6 files will be created for the following data: + superblock, B-tree, raw data, global heap, local heap, and object + header. More than one type of data can be written to the same file.</p> + </li> + <li>Family driver + <p>The identifier for this driver is “NCSAfami” and is + encoded in this field for library version 1.8 and after. This driver + is designed for systems that do not support files larger than 2 + gigabytes by splitting the HDF5 file address space across several + smaller files. It does nothing to segregate metadata and raw data; + they are mixed in the address space just as they would be in a single + contiguous file.</p> + </li> +</ul> +<p> + The format of the <em>Driver Information</em> field for the above two + drivers are described below: +</p> - <br /> - The two drivers encoded in the <em>Driver Identification</em> field are as follows: - <ul> - <li> - Multi driver: - <p> - The identifier for this driver is “NCSAmulti”. - This driver provides a mechanism for segregating raw data and different types of metadata - into multiple files. - These files are viewed by the library as a single virtual HDF5 file with a single file address. - A maximum of 6 files will be created for the following data: - superblock, B-tree, raw data, global heap, local heap, and object header. - More than one type of data can be written to the same file. - </p></li> - <li> - Family driver - <p> - The identifier for this driver is “NCSAfami” and is encoded in this field for library version 1.8 and after. - This driver is designed for systems that do not support files larger than 2 gigabytes - by splitting the HDF5 file address space across several smaller files. - It does nothing to segregate metadata and raw data; - they are mixed in the address space just as they would be in a single contiguous file. - </p></li> - </ul> - <p>The format of the <em>Driver Information</em> field for the - above two drivers are described below:</p> - - <div align="center"> - <table class="format"> - <caption> - Multi Driver Information - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Member Mapping</td> - <td>Member Mapping</td> - <td>Member Mapping</td> - <td>Member Mapping</td> - </tr> - - <tr> - <td>Member Mapping</td> - <td>Member Mapping</td> - <td>Reserved</td> - <td>Reserved</td> - </tr> - - <tr> - <td colspan="4"><br />Address of Member File 1<br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />End of Address for Member File 1<br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Address of Member File 2<br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />End of Address for Member File 2<br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />... ...<br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Address of Member File N<br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />End of Address for Member File N<br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Name of Member File 1 <em>(variable size)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Name of Member File 2 <em>(variable size)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />... ...<br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Name of Member File N <em>(variable size)</em><br /><br /></td> - </tr> +<div align="center"> + <table class="format"> + <caption>Multi Driver Information</caption> - </table> - </div> + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> + <tr> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Member Mapping</td> + </tr> + + <tr> + <td>Member Mapping</td> + <td>Member Mapping</td> + <td>Reserved</td> + <td>Reserved</td> + </tr> + + <tr> + <td colspan="4"><br />Address of Member File 1<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of Address for Member File 1<br /> + <br /></td> + </tr> - <tr> - <td><p>Member Mapping</p></td> - <td><p>These fields are integer values from 1 to 6 - indicating how the data can be mapped to or merged with another type of - data. - <table class="list"> + <tr> + <td colspan="4"><br />Address of Member File 2<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of Address for Member File 2<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />... ...<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of Member File N<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />End of Address for Member File N<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Name of Member File 1 <em>(variable + size)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Name of Member File 2 <em>(variable + size)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />... ...<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Name of Member File N <em>(variable + size)</em><br /> + <br /></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Member Mapping</p></td> + <td><p>These fields are integer values from 1 to 6 + indicating how the data can be mapped to or merged with another + type of data.</p> + <table class="list"> <tr> - <th width="20%" align="center">Member Mapping</th> - <th width="80%" align="left">Description</th> + <th width="20%" align="center">Member Mapping</th> + <th width="80%" align="left">Description</th> </tr> <tr> <td align="center">1</td> @@ -1261,4097 +1399,4089 @@ II.B. Disk Format: Level 0B - File Driver Info</a></h3> <td align="center">6</td> <td>The object header data.</td> </tr> - </table></p> - <p>For example, if the third field has the value 3 and all the rest have the - value 1, it means there are two files: one for raw data, and one for superblock, - B-tree, global heap, local heap, and object header.</p> - </td> - </tr> - - <tr> - <td><p>Reserved</p></td> - <td><p>These fields are reserved and should always be zero.</p></td> - </tr> - - <tr> - <td><p>Address of Member File N</p></td> - <td><p>This field Specifies the virtual address at which the member file starts.</p> - <p>N is the number of member files.</p> - </td> - </tr> - - <tr> - <td><p>End of Address for Member File N</p></td> - <td><p>This field is the end of the allocated address for the member file. - </p></td> - </tr> - - <tr> - <td><p>Name of Member File N</p></td> - <td><p>This field is the null-terminated name of the member file and - its length should be multiples of 8 bytes. - Additional bytes will be padded with <em>NULL</em>s. The default naming - convention is <em>%s-X.h5</em>, where <em>X</em> is one of the letters - <em>s</em> (for superblock), <em>b</em> (for B-tree), <em>r</em> (for raw data), - <em>g</em> (for global heap), <em>l</em> (for local heap), and <em>o</em> (for - object header). The name of the whole HDF5 file will substitute the <em>%s</em> - in the string. - </p> - </td> - </tr> - </table> - </div> + </table> + <p></p> + <p>For example, if the third field has the value 3 and all the + rest have the value 1, it means there are two files: one for raw + data, and one for superblock, B-tree, global heap, local heap, and + object header.</p></td> + </tr> - <br /> - <div align="center"> - <table class="format"> - <caption> - Family Driver Information - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td colspan="8"><br />Size of Member File<br /><br /></td> - </tr> + <tr> + <td><p>Reserved</p></td> + <td><p>These fields are reserved and should always be zero.</p></td> + </tr> - </table> - </div> + <tr> + <td><p>Address of Member File N</p></td> + <td><p>This field Specifies the virtual address at which the + member file starts.</p> + <p>N is the number of member files.</p></td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Size of Member File</p></td> - <td><p>This field is the size of the member file in the family of files.</p></td> - </tr> - </table> - </div> + <tr> + <td><p>End of Address for Member File N</p></td> + <td><p>This field is the end of the allocated address for + the member file.</p></td> + </tr> + + <tr> + <td><p>Name of Member File N</p></td> + <td><p> + This field is the null-terminated name of the member file and its + length should be multiples of 8 bytes. Additional bytes will be + padded with <em>NULL</em>s. The default naming convention is <em>%s-X.h5</em>, + where <em>X</em> is one of the letters <em>s</em> (for superblock), + <em>b</em> (for B-tree), <em>r</em> (for raw data), <em>g</em> (for + global heap), <em>l</em> (for local heap), and <em>o</em> (for + object header). The name of the whole HDF5 file will substitute the + <em>%s</em> in the string. + </p></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="format"> + <caption>Family Driver Information</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="8"><br />Size of Member File<br /> + <br /></td> + </tr> + + </table> +</div> <br /> -<h3><a name="SuperblockExt"> -II.C. Disk Format: Level 0C - Superblock Extension</a></h3> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Size of Member File</p></td> + <td><p>This field is the size of the member file in the + family of files.</p></td> + </tr> + </table> +</div> - <p>The <em>superblock extension</em> is used to store superblock metadata - which is either optional, or added after the version of the superblock - was defined. Superblock extensions may only exist when version 2+ of - superblock is used. A superblock extension is an object header which may - hold the following messages:</p> - <ul> - <li> - <a href="#SOHMTableMessage">Shared Message Table message</a> containing - information to locate the master table of shared object header message - indices.</li> - <li> - <a href="#BtreeKValuesMessage">B-tree ‘K’ Values message</a> containing - non-default B-tree ‘K’ values.</li> - <li> - <a href="#DrvInfoMessage">Driver Info message</a> containing information - needed by the file driver in order to reopen a file. - See also the - <a href="#DriverInfo">“Disk Format: Level 0B - File Driver - Info”</a> section above.</li> - <li> - <a href="#FsinfoMessage">File Space Info message</a> containing - information about file space handling in the file.</li> - </ul> +<br /> +<h3> + <a name="SuperblockExt"> II.C. Disk Format: Level 0C - Superblock + Extension</a> +</h3> + +<p> + The <em>superblock extension</em> is used to store superblock metadata + which is either optional, or added after the version of the superblock + was defined. Superblock extensions may only exist when version 2+ of + superblock is used. A superblock extension is an object header which + may hold the following messages: +</p> +<ul> + <li><a href="#SOHMTableMessage">Shared Message Table message</a> + containing information to locate the master table of shared object + header message indices.</li> + <li><a href="#BtreeKValuesMessage">B-tree ‘K’ + Values message</a> containing non-default B-tree ‘K’ values.</li> + <li><a href="#DrvInfoMessage">Driver Info message</a> containing + information needed by the file driver in order to reopen a file. See + also the <a href="#DriverInfo">“Disk Format: Level 0B - File + Driver Info”</a> section above.</li> + <li><a href="#FsinfoMessage">File Space Info message</a> + containing information about file space handling in the file.</li> +</ul> <br /> <br /> <hr /> -<h2><a name="FileInfra"> -III. Disk Format: Level 1 - File Infrastructure</a></h2> - -<br /> -<h3><a name="Btrees"> -III.A. Disk Format: Level 1A - B-trees and B-tree Nodes</a></h3> - - <p>B-trees allow flexible storage for objects which tend to grow - in ways that cause the object to be stored discontiguously. B-trees - are described in various algorithms books including “Introduction to - Algorithms” by Thomas H. Cormen, Charles E. Leiserson, and Ronald - L. Rivest. B-trees are used in several places in the HDF5 file format, - when an index is needed for another data structure.</p> - - <p>The version 1 B-tree structure described below is the original index - structure, but are limited by some bugs in our implementation (mainly in - how they handle deleting records). The version 1 B-trees are being phased - out in favor of the version 2 B-trees described below, although both - types of structures may be found in the same file, depending on - application settings when creating the file.</p> - -<br /> -<h4><a name="V1Btrees"> -III.A.1. Disk Format: Level 1A1 - Version 1 B-trees (B-link Trees)</a></h4> - - <p>Version 1 B-trees in HDF5 files an implementation of the B-link tree, - in which the sibling nodes at a particular level in the tree are stored - in a doubly-linked list, is described in the “Efficient Locking for - Concurrent Operations on B-trees” paper by Phillip Lehman and S. Bing Yao - as published in the <cite>ACM Transactions on Database Systems</cite>, - Vol. 6, No. 4, December 1981.</p> - - <p>The B-link trees implemented by the file format contain one more - key than the number of children. In other words, each child - pointer out of a B-tree node has a left key and a right key. - The pointers out of internal nodes point to sub-trees while - the pointers out of leaf nodes point to symbol nodes and - raw data chunks. - Aside from that difference, internal nodes and leaf nodes - are identical.</p> - - <div align="center"> - <table class="format"> - <caption> - B-link Tree Nodes - </caption> +<h2> + <a name="FileInfra"> III. Disk Format: Level 1 - File + Infrastructure</a> +</h2> + +<br /> +<h3> + <a name="Btrees"> III.A. Disk Format: Level 1A - B-trees and B-tree + Nodes</a> +</h3> + +<p>B-trees allow flexible storage for objects which tend to grow in + ways that cause the object to be stored discontiguously. B-trees are + described in various algorithms books including “Introduction to + Algorithms” by Thomas H. Cormen, Charles E. Leiserson, and Ronald + L. Rivest. B-trees are used in several places in the HDF5 file format, + when an index is needed for another data structure.</p> + +<p>The version 1 B-tree structure described below is the original + index structure, but are limited by some bugs in our implementation + (mainly in how they handle deleting records). The version 1 B-trees are + being phased out in favor of the version 2 B-trees described below, + although both types of structures may be found in the same file, + depending on application settings when creating the file.</p> + +<br /> +<h4> + <a name="V1Btrees"> III.A.1. Disk Format: Level 1A1 - Version 1 + B-trees (B-link Trees)</a> +</h4> + +<p> + Version 1 B-trees in HDF5 files an implementation of the B-link tree, + in which the sibling nodes at a particular level in the tree are stored + in a doubly-linked list, is described in the “Efficient Locking + for Concurrent Operations on B-trees” paper by Phillip Lehman and + S. Bing Yao as published in the <cite>ACM Transactions on + Database Systems</cite>, Vol. 6, No. 4, December 1981. +</p> + +<p>The B-link trees implemented by the file format contain one more + key than the number of children. In other words, each child pointer out + of a B-tree node has a left key and a right key. The pointers out of + internal nodes point to sub-trees while the pointers out of leaf nodes + point to symbol nodes and raw data chunks. Aside from that difference, + internal nodes and leaf nodes are identical.</p> + +<div align="center"> + <table class="format"> + <caption>B-link Tree Nodes</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Signature</td> + <td colspan="4">Signature</td> </tr> <tr> - <td>Node Type</td> - <td>Node Level</td> - <td colspan="2">Entries Used</td> + <td>Node Type</td> + <td>Node Level</td> + <td colspan="2">Entries Used</td> </tr> <tr> - <td colspan="4"><br />Address of Left Sibling<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address of Left Sibling<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Address of Right Sibling<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address of Right Sibling<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4">Key 0 (variable size)</td> + <td colspan="4">Key 0 (variable size)</td> </tr> <tr> - <td colspan="4"><br />Address of Child 0<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address of Child 0<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4">Key 1 (variable size)</td> + <td colspan="4">Key 1 (variable size)</td> </tr> <tr> - <td colspan="4"><br />Address of Child 1<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address of Child 1<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4">...</td> + <td colspan="4">...</td> </tr> <tr> - <td colspan="4">Key 2<em>K</em> (variable size)</td> + <td colspan="4">Key 2<em>K</em> (variable size) + </td> </tr> <tr> - <td colspan="4"><br />Address of Child 2<em>K</em><sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address of Child 2<em>K</em><sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4">Key 2<em>K</em>+1 (variable size)</td> + <td colspan="4">Key 2<em>K</em>+1 (variable size) + </td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>TREE</code>” is - used to indicate the - beginning of a B-link tree node. This gives file - consistency checking utilities a better chance of - reconstructing a damaged file. - </p> - </td> - </tr> - - <tr> - <td><p>Node Type</p></td> - <td> - <p>Each B-link tree points to a particular type of data. - This field indicates the type of data as well as - implying the maximum degree <em>K</em> of the tree and - the size of each Key field. - - - <table class="list"> - <tr> - <th width="20%" align="center">Node Type</th> - <th width="80%" align="left">Description</th> - </tr> - <tr> - <td align="center">0</td> - <td>This tree points to group nodes.</td> - </tr> - <tr> - <td align="center">1</td> - <td>This tree points to raw data chunk nodes.</td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Node Level</p></td> - <td> - <p>The node level indicates the level at which this node - appears in the tree (leaf nodes are at level zero). Not - only does the level indicate whether child pointers - point to sub-trees or to data, but it can also be used - to help file consistency checking utilities reconstruct - damaged trees. - </p> - </td> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>TREE</code> + ” is used to indicate the beginning of a B-link tree node. + This gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Node Type</p></td> + <td> + <p> + Each B-link tree points to a particular type of data. This field + indicates the type of data as well as implying the maximum degree <em>K</em> + of the tree and the size of each Key field. + + + </p> + <table class="list"> + <tr> + <th width="20%" align="center">Node Type</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>This tree points to group nodes.</td> + </tr> + <tr> + <td align="center">1</td> + <td>This tree points to raw data chunk nodes.</td> + </tr> + </table> + <p></p> + </td> + </tr> + + <tr> + <td><p>Node Level</p></td> + <td> + <p>The node level indicates the level at which this node appears + in the tree (leaf nodes are at level zero). Not only does the level + indicate whether child pointers point to sub-trees or to data, but + it can also be used to help file consistency checking utilities + reconstruct damaged trees.</p> + </td> </tr> <tr valign="top"> - <td><p>Entries Used</p></td> - <td> - <p>This determines the number of children to which this - node points. All nodes of a particular type of tree - have the same maximum degree, but most nodes will point - to less than that number of children. The valid child - pointers and keys appear at the beginning of the node - and the unused pointers and keys appear at the end of - the node. The unused pointers and keys have undefined - values. - </p> - </td> + <td><p>Entries Used</p></td> + <td> + <p>This determines the number of children to which this node + points. All nodes of a particular type of tree have the same + maximum degree, but most nodes will point to less than that number + of children. The valid child pointers and keys appear at the + beginning of the node and the unused pointers and keys appear at + the end of the node. The unused pointers and keys have undefined + values.</p> + </td> </tr> <tr valign="top"> - <td><p>Address of Left Sibling</p></td> - <td> - <p>This is the relative file address of the left sibling of - the current node. If the current - node is the left-most node at this level then this field - is the <a href="#UndefinedAddress">undefined address</a>. - </p> - </td> + <td><p>Address of Left Sibling</p></td> + <td> + <p> + This is the relative file address of the left sibling of the + current node. If the current node is the left-most node at this + level then this field is the <a href="#UndefinedAddress">undefined + address</a>. + </p> + </td> </tr> <tr valign="top"> - <td><p>Address of Right Sibling</p></td> - <td> - <p>This is the relative file address of the right sibling of - the current node. If the current - node is the right-most node at this level then this - field is the <a href="#UndefinedAddress">undefined address</a>. - </p> - </td> + <td><p>Address of Right Sibling</p></td> + <td> + <p> + This is the relative file address of the right sibling of the + current node. If the current node is the right-most node at this + level then this field is the <a href="#UndefinedAddress">undefined + address</a>. + </p> + </td> </tr> <tr valign="top"> - <td><p>Keys and Child Pointers</p></td> - <td> - <p>Each tree has 2<em>K</em>+1 keys with 2<em>K</em> - child pointers interleaved between the keys. The number - of keys and child pointers actually containing valid - values is determined by the node’s <em>Entries Used</em> field. - If that field is <em>N</em> then the B-link tree contains - <em>N</em> child pointers and <em>N</em>+1 keys. - </p> - </td> + <td><p>Keys and Child Pointers</p></td> + <td> + <p> + Each tree has 2<em>K</em>+1 keys with 2<em>K</em> child pointers + interleaved between the keys. The number of keys and child pointers + actually containing valid values is determined by the node’s + <em>Entries Used</em> field. If that field is <em>N</em> then the + B-link tree contains <em>N</em> child pointers and <em>N</em>+1 + keys. + </p> + </td> </tr> <tr valign="top"> - <td><p>Key</p></td> - <td> - <p>The format and size of the key values is determined by - the type of data to which this tree points. The keys are - ordered and are boundaries for the contents of the child - pointer; that is, the key values represented by child - <em>N</em> fall between Key <em>N</em> and Key - <em>N</em>+1. Whether the interval is open or closed on - each end is determined by the type of data to which the - tree points. - </p> - - <p> - The format of the key depends on the node type. - For nodes of node type 0 (group nodes), the key is formatted as - follows: - - <table class="list"> - <tr> - <td width="20%">A single field of <i>Size of Lengths</i> - bytes:</td> - <td width="80%">Indicates the byte offset into the local heap - for the first object name in the subtree which - that key describes. - </td> - </tr> - </table> - </p> - - - <p> - For nodes of node type 1 (chunked raw data nodes), the key is - formatted as follows: - - <table class="list"> - <tr> - <td width="20%">Bytes 1-4:</td> - <td width="80%">Size of chunk in bytes.</td> - </tr> - <tr> - <td>Bytes 4-8:</td> - <td>Filter mask, a 32-bit bit field indicating which - filters have been skipped for this chunk. Each filter - has an index number in the pipeline (starting at 0, with - the first filter to apply) and if that filter is skipped, - the bit corresponding to its index is set.</td> - </tr> - <tr> - <td>(<em>D + 1</em>) 64-bit fields:</td> - <td>The offset of the - chunk within the dataset where <i>D</i> is the number - of dimensions of the dataset, and the last value is the - offset within the dataset’s datatype and should always be - zero. For example, if - a chunk in a 3-dimensional dataset begins at the - position <code>[5,5,5]</code>, there will be three - such 64-bit values, each with the value of - <code>5</code>, followed by a <code>0</code> value.</td> - </tr> - </table> - </p> - - </td> + <td><p>Key</p></td> + <td> + <p> + The format and size of the key values is determined by the type of + data to which this tree points. The keys are ordered and are + boundaries for the contents of the child pointer; that is, the key + values represented by child <em>N</em> fall between Key <em>N</em> + and Key <em>N</em>+1. Whether the interval is open or closed on + each end is determined by the type of data to which the tree + points. + </p> + + <p>The format of the key depends on the node type. For nodes of + node type 0 (group nodes), the key is formatted as follows:</p> + <table class="list"> + <tr> + <td width="20%">A single field of <i>Size of Lengths</i> + bytes: + </td> + <td width="80%">Indicates the byte offset into the local heap + for the first object name in the subtree which that key + describes.</td> + </tr> + </table> + <p></p> + + + <p>For nodes of node type 1 (chunked raw data nodes), the key is + formatted as follows:</p> + <table class="list"> + <tr> + <td width="20%">Bytes 1-4:</td> + <td width="80%">Size of chunk in bytes.</td> + </tr> + <tr> + <td>Bytes 4-8:</td> + <td>Filter mask, a 32-bit bit field indicating which filters + have been skipped for this chunk. Each filter has an index number + in the pipeline (starting at 0, with the first filter to apply) + and if that filter is skipped, the bit corresponding to its index + is set.</td> + </tr> + <tr> + <td>(<em>D + 1</em>) 64-bit fields: + </td> + <td>The offset of the chunk within the dataset where <i>D</i> + is the number of dimensions of the dataset, and the last value is + the offset within the dataset’s datatype and should always + be zero. For example, if a chunk in a 3-dimensional dataset + begins at the position <code>[5,5,5]</code>, there will be three + such 64-bit values, each with the value of <code>5</code>, + followed by a <code>0</code> value. + </td> + </tr> + </table> + <p></p> + + </td> </tr> <tr valign="top"> - <td><p>Child Pointer</p></td> - <td> - <p>The tree node contains file addresses of subtrees or - data depending on the node level. Nodes at Level 0 point - to data addresses, either raw data chunks or group nodes. - Nodes at non-zero levels point to other nodes of the - same B-tree. - </p> - <p>For raw data chunk nodes, the child pointer is the address - of a single raw data chunk. For group nodes, the child pointer - points to a <a href="#SymbolTable">symbol table</a>, which contains - information for multiple symbol table entries. - </p> - </td> + <td><p>Child Pointer</p></td> + <td> + <p>The tree node contains file addresses of subtrees or data + depending on the node level. Nodes at Level 0 point to data + addresses, either raw data chunks or group nodes. Nodes at non-zero + levels point to other nodes of the same B-tree.</p> + <p> + For raw data chunk nodes, the child pointer is the address of a + single raw data chunk. For group nodes, the child pointer points to + a <a href="#SymbolTable">symbol table</a>, which contains + information for multiple symbol table entries. + </p> + </td> </tr> - </table> - </div> - - <p> - Conceptually, each B-tree node looks like this:</p> - <center> - <table> - <tr valign="top" align="center"> - <td>key[0]</td><td> </td> - <td>child[0]</td><td> </td> - <td>key[1]</td><td> </td> - <td>child[1]</td><td> </td> - <td>key[2]</td><td> </td> - <td>...</td><td> </td> - <td>...</td><td> </td> - <td>key[<i>N</i>-1]</td><td> </td> - <td>child[<i>N</i>-1]</td><td> </td> - <td>key[<i>N</i>]</td> - </tr> - </table> - </center> - <br /> - - where child[<i>i</i>] is a pointer to a sub-tree (at a level - above Level 0) or to data (at Level 0). - Each key[<i>i</i>] describes an <i>item</i> stored by the B-tree - (a chunk or an object of a group node). The range of values - represented by child[<i>i</i>] is indicated by key[<i>i</i>] - and key[<i>i</i>+1]. - - - <p>The following question must next be answered: - “Is the value described by key[<i>i</i>] contained in - child[<i>i</i>-1] or in child[<i>i</i>]?” - The answer depends on the type of tree. - In trees for groups (node type 0) the object described by - key[<i>i</i>] is the greatest object contained in - child[<i>i</i>-1] while in chunk trees (node type 1) the - chunk described by key[<i>i</i>] is the least chunk in - child[<i>i</i>].</p> - - <p>That means that key[0] for group trees is sometimes unused; - it points to offset zero in the heap, which is always the - empty string and compares as “less-than” any valid object name.</p> - - <p>And key[<i>N</i>] for chunk trees is sometimes unused; - it contains a chunk offset which compares as “greater-than” - any other chunk offset and has a chunk byte size of zero - to indicate that it is not actually allocated.</p> - -<br /> -<h4><a name="V2Btrees"> -III.A.2. Disk Format: Level 1A2 - Version 2 B-trees</a></h4> - - <p>Version 2 B-trees are “traditional” B-trees, with one major difference. - Instead of just using a simple pointer (or address in the file) to a - child of an internal node, the pointer to the child node contains two - additional pieces of information: the number of records in the child - node itself, and the total number of records in the child node and - all its descendants. Storing this additional information allows fast - array-like indexing to locate the n<sup>th</sup> record in the B-tree.</p> - - <p>The entry into a version 2 B-tree is a header which contains global - information about the structure of the B-tree. The <em>root node - address</em> - field in the header points to the B-tree root node, which is either an - internal or leaf node, depending on the value in the header’s - <em>depth</em> field. An internal node consists of records plus - pointers to further leaf or internal nodes in the tree. A leaf node - consists of solely of records. The format of the records depends on - the B-tree type (stored in the header).</p> - - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree Header - </caption> + </table> +</div> + +<p>Conceptually, each B-tree node looks like this:</p> +<center> + <table> + <tr valign="top" align="center"> + <td>key[0]</td> + <td> </td> + <td>child[0]</td> + <td> </td> + <td>key[1]</td> + <td> </td> + <td>child[1]</td> + <td> </td> + <td>key[2]</td> + <td> </td> + <td>...</td> + <td> </td> + <td>...</td> + <td> </td> + <td>key[<i>N</i>-1] + </td> + <td> </td> + <td>child[<i>N</i>-1] + </td> + <td> </td> + <td>key[<i>N</i>] + </td> + </tr> + </table> +</center> +<br /> where child[ +<i>i</i>] is a pointer to a sub-tree (at a level above Level 0) or to +data (at Level 0). Each key[ +<i>i</i>] describes an +<i>item</i> stored by the B-tree (a chunk or an object of a group node). +The range of values represented by child[ +<i>i</i>] is indicated by key[ +<i>i</i>] and key[ +<i>i</i>+1]. + + +<p> + The following question must next be answered: “Is the value + described by key[<i>i</i>] contained in child[<i>i</i>-1] or in child[<i>i</i>]?” + The answer depends on the type of tree. In trees for groups (node type + 0) the object described by key[<i>i</i>] is the greatest object + contained in child[<i>i</i>-1] while in chunk trees (node type 1) the + chunk described by key[<i>i</i>] is the least chunk in child[<i>i</i>]. +</p> + +<p>That means that key[0] for group trees is sometimes unused; it + points to offset zero in the heap, which is always the empty string and + compares as “less-than” any valid object name.</p> + +<p> + And key[<i>N</i>] for chunk trees is sometimes unused; it contains a + chunk offset which compares as “greater-than” any other + chunk offset and has a chunk byte size of zero to indicate that it is + not actually allocated. +</p> + +<br /> +<h4> + <a name="V2Btrees"> III.A.2. Disk Format: Level 1A2 - Version 2 + B-trees</a> +</h4> + +<p> + Version 2 B-trees are “traditional” B-trees, with one major + difference. Instead of just using a simple pointer (or address in the + file) to a child of an internal node, the pointer to the child node + contains two additional pieces of information: the number of records in + the child node itself, and the total number of records in the child + node and all its descendants. Storing this additional information + allows fast array-like indexing to locate the n<sup>th</sup> record in + the B-tree. +</p> + +<p> + The entry into a version 2 B-tree is a header which contains global + information about the structure of the B-tree. The <em>root node + address</em> field in the header points to the B-tree root node, which is + either an internal or leaf node, depending on the value in the + header’s <em>depth</em> field. An internal node consists of + records plus pointers to further leaf or internal nodes in the tree. A + leaf node consists of solely of records. The format of the records + depends on the B-tree type (stored in the header). +</p> + +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree Header</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - - <tr> - <td colspan="4">Signature</td> - </tr> - <tr> - <td>Version</td> - <td>Type</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - <tr> - <td colspan="4">Node Size</td> - </tr> - <tr> - <td colspan="2">Record Size</td> - <td colspan="2">Depth</td> - </tr> - <tr> - <td>Split Percent</td> - <td>Merge Percent</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - <tr> - <td colspan="4"><br />Root Node Address<sup>O</sup><br /><br /></td> - </tr> - <tr> - <td colspan="2">Number of Records in Root Node</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - <tr> - <td colspan="4"><br />Total Number of Records in B-tree<sup>L</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4">Checksum</td> - </tr> - </table> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> - <table class="note"> + </tr> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td colspan="4">Signature</td> + </tr> <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td>Version</td> + <td>Type</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Node Size</td> + </tr> + <tr> + <td colspan="2">Record Size</td> + <td colspan="2">Depth</td> + </tr> + <tr> + <td>Split Percent</td> + <td>Merge Percent</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Root Node Address<sup>O</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="2">Number of Records in Root Node</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Total Number of Records in B-tree<sup>L</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> - </div> + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + <tr> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>BTHD</code>” is - used to indicate the header of a version 2 B-link tree node. - </p> - </td> - </tr> - - <tr> - <td><p>Version</p></td> - <td> - <p>The version number for this B-tree header. This document - describes version 0. - </p> - </td> - </tr> - - <tr> - <td><p>Type</p></td> - <td> - <p>This field indicates the type of B-tree: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - <tr> - <td align="center">0</td> - <td>A “testing” B-tree, this value should <em>not</em> be - used for storing records in actual HDF5 files. - </td> - </tr> - <tr> - <td align="center">1</td> - <td>This B-tree is used for indexing indirectly accessed, - non-filtered ‘huge’ fractal heap objects. - </td> - </tr> - <tr> - <td align="center">2</td> - <td>This B-tree is used for indexing indirectly accessed, - filtered ‘huge’ fractal heap objects. - </td> - </tr> - <tr> - <td align="center">3</td> - <td>This B-tree is used for indexing directly accessed, - non-filtered ‘huge’ fractal heap objects. - </td> - </tr> - <tr> - <td align="center">4</td> - <td>This B-tree is used for indexing directly accessed, - filtered ‘huge’ fractal heap objects. - </td> - </tr> - <tr> - <td align="center">5</td> - <td>This B-tree is used for indexing the ‘name’ field for - links in indexed groups. - </td> - </tr> - <tr> - <td align="center">6</td> - <td>This B-tree is used for indexing the ‘creation order’ - field for links in indexed groups. - </td> - </tr> - <tr> - <td align="center">7</td> - <td>This B-tree is used for indexing shared object header - messages. - </td> - </tr> - <tr> - <td align="center">8</td> - <td>This B-tree is used for indexing the ‘name’ field for - indexed attributes. - </td> - </tr> - <tr> - <td align="center">9</td> - <td>This B-tree is used for indexing the ‘creation order’ - field for indexed attributes. - </td> - </tr> - </table></p> - <p>The format of records for each type is described below.</p> - </td> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>BTHD</code> + ” is used to indicate the header of a version 2 B-link tree + node. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number for this B-tree header. This document + describes version 0.</p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td> + <p>This field indicates the type of B-tree:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>A “testing” B-tree, this value should <em>not</em> + be used for storing records in actual HDF5 files. + </td> + </tr> + <tr> + <td align="center">1</td> + <td>This B-tree is used for indexing indirectly accessed, + non-filtered ‘huge’ fractal heap objects.</td> + </tr> + <tr> + <td align="center">2</td> + <td>This B-tree is used for indexing indirectly accessed, + filtered ‘huge’ fractal heap objects.</td> + </tr> + <tr> + <td align="center">3</td> + <td>This B-tree is used for indexing directly accessed, + non-filtered ‘huge’ fractal heap objects.</td> + </tr> + <tr> + <td align="center">4</td> + <td>This B-tree is used for indexing directly accessed, + filtered ‘huge’ fractal heap objects.</td> + </tr> + <tr> + <td align="center">5</td> + <td>This B-tree is used for indexing the ‘name’ + field for links in indexed groups.</td> + </tr> + <tr> + <td align="center">6</td> + <td>This B-tree is used for indexing the ‘creation + order’ field for links in indexed groups.</td> + </tr> + <tr> + <td align="center">7</td> + <td>This B-tree is used for indexing shared object header + messages.</td> + </tr> + <tr> + <td align="center">8</td> + <td>This B-tree is used for indexing the ‘name’ + field for indexed attributes.</td> + </tr> + <tr> + <td align="center">9</td> + <td>This B-tree is used for indexing the ‘creation + order’ field for indexed attributes.</td> + </tr> + </table> + <p></p> + <p>The format of records for each type is described below.</p> + </td> </tr> <tr valign="top"> - <td><p>Node Size</p></td> - <td> - <p>This is the size in bytes of all B-tree nodes. - </p> - </td> + <td><p>Node Size</p></td> + <td> + <p>This is the size in bytes of all B-tree nodes.</p> + </td> </tr> <tr valign="top"> - <td><p>Record Size</p></td> - <td> - <p>This field is the size in bytes of the B-tree record. - </p> - </td> + <td><p>Record Size</p></td> + <td> + <p>This field is the size in bytes of the B-tree record.</p> + </td> </tr> <tr valign="top"> - <td><p>Depth</p></td> - <td> - <p>This is the depth of the B-tree. - </p> - </td> + <td><p>Depth</p></td> + <td> + <p>This is the depth of the B-tree.</p> + </td> </tr> <tr valign="top"> - <td><p>Split Percent</p></td> - <td> - <p>The percent full that a node needs to increase above before it - is split. - </p> - </td> + <td><p>Split Percent</p></td> + <td> + <p>The percent full that a node needs to increase above before + it is split.</p> + </td> </tr> <tr valign="top"> - <td><p>Merge Percent</p></td> - <td> - <p>The percent full that a node needs to be decrease below before it - is split. - </p> - </td> + <td><p>Merge Percent</p></td> + <td> + <p>The percent full that a node needs to be decrease below + before it is split.</p> + </td> </tr> <tr valign="top"> - <td><p>Root Node Address</p></td> - <td> - <p>This is the address of the root B-tree node. A B-tree with - no records will have the <a href="#UndefinedAddress">undefined - address</a> in this field. - </p> - </td> + <td><p>Root Node Address</p></td> + <td> + <p> + This is the address of the root B-tree node. A B-tree with no + records will have the <a href="#UndefinedAddress">undefined + address</a> in this field. + </p> + </td> </tr> <tr valign="top"> - <td><p>Number of Records in Root Node</p></td> - <td> - <p>This is the number of records in the root node. - </p> - </td> + <td><p>Number of Records in Root Node</p></td> + <td> + <p>This is the number of records in the root node.</p> + </td> </tr> <tr valign="top"> - <td><p>Total Number of Records in B-tree</p></td> - <td> - <p>This is the total number of records in the entire B-tree. - </p> - </td> + <td><p>Total Number of Records in B-tree</p></td> + <td> + <p>This is the total number of records in the entire B-tree.</p> + </td> </tr> <tr valign="top"> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for the B-tree header. - </p> - </td> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the B-tree header.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree Internal Node - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree Internal Node</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Signature</td> + <td colspan="4">Signature</td> </tr> <tr> - <td>Version</td> - <td>Type</td> - <td colspan="2">Records 0, 1, 2...N-1 <em>(variable size)</em></td> + <td>Version</td> + <td>Type</td> + <td colspan="2">Records 0, 1, 2...N-1 <em>(variable size)</em></td> </tr> - <tr> - <td colspan="4"><br />Child Node Pointer 0<sup>O</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4"><br />Number of Records N<sub>0</sub> for Child Node 0 <em>(variable size)</em></td> - </tr> - <tr> - <td colspan="4"><br />Total Number of Records for Child Node 0 <em>(optional, variable size)</em></td> - </tr> - <tr> - <td colspan="4"><br />Child Node Pointer 1<sup>O</sup><br /><br /></td> - </tr> - <td colspan="4"><br />Number of Records N<sub>1</sub> for Child Node 1 <em>(variable size)</em></td> - </tr> - <tr> - <td colspan="4"><br />Total Number of Records for Child Node 1 <em>(optional, variable size)</em></td> - </tr> - <tr> - <td colspan="4">...</td> - </tr> - <tr> - <td colspan="4"><br />Child Node Pointer N<sup>O</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4"><br />Number of Records N<sub>n</sub> for Child Node N <em>(variable size)</em></td> - </tr> - <tr> - <td colspan="4"><br />Total Number of Records for Child Node N <em>(optional, variable size)</em></td> - </tr> - <tr> - <td colspan="4">Checksum</td> - </tr> - </table> + <tr> + <td colspan="4"><br />Child Node Pointer 0<sup>O</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4"><br />Number of Records N<sub>0</sub> for Child + Node 0 <em>(variable size)</em></td> + </tr> + <tr> + <td colspan="4"><br />Total Number of Records for Child Node 0 + <em>(optional, variable size)</em></td> + </tr> + <tr> + <td colspan="4"><br />Child Node Pointer 1<sup>O</sup><br /> + <br /></td> + </tr> + <td colspan="4"><br />Number of Records N<sub>1</sub> for Child + Node 1 <em>(variable size)</em></td> + <tr></tr> + <tr> + <td colspan="4"><br />Total Number of Records for Child Node 1 + <em>(optional, variable size)</em></td> + </tr> + <tr> + <td colspan="4">...</td> + </tr> + <tr> + <td colspan="4"><br />Child Node Pointer N<sup>O</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4"><br />Number of Records N<sub>n</sub> for Child + Node N <em>(variable size)</em></td> + </tr> + <tr> + <td colspan="4"><br />Total Number of Records for Child Node N + <em>(optional, variable size)</em></td> + </tr> + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> - </div> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>BTIN</code>” is - used to indicate the internal node of a B-link tree. - </p> - </td> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>BTIN</code> + ” is used to indicate the internal node of a B-link tree. + </p> + </td> </tr> <tr> - <td><p>Version</p></td> - <td> - <p>The version number for this B-tree internal node. - This document describes version 0. - </p> - </td> + <td><p>Version</p></td> + <td> + <p>The version number for this B-tree internal node. This + document describes version 0.</p> + </td> </tr> <tr> - <td><p>Type</p></td> - <td> - <p>This field is the type of the B-tree node. It should always - be the same as the B-tree type in the header. - </p> - </td> + <td><p>Type</p></td> + <td> + <p>This field is the type of the B-tree node. It should always + be the same as the B-tree type in the header.</p> + </td> </tr> <tr> - <td><p>Records</p></td> - <td> - <p>The size of this field is determined by the number of records - for this node and the record size (from the header). The format - of records depends on the type of B-tree. - </p> - </td> + <td><p>Records</p></td> + <td> + <p>The size of this field is determined by the number of records + for this node and the record size (from the header). The format of + records depends on the type of B-tree.</p> + </td> </tr> <tr> - <td><p>Child Node Pointer</p></td> - <td> - <p>This field is the address of the child node pointed to by the - internal node. - </p> - </td> + <td><p>Child Node Pointer</p></td> + <td> + <p>This field is the address of the child node pointed to by the + internal node.</p> + </td> </tr> <tr> - <td><p>Number of Records in Child Node</p></td> - <td> - <p>This is the number of records in the child node pointed to by - the corresponding <em>Node Pointer</em>. - </p> - <p>The number of bytes used to store this field is determined by - the maximum possible number of records able to be stored in the - child node. - </p> - <p> - The maximum number of records in a child node is computed - in the following way: - + <td><p>Number of Records in Child Node</p></td> + <td> + <p> + This is the number of records in the child node pointed to by the + corresponding <em>Node Pointer</em>. + </p> + <p>The number of bytes used to store this field is determined by + the maximum possible number of records able to be stored in the + child node.</p> + <p>The maximum number of records in a child node is computed in + the following way:</p> <ul> - <li>Subtract the fixed size overhead for - the child node (for example, its signature, version, - checksum, and so on and <em>one</em> pointer triplet - of information for the child node (because there is one - more pointer triplet than records in each internal node)) - from the size of nodes for the B-tree. </li> - <li>Divide that result by the size of a record plus the - pointer triplet of information stored to reach each - child node from this node. + <li>Subtract the fixed size overhead for the child node (for + example, its signature, version, checksum, and so on and <em>one</em> + pointer triplet of information for the child node (because there + is one more pointer triplet than records in each internal node)) + from the size of nodes for the B-tree. + </li> + <li>Divide that result by the size of a record plus the + pointer triplet of information stored to reach each child node + from this node.</li> </ul> - </p> - <p> - Note that leaf nodes do not encode any - child pointer triplets, so the maximum number of records in a - leaf node is just the node size minus the leaf node overhead, - divided by the record size. - </p> - <p> - Also note that the first level of internal nodes above the - leaf nodes do not encode the <em>Total Number of Records in Child - Node</em> value in the child pointer triplets (since it is the - same as the <em>Number of Records in Child Node</em>), so the - maximum number of records in these nodes is computed with the - equation above, but using (<em>Child Pointer</em>, <em>Number of - Records in Child Node</em>) pairs instead of triplets. - </p> - <p> - The number of - bytes used to encode this field is the least number of bytes - required to encode the maximum number of records in a child - node value for the child nodes below this level - in the B-tree. - </p> - <p> - For example, if the maximum number of child records is - 123, one byte will be used to encode these values in this - node; if the maximum number of child records is - 20000, two bytes will be used to encode these values in this - node; and so on. The maximum number of bytes used to - encode these values is 8 (in other words, an unsigned - 64-bit integer). - </p> - </td> - </tr> - - <tr> - <td><p>Total Number of Records in Child Node</p></td> - <td> - <p>This is the total number of records for the node pointed to by - the corresponding <em>Node Pointer</em> and all its children. - This field exists only in nodes whose depth in the B-tree node - is greater than 1 (in other words, the “twig” - internal nodes, just above leaf nodes, do not store this - field in their child node pointers). - </p> - <p>The number of bytes used to store this field is determined by - the maximum possible number of records able to be stored in the - child node and its descendants. - </p> - <p> - The maximum possible number of records able to be stored in a - child node and its descendants is computed iteratively, in the - following way: The maximum number of records in a leaf node - is computed, then that value is used to compute the maximum - possible number of records in the first level of internal nodes - above the leaf nodes. Multiplying these two values together - determines the maximum possible number of records in child node - pointers for the level of nodes two levels above leaf nodes. - This process is continued up to any level in the B-tree. - </p> - <p> - The number of bytes used to encode this value is computed in - the same way as for the <em>Number of Records in Child Node</em> - field. - </p> - </td> - </tr> - - <tr> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for this node. - </p> - </td> + <p></p> + <p>Note that leaf nodes do not encode any child pointer + triplets, so the maximum number of records in a leaf node is just + the node size minus the leaf node overhead, divided by the record + size.</p> + <p> + Also note that the first level of internal nodes above the leaf + nodes do not encode the <em>Total Number of Records in Child + Node</em> value in the child pointer triplets (since it is the same as + the <em>Number of Records in Child Node</em>), so the maximum + number of records in these nodes is computed with the equation + above, but using (<em>Child Pointer</em>, <em>Number of + Records in Child Node</em>) pairs instead of triplets. + </p> + <p>The number of bytes used to encode this field is the least + number of bytes required to encode the maximum number of records in + a child node value for the child nodes below this level in the + B-tree.</p> + <p>For example, if the maximum number of child records is 123, + one byte will be used to encode these values in this node; if the + maximum number of child records is 20000, two bytes will be used to + encode these values in this node; and so on. The maximum number of + bytes used to encode these values is 8 (in other words, an unsigned + 64-bit integer).</p> + </td> </tr> - </table> - </div> + <tr> + <td><p>Total Number of Records in Child Node</p></td> + <td> + <p> + This is the total number of records for the node pointed to by the + corresponding <em>Node Pointer</em> and all its children. This + field exists only in nodes whose depth in the B-tree node is + greater than 1 (in other words, the “twig” internal + nodes, just above leaf nodes, do not store this field in their + child node pointers). + </p> + <p>The number of bytes used to store this field is determined by + the maximum possible number of records able to be stored in the + child node and its descendants.</p> + <p>The maximum possible number of records able to be stored in a + child node and its descendants is computed iteratively, in the + following way: The maximum number of records in a leaf node is + computed, then that value is used to compute the maximum possible + number of records in the first level of internal nodes above the + leaf nodes. Multiplying these two values together determines the + maximum possible number of records in child node pointers for the + level of nodes two levels above leaf nodes. This process is + continued up to any level in the B-tree.</p> + <p> + The number of bytes used to encode this value is computed in the + same way as for the <em>Number of Records in Child Node</em> field. + </p> + </td> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree Leaf Node - </caption> + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for this node.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree Leaf Node</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Signature</td> + <td colspan="4">Signature</td> </tr> <tr> - <td>Version</td> - <td>Type</td> - <td colspan="2">Record 0, 1, 2...N-1 <em>(variable size)</em></td> - </tr> - <tr> - <td colspan="4">Checksum</td> - </tr> - </table> - </div> + <td>Version</td> + <td>Type</td> + <td colspan="2">Record 0, 1, 2...N-1 <em>(variable size)</em></td> + </tr> + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>BTLF</code>“ is - used to indicate the leaf node of a version 2 B-link tree. - </p> - </td> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>BTLF</code> + “ is used to indicate the leaf node of a version 2 B-link + tree. + </p> + </td> </tr> <tr> - <td><p>Version</p></td> - <td> - <p>The version number for this B-tree leaf node. - This document describes version 0. - </p> - </td> + <td><p>Version</p></td> + <td> + <p>The version number for this B-tree leaf node. This document + describes version 0.</p> + </td> </tr> <tr> - <td><p>Type</p></td> - <td> - <p>This field is the type of the B-tree node. It should always - be the same as the B-tree type in the header. - </p> - </td> - </tr> + <td><p>Type</p></td> + <td> + <p>This field is the type of the B-tree node. It should always + be the same as the B-tree type in the header.</p> + </td> + </tr> <tr> - <td><p>Records</p></td> - <td> - <p>The size of this field is determined by the number of records - for this node and the record size (from the header). The format - of records depends on the type of B-tree. - </p> - </td> + <td><p>Records</p></td> + <td> + <p>The size of this field is determined by the number of records + for this node and the record size (from the header). The format of + records depends on the type of B-tree.</p> + </td> </tr> <tr> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for this node. - </p> - </td> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for this node.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <p>The record layout for each stored (in other words, non-testing) +<br /> +<p>The record layout for each stored (in other words, non-testing) B-tree type is as follows:</p> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree, Type 1 Record Layout - Indirectly Accessed, Non-Filtered, - ‘Huge’ Fractal Heap Objects - </caption> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree, Type 1 Record Layout - Indirectly + Accessed, Non-Filtered, ‘Huge’ Fractal Heap Objects</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> <tr> - <td colspan="4"><br />Huge Object Address<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Huge Object Address<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Huge Object Length<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Huge Object Length<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Huge Object ID<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Huge Object ID<sup>L</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Huge Object Address</p></td> - <td> - <p>The address of the huge object in the file. - </p> - </td> + <td><p>Huge Object Address</p></td> + <td> + <p>The address of the huge object in the file.</p> + </td> </tr> <tr> - <td><p>Huge Object Length</p></td> - <td> - <p>The length of the huge object in the file. - </p> - </td> + <td><p>Huge Object Length</p></td> + <td> + <p>The length of the huge object in the file.</p> + </td> </tr> <tr> - <td><p>Huge Object ID</p></td> - <td> - <p>The heap ID for the huge object. - </p> - </td> + <td><p>Huge Object ID</p></td> + <td> + <p>The heap ID for the huge object.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree, Type 2 Record Layout - Indirectly Accessed, Filtered, - ‘Huge’ Fractal Heap Objects - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree, Type 2 Record Layout - Indirectly + Accessed, Filtered, ‘Huge’ Fractal Heap Objects</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4"><br />Filtered Huge Object Address<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Filtered Huge Object Address<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Filtered Huge Object Length<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Filtered Huge Object Length<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4">Filter Mask</td> + <td colspan="4">Filter Mask</td> </tr> <tr> - <td colspan="4"><br />Filtered Huge Object Memory Size<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Filtered Huge Object Memory Size<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Huge Object ID<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Huge Object ID<sup>L</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Filtered Huge Object Address</p></td> - <td> - <p>The address of the filtered huge object in the file. - </p> - </td> + <td><p>Filtered Huge Object Address</p></td> + <td> + <p>The address of the filtered huge object in the file.</p> + </td> </tr> <tr> - <td><p>Filtered Huge Object Length</p></td> - <td> - <p>The length of the filtered huge object in the file. - </p> - </td> + <td><p>Filtered Huge Object Length</p></td> + <td> + <p>The length of the filtered huge object in the file.</p> + </td> </tr> <tr> - <td><p>Filter Mask</p></td> - <td> - <p>A 32-bit bit field indicating which filters have been skipped for - this chunk. Each filter has an index number in the pipeline - (starting at 0, with the first filter to apply) and if that - filter is skipped, the bit corresponding to its index is set. - </p> - </td> + <td><p>Filter Mask</p></td> + <td> + <p>A 32-bit bit field indicating which filters have been skipped + for this chunk. Each filter has an index number in the pipeline + (starting at 0, with the first filter to apply) and if that filter + is skipped, the bit corresponding to its index is set.</p> + </td> </tr> <tr> - <td><p>Filtered Huge Object Memory Size</p></td> - <td> - <p>The size of the de-filtered huge object in memory. - </p> - </td> + <td><p>Filtered Huge Object Memory Size</p></td> + <td> + <p>The size of the de-filtered huge object in memory.</p> + </td> </tr> <tr> - <td><p>Huge Object ID</p></td> - <td> - <p>The heap ID for the huge object. - </p> - </td> + <td><p>Huge Object ID</p></td> + <td> + <p>The heap ID for the huge object.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree, Type 3 Record Layout - Directly Accessed, Non-Filtered, - ‘Huge’ Fractal Heap Objects - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree, Type 3 Record Layout - Directly + Accessed, Non-Filtered, ‘Huge’ Fractal Heap Objects</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> <tr> - <td colspan="4"><br />Huge Object Address<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Huge Object Address<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Huge Object Length<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Huge Object Length<sup>L</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Huge Object Address</p></td> - <td> - <p>The address of the huge object in the file. - </p> - </td> + <td><p>Huge Object Address</p></td> + <td> + <p>The address of the huge object in the file.</p> + </td> </tr> <tr> - <td><p>Huge Object Length</p></td> - <td> - <p>The length of the huge object in the file. - </p> - </td> + <td><p>Huge Object Length</p></td> + <td> + <p>The length of the huge object in the file.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree, Type 4 Record Layout - Directly Accessed, Filtered, - ‘Huge’ Fractal Heap Objects - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree, Type 4 Record Layout - Directly + Accessed, Filtered, ‘Huge’ Fractal Heap Objects</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4"><br />Filtered Huge Object Address<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Filtered Huge Object Address<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Filtered Huge Object Length<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Filtered Huge Object Length<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4">Filter Mask</td> + <td colspan="4">Filter Mask</td> </tr> <tr> - <td colspan="4"><br />Filtered Huge Object Memory Size<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Filtered Huge Object Memory Size<sup>L</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Filtered Huge Object Address</p></td> - <td> - <p>The address of the filtered huge object in the file. - </p> - </td> + <td><p>Filtered Huge Object Address</p></td> + <td> + <p>The address of the filtered huge object in the file.</p> + </td> </tr> <tr> - <td><p>Filtered Huge Object Length</p></td> - <td> - <p>The length of the filtered huge object in the file. - </p> - </td> + <td><p>Filtered Huge Object Length</p></td> + <td> + <p>The length of the filtered huge object in the file.</p> + </td> </tr> <tr> - <td><p>Filter Mask</p></td> - <td> - <p>A 32-bit bit field indicating which filters have been skipped for - this chunk. Each filter has an index number in the pipeline - (starting at 0, with the first filter to apply) and if that - filter is skipped, the bit corresponding to its index is set. - </p> - </td> + <td><p>Filter Mask</p></td> + <td> + <p>A 32-bit bit field indicating which filters have been skipped + for this chunk. Each filter has an index number in the pipeline + (starting at 0, with the first filter to apply) and if that filter + is skipped, the bit corresponding to its index is set.</p> + </td> </tr> <tr> - <td><p>Filtered Huge Object Memory Size</p></td> - <td> - <p>The size of the de-filtered huge object in memory. - </p> - </td> + <td><p>Filtered Huge Object Memory Size</p></td> + <td> + <p>The size of the de-filtered huge object in memory.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree, Type 5 Record Layout - Link Name for Indexed Group - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree, Type 5 Record Layout - Link Name + for Indexed Group</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> <tr> - <td colspan="4">Hash of Name</td> + <td colspan="4">Hash of Name</td> </tr> <tr> - <td colspan="4">ID <em>(bytes 1-4)</em></td> - </tr> + <td colspan="4">ID <em>(bytes 1-4)</em></td> + </tr> <tr> - <td colspan="3">ID <em>(bytes 5-7)</em></td> - </tr> + <td colspan="3">ID <em>(bytes 5-7)</em></td> + </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Hash</p></td> - <td> - <p>This field is hash value of the name for the link. The hash - value is the Jenkins’ lookup3 checksum algorithm applied to - the link’s name. - </p> - </td> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the name for the link. The hash + value is the Jenkins’ lookup3 checksum algorithm applied to + the link’s name.</p> + </td> </tr> <tr> - <td><p>ID</p></td> - <td> - <p>This is a 7-byte sequence of bytes and is the heap ID for the - link record in the group’s fractal heap.</p> - </td> + <td><p>ID</p></td> + <td> + <p>This is a 7-byte sequence of bytes and is the heap ID for the + link record in the group’s fractal heap.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree, Type 6 Record Layout - Creation Order for Indexed Group - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree, Type 6 Record Layout - Creation + Order for Indexed Group</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4"><br />Creation Order <em>(8 bytes)</em><br /><br /></td> + <td colspan="4"><br />Creation Order <em>(8 bytes)</em><br /> + <br /></td> </tr> <tr> - <td colspan="4">ID <em>(bytes 1-4)</em></td> + <td colspan="4">ID <em>(bytes 1-4)</em></td> </tr> <tr> - <td colspan="3">ID <em>(bytes 5-7)</em></td> + <td colspan="3">ID <em>(bytes 5-7)</em></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Creation Order</p></td> - <td> - <p>This field is the creation order value for the link. - </p> - </td> + <td><p>Creation Order</p></td> + <td> + <p>This field is the creation order value for the link.</p> + </td> </tr> <tr> - <td><p>ID</p></td> - <td> - <p>This is a 7-byte sequence of bytes and is the heap ID for the - link record in the group’s fractal heap.</p> - </td> + <td><p>ID</p></td> + <td> + <p>This is a 7-byte sequence of bytes and is the heap ID for the + link record in the group’s fractal heap.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree, Type 7 Record Layout - Shared Object Header Messages (Sub-Type 0 - Message in Heap) - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree, Type 7 Record Layout - Shared + Object Header Messages (Sub-Type 0 - Message in Heap)</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan>Message Location</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td colspan>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4">Hash</td> + <td colspan="4">Hash</td> </tr> <tr> - <td colspan="4">Reference Count</td> + <td colspan="4">Reference Count</td> </tr> <tr> - <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /><br /></td> + <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /> + <br /></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Message Location</p></td> - <td> - <p>This field Indicates the location where the message is stored: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - <tr> - <td align="center">0</td> - <td>Shared message is stored in shared message index heap. - </td> - </tr> - <tr> - <td align="center">1</td> - <td>Shared message is stored in object header. - </td> - </tr> - </table></p> - </td> + <td><p>Message Location</p></td> + <td> + <p>This field Indicates the location where the message is + stored:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>Shared message is stored in shared message index heap.</td> + </tr> + <tr> + <td align="center">1</td> + <td>Shared message is stored in object header.</td> + </tr> + </table> + <p></p> + </td> </tr> <tr> - <td><p>Hash</p></td> - <td> - <p>This field is hash value of the shared message. The hash - value is the Jenkins’ lookup3 checksum algorithm applied to - the shared message.</p> - </td> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the shared message. The hash + value is the Jenkins’ lookup3 checksum algorithm applied to + the shared message.</p> + </td> </tr> <tr> - <td><p>Reference Count</p></td> - <td> - <p>The number of objects which reference this message.</p> - </td> + <td><p>Reference Count</p></td> + <td> + <p>The number of objects which reference this message.</p> + </td> </tr> <tr> - <td><p>Heap ID</p></td> - <td> - <p>This is an 8-byte sequence of bytes and is the heap ID for the - shared message in the shared message index’s fractal heap.</p> - </td> + <td><p>Heap ID</p></td> + <td> + <p>This is an 8-byte sequence of bytes and is the heap ID for + the shared message in the shared message index’s fractal + heap.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree, Type 7 Record Layout - Shared Object Header Messages (Sub-Type 1 - Message in Object Header) - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree, Type 7 Record Layout - Shared + Object Header Messages (Sub-Type 1 - Message in Object Header)</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan>Message Location</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td colspan>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4">Hash</td> + <td colspan="4">Hash</td> </tr> <tr> - <td>Reserved (zero)</td> - <td>Message Type</td> - <td colspan="2">Object Header Index</td> + <td>Reserved (zero)</td> + <td>Message Type</td> + <td colspan="2">Object Header Index</td> </tr> <tr> - <td colspan="4"><br />Object Header Address<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Object Header Address<sup>O</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Message Location</p></td> - <td> - <p>This field Indicates the location where the message is stored: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - <tr> - <td align="center">0</td> - <td>Shared message is stored in shared message index heap. - </td> - </tr> - <tr> - <td align="center">1</td> - <td>Shared message is stored in object header. - </td> - </tr> - </table></p> - </td> + <td><p>Message Location</p></td> + <td> + <p>This field Indicates the location where the message is + stored:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>Shared message is stored in shared message index heap.</td> + </tr> + <tr> + <td align="center">1</td> + <td>Shared message is stored in object header.</td> + </tr> + </table> + <p></p> + </td> </tr> <tr> - <td><p>Hash</p></td> - <td> - <p>This field is hash value of the shared message. The hash - value is the Jenkins’ lookup3 checksum algorithm applied to - the shared message.</p> - </td> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the shared message. The hash + value is the Jenkins’ lookup3 checksum algorithm applied to + the shared message.</p> + </td> </tr> <tr> - <td><p>Message Type</p></td> - <td> - <p>The object header message type of the shared message.</p> - </td> + <td><p>Message Type</p></td> + <td> + <p>The object header message type of the shared message.</p> + </td> </tr> <tr> - <td><p>Object Header Index</p></td> - <td> - <p>This field indicates that the shared message is the n<sup>th</sup> message - of its type in the specified object header.</p> - </td> + <td><p>Object Header Index</p></td> + <td> + <p> + This field indicates that the shared message is the n<sup>th</sup> + message of its type in the specified object header. + </p> + </td> </tr> <tr> - <td><p>Object Header Address</p></td> - <td> - <p>The address of the object header containing the shared message.</p> - </td> + <td><p>Object Header Address</p></td> + <td> + <p>The address of the object header containing the shared + message.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree, Type 8 Record Layout - Attribute Name for Indexed Attributes - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree, Type 8 Record Layout - Attribute + Name for Indexed Attributes</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /><br /></td> + <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /> + <br /></td> </tr> <tr> - <td colspan>Message Flags</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td colspan>Message Flags</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4">Creation Order</td> + <td colspan="4">Creation Order</td> </tr> <tr> - <td colspan="4">Hash of Name</td> + <td colspan="4">Hash of Name</td> </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Heap ID</p></td> - <td> - <p>This is an 8-byte sequence of bytes and is the heap ID for the - attribute in the object’s attribute fractal heap.</p> - </td> + <td><p>Heap ID</p></td> + <td> + <p>This is an 8-byte sequence of bytes and is the heap ID for + the attribute in the object’s attribute fractal heap.</p> + </td> </tr> <tr> - <td><p>Message Flags</p></td> - <td><p>The object header message flags for the attribute message.</p> - </td> + <td><p>Message Flags</p></td> + <td><p>The object header message flags for the attribute + message.</p></td> </tr> <tr> - <td><p>Creation Order</p></td> - <td> - <p>This field is the creation order value for the attribute. - </p> - </td> + <td><p>Creation Order</p></td> + <td> + <p>This field is the creation order value for the attribute.</p> + </td> </tr> <tr> - <td><p>Hash</p></td> - <td> - <p>This field is hash value of the name for the attribute. The hash - value is the Jenkins’ lookup3 checksum algorithm applied to - the attribute’s name. - </p> - </td> + <td><p>Hash</p></td> + <td> + <p>This field is hash value of the name for the attribute. The + hash value is the Jenkins’ lookup3 checksum algorithm applied + to the attribute’s name.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Version 2 B-tree, Type 9 Record Layout- Creation Order for Indexed Attributes - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Version 2 B-tree, Type 9 Record Layout- Creation + Order for Indexed Attributes</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /><br /></td> + <td colspan="4"><br />Heap ID <em>(8 bytes)</em><br /> + <br /></td> </tr> <tr> - <td colspan>Message Flags</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td colspan>Message Flags</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4">Creation Order</td> + <td colspan="4">Creation Order</td> </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Heap ID</p></td> - <td> - <p>This is an 8-byte sequence of bytes and is the heap ID for the - attribute in the object’s attribute fractal heap.</p> - </td> + <td><p>Heap ID</p></td> + <td> + <p>This is an 8-byte sequence of bytes and is the heap ID for + the attribute in the object’s attribute fractal heap.</p> + </td> </tr> <tr> - <td><p>Message Flags</p></td> - <td> - <p>The object header message flags for the attribute message.</p> - </td> + <td><p>Message Flags</p></td> + <td> + <p>The object header message flags for the attribute message.</p> + </td> </tr> <tr> - <td><p>Creation Order</p></td> - <td> - <p>This field is the creation order value for the attribute. - </p> - </td> + <td><p>Creation Order</p></td> + <td> + <p>This field is the creation order value for the attribute.</p> + </td> </tr> - </table> - </div> + </table> +</div> <br /> -<h3><a name="SymbolTable"> -III.B. Disk Format: Level 1B - Group Symbol Table Nodes</a></h3> - - <p>A group is an object internal to the file that allows - arbitrary nesting of objects within the file (including other groups). - A group maps a set of link names in the group to a set of relative - file addresses of objects in the file. Certain metadata for an object to - which the group points can be cached in the group’s symbol table entry in - addition to being in the object’s header.</p> - - <p>An HDF5 object name space can be stored hierarchically by - partitioning the name into components and storing each - component as a link in a group. The link for a - non-ultimate component points to the group containing - the next component. The link for the last - component points to the object being named.</p> +<h3> + <a name="SymbolTable"> III.B. Disk Format: Level 1B - Group Symbol + Table Nodes</a> +</h3> + +<p>A group is an object internal to the file that allows arbitrary + nesting of objects within the file (including other groups). A group + maps a set of link names in the group to a set of relative file + addresses of objects in the file. Certain metadata for an object to + which the group points can be cached in the group’s symbol table + entry in addition to being in the object’s header.</p> + +<p>An HDF5 object name space can be stored hierarchically by + partitioning the name into components and storing each component as a + link in a group. The link for a non-ultimate component points to the + group containing the next component. The link for the last component + points to the object being named.</p> + +<p> + One implementation of a group is a collection of symbol table nodes + indexed by a B-link tree. Each symbol table node contains entries for + one or more links. If an attempt is made to add a link to an already + full symbol table node containing 2<em>K</em> entries, then the node is + split and one node contains <em>K</em> symbols and the other contains <em>K</em>+1 + symbols. +</p> - <p>One implementation of a group is a collection of symbol table nodes - indexed by a B-link tree. Each symbol table node contains entries - for one or more links. If an attempt is made to add a link to an already - full symbol table node containing 2<em>K</em> entries, then the node is - split and one node contains <em>K</em> symbols and the other contains - <em>K</em>+1 symbols.</p> - - <div align="center"> - <table class="format"> - <caption> - Symbol Table Node (A Leaf of a B-link tree) - </caption> +<div align="center"> + <table class="format"> + <caption>Symbol Table Node (A Leaf of a B-link tree)</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Signature</td> + <td colspan="4">Signature</td> </tr> <tr> - <td>Version Number</td> - <td>Reserved (zero)</td> - <td colspan="2">Number of Symbols</td> + <td>Version Number</td> + <td>Reserved (zero)</td> + <td colspan="2">Number of Symbols</td> </tr> <tr> - <td colspan="4"><br /><br />Group Entries<br /><br /><br /></td> + <td colspan="4"><br /> + <br />Group Entries<br /> + <br /> + <br /></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>SNOD</code>” is - used to indicate the - beginning of a symbol table node. This gives file - consistency checking utilities a better chance of - reconstructing a damaged file. - </p> - </td> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>SNOD</code> + ” is used to indicate the beginning of a symbol table node. + This gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> </tr> <tr> - <td><p>Version Number</p></td> - <td> - <p>The version number for the symbol table node. This - document describes version 1. (There is no version ‘0’ - of the symbol table node) - </p> - </td> + <td><p>Version Number</p></td> + <td> + <p>The version number for the symbol table node. This document + describes version 1. (There is no version ‘0’ of the + symbol table node)</p> + </td> </tr> <tr> - <td><p>Number of Entries</p></td> - <td> - <p>Although all symbol table nodes have the same length, - most contain fewer than the maximum possible number of - link entries. This field indicates how many entries - contain valid data. The valid entries are packed at the - beginning of the symbol table node while the remaining - entries contain undefined values. - </p> - </td> + <td><p>Number of Entries</p></td> + <td> + <p>Although all symbol table nodes have the same length, most + contain fewer than the maximum possible number of link entries. + This field indicates how many entries contain valid data. The valid + entries are packed at the beginning of the symbol table node while + the remaining entries contain undefined values.</p> + </td> </tr> <tr> - <td><p>Symbol Table Entries</p></td> - <td> - <p>Each link has an entry in the symbol table node. - The format of the entry is described below. - There are 2<em>K</em> entries in each group node, where - <em>K</em> is the “Group Leaf Node K” value from the - <a href="#Superblock">superblock</a>. - </p> - </td> + <td><p>Symbol Table Entries</p></td> + <td> + <p> + Each link has an entry in the symbol table node. The format of the + entry is described below. There are 2<em>K</em> entries in each + group node, where <em>K</em> is the “Group Leaf Node K” + value from the <a href="#Superblock">superblock</a>. + </p> + </td> </tr> - </table> - </div> + </table> +</div> <br /> -<h3><a name="SymbolTableEntry"> -III.C. Disk Format: Level 1C - Symbol Table Entry </a></h3> +<h3> + <a name="SymbolTableEntry"> III.C. Disk Format: Level 1C - Symbol + Table Entry </a> +</h3> - <p>Each symbol table entry in a symbol table node is designed - to allow for very fast browsing of stored objects. - Toward that design goal, the symbol table entries - include space for caching certain constant metadata from the - object header.</p> +<p>Each symbol table entry in a symbol table node is designed to + allow for very fast browsing of stored objects. Toward that design + goal, the symbol table entries include space for caching certain + constant metadata from the object header.</p> - <div align="center"> - <table class="format"> - <caption> - Symbol Table Entry - </caption> +<div align="center"> + <table class="format"> + <caption>Symbol Table Entry</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4"><br />Link Name Offset<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Link Name Offset<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Object Header Address<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Object Header Address<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4">Cache Type</td> + <td colspan="4">Cache Type</td> </tr> <tr> - <td colspan="4">Reserved (zero)</td> + <td colspan="4">Reserved (zero)</td> </tr> <tr> - <td colspan="4"><br /><br />Scratch-pad Space (16 bytes)<br /><br /><br /></td> + <td colspan="4"><br /> + <br />Scratch-pad Space (16 bytes)<br /> + <br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Link Name Offset</p></td> - <td> - <p>This is the byte offset into the group’s local - heap for the name of the link. The name is null - terminated. - </p> - </td> - </tr> - - <tr> - <td><p>Object Header Address</p></td> - <td> - <p>Every object has an object header which serves as a - permanent location for the object’s metadata. In addition - to appearing in the object header, some of the object’s metadata - can be cached in the scratch-pad space. - </p> - </td> - </tr> - - <tr> - <td><p>Cache Type</p></td> - <td> - <p>The cache type is determined from the object header. - It also determines the format for the scratch-pad space: - - <table class="list"> - <tr> - <th width="20%" align="center">Type</th> - <th width="80%" align="left">Description</th> - </tr> - <tr> - <td align="center">0</td> - <td>No data is cached by the group entry. This - is guaranteed to be the case when an object header - has a link count greater than one. - </td> - </tr> - <tr> - <td align="center">1</td> - <td>Group object header metadata is cached in the - scratch-pad space. This implies that the symbol table - entry refers to another group. - </td> - </tr> - <tr> - <td align="center">2</td> - <td>The entry is a symbolic link. The first four bytes - of the scratch-pad space are the offset into the local - heap for the link value. The object header address - will be undefined. - </td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>Reserved</p></td> - <td> - <p>These four bytes are present so that the scratch-pad - space is aligned on an eight-byte boundary. They are - always set to zero. - </p> - </td> - </tr> - - <tr> - <td><p>Scratch-pad Space</p></td> - <td> - <p>This space is used for different purposes, depending - on the value of the Cache Type field. Any metadata - about an object represented in the scratch-pad - space is duplicated in the object header for that - object. - </p> - <p> - Furthermore, no data is cached in the group - entry scratch-pad space if the object header for - the object has a link count greater than one. - </p> - </td> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Link Name Offset</p></td> + <td> + <p>This is the byte offset into the group’s local heap for + the name of the link. The name is null terminated.</p> + </td> + </tr> + + <tr> + <td><p>Object Header Address</p></td> + <td> + <p>Every object has an object header which serves as a permanent + location for the object’s metadata. In addition to appearing + in the object header, some of the object’s metadata can be + cached in the scratch-pad space.</p> + </td> </tr> - </table> - </div> + + <tr> + <td><p>Cache Type</p></td> + <td> + <p>The cache type is determined from the object header. It also + determines the format for the scratch-pad space:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Type</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center">0</td> + <td>No data is cached by the group entry. This is guaranteed + to be the case when an object header has a link count greater + than one.</td> + </tr> + <tr> + <td align="center">1</td> + <td>Group object header metadata is cached in the scratch-pad + space. This implies that the symbol table entry refers to another + group.</td> + </tr> + <tr> + <td align="center">2</td> + <td>The entry is a symbolic link. The first four bytes of the + scratch-pad space are the offset into the local heap for the link + value. The object header address will be undefined.</td> + </tr> + </table> + <p></p> + + </td> + </tr> + + <tr> + <td><p>Reserved</p></td> + <td> + <p>These four bytes are present so that the scratch-pad space is + aligned on an eight-byte boundary. They are always set to zero.</p> + </td> + </tr> + + <tr> + <td><p>Scratch-pad Space</p></td> + <td> + <p>This space is used for different purposes, depending on the + value of the Cache Type field. Any metadata about an object + represented in the scratch-pad space is duplicated in the object + header for that object.</p> + <p>Furthermore, no data is cached in the group entry scratch-pad + space if the object header for the object has a link count greater + than one.</p> + </td> + </tr> + </table> +</div> <br /> <h4>Format of the Scratch-pad Space</h4> - <p>The symbol table entry scratch-pad space is formatted - according to the value in the Cache Type field.</p> +<p>The symbol table entry scratch-pad space is formatted according + to the value in the Cache Type field.</p> - <p>If the Cache Type field contains the value zero - <code>(0)</code> then no information is - stored in the scratch-pad space.</p> +<p> + If the Cache Type field contains the value zero + <code>(0)</code> + then no information is stored in the scratch-pad space. +</p> - <p>If the Cache Type field contains the value one - <code>(1)</code>, then the scratch-pad space - contains cached metadata for another object header - in the following format:</p> +<p> + If the Cache Type field contains the value one + <code>(1)</code> + , then the scratch-pad space contains cached metadata for another + object header in the following format: +</p> - <div align="center"> - <table class="format"> - <caption> - Object Header Scratch-pad Format - </caption> +<div align="center"> + <table class="format"> + <caption>Object Header Scratch-pad Format</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4"><br />Address of B-tree<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address of B-tree<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Address of Name Heap<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address of Name Heap<sup>O</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Address of B-tree</p></td> - <td> - <p>This is the file address for the root of the - group’s B-tree. - </p> - </td> + <td><p>Address of B-tree</p></td> + <td> + <p>This is the file address for the root of the group’s + B-tree.</p> + </td> </tr> <tr> - <td><p>Address of Name Heap</p></td> - <td> - <p>This is the file address for the group’s local - heap, in which are stored the group’s symbol names. - </p> - </td> + <td><p>Address of Name Heap</p></td> + <td> + <p>This is the file address for the group’s local heap, in + which are stored the group’s symbol names.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <p>If the Cache Type field contains the value two - <code>(2)</code>, then the scratch-pad space - contains cached metadata for a symbolic link - in the following format:</p> +<br /> +<p> + If the Cache Type field contains the value two + <code>(2)</code> + , then the scratch-pad space contains cached metadata for a symbolic + link in the following format: +</p> - <div align="center"> - <table class="format"> - <caption> - Symbolic Link Scratch-pad Format - </caption> +<div align="center"> + <table class="format"> + <caption>Symbolic Link Scratch-pad Format</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Offset to Link Value</td> + <td colspan="4">Offset to Link Value</td> </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Offset to Link Value</p></td> - <td> - <p>The value of a symbolic link (that is, the name of the - thing to which it points) is stored in the local heap. - This field is the 4-byte offset into the local heap for - the start of the link value, which is null terminated. - </p> - </td> + <td><p>Offset to Link Value</p></td> + <td> + <p>The value of a symbolic link (that is, the name of the thing + to which it points) is stored in the local heap. This field is the + 4-byte offset into the local heap for the start of the link value, + which is null terminated.</p> + </td> </tr> - </table> - </div> + </table> +</div> <br /> -<h3><a name="LocalHeap"> -III.D. Disk Format: Level 1D - Local Heaps</a></h3> +<h3> + <a name="LocalHeap"> III.D. Disk Format: Level 1D - Local Heaps</a> +</h3> - <p>A local heap is a collection of small pieces of data that are particular - to a single object in the HDF5 file. Objects can be - inserted and removed from the heap at any time. - The address of a heap does not change once the heap is created. - For example, a group stores addresses of objects in symbol table nodes - with the names of links stored in the group’s local heap. - </p> +<p>A local heap is a collection of small pieces of data that are + particular to a single object in the HDF5 file. Objects can be inserted + and removed from the heap at any time. The address of a heap does not + change once the heap is created. For example, a group stores addresses + of objects in symbol table nodes with the names of links stored in the + group’s local heap.</p> - <div align="center"> - <table class="format"> - <caption> - Local Heap - </caption> +<div align="center"> + <table class="format"> + <caption>Local Heap</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Signature</td> + <td colspan="4">Signature</td> </tr> <tr> - <td>Version</td> - <td colspan="3">Reserved (zero)</td> + <td>Version</td> + <td colspan="3">Reserved (zero)</td> </tr> <tr> - <td colspan="4"><br />Data Segment Size<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Data Segment Size<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Offset to Head of Free-list<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Offset to Head of Free-list<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Address of Data Segment<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address of Data Segment<sup>O</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>HEAP</code>” - is used to indicate the - beginning of a heap. This gives file consistency - checking utilities a better chance of reconstructing a - damaged file. - </p> - </td> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>HEAP</code> + ” is used to indicate the beginning of a heap. This gives + file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> </tr> <tr> - <td><p>Version</p></td> - <td> - <p>Each local heap has its own version number so that new - heaps can be added to old files. This document - describes version zero (0) of the local heap. - </p> - </td> + <td><p>Version</p></td> + <td> + <p>Each local heap has its own version number so that new heaps + can be added to old files. This document describes version zero (0) + of the local heap.</p> + </td> </tr> <tr> - <td><p>Data Segment Size</p></td> - <td> - <p>The total amount of disk memory allocated for the heap - data. This may be larger than the amount of space - required by the objects stored in the heap. The extra - unused space in the heap holds a linked list of free blocks. - </p> - </td> + <td><p>Data Segment Size</p></td> + <td> + <p>The total amount of disk memory allocated for the heap data. + This may be larger than the amount of space required by the objects + stored in the heap. The extra unused space in the heap holds a + linked list of free blocks.</p> + </td> </tr> <tr> - <td><p>Offset to Head of Free-list</p></td> - <td> - <p>This is the offset within the heap data segment of the - first free block (or the - <a href="#UndefinedAddress">undefined address</a> if there is no - free block). The free block contains “Size of Lengths” bytes that - are the offset of the next free block (or the - value ‘1’ if this is the - last free block) followed by “Size of Lengths” bytes that store - the size of this free block. The size of the free block includes - the space used to store the offset of the next free block and - the size of the current block, making the minimum size of a free - block 2 * “Size of Lengths”. - </p> - </td> + <td><p>Offset to Head of Free-list</p></td> + <td> + <p> + This is the offset within the heap data segment of the first free + block (or the <a href="#UndefinedAddress">undefined address</a> if + there is no free block). The free block contains “Size of + Lengths” bytes that are the offset of the next free block (or + the value ‘1’ if this is the last free block) followed + by “Size of Lengths” bytes that store the size of this + free block. The size of the free block includes the space used to + store the offset of the next free block and the size of the current + block, making the minimum size of a free block 2 * “Size of + Lengths”. + </p> + </td> </tr> <tr> - <td><p>Address of Data Segment</p></td> - <td> - <p>The data segment originally starts immediately after - the heap header, but if the data segment must grow as a - result of adding more objects, then the data segment may - be relocated, in its entirety, to another part of the - file. - </p> - </td> + <td><p>Address of Data Segment</p></td> + <td> + <p>The data segment originally starts immediately after the heap + header, but if the data segment must grow as a result of adding + more objects, then the data segment may be relocated, in its + entirety, to another part of the file.</p> + </td> </tr> - </table> - </div> - - <p>Objects within a local heap should be aligned on an 8-byte boundary.</p> - -<br /> -<h3><a name="GlobalHeap"> -III.E. Disk Format: Level 1E - Global Heap</a></h3> - - <p>Each HDF5 file has a global heap which stores various types of - information which is typically shared between datasets. The - global heap was designed to satisfy these goals:</p> - - <ol type="A"> - <li>Repeated access to a heap object must be efficient without - resulting in repeated file I/O requests. Since global heap - objects will typically be shared among several datasets, it is - probable that the object will be accessed repeatedly.</li> - <li>Collections of related global heap objects should result in - fewer and larger I/O requests. For instance, a dataset of - object references will have a global heap object for each - reference. Reading the entire set of object references - should result in a few large I/O requests instead of one small - I/O request for each reference.</li> - <li>It should be possible to remove objects from the global heap - and the resulting file hole should be eligible to be reclaimed - for other uses.</li> - </ol> - - - <p>The implementation of the heap makes use of the memory management - already available at the file level and combines that with a new - object called a <em>collection</em> to achieve goal B. The global heap - is the set of all collections. Each global heap object belongs to - exactly one collection and each collection contains one or more global - heap objects. For the purposes of disk I/O and caching, a collection is - treated as an atomic object, addressing goal A. - </p> - - <p>When a global heap object is deleted from a collection (which occurs - when its reference count falls to zero), objects located after the - deleted object in the collection are packed down toward the beginning - of the collection and the collection’s global heap object 0 is created - (if possible) or its size is increased to account for the recently - freed space. There are no gaps between objects in each collection, - with the possible exception of the final space in the collection, if - it is not large enough to hold the header for the collection’s global - heap object 0. These features address goal C. - </p> - - <p>The HDF5 Library creates global heap collections as needed, so there may - be multiple collections throughout the file. The set of all of them is - abstractly called the “global heap”, although they do not actually link - to each other, and there is no global place in the file where you can - discover all of the collections. The collections are found simply by - finding a reference to one through another object in the file. For - example, data of variable-length datatype elements is stored in the - global heap and is accessed via a global heap ID. The format for - global heap IDs is described at the end of this section. - </p> - - <div align="center"> - <table class="format"> - <caption> - A Global Heap Collection - </caption> + </table> +</div> + +<p>Objects within a local heap should be aligned on an 8-byte + boundary.</p> + +<br /> +<h3> + <a name="GlobalHeap"> III.E. Disk Format: Level 1E - Global Heap</a> +</h3> + +<p>Each HDF5 file has a global heap which stores various types of + information which is typically shared between datasets. The global heap + was designed to satisfy these goals:</p> + +<ol type="A"> + <li>Repeated access to a heap object must be efficient without + resulting in repeated file I/O requests. Since global heap objects + will typically be shared among several datasets, it is probable that + the object will be accessed repeatedly.</li> + <li>Collections of related global heap objects should result in + fewer and larger I/O requests. For instance, a dataset of object + references will have a global heap object for each reference. Reading + the entire set of object references should result in a few large I/O + requests instead of one small I/O request for each reference.</li> + <li>It should be possible to remove objects from the global heap + and the resulting file hole should be eligible to be reclaimed for + other uses.</li> +</ol> + + +<p> + The implementation of the heap makes use of the memory management + already available at the file level and combines that with a new object + called a <em>collection</em> to achieve goal B. The global heap is the + set of all collections. Each global heap object belongs to exactly one + collection and each collection contains one or more global heap + objects. For the purposes of disk I/O and caching, a collection is + treated as an atomic object, addressing goal A. +</p> + +<p>When a global heap object is deleted from a collection (which + occurs when its reference count falls to zero), objects located after + the deleted object in the collection are packed down toward the + beginning of the collection and the collection’s global heap + object 0 is created (if possible) or its size is increased to account + for the recently freed space. There are no gaps between objects in each + collection, with the possible exception of the final space in the + collection, if it is not large enough to hold the header for the + collection’s global heap object 0. These features address goal C. +</p> + +<p>The HDF5 Library creates global heap collections as needed, so + there may be multiple collections throughout the file. The set of all + of them is abstractly called the “global heap”, although + they do not actually link to each other, and there is no global place + in the file where you can discover all of the collections. The + collections are found simply by finding a reference to one through + another object in the file. For example, data of variable-length + datatype elements is stored in the global heap and is accessed via a + global heap ID. The format for global heap IDs is described at the end + of this section.</p> + +<div align="center"> + <table class="format"> + <caption>A Global Heap Collection</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Signature</td> + <td colspan="4">Signature</td> </tr> <tr> - <td>Version</td> - <td colspan="3">Reserved (zero)</td> + <td>Version</td> + <td colspan="3">Reserved (zero)</td> </tr> <tr> - <td colspan="4"><br />Collection Size<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Collection Size<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Global Heap Object 1<br /><br /></td> + <td colspan="4"><br />Global Heap Object 1<br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Global Heap Object 2<br /><br /></td> + <td colspan="4"><br />Global Heap Object 2<br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />...<br /><br /></td> + <td colspan="4"><br />...<br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Global Heap Object <em>N</em><br /><br /></td> + <td colspan="4"><br />Global Heap Object <em>N</em><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Global Heap Object 0 (free space)<br /><br /></td> + <td colspan="4"><br />Global Heap Object 0 (free space)<br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘L’ in the + above table are of the size specified in “Size of + Lengths” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>GCOL</code>” - is used to indicate the - beginning of a collection. This gives file consistency - checking utilities a better chance of reconstructing a - damaged file. - </p> - </td> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>GCOL</code> + ” is used to indicate the beginning of a collection. This + gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> </tr> <tr> - <td><p>Version</p></td> - <td> - <p>Each collection has its own version number so that new - collections can be added to old files. This document - describes version one (1) of the collections (there is no - version zero (0)). - </p> - </td> + <td><p>Version</p></td> + <td> + <p>Each collection has its own version number so that new + collections can be added to old files. This document describes + version one (1) of the collections (there is no version zero (0)). + </p> + </td> </tr> <tr> - <td><p>Collection Size</p></td> - <td> - <p>This is the size in bytes of the entire collection - including this field. The default (and minimum) - collection size is 4096 bytes which is a typical file - system block size. This allows for 127 16-byte heap - objects plus their overhead (the collection header of 16 bytes - and the 16 bytes of information about each heap object). - </p> - </td> + <td><p>Collection Size</p></td> + <td> + <p>This is the size in bytes of the entire collection including + this field. The default (and minimum) collection size is 4096 bytes + which is a typical file system block size. This allows for 127 + 16-byte heap objects plus their overhead (the collection header of + 16 bytes and the 16 bytes of information about each heap object).</p> + </td> </tr> <tr> - <td><p>Global Heap Object 1 through <em>N</em></p></td> - <td> - <p>The objects are stored in any order with no - intervening unused space. - </p> - </td> + <td><p> + Global Heap Object 1 through <em>N</em> + </p></td> + <td> + <p>The objects are stored in any order with no intervening + unused space.</p> + </td> </tr> <tr> - <td><p>Global Heap Object 0</p></td> - <td> - <p>Global Heap Object 0 (zero), when present, represents the free - space in the collection. Free space always appears at the end of - the collection. If the free space is too small to store the header - for Object 0 (described below) then the header is implied and the - collection contains no free space. - </p> - </td> + <td><p>Global Heap Object 0</p></td> + <td> + <p>Global Heap Object 0 (zero), when present, represents the + free space in the collection. Free space always appears at the end + of the collection. If the free space is too small to store the + header for Object 0 (described below) then the header is implied + and the collection contains no free space.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Global Heap Object - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Global Heap Object</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="2">Heap Object Index</td> - <td colspan="2">Reference Count</td> + <td colspan="2">Heap Object Index</td> + <td colspan="2">Reference Count</td> </tr> <tr> - <td colspan="4">Reserved (zero)</td> + <td colspan="4">Reserved (zero)</td> </tr> <tr> - <td colspan="4"><br />Object Size<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Object Size<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Object Data<br /><br /></td> + <td colspan="4"><br />Object Data<br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘L’ in the + above table are of the size specified in “Size of + Lengths” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Heap Object Index</p></td> - <td> - <p>Each object has a unique identification number within a - collection. The identification numbers are chosen so that - new objects have the smallest value possible with the - exception that the identifier <code>0</code> always refers to the - object which represents all free space within the - collection. - </p> - </td> + <td><p>Heap Object Index</p></td> + <td> + <p> + Each object has a unique identification number within a collection. + The identification numbers are chosen so that new objects have the + smallest value possible with the exception that the identifier + <code>0</code> + always refers to the object which represents all free space within + the collection. + </p> + </td> </tr> <tr> - <td><p>Reference Count</p></td> - <td> - <p>All heap objects have a reference count field. An - object which is referenced from some other part of the - file will have a positive reference count. The reference - count for Object 0 is always zero. - </p> - </td> + <td><p>Reference Count</p></td> + <td> + <p>All heap objects have a reference count field. An object + which is referenced from some other part of the file will have a + positive reference count. The reference count for Object 0 is + always zero.</p> + </td> </tr> <tr> - <td><p>Reserved</p></td> - <td> - <p>Zero padding to align next field on an 8-byte boundary. - </p> - </td> + <td><p>Reserved</p></td> + <td> + <p>Zero padding to align next field on an 8-byte boundary.</p> + </td> </tr> <tr> - <td><p>Object Size</p></td> - <td> - <p>This is the size of the object data stored for the object. - The actual storage space allocated for the object data is rounded - up to a multiple of eight. - </p> - </td> + <td><p>Object Size</p></td> + <td> + <p>This is the size of the object data stored for the object. + The actual storage space allocated for the object data is rounded + up to a multiple of eight.</p> + </td> </tr> <tr> - <td><p>Object Data</p></td> - <td> - <p>The object data is treated as a one-dimensional array - of bytes to be interpreted by the caller. - </p> - </td> + <td><p>Object Data</p></td> + <td> + <p>The object data is treated as a one-dimensional array of + bytes to be interpreted by the caller.</p> + </td> </tr> - </table> + </table> - </div> +</div> - <br /> - <p> - The format for the ID used to locate an object in the global heap is - described here:</p> +<br /> +<p>The format for the ID used to locate an object in the global heap + is described here:</p> - <div align="center"> - <table class="format"> - <caption> - Global Heap ID - </caption> +<div align="center"> + <table class="format"> + <caption>Global Heap ID</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4"><br />Collection Address<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Collection Address<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4">Object Index</td> + <td colspan="4">Object Index</td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Collection Address</p></td> - <td> - <p>This field is the address of the global heap collection - where the data object is stored. - </p> - </td> + <td><p>Collection Address</p></td> + <td> + <p>This field is the address of the global heap collection where + the data object is stored.</p> + </td> </tr> <tr> - <td><p>ID</p></td> - <td> - <p>This field is the index of the data object within the - global heap collection. - </p> - </td> + <td><p>ID</p></td> + <td> + <p>This field is the index of the data object within the global + heap collection.</p> + </td> </tr> - </table> - </div> - - -<br /> -<h3><a name="FractalHeap"> -III.F. Disk Format: Level 1F - Fractal Heap</a></h3> - - <p> - Each fractal heap consists of a header and zero or more direct and - indirect blocks (described below). The header contains general - information as well as - initialization parameters for the doubling table. The <em>Root - Block Address</em> in the header points to the first direct or - indirect block in the heap. - </p> - - <p> - Fractal heaps are based on a data structure called a <em>doubling - table</em>. A doubling table provides a mechanism for quickly - extending an array-like data structure that minimizes the number of - empty blocks in the heap, while retaining very fast lookup of any - element within the array. More information on fractal heaps and - doubling tables can be found in the RFC - “<a href="Supplements/FractalHeap/PrivateHeap.pdf">Private - Heaps in HDF5</a>.” - </p> - - <p> - The fractal heap implements the doubling table structure with - indirect and direct blocks. - Indirect blocks in the heap do not actually contain data for - objects in the heap, their “size” is abstract - - they represent the indexing structure for locating the - direct blocks in the doubling table. - Direct blocks - contain the actual data for objects stored in the heap. - </p> - - <p> - All indirect blocks have a constant number of block entries in each - row, called the <em>width</em> of the doubling table (stored in - the heap header). - - The number - of rows for each indirect block in the heap is determined by the - size of the block that the indirect block represents in the - doubling table (calculation of this is shown below) and is - constant, except for the “root” - indirect block, which expands and shrinks its number of rows as - needed. - </p> - - <p> - Blocks in the first <em>two</em> rows of an indirect block - are <em>Starting Block Size</em> number of bytes in size, - and the blocks in each subsequent row are twice the size of - the blocks in the previous row. In other words, blocks in - the third row are twice the <em>Starting Block Size</em>, - blocks in the fourth row are four times the - <em>Starting Block Size</em>, and so on. Entries for - blocks up to the <em>Maximum Direct Block Size</em> point to - direct blocks, and entries for blocks greater than that size - point to further indirect blocks (which have their own - entries for direct and indirect blocks). - </p> - - <p> - The number of rows of blocks, <em>nrows</em>, in an - indirect block of size <em>iblock_size</em> is given by the - following expression: - <br /> <br /> - <em>nrows</em> = (log<sub>2</sub>(<em>iblock_size</em>) - - log<sub>2</sub>(<em><Starting Block Size></em> * - <em><Width></em>)) + 1 - </p> - - <p> - The maximum number of rows of direct blocks, <em>max_dblock_rows</em>, - in any indirect block of a fractal heap is given by the - following expression: - <br /> <br /> - <em>max_dblock_rows</em> = - (log<sub>2</sub>(<em><Max. Direct Block Size></em>) - - log<sub>2</sub>(<em><Starting Block Size></em>)) + 2 - </p> - - <p> - Using the computed values for <em>nrows</em> and - <em>max_dblock_rows</em>, along with the <em>Width</em> of the - doubling table, the number of direct and indirect block entries - (<em>K</em> and <em>N</em> in the indirect block description, below) - in an indirect block can be computed: - <br /> <br /> - <em>K</em> = MIN(<em>nrows</em>, <em>max_dblock_rows</em>) * - <em>Width</em> - - <br /> <br /> - If <em>nrows</em> is less than or equal to <em>max_dblock_rows</em>, - <em>N</em> is 0. Otherwise, <em>N</em> is simply computed: - <br /> <br /> - <em>N</em> = <em>K</em> - (<em>max_dblock_rows</em> * - <em>Width</em>) - </p> - - <p> - The size indirect blocks on disk is determined by the number - of rows in the indirect block (computed above). The size of direct - blocks on disk is exactly the size of the block in the doubling - table. - </p> - - <div align="center"> - <table class="format"> - <caption> - Fractal Heap Header - </caption> + </table> +</div> + + +<br /> +<h3> + <a name="FractalHeap"> III.F. Disk Format: Level 1F - Fractal Heap</a> +</h3> + +<p> + Each fractal heap consists of a header and zero or more direct and + indirect blocks (described below). The header contains general + information as well as initialization parameters for the doubling + table. The <em>Root Block Address</em> in the header points to the + first direct or indirect block in the heap. +</p> + +<p> + Fractal heaps are based on a data structure called a <em>doubling + table</em>. A doubling table provides a mechanism for quickly extending an + array-like data structure that minimizes the number of empty blocks in + the heap, while retaining very fast lookup of any element within the + array. More information on fractal heaps and doubling tables can be + found in the RFC “<a + href="Supplements/FractalHeap/PrivateHeap.pdf">Private Heaps in + HDF5</a>.” +</p> + +<p>The fractal heap implements the doubling table structure with + indirect and direct blocks. Indirect blocks in the heap do not actually + contain data for objects in the heap, their “size” is + abstract - they represent the indexing structure for locating the + direct blocks in the doubling table. Direct blocks contain the actual + data for objects stored in the heap.</p> + +<p> + All indirect blocks have a constant number of block entries in each + row, called the <em>width</em> of the doubling table (stored in the + heap header). The number of rows for each indirect block in the heap is + determined by the size of the block that the indirect block represents + in the doubling table (calculation of this is shown below) and is + constant, except for the “root” indirect block, which + expands and shrinks its number of rows as needed. +</p> + +<p> + Blocks in the first <em>two</em> rows of an indirect block are <em>Starting + Block Size</em> number of bytes in size, and the blocks in each subsequent + row are twice the size of the blocks in the previous row. In other + words, blocks in the third row are twice the <em>Starting Block + Size</em>, blocks in the fourth row are four times the <em>Starting + Block Size</em>, and so on. Entries for blocks up to the <em>Maximum + Direct Block Size</em> point to direct blocks, and entries for blocks + greater than that size point to further indirect blocks (which have + their own entries for direct and indirect blocks). +</p> + +<p> + The number of rows of blocks, <em>nrows</em>, in an indirect block of + size <em>iblock_size</em> is given by the following expression: <br /> + <br /> <em>nrows</em> = (log<sub>2</sub>(<em>iblock_size</em>) - log<sub>2</sub>(<em><Starting + Block Size></em> * <em><Width></em>)) + 1 +</p> + +<p> + The maximum number of rows of direct blocks, <em>max_dblock_rows</em>, + in any indirect block of a fractal heap is given by the following + expression: <br /> <br /> <em>max_dblock_rows</em> = (log<sub>2</sub>(<em><Max. + Direct Block Size></em>) - log<sub>2</sub>(<em><Starting Block + Size></em>)) + 2 +</p> + +<p> + Using the computed values for <em>nrows</em> and <em>max_dblock_rows</em>, + along with the <em>Width</em> of the doubling table, the number of + direct and indirect block entries (<em>K</em> and <em>N</em> in the + indirect block description, below) in an indirect block can be + computed: <br /> <br /> <em>K</em> = MIN(<em>nrows</em>, <em>max_dblock_rows</em>) + * <em>Width</em> <br /> <br /> If <em>nrows</em> is less than or + equal to <em>max_dblock_rows</em>, <em>N</em> is 0. Otherwise, <em>N</em> + is simply computed: <br /> <br /> <em>N</em> = <em>K</em> - (<em>max_dblock_rows</em> + * <em>Width</em>) +</p> + +<p>The size indirect blocks on disk is determined by the number of + rows in the indirect block (computed above). The size of direct blocks + on disk is exactly the size of the block in the doubling table.</p> + +<div align="center"> + <table class="format"> + <caption>Fractal Heap Header</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Signature</td> + <td colspan="4">Signature</td> </tr> <tr> - <td>Version</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="2">Heap ID Length</td> - <td colspan="2">I/O Filters’ Encoded Length</td> + <td colspan="2">Heap ID Length</td> + <td colspan="2">I/O Filters’ Encoded Length</td> </tr> <tr> - <td>Flags</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td>Flags</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4">Maximum Size of Managed Objects</td> + <td colspan="4">Maximum Size of Managed Objects</td> </tr> <tr> - <td colspan="4"><br />Next Huge Object ID<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Next Huge Object ID<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />v2 B-tree Address of Huge Objects<sup>O</sup><br /><br /></td> + <td colspan="4"><br />v2 B-tree Address of Huge Objects<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Amount of Free Space in Managed Blocks<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Amount of Free Space in Managed Blocks<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Address of Managed Block Free Space Manager<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address of Managed Block Free Space + Manager<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Amount of Managed Space in Heap<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Amount of Managed Space in Heap<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Amount of Allocated Managed Space in Heap<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Amount of Allocated Managed Space in Heap<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Offset of Direct Block Allocation Iterator in Managed Space<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Offset of Direct Block Allocation + Iterator in Managed Space<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Number of Managed Objects in Heap<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Number of Managed Objects in Heap<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Size of Huge Objects in Heap<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Size of Huge Objects in Heap<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Number of Huge Objects in Heap<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Number of Huge Objects in Heap<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Size of Tiny Objects in Heap<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Size of Tiny Objects in Heap<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Number of Tiny Objects in Heap<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Number of Tiny Objects in Heap<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="2">Table Width</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td colspan="2">Table Width</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4"><br />Starting Block Size<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Starting Block Size<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Maximum Direct Block Size<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Maximum Direct Block Size<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="2">Maximum Heap Size</td> - <td colspan="2">Starting # of Rows in Root Indirect Block</td> + <td colspan="2">Maximum Heap Size</td> + <td colspan="2">Starting # of Rows in Root Indirect Block</td> </tr> <tr> - <td colspan="4"><br />Address of Root Block<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address of Root Block<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="2">Current # of Rows in Root Indirect Block</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td colspan="2">Current # of Rows in Root Indirect Block</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4"><br />Size of Filtered Root Direct Block <em>(optional)</em><sup>L</sup><br /><br /></td> + <td colspan="4"><br />Size of Filtered Root Direct Block <em>(optional)</em><sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4">I/O Filter Mask<em> (optional)</em></td> + <td colspan="4">I/O Filter Mask<em> (optional)</em></td> </tr> <tr> - <td colspan="4">I/O Filter Information<em> (optional, variable size)</em></td> + <td colspan="4">I/O Filter Information<em> (optional, + variable size)</em></td> </tr> <tr> - <td colspan="4">Checksum</td> + <td colspan="4">Checksum</td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="40%">Field Name</th> - <th>Description</th> + <th width="40%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>FRHP</code>” - is used to indicate the - beginning of a fractal heap header. This gives file consistency - checking utilities a better chance of reconstructing a - damaged file. - </p> - </td> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>FRHP</code> + ” is used to indicate the beginning of a fractal heap header. + This gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> </tr> <tr> - <td><p>Version</p></td> - <td> - <p>This document describes version 0.</p> - </td> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> </tr> <tr> - <td><p>Heap ID Length</p></td> - <td> - <p>This is the length in bytes of heap object IDs for this heap.</p> - </td> + <td><p>Heap ID Length</p></td> + <td> + <p>This is the length in bytes of heap object IDs for this heap.</p> + </td> </tr> <tr> - <td><p>I/O Filters’ Encoded Length</p></td> - <td> - <p>This is the size in bytes of the encoded <em>I/O Filter Information</em>. - </p> - </td> + <td><p>I/O Filters’ Encoded Length</p></td> + <td> + <p> + This is the size in bytes of the encoded <em>I/O Filter + Information</em>. + </p> + </td> </tr> <tr> - <td><p>Flags</p></td> - <td> - <p>This field is the heap status flag and is a bit field - indicating additional information about the fractal heap. - <table class="list"> - <tr> - <th width="20%" align="center">Bit(s)</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>If set, the ID value to use for huge object has wrapped - around. If the value for the <em>Next Huge Object ID</em> - has wrapped around, each new huge object inserted into the - heap will require a search for an ID value. - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td>If set, the direct blocks in the heap are checksummed. - </td> - </tr> - <tr> - <td align="center"><code>2-7</code></td> - <td>Reserved</td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>Maximum Size of Managed Objects</p></td> - <td> - <p>This is the maximum size of managed objects allowed in the heap. - Objects greater than this this are ‘huge’ objects and will be - stored in the file directly, rather than in a direct block for - the heap. - </p> - </td> + <td><p>Flags</p></td> + <td> + <p>This field is the heap status flag and is a bit field + indicating additional information about the fractal heap.</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit(s)</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, the ID value to use for huge object has wrapped + around. If the value for the <em>Next Huge Object ID</em> has + wrapped around, each new huge object inserted into the heap will + require a search for an ID value. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, the direct blocks in the heap are checksummed.</td> + </tr> + <tr> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table> + <p></p> + + </td> </tr> <tr> - <td><p>Next Huge Object ID</p></td> - <td> - <p>This is the next ID value to use for a huge object in the heap. - </p> - </td> + <td><p>Maximum Size of Managed Objects</p></td> + <td> + <p>This is the maximum size of managed objects allowed in the + heap. Objects greater than this this are ‘huge’ objects + and will be stored in the file directly, rather than in a direct + block for the heap.</p> + </td> </tr> <tr> - <td><p>v2 B-tree Address of Huge Objects</p></td> - <td> - <p>This is the address of the <a href="#V2Btrees">v2 B-tree</a> - used to track huge objects in the heap. The type of records - stored in the <em>v2 B-tree</em> will - be determined by whether the address & length of a huge object - can fit into a heap ID (if yes, it is a “directly” accessed - huge object) and whether there is a filter used on objects - in the heap. - </p> - </td> + <td><p>Next Huge Object ID</p></td> + <td> + <p>This is the next ID value to use for a huge object in the + heap.</p> + </td> </tr> <tr> - <td><p>Amount of Free Space in Managed Blocks</p></td> - <td> - <p>This is the total amount of free space in managed direct blocks - (in bytes). - </p> - </td> + <td><p>v2 B-tree Address of Huge Objects</p></td> + <td> + <p> + This is the address of the <a href="#V2Btrees">v2 B-tree</a> used + to track huge objects in the heap. The type of records stored in + the <em>v2 B-tree</em> will be determined by whether the address & + length of a huge object can fit into a heap ID (if yes, it is a + “directly” accessed huge object) and whether there is a + filter used on objects in the heap. + </p> + </td> </tr> <tr> - <td><p>Address of Managed Block Free Space Manager</p></td> - <td> - <p>This is the address of the - <em><a href="#FreeSpaceManager">Free-space Manager</a></em> for - managed blocks. - </p> - </td> + <td><p>Amount of Free Space in Managed Blocks</p></td> + <td> + <p>This is the total amount of free space in managed direct + blocks (in bytes).</p> + </td> </tr> <tr> - <td><p>Amount of Managed Space in Heap</p></td> - <td> - <p>This is the total amount of managed space in the heap (in bytes), - essentially the upper bound of the heap’s linear address space. - </p> - </td> + <td><p>Address of Managed Block Free Space Manager</p></td> + <td> + <p> + This is the address of the <em><a href="#FreeSpaceManager">Free-space + Manager</a></em> for managed blocks. + </p> + </td> </tr> - <tr> - <td><p>Amount of Allocated Managed Space in Heap</p></td> - <td> - <p>This is the total amount of managed space (in bytes) actually - allocated in - the heap. This can be less than the <em>Amount of Managed Space - in Heap</em> field, if some direct blocks in the heap’s linear - address space are not allocated. - </p> - </td> - </tr> - - <tr> - <td><p>Offset of Direct Block Allocation Iterator in Managed Space</p></td> - <td> - <p>This is the linear heap offset where the next direct - block should be allocated at (in bytes). This may be less than - the <em>Amount of Managed Space in Heap</em> value because the - heap’s address space is increased by a “row” of direct blocks - at a time, rather than by single direct block increments. - </p> - </td> - </tr> - - <tr> - <td><p>Number of Managed Objects in Heap</p></td> - <td> - <p>This is the number of managed objects in the heap. - </p> - </td> - </tr> - - <tr> - <td><p>Size of Huge Objects in Heap</p></td> - <td> - <p>This is the total size of huge objects in the heap (in bytes). - </p> - </td> - </tr> - - <tr> - <td><p>Number of Huge Objects in Heap</p></td> - <td> - <p>This is the number of huge objects in the heap. - </p> - </td> - </tr> - - <tr> - <td><p>Size of Tiny Objects in Heap</p></td> - <td> - <p>This is the total size of tiny objects that are packed in heap - IDs (in bytes). - </p> - </td> - </tr> - - <tr> - <td><p>Number of Tiny Objects in Heap</p></td> - <td> - <p>This is the number of tiny objects that are packed in heap IDs. - </p> - </td> - </tr> - - <tr> - <td><p>Table Width</p></td> - <td> - <p>This is the number of columns in the doubling table for managed - blocks. This value must be a power of two. - </p> - </td> - </tr> - - <tr> - <td><p>Starting Block Size</p></td> - <td> - <p>This is the starting block size to use in the doubling table for - managed blocks (in bytes). This value must be a power of two. - </p> - </td> - </tr> - - <tr> - <td><p>Maximum Direct Block Size</p></td> - <td> - <p>This is the maximum size allowed for a managed direct block. - Objects inserted into the heap that are larger than this value - (less the # of bytes of direct block prefix/suffix) - are stored as ‘huge’ objects. This value must be a power of - two. - </p> - </td> - </tr> - - <tr> - <td><p>Maximum Heap Size</p></td> - <td> - <p>This is the maximum size of the heap’s linear address space for - managed objects (in bytes). The value stored is the log2 of - the actual value, that is: the # of bits of the address space. - ‘Huge’ and ‘tiny’ objects are not counted in this value, since - they do not store objects in the linear address space of the - heap. - </p> - </td> - </tr> - - <tr> - <td><p>Starting # of Rows in Root Indirect Block</p></td> - <td> - <p>This is the starting number of rows for the root indirect block. - A value of 0 indicates that the root indirect block will have - the maximum number of rows needed to address the heap’s <em>Maximum - Heap Size</em>. - </p> - </td> - </tr> - - <tr> - <td><p>Address of Root Block</p></td> - <td> - <p>This is the address of the root block for the heap. It can - be the <a href="#UndefinedAddress">undefined address</a> if - there is no data in the heap. It either points to a direct - block (if the <em>Current # of Rows in the Root Indirect Block</em> - value is 0), or an indirect block. - </p> - </td> - </tr> - - <tr> - <td><p>Current # of Rows in Root Indirect Block</p></td> - <td> - <p>This is the current number of rows in the root indirect block. - A value of 0 indicates that <em>Address of Root Block</em> - points to direct block instead of indirect block. - </p> - </td> - </tr> - - <tr> - <td><p>Size of Filtered Root Direct Block</p></td> - <td> - <p>This is the size of the root direct block, if filters are - applied to heap objects (in bytes). This field is only - stored in the header if the <em>I/O Filters’ Encoded Length</em> - is greater than 0. - </p> - </td> - </tr> - - <tr> - <td><p>I/O Filter Mask</p></td> - <td> - <p>This is the filter mask for the root direct block, if filters - are applied to heap objects. This mask has the same format as - that used for the filter mask in chunked raw data records in a - <a href="#V1Btrees">v1 B-tree</a>. - This field is only - stored in the header if the <em>I/O Filters’ Encoded Length</em> - is greater than 0. - </p> - </td> - </tr> - - <tr> - <td><p>I/O Filter Information</p></td> - <td> - <p>This is the I/O filter information encoding direct blocks and - huge objects, if filters are applied to heap objects. This - field is encoded as a <a href="#FilterMessage">Filter Pipeline</a> - message. - The size of this field is determined by <em>I/O Filters’ - Encoded Length</em>. - </p> - </td> - </tr> - - <tr> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for the header.</p> - </td> + <tr> + <td><p>Amount of Managed Space in Heap</p></td> + <td> + <p>This is the total amount of managed space in the heap (in + bytes), essentially the upper bound of the heap’s linear + address space.</p> + </td> </tr> - </table> - </div> + <tr> + <td><p>Amount of Allocated Managed Space in Heap</p></td> + <td> + <p> + This is the total amount of managed space (in bytes) actually + allocated in the heap. This can be less than the <em>Amount of + Managed Space in Heap</em> field, if some direct blocks in the + heap’s linear address space are not allocated. + </p> + </td> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Fractal Heap Direct Block - </caption> + <tr> + <td><p>Offset of Direct Block Allocation Iterator in Managed + Space</p></td> + <td> + <p> + This is the linear heap offset where the next direct block should + be allocated at (in bytes). This may be less than the <em>Amount + of Managed Space in Heap</em> value because the heap’s address + space is increased by a “row” of direct blocks at a + time, rather than by single direct block increments. + </p> + </td> + </tr> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <td><p>Number of Managed Objects in Heap</p></td> + <td> + <p>This is the number of managed objects in the heap.</p> + </td> </tr> <tr> - <td colspan="4">Signature</td> + <td><p>Size of Huge Objects in Heap</p></td> + <td> + <p>This is the total size of huge objects in the heap (in + bytes).</p> + </td> </tr> <tr> - <td>Version</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td><p>Number of Huge Objects in Heap</p></td> + <td> + <p>This is the number of huge objects in the heap.</p> + </td> </tr> <tr> - <td colspan="4"><br />Heap Header Address<sup>O</sup><br /><br /></td> + <td><p>Size of Tiny Objects in Heap</p></td> + <td> + <p>This is the total size of tiny objects that are packed in + heap IDs (in bytes).</p> + </td> </tr> <tr> - <td colspan="4">Block Offset <em>(variable size)</em></td> + <td><p>Number of Tiny Objects in Heap</p></td> + <td> + <p>This is the number of tiny objects that are packed in heap + IDs.</p> + </td> </tr> <tr> - <td colspan="4">Checksum <em>(optional)</em></td> + <td><p>Table Width</p></td> + <td> + <p>This is the number of columns in the doubling table for + managed blocks. This value must be a power of two.</p> + </td> </tr> <tr> - <td colspan="4"><br />Object Data <em>(variable size)</em><br /><br /></td> + <td><p>Starting Block Size</p></td> + <td> + <p>This is the starting block size to use in the doubling table + for managed blocks (in bytes). This value must be a power of two.</p> + </td> </tr> - </table> + <tr> + <td><p>Maximum Direct Block Size</p></td> + <td> + <p>This is the maximum size allowed for a managed direct block. + Objects inserted into the heap that are larger than this value + (less the # of bytes of direct block prefix/suffix) are stored as + ‘huge’ objects. This value must be a power of two.</p> + </td> + </tr> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <td><p>Maximum Heap Size</p></td> + <td> + <p>This is the maximum size of the heap’s linear address + space for managed objects (in bytes). The value stored is the log2 + of the actual value, that is: the # of bits of the address space. + ‘Huge’ and ‘tiny’ objects are not counted + in this value, since they do not store objects in the linear + address space of the heap.</p> + </td> + </tr> - </div> + <tr> + <td><p>Starting # of Rows in Root Indirect Block</p></td> + <td> + <p> + This is the starting number of rows for the root indirect block. A + value of 0 indicates that the root indirect block will have the + maximum number of rows needed to address the heap’s <em>Maximum + Heap Size</em>. + </p> + </td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <tr> + <td><p>Address of Root Block</p></td> + <td> + <p> + This is the address of the root block for the heap. It can be the <a + href="#UndefinedAddress">undefined address</a> if there is no data + in the heap. It either points to a direct block (if the <em>Current + # of Rows in the Root Indirect Block</em> value is 0), or an indirect + block. + </p> + </td> </tr> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>FHDB</code>” - is used to indicate the - beginning of a fractal heap direct block. This gives file consistency - checking utilities a better chance of reconstructing a - damaged file. - </p> - </td> + <td><p>Current # of Rows in Root Indirect Block</p></td> + <td> + <p> + This is the current number of rows in the root indirect block. A + value of 0 indicates that <em>Address of Root Block</em> points to + direct block instead of indirect block. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Filtered Root Direct Block</p></td> + <td> + <p> + This is the size of the root direct block, if filters are applied + to heap objects (in bytes). This field is only stored in the header + if the <em>I/O Filters’ Encoded Length</em> is greater than + 0. + </p> + </td> </tr> <tr> - <td><p>Version</p></td> - <td> - <p>This document describes version 0.</p> - </td> + <td><p>I/O Filter Mask</p></td> + <td> + <p> + This is the filter mask for the root direct block, if filters are + applied to heap objects. This mask has the same format as that used + for the filter mask in chunked raw data records in a <a + href="#V1Btrees">v1 B-tree</a>. This field is only stored in the + header if the <em>I/O Filters’ Encoded Length</em> is greater + than 0. + </p> + </td> </tr> <tr> - <td><p>Heap Header Address</p></td> - <td> - <p>This is the address for the fractal heap header that this - block belongs to. This field is principally used for file - integrity checking. - </p> - </td> + <td><p>I/O Filter Information</p></td> + <td> + <p> + This is the I/O filter information encoding direct blocks and huge + objects, if filters are applied to heap objects. This field is + encoded as a <a href="#FilterMessage">Filter Pipeline</a> message. + The size of this field is determined by <em>I/O Filters’ + Encoded Length</em>. + </p> + </td> </tr> <tr> - <td><p>Block Offset</p></td> - <td> - <p>This is the offset of the block within the fractal heap’s - address space (in bytes). The number of bytes used to encode - this field is the <em>Maximum Heap Size</em> (in the heap’s - header) divided by 8 and rounded up to the next highest integer, - for values that are not a multiple of 8. This value is - principally used for file integrity checking. - </p> - </td> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the header.</p> + </td> </tr> + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Fractal Heap Direct Block</caption> + <tr> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for the direct block.</p> - <p>This field is only present if bit 1 of <em>Flags</em> in the - heap’s header is set.</p> - </td> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td><p>Object Data</p></td> - <td> - <p>This section of the direct block stores the actual data for - objects in the heap. The size of this section is determined by - the direct block’s size minus the size of the other fields - stored in the direct block (for example, the <em>Signature</em>, - <em>Version</em>, and others including the <em>Checksum</em> if it is - present). - </p> - </td> + <td colspan="4">Signature</td> </tr> - </table> - </div> + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Fractal Heap Indirect Block - </caption> + <tr> + <td colspan="4"><br />Heap Header Address<sup>O</sup><br /> + <br /></td> + </tr> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <td colspan="4">Block Offset <em>(variable size)</em></td> </tr> <tr> - <td colspan="4">Signature</td> + <td colspan="4">Checksum <em>(optional)</em></td> </tr> <tr> - <td>Version</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td colspan="4"><br />Object Data <em>(variable size)</em><br /> + <br /></td> </tr> + </table> + + <table class="note"> <tr> - <td colspan="4"><br />Heap Header Address<sup>O</sup><br /><br /></td> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> <tr> - <td colspan="4">Block Offset <em>(variable size)</em></td> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td colspan="4"><br />Child Direct Block #0 Address<sup>O</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4"><br />Size of Filtered Direct Block #0 <em>(optional)</em> <sup>L</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4">Filter Mask for Direct Block #0 <em>(optional)</em></td> - </tr> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>FHDB</code> + ” is used to indicate the beginning of a fractal heap direct + block. This gives file consistency checking utilities a better + chance of reconstructing a damaged file. + </p> + </td> + </tr> <tr> - <td colspan="4"><br />Child Direct Block #1 Address<sup>O</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4"><br />Size of Filtered Direct Block #1 <em>(optional)</em><sup>L</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4">Filter Mask for Direct Block #1 <em>(optional)</em></td> - </tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> - <tr> - <td colspan="4">...</td> - </tr> + <tr> + <td><p>Heap Header Address</p></td> + <td> + <p>This is the address for the fractal heap header that this + block belongs to. This field is principally used for file integrity + checking.</p> + </td> + </tr> <tr> - <td colspan="4"><br />Child Direct Block #K-1 Address<sup>O</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4"><br />Size of Filtered Direct Block #K-1 <em>(optional)</em><sup>L</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4">Filter Mask for Direct Block #K-1 <em>(optional)</em></td> - </tr> + <td><p>Block Offset</p></td> + <td> + <p> + This is the offset of the block within the fractal heap’s + address space (in bytes). The number of bytes used to encode this + field is the <em>Maximum Heap Size</em> (in the heap’s + header) divided by 8 and rounded up to the next highest integer, + for values that are not a multiple of 8. This value is principally + used for file integrity checking. + </p> + </td> + </tr> <tr> - <td colspan="4"><br />Child Indirect Block #0 Address<sup>O</sup><br /><br /></td> - </tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the direct block.</p> + <p> + This field is only present if bit 1 of <em>Flags</em> in the + heap’s header is set. + </p> + </td> + </tr> <tr> - <td colspan="4"><br />Child Indirect Block #1 Address<sup>O</sup><br /><br /></td> - </tr> + <td><p>Object Data</p></td> + <td> + <p> + This section of the direct block stores the actual data for objects + in the heap. The size of this section is determined by the direct + block’s size minus the size of the other fields stored in the + direct block (for example, the <em>Signature</em>, <em>Version</em>, + and others including the <em>Checksum</em> if it is present). + </p> + </td> + </tr> - <tr> - <td colspan="4">...</td> - </tr> + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Fractal Heap Indirect Block</caption> <tr> - <td colspan="4"><br />Child Indirect Block #N-1 Address<sup>O</sup><br /><br /></td> - </tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> <tr> - <td colspan="4">Checksum</td> + <td colspan="4">Signature</td> </tr> - </table> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td colspan="4"><br />Heap Header Address<sup>O</sup><br /> + <br /></td> + </tr> - </div> + <tr> + <td colspan="4">Block Offset <em>(variable size)</em></td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <tr> + <td colspan="4"><br />Child Direct Block #0 Address<sup>O</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4"><br />Size of Filtered Direct Block #0 <em>(optional)</em> + <sup>L</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask for Direct Block #0 <em>(optional)</em></td> </tr> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>FHIB</code>” is used to - indicate the beginning of a fractal heap indirect block. This - gives file consistency checking utilities a better chance of - reconstructing a damaged file. - </p> - </td> + <td colspan="4"><br />Child Direct Block #1 Address<sup>O</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4"><br />Size of Filtered Direct Block #1 <em>(optional)</em><sup>L</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask for Direct Block #1 <em>(optional)</em></td> </tr> <tr> - <td><p>Version</p></td> - <td> - <p>This document describes version 0.</p> - </td> + <td colspan="4">...</td> </tr> <tr> - <td><p>Heap Header Address</p></td> - <td> - <p>This is the address for the fractal heap header that this - block belongs to. This field is principally used for file - integrity checking. - </p> - </td> + <td colspan="4"><br />Child Direct Block #K-1 Address<sup>O</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4"><br />Size of Filtered Direct Block #K-1 <em>(optional)</em><sup>L</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4">Filter Mask for Direct Block #K-1 <em>(optional)</em></td> </tr> <tr> - <td><p>Block Offset</p></td> - <td> - <p>This is the offset of the block within the fractal heap’s - address space (in bytes). The number of bytes used to encode - this field is the <em>Maximum Heap Size</em> (in the heap’s - header) divided by 8 and rounded up to the next highest integer, - for values that are not a multiple of 8. This value is - principally used for file integrity checking. - </p> - </td> + <td colspan="4"><br />Child Indirect Block #0 Address<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td><p>Child Direct Block #K Address</p></td> - <td> - <p>This field is the address of the child direct block. - The size of the [uncompressed] direct block can be computed by - its offset in the heap’s linear address space. - </p> - </td> + <td colspan="4"><br />Child Indirect Block #1 Address<sup>O</sup><br /> + <br /></td> </tr> - <tr> - <td><p>Size of Filtered Direct Block #K</p></td> - <td> - <p>This is the size of the child direct block after passing through - the I/O filters defined for this heap (in bytes). If no I/O - filters are present for this heap, this field is not present. - </p> - </td> - </tr> - <tr> - <td><p>Filter Mask for Direct Block #K</p></td> - <td> - <p>This is the I/O filter mask for the filtered direct block. - This mask has the same format as that used for the filter mask - in chunked raw data records in a <a href="#V1Btrees">v1 B-tree</a>. - If no I/O filters are present for this heap, this field is not - present. - </p> - </td> + <tr> + <td colspan="4">...</td> </tr> <tr> - <td><p>Child Indirect Block #N Address</p></td> - <td> - <p>This field is the address of the child indirect block. - The size of the indirect block can be computed by - its offset in the heap’s linear address space. - </p> - </td> + <td colspan="4"><br />Child Indirect Block #N-1 Address<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for the indirect block.</p> - </td> + <td colspan="4">Checksum</td> </tr> + </table> - </table> + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + <tr> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <p>An object in the fractal heap is identified by means of a fractal heap ID, - which encodes information to locate the object in the heap. - Currently, the fractal heap stores an object in one of three ways, - depending on the object’s size:</p> - - <div align="center"> - <table class="list80"> - <tr> - <th width="20%">Type</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center">Tiny</td> - <td> - <p>When an object is small enough to be encoded in the heap ID, the - object’s data is embedded in the fractal heap ID itself. There are - 2 sub-types for this type of object: normal and extended. The - sub-type for tiny heap IDs depends on whether the heap ID is large - enough to store objects greater than 16 bytes or not. If the - heap ID length is 18 bytes or smaller, the ‘normal’ tiny heap ID - form is used. If the heap ID length is greater than 18 bytes in - length, the “extended” form is used. See format description below - for both sub-types. - </p> - </td> - </tr> - - <tr> - <td align="center">Huge</td> - <td> - <p>When the size of an object is larger than <em>Maximum Size of - Managed Objects</em> in the <em>Fractal Heap Header</em>, the - object’s data is stored on its own in the file and the object - is tracked/indexed via a version 2 B-tree. All huge objects - for a particular fractal heap use the same v2 B-tree. All huge - objects for a particular fractal heap use the same format for - their huge object IDs. - </p> - - <p>Depending on whether the IDs for a heap are large enough to hold - the object’s retrieval information and whether I/O pipeline filters - are applied to the heap’s objects, 4 sub-types are derived for - huge object IDs for this heap:</p> - - <div align="center"> - <table class="list"> - <tr> - <th align="left" width="35%">Sub-type</th> - <th align="left">Description</th> - </tr> - - <tr> - <td align="left">Directly accessed, non-filtered</td> - <td> - <p>The object’s address and length are embedded in the - fractal heap ID itself and the object is directly accessed - from them. This allows the object to be accessed without - resorting to the B-tree. - </p> - </td> - </tr> - - <tr> - <td align="left">Directly accessed, filtered</td> - <td> - <p>The filtered object’s address, length, filter mask and - de-filtered size are embedded in the fractal heap ID itself - and the object is accessed directly with them. This allows - the object to be accessed without resorting to the B-tree. - </p> - </td> - </tr> - - <tr> - <td align="left">Indirectly accessed, non-filtered</td> - <td> - <p>The object is located by using a B-tree key embedded in - the fractal heap ID to retrieve the address and length from - the version 2 B-tree for huge objects. Then, the address - and length are used to access the object. - </p> - </td> - </tr> - - <tr> - <td align="left">Indirectly accessed, filtered</td> - <td> - <p>The object is located by using a B-tree key embedded in - the fractal heap ID to retrieve the filtered object’s - address, length, filter mask and de-filtered size from the - version 2 B-tree for huge objects. Then, this information - is used to access the object. - </p> - </td> - </tr> - </table> - </div> - - </td> - </tr> - - <tr> - <td align="center">Managed</td> - <td> - <p>When the size of an object does not meet the above two - conditions, the object is stored and managed via the direct and - indirect blocks based on the doubling table. - </p> - </td> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> - </table> - </div> + <tr> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>FHIB</code> + ” is used to indicate the beginning of a fractal heap + indirect block. This gives file consistency checking utilities a + better chance of reconstructing a damaged file. + </p> + </td> + </tr> - <p>The specific format for each type of heap ID is described below: - </p> + <tr> + <td><p>Version</p></td> + <td> + <p>This document describes version 0.</p> + </td> + </tr> - <div align="center"> - <table class="format"> - <caption>Fractal Heap ID for Tiny Objects (sub-type 1 - ‘Normal’) - </caption> + <tr> + <td><p>Heap Header Address</p></td> + <td> + <p>This is the address for the fractal heap header that this + block belongs to. This field is principally used for file integrity + checking.</p> + </td> + </tr> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> + <td><p>Block Offset</p></td> + <td> + <p> + This is the offset of the block within the fractal heap’s + address space (in bytes). The number of bytes used to encode this + field is the <em>Maximum Heap Size</em> (in the heap’s + header) divided by 8 and rounded up to the next highest integer, + for values that are not a multiple of 8. This value is principally + used for file integrity checking. + </p> + </td> + </tr> <tr> - <td>Version, Type & Length</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td><p>Child Direct Block #K Address</p></td> + <td> + <p>This field is the address of the child direct block. The size + of the [uncompressed] direct block can be computed by its offset in + the heap’s linear address space.</p> + </td> </tr> <tr> - <td colspan="4"><br />Data <em>(variable size)</em></td> + <td><p>Size of Filtered Direct Block #K</p></td> + <td> + <p>This is the size of the child direct block after passing + through the I/O filters defined for this heap (in bytes). If no I/O + filters are present for this heap, this field is not present.</p> + </td> + </tr> + <tr> + <td><p>Filter Mask for Direct Block #K</p></td> + <td> + <p> + This is the I/O filter mask for the filtered direct block. This + mask has the same format as that used for the filter mask in + chunked raw data records in a <a href="#V1Btrees">v1 B-tree</a>. If + no I/O filters are present for this heap, this field is not + present. + </p> + </td> </tr> - </table> - </div> + <tr> + <td><p>Child Indirect Block #N Address</p></td> + <td> + <p>This field is the address of the child indirect block. The + size of the indirect block can be computed by its offset in the + heap’s linear address space.</p> + </td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version, Type & Length</p></td> - <td> - <p>This is a bit field with the following definition: - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>6-7</code></td> - <td>The current version of ID format. This document - describes version 0. - </td> - </tr> - <tr> - <td align="center"><code>4-5</code></td> - <td>The ID type. Tiny objects have a value of <code>2</code>. - </td> - </tr> - <tr> - <td align="center"><code>0-3</code></td> - <td>The length of the tiny object. The value stored - is one less than the actual length (since zero-length - objects are not allowed to be stored in the heap). - For example, an object of actual length 1 has an - encoded length of 0, an object of actual length 2 - has an encoded length of 1, and so on. - </td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>Data</p></td> - <td> - <p>This is the data for the object. - </p> - </td> + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the indirect block.</p> + </td> </tr> - </table> - </div> + </table> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption>Fractal Heap ID for Tiny Objects (sub-type 2 - ‘Extended’) - </caption> +</div> + +<br /> +<p>An object in the fractal heap is identified by means of a fractal + heap ID, which encodes information to locate the object in the heap. + Currently, the fractal heap stores an object in one of three ways, + depending on the object’s size:</p> + +<div align="center"> + <table class="list80"> + <tr> + <th width="20%">Type</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center">Tiny</td> + <td> + <p>When an object is small enough to be encoded in the heap ID, + the object’s data is embedded in the fractal heap ID itself. + There are 2 sub-types for this type of object: normal and extended. + The sub-type for tiny heap IDs depends on whether the heap ID is + large enough to store objects greater than 16 bytes or not. If the + heap ID length is 18 bytes or smaller, the ‘normal’ + tiny heap ID form is used. If the heap ID length is greater than 18 + bytes in length, the “extended” form is used. See + format description below for both sub-types.</p> + </td> + </tr> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> + <td align="center">Huge</td> + <td> + <p> + When the size of an object is larger than <em>Maximum Size of + Managed Objects</em> in the <em>Fractal Heap Header</em>, the + object’s data is stored on its own in the file and the object + is tracked/indexed via a version 2 B-tree. All huge objects for a + particular fractal heap use the same v2 B-tree. All huge objects + for a particular fractal heap use the same format for their huge + object IDs. + </p> + + <p>Depending on whether the IDs for a heap are large enough to + hold the object’s retrieval information and whether I/O + pipeline filters are applied to the heap’s objects, 4 + sub-types are derived for huge object IDs for this heap:</p> + + <div align="center"> + <table class="list"> + <tr> + <th align="left" width="35%">Sub-type</th> + <th align="left">Description</th> + </tr> + + <tr> + <td align="left">Directly accessed, non-filtered</td> + <td> + <p>The object’s address and length are embedded in the + fractal heap ID itself and the object is directly accessed from + them. This allows the object to be accessed without resorting + to the B-tree.</p> + </td> + </tr> + + <tr> + <td align="left">Directly accessed, filtered</td> + <td> + <p>The filtered object’s address, length, filter mask + and de-filtered size are embedded in the fractal heap ID itself + and the object is accessed directly with them. This allows the + object to be accessed without resorting to the B-tree.</p> + </td> + </tr> + + <tr> + <td align="left">Indirectly accessed, non-filtered</td> + <td> + <p>The object is located by using a B-tree key embedded in + the fractal heap ID to retrieve the address and length from the + version 2 B-tree for huge objects. Then, the address and length + are used to access the object.</p> + </td> + </tr> + + <tr> + <td align="left">Indirectly accessed, filtered</td> + <td> + <p>The object is located by using a B-tree key embedded in + the fractal heap ID to retrieve the filtered object’s + address, length, filter mask and de-filtered size from the + version 2 B-tree for huge objects. Then, this information is + used to access the object.</p> + </td> + </tr> + </table> + </div> + + </td> + </tr> <tr> - <td>Version, Type & Length</td> - <td>Extended Length</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td align="center">Managed</td> + <td> + <p>When the size of an object does not meet the above two + conditions, the object is stored and managed via the direct and + indirect blocks based on the doubling table.</p> + </td> </tr> + </table> +</div> + + +<p>The specific format for each type of heap ID is described below: +</p> + +<div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Tiny Objects (sub-type 1 - + ‘Normal’)</caption> <tr> - <td colspan="4">Data <em>(variable size)</em></td> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> - </table> - </div> + <tr> + <td>Version, Type & Length</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version, Type & Length</p></td> - <td> - <p>This is a bit field with the following definition: - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>6-7</code></td> - <td>The current version of ID format. This document - describes version 0. - </td> - </tr> - <tr> - <td align="center"><code>4-5</code></td> - <td>The ID type. Tiny objects have a value of <code>2</code>. - </td> - </tr> - <tr> - <td align="center"><code>0-3</code></td> - <td>These 4 bits, together with the next byte, form an - unsigned 12-bit integer for holding the length of the - object. These 4-bits are bits 8-11 of the 12-bit integer. - See description for the <em>Extended Length</em> field below. - </td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>Extended Length</p></td> - <td> - <p>This byte, together with the 4 bits in the previous byte, - forms an unsigned 12-bit integer for holding the length of - the tiny object. These 8 bits are bits 0-7 of the 12-bit - integer formed. The value stored is one less than the actual - length (since zero-length objects are not allowed to be - stored in the heap). For example, an object of actual length - 1 has an encoded length of 0, an object of actual length - 2 has an encoded length of 1, and so on. - </p> - </td> - </tr> - - <tr> - <td><p>Data</p></td> - <td> - <p>This is the data for the object. - </p> - </td> + <tr> + <td colspan="4"><br />Data <em>(variable size)</em></td> </tr> - </table> - </div> + </table> +</div> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption>Fractal Heap ID for Huge Objects (sub-type 1 & 2): indirectly accessed, non-filtered/filtered - </caption> + <tr> + <td><p>Version, Type & Length</p></td> + <td> + <p>This is a bit field with the following definition:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document describes + version 0.</td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Tiny objects have a value of <code>2</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>The length of the tiny object. The value stored is one + less than the actual length (since zero-length objects are not + allowed to be stored in the heap). For example, an object of + actual length 1 has an encoded length of 0, an object of actual + length 2 has an encoded length of 1, and so on.</td> + </tr> + </table> + <p></p> + + </td> + </tr> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <td><p>Data</p></td> + <td> + <p>This is the data for the object.</p> + </td> </tr> + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Tiny Objects (sub-type 2 - + ‘Extended’)</caption> + <tr> - <td>Version & Type</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4"><br />v2 B-tree Key<sup>L</sup><em> (variable size)</em><br /><br /></td> + <td>Version, Type & Length</td> + <td>Extended Length</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> - </table> + <tr> + <td colspan="4">Data <em>(variable size)</em></td> + </tr> + + </table> +</div> - <table class="note"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> - </div> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <br /> - <div align="center"> - <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <td><p>Version, Type & Length</p></td> + <td> + <p>This is a bit field with the following definition:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document describes + version 0.</td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Tiny objects have a value of <code>2</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>These 4 bits, together with the next byte, form an + unsigned 12-bit integer for holding the length of the object. + These 4-bits are bits 8-11 of the 12-bit integer. See description + for the <em>Extended Length</em> field below. + </td> + </tr> + </table> + <p></p> + + </td> + </tr> + + <tr> + <td><p>Extended Length</p></td> + <td> + <p>This byte, together with the 4 bits in the previous byte, + forms an unsigned 12-bit integer for holding the length of the tiny + object. These 8 bits are bits 0-7 of the 12-bit integer formed. The + value stored is one less than the actual length (since zero-length + objects are not allowed to be stored in the heap). For example, an + object of actual length 1 has an encoded length of 0, an object of + actual length 2 has an encoded length of 1, and so on.</p> + </td> </tr> <tr> - <td><p>Version & Type</p></td> - <td> - <p>This is a bit field with the following definition: - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> + <td><p>Data</p></td> + <td> + <p>This is the data for the object.</p> + </td> + </tr> + + </table> +</div> - <tr> - <td align="center"><code>6-7</code></td> - <td>The current version of ID format. This document - describes version 0. - </td> - </tr> - <tr> - <td align="center"><code>4-5</code></td> - <td>The ID type. Huge objects have a value of <code>1</code>. - </td> - </tr> - <tr> - <td align="center"><code>0-3</code></td> - <td>Reserved. - </td> - </tr> - </table></p> - </td> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Huge Objects (sub-type 1 & 2): + indirectly accessed, non-filtered/filtered</caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td><p>v2 B-tree Key</p></td> - <td><p>This field is the B-tree key for retrieving the information - from the version 2 B-tree for huge objects needed to access the - object. See the description of <a href="#V2Btrees">v2 B-tree</a> - records sub-type 1 & 2 for a description of the fields. New key - values are derived from <em>Next Huge Object ID</em> in the - <em>Fractal Heap Header</em>.</p> + <td>Version & Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />v2 B-tree Key<sup>L</sup><em> + (variable size)</em><br /> + <br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘L’ in the + above table are of the size specified in “Size of + Lengths” field in the superblock.)</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version & Type</p></td> + <td> + <p>This is a bit field with the following definition:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document describes + version 0.</td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Huge objects have a value of <code>1</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved.</td> + </tr> + </table> + <p></p> + </td> </tr> - </table> - </div> + <tr> + <td><p>v2 B-tree Key</p></td> + <td><p> + This field is the B-tree key for retrieving the information from + the version 2 B-tree for huge objects needed to access the object. + See the description of <a href="#V2Btrees">v2 B-tree</a> records + sub-type 1 & 2 for a description of the fields. New key values are + derived from <em>Next Huge Object ID</em> in the <em>Fractal + Heap Header</em>. + </p></td> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption>Fractal Heap ID for Huge Objects (sub-type 3): directly accessed, non-filtered - </caption> + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Huge Objects (sub-type 3): + directly accessed, non-filtered</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td>Version & Type</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td>Version & Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4"><br />Address <sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address <sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Length <sup>L</sup><br /><br /></td> + <td colspan="4"><br />Length <sup>L</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Version & Type</p></td> - <td> - <p>This is a bit field with the following definition: - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> + <td><p>Version & Type</p></td> + <td> + <p>This is a bit field with the following definition:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> - <tr> - <td align="center"><code>6-7</code></td> - <td>The current version of ID format. This document - describes version 0. - </td> - </tr> - <tr> - <td align="center"><code>4-5</code></td> - <td>The ID type. Huge objects have a value of <code>1</code>. - </td> - </tr> - <tr> - <td align="center"><code>0-3</code></td> - <td>Reserved. - </td> - </tr> - </table></p> + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document describes + version 0.</td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Huge objects have a value of <code>1</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved.</td> + </tr> + </table> + <p></p> - </td> + </td> </tr> <tr> @@ -5362,2899 +5492,2913 @@ III.F. Disk Format: Level 1F - Fractal Heap</a></h3> <tr> <td><p>Length</p></td> - <td><p>This field is the length of the object in the file.</p> - </td> + <td><p>This field is the length of the object in the file.</p></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption>Fractal Heap ID for Huge Objects (sub-type 4): directly accessed, filtered - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Huge Objects (sub-type 4): + directly accessed, filtered</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td>Version & Type</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td>Version & Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4"><br />Address <sup>O</sup><br /><br /></td> + <td colspan="4"><br />Address <sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Length <sup>L</sup><br /><br /></td> + <td colspan="4"><br />Length <sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4">Filter Mask</td> + <td colspan="4">Filter Mask</td> </tr> <tr> - <td colspan="4"><br />De-filtered Size <sup>L</sup><br /><br /></td> + <td colspan="4"><br />De-filtered Size <sup>L</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> </tr> <tr> - <td> </td> - <td>(Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Version & Type</p></td> - <td> - <p>This is a bit field with the following definition: - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> + <td><p>Version & Type</p></td> + <td> + <p>This is a bit field with the following definition:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> - <tr> - <td align="center"><code>6-7</code></td> - <td>The current version of ID format. This document - describes version 0. - </td> - </tr> - <tr> - <td align="center"><code>4-5</code></td> - <td>The ID type. Huge objects have a value of <code>1</code>. - </td> - </tr> - <tr> - <td align="center"><code>0-3</code></td> - <td>Reserved. - </td> - </tr> - </table></p> + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document describes + version 0.</td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Huge objects have a value of <code>1</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved.</td> + </tr> + </table> + <p></p> - </td> + </td> </tr> <tr> <td><p>Address</p></td> - <td><p>This field is the address of the filtered object in the file.</p> - </td> - </tr> - - <tr> - <td><p>Length</p></td> - <td><p>This field is the length of the filtered object in the file.</p> - </td> - </tr> - - <tr> - <td><p>Filter Mask</p></td> - <td><p>This field is the I/O pipeline filter mask for the - filtered object in the file.</p> - </td> - </tr> - - <tr> - <td><p>Filtered Size</p></td> - <td><p>This field is the size of the de-filtered object in the file.</p> - </td> - </tr> + <td><p>This field is the address of the filtered object in + the file.</p></td> + </tr> - </table> - </div> + <tr> + <td><p>Length</p></td> + <td><p>This field is the length of the filtered object in + the file.</p></td> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption>Fractal Heap ID for Managed Objects - </caption> + <tr> + <td><p>Filter Mask</p></td> + <td><p>This field is the I/O pipeline filter mask for the + filtered object in the file.</p></td> + </tr> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> + <td><p>Filtered Size</p></td> + <td><p>This field is the size of the de-filtered object in + the file.</p></td> + </tr> + + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Fractal Heap ID for Managed Objects</caption> <tr> - <td>Version & Type</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> + <tr> - <td colspan="4">Offset <em>(variable size)</em></td> + <td>Version & Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Offset <em>(variable size)</em></td> </tr> <tr> - <td colspan="4">Length <em>(variable size)</em></td> + <td colspan="4">Length <em>(variable size)</em></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version & Type</p></td> - <td><p>This is a bit field with the following definition: - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>6-7</code></td> - <td>The current version of ID format. This document - describes version 0. - </td> - </tr> - <tr> - <td align="center"><code>4-5</code></td> - <td>The ID type. Managed objects have a value of <code>0</code>. - </td> - </tr> - <tr> - <td align="center"><code>0-3</code></td> - <td>Reserved. - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Offset</p></td> - <td><p>This field is the offset of the object in the heap. - This field’s size is the minimum number of bytes - necessary to encode the <em>Maximum Heap Size</em> value - (from the <em>Fractal Heap Header</em>). For example, if the - value of the <em>Maximum Heap Size</em> is less than 256 bytes, - this field is 1 byte in length, a <em>Maximum Heap Size</em> - of 256-65535 bytes uses a 2 byte length, and so on.</p></td> - </tr> - - <tr> - <td><p>Length</p></td> - <td><p>This field is the length of the object in the heap. It - is determined by taking the minimum value of <em>Maximum - Direct Block Size</em> and <em>Maximum Size of Managed - Objects</em> in the <em>Fractal Heap Header</em>. Again, - the minimum number of bytes needed to encode that value is - used for the size of this field.</p></td> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> - </table> - </div> - -<br /> -<h3><a name="FreeSpaceManager"> -III.G. Disk Format: Level 1G - Free-space Manager</a></h3> - - <p> - Free-space managers are used to describe space within a heap or - the entire HDF5 file that is not currently used for that heap or - file. - </p> - - <p> - The <em>free-space manager header</em> contains metadata information - about the space being tracked, along with the address of the list - of <em>free space sections</em> which actually describes the free - space. The header records information about free-space sections being - tracked, creation parameters for handling free-space sections of a - client, and section information used to locate the collection of - free-space sections. - </p> - - <p> - The <em>free-space section list</em> stores a collection of - free-space sections that is specific to each <em>client</em> of the - free-space manager. - - For example, the fractal heap is a client of the free space manager - and uses it to track unused space within the heap. There are 4 - types of section records for the fractal heap, each of which has - its own format, listed below. - </p> - - <div align="center"> - <table class="format"> - <caption> - Free-space Manager Header - </caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <td><p>Version & Type</p></td> + <td><p>This is a bit field with the following definition:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>6-7</code></td> + <td>The current version of ID format. This document describes + version 0.</td> + </tr> + <tr> + <td align="center"><code>4-5</code></td> + <td>The ID type. Managed objects have a value of <code>0</code>. + </td> + </tr> + <tr> + <td align="center"><code>0-3</code></td> + <td>Reserved.</td> + </tr> + </table> + <p></p></td> </tr> <tr> - <td colspan="4">Signature</td> + <td><p>Offset</p></td> + <td><p> + This field is the offset of the object in the heap. This + field’s size is the minimum number of bytes necessary to + encode the <em>Maximum Heap Size</em> value (from the <em>Fractal + Heap Header</em>). For example, if the value of the <em>Maximum + Heap Size</em> is less than 256 bytes, this field is 1 byte in length, + a <em>Maximum Heap Size</em> of 256-65535 bytes uses a 2 byte + length, and so on. + </p></td> </tr> <tr> - <td>Version</td> - <td>Client ID</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td><p>Length</p></td> + <td><p> + This field is the length of the object in the heap. It is + determined by taking the minimum value of <em>Maximum Direct + Block Size</em> and <em>Maximum Size of Managed Objects</em> in the <em>Fractal + Heap Header</em>. Again, the minimum number of bytes needed to encode + that value is used for the size of this field. + </p></td> </tr> + </table> +</div> + +<br /> +<h3> + <a name="FreeSpaceManager"> III.G. Disk Format: Level 1G - + Free-space Manager</a> +</h3> + +<p>Free-space managers are used to describe space within a heap or + the entire HDF5 file that is not currently used for that heap or file. +</p> + +<p> + The <em>free-space manager header</em> contains metadata information + about the space being tracked, along with the address of the list of <em>free + space sections</em> which actually describes the free space. The header + records information about free-space sections being tracked, creation + parameters for handling free-space sections of a client, and section + information used to locate the collection of free-space sections. +</p> + +<p> + The <em>free-space section list</em> stores a collection of free-space + sections that is specific to each <em>client</em> of the free-space + manager. For example, the fractal heap is a client of the free space + manager and uses it to track unused space within the heap. There are 4 + types of section records for the fractal heap, each of which has its + own format, listed below. +</p> + +<div align="center"> + <table class="format"> + <caption>Free-space Manager Header</caption> <tr> - <td colspan="4"><br />Total Space Tracked<sup>L</sup><br /><br /></td> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4"><br />Total Number of Sections<sup>L</sup><br /><br /></td> + <td colspan="4">Signature</td> </tr> <tr> - <td colspan="4"><br />Number of Serialized Sections<sup>L</sup><br /><br /></td> - </tr> + <td>Version</td> + <td>Client ID</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <tr> - <td colspan="4"><br />Number of Un-Serialized Sections<sup>L</sup><br /><br /></td> - </tr> + <tr> + <td colspan="4"><br />Total Space Tracked<sup>L</sup><br /> + <br /></td> + </tr> - <tr> - <td colspan="2">Number of Section Classes</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <tr> + <td colspan="4"><br />Total Number of Sections<sup>L</sup><br /> + <br /></td> + </tr> <tr> - <td colspan="2">Shrink Percent</td> - <td colspan="2">Expand Percent</td> + <td colspan="4"><br />Number of Serialized Sections<sup>L</sup><br /> + <br /></td> </tr> <tr> - <td colspan="2">Size of Address Space</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <td colspan="4"><br />Number of Un-Serialized Sections<sup>L</sup><br /> + <br /></td> + </tr> <tr> - <td colspan="4"><br />Maximum Section Size <sup>L</sup><br /><br /></td> - </tr> + <td colspan="2">Number of Section Classes</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> <tr> - <td colspan="4"><br />Address of Serialized Section List<sup>O</sup><br /><br /></td> + <td colspan="2">Shrink Percent</td> + <td colspan="2">Expand Percent</td> </tr> <tr> - <td colspan="4"><br />Size of Serialized Section List Used<sup>L</sup><br /><br /></td> + <td colspan="2">Size of Address Space</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4"><br />Allocated Size of Serialized Section List<sup>L</sup><br /><br /></td> - </tr> + <td colspan="4"><br />Maximum Section Size <sup>L</sup><br /> + <br /></td> + </tr> - <tr> - <td colspan="4">Checksum</td> - </tr> - </table> + <tr> + <td colspan="4"><br />Address of Serialized Section List<sup>O</sup><br /> + <br /></td> + </tr> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td colspan="4"><br />Size of Serialized Section List Used<sup>L</sup><br /> + <br /></td> + </tr> + <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td colspan="4"><br />Allocated Size of Serialized Section List<sup>L</sup><br /> + <br /></td> + </tr> - </div> + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="35%">Field Name</th> - <th>Description</th> + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + <tr> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> </tr> + </table> + +</div> +<br /> +<div align="center"> + <table class="desc"> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>FSHD</code>” is used to - indicate the beginning of the Free-space Manager Header. - This gives file consistency checking utilities a better chance of - reconstructing a damaged file. - </p> - </td> + <th width="35%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Version</p></td> - <td> - <p>This is the version number for the Free-space Manager Header - and this document describes version 0.</p> - </td> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>FSHD</code> + ” is used to indicate the beginning of the Free-space Manager + Header. This gives file consistency checking utilities a better + chance of reconstructing a damaged file. + </p> + </td> </tr> <tr> - <td><p>Client ID</p></td> - <td> - <p>This is the client ID for identifying the user of this - free-space manager: + <td><p>Version</p></td> + <td> + <p>This is the version number for the Free-space Manager Header + and this document describes version 0.</p> + </td> + </tr> + <tr> + <td><p>Client ID</p></td> + <td> + <p>This is the client ID for identifying the user of this + free-space manager:</p> <table class="list"> <tr> - <th width="20%" align="center">ID</th> - <th width="80%" align="left">Description</th> + <th width="20%" align="center">ID</th> + <th width="80%" align="left">Description</th> </tr> <tr> - <td align="center"><code>0</code></td> - <td>Fractal heap - </td> + <td align="center"><code>0</code></td> + <td>Fractal heap</td> </tr> <tr> - <td align="center"><code>1</code></td> - <td>File - </td> + <td align="center"><code>1</code></td> + <td>File</td> </tr> <tr> - <td align="center"><code>2+</code></td> - <td>Reserved. - </td> + <td align="center"><code>2+</code></td> + <td>Reserved.</td> </tr> - </table></p> + </table> + <p></p> - </td> + </td> </tr> - <tr> - <td><p>Total Space Tracked</p></td> - <td> - <p>This is the total amount of free space being tracked, in bytes. - </p> - </td> - </tr> + <tr> + <td><p>Total Space Tracked</p></td> + <td> + <p>This is the total amount of free space being tracked, in + bytes.</p> + </td> + </tr> <tr> - <td><p>Total Number of Sections</p></td> - <td> - <p>This is the total number of free-space sections being tracked. - </p> - </td> + <td><p>Total Number of Sections</p></td> + <td> + <p>This is the total number of free-space sections being + tracked.</p> + </td> </tr> - <tr> - <td><p>Number of Serialized Sections</p></td> - <td> - <p>This is the number of serialized free-space sections being - tracked. - </p> - </td> - </tr> - <tr> - <td><p>Number of Un-Serialized Sections</p></td> - <td> - <p>This is the number of un-serialized free-space sections being - managed. Un-serialized sections are created by the free-space - client when the list of sections is read in. - </p> - </td> + <tr> + <td><p>Number of Serialized Sections</p></td> + <td> + <p>This is the number of serialized free-space sections being + tracked.</p> + </td> + </tr> + <tr> + <td><p>Number of Un-Serialized Sections</p></td> + <td> + <p>This is the number of un-serialized free-space sections being + managed. Un-serialized sections are created by the free-space + client when the list of sections is read in.</p> + </td> </tr> <tr> - <td><p>Number of Section Classes</p></td> - <td> - <p>This is the number of section classes handled by this free space - manager for the free-space client. - </p> - </td> + <td><p>Number of Section Classes</p></td> + <td> + <p>This is the number of section classes handled by this free + space manager for the free-space client.</p> + </td> </tr> <tr> - <td><p>Shrink Percent</p></td> - <td> - <p>This is the percent of current size to shrink the allocated - serialized free-space section list. - </p> - </td> + <td><p>Shrink Percent</p></td> + <td> + <p>This is the percent of current size to shrink the allocated + serialized free-space section list.</p> + </td> </tr> <tr> - <td><p>Expand Percent</p></td> - <td> - <p>This is the percent of current size to expand the allocated - serialized free-space section list. - </p> - </td> + <td><p>Expand Percent</p></td> + <td> + <p>This is the percent of current size to expand the allocated + serialized free-space section list.</p> + </td> </tr> <tr> - <td><p>Size of Address Space</p></td> - <td> - <p>This is the size of the address space that free-space sections - are within. This is stored as the log<sub>2</sub> of the - actual value (in other words, the number of bits required - to store values within that address space). - </p> - </td> + <td><p>Size of Address Space</p></td> + <td> + <p> + This is the size of the address space that free-space sections are + within. This is stored as the log<sub>2</sub> of the actual value + (in other words, the number of bits required to store values within + that address space). + </p> + </td> </tr> <tr> - <td><p>Maximum Section Size</p></td> - <td> - <p>This is the maximum size of a section to be tracked. - </p> - </td> + <td><p>Maximum Section Size</p></td> + <td> + <p>This is the maximum size of a section to be tracked.</p> + </td> </tr> <tr> - <td><p>Address of Serialized Section List</p></td> - <td> - <p>This is the address where the serialized free-space section - list is stored. - </p> - </td> + <td><p>Address of Serialized Section List</p></td> + <td> + <p>This is the address where the serialized free-space section + list is stored.</p> + </td> </tr> <tr> - <td><p>Size of Serialized Section List Used</p></td> - <td> - <p>This is the size of the serialized free-space section - list used (in bytes). This value must be less than - or equal to the <em>allocated size of serialized section - list</em>, below. - </p> - </td> + <td><p>Size of Serialized Section List Used</p></td> + <td> + <p> + This is the size of the serialized free-space section list used (in + bytes). This value must be less than or equal to the <em>allocated + size of serialized section list</em>, below. + </p> + </td> </tr> <tr> - <td><p>Allocated Size of Serialized Section List</p></td> - <td> - <p>This is the size of serialized free-space section list - actually allocated (in bytes). - </p> - </td> + <td><p>Allocated Size of Serialized Section List</p></td> + <td> + <p>This is the size of serialized free-space section list + actually allocated (in bytes).</p> + </td> </tr> <tr> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for the free-space manager header.</p> - </td> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the free-space manager header.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <p>The free-space sections being managed are stored in a - <em>free-space section list</em>, described below. The sections - in the free-space section list are stored in the following way: - a count of the number of sections describing a particular size of - free space and the size of the free-space described (in bytes), - followed by a list of section description records; then another - section count and size, followed by the list of section - descriptions for that size; and so on.</p> - - - <div align="center"> - <table class="format"> - <caption> - Free-space Section List - </caption> +<br /> +<p> + The free-space sections being managed are stored in a <em>free-space + section list</em>, described below. The sections in the free-space section + list are stored in the following way: a count of the number of sections + describing a particular size of free space and the size of the + free-space described (in bytes), followed by a list of section + description records; then another section count and size, followed by + the list of section descriptions for that size; and so on. +</p> + + +<div align="center"> + <table class="format"> + <caption>Free-space Section List</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Signature</td> + <td colspan="4">Signature</td> </tr> <tr> - <td>Version</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4"><br />Free-space Manager Header Address<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Free-space Manager Header Address<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4">Number of Section Records in Set #0 <em>(variable size)</em></td> + <td colspan="4">Number of Section Records in Set #0 <em>(variable + size)</em></td> </tr> <tr> - <td colspan="4">Size of Free-space Section Described in Record Set #0 <em>(variable size)</em></td> - </tr> + <td colspan="4">Size of Free-space Section Described in Record + Set #0 <em>(variable size)</em> + </td> + </tr> - <tr> - <td colspan="4">Record Set #0 Section Record #0 Offset<em>(variable size)</em></td> - </tr> + <tr> + <td colspan="4">Record Set #0 Section Record #0 Offset<em>(variable + size)</em></td> + </tr> - <tr> - <td colspan="1">Record Set #0 Section Record #0 Type</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <tr> + <td colspan="1">Record Set #0 Section Record #0 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <tr> - <td colspan="4">Record Set #0 Section Record #0 Data <em>(variable size)</em></td> - </tr> + <tr> + <td colspan="4">Record Set #0 Section Record #0 Data <em>(variable + size)</em></td> + </tr> - <tr> - <td colspan="4">...</td> - </tr> + <tr> + <td colspan="4">...</td> + </tr> - <tr> - <td colspan="4">Record Set #0 Section Record #K-1 Offset<em>(variable size)</em></td> - </tr> + <tr> + <td colspan="4">Record Set #0 Section Record #K-1 Offset<em>(variable + size)</em></td> + </tr> - <tr> - <td colspan="1">Record Set #0 Section Record #K-1 Type</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <tr> + <td colspan="1">Record Set #0 Section Record #K-1 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <tr> - <td colspan="4">Record Set #0 Section Record #K-1 Data <em>(variable size)</em></td> - </tr> + <tr> + <td colspan="4">Record Set #0 Section Record #K-1 Data <em>(variable + size)</em></td> + </tr> <tr> - <td colspan="4">Number of Section Records in Set #1 <em>(variable size)</em></td> + <td colspan="4">Number of Section Records in Set #1 <em>(variable + size)</em></td> </tr> <tr> - <td colspan="4">Size of Free-space Section Described in Record Set #1 <em>(variable size)</em></td> - </tr> + <td colspan="4">Size of Free-space Section Described in Record + Set #1 <em>(variable size)</em> + </td> + </tr> - <tr> - <td colspan="4">Record Set #1 Section Record #0 Offset<em>(variable size)</em></td> - </tr> + <tr> + <td colspan="4">Record Set #1 Section Record #0 Offset<em>(variable + size)</em></td> + </tr> - <tr> - <td colspan="1">Record Set #1 Section Record #0 Type</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <tr> + <td colspan="1">Record Set #1 Section Record #0 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <tr> - <td colspan="4">Record Set #1 Section Record #0 Data <em>(variable size)</em></td> - </tr> + <tr> + <td colspan="4">Record Set #1 Section Record #0 Data <em>(variable + size)</em></td> + </tr> - <tr> - <td colspan="4">...</td> - </tr> + <tr> + <td colspan="4">...</td> + </tr> - <tr> - <td colspan="4">Record Set #1 Section Record #K-1 Offset<em>(variable size)</em></td> - </tr> + <tr> + <td colspan="4">Record Set #1 Section Record #K-1 Offset<em>(variable + size)</em></td> + </tr> - <tr> - <td colspan="1">Record Set #1 Section Record #K-1 Type</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <tr> + <td colspan="1">Record Set #1 Section Record #K-1 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <tr> - <td colspan="4">Record Set #1 Section Record #K-1 Data <em>(variable size)</em></td> - </tr> + <tr> + <td colspan="4">Record Set #1 Section Record #K-1 Data <em>(variable + size)</em></td> + </tr> - <tr> - <td colspan="4"><strong>...</strong></td> - </tr> + <tr> + <td colspan="4"><strong>...</strong></td> + </tr> - <tr> - <td colspan="4"><strong>...</strong></td> - </tr> + <tr> + <td colspan="4"><strong>...</strong></td> + </tr> <tr> - <td colspan="4">Number of Section Records in Set #N-1 <em>(variable size)</em></td> + <td colspan="4">Number of Section Records in Set #N-1 <em>(variable + size)</em></td> </tr> <tr> - <td colspan="4">Size of Free-space Section Described in Record Set #N-1 <em>(variable size)</em></td> - </tr> + <td colspan="4">Size of Free-space Section Described in Record + Set #N-1 <em>(variable size)</em> + </td> + </tr> - <tr> - <td colspan="4">Record Set #N-1 Section Record #0 Offset<em>(variable size)</em></td> - </tr> + <tr> + <td colspan="4">Record Set #N-1 Section Record #0 Offset<em>(variable + size)</em></td> + </tr> - <tr> - <td colspan="1">Record Set #N-1 Section Record #0 Type</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <tr> + <td colspan="1">Record Set #N-1 Section Record #0 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <tr> - <td colspan="4">Record Set #N-1 Section Record #0 Data <em>(variable size)</em></td> - </tr> + <tr> + <td colspan="4">Record Set #N-1 Section Record #0 Data <em>(variable + size)</em></td> + </tr> - <tr> - <td colspan="4">...</td> - </tr> + <tr> + <td colspan="4">...</td> + </tr> - <tr> - <td colspan="4">Record Set #N-1 Section Record #K-1 Offset<em>(variable size)</em></td> - </tr> + <tr> + <td colspan="4">Record Set #N-1 Section Record #K-1 Offset<em>(variable + size)</em></td> + </tr> - <tr> - <td colspan="1">Record Set #N-1 Section Record #K-1 Type</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <tr> + <td colspan="1">Record Set #N-1 Section Record #K-1 Type</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <tr> - <td colspan="4">Record Set #N-1 Section Record #K-1 Data <em>(variable size)</td> - </tr> + <tr> + <td colspan="4">Record Set #N-1 Section Record #K-1 Data <em>(variable + size)</em></td> + </tr> - <tr> - <td colspan="4">Checksum</td> - </tr> - </table> + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> - </div> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="35%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="35%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>FSSE</code>” is used to - indicate the beginning of the Free-space Section Information. - This gives file consistency checking utilities a better chance of - reconstructing a damaged file. - </p> - </td> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>FSSE</code> + ” is used to indicate the beginning of the Free-space Section + Information. This gives file consistency checking utilities a + better chance of reconstructing a damaged file. + </p> + </td> </tr> <tr> - <td><p>Version</p></td> - <td> - <p>This is the version number for the Free-space Section List - and this document describes version 0.</p> - </td> + <td><p>Version</p></td> + <td> + <p>This is the version number for the Free-space Section List + and this document describes version 0.</p> + </td> </tr> <tr> - <td><p>Free-space Manager Header Address</p></td> - <td> - <p>This is the address of the <em>Free-space Manager Header</em>. - This field is principally used for file - integrity checking. - </p> - </td> + <td><p>Free-space Manager Header Address</p></td> + <td> + <p> + This is the address of the <em>Free-space Manager Header</em>. This + field is principally used for file integrity checking. + </p> + </td> </tr> - <tr> - <td><p>Number of Section Records for Set #N</p></td> - <td> - <p>This is the number of free-space section records for set #N. - The length of this field is the minimum number of bytes needed - to store the <em>number of serialized sections</em> (from the - <em>free-space manager header</em>). - </p> + <tr> + <td><p>Number of Section Records for Set #N</p></td> + <td> + <p> + This is the number of free-space section records for set #N. The + length of this field is the minimum number of bytes needed to store + the <em>number of serialized sections</em> (from the <em>free-space + manager header</em>). + </p> - <p> - The number of sets of free-space section records is - determined by the <em>size of serialized section list</em> in - the <em>free-space manager header</em>. - </p> - </td> - </tr> + <p> + The number of sets of free-space section records is determined by + the <em>size of serialized section list</em> in the <em>free-space + manager header</em>. + </p> + </td> + </tr> <tr> - <td><p>Section Size for Record Set #N</p></td> - <td> - <p>This is the size (in bytes) of the free-space section described - for <em>all</em> the section records in set #N. - </p> + <td><p>Section Size for Record Set #N</p></td> + <td> + <p> + This is the size (in bytes) of the free-space section described for + <em>all</em> the section records in set #N. + </p> - <p> - The length of this field is the minimum number of bytes needed - to store the <em>maximum section size</em> (from the - <em>free-space manager header</em>). - </p> - </td> + <p> + The length of this field is the minimum number of bytes needed to + store the <em>maximum section size</em> (from the <em>free-space + manager header</em>). + </p> + </td> </tr> <tr> - <td><p>Record Set #N Section #K Offset</p></td> - <td> - <p>This is the offset (in bytes) of the free-space section within - the client for the free-space manager. - </p> + <td><p>Record Set #N Section #K Offset</p></td> + <td> + <p>This is the offset (in bytes) of the free-space section + within the client for the free-space manager.</p> - <p> - The length of this field is the minimum number of bytes needed - to store the <em>size of address space</em> (from the - <em>free-space manager header</em>). - </p> - </td> + <p> + The length of this field is the minimum number of bytes needed to + store the <em>size of address space</em> (from the <em>free-space + manager header</em>). + </p> + </td> </tr> <tr> - <td><p>Record Set #N Section #K Type</p></td> - <td> - <p>This is the type of the section record, used to decode the - <em>record set #N section #K data</em> information. The defined - record type for <em>file</em> client is: + <td><p>Record Set #N Section #K Type</p></td> + <td> + <p> + This is the type of the section record, used to decode the <em>record + set #N section #K data</em> information. The defined record type for <em>file</em> + client is: + </p> <table class="list"> <tr> - <th width="20%" align="center">Type</th> - <th width="80%" align="left">Description</th> + <th width="20%" align="center">Type</th> + <th width="80%" align="left">Description</th> </tr> <tr> - <td align="center"><code>0</code></td> - <td>File’s section (a range of actual bytes in file) - </td> + <td align="center"><code>0</code></td> + <td>File’s section (a range of actual bytes in file)</td> </tr> <tr> - <td align="center"><code>1+</code></td> - <td>Reserved. - </td> + <td align="center"><code>1+</code></td> + <td>Reserved.</td> </tr> - </table></p> + </table> + <p></p> - <p>The defined record types for a <em>fractal heap</em> client are: + <p> + The defined record types for a <em>fractal heap</em> client are: + </p> <table class="list"> <tr> - <th width="20%" align="center">Type</th> - <th width="80%" align="left">Description</th> + <th width="20%" align="center">Type</th> + <th width="80%" align="left">Description</th> </tr> <tr> - <td align="center"><code>0</code></td> - <td>Fractal heap “single” section - </td> + <td align="center"><code>0</code></td> + <td>Fractal heap “single” section</td> </tr> <tr> - <td align="center"><code>1</code></td> - <td>Fractal heap “first row” section - </td> + <td align="center"><code>1</code></td> + <td>Fractal heap “first row” section</td> </tr> <tr> - <td align="center"><code>2</code></td> - <td>Fractal heap “normal row” section - </td> + <td align="center"><code>2</code></td> + <td>Fractal heap “normal row” section</td> </tr> <tr> - <td align="center"><code>3</code></td> - <td>Fractal heap “indirect” section - </td> + <td align="center"><code>3</code></td> + <td>Fractal heap “indirect” section</td> </tr> <tr> - <td align="center"><code>4+</code></td> - <td>Reserved. - </td> + <td align="center"><code>4+</code></td> + <td>Reserved.</td> </tr> - </table></p> + </table> + <p></p> - </td> + </td> </tr> <tr> - <td><p>Record Set #N Section #K Data</p></td> - <td> - <p>This is the section-type specific information for each record - in the record set, described below. - </p> - </td> + <td><p>Record Set #N Section #K Data</p></td> + <td> + <p>This is the section-type specific information for each record + in the record set, described below.</p> + </td> </tr> <tr> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for the <em>Free-space Section List</em>. - </p> - </td> + <td><p>Checksum</p></td> + <td> + <p> + This is the checksum for the <em>Free-space Section List</em>. + </p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <p> - The section-type specific data for each free-space section record is - described below: - </p> +<br /> +<p>The section-type specific data for each free-space section record + is described below:</p> - <div align="center"> - <table class="format"> - <caption> - File’s Section Data Record - </caption> +<div align="center"> + <table class="format"> + <caption>File’s Section Data Record</caption> <tr> - <td colspan="4"><em>No additional record data stored</em></td> + <td colspan="4"><em>No additional record data stored</em></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Fractal Heap “Single” Section Data Record - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Fractal Heap “Single” Section Data + Record</caption> <tr> - <td colspan="4"><em>No additional record data stored</em></td> + <td colspan="4"><em>No additional record data stored</em></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Fractal Heap “First Row” Section Data Record - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Fractal Heap “First Row” Section Data + Record</caption> <tr> - <td colspan="4"><em>Same format as “indirect” section data</em></td> + <td colspan="4"><em>Same format as “indirect” + section data</em></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Fractal Heap “Normal Row” Section Data Record - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Fractal Heap “Normal Row” Section Data + Record</caption> <tr> - <td colspan="4"><em>No additional record data stored</em></td> + <td colspan="4"><em>No additional record data stored</em></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Fractal Heap “Indirect” Section Data Record - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Fractal Heap “Indirect” Section Data + Record</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Fractal Heap Indirect Block Offset <em>(variable size)</em></td> + <td colspan="4">Fractal Heap Indirect Block Offset <em>(variable + size)</em></td> </tr> <tr> - <td colspan="2">Block Start Row</td> - <td colspan="2">Block Start Column</td> + <td colspan="2">Block Start Row</td> + <td colspan="2">Block Start Column</td> </tr> <tr> - <td colspan="2">Number of Blocks</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td colspan="2">Number of Blocks</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Fractal Heap Block Offset</p></td> - <td> - <p>The offset of the indirect block in the fractal heap’s address - space containing the empty blocks. - </p> - <p> - The number of bytes used to encode this field is the minimum - number of bytes needed to encode values for the <em>Maximum - Heap Size</em> (in the fractal heap’s header). - </p> - </td> + <td><p>Fractal Heap Block Offset</p></td> + <td> + <p>The offset of the indirect block in the fractal heap’s + address space containing the empty blocks.</p> + <p> + The number of bytes used to encode this field is the minimum number + of bytes needed to encode values for the <em>Maximum Heap Size</em> + (in the fractal heap’s header). + </p> + </td> </tr> <tr> - <td><p>Block Start Row</p></td> - <td> - <p>This is the row that the empty blocks start in. - </p> - </td> + <td><p>Block Start Row</p></td> + <td> + <p>This is the row that the empty blocks start in.</p> + </td> </tr> <tr> - <td><p>Block Start Column</p></td> - <td> - <p>This is the column that the empty blocks start in. - </p> - </td> + <td><p>Block Start Column</p></td> + <td> + <p>This is the column that the empty blocks start in.</p> + </td> </tr> <tr> - <td><p>Number of Blocks</p></td> - <td> - <p>This is the number of empty blocks covered by the section. - </p> - </td> + <td><p>Number of Blocks</p></td> + <td> + <p>This is the number of empty blocks covered by the section.</p> + </td> </tr> - </table> - </div> - -<br /> -<h3><a name="SOHMTable"> -III.H. Disk Format: Level 1H - Shared Object Header Message Table</a></h3> - - <p> - The <em>shared object header message table</em> is used to locate - object - header messages that are shared between two or more object headers - in the file. Shared object header messages are stored and indexed - in the file in one of two ways: indexed sequentially in a - <em>shared header message list</em> or indexed with a v2 B-tree. - The shared messages themselves are either stored in a fractal - heap (when two or more objects share the message), or remain in an - object’s header (when only one object uses the message currently, - but the message can be shared in the future). - </p> - - <p> - The <em>shared object header message table</em> - contains a list of shared message index headers. Each index header - records information about the version of the index format, the index - storage type, flags for the message types indexed, the number of - messages in the index, the address where the index resides, - and the fractal heap address if shared messages are stored there. - </p> - - <p> - Each index can be either a list or a v2 B-tree and may transition - between those two forms as the number of messages in the index - varies. Each shared message record contains information used to - locate the shared message from either a fractal heap or an object - header. The types of messages that can be shared are: <em>Dataspace, - Datatype, Fill Value, Filter Pipeline and Attribute</em>. - </p> - - <p> - The <em>shared object header message table</em> is pointed to - from a <a href="#SOHMTableMessage">shared message table</a> message - in the superblock extension for a file. This message stores the - version of the table format, along with the number of index headers - in the table. - </p> - - <div align="center"> - <table class="format"> - <caption> - Shared Object Header Message Table - </caption> + </table> +</div> + +<br /> +<h3> + <a name="SOHMTable"> III.H. Disk Format: Level 1H - Shared Object + Header Message Table</a> +</h3> + +<p> + The <em>shared object header message table</em> is used to locate + object header messages that are shared between two or more object + headers in the file. Shared object header messages are stored and + indexed in the file in one of two ways: indexed sequentially in a <em>shared + header message list</em> or indexed with a v2 B-tree. The shared messages + themselves are either stored in a fractal heap (when two or more + objects share the message), or remain in an object’s header (when + only one object uses the message currently, but the message can be + shared in the future). +</p> + +<p> + The <em>shared object header message table</em> contains a list of + shared message index headers. Each index header records information + about the version of the index format, the index storage type, flags + for the message types indexed, the number of messages in the index, the + address where the index resides, and the fractal heap address if shared + messages are stored there. +</p> + +<p> + Each index can be either a list or a v2 B-tree and may transition + between those two forms as the number of messages in the index varies. + Each shared message record contains information used to locate the + shared message from either a fractal heap or an object header. The + types of messages that can be shared are: <em>Dataspace, Datatype, + Fill Value, Filter Pipeline and Attribute</em>. +</p> + +<p> + The <em>shared object header message table</em> is pointed to from a <a + href="#SOHMTableMessage">shared message table</a> message in the + superblock extension for a file. This message stores the version of the + table format, along with the number of index headers in the table. +</p> + +<div align="center"> + <table class="format"> + <caption>Shared Object Header Message Table</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Signature</td> + <td colspan="4">Signature</td> </tr> <tr> - <td>Version for index #0</td> - <td>Index Type for index #0</td> - <td colspan="2">Message Type Flags for index #0</td> + <td>Version for index #0</td> + <td>Index Type for index #0</td> + <td colspan="2">Message Type Flags for index #0</td> </tr> <tr> - <td colspan="4">Minimum Message Size for index #0</td> + <td colspan="4">Minimum Message Size for index #0</td> </tr> <tr> - <td colspan="2">List Cutoff for index #0</td> - <td colspan="2">v2 B-tree Cutoff for index #0</td> + <td colspan="2">List Cutoff for index #0</td> + <td colspan="2">v2 B-tree Cutoff for index #0</td> </tr> <tr> - <td colspan="2">Number of Messages for index #0</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <td colspan="2">Number of Messages for index #0</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <tr> - <td colspan="4"><br />Index Address<sup>O</sup> for index #0<br /><br /></td> - </tr> + <tr> + <td colspan="4"><br />Index Address<sup>O</sup> for index #0<br /> + <br /></td> + </tr> - <tr> - <td colspan="4"><br />Fractal Heap Address<sup>O</sup> for index #0<br /><br /></td> - </tr> + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup> for + index #0<br /> + <br /></td> + </tr> <tr> - <td colspan="4">...</td> - </tr> + <td colspan="4">...</td> + </tr> <tr> - <td colspan="4">...</td> - </tr> + <td colspan="4">...</td> + </tr> <tr> - <td>Version for index #N-1</td> - <td>Index Type for index #N-1</td> - <td colspan="2">Message Type Flags for index #N-1</td> + <td>Version for index #N-1</td> + <td>Index Type for index #N-1</td> + <td colspan="2">Message Type Flags for index #N-1</td> </tr> <tr> - <td colspan="4">Minimum Message Size for index #N-1</td> + <td colspan="4">Minimum Message Size for index #N-1</td> </tr> <tr> - <td colspan="2">List Cutoff for index #N-1</td> - <td colspan="2">v2 B-tree Cutoff for index #N-1</td> + <td colspan="2">List Cutoff for index #N-1</td> + <td colspan="2">v2 B-tree Cutoff for index #N-1</td> </tr> <tr> - <td colspan="2">Number of Messages for index #N-1</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <td colspan="2">Number of Messages for index #N-1</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <tr> - <td colspan="4"><br />Index Address<sup>O</sup> for index #N-1<br /><br /></td> - </tr> + <tr> + <td colspan="4"><br />Index Address<sup>O</sup> for index #N-1<br /> + <br /></td> + </tr> - <tr> - <td colspan="4"><br />Fractal Heap Address<sup>O</sup> for index #N-1<br /><br /></td> - </tr> + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup> for + index #N-1<br /> + <br /></td> + </tr> - <tr> - <td colspan="4">Checksum</td> - </tr> - </table> + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="35%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="35%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>SMTB</code>” is used to - indicate the beginning of the Shared Object Header Message table. - This gives file consistency checking utilities a better chance of - reconstructing a damaged file. - </p> - </td> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>SMTB</code> + ” is used to indicate the beginning of the Shared Object + Header Message table. This gives file consistency checking + utilities a better chance of reconstructing a damaged file. + </p> + </td> </tr> <tr> - <td><p>Version for index #N</p></td> - <td> - <p>This is the version number for the list of shared object header message - indexes and this document describes version 0.</p> - </td> + <td><p>Version for index #N</p></td> + <td> + <p>This is the version number for the list of shared object + header message indexes and this document describes version 0.</p> + </td> </tr> <tr> - <td><p>Index Type for index #N</p></td> - <td> - <p>The type of index can be an unsorted list or a v2 B-tree. - </p> - </td> + <td><p>Index Type for index #N</p></td> + <td> + <p>The type of index can be an unsorted list or a v2 B-tree.</p> + </td> </tr> - <tr> - <td><p>Message Type Flags for index #N</p></td> - <td> - <p>This field indicates the type of messages tracked in the index, - as follows: + <tr> + <td><p>Message Type Flags for index #N</p></td> + <td> + <p>This field indicates the type of messages tracked in the + index, as follows:</p> <table class="list"> <tr> - <th width="20%" align="center">Bits</th> - <th width="80%" align="left">Description</th> + <th width="20%" align="center">Bits</th> + <th width="80%" align="left">Description</th> </tr> <tr> - <td align="center"><code>0</code></td> - <td>If set, the index tracks <em>Dataspace Messages</em>. - </td> + <td align="center"><code>0</code></td> + <td>If set, the index tracks <em>Dataspace Messages</em>. + </td> </tr> <tr> - <td align="center"><code>1</code></td> - <td>If set, the message tracks <em>Datatype Messages</em>. - </td> + <td align="center"><code>1</code></td> + <td>If set, the message tracks <em>Datatype Messages</em>. + </td> </tr> <tr> - <td align="center"><code>2</code></td> - <td>If set, the message tracks <em>Fill Value Messages</em>. - </td> + <td align="center"><code>2</code></td> + <td>If set, the message tracks <em>Fill Value Messages</em>. + </td> </tr> <tr> - <td align="center"><code>3</code></td> - <td>If set, the message tracks <em>Filter Pipeline Messages</em>. - </td> + <td align="center"><code>3</code></td> + <td>If set, the message tracks <em>Filter Pipeline + Messages</em>. + </td> </tr> <tr> - <td align="center"><code>4</code></td> - <td>If set, the message tracks <em>Attribute Messages</em>. - </td> + <td align="center"><code>4</code></td> + <td>If set, the message tracks <em>Attribute Messages</em>. + </td> </tr> <tr> - <td align="center"><code>5-15</code></td> - <td>Reserved (zero). - </td> + <td align="center"><code>5-15</code></td> + <td>Reserved (zero).</td> </tr> - </table></p> + </table> + <p></p> - <p> - An index can track more than one type of message, but each type - of message can only by in one index. - </p> - </td> - </tr> + <p>An index can track more than one type of message, but each + type of message can only by in one index.</p> + </td> + </tr> <tr> - <td><p>Minimum Message Size for index #N</p></td> - <td> - <p>This is the message size sharing threshold for the index. - If the encoded size of the message is less than this value, the - message is not shared. - </p> - </td> + <td><p>Minimum Message Size for index #N</p></td> + <td> + <p>This is the message size sharing threshold for the index. If + the encoded size of the message is less than this value, the + message is not shared.</p> + </td> </tr> - <tr> - <td><p>List Cutoff for index #N</p></td> - <td> - <p>This is the cutoff value for the indexing of messages to - switch from a list to a v2 B-tree. If the number of messages - is greater than this value, the index should be a v2 B-tree. - </p> - </td> - </tr> - <tr> - <td><p>v2 B-tree Cutoff for index #N</p></td> - <td> - <p>This is the cutoff value for the indexing of messages to - switch from a v2 B-tree back to a list. If the number of - messages is less than this value, the index should be a list. - </p> - </td> + <tr> + <td><p>List Cutoff for index #N</p></td> + <td> + <p>This is the cutoff value for the indexing of messages to + switch from a list to a v2 B-tree. If the number of messages is + greater than this value, the index should be a v2 B-tree.</p> + </td> + </tr> + <tr> + <td><p>v2 B-tree Cutoff for index #N</p></td> + <td> + <p>This is the cutoff value for the indexing of messages to + switch from a v2 B-tree back to a list. If the number of messages + is less than this value, the index should be a list.</p> + </td> </tr> <tr> - <td><p>Number of Messages for index #N</p></td> - <td> - <p>The number of shared messages being tracked for the index. - </p> - </td> + <td><p>Number of Messages for index #N</p></td> + <td> + <p>The number of shared messages being tracked for the index.</p> + </td> </tr> <tr> - <td><p>Index Address for index #N</p></td> - <td> - <p>This field is the address of the list or v2 B-tree where the - index nodes reside. - </p> - </td> + <td><p>Index Address for index #N</p></td> + <td> + <p>This field is the address of the list or v2 B-tree where the + index nodes reside.</p> + </td> </tr> <tr> - <td><p>Fractal Heap Address for index #N</p></td> - <td> - <p>This field is the address of the fractal heap if shared messages - are stored there. - </p> - </td> + <td><p>Fractal Heap Address for index #N</p></td> + <td> + <p>This field is the address of the fractal heap if shared + messages are stored there.</p> + </td> </tr> <tr> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for the table.</p> - </td> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the table.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <p> - Shared messages are indexed either with a <em>shared message record - list</em>, described below, or using a v2 B-tree (using record type 7). - The number of records in the <em>shared message record list</em> is - determined in the index’s entry in the <em>shared object header message - table</em>. - </p> - - <div align="center"> - <table class="format"> - <caption> - Shared Message Record List - </caption> +<br /> +<p> + Shared messages are indexed either with a <em>shared message + record list</em>, described below, or using a v2 B-tree (using record type + 7). The number of records in the <em>shared message record list</em> is + determined in the index’s entry in the <em>shared object + header message table</em>. +</p> + +<div align="center"> + <table class="format"> + <caption>Shared Message Record List</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td colspan="4">Signature</td> + <td colspan="4">Signature</td> </tr> <tr> - <td colspan="4">Shared Message Record #0</td> + <td colspan="4">Shared Message Record #0</td> </tr> <tr> - <td colspan="4">Shared Message Record #1</td> + <td colspan="4">Shared Message Record #1</td> </tr> <tr> - <td colspan="4">...</td> + <td colspan="4">...</td> </tr> <tr> - <td colspan="4">Shared Message Record #N-1</td> + <td colspan="4">Shared Message Record #N-1</td> </tr> <tr> - <td colspan="4">Checksum</td> + <td colspan="4">Checksum</td> </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>SMLI</code>” is used to - indicate the beginning of a list of index nodes. - This gives file consistency checking utilities a better chance of - reconstructing a damaged file. - </p> - </td> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>SMLI</code> + ” is used to indicate the beginning of a list of index nodes. + This gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> </tr> <tr> - <td><p>Shared Message Record #N</p></td> - <td> - <p>The record for locating the shared message, either in the - fractal heap for the index, or an object header (see format for - <em>index nodes</em> below). - </p> - </td> + <td><p>Shared Message Record #N</p></td> + <td> + <p> + The record for locating the shared message, either in the fractal + heap for the index, or an object header (see format for <em>index + nodes</em> below). + </p> + </td> </tr> <tr> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for the list. - </p> - </td> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the list.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <p> - The record for each shared message in an index is stored in one of the - following forms: - </p> +<br /> +<p>The record for each shared message in an index is stored in one + of the following forms:</p> - <div align="center"> - <table class="format"> - <caption> - Shared Message Record, for messages stored in a fractal heap - </caption> +<div align="center"> + <table class="format"> + <caption>Shared Message Record, for messages stored in a + fractal heap</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td>Message Location</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4">Hash Value</td> + <td colspan="4">Hash Value</td> </tr> <tr> - <td colspan="4">Reference Count</td> + <td colspan="4">Reference Count</td> </tr> <tr> - <td colspan="4"><br />Fractal Heap ID<br /><br /></td> + <td colspan="4"><br />Fractal Heap ID<br /> + <br /></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Message Location</p></td> - <td> - <p>This has a value of 0 indicating that the message is stored in - the heap. - </p> - </td> + <td><p>Message Location</p></td> + <td> + <p>This has a value of 0 indicating that the message is stored + in the heap.</p> + </td> </tr> <tr> - <td><p>Hash Value</p></td> - <td> - <p>This is the hash value for the message. - </p> - </td> + <td><p>Hash Value</p></td> + <td> + <p>This is the hash value for the message.</p> + </td> </tr> <tr> - <td><p>Reference Count</p></td> - <td> - <p>This is the number of times the message is used in the file. - </p> - </td> + <td><p>Reference Count</p></td> + <td> + <p>This is the number of times the message is used in the file. + </p> + </td> </tr> <tr> - <td><p>Fractal Heap ID</p></td> - <td> - <p>This is an 8-byte fractal heap ID for the message as stored in - the fractal heap for the index. - </p> - </td> + <td><p>Fractal Heap ID</p></td> + <td> + <p>This is an 8-byte fractal heap ID for the message as stored + in the fractal heap for the index.</p> + </td> </tr> - </table> - </div> + </table> +</div> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Shared Message Record, for messages stored in an object header - </caption> +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Shared Message Record, for messages stored in an + object header</caption> <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> <tr> - <td>Message Location</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> + <td>Message Location</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> </tr> <tr> - <td colspan="4">Hash Value</td> + <td colspan="4">Hash Value</td> </tr> <tr> - <td>Reserved</td> - <td>Message Type</td> - <td colspan="2">Creation Index</td> + <td>Reserved</td> + <td>Message Type</td> + <td colspan="2">Creation Index</td> </tr> <tr> - <td colspan="4"><br />Object Header Address<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Object Header Address<sup>O</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Message Location</p></td> - <td> - <p>This has a value of 1 indicating that the message is stored in - an object header. - </p> - </td> + <td><p>Message Location</p></td> + <td> + <p>This has a value of 1 indicating that the message is stored + in an object header.</p> + </td> </tr> <tr> - <td><p>Hash Value</p></td> - <td> - <p>This is the hash value for the message. - </p> - </td> + <td><p>Hash Value</p></td> + <td> + <p>This is the hash value for the message.</p> + </td> </tr> <tr> - <td><p>Message Type</p></td> - <td> - <p>This is the message type in the object header. - </p> - </td> + <td><p>Message Type</p></td> + <td> + <p>This is the message type in the object header.</p> + </td> </tr> <tr> - <td><p>Creation Index</p></td> - <td> - <p>This is the creation index of the message within the object - header. - </p> - </td> + <td><p>Creation Index</p></td> + <td> + <p>This is the creation index of the message within the object + header.</p> + </td> </tr> <tr> - <td><p>Object Header Address</p></td> - <td> - <p>This is the address of the object header where the message is - located. - </p> - </td> + <td><p>Object Header Address</p></td> + <td> + <p>This is the address of the object header where the message is + located.</p> + </td> </tr> - </table> - </div> + </table> +</div> <br /> <br /> <hr /> -<h2><a name="DataObject"> -IV. Disk Format: Level 2 - Data Objects </a></h2> - - <p>Data objects contain the “real” user-visible information in the file. - These objects compose the scientific data and other information which - are generally thought of as “data” by the end-user. All the - other information in the file is provided as a framework for - storing and accessing these data objects. - </p> - - <p>A data object is composed of header and data - information. The header information contains the information - needed to interpret the data information for the object as - well as additional “metadata” or pointers to additional - “metadata” used to describe or annotate each object. - </p> - -<br /> -<h3><a name="ObjectHeader"> -IV.A. Disk Format: Level 2A - Data Object Headers</a></h3> - - <p>The header information of an object is designed to encompass - all of the information about an object, except for the data itself. - This information includes the dataspace, the datatype, information - about how the data is stored on disk (in external files, compressed, - broken up in blocks, and so on), as well as other information used - by the library to speed up access to the data objects or maintain - a file’s integrity. Information stored by user applications - as attributes is also stored in the object’s header. The header - of each object is not necessarily located immediately prior to the - object’s data in the file and in fact may be located in any - position in the file. The order of the messages in an object header - is not significant.</p> - - <p>Object headers are composed of a prefix and a set of messages. The - prefix contains the information needed to interpret the messages and - a small amount of metadata about the object, and the messages contain - the majority of the metadata about the object. - </p> - -<br /> -<h3><a name="ObjectHeaderPrefix"> -IV.A.1. Disk Format: Level 2A1 - Data Object Header Prefix</a></h3> - -<br /> -<h4><a name="V1ObjectHeaderPrefix"> -IV.A.1.a. Version 1 Data Object Header Prefix</a></h4> - - <p>Header messages are aligned on 8-byte boundaries for version 1 - object headers. - </p> - - <div align="center"> - <table class="format"> - <caption> - Version 1 Object Header - </caption> - - <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Reserved (zero)</td> - <td colspan="2">Total Number of Header Messages</td> - </tr> - - <tr> - <td colspan="4">Object Reference Count</td> - </tr> - - <tr> - <td colspan="4">Object Header Size</td> - </tr> - - <tr> - <td colspan="2">Header Message Type #1</td> - <td colspan="2">Size of Header Message Data #1</td> - </tr> - - <tr> - <td>Header Message #1 Flags</td> - <td colspan="3">Reserved (zero)</td> - </tr> - - <tr> - <td colspan="4"><br />Header Message Data #1<br /><br /></td> - </tr> - - <tr> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - - <tr> - <td colspan="2">Header Message Type #n</td> - <td colspan="2">Size of Header Message Data #n</td> - </tr> - - <tr> - <td>Header Message #n Flags</td> - <td colspan="3">Reserved (zero)</td> - </tr> - - <tr> - <td colspan="4"><br />Header Message Data #n<br /><br /></td> - </tr> - </table> - </div> +<h2> + <a name="DataObject"> IV. Disk Format: Level 2 - Data Objects </a> +</h2> + +<p>Data objects contain the “real” user-visible + information in the file. These objects compose the scientific data and + other information which are generally thought of as “data” + by the end-user. All the other information in the file is provided as a + framework for storing and accessing these data objects.</p> + +<p>A data object is composed of header and data information. The + header information contains the information needed to interpret the + data information for the object as well as additional + “metadata” or pointers to additional “metadata” + used to describe or annotate each object.</p> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td> - <p>This value is used to determine the format of the - information in the object header. When the format of the - object header is changed, the version number - is incremented and can be used to determine how the - information in the object header is formatted. This - is version one (1) (there was no version zero (0)) of the - object header. - </p> - </td> - </tr> - - <tr> - <td><p>Total Number of Header Messages</p></td> - <td> - <p>This value determines the total number of messages listed in - object headers for this object. This value includes the messages - in continuation messages for this object. - </p> - </td> - </tr> - - <tr> - <td><p>Object Reference Count</p></td> - <td> - <p>This value specifies the number of “hard links” to this object - within the current file. References to the object from external - files, “soft links” in this file and object references in this - file are not tracked. - </p> - </td> - </tr> - - <tr> - <td><p>Object Header Size</p></td> - <td> - <p>This value specifies the number of bytes of header message data - following this length field that contain object header messages - for this object header. This value does not include the size of - object header continuation blocks for this object elsewhere in the - file. - </p> - </td> - </tr> - - <tr> - <td><p>Header Message #n Type</p></td> - <td> - <p>This value specifies the type of information included in the - following header message data. The message types for - header messages are defined in sections below. - </p> - </td> - </tr> - - <tr> - <td><p>Size of Header Message #n Data</p></td> - <td> - <p>This value specifies the number of bytes of header - message data following the header message type and length - information for the current message. The size includes - padding bytes to make the message a multiple of eight - bytes. - </p> - </td> - </tr> - - <tr> - <td><p>Header Message #n Flags</p></td> - <td> - <p>This is a bit field with the following definition: - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>If set, the message data is constant. This is used - for messages like the datatype message of a dataset. - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td>If set, the message is <em>shared</em> and stored - in another location than the object header. The Header - Message Data field contains a Shared Message - (described in the <a href="#ObjectHeaderMessages">Data Object Header Messages</a> - section below) - and the Size of Header Message Data field - contains the size of that Shared Message. - </td> - </tr> - <tr> - <td align="center"><code>2</code></td> - <td>If set, the message should not be shared. - </td> - </tr> - <tr> - <td align="center"><code>3</code></td> - <td>If set, the HDF5 decoder should fail to open this object - if it does not understand the message’s type and the file - is open with permissions allowing write access to the file. - (Normally, unknown messages can just be ignored by HDF5 - decoders) - </td> - </tr> - <tr> - <td align="center"><code>4</code></td> - <td>If set, the HDF5 decoder should set bit 5 of this - message’s flags (in other words, this bit field) - if it does not understand the message’s type - and the object is modified in any way. (Normally, - unknown messages can just be ignored by HDF5 - decoders) - </td> - </tr> - <tr> - <td align="center"><code>5</code></td> - <td>If set, this object was modified by software that did not - understand this message. - (Normally, unknown messages should just be ignored by HDF5 - decoders) (Can be used to invalidate an index or a similar - feature) - </td> - </tr> - <tr> - <td align="center"><code>6</code></td> - <td>If set, this message is shareable. - </td> - </tr> - <tr> - <td align="center"><code>7</code></td> - <td>If set, the HDF5 decoder should always fail to open this - object if it does not understand the message’s type (whether - it is open for read-only or read-write access). (Normally, - unknown messages can just be ignored by HDF5 decoders) - </td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>Header Message #n Data</p></td> - <td> - <p>The format and length of this field is determined by the - header message type and size respectively. Some header - message types do not require any data and this information - can be eliminated by setting the length of the message to - zero. The data is padded with enough zeroes to make the - size a multiple of eight. - </p> - </td> - </tr> - </table> - </div> - -<br /> -<h4><a name="V2ObjectHeaderPrefix"> -IV.A.1.b. Version 2 Data Object Header Prefix</a></h4> - - <p>Note that the “total number of messages” field has been dropped from - the data object header prefix in this version. The number of messages - in the data object header is just determined by the messages encountered - in all the object header blocks.</p> - - <p>Note also that the fields and messages in this version of data object - headers have <em>no</em> alignment or padding bytes inserted - they are - stored packed together.</p> - - <div align="center"> - <table class="format"> - <caption> - Version 2 Object Header - </caption> - - <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> - - <tr> - <td colspan="4">Signature</td> - </tr> - <tr> - <td>Version</td> - <td>Flags</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4">Access time <em>(optional)</em></td> - </tr> - - <tr> - <td colspan="4">Modification Time <em>(optional)</em></td> - </tr> - - <tr> - <td colspan="4">Change Time <em>(optional)</em></td> - </tr> - - <tr> - <td colspan="4">Birth Time <em>(optional)</em></td> - </tr> - - <tr> - <td colspan="2">Maximum # of compact attributes <em>(optional)</em></td> - <td colspan="2">Minimum # of dense attributes <em>(optional)</em></td> - </tr> - - <tr> - <td>Size of Chunk #0 <em>(variable size)</em></td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td>Header Message Type #1</td> - <td colspan="2">Size of Header Message Data #1</td> - <td>Header Message #1 Flags</td> - </tr> - - <tr> - <td colspan="2">Header Message #1 Creation Order <em>(optional)</em></td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Header Message Data #1<br /><br /></td> - </tr> - - <tr> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - - <tr> - <td>Header Message Type #n</td> - <td colspan="2">Size of Header Message Data #n</td> - <td>Header Message #n Flags</td> - </tr> - - <tr> - <td colspan="2">Header Message #n Creation Order <em>(optional)</em></td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Header Message Data #n<br /><br /></td> - </tr> - - <tr> - <td colspan="4">Gap <em>(optional, variable size)</em></td> - </tr> - - <tr> - <td colspan="4">Checksum</td> - </tr> - </table> - </div> +<br /> +<h3> + <a name="ObjectHeader"> IV.A. Disk Format: Level 2A - Data Object + Headers</a> +</h3> + +<p>The header information of an object is designed to encompass all + of the information about an object, except for the data itself. This + information includes the dataspace, the datatype, information about how + the data is stored on disk (in external files, compressed, broken up in + blocks, and so on), as well as other information used by the library to + speed up access to the data objects or maintain a file’s + integrity. Information stored by user applications as attributes is + also stored in the object’s header. The header of each object is + not necessarily located immediately prior to the object’s data in + the file and in fact may be located in any position in the file. The + order of the messages in an object header is not significant.</p> + +<p>Object headers are composed of a prefix and a set of messages. + The prefix contains the information needed to interpret the messages + and a small amount of metadata about the object, and the messages + contain the majority of the metadata about the object.</p> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>OHDR</code>” - is used to indicate the - beginning of an object header. This gives file consistency - checking utilities a better chance of reconstructing a - damaged file. - </p> - </td> - </tr> - - <tr> - <td><p>Version</p></td> - <td> - <p>This field has a value of 2 indicating version 2 of the object header. - </p> - </td> - </tr> - - <tr> - <td><p>Flags</p></td> - <td> - <p>This field is a bit field indicating additional information - about the object header. - <table class="list"> - <tr> - <th width="20%" align="center">Bit(s)</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0-1</code></td> - <td>This two bit field determines the size of the - <em>Size of Chunk #0</em> field. The values are: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> +<br /> +<h3> + <a name="ObjectHeaderPrefix"> IV.A.1. Disk Format: Level 2A1 - Data + Object Header Prefix</a> +</h3> - <tr> - <td align="center"><code>0</code></td> - <td>The <em>Size of Chunk #0</em> field is 1 byte. - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td>The <em>Size of Chunk #0</em> field is 2 bytes. - </td> - </tr> - <tr> - <td align="center"><code>2</code></td> - <td>The <em>Size of Chunk #0</em> field is 4 bytes. - </td> - </tr> - <tr> - <td align="center"><code>3</code></td> - <td>The <em>Size of Chunk #0</em> field is 8 bytes. - </td> - </tr> - </table></p> - </td> - </tr> - <tr> - <td align="center"><code>2</code></td> - <td>If set, attribute creation order is tracked.</td> - </tr> - <tr> - <td align="center"><code>3</code></td> - <td>If set, attribute creation order is indexed.</td> - </tr> - <tr> - <td align="center"><code>4</code></td> - <td>If set, non-default attribute storage phase change - values are stored.</td> - </tr> - <tr> - <td align="center"><code>5</code></td> - <td>If set, access, modification, change and birth times - are stored.</td> - </tr> - <tr> - <td align="center"><code>6-7</code></td> - <td>Reserved</td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>Access Time</p></td> - <td> - <p>This 32-bit value represents the number of seconds after the - UNIX epoch when the object’s raw data was last accessed - (in other words, read or written). - </p> - <p>This field is present if bit 5 of <em>flags</em> is set. - </p> - </td> - </tr> - - <tr> - <td><p>Modification Time</p></td> - <td> - <p>This 32-bit value represents the number of seconds after - the UNIX epoch when the object’s raw data was last - modified (in other words, written). - </p> - <p>This field is present if bit 5 of <em>flags</em> is set. - </p> - </td> - </tr> - - <tr> - <td><p>Change Time</p></td> - <td> - <p>This 32-bit value represents the number of seconds after the - UNIX epoch when the object’s metadata was last changed. - </p> - <p>This field is present if bit 5 of <em>flags</em> is set. - </p> - </td> - </tr> - - <tr> - <td><p>Birth Time</p></td> - <td> - <p>This 32-bit value represents the number of seconds after the - UNIX epoch when the object was created. - </p> - <p>This field is present if bit 5 of <em>flags</em> is set. - </p> - </td> - </tr> - - <tr> - <td><p>Maximum # of compact attributes</p></td> - <td> - <p>This is the maximum number of attributes to store in the compact - format before switching to the indexed format. - </p> - <p>This field is present if bit 4 of <em>flags</em> is set. - </p> - </td> - </tr> - - <tr> - <td><p>Minimum # of dense attributes</p></td> - <td> - <p>This is the minimum number of attributes to store in the indexed - format before switching to the compact format. - </p> - <p>This field is present if bit 4 of <em>flags</em> is set. - </p> - </td> - </tr> - - <tr> - <td><p>Size of Chunk #0</p></td> - <td> - <p> - This unsigned value specifies the number of bytes of header - message data following this field that contain object header - information. - </p> - <p> - This value does not include the size of object header - continuation blocks for this object elsewhere in the file. - </p> - <p> - The length of this field varies depending on bits 0 and 1 of - the <em>flags</em> field. - </p> - </td> - </tr> - - <tr> - <td><p>Header Message #n Type</p></td> - <td> - <p>Same format as version 1 of the object header, described above. - </p> - </td> - </tr> - - <tr> - <td><p>Size of Header Message #n Data</p></td> - <td> - <p>This value specifies the number of bytes of header - message data following the header message type and length - information for the current message. The size of messages - in this version does <em>not</em> include any padding bytes. - </p> - </td> - </tr> - - <tr> - <td><p>Header Message #n Flags</p></td> - <td> - <p>Same format as version 1 of the object header, described above. - </p> - </td> - </tr> - - <tr> - <td><p>Header Message #n Creation Order</p></td> - <td> - <p>This field stores the order that a message of a given type - was created in. - </p> - <p>This field is present if bit 2 of <em>flags</em> is set. - </p> - </td> - </tr> - - <tr> - <td><p>Header Message #n Data</p></td> - <td> - <p>Same format as version 1 of the object header, described above. - </p> - </td> - </tr> - - <tr> - <td><p>Gap</p></td> - <td> - <p>A gap in an object header chunk is inferred by the end of the - messages for the chunk before the beginning of the chunk’s - checksum. Gaps are always smaller than the size of an - object header message prefix (message type + message size + - message flags). - </p> - <p>Gaps are formed when a message (typically an attribute message) - in an earlier chunk is deleted and a message from a later - chunk that does not quite fit into the free space is moved - into the earlier chunk. - </p> - </td> - </tr> - - <tr> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for the object header chunk. - </p> - </td> +<br /> +<h4> + <a name="V1ObjectHeaderPrefix"> IV.A.1.a. Version 1 Data Object + Header Prefix</a> +</h4> + +<p>Header messages are aligned on 8-byte boundaries for version 1 + object headers.</p> + +<div align="center"> + <table class="format"> + <caption>Version 1 Object Header</caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> </tr> - </table> - </div> - - <p>The header message types and the message data associated with - them compose the critical “metadata” about each object. Some - header messages are required for each object while others are - optional. Some optional header messages may also be repeated - several times in the header itself, the requirements and number - of times allowed in the header will be noted in each header - message description below. - </p> - - -<br /> -<h3><a name="ObjectHeaderMessages"> -IV.A.2. Disk Format: Level 2A2 - Data Object Header Messages</a></h3> - - <p>Data object header messages are small pieces of metadata that are - stored in the data object header for each object in an HDF5 file. - Data object header messages provide the metadata required to describe - an object and its contents, as well as optional pieces of metadata - that annotate the meaning or purpose of the object. - </p> - - <p>Data object header messages are either stored directly in the data - object header for the object or are shared between multiple objects - in the file. When a message is shared, a flag in the <em>Message Flags</em> - indicates that the actual <em>Message Data</em> - portion of that message is stored in another location (such as another - data object header, or a heap in the file) and the <em>Message Data</em> - field contains the information needed to locate the actual information - for the message. - </p> - - <p> - The format of shared message data is described here:</p> - - <div align="center"> - <table class="format"> - <caption> - Shared Message (Version 1) - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Type</td> - <td colspan="2">Reserved (zero)</td> - </tr> - - <tr> - <td colspan="4">Reserved (zero)</td> - </tr> - - <tr> - <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> - </tr> - </table> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <td>Version</td> + <td>Reserved (zero)</td> + <td colspan="2">Total Number of Header Messages</td> + </tr> - </div> + <tr> + <td colspan="4">Object Reference Count</td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number is used when there are changes in the format - of a shared object message and is described here: - <table class="list"> - <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Never used.</td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>Used by the library before version 1.6.1. - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Type</p></td> - <td><p>The type of shared message location: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Message stored in another object’s header (a <em>committed</em> - message). - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Address</p></td> - <td><p>The address of the object header - containing the message to be shared.</p> - </td> - </tr> - </table> - </div> + <tr> + <td colspan="4">Object Header Size</td> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Shared Message (Version 2) - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Type</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> - </tr> - </table> + <tr> + <td colspan="2">Header Message Type #1</td> + <td colspan="2">Size of Header Message Data #1</td> + </tr> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> - </div> + <td>Header Message #1 Flags</td> + <td colspan="3">Reserved (zero)</td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number is used when there are changes in the format - of a shared object message and is described here: - <table class="list"> - <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>2</code></td> - <td>Used by the library of version 1.6.1 and after. - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Type</p></td> - <td><p>The type of shared message location: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Message stored in another object’s header (a <em>committed</em> - message). - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Address</p></td> - <td><p>The address of the object header - containing the message to be shared.</p></td> - </tr> - </table> - </div> + <tr> + <td colspan="4"><br />Header Message Data #1<br /> + <br /></td> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Shared Message (Version 3) - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Type</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4">Location <em>(variable size)</em></td> - </tr> - </table> - </div> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number indicates changes in the format of shared - object message and is described here: - <table class="list"> - <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>3</code></td> - <td>Used by the library of version 1.8 and after. In this - version, the <em>Type</em> field can indicate that - the message is stored in the fractal heap. - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Type</p></td> - <td><p>The type of shared message location: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Message is not shared and is not shareable. - </td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>Message stored in file’s <em>shared object header message</em> - heap (a <em>shared</em> message). - </td> - </tr> - - <tr> - <td align="center"><code>2</code></td> - <td>Message stored in another object’s header (a <em>committed</em> - message). - </td> - </tr> - - <tr> - <td align="center"><code>3</code></td> - <td>Message stored is not shared, but is shareable. - </td> - </tr> - - </table></p> - </td> - </tr> - - <tr> - <td><p>Location</p></td> - <td><p>This field contains either a <em>Size of Offsets</em>-bytes - address of the object header - containing the message to be shared, or an 8-byte fractal heap ID - for the message in the file’s <em>shared object header message</em> - heap. - </p> - </td> - </tr> - </table> - </div> + <tr> + <td colspan="2">Header Message Type #n</td> + <td colspan="2">Size of Header Message Data #n</td> + </tr> + <tr> + <td>Header Message #n Flags</td> + <td colspan="3">Reserved (zero)</td> + </tr> - <p>The following is a list of currently defined header messages: - </p> + <tr> + <td colspan="4"><br />Header Message Data #n<br /> + <br /></td> + </tr> + </table> +</div> <br /> -<h4><a name="NILMessage">IV.A.2.a. The NIL Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Version</p></td> + <td> + <p>This value is used to determine the format of the information + in the object header. When the format of the object header is + changed, the version number is incremented and can be used to + determine how the information in the object header is formatted. + This is version one (1) (there was no version zero (0)) of the + object header.</p> + </td> + </tr> + + <tr> + <td><p>Total Number of Header Messages</p></td> + <td> + <p>This value determines the total number of messages listed in + object headers for this object. This value includes the messages in + continuation messages for this object.</p> + </td> + </tr> + + <tr> + <td><p>Object Reference Count</p></td> + <td> + <p>This value specifies the number of “hard links” + to this object within the current file. References to the object + from external files, “soft links” in this file and + object references in this file are not tracked.</p> + </td> + </tr> + + <tr> + <td><p>Object Header Size</p></td> + <td> + <p>This value specifies the number of bytes of header message + data following this length field that contain object header + messages for this object header. This value does not include the + size of object header continuation blocks for this object elsewhere + in the file.</p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Type</p></td> + <td> + <p>This value specifies the type of information included in the + following header message data. The message types for header + messages are defined in sections below.</p> + </td> + </tr> + + <tr> + <td><p>Size of Header Message #n Data</p></td> + <td> + <p>This value specifies the number of bytes of header message + data following the header message type and length information for + the current message. The size includes padding bytes to make the + message a multiple of eight bytes.</p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Flags</p></td> + <td> + <p>This is a bit field with the following definition:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, the message data is constant. This is used for + messages like the datatype message of a dataset.</td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, the message is <em>shared</em> and stored in + another location than the object header. The Header Message Data + field contains a Shared Message (described in the <a + href="#ObjectHeaderMessages">Data Object Header Messages</a> + section below) and the Size of Header Message Data field contains + the size of that Shared Message. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>If set, the message should not be shared.</td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>If set, the HDF5 decoder should fail to open this object + if it does not understand the message’s type and the file + is open with permissions allowing write access to the file. + (Normally, unknown messages can just be ignored by HDF5 decoders) + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>If set, the HDF5 decoder should set bit 5 of this + message’s flags (in other words, this bit field) if it does + not understand the message’s type and the object is + modified in any way. (Normally, unknown messages can just be + ignored by HDF5 decoders)</td> + </tr> + <tr> + <td align="center"><code>5</code></td> + <td>If set, this object was modified by software that did not + understand this message. (Normally, unknown messages should just + be ignored by HDF5 decoders) (Can be used to invalidate an index + or a similar feature)</td> + </tr> + <tr> + <td align="center"><code>6</code></td> + <td>If set, this message is shareable.</td> + </tr> + <tr> + <td align="center"><code>7</code></td> + <td>If set, the HDF5 decoder should always fail to open this + object if it does not understand the message’s type + (whether it is open for read-only or read-write access). + (Normally, unknown messages can just be ignored by HDF5 decoders) + </td> + </tr> + </table> + <p></p> + + </td> + </tr> + + <tr> + <td><p>Header Message #n Data</p></td> + <td> + <p>The format and length of this field is determined by the + header message type and size respectively. Some header message + types do not require any data and this information can be + eliminated by setting the length of the message to zero. The data + is padded with enough zeroes to make the size a multiple of eight. + </p> + </td> + </tr> + </table> +</div> + +<br /> +<h4> + <a name="V2ObjectHeaderPrefix"> IV.A.1.b. Version 2 Data Object + Header Prefix</a> +</h4> + +<p>Note that the “total number of messages” field has + been dropped from the data object header prefix in this version. The + number of messages in the data object header is just determined by the + messages encountered in all the object header blocks.</p> + +<p> + Note also that the fields and messages in this version of data object + headers have <em>no</em> alignment or padding bytes inserted - they are + stored packed together. +</p> + +<div align="center"> + <table class="format"> + <caption>Version 2 Object Header</caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Access time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">Modification Time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">Change Time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4">Birth Time <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="2">Maximum # of compact attributes <em>(optional)</em></td> + <td colspan="2">Minimum # of dense attributes <em>(optional)</em></td> + </tr> + + <tr> + <td>Size of Chunk #0 <em>(variable size)</em></td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td>Header Message Type #1</td> + <td colspan="2">Size of Header Message Data #1</td> + <td>Header Message #1 Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #1 Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #1<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + + <tr> + <td>Header Message Type #n</td> + <td colspan="2">Size of Header Message Data #n</td> + <td>Header Message #n Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #n Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #n<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4">Gap <em>(optional, variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>OHDR</code> + ” is used to indicate the beginning of an object header. This + gives file consistency checking utilities a better chance of + reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This field has a value of 2 indicating version 2 of the + object header.</p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>This field is a bit field indicating additional information + about the object header.</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit(s)</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0-1</code></td> + <td>This two bit field determines the size of the <em>Size + of Chunk #0</em> field. The values are: + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>The <em>Size of Chunk #0</em> field is 1 byte. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The <em>Size of Chunk #0</em> field is 2 bytes. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>The <em>Size of Chunk #0</em> field is 4 bytes. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>The <em>Size of Chunk #0</em> field is 8 bytes. + </td> + </tr> + </table> + <p></p> + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>If set, attribute creation order is tracked.</td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>If set, attribute creation order is indexed.</td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>If set, non-default attribute storage phase change values + are stored.</td> + </tr> + <tr> + <td align="center"><code>5</code></td> + <td>If set, access, modification, change and birth times are + stored.</td> + </tr> + <tr> + <td align="center"><code>6-7</code></td> + <td>Reserved</td> + </tr> + </table> + <p></p> + + </td> + </tr> + + <tr> + <td><p>Access Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after the + UNIX epoch when the object’s raw data was last accessed (in + other words, read or written).</p> + <p> + This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Modification Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after the + UNIX epoch when the object’s raw data was last modified (in + other words, written).</p> + <p> + This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Change Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after the + UNIX epoch when the object’s metadata was last changed.</p> + <p> + This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Birth Time</p></td> + <td> + <p>This 32-bit value represents the number of seconds after the + UNIX epoch when the object was created.</p> + <p> + This field is present if bit 5 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Maximum # of compact attributes</p></td> + <td> + <p>This is the maximum number of attributes to store in the + compact format before switching to the indexed format.</p> + <p> + This field is present if bit 4 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Minimum # of dense attributes</p></td> + <td> + <p>This is the minimum number of attributes to store in the + indexed format before switching to the compact format.</p> + <p> + This field is present if bit 4 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Size of Chunk #0</p></td> + <td> + <p>This unsigned value specifies the number of bytes of header + message data following this field that contain object header + information.</p> + <p>This value does not include the size of object header + continuation blocks for this object elsewhere in the file.</p> + <p> + The length of this field varies depending on bits 0 and 1 of the <em>flags</em> + field. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Type</p></td> + <td> + <p>Same format as version 1 of the object header, described + above.</p> + </td> + </tr> + + <tr> + <td><p>Size of Header Message #n Data</p></td> + <td> + <p> + This value specifies the number of bytes of header message data + following the header message type and length information for the + current message. The size of messages in this version does <em>not</em> + include any padding bytes. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Flags</p></td> + <td> + <p>Same format as version 1 of the object header, described + above.</p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Creation Order</p></td> + <td> + <p>This field stores the order that a message of a given type + was created in.</p> + <p> + This field is present if bit 2 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Data</p></td> + <td> + <p>Same format as version 1 of the object header, described + above.</p> + </td> + </tr> + + <tr> + <td><p>Gap</p></td> + <td> + <p>A gap in an object header chunk is inferred by the end of the + messages for the chunk before the beginning of the chunk’s + checksum. Gaps are always smaller than the size of an object header + message prefix (message type + message size + message flags).</p> + <p>Gaps are formed when a message (typically an attribute + message) in an earlier chunk is deleted and a message from a later + chunk that does not quite fit into the free space is moved into the + earlier chunk.</p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the object header chunk.</p> + </td> + </tr> + </table> +</div> + +<p>The header message types and the message data associated with + them compose the critical “metadata” about each object. + Some header messages are required for each object while others are + optional. Some optional header messages may also be repeated several + times in the header itself, the requirements and number of times + allowed in the header will be noted in each header message description + below.</p> + + +<br /> +<h3> + <a name="ObjectHeaderMessages"> IV.A.2. Disk Format: Level 2A2 - + Data Object Header Messages</a> +</h3> + +<p>Data object header messages are small pieces of metadata that are + stored in the data object header for each object in an HDF5 file. Data + object header messages provide the metadata required to describe an + object and its contents, as well as optional pieces of metadata that + annotate the meaning or purpose of the object.</p> + +<p> + Data object header messages are either stored directly in the data + object header for the object or are shared between multiple objects in + the file. When a message is shared, a flag in the <em>Message + Flags</em> indicates that the actual <em>Message Data</em> portion of that + message is stored in another location (such as another data object + header, or a heap in the file) and the <em>Message Data</em> field + contains the information needed to locate the actual information for + the message. +</p> + +<p>The format of shared message data is described here:</p> + +<div align="center"> + <table class="format"> + <caption>Shared Message (Version 1)</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /> + <br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number is used when there are changes in + the format of a shared object message and is described here:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Used by the library before version 1.6.1.</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Type</p></td> + <td><p>The type of shared message location:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Message stored in another object’s header (a <em>committed</em> + message). + </td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>The address of the object header containing the + message to be shared.</p></td> + </tr> + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Shared Message (Version 2)</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /> + <br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number is used when there are changes in + the format of a shared object message and is described here:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Used by the library of version 1.6.1 and after.</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Type</p></td> + <td><p>The type of shared message location:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Message stored in another object’s header (a <em>committed</em> + message). + </td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>The address of the object header containing the + message to be shared.</p></td> + </tr> + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Shared Message (Version 3)</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Type</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Location <em>(variable size)</em></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number indicates changes in the format of + shared object message and is described here:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Used by the library of version 1.8 and after. In this + version, the <em>Type</em> field can indicate that the message is + stored in the fractal heap. + </td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Type</p></td> + <td><p>The type of shared message location:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Message is not shared and is not shareable.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Message stored in file’s <em>shared object + header message</em> heap (a <em>shared</em> message). + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Message stored in another object’s header (a <em>committed</em> + message). + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Message stored is not shared, but is shareable.</td> + </tr> + + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Location</p></td> + <td><p> + This field contains either a <em>Size of Offsets</em>-bytes address + of the object header containing the message to be shared, or an + 8-byte fractal heap ID for the message in the file’s <em>shared + object header message</em> heap. + </p></td> + </tr> + </table> +</div> + + +<p>The following is a list of currently defined header messages:</p> + +<br /> +<h4> + <a name="NILMessage">IV.A.2.a. The NIL Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> NIL</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0000</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may be repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>The NIL message is used to indicate a message which is to be - ignored when reading the header messages for a data object. - [Possibly one which has been deleted for some reason.] - </td></tr> - <tr><td colspan="2"><b>Format of Data:</b> Unspecified</td></tr> - </table></center> - <!-- end msgdesc table --> + <tr> + <td colspan="2"><b>Header Message Name:</b> NIL</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0000</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>The NIL message is used to indicate a message which is to be + ignored when reading the header messages for a data object. + [Possibly one which has been deleted for some reason.]</td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> Unspecified</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> <br /> -<h4><a name="DataspaceMessage">IV.A.2.b. The Dataspace Message</a></h4> +<h4> + <a name="DataspaceMessage">IV.A.2.b. The Dataspace Message</a> +</h4> - <!-- start msgdesc table --> - <center> +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Dataspace</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0001</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies according to the number of - dimensions, as described in the following table.</td></tr> - <tr><td colspan="2"><b>Status:</b> Required for dataset objects; - may not be repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>The dataspace message describes the number of dimensions (in - other words, “rank”) and size of each dimension that - the data object has. This message is only used for datasets which - have a simple, rectilinear, array-like layout; datasets requiring - a more complex layout are not yet supported. - </td> - </tr> + <tr> + <td colspan="2"><b>Header Message Name:</b> Dataspace</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0001</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies according to the number of + dimensions, as described in the following table.</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Required for dataset objects; may + not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>The dataspace message describes the number of dimensions (in + other words, “rank”) and size of each dimension that the + data object has. This message is only used for datasets which have a + simple, rectilinear, array-like layout; datasets requiring a more + complex layout are not yet supported.</td> + </tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Dataspace Message - Version 1 - </caption> - - <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Dimensionality</td> - <td>Flags</td> - <td>Reserved</td> - </tr> - - <tr> - <td colspan="4">Reserved</td> - </tr> - - <tr> - <td colspan="4"><br />Dimension #1 Size<sup>L</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - <tr> - <td colspan="4"><br />Dimension #n Size<sup>L</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4"><br />Dimension #1 Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> - </tr> - <tr> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - <tr> - <td colspan="4"><br />Dimension #n Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> - </tr> - <tr> - <td colspan="4"><br />Permutation Index #1<sup>L</sup> <em>(optional)</em><br /><br /></td> - </tr> - <tr> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - <tr> - <td colspan="4"><br />Permutation Index #n<sup>L</sup> <em>(optional)</em><br /><br /></td> - </tr> - </table> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption>Dataspace Message - Version 1</caption> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> - </div> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td> - <p>This value is used to determine the format of the - Dataspace Message. When the format of the - information in the message is changed, the version number - is incremented and can be used to determine how the - information in the object header is formatted. This - document describes version one (1) (there was no version - zero (0)). - </p> - </td> - </tr> - - <tr> - <td><p>Dimensionality</p></td> - <td> - <p>This value is the number of dimensions that the data - object has. - </p> - </td> - </tr> - - <tr> - <td><p>Flags</p></td> - <td> - <p>This field is used to store flags to indicate the - presence of parts of this message. Bit 0 (the least - significant bit) is used to indicate that maximum - dimensions are present. Bit 1 is used to indicate that - permutation indices are present. - </p> - </td> - </tr> - - <tr> - <td><p>Dimension #n Size</p></td> - <td> - <p>This value is the current size of the dimension of the - data as stored in the file. The first dimension stored in - the list of dimensions is the slowest changing dimension - and the last dimension stored is the fastest changing - dimension. - </p> - </td> - </tr> - - <tr> - <td><p>Dimension #n Maximum Size</p></td> - <td> - <p>This value is the maximum size of the dimension of the - data as stored in the file. This value may be the special - “<a href="#UnlimitedDim">unlimited</a>” size which indicates - that the data may expand along this dimension indefinitely. - If these values are not stored, the maximum size of each - dimension is assumed to be the dimension’s current size. - </p> - </td> - </tr> - - <tr> - <td><p>Permutation Index #n</p></td> - <td> - <p>This value is the index permutation used to map - each dimension from the canonical representation to an - alternate axis for each dimension. If these values are - not stored, the first dimension stored in the list of - dimensions is the slowest changing dimension and the last - dimension stored is the fastest changing dimension. - </p> - </td> - </tr> - </table> - </div> + <tr> + <td>Version</td> + <td>Dimensionality</td> + <td>Flags</td> + <td>Reserved</td> + </tr> + + <tr> + <td colspan="4">Reserved</td> + </tr> + + <tr> + <td colspan="4"><br />Dimension #1 Size<sup>L</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Size<sup>L</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #1 Maximum Size<sup>L</sup> <em>(optional)</em><br /> + <br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Maximum Size<sup>L</sup> <em>(optional)</em><br /> + <br /></td> + </tr> + <tr> + <td colspan="4"><br />Permutation Index #1<sup>L</sup> <em>(optional)</em><br /> + <br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Permutation Index #n<sup>L</sup> <em>(optional)</em><br /> + <br /></td> + </tr> + </table> + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘L’ in the + above table are of the size specified in “Size of + Lengths” field in the superblock.)</td> + </tr> + </table> +</div> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <br /> - <p>Version 2 of the dataspace message dropped the optional + <tr> + <td><p>Version</p></td> + <td> + <p>This value is used to determine the format of the Dataspace + Message. When the format of the information in the message is + changed, the version number is incremented and can be used to + determine how the information in the object header is formatted. + This document describes version one (1) (there was no version zero + (0)).</p> + </td> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the data object + has.</p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>This field is used to store flags to indicate the presence of + parts of this message. Bit 0 (the least significant bit) is used to + indicate that maximum dimensions are present. Bit 1 is used to + indicate that permutation indices are present.</p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the current size of the dimension of the data + as stored in the file. The first dimension stored in the list of + dimensions is the slowest changing dimension and the last dimension + stored is the fastest changing dimension.</p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Maximum Size</p></td> + <td> + <p> + This value is the maximum size of the dimension of the data as + stored in the file. This value may be the special “<a + href="#UnlimitedDim">unlimited</a>” size which indicates + that the data may expand along this dimension indefinitely. If + these values are not stored, the maximum size of each dimension is + assumed to be the dimension’s current size. + </p> + </td> + </tr> + + <tr> + <td><p>Permutation Index #n</p></td> + <td> + <p>This value is the index permutation used to map each + dimension from the canonical representation to an alternate axis + for each dimension. If these values are not stored, the first + dimension stored in the list of dimensions is the slowest changing + dimension and the last dimension stored is the fastest changing + dimension.</p> + </td> + </tr> + </table> +</div> + + + +<br /> +<p>Version 2 of the dataspace message dropped the optional permutation index value support, as it was never implemented in the HDF5 Library:</p> - <div align="center"> - <table class="format"> - <caption> - Dataspace Message - Version 2 - </caption> - - <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Dimensionality</td> - <td>Flags</td> - <td>Type</td> - </tr> - - <tr> - <td colspan="4"><br />Dimension #1 Size<sup>L</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - <tr> - <td colspan="4"><br />Dimension #n Size<sup>L</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4"><br />Dimension #1 Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> - </tr> - <tr> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - <tr> - <td colspan="4"><br />Dimension #n Maximum Size<sup>L</sup> <em>(optional)</em><br /><br /></td> - </tr> - </table> +<div align="center"> + <table class="format"> + <caption>Dataspace Message - Version 2</caption> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> - </div> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td> - <p>This value is used to determine the format of the - Dataspace Message. This field should be ‘2’ for version 2 - format messages. - </p> - </td> - </tr> - - <tr> - <td><p>Dimensionality</p></td> - <td> - <p>This value is the number of dimensions that the data object has. - </p> - </td> - </tr> - - <tr> - <td><p>Flags</p></td> - <td> - <p>This field is used to store flags to indicate the - presence of parts of this message. Bit 0 (the least - significant bit) is used to indicate that maximum - dimensions are present. - </p> - </td> - </tr> - - <tr> - <td><p>Type</p></td> - <td> - <p>This field indicates the type of the dataspace: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>A <em>scalar</em> dataspace; in other words, - a dataspace with a single, dimensionless element. - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td>A <em>simple</em> dataspace; in other words, - a dataspace with a rank > 0 and an appropriate # of - dimensions. - </td> - </tr> - <tr> - <td align="center"><code>2</code></td> - <td>A <em>null</em> dataspace; in other words, - a dataspace with no elements. - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Dimension #n Size</p></td> - <td> - <p>This value is the current size of the dimension of the - data as stored in the file. The first dimension stored in - the list of dimensions is the slowest changing dimension - and the last dimension stored is the fastest changing - dimension. - </p> - </td> - </tr> - - <tr> - <td><p>Dimension #n Maximum Size</p></td> - <td> - <p>This value is the maximum size of the dimension of the - data as stored in the file. This value may be the special - “<a href="#UnlimitedDim">unlimited</a>” size which indicates - that the data may expand along this dimension indefinitely. - If these values are not stored, the maximum size of each - dimension is assumed to be the dimension’s current size. - </p> - </td> - </tr> + <tr> + <td>Version</td> + <td>Dimensionality</td> + <td>Flags</td> + <td>Type</td> + </tr> - </table> - </div> + <tr> + <td colspan="4"><br />Dimension #1 Size<sup>L</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Size<sup>L</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #1 Maximum Size<sup>L</sup> <em>(optional)</em><br /> + <br /></td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4"><br />Dimension #n Maximum Size<sup>L</sup> <em>(optional)</em><br /> + <br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘L’ in the + above table are of the size specified in “Size of + Lengths” field in the superblock.)</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>This value is used to determine the format of the Dataspace + Message. This field should be ‘2’ for version 2 format + messages.</p> + </td> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the data object + has.</p> + </td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td> + <p>This field is used to store flags to indicate the presence of + parts of this message. Bit 0 (the least significant bit) is used to + indicate that maximum dimensions are present.</p> + </td> + </tr> + + <tr> + <td><p>Type</p></td> + <td> + <p>This field indicates the type of the dataspace:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>A <em>scalar</em> dataspace; in other words, a dataspace + with a single, dimensionless element. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>A <em>simple</em> dataspace; in other words, a dataspace + with a rank > 0 and an appropriate # of dimensions. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>A <em>null</em> dataspace; in other words, a dataspace + with no elements. + </td> + </tr> + </table> + <p></p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the current size of the dimension of the data + as stored in the file. The first dimension stored in the list of + dimensions is the slowest changing dimension and the last dimension + stored is the fastest changing dimension.</p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Maximum Size</p></td> + <td> + <p> + This value is the maximum size of the dimension of the data as + stored in the file. This value may be the special “<a + href="#UnlimitedDim">unlimited</a>” size which indicates + that the data may expand along this dimension indefinitely. If + these values are not stored, the maximum size of each dimension is + assumed to be the dimension’s current size. + </p> + </td> + </tr> + + </table> +</div> @@ -8287,22 +8431,22 @@ IV.A.2. Disk Format: Level 2A2 - Data Object Header Messages</a></h3> <center> <table border cellpadding="4" width="80%"> - <caption align="bottom"> - <b>HDF5 Dataspace Message Layout</b> - </caption> - - <tr align="center"> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> + <caption align="bottom"> + <b>HDF5 Dataspace Message Layout</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> </tr> - <tr align="center"> - <td colspan="4">Mesh Type</td> + <tr align="center"> + <td colspan="4">Mesh Type</td> </tr> - <tr align="center"> - <td colspan="4">Logical Dimensionality</td> + <tr align="center"> + <td colspan="4">Logical Dimensionality</td> </tr> </table> </center> @@ -8311,156 +8455,156 @@ IV.A.2. Disk Format: Level 2A2 - Data Object Header Messages</a></h3> <dl> <dt>The elements of the dimensionality message are described below: <dd> - <dl> - <dt>Mesh Type: (unsigned 32-bit integer) - <dd>This value indicates whether the grid is - polar/spherical/cartesion, - structured/unstructured and regular/irregular. <br /> - The mesh type value is broken up as follows: <br /> - - <br /> - <center> - <table border cellpadding="4" width="80%"> - <caption align="bottom"> - <b>HDF5 Mesh-type Layout</b> - </caption> - - <tr align="center"> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr align="center"> - <td colspan="1">Mesh Embedding</td> - <td colspan="1">Coordinate System</td> - <td colspan="1">Structure</td> - <td colspan="1">Regularity</td> - </tr> - </table> - </center> - The following are the definitions of mesh-type bytes: - <dl> - <dt>Mesh Embedding - <dd>This value indicates whether the dataset dataspace - is located within - another dataspace or not: - <dl> <dl> - <dt><STANDALONE> - <dd>The dataset mesh is self-contained and is not - embedded in another mesh. - <dt><EMBEDDED> - <dd>The dataset’s dataspace is located within - another dataspace, as - described in information below. - </dl> </dl> - <dt>Coordinate System - <dd>This value defines the type of coordinate system - used for the mesh: - <dl> <dl> - <dt><POLAR> - <dd>The last two dimensions are in polar - coordinates, higher dimensions are - cartesian. - <dt><SPHERICAL> - <dd>The last three dimensions are in spherical - coordinates, higher dimensions - are cartesian. - <dt><CARTESIAN> - <dd>All dimensions are in cartesian coordinates. - </dl> </dl> - <dt>Structure - <dd>This value defines the locations of the grid-points - on the axes: - <dl> <dl> - <dt><STRUCTURED> - <dd>All grid-points are on integral, sequential - locations, starting from 0. - <dt><UNSTRUCTURED> - <dd>Grid-points locations in each dimension are - explicitly defined and - may be of any numeric datatype. - </dl> </dl> - <dt>Regularity - <dd>This value defines the locations of the dataset - points on the grid: - <dl> <dl> - <dt><REGULAR> - <dd>All dataset elements are located at the - grid-points defined. - <dt><IRREGULAR> - <dd>Each dataset element has a particular - grid-location defined. - </dl> </dl> - </dl> - <p>The following grid combinations are currently allowed:</p> - <dl> <dl> - <dt><POLAR-STRUCTURED-REGULAR> - <dt><SPHERICAL-STRUCTURED-REGULAR> - <dt><CARTESIAN-STRUCTURED-REGULAR> - <dt><POLAR-UNSTRUCTURED-REGULAR> - <dt><SPHERICAL-UNSTRUCTURED-REGULAR> - <dt><CARTESIAN-UNSTRUCTURED-REGULAR> - <dt><CARTESIAN-UNSTRUCTURED-IRREGULAR> - </dl> </dl> - All of the above grid types can be embedded within another - dataspace. - <br /> <br /> - <dt>Logical Dimensionality: (unsigned 32-bit integer) - <dd>This value is the number of dimensions that the dataset occupies. - - <br /> - <center> - <table border cellpadding="4" width="80%"> - <caption align="bottom"> - <b>HDF5 Dataspace Embedded Dimensionality Information</b> - </caption> - - <tr align="center"> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr align="center"> - <td colspan="4">Embedded Dimensionality</td> - </tr> - <tr align="center"> - <td colspan="4">Embedded Dimension Size #1</td> - </tr> - <tr align="center"> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - <tr align="center"> - <td colspan="4">Embedded Dimension Size #n</td> - </tr> - <tr align="center"> - <td colspan="4">Embedded Origin Location #1</td> - </tr> - <tr align="center"> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - <tr align="center"> - <td colspan="4">Embedded Origin Location #n</td> - </tr> - </table> - </center> - - <dt>Embedded Dimensionality: (unsigned 32-bit integer) - <dd>This value is the number of dimensions of the space the - dataset is located within: in other words, a planar dataset + <dl> + <dt>Mesh Type: (unsigned 32-bit integer) + <dd>This value indicates whether the grid is + polar/spherical/cartesion, + structured/unstructured and regular/irregular. <br /> + The mesh type value is broken up as follows: <br /> + + <br /> + <center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Mesh-type Layout</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="1">Mesh Embedding</td> + <td colspan="1">Coordinate System</td> + <td colspan="1">Structure</td> + <td colspan="1">Regularity</td> + </tr> + </table> + </center> + The following are the definitions of mesh-type bytes: + <dl> + <dt>Mesh Embedding + <dd>This value indicates whether the dataset dataspace + is located within + another dataspace or not: + <dl> <dl> + <dt><STANDALONE> + <dd>The dataset mesh is self-contained and is not + embedded in another mesh. + <dt><EMBEDDED> + <dd>The dataset’s dataspace is located within + another dataspace, as + described in information below. + </dl> </dl> + <dt>Coordinate System + <dd>This value defines the type of coordinate system + used for the mesh: + <dl> <dl> + <dt><POLAR> + <dd>The last two dimensions are in polar + coordinates, higher dimensions are + cartesian. + <dt><SPHERICAL> + <dd>The last three dimensions are in spherical + coordinates, higher dimensions + are cartesian. + <dt><CARTESIAN> + <dd>All dimensions are in cartesian coordinates. + </dl> </dl> + <dt>Structure + <dd>This value defines the locations of the grid-points + on the axes: + <dl> <dl> + <dt><STRUCTURED> + <dd>All grid-points are on integral, sequential + locations, starting from 0. + <dt><UNSTRUCTURED> + <dd>Grid-points locations in each dimension are + explicitly defined and + may be of any numeric datatype. + </dl> </dl> + <dt>Regularity + <dd>This value defines the locations of the dataset + points on the grid: + <dl> <dl> + <dt><REGULAR> + <dd>All dataset elements are located at the + grid-points defined. + <dt><IRREGULAR> + <dd>Each dataset element has a particular + grid-location defined. + </dl> </dl> + </dl> + <p>The following grid combinations are currently allowed:</p> + <dl> <dl> + <dt><POLAR-STRUCTURED-REGULAR> + <dt><SPHERICAL-STRUCTURED-REGULAR> + <dt><CARTESIAN-STRUCTURED-REGULAR> + <dt><POLAR-UNSTRUCTURED-REGULAR> + <dt><SPHERICAL-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-REGULAR> + <dt><CARTESIAN-UNSTRUCTURED-IRREGULAR> + </dl> </dl> + All of the above grid types can be embedded within another + dataspace. + <br /> <br /> + <dt>Logical Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions that the dataset occupies. + + <br /> + <center> + <table border cellpadding="4" width="80%"> + <caption align="bottom"> + <b>HDF5 Dataspace Embedded Dimensionality Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="4">Embedded Dimensionality</td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Dimension Size #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Dimension Size #n</td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Origin Location #1</td> + </tr> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr align="center"> + <td colspan="4">Embedded Origin Location #n</td> + </tr> + </table> + </center> + + <dt>Embedded Dimensionality: (unsigned 32-bit integer) + <dd>This value is the number of dimensions of the space the + dataset is located within: in other words, a planar dataset located within a 3-D space, a 3-D dataset - which is a subset of another 3-D space, and so on. - <dt>Embedded Dimension Size: (unsigned 32-bit integer) - <dd>These values are the sizes of the dimensions of the - embedded dataspace - that the dataset is located within. - <dt>Embedded Origin Location: (unsigned 32-bit integer) - <dd>These values comprise the location of the dataset’s - origin within the embedded dataspace. - </dl> + which is a subset of another 3-D space, and so on. + <dt>Embedded Dimension Size: (unsigned 32-bit integer) + <dd>These values are the sizes of the dimensions of the + embedded dataspace + that the dataset is located within. + <dt>Embedded Origin Location: (unsigned 32-bit integer) + <dd>These values comprise the location of the dataset’s + origin within the embedded dataspace. + </dl> </dl> [Comment: need some way to handle different orientations of the dataset dataspace @@ -8469,31 +8613,31 @@ IV.A.2. Disk Format: Level 2A2 - Data Object Header Messages</a></h3> <br /> <center> <table border cellpadding="4" width="80%"> - <caption align="bottom"> - <b>HDF5 Dataspace Structured/Regular Grid Information</b> - </caption> - - <tr align="center"> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> + <caption align="bottom"> + <b>HDF5 Dataspace Structured/Regular Grid Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> </tr> - <tr align="center"> - <td colspan="4">Logical Dimension Size #1</td> + <tr align="center"> + <td colspan="4">Logical Dimension Size #1</td> </tr> - <tr align="center"> - <td colspan="4">Logical Dimension Maximum #1</td> + <tr align="center"> + <td colspan="4">Logical Dimension Maximum #1</td> </tr> - <tr align="center"> - <td colspan="4">.<br />.<br />.<br /></td> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> </tr> - <tr align="center"> - <td colspan="4">Logical Dimension Size #n</td> + <tr align="center"> + <td colspan="4">Logical Dimension Size #n</td> </tr> - <tr align="center"> - <td colspan="4">Logical Dimension Maximum #n</td> + <tr align="center"> + <td colspan="4">Logical Dimension Maximum #n</td> </tr> </table> </center> @@ -8502,58 +8646,58 @@ IV.A.2. Disk Format: Level 2A2 - Data Object Header Messages</a></h3> <dl> <dt>The elements of the dimensionality message are described below: <dd> - <dl> - <dt>Logical Dimension Size #n: (unsigned 32-bit integer) - <dd>This value is the current size of the dimension of the - data as stored in - the file. The first dimension stored in the list of - dimensions is the slowest - changing dimension and the last dimension stored is the - fastest changing - dimension. - <dt>Logical Dimension Maximum #n: (unsigned 32-bit integer) - <dd>This value is the maximum size of the dimension of the - data as stored in - the file. This value may be the special value - <UNLIMITED> which - indicates that the data may expand along this dimension - indefinitely. - </dl> + <dl> + <dt>Logical Dimension Size #n: (unsigned 32-bit integer) + <dd>This value is the current size of the dimension of the + data as stored in + the file. The first dimension stored in the list of + dimensions is the slowest + changing dimension and the last dimension stored is the + fastest changing + dimension. + <dt>Logical Dimension Maximum #n: (unsigned 32-bit integer) + <dd>This value is the maximum size of the dimension of the + data as stored in + the file. This value may be the special value + <UNLIMITED> which + indicates that the data may expand along this dimension + indefinitely. + </dl> </dl> <br /> <center> <table border cellpadding="4" width="80%"> - <caption align="bottom"> - <b>HDF5 Dataspace Structured/Irregular Grid Information</b> - </caption> - - <tr align="center"> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> + <caption align="bottom"> + <b>HDF5 Dataspace Structured/Irregular Grid Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> </tr> - <tr align="center"> - <td colspan="4"># of Grid Points in Dimension #1</td> + <tr align="center"> + <td colspan="4"># of Grid Points in Dimension #1</td> </tr> - <tr align="center"> - <td colspan="4">.<br />.<br />.<br /></td> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> </tr> - <tr align="center"> - <td colspan="4"># of Grid Points in Dimension #n</td> + <tr align="center"> + <td colspan="4"># of Grid Points in Dimension #n</td> </tr> - <tr align="center"> - <td colspan="4">Datatype of Grid Point Locations</td> + <tr align="center"> + <td colspan="4">Datatype of Grid Point Locations</td> </tr> - <tr align="center"> - <td colspan="4">Location of Grid Points in Dimension #1</td> + <tr align="center"> + <td colspan="4">Location of Grid Points in Dimension #1</td> </tr> - <tr align="center"> - <td colspan="4">.<br />.<br />.<br /></td> + <tr align="center"> + <td colspan="4">.<br />.<br />.<br /></td> </tr> - <tr align="center"> - <td colspan="4">Location of Grid Points in Dimension #n</td> + <tr align="center"> + <td colspan="4">Location of Grid Points in Dimension #n</td> </tr> </table> </center> @@ -8561,6342 +8705,6548 @@ IV.A.2. Disk Format: Level 2A2 - Data Object Header Messages</a></h3> <br /> <center> <table border cellpadding="4" width="80%"> - <caption align="bottom"> - <b>HDF5 Dataspace Unstructured Grid Information</b> - </caption> - - <tr align="center"> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> + <caption align="bottom"> + <b>HDF5 Dataspace Unstructured Grid Information</b> + </caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> </tr> - <tr align="center"> - <td colspan="4"># of Grid Points</td> + <tr align="center"> + <td colspan="4"># of Grid Points</td> </tr> - <tr align="center"> - <td colspan="4">Datatype of Grid Point Locations</td> + <tr align="center"> + <td colspan="4">Datatype of Grid Point Locations</td> </tr> - <tr align="center"> - <td colspan="4">Grid Point Locations<br />.<br />.<br /></td> + <tr align="center"> + <td colspan="4">Grid Point Locations<br />.<br />.<br /></td> </tr> </table> </center> --> <br /> -<h4><a name="LinkInfoMessage">IV.A.2.c. The Link Info Message</a></h4> +<h4> + <a name="LinkInfoMessage">IV.A.2.c. The Link Info Message</a> +</h4> - <!-- start msgdesc table --> - <center> +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Link Info</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x002 </td></tr> - <tr><td colspan="2"><b>Length:</b> Varies </td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated. </td></tr> - <tr><td><b>Description:</b></td> - <td>The link info message tracks variable information about the - current state of the links for a “new style” - group’s behavior. Variable information will be stored in - this message and constant information will be stored in the - <a href="#GroupInfoMessage">Group Info</a> message. - </td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Link Info - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Flags</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Maximum Creation Index <em>(8 bytes, optional)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Fractal Heap Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Address of v2 B-tree for Name Index<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Address of v2 B-tree for Creation Order Index<sup>O</sup> <em>(optional)</em><br /><br /></td> - </tr> + <tr> + <td colspan="2"><b>Header Message Name:</b> Link Info</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x002</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>The link info message tracks variable information about the + current state of the links for a “new style” + group’s behavior. Variable information will be stored in this + message and constant information will be stored in the <a + href="#GroupInfoMessage">Group Info</a> message. + </td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - </table> +<div align="center"> + <table class="format"> + <caption>Link Info</caption> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> - </div> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td> - <p>The version number for this message. This document describes - version 0.</p> - </td> - </tr> - - <tr> - <td><p>Flags</p></td> - <td><p>This field determines various optional aspects of the link - info message: - - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>If set, creation order for the links is tracked. - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td>If set, creation order for the links is indexed. - </td> - </tr> - <tr> - <td align="center"><code>2-7</code></td> - <td>Reserved</td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>Maximum Creation Index</p></td> - <td><p>This 64-bit value is the maximum creation order index value - stored for a link in this group.</p> - <p>This field is present if bit 0 of <em>flags</em> is set.</p> - </td> - </tr> - - <tr> - <td><p>Fractal Heap Address</p></td> - <td> - <p> - This is the address of the fractal heap to store dense links. - Each link stored in the fractal heap is stored as a - <a href="#LinkMessage">Link Message</a>. - </p> - <p> - If there are no links in the group, or the group’s links - are stored “compactly” (as object header messages), this - value will be the <a href="#UndefinedAddress">undefined - address</a>. - </p> - </td> - </tr> - - <tr> - <td><p>Address of v2 B-tree for Name Index</p></td> - <td><p>This is the address of the version 2 B-tree to index names of links.</p> - <p>If there are no links in the group, or the group’s links - are stored “compactly” (as object header messages), this - value will be the <a href="#UndefinedAddress">undefined - address</a>. - </p> - </td> - </tr> - - <tr> - <td><p>Address of v2 B-tree for Creation Order Index</p></td> - <td><p>This is the address of the version 2 B-tree to index creation order of links.</p> - <p>If there are no links in the group, or the group’s links - are stored “compactly” (as object header messages), this - value will be the <a href="#UndefinedAddress">undefined - address</a>. - </p> - <p>This field exists if bit 1 of <em>flags</em> is set.</p> - </td> - </tr> + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - </table> - </div> + <tr> + <td colspan="4"><br />Maximum Creation Index <em>(8 bytes, + optional)</em><br /> + <br /></td> + </tr> + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of v2 B-tree for Name Index<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Address of v2 B-tree for Creation Order + Index<sup>O</sup> <em>(optional)</em><br /> + <br /></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> +</div> <br /> -<h4><a name="DatatypeMessage">IV.A.2.d. The Datatype Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> - <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Datatype</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0003 - </td></tr> - <tr><td colspan="2"><b>Length:</b> Variable</td></tr> - <tr><td colspan="2"><b>Status:</b> Required for dataset or committed - datatype (formerly named datatype) objects; may not be repeated. - </td></tr> - <tr><td><b>Description:</b></td> - <td><p>The datatype message defines the datatype for each element - of a dataset or a common datatype for sharing between multiple - datasets. A datatype can describe an atomic type like a fixed- - or floating-point type or more complex types like a C struct - (compound datatype), array (array datatype) or C++ vector - (variable-length datatype).</p> - <p>Datatype messages that are part of a dataset object do not - describe how elements are related to one another; the dataspace - message is used for that purpose. Datatype messages that are part of - a committed datatype (formerly named datatype) message describe - a common datatype that can be shared by multiple datasets in the - file.</p> - </td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Datatype Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Class and Version</td> - <td>Class Bit Field, Bits 0-7</td> - <td>Class Bit Field, Bits 8-15</td> - <td>Class Bit Field, Bits 16-23</td> - </tr> - - <tr> - <td colspan="4">Size</td> - </tr> - - <tr> - <td colspan="4"><br /><br />Properties<br /><br /><br /></td> - </tr> - </table> - </div> + <tr> + <td><p>Version</p></td> + <td> + <p>The version number for this message. This document describes + version 0.</p> + </td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Class and Version</p></td> - <td> - <p>The version of the datatype message and the datatype’s class - information are packed together in this field. The version - number is packed in the top 4 bits of the field and the class - is contained in the bottom 4 bits. - </p> - <p>The version number information is used for changes in the - format of the datatype message and is described here: + <tr> + <td><p>Flags</p></td> + <td><p>This field determines various optional aspects of the + link info message:</p> <table class="list"> <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> </tr> <tr> - <td align="center"><code>0</code></td> - <td>Never used - </td> + <td align="center"><code>0</code></td> + <td>If set, creation order for the links is tracked.</td> </tr> <tr> - <td align="center"><code>1</code></td> - <td>Used by early versions of the library to encode - compound datatypes with explicit array fields. - See the compound datatype description below for - further details. - </td> + <td align="center"><code>1</code></td> + <td>If set, creation order for the links is indexed.</td> </tr> <tr> - <td align="center"><code>2</code></td> - <td>Used when an array datatype needs to be encoded. - </td> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Maximum Creation Index</p></td> + <td><p>This 64-bit value is the maximum creation order index + value stored for a link in this group.</p> + <p> + This field is present if bit 0 of <em>flags</em> is set. + </p></td> + </tr> + + <tr> + <td><p>Fractal Heap Address</p></td> + <td> + <p> + This is the address of the fractal heap to store dense links. Each + link stored in the fractal heap is stored as a <a + href="#LinkMessage">Link Message</a>. + </p> + <p> + If there are no links in the group, or the group’s links are + stored “compactly” (as object header messages), this + value will be the <a href="#UndefinedAddress">undefined address</a>. + </p> + </td> + </tr> + + <tr> + <td><p>Address of v2 B-tree for Name Index</p></td> + <td><p>This is the address of the version 2 B-tree to index + names of links.</p> + <p> + If there are no links in the group, or the group’s links are + stored “compactly” (as object header messages), this + value will be the <a href="#UndefinedAddress">undefined address</a>. + </p></td> + </tr> + + <tr> + <td><p>Address of v2 B-tree for Creation Order Index</p></td> + <td><p>This is the address of the version 2 B-tree to index + creation order of links.</p> + <p> + If there are no links in the group, or the group’s links are + stored “compactly” (as object header messages), this + value will be the <a href="#UndefinedAddress">undefined address</a>. + </p> + <p> + This field exists if bit 1 of <em>flags</em> is set. + </p></td> + </tr> + + </table> +</div> + + +<br /> +<h4> + <a name="DatatypeMessage">IV.A.2.d. The Datatype Message</a> +</h4> + +<!-- start msgdesc table --> +<center> + <table class="msgdesc"> + <tr> + <td colspan="2"><b>Header Message Name:</b> Datatype</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0003</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Variable</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Required for dataset or committed + datatype (formerly named datatype) objects; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td><p>The datatype message defines the datatype for each + element of a dataset or a common datatype for sharing between + multiple datasets. A datatype can describe an atomic type like a + fixed- or floating-point type or more complex types like a C struct + (compound datatype), array (array datatype) or C++ vector + (variable-length datatype).</p> + <p>Datatype messages that are part of a dataset object do not + describe how elements are related to one another; the dataspace + message is used for that purpose. Datatype messages that are part + of a committed datatype (formerly named datatype) message describe + a common datatype that can be shared by multiple datasets in the + file.</p></td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption>Datatype Message</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Class and Version</td> + <td>Class Bit Field, Bits 0-7</td> + <td>Class Bit Field, Bits 8-15</td> + <td>Class Bit Field, Bits 16-23</td> + </tr> + + <tr> + <td colspan="4">Size</td> + </tr> + + <tr> + <td colspan="4"><br /> + <br />Properties<br /> + <br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Class and Version</p></td> + <td> + <p>The version of the datatype message and the datatype’s + class information are packed together in this field. The version + number is packed in the top 4 bits of the field and the class is + contained in the bottom 4 bits.</p> + <p>The version number information is used for changes in the + format of the datatype message and is described here:</p> + <table class="list"> <tr> - <td align="center"><code>3</code></td> - <td>Used when a VAX byte-ordered type needs to be - encoded. Packs various other datatype classes more - efficiently also. - </td> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> </tr> - </table></p> - <p>The class of the datatype determines the format for the class - bit field and properties portion of the datatype message, which - are described below. The - following classes are currently defined: + <tr> + <td align="center"><code>0</code></td> + <td>Never used</td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Used by early versions of the library to encode compound + datatypes with explicit array fields. See the compound datatype + description below for further details.</td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Used when an array datatype needs to be encoded.</td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Used when a VAX byte-ordered type needs to be encoded. + Packs various other datatype classes more efficiently also.</td> + </tr> + </table> + <p></p> + <p>The class of the datatype determines the format for the class + bit field and properties portion of the datatype message, which are + described below. The following classes are currently defined:</p> <table class="list"> <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> </tr> <tr> - <td align="center"><code>0</code></td> - <td>Fixed-Point</td> + <td align="center"><code>0</code></td> + <td>Fixed-Point</td> </tr> <tr> - <td align="center"><code>1</code></td> - <td>Floating-Point</td> + <td align="center"><code>1</code></td> + <td>Floating-Point</td> </tr> <tr> - <td align="center"><code>2</code></td> - <td>Time</td> + <td align="center"><code>2</code></td> + <td>Time</td> </tr> <tr> - <td align="center"><code>3</code></td> - <td>String</td> + <td align="center"><code>3</code></td> + <td>String</td> </tr> <tr> - <td align="center"><code>4</code></td> - <td>Bit field</td> + <td align="center"><code>4</code></td> + <td>Bit field</td> </tr> <tr> - <td align="center"><code>5</code></td> - <td>Opaque</td> + <td align="center"><code>5</code></td> + <td>Opaque</td> </tr> <tr> - <td align="center"><code>6</code></td> - <td>Compound</td> + <td align="center"><code>6</code></td> + <td>Compound</td> </tr> <tr> - <td align="center"><code>7</code></td> - <td>Reference</td> + <td align="center"><code>7</code></td> + <td>Reference</td> </tr> <tr> - <td align="center"><code>8</code></td> - <td>Enumerated</td> + <td align="center"><code>8</code></td> + <td>Enumerated</td> </tr> <tr> - <td align="center"><code>9</code></td> - <td>Variable-Length</td> + <td align="center"><code>9</code></td> + <td>Variable-Length</td> </tr> <tr> - <td align="center"><code>10</code></td> - <td>Array</td> + <td align="center"><code>10</code></td> + <td>Array</td> </tr> - </table></p> + </table> + <p></p> - </td> - </tr> + </td> + </tr> - <tr> - <td><p>Class Bit Fields</p></td> - <td> - <p>The information in these bit fields is specific to each datatype - class and is described below. All bits not defined for a - datatype class are set to zero. - </p> - </td> - </tr> + <tr> + <td><p>Class Bit Fields</p></td> + <td> + <p>The information in these bit fields is specific to each + datatype class and is described below. All bits not defined for a + datatype class are set to zero.</p> + </td> + </tr> - <tr> - <td><p>Size</p></td> - <td> - <p>The size of a datatype element in bytes. - </p> - </td> - </tr> + <tr> + <td><p>Size</p></td> + <td> + <p>The size of a datatype element in bytes.</p> + </td> + </tr> - <tr> - <td><p>Properties</p></td> - <td> - <p>This variable-sized sequence of bytes encodes information - specific to each datatype class and is described for each class - below. If there is no property information specified for a - datatype class, the size of this field is zero bytes. - </p> - </td> - </tr> + <tr> + <td><p>Properties</p></td> + <td> + <p>This variable-sized sequence of bytes encodes information + specific to each datatype class and is described for each class + below. If there is no property information specified for a datatype + class, the size of this field is zero bytes.</p> + </td> + </tr> - </table> - </div> + </table> +</div> - <br /> - <p>Class specific information for Fixed-Point Numbers (Class 0):</p> - - <div align="center"> - <table class="desc"> - <caption> - Fixed-point Bit Field Description - </caption> - - <tr> - <th width="10%">Bits</th> - <th>Meaning</th> - </tr> - - <tr> - <td><p>0</p></td> - <td><p><b>Byte Order.</b> If zero, byte order is little-endian; - otherwise, byte order is big endian.</p></td> - </tr> - - <tr> - <td><p>1, 2</p></td> - <td><p><b>Padding type.</b> Bit 1 is the lo_pad bit and bit 2 - is the hi_pad bit. If a datum has unused bits at either - end, then the lo_pad or hi_pad bit is copied to those - locations.</p></td> - </tr> - - <tr> - <td><p>3</p></td> - <td><p><b>Signed.</b> If this bit is set then the fixed-point - number is in 2’s complement form.</p></td> - </tr> - - <tr> - <td><p>4-23</p></td> - <td><p>Reserved (zero).</p></td> - </tr> - </table> - </div> +<br /> +<p>Class specific information for Fixed-Point Numbers (Class 0):</p> - <br /> - <div align="center"> - <table class="format"> - <caption> - Fixed-Point Property Description - </caption> - - <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - </tr> - - <tr> - <td colspan="2">Bit Offset</td> - <td colspan="2">Bit Precision</td> - </tr> - </table> - </div> +<div align="center"> + <table class="desc"> + <caption>Fixed-point Bit Field Description</caption> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Bit Offset</p></td> - <td> - <p>The bit offset of the first significant bit of the fixed-point - value within the datatype. The bit offset specifies the number - of bits “to the right of” the value (which are set to the - lo_pad bit value). - </p> - </td> - </tr> - - <tr> - <td><p>Bit Precision</p></td> - <td> - <p>The number of bits of precision of the fixed-point value - within the datatype. This value, combined with the datatype - element’s size and the Bit Offset field specifies the number - of bits “to the left of” the value (which are set to the - hi_pad bit value). - </p> - </td> - </tr> + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> - </table> - </div> + <tr> + <td><p>0</p></td> + <td><p> + <b>Byte Order.</b> If zero, byte order is little-endian; otherwise, + byte order is big endian. + </p></td> + </tr> + <tr> + <td><p>1, 2</p></td> + <td><p> + <b>Padding type.</b> Bit 1 is the lo_pad bit and bit 2 is the + hi_pad bit. If a datum has unused bits at either end, then the + lo_pad or hi_pad bit is copied to those locations. + </p></td> + </tr> - <br /> - <p>Class specific information for Floating-Point Numbers (Class 1):</p> - - <div align="center"> - <table class="desc"> - <caption> - Floating-Point Bit Field Description - </caption> - - <tr> - <th width="10%">Bits</th> - <th>Meaning</th> - </tr> - - <tr> - <td><p>0, 6</p></td> - <td><p><b>Byte Order.</b> These two non-contiguous bits specify the - “endianness” of the bytes in the datatype element. - <table class="list"> - <tr> - <th width="10%" align="center">Bit 6</th> - <th width="10%" align="center">Bit 0</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td align="center"><code>0</code></td> - <td>Byte order is little-endian - </td> - </tr> - <tr> - <td align="center"><code>0</code></td> - <td align="center"><code>1</code></td> - <td>Byte order is big-endian - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td align="center"><code>0</code></td> - <td>Reserved - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td align="center"><code>1</code></td> - <td>Byte order is VAX-endian - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>1, 2, 3</p></td> - <td><p><b>Padding type.</b> Bit 1 is the low bits pad type, bit 2 - is the high bits pad type, and bit 3 is the internal bits - pad type. If a datum has unused bits at either end or between - the sign bit, exponent, or mantissa, then the value of bit - 1, 2, or 3 is copied to those locations.</p></td> - </tr> - - <tr> - <td><p>4-5</p></td> - <td><p><b>Mantissa Normalization.</b> This 2-bit bit field specifies - how the most significant bit of the mantissa is managed. + <tr> + <td><p>3</p></td> + <td><p> + <b>Signed.</b> If this bit is set then the fixed-point number is in + 2’s complement form. + </p></td> + </tr> + + <tr> + <td><p>4-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="format"> + <caption>Fixed-Point Property Description</caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="2">Bit Offset</td> + <td colspan="2">Bit Precision</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bit Offset</p></td> + <td> + <p>The bit offset of the first significant bit of the + fixed-point value within the datatype. The bit offset specifies the + number of bits “to the right of” the value (which are + set to the lo_pad bit value).</p> + </td> + </tr> + + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the fixed-point value + within the datatype. This value, combined with the datatype + element’s size and the Bit Offset field specifies the number + of bits “to the left of” the value (which are set to + the hi_pad bit value).</p> + </td> + </tr> + + </table> +</div> + + +<br /> +<p>Class specific information for Floating-Point Numbers (Class 1):</p> + +<div align="center"> + <table class="desc"> + <caption>Floating-Point Bit Field Description</caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0, 6</p></td> + <td><p> + <b>Byte Order.</b> These two non-contiguous bits specify the + “endianness” of the bytes in the datatype element. + </p> <table class="list"> <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> + <th width="10%" align="center">Bit 6</th> + <th width="10%" align="center">Bit 0</th> + <th width="80%" align="left">Description</th> </tr> <tr> - <td align="center"><code>0</code></td> - <td>No normalization - </td> + <td align="center"><code>0</code></td> + <td align="center"><code>0</code></td> + <td>Byte order is little-endian</td> </tr> <tr> - <td align="center"><code>1</code></td> - <td>The most significant bit of the mantissa is always set - (except for 0.0). - </td> + <td align="center"><code>0</code></td> + <td align="center"><code>1</code></td> + <td>Byte order is big-endian</td> </tr> <tr> - <td align="center"><code>2</code></td> - <td>The most significant bit of the mantissa is not stored, - but is implied to be set. - </td> + <td align="center"><code>1</code></td> + <td align="center"><code>0</code></td> + <td>Reserved</td> </tr> <tr> - <td align="center"><code>3</code></td> - <td>Reserved. - </td> + <td align="center"><code>1</code></td> + <td align="center"><code>1</code></td> + <td>Byte order is VAX-endian</td> </tr> - </table></p> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>1, 2, 3</p></td> + <td><p> + <b>Padding type.</b> Bit 1 is the low bits pad type, bit 2 is the + high bits pad type, and bit 3 is the internal bits pad type. If a + datum has unused bits at either end or between the sign bit, + exponent, or mantissa, then the value of bit 1, 2, or 3 is copied + to those locations. + </p></td> + </tr> + + <tr> + <td><p>4-5</p></td> + <td><p> + <b>Mantissa Normalization.</b> This 2-bit bit field specifies how + the most significant bit of the mantissa is managed. + </p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>No normalization</td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The most significant bit of the mantissa is always set + (except for 0.0).</td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>The most significant bit of the mantissa is not stored, + but is implied to be set.</td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Reserved.</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>7</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + + <tr> + <td><p>8-15</p></td> + <td><p> + <b>Sign Location.</b> This is the bit position of the sign bit. + Bits are numbered with the least significant bit zero. + </p></td> + </tr> + + <tr> + <td><p>16-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Floating-Point Property Description</caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="2">Bit Offset</td> + <td colspan="2">Bit Precision</td> + </tr> + + <tr> + <td>Exponent Location</td> + <td>Exponent Size</td> + <td>Mantissa Location</td> + <td>Mantissa Size</td> + </tr> + + <tr> + <td colspan="4">Exponent Bias</td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Bit Offset</p></td> + <td> + <p>The bit offset of the first significant bit of the + floating-point value within the datatype. The bit offset specifies + the number of bits “to the right of” the value.</p> </td> - </tr> + </tr> - <tr> - <td><p>7</p></td> - <td><p>Reserved (zero).</p></td> - </tr> + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the floating-point value + within the datatype.</p> + </td> + </tr> - <tr> - <td><p>8-15</p></td> - <td><p><b>Sign Location.</b> This is the bit position of the sign - bit. Bits are numbered with the least significant bit zero.</p></td> - </tr> + <tr> + <td><p>Exponent Location</p></td> + <td> + <p>The bit position of the exponent field. Bits are numbered + with the least significant bit number zero.</p> + </td> + </tr> - <tr> - <td><p>16-23</p></td> - <td><p>Reserved (zero).</p></td> - </tr> + <tr> + <td><p>Exponent Size</p></td> + <td> + <p>The size of the exponent field in bits.</p> + </td> + </tr> - </table> - </div> + <tr> + <td><p>Mantissa Location</p></td> + <td> + <p>The bit position of the mantissa field. Bits are numbered + with the least significant bit number zero.</p> + </td> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Floating-Point Property Description - </caption> - - <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - </tr> - - <tr> - <td colspan="2">Bit Offset</td> - <td colspan="2">Bit Precision</td> - </tr> - - <tr> - <td>Exponent Location</td> - <td>Exponent Size</td> - <td>Mantissa Location</td> - <td>Mantissa Size</td> - </tr> - - <tr> - <td colspan="4">Exponent Bias</td> - </tr> - </table> - </div> + <tr> + <td><p>Mantissa Size</p></td> + <td> + <p>The size of the mantissa field in bits.</p> + </td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Bit Offset</p></td> - <td> - <p>The bit offset of the first significant bit of the floating-point - value within the datatype. The bit offset specifies the number - of bits “to the right of” the value. - </p> - </td> - </tr> - - <tr> - <td><p>Bit Precision</p></td> - <td> - <p>The number of bits of precision of the floating-point value - within the datatype. - </p> - </td> - </tr> - - <tr> - <td><p>Exponent Location</p></td> - <td> - <p>The bit position of the exponent field. Bits are numbered with - the least significant bit number zero. - </p> - </td> - </tr> - - <tr> - <td><p>Exponent Size</p></td> - <td> - <p>The size of the exponent field in bits. - </p> - </td> - </tr> - - <tr> - <td><p>Mantissa Location</p></td> - <td> - <p>The bit position of the mantissa field. Bits are numbered with - the least significant bit number zero. - </p> - </td> - </tr> - - <tr> - <td><p>Mantissa Size</p></td> - <td> - <p>The size of the mantissa field in bits. - </p> - </td> - </tr> - - <tr> - <td><p>Exponent Bias</p></td> - <td> - <p>The bias of the exponent field. - </p> - </td> - </tr> + <tr> + <td><p>Exponent Bias</p></td> + <td> + <p>The bias of the exponent field.</p> + </td> + </tr> - </table> - </div> + </table> +</div> - <br /> - <p>Class specific information for Time (Class 2):</p> - - - <div align="center"> - <table class="desc"> - <caption> - Time Bit Field Description - </caption> - - <tr> - <th width="10%">Bits</th> - <th>Meaning</th> - </tr> - - <tr> - <td><p>0</p></td> - <td><p><b>Byte Order.</b> If zero, byte order is little-endian; - otherwise, byte order is big endian.</p></td> - </tr> - - <tr> - <td><p>1-23</p></td> - <td><p>Reserved (zero).</p></td> - </tr> - </table> - </div> +<br /> +<p>Class specific information for Time (Class 2):</p> - <br /> - <div align="center"> - <table class="format"> - <caption> - Time Property Description - </caption> - - <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - </tr> - - <tr> - <td colspan="2">Bit Precision</td> - </tr> - </table> - </div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Bit Precision</p></td> - <td> - <p>The number of bits of precision of the time value. - </p> - </td> - </tr> +<div align="center"> + <table class="desc"> + <caption>Time Bit Field Description</caption> - </table> - </div> + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + <tr> + <td><p>0</p></td> + <td><p> + <b>Byte Order.</b> If zero, byte order is little-endian; otherwise, + byte order is big endian. + </p></td> + </tr> - <br /> - <p>Class specific information for Strings (Class 3):</p> - - - <div align="center"> - <table class="desc"> - <caption> - String Bit Field Description - </caption> - - <tr> - <th width="10%">Bits</th> - <th>Meaning</th> - </tr> - - <tr> - <td><p>0-3</p></td> - <td><p><b>Padding type.</b> This four-bit value determines the - type of padding to use for the string. The values are: - - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Null Terminate: A zero byte marks the end of the - string and is guaranteed to be present after - converting a long string to a short string. When - converting a short string to a long string the value is - padded with additional null characters as necessary. - </td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>Null Pad: Null characters are added to the end of - the value during conversions from short values to long - values but conversion in the opposite direction simply - truncates the value. - </td> - </tr> - - <tr> - <td align="center"><code>2</code></td> - <td>Space Pad: Space characters are added to the end of - the value during conversions from short values to long - values but conversion in the opposite direction simply - truncates the value. This is the Fortran - representation of the string. - </td> - </tr> - - <tr> - <td align="center"><code>3-15</code></td> - <td>Reserved - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>4-7</p></td> - <td><p><b>Character Set.</b> The character set used to - encode the string. - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>ASCII character set encoding - </td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>UTF-8 character set encoding - </td> - </tr> - - <tr> - <td align="center"><code>2-15</code></td> - <td>Reserved - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>8-23</p></td> - <td><p>Reserved (zero).</p></td> - </tr> - </table> - </div> - - <p>There are no properties defined for the string class. - </p> - - - <p>Class specific information for bit fields (Class 4):</p> - - <div align="center"> - <table class="desc"> - <caption> - Bitfield Bit Field Description - </caption> - - <tr> - <th width="10%">Bits</th> - <th>Meaning</th> - </tr> - - <tr> - <td><p>0</p></td> - <td><p><b>Byte Order.</b> If zero, byte order is little-endian; - otherwise, byte order is big endian.</p></td> - </tr> - - <tr> - <td><p>1, 2</p></td> - <td><p><b>Padding type.</b> Bit 1 is the lo_pad type and bit 2 - is the hi_pad type. If a datum has unused bits at either - end, then the lo_pad or hi_pad bit is copied to those - locations.</p></td> - </tr> - - <tr> - <td><p>3-23</p></td> - <td><p>Reserved (zero).</p></td> - </tr> - </table> - </div> + <tr> + <td><p>1-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> +</div> - <br /> - <div align="center"> - <table class="format"> - <caption> - Bit Field Property Description - </caption> - - <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - </tr> - - <tr> - <td colspan="2">Bit Offset</td> - <td colspan="2">Bit Precision</td> - </tr> - </table> - </div> +<br /> +<div align="center"> + <table class="format"> + <caption>Time Property Description</caption> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Bit Offset</p></td> - <td> - <p>The bit offset of the first significant bit of the bit field - within the datatype. The bit offset specifies the number - of bits “to the right of” the value. - </p> - </td> - </tr> - - <tr> - <td><p>Bit Precision</p></td> - <td> - <p>The number of bits of precision of the bit field - within the datatype. - </p> - </td> - </tr> - </table> - </div> + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + <tr> + <td colspan="2">Bit Precision</td> + </tr> + </table> +</div> - <br /> - <p>Class specific information for Opaque (Class 5):</p> - - <div align="center"> - <table class="desc"> - <caption> - Opaque Bit Field Description - </caption> - - <tr> - <th width="10%">Bits</th> - <th>Meaning</th> - </tr> - - <tr> - <td><p>0-7</p></td> - <td><p>Length of ASCII tag in bytes.</p></td> - </tr> - - <tr> - <td><p>8-23</p></td> - <td><p>Reserved (zero).</p></td> - </tr> - </table> - </div> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <br /> - <div align="center"> - <table class="format"> - <caption> - Opaque Property Description - </caption> - - <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - </tr> - - <tr> - <td colspan="4"><br />ASCII Tag<br /> - <br /></td> - </tr> - </table> - </div> + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the time value.</p> + </td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>ASCII Tag</p></td> - <td> - <p>This NUL-terminated string provides a description for the - opaque type. It is NUL-padded to a multiple of 8 bytes. - </p> - </td> - </tr> - </table> - </div> + </table> +</div> - <br /> - <p>Class specific information for Compound (Class 6):</p> - - <div align="center"> - <table class="desc"> - <caption> - Compound Bit Field Description - </caption> - - <tr> - <th width="10%">Bits</th> - <th>Meaning</th> - </tr> - - <tr> - <td><p>0-15</p></td> - <td><p><b>Number of Members.</b> This field contains the number - of members defined for the compound datatype. The member - definitions are listed in the Properties field of the data - type message.</p></td> - </tr> - - <tr> - <td><p>16-23</p></td> - <td><p>Reserved (zero).</p></td> - </tr> - </table> - </div> +<br /> +<p>Class specific information for Strings (Class 3):</p> - <p>The Properties field of a compound datatype is a list of the - member definitions of the compound datatype. The member - definitions appear one after another with no intervening bytes. - The member types are described with a (recursively) encoded datatype - message.</p> +<div align="center"> + <table class="desc"> + <caption>String Bit Field Description</caption> - <p>Note that the property descriptions are different for different - versions of the datatype version. Additionally note that the version - 0 datatype encoding is deprecated and has been replaced with later - encodings in versions of the HDF5 Library from the 1.4 release - onward.</p> + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + <tr> + <td><p>0-3</p></td> + <td><p> + <b>Padding type.</b> This four-bit value determines the type of + padding to use for the string. The values are: - <div align="center"> - <table class="format"> - <caption> - Compound Properties Description for Datatype Version 1 - </caption> + </p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> - <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - </tr> + <tr> + <td align="center"><code>0</code></td> + <td>Null Terminate: A zero byte marks the end of the string + and is guaranteed to be present after converting a long string to + a short string. When converting a short string to a long string + the value is padded with additional null characters as necessary. + </td> + </tr> - <tr> - <td colspan="4"><br />Name<br /><br /></td> - </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Null Pad: Null characters are added to the end of the + value during conversions from short values to long values but + conversion in the opposite direction simply truncates the value. + </td> + </tr> - <tr> - <td colspan="4">Byte Offset of Member</td> - </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Space Pad: Space characters are added to the end of the + value during conversions from short values to long values but + conversion in the opposite direction simply truncates the value. + This is the Fortran representation of the string.</td> + </tr> - <tr> - <td>Dimensionality</td> - <td colspan="3">Reserved (zero)</td> - </tr> + <tr> + <td align="center"><code>3-15</code></td> + <td>Reserved</td> + </tr> + </table> + <p></p></td> + </tr> - <tr> - <td colspan="4">Dimension Permutation</td> - </tr> + <tr> + <td><p>4-7</p></td> + <td><p> + <b>Character Set.</b> The character set used to encode the string. + </p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> - <tr> - <td colspan="4">Reserved (zero)</td> - </tr> + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding</td> + </tr> - <tr> - <td colspan="4">Dimension #1 Size (required)</td> - </tr> + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding</td> + </tr> - <tr> - <td colspan="4">Dimension #2 Size (required)</td> - </tr> + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved</td> + </tr> + </table> + <p></p></td> + </tr> - <tr> - <td colspan="4">Dimension #3 Size (required)</td> - </tr> + <tr> + <td><p>8-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> +</div> - <tr> - <td colspan="4">Dimension #4 Size (required)</td> - </tr> +<p>There are no properties defined for the string class.</p> - <tr> - <td colspan="4"><br />Member Type Message<br /><br /></td> - </tr> - </table> - </div> +<p>Class specific information for bit fields (Class 4):</p> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Name</p></td> - <td> - <p>This NUL-terminated string provides a description for the - opaque type. It is NUL-padded to a multiple of 8 bytes. - </p> - </td> - </tr> - - <tr> - <td><p>Byte Offset of Member</p></td> - <td> - <p>This is the byte offset of the member within the datatype. - </p> - </td> - </tr> - - <tr> - <td><p>Dimensionality</p></td> - <td> - <p>If set to zero, this field indicates a scalar member. If set - to a value greater than zero, this field indicates that the - member is an array of values. For array members, the size of - the array is indicated by the ‘Size of Dimension n’ field in - this message. - </p> - </td> - </tr> - - <tr> - <td><p>Dimension Permutation</p></td> - <td> - <p>This field was intended to allow an array field to have - its dimensions permuted, but this was never implemented. - This field should always be set to zero. - </p> - </td> - </tr> - - <tr> - <td><p>Dimension #n Size</p></td> - <td> - <p>This field is the size of a dimension of the array field as - stored in the file. The first dimension stored in the list of - dimensions is the slowest changing dimension and the last - dimension stored is the fastest changing dimension. - </p> - </td> - </tr> - - <tr> - <td><p>Member Type Message</p></td> - <td> - <p>This field is a datatype message describing the datatype of - the member. - </p> - </td> - </tr> +<div align="center"> + <table class="desc"> + <caption>Bitfield Bit Field Description</caption> - </table> - </div> + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Compound Properties Description for Datatype Version 2 - </caption> - - <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - </tr> - - <tr> - <td colspan="4"><br />Name<br /><br /></td> - </tr> - - <tr> - <td colspan="4">Byte Offset of Member</td> - </tr> - - <tr> - <td colspan="4"><br />Member Type Message<br /><br /></td> - </tr> + <tr> + <td><p>0</p></td> + <td><p> + <b>Byte Order.</b> If zero, byte order is little-endian; otherwise, + byte order is big endian. + </p></td> + </tr> - </table> - </div> + <tr> + <td><p>1, 2</p></td> + <td><p> + <b>Padding type.</b> Bit 1 is the lo_pad type and bit 2 is the + hi_pad type. If a datum has unused bits at either end, then the + lo_pad or hi_pad bit is copied to those locations. + </p></td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Name</p></td> - <td> - <p>This NUL-terminated string provides a description for the - opaque type. It is NUL-padded to a multiple of 8 bytes. - </p> - </td> - </tr> - - <tr> - <td><p>Byte Offset of Member</p></td> - <td> - <p>This is the byte offset of the member within the datatype. - </p> - </td> - </tr> - - <tr> - <td><p>Member Type Message</p></td> - <td> - <p>This field is a datatype message describing the datatype of - the member. - </p> - </td> - </tr> + <tr> + <td><p>3-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> +</div> - </table> - </div> +<br /> +<div align="center"> + <table class="format"> + <caption>Bit Field Property Description</caption> + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Compound Properties Description for Datatype Version 3 - </caption> - - <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - </tr> - - <tr> - <td colspan="4"><br />Name<br /><br /></td> - </tr> - - <tr> - <td colspan="4">Byte Offset of Member <em>(variable size)</em></td> - </tr> - - <tr> - <td colspan="4"><br />Member Type Message<br /><br /></td> - </tr> + <tr> + <td colspan="2">Bit Offset</td> + <td colspan="2">Bit Precision</td> + </tr> + </table> +</div> - </table> - </div> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Name</p></td> - <td><p>This NUL-terminated string provides a description for the - opaque type. It is <em>not</em> NUL-padded to a multiple of 8 - bytes.</p></td> - </tr> - - <tr> - <td><p>Byte Offset of Member</p></td> - <td><p>This is the byte offset of the member within the datatype. - The field size is the minimum number of bytes necessary, - based on the size of the datatype element. For example, a - datatype element size of less than 256 bytes uses a 1 byte - length, a datatype element size of 256-65535 bytes uses a - 2 byte length, and so on.</p></td> - </tr> - - <tr> - <td><p>Member Type Message</p></td> - <td><p>This field is a datatype message describing the datatype of - the member.</p></td> - </tr> + <tr> + <td><p>Bit Offset</p></td> + <td> + <p>The bit offset of the first significant bit of the bit field + within the datatype. The bit offset specifies the number of bits + “to the right of” the value.</p> + </td> + </tr> - </table> - </div> + <tr> + <td><p>Bit Precision</p></td> + <td> + <p>The number of bits of precision of the bit field within the + datatype.</p> + </td> + </tr> + </table> +</div> - <br /> - <p>Class specific information for Reference (Class 7):</p> - - <div align="center"> - <table class="desc"> - <caption> - Reference Bit Field Description - </caption> - - <tr> - <th width="10%">Bits</th> - <th>Meaning</th> - </tr> - - <tr> - <td><p>0-3</p></td> - <td><p><b>Type.</b> This four-bit value contains the type of reference - described. The values defined are: - - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Object Reference: A reference to another object in this - HDF5 file. - </td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>Dataset Region Reference: A reference to a region within - a dataset in this HDF5 file. - </td> - </tr> - - <tr> - <td align="center"><code>2-15</code></td> - <td>Reserved - </td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>4-23</p></td> - <td><p>Reserved (zero).</p></td> - </tr> - </table> - </div> +<br /> +<p>Class specific information for Opaque (Class 5):</p> - <p>There are no properties defined for the reference class. - </p> +<div align="center"> + <table class="desc"> + <caption>Opaque Bit Field Description</caption> + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> - <br /> - <p>Class specific information for Enumeration (Class 8):</p> - - <div align="center"> - <table class="desc"> - <caption> - Enumeration Bit Field Description - </caption> - - <tr> - <th width="10%">Bits</th> - <th>Meaning</th> - </tr> - - <tr> - <td><p>0-15</p></td> - <td><p><b>Number of Members.</b> The number of name/value - pairs defined for the enumeration type.</p></td> - </tr> - - <tr> - <td><p>16-23</p></td> - <td><p>Reserved (zero).</p></td> - </tr> - </table> - </div> + <tr> + <td><p>0-7</p></td> + <td><p>Length of ASCII tag in bytes.</p></td> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Enumeration Property Description for Datatype Versions 1 & 2 - </caption> + <tr> + <td><p>8-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> +</div> - <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - </tr> +<br /> +<div align="center"> + <table class="format"> + <caption>Opaque Property Description</caption> - <tr> - <td colspan="4"><br />Base Type<br /><br /></td> - </tr> + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> - <tr> - <td colspan="4"><br />Names<br /><br /></td> - </tr> + <tr> + <td colspan="4"><br />ASCII Tag<br /> <br /></td> + </tr> + </table> +</div> - <tr> - <td colspan="4"><br />Values<br /><br /></td> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> </tr> - </table> - </div> + <tr> + <td><p>ASCII Tag</p></td> + <td> + <p>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes.</p> + </td> + </tr> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Base Type</p></td> - <td> - <p>Each enumeration type is based on some parent type, usually an - integer. The information for that parent type is described - recursively by this field. - </p> - </td> - </tr> - - <tr> - <td><p>Names</p></td> - <td> - <p>The name for each name/value pair. Each name is stored as a null - terminated ASCII string in a multiple of eight bytes. The names - are in no particular order. - </p> - </td> - </tr> - - <tr> - <td><p>Values</p></td> - <td> - <p>The list of values in the same order as the names. The values - are packed (no inter-value padding) and the size of each value - is determined by the parent type. - </p> - </td> - </tr> - </table> - </div> +<br /> +<p>Class specific information for Compound (Class 6):</p> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Enumeration Property Description for Datatype Version 3 - </caption> +<div align="center"> + <table class="desc"> + <caption>Compound Bit Field Description</caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-15</p></td> + <td><p> + <b>Number of Members.</b> This field contains the number of members + defined for the compound datatype. The member definitions are + listed in the Properties field of the data type message. + </p></td> + </tr> - <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - </tr> + <tr> + <td><p>16-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> +</div> + + +<p>The Properties field of a compound datatype is a list of the + member definitions of the compound datatype. The member definitions + appear one after another with no intervening bytes. The member types + are described with a (recursively) encoded datatype message.</p> - <tr> - <td colspan="4"><br />Base Type<br /><br /></td> - </tr> +<p>Note that the property descriptions are different for different + versions of the datatype version. Additionally note that the version 0 + datatype encoding is deprecated and has been replaced with later + encodings in versions of the HDF5 Library from the 1.4 release onward.</p> - <tr> - <td colspan="4"><br />Names<br /><br /></td> - </tr> - <tr> - <td colspan="4"><br />Values<br /><br /></td> +<div align="center"> + <table class="format"> + <caption>Compound Properties Description for Datatype + Version 1</caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> </tr> - </table> - </div> + <tr> + <td colspan="4"><br />Name<br /> + <br /></td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Base Type</p></td> - <td> - <p>Each enumeration type is based on some parent type, usually an - integer. The information for that parent type is described - recursively by this field. - </p> - </td> - </tr> - - <tr> - <td><p>Names</p></td> - <td> - <p>The name for each name/value pair. Each name is stored as a null - terminated ASCII string, <em>not</em> padded to a multiple of - eight bytes. The names are in no particular order. - </p> - </td> - </tr> - - <tr> - <td><p>Values</p></td> - <td> - <p>The list of values in the same order as the names. The values - are packed (no inter-value padding) and the size of each value - is determined by the parent type. - </p> - </td> - </tr> + <tr> + <td colspan="4">Byte Offset of Member</td> + </tr> - </table> - </div> + <tr> + <td>Dimensionality</td> + <td colspan="3">Reserved (zero)</td> + </tr> + <tr> + <td colspan="4">Dimension Permutation</td> + </tr> + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> - <br /> - <p>Class specific information for Variable-Length (Class 9):</p> - - <div align="center"> - <table class="desc"> - <caption> - Variable-Length Bit Field Description - </caption> - - <tr> - <th width="10%">Bits</th> - <th>Meaning</th> - </tr> - - <tr> - <td><p>0-3</p></td> - <td><p><b>Type.</b> This four-bit value contains the type of - variable-length datatype described. The values defined are: - - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Sequence: A variable-length sequence of any datatype. - Variable-length sequences do not have padding or - character set information. - </td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>String: A variable-length sequence of characters. - Variable-length strings have padding and character set - information. - </td> - </tr> - - <tr> - <td align="center"><code>2-15</code></td> - <td>Reserved - </td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>4-7</p></td> - <td><p><b>Padding type.</b> (variable-length string only) - This four-bit value determines the type of padding - used for variable-length strings. The values are the same - as for the string padding type, as follows: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Null terminate: A zero byte marks the end of a string - and is guaranteed to be present after converting a long - string to a short string. When converting a short string - to a long string, the value is padded with additional null - characters as necessary. - </td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>Null pad: Null characters are added to the end of the - value during conversion from a short string to a longer - string. Conversion from a long string to a shorter string - simply truncates the value. - </td> - </tr> - - <tr> - <td align="center"><code>2</code></td> - <td>Space pad: Space characters are added to the end of the - value during conversion from a short string to a longer - string. Conversion from a long string to a shorter string - simply truncates the value. This is the Fortran - representation of the string. - </td> - </tr> - - <tr> - <td align="center"><code>3-15</code></td> - <td>Reserved - </td> - </tr> - </table></p> - - <p>This value is set to zero for variable-length sequences.</p> - - </td> - </tr> - - <tr> - <td><p>8-11</p></td> - <td><p><b>Character Set.</b> (variable-length string only) - This four-bit value specifies the character set - to be used for encoding the string: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>ASCII character set encoding - </td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>UTF-8 character set encoding - </td> - </tr> - - <tr> - <td align="center"><code>2-15</code></td> - <td>Reserved - </td> - </tr> - </table></p> - - <p>This value is set to zero for variable-length sequences.</p> - - </td> - </tr> - - <tr> - <td><p>12-23</p></td> - <td><p>Reserved (zero).</p></td> - </tr> - </table> - </div> + <tr> + <td colspan="4">Dimension #1 Size (required)</td> + </tr> - <br /> - <br /> - <div align="center"> - <table class="format"> - <caption> - Variable-Length Property Description - </caption> + <tr> + <td colspan="4">Dimension #2 Size (required)</td> + </tr> <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> + <td colspan="4">Dimension #3 Size (required)</td> </tr> <tr> - <td colspan="4"><br />Base Type<br /><br /></td> + <td colspan="4">Dimension #4 Size (required)</td> </tr> - </table> - </div> + <tr> + <td colspan="4"><br />Member Type Message<br /> + <br /></td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="10%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Base Type</p></td> - <td> - <p>Each variable-length type is based on some parent type. The - information for that parent type is described recursively by - this field. - </p> - </td> - </tr> + </table> +</div> - </table> - </div> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name</p></td> + <td> + <p>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes.</p> + </td> + </tr> + <tr> + <td><p>Byte Offset of Member</p></td> + <td> + <p>This is the byte offset of the member within the datatype.</p> + </td> + </tr> - <br /> - <p>Class specific information for Array (Class 10):</p> + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>If set to zero, this field indicates a scalar member. If set + to a value greater than zero, this field indicates that the member + is an array of values. For array members, the size of the array is + indicated by the ‘Size of Dimension n’ field in this + message.</p> + </td> + </tr> - <p>There are no bit fields defined for the array class. - </p> + <tr> + <td><p>Dimension Permutation</p></td> + <td> + <p>This field was intended to allow an array field to have its + dimensions permuted, but this was never implemented. This field + should always be set to zero.</p> + </td> + </tr> - <p>Note that the dimension information defined in the property for this - datatype class is independent of dataspace information for a dataset. - The dimension information here describes the dimensionality of the - information within a data element (or a component of an element, if the - array datatype is nested within another datatype) and the dataspace for a - dataset describes the size and locations of the elements in a dataset. - </p> + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This field is the size of a dimension of the array field as + stored in the file. The first dimension stored in the list of + dimensions is the slowest changing dimension and the last dimension + stored is the fastest changing dimension.</p> + </td> + </tr> + <tr> + <td><p>Member Type Message</p></td> + <td> + <p>This field is a datatype message describing the datatype of + the member.</p> + </td> + </tr> - <div align="center"> - <table class="format"> - <caption> - Array Property Description for Datatype Version 2 - </caption> + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Compound Properties Description for Datatype + Version 2</caption> <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> </tr> - <tr> - <td>Dimensionality</td> - <td colspan="3">Reserved (zero)</td> - </tr> + <tr> + <td colspan="4"><br />Name<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4">Byte Offset of Member</td> + </tr> - <tr> - <td colspan="4">Dimension #1 Size</td> - </tr> - <tr> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - <tr> - <td colspan="4">Dimension #n Size</td> - </tr> + <tr> + <td colspan="4"><br />Member Type Message<br /> + <br /></td> + </tr> - <tr> - <td colspan="4">Permutation Index #1</td> - </tr> - <tr> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - <tr> - <td colspan="4">Permutation Index #n</td> - </tr> + </table> +</div> +<br /> +<div align="center"> + <table class="desc"> <tr> - <td colspan="4"><br />Base Type<br /><br /></td> + <th width="30%">Field Name</th> + <th>Description</th> </tr> - </table> - </div> + <tr> + <td><p>Name</p></td> + <td> + <p>This NUL-terminated string provides a description for the + opaque type. It is NUL-padded to a multiple of 8 bytes.</p> + </td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Dimensionality</p></td> - <td> - <p>This value is the number of dimensions that the array has. - </p> - </td> - </tr> - - <tr> - <td><p>Dimension #n Size</p></td> - <td> - <p>This value is the size of the dimension of the array - as stored in the file. The first dimension stored in - the list of dimensions is the slowest changing dimension - and the last dimension stored is the fastest changing - dimension. - </p> - </td> - </tr> - - <tr> - <td><p>Permutation Index #n</p></td> - <td> - <p>This value is the index permutation used to map - each dimension from the canonical representation to an - alternate axis for each dimension. Currently, dimension - permutations are not supported, and these indices should - be set to the index position minus one. In other words, - the first dimension should be set to 0, the second dimension - should be set to 1, and so on. - </p> - </td> - </tr> - - <tr> - <td><p>Base Type</p></td> - <td> - <p>Each array type is based on some parent type. The - information for that parent type is described recursively by - this field. - </p> - </td> - </tr> + <tr> + <td><p>Byte Offset of Member</p></td> + <td> + <p>This is the byte offset of the member within the datatype.</p> + </td> + </tr> - </table> - </div> + <tr> + <td><p>Member Type Message</p></td> + <td> + <p>This field is a datatype message describing the datatype of + the member.</p> + </td> + </tr> - <br /> - <div align="center"> - <table class="format"> - <caption> - Array Property Description for Datatype Version 3 - </caption> + </table> +</div> + + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Compound Properties Description for Datatype + Version 3</caption> <tr> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> - <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> </tr> - <tr> - <td>Dimensionality</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <tr> + <td colspan="4"><br />Name<br /> + <br /></td> + </tr> - <tr> - <td colspan="4">Dimension #1 Size</td> - </tr> - <tr> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - <tr> - <td colspan="4">Dimension #n Size</td> - </tr> + <tr> + <td colspan="4">Byte Offset of Member <em>(variable size)</em></td> + </tr> <tr> - <td colspan="4"><br />Base Type<br /><br /></td> + <td colspan="4"><br />Member Type Message<br /> + <br /></td> </tr> - </table> - </div> + </table> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Dimensionality</p></td> - <td> - <p>This value is the number of dimensions that the array has. - </p> - </td> - </tr> - - <tr> - <td><p>Dimension #n Size</p></td> - <td> - <p>This value is the size of the dimension of the array - as stored in the file. The first dimension stored in - the list of dimensions is the slowest changing dimension - and the last dimension stored is the fastest changing - dimension. - </p> - </td> - </tr> - - <tr> - <td><p>Base Type</p></td> - <td> - <p>Each array type is based on some parent type. The - information for that parent type is described recursively by - this field. - </p> - </td> - </tr> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - </table> - </div> + <tr> + <td><p>Name</p></td> + <td><p> + This NUL-terminated string provides a description for the opaque + type. It is <em>not</em> NUL-padded to a multiple of 8 bytes. + </p></td> + </tr> + <tr> + <td><p>Byte Offset of Member</p></td> + <td><p>This is the byte offset of the member within the + datatype. The field size is the minimum number of bytes necessary, + based on the size of the datatype element. For example, a datatype + element size of less than 256 bytes uses a 1 byte length, a + datatype element size of 256-65535 bytes uses a 2 byte length, and + so on.</p></td> + </tr> + + <tr> + <td><p>Member Type Message</p></td> + <td><p>This field is a datatype message describing the + datatype of the member.</p></td> + </tr> + + </table> +</div> <br /> -<h4><a name="OldFillValueMessage">IV.A.2.e. The Data Storage - -Fill Value (Old) Message</a></h4> +<p>Class specific information for Reference (Class 7):</p> - <!-- start msgdesc table --> - <center> +<div align="center"> + <table class="desc"> + <caption>Reference Bit Field Description</caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-3</p></td> + <td><p> + <b>Type.</b> This four-bit value contains the type of reference + described. The values defined are: + + </p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Object Reference: A reference to another object in this + HDF5 file.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Dataset Region Reference: A reference to a region within + a dataset in this HDF5 file.</td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>4-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> +</div> + +<p>There are no properties defined for the reference class.</p> + + +<br /> +<p>Class specific information for Enumeration (Class 8):</p> + +<div align="center"> + <table class="desc"> + <caption>Enumeration Bit Field Description</caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-15</p></td> + <td><p> + <b>Number of Members.</b> The number of name/value pairs defined + for the enumeration type. + </p></td> + </tr> + + <tr> + <td><p>16-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Enumeration Property Description for Datatype + Versions 1 & 2</caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Names<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Values<br /> + <br /></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each enumeration type is based on some parent type, usually + an integer. The information for that parent type is described + recursively by this field.</p> + </td> + </tr> + + <tr> + <td><p>Names</p></td> + <td> + <p>The name for each name/value pair. Each name is stored as a + null terminated ASCII string in a multiple of eight bytes. The + names are in no particular order.</p> + </td> + </tr> + + <tr> + <td><p>Values</p></td> + <td> + <p>The list of values in the same order as the names. The values + are packed (no inter-value padding) and the size of each value is + determined by the parent type.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Enumeration Property Description for Datatype + Version 3</caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Names<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Values<br /> + <br /></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each enumeration type is based on some parent type, usually + an integer. The information for that parent type is described + recursively by this field.</p> + </td> + </tr> + + <tr> + <td><p>Names</p></td> + <td> + <p> + The name for each name/value pair. Each name is stored as a null + terminated ASCII string, <em>not</em> padded to a multiple of eight + bytes. The names are in no particular order. + </p> + </td> + </tr> + + <tr> + <td><p>Values</p></td> + <td> + <p>The list of values in the same order as the names. The values + are packed (no inter-value padding) and the size of each value is + determined by the parent type.</p> + </td> + </tr> + + </table> +</div> + + + +<br /> +<p>Class specific information for Variable-Length (Class 9):</p> + +<div align="center"> + <table class="desc"> + <caption>Variable-Length Bit Field Description</caption> + + <tr> + <th width="10%">Bits</th> + <th>Meaning</th> + </tr> + + <tr> + <td><p>0-3</p></td> + <td><p> + <b>Type.</b> This four-bit value contains the type of + variable-length datatype described. The values defined are: + + </p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Sequence: A variable-length sequence of any datatype. + Variable-length sequences do not have padding or character set + information.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>String: A variable-length sequence of characters. + Variable-length strings have padding and character set + information.</td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>4-7</p></td> + <td><p> + <b>Padding type.</b> (variable-length string only) This four-bit + value determines the type of padding used for variable-length + strings. The values are the same as for the string padding type, as + follows: + </p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Null terminate: A zero byte marks the end of a string and + is guaranteed to be present after converting a long string to a + short string. When converting a short string to a long string, + the value is padded with additional null characters as necessary. + </td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Null pad: Null characters are added to the end of the + value during conversion from a short string to a longer string. + Conversion from a long string to a shorter string simply + truncates the value.</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Space pad: Space characters are added to the end of the + value during conversion from a short string to a longer string. + Conversion from a long string to a shorter string simply + truncates the value. This is the Fortran representation of the + string.</td> + </tr> + + <tr> + <td align="center"><code>3-15</code></td> + <td>Reserved</td> + </tr> + </table> + <p></p> + + <p>This value is set to zero for variable-length sequences.</p></td> + </tr> + + <tr> + <td><p>8-11</p></td> + <td><p> + <b>Character Set.</b> (variable-length string only) This four-bit + value specifies the character set to be used for encoding the + string: + </p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding</td> + </tr> + + <tr> + <td align="center"><code>2-15</code></td> + <td>Reserved</td> + </tr> + </table> + <p></p> + + <p>This value is set to zero for variable-length sequences.</p></td> + </tr> + + <tr> + <td><p>12-23</p></td> + <td><p>Reserved (zero).</p></td> + </tr> + </table> +</div> + +<br /> +<br /> +<div align="center"> + <table class="format"> + <caption>Variable-Length Property Description</caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /> + <br /></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="10%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each variable-length type is based on some parent type. The + information for that parent type is described recursively by this + field.</p> + </td> + </tr> + + </table> +</div> + + +<br /> +<p>Class specific information for Array (Class 10):</p> + +<p>There are no bit fields defined for the array class.</p> + +<p>Note that the dimension information defined in the property for + this datatype class is independent of dataspace information for a + dataset. The dimension information here describes the dimensionality of + the information within a data element (or a component of an element, if + the array datatype is nested within another datatype) and the dataspace + for a dataset describes the size and locations of the elements in a + dataset.</p> + + +<div align="center"> + <table class="format"> + <caption>Array Property Description for Datatype Version 2</caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Dimension #1 Size</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + + <tr> + <td colspan="4">Permutation Index #1</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Permutation Index #n</td> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /> + <br /></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the array has.</p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the size of the dimension of the array as + stored in the file. The first dimension stored in the list of + dimensions is the slowest changing dimension and the last dimension + stored is the fastest changing dimension.</p> + </td> + </tr> + + <tr> + <td><p>Permutation Index #n</p></td> + <td> + <p>This value is the index permutation used to map each + dimension from the canonical representation to an alternate axis + for each dimension. Currently, dimension permutations are not + supported, and these indices should be set to the index position + minus one. In other words, the first dimension should be set to 0, + the second dimension should be set to 1, and so on.</p> + </td> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each array type is based on some parent type. The information + for that parent type is described recursively by this field.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="format"> + <caption>Array Property Description for Datatype Version 3</caption> + + <tr> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + <th width="25%">Byte</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Dimension #1 Size</td> + </tr> + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + + <tr> + <td colspan="4"><br />Base Type<br /> + <br /></td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td> + <p>This value is the number of dimensions that the array has.</p> + </td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td> + <p>This value is the size of the dimension of the array as + stored in the file. The first dimension stored in the list of + dimensions is the slowest changing dimension and the last dimension + stored is the fastest changing dimension.</p> + </td> + </tr> + + <tr> + <td><p>Base Type</p></td> + <td> + <p>Each array type is based on some parent type. The information + for that parent type is described recursively by this field.</p> + </td> + </tr> + + </table> +</div> + + + +<br /> +<h4> + <a name="OldFillValueMessage">IV.A.2.e. The Data Storage - Fill + Value (Old) Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Fill Value - (old)</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0004</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td><p>The fill value message stores a single data value which - is returned to the application when an uninitialized data element - is read from a dataset. The fill value is interpreted with the - same datatype as the dataset. If no fill value message is present - then a fill value of all zero bytes is assumed.</p> - <p>This fill value message is deprecated in favor of the - “new” fill value message (Message Type 0x0005) and - is only written to the file for forward compatibility with - versions of the HDF5 Library before the 1.6.0 version. - Additionally, it only appears for datasets with a user-defined - fill value (as opposed to the library default fill value or an - explicitly set “undefined” fill value).</p> - </td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Fill Value Message (Old) - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td colspan="4">Size</td> - </tr> - - <tr> - <td colspan="4"><br />Fill Value <em>(optional, variable size)</em><br /><br /></td> - </tr> - </table> - </div> + <tr> + <td colspan="2"><b>Header Message Name:</b> Fill Value (old)</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0004</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td><p>The fill value message stores a single data value + which is returned to the application when an uninitialized data + element is read from a dataset. The fill value is interpreted with + the same datatype as the dataset. If no fill value message is + present then a fill value of all zero bytes is assumed.</p> + <p>This fill value message is deprecated in favor of the + “new” fill value message (Message Type 0x0005) and is + only written to the file for forward compatibility with versions of + the HDF5 Library before the 1.6.0 version. Additionally, it only + appears for datasets with a user-defined fill value (as opposed to + the library default fill value or an explicitly set + “undefined” fill value).</p></td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Size</p></td> - <td> - <p>This is the size of the Fill Value field in bytes. - </p> - </td> - </tr> - - <tr> - <td><p>Fill Value</p></td> - <td> - <p>The fill value. The bytes of the fill value are interpreted - using the same datatype as for the dataset. - </p> - </td> - </tr> - </table> - </div> +<div align="center"> + <table class="format"> + <caption>Fill Value Message (Old)</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + <tr> + <td colspan="4">Size</td> + </tr> + + <tr> + <td colspan="4"><br />Fill Value <em>(optional, variable + size)</em><br /> + <br /></td> + </tr> + </table> +</div> <br /> -<h4><a name="FillValueMessage">IV.A.2.f. The Data Storage - -Fill Value Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Size</p></td> + <td> + <p>This is the size of the Fill Value field in bytes.</p> + </td> + </tr> + + <tr> + <td><p>Fill Value</p></td> + <td> + <p>The fill value. The bytes of the fill value are interpreted + using the same datatype as for the dataset.</p> + </td> + </tr> + </table> +</div> + + +<br /> +<h4> + <a name="FillValueMessage">IV.A.2.f. The Data Storage - Fill Value + Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Fill - Value</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0005</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies</td></tr> - <tr><td colspan="2"><b>Status:</b> Required for dataset objects; - may not be repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>The fill value message stores a single data value which is - returned to the application when an uninitialized data element - is read from a dataset. The fill value is interpreted with the - same datatype as the dataset.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Fill Value Message - Versions 1 & 2 - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Space Allocation Time</td> - <td>Fill Value Write Time</td> - <td>Fill Value Defined</td> - </tr> - - <tr> - <td colspan="4">Size <em>(optional)</em></td> - </tr> - - <tr> - <td colspan="4"><br />Fill Value <em>(optional, variable size)</em><br /><br /></td> - </tr> - </table> - </div> + <tr> + <td colspan="2"><b>Header Message Name:</b> Fill Value</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0005</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Required for dataset objects; may + not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>The fill value message stores a single data value which is + returned to the application when an uninitialized data element is + read from a dataset. The fill value is interpreted with the same + datatype as the dataset.</td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td> - <p>The version number information is used for changes in the - format of the fill value message and is described here: +<div align="center"> + <table class="format"> + <caption>Fill Value Message - Versions 1 & 2</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Space Allocation Time</td> + <td>Fill Value Write Time</td> + <td>Fill Value Defined</td> + </tr> + + <tr> + <td colspan="4">Size <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Fill Value <em>(optional, variable + size)</em><br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the + format of the fill value message and is described here:</p> <table class="list"> <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> </tr> <tr> - <td align="center"><code>0</code></td> - <td>Never used - </td> + <td align="center"><code>0</code></td> + <td>Never used</td> </tr> <tr> - <td align="center"><code>1</code></td> - <td>Initial version of this message. - </td> + <td align="center"><code>1</code></td> + <td>Initial version of this message.</td> </tr> <tr> - <td align="center"><code>2</code></td> - <td>In this version, the Size and Fill Value fields are - only present if the Fill Value Defined field is set - to 1. - </td> + <td align="center"><code>2</code></td> + <td>In this version, the Size and Fill Value fields are only + present if the Fill Value Defined field is set to 1.</td> </tr> <tr> - <td align="center"><code>3</code></td> - <td>This version packs the other fields in the message - more efficiently than version 2. - </td> + <td align="center"><code>3</code></td> + <td>This version packs the other fields in the message more + efficiently than version 2.</td> </tr> - </table></p> - </p> - </td> - </tr> + </table> + <p></p> + <p></p> + </td> + </tr> - <tr> - <td><p>Space Allocation Time</p></td> - <td> - <p>When the storage space for the dataset’s raw data will be - allocated. The allowed values are: + <tr> + <td><p>Space Allocation Time</p></td> + <td> + <p>When the storage space for the dataset’s raw data will + be allocated. The allowed values are:</p> <table class="list"> <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> </tr> <tr> - <td align="center"><code>0</code></td> - <td>Not used. - </td> + <td align="center"><code>0</code></td> + <td>Not used.</td> </tr> <tr> - <td align="center"><code>1</code></td> - <td>Early allocation. Storage space for the entire dataset - should be allocated in the file when the dataset is - created. - </td> + <td align="center"><code>1</code></td> + <td>Early allocation. Storage space for the entire dataset + should be allocated in the file when the dataset is created.</td> </tr> <tr> - <td align="center"><code>2</code></td> - <td>Late allocation. Storage space for the entire dataset - should not be allocated until the dataset is written - to. - </td> + <td align="center"><code>2</code></td> + <td>Late allocation. Storage space for the entire dataset + should not be allocated until the dataset is written to.</td> </tr> <tr> - <td align="center"><code>3</code></td> - <td>Incremental allocation. Storage space for the - dataset should not be allocated until the portion - of the dataset is written to. This is currently - used in conjunction with chunked data storage for - datasets. - </td> + <td align="center"><code>3</code></td> + <td>Incremental allocation. Storage space for the dataset + should not be allocated until the portion of the dataset is + written to. This is currently used in conjunction with chunked + data storage for datasets.</td> </tr> - </table></p> + </table> + <p></p> - </td> - </tr> + </td> + </tr> - <tr> - <td><p>Fill Value Write Time</p></td> - <td> - <p>At the time that storage space for the dataset’s raw data is - allocated, this value indicates whether the fill value should - be written to the raw data storage elements. The allowed values - are: + <tr> + <td><p>Fill Value Write Time</p></td> + <td> + <p>At the time that storage space for the dataset’s raw + data is allocated, this value indicates whether the fill value + should be written to the raw data storage elements. The allowed + values are:</p> <table class="list"> <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>On allocation. The fill value is always written to - the raw data storage when the storage space is allocated. - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td>Never. The fill value should never be written to - the raw data storage. - </td> - </tr> - <tr> - <td align="center"><code>2</code></td> - <td>Fill value written if set by user. The fill value - will be written to the raw data storage when the storage - space is allocated only if the user explicitly set - the fill value. If the fill value is the library - default or is undefined, it will not be written to - the raw data storage. - </td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>Fill Value Defined</p></td> - <td> - <p>This value indicates if a fill value is defined for this - dataset. If this value is 0, the fill value is undefined. - If this value is 1, a fill value is defined for this dataset. - For version 2 or later of the fill value message, this value - controls the presence of the Size and Fill Value fields. - </p> - </td> - </tr> - - <tr> - <td><p>Size</p></td> - <td> - <p>This is the size of the Fill Value field in bytes. This field - is not present if the Version field is greater than 1, - and the Fill Value Defined field is set to 0. - </p> - </td> - </tr> - - <tr> - <td><p>Fill Value</p></td> - <td> - <p>The fill value. The bytes of the fill value are interpreted - using the same datatype as for the dataset. This field is - not present if the Version field is greater than 1, - and the Fill Value Defined field is set to 0. - </p> - </td> - </tr> - </table> - </div> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> - <br /> - <div align="center"> - <table class="format"> - <caption> - Fill Value Message - Version 3 - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Flags</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4">Size <em>(optional)</em></td> - </tr> - - <tr> - <td colspan="4"><br />Fill Value <em>(optional, variable size)</em><br /><br /></td> - </tr> - </table> - </div> + <tr> + <td align="center"><code>0</code></td> + <td>On allocation. The fill value is always written to the + raw data storage when the storage space is allocated.</td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>Never. The fill value should never be written to the raw + data storage.</td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Fill value written if set by user. The fill value will be + written to the raw data storage when the storage space is + allocated only if the user explicitly set the fill value. If the + fill value is the library default or is undefined, it will not be + written to the raw data storage.</td> + </tr> + </table> + <p></p> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td> - <p>The version number information is used for changes in the - format of the fill value message and is described here: + </td> + </tr> + + <tr> + <td><p>Fill Value Defined</p></td> + <td> + <p>This value indicates if a fill value is defined for this + dataset. If this value is 0, the fill value is undefined. If this + value is 1, a fill value is defined for this dataset. For version 2 + or later of the fill value message, this value controls the + presence of the Size and Fill Value fields.</p> + </td> + </tr> + + <tr> + <td><p>Size</p></td> + <td> + <p>This is the size of the Fill Value field in bytes. This field + is not present if the Version field is greater than 1, and the Fill + Value Defined field is set to 0.</p> + </td> + </tr> + + <tr> + <td><p>Fill Value</p></td> + <td> + <p>The fill value. The bytes of the fill value are interpreted + using the same datatype as for the dataset. This field is not + present if the Version field is greater than 1, and the Fill Value + Defined field is set to 0.</p> + </td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="format"> + <caption>Fill Value Message - Version 3</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Size <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="4"><br />Fill Value <em>(optional, variable + size)</em><br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the + format of the fill value message and is described here:</p> <table class="list"> <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> </tr> <tr> - <td align="center"><code>0</code></td> - <td>Never used - </td> + <td align="center"><code>0</code></td> + <td>Never used</td> </tr> <tr> - <td align="center"><code>1</code></td> - <td>Initial version of this message. - </td> + <td align="center"><code>1</code></td> + <td>Initial version of this message.</td> </tr> <tr> - <td align="center"><code>2</code></td> - <td>In this version, the Size and Fill Value fields are - only present if the Fill Value Defined field is set - to 1. - </td> + <td align="center"><code>2</code></td> + <td>In this version, the Size and Fill Value fields are only + present if the Fill Value Defined field is set to 1.</td> </tr> <tr> - <td align="center"><code>3</code></td> - <td>This version packs the other fields in the message - more efficiently than version 2. - </td> + <td align="center"><code>3</code></td> + <td>This version packs the other fields in the message more + efficiently than version 2.</td> </tr> - </table></p> + </table> + <p></p> - </td> - </tr> + </td> + </tr> - <tr> - <td><p>Flags</p></td> - <td> - <p>When the storage space for the dataset’s raw data will be - allocated. The allowed values are: + <tr> + <td><p>Flags</p></td> + <td> + <p>When the storage space for the dataset’s raw data will + be allocated. The allowed values are:</p> <table class="list"> <tr> - <th width="20%" align="center">Bits</th> - <th width="80%" align="left">Description</th> + <th width="20%" align="center">Bits</th> + <th width="80%" align="left">Description</th> </tr> <tr> - <td align="center"><code>0-1</code></td> - <td>Space Allocation Time, with the same - values as versions 1 and 2 of the message. - </td> + <td align="center"><code>0-1</code></td> + <td>Space Allocation Time, with the same values as versions 1 + and 2 of the message.</td> </tr> <tr> - <td align="center"><code>2-3</code></td> - <td>Fill Value Write Time, with the same - values as versions 1 and 2 of the message. - </td> + <td align="center"><code>2-3</code></td> + <td>Fill Value Write Time, with the same values as versions 1 + and 2 of the message.</td> </tr> <tr> - <td align="center"><code>4</code></td> - <td>Fill Value Undefined, indicating that the fill - value has been marked as “undefined” for this dataset. - Bits 4 and 5 cannot both be set. - </td> + <td align="center"><code>4</code></td> + <td>Fill Value Undefined, indicating that the fill value has + been marked as “undefined” for this dataset. Bits 4 + and 5 cannot both be set.</td> </tr> <tr> - <td align="center"><code>5</code></td> - <td>Fill Value Defined, with the same values as - versions 1 and 2 of the message. - Bits 4 and 5 cannot both be set. - </td> + <td align="center"><code>5</code></td> + <td>Fill Value Defined, with the same values as versions 1 + and 2 of the message. Bits 4 and 5 cannot both be set.</td> </tr> <tr> - <td align="center"><code>6-7</code></td> - <td>Reserved (zero). - </td> + <td align="center"><code>6-7</code></td> + <td>Reserved (zero).</td> </tr> - </table></p> + </table> + <p></p> - </td> - </tr> + </td> + </tr> - <tr> - <td><p>Size</p></td> - <td> - <p>This is the size of the Fill Value field in bytes. This field - is not present if the Version field is greater than 1, - and the Fill Value Defined flag is set to 0. - </p> - </td> - </tr> + <tr> + <td><p>Size</p></td> + <td> + <p>This is the size of the Fill Value field in bytes. This field + is not present if the Version field is greater than 1, and the Fill + Value Defined flag is set to 0.</p> + </td> + </tr> - <tr> - <td><p>Fill Value</p></td> - <td> - <p>The fill value. The bytes of the fill value are interpreted - using the same datatype as for the dataset. This field is - not present if the Version field is greater than 1, - and the Fill Value Defined flag is set to 0. - </p> - </td> - </tr> - </table> - </div> + <tr> + <td><p>Fill Value</p></td> + <td> + <p>The fill value. The bytes of the fill value are interpreted + using the same datatype as for the dataset. This field is not + present if the Version field is greater than 1, and the Fill Value + Defined flag is set to 0.</p> + </td> + </tr> + </table> +</div> <br /> -<h4><a name="LinkMessage">IV.A.2.g. The Link Message</a></h4> +<h4> + <a name="LinkMessage">IV.A.2.g. The Link Message</a> +</h4> - <!-- start msgdesc table --> - <center> +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Link</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0006</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies </td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may be - repeated. </td></tr> - <tr><td><b>Description:</b></td> - <td><p>This message encodes the information for a link in a - group’s object header, when the group is storing its links - “compactly”, or in the group’s fractal heap, - when the group is storing its links “densely”.</p> - <p>A group is storing its links compactly when the fractal heap - address in the <em><a href="#LinkInfoMessage">Link Info - Message</a></em> is set to the “undefined address” - value.</p></td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Link Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Flags</td> - <td>Link type <em>(optional)</em></td> - <td bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - <tr> - <td colspan="4"><br />Creation Order <em>(8 bytes, optional)</em><br /><br /></td> - </tr> - <tr> - <td>Link Name Character Set <em>(optional)</em></td> - <td>Length of Link Name (variable size)</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - <tr> - <td colspan="4">Link Name (variable size)</td> - </tr> - <tr> - <td colspan="4"><br />Link Information (variable size)<br /><br /></td> - </tr> - </table> - </div> + <tr> + <td colspan="2"><b>Header Message Name:</b> Link</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0006</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td><p>This message encodes the information for a link in a + group’s object header, when the group is storing its links + “compactly”, or in the group’s fractal heap, when + the group is storing its links “densely”.</p> + <p> + A group is storing its links compactly when the fractal heap + address in the <em><a href="#LinkInfoMessage">Link Info + Message</a></em> is set to the “undefined address” value. + </p></td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number for this message. This document describes version 1.</p> - </td> - </tr> - - <tr> - <td><p>Flags</p></td> - <td><p>This field contains information about the link and controls - the presence of other fields below. +<div align="center"> + <table class="format"> + <caption>Link Message</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td>Link type <em>(optional)</em></td> + <td bgcolor="#DDDDDD"><em>This space inserted only to align + table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Creation Order <em>(8 bytes, + optional)</em><br /> + <br /></td> + </tr> + <tr> + <td>Link Name Character Set <em>(optional)</em></td> + <td>Length of Link Name (variable size)</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4">Link Name (variable size)</td> + </tr> + <tr> + <td colspan="4"><br />Link Information (variable size)<br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document + describes version 1.</p></td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This field contains information about the link and + controls the presence of other fields below.</p> <table class="list"> <tr> - <th width="20%" align="center">Bits</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0-1</code></td> - <td>Determines the size of the <em>Length of Link Name</em> - field. - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>The size of the <em>Length of Link Name</em> - field is 1 byte. - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td>The size of the <em>Length of Link Name</em> - field is 2 bytes. - </td> - </tr> - <tr> - <td align="center"><code>2</code></td> - <td>The size of the <em>Length of Link Name</em> - field is 4 bytes. - </td> - </tr> - <tr> - <td align="center"><code>3</code></td> - <td>The size of the <em>Length of Link Name</em> - field is 8 bytes. - </td> - </tr> - </table> - </td> - </tr> - <tr> - <td align="center"><code>2</code></td> - <td>Creation Order Field Present: if set, the <em>Creation - Order</em> field is present. If not set, creation order - information is not stored for links in this group. - </td> - </tr> - <tr> - <td align="center"><code>3</code></td> - <td>Link Type Field Present: if set, the link is not - a hard link and the <em>Link Type</em> field is present. - If not set, the link is a hard link. - </td> - </tr> - <tr> - <td align="center"><code>4</code></td> - <td>Link Name Character Set Field Present: if set, the - link name is not represented with the ASCII character - set and the <em>Link Name Character Set</em> field is - present. If not set, the link name is represented with - the ASCII character set. - </td> - </tr> - <tr> - <td align="center"><code>5-7</code></td> - <td>Reserved (zero). - </td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>Link type</p></td> - <td><p>This is the link class type and can be one of the following - values: + <th width="20%" align="center">Bits</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0-1</code></td> + <td>Determines the size of the <em>Length of Link Name</em> + field. + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>The size of the <em>Length of Link Name</em> field is + 1 byte. + </td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The size of the <em>Length of Link Name</em> field is + 2 bytes. + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>The size of the <em>Length of Link Name</em> field is + 4 bytes. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>The size of the <em>Length of Link Name</em> field is + 8 bytes. + </td> + </tr> + </table> + </td> + </tr> + <tr> + <td align="center"><code>2</code></td> + <td>Creation Order Field Present: if set, the <em>Creation + Order</em> field is present. If not set, creation order information + is not stored for links in this group. + </td> + </tr> + <tr> + <td align="center"><code>3</code></td> + <td>Link Type Field Present: if set, the link is not a hard + link and the <em>Link Type</em> field is present. If not set, the + link is a hard link. + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>Link Name Character Set Field Present: if set, the link + name is not represented with the ASCII character set and the <em>Link + Name Character Set</em> field is present. If not set, the link name + is represented with the ASCII character set. + </td> + </tr> + <tr> + <td align="center"><code>5-7</code></td> + <td>Reserved (zero).</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Link type</p></td> + <td><p>This is the link class type and can be one of the + following values:</p> <table class="list"> <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>A hard link (should never be stored in the file) - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td>A soft link. - </td> - </tr> - <tr> - <td align="center"><code>2-63</code></td> - <td>Reserved for future HDF5 internal use. - </td> - </tr> - <tr> - <td align="center"><code>64</code></td> - <td>An external link. - </td> - </tr> - <tr> - <td align="center"><code>65-255</code></td> - <td>Reserved, but available for user-defined link types. - </td> - </tr> - </table></p> - - <p>This field is present if bit 3 of <em>Flags</em> is set.</p> - </td> - </tr> - - <tr> - <td><p>Creation Order</p></td> - <td><p>This 64-bit value is an index of the link’s creation time within - the group. Values start at 0 when the group is created an increment - by one for each link added to the group. Removing a link from a - group does not change existing links’ creation order field. - </p> - <p>This field is present if bit 2 of <em>Flags</em> is set.</p> - </td> - </tr> - - <tr> - <td><p>Link Name Character Set</p></td> - <td><p>This is the character set for encoding the link’s name: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>ASCII character set encoding (this should never be stored - in the file) - </td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>UTF-8 character set encoding - </td> - </tr> - </table></p> - - <p>This field is present if bit 4 of <em>Flags</em> is set.</p> - </td> - </tr> - - <tr> - <td><p>Length of link name</p></td> - <td><p>This is the length of the link’s name. The size of this field - depends on bits 0 and 1 of <em>Flags</em>.</p> - </td> - </tr> - - <tr> - <td><p>Link name</p></td> - <td><p>This is the name of the link, non-NULL terminated.</p> - </td> - </tr> - - <tr> - <td><p>Link information</p></td> - <td><p>The format of this field depends on the <em>link type</em>.</p> - <p>For <b>hard</b> links, the field is formatted as follows: - - <table class="list"> - <tr> - <td width="20%"><i>Size of Offsets</i> bytes:</td> - <td width="80%">The address of the object header for the object that the - link points to. - </td> - </tr> - </table> - </p> - - <p> - For <b>soft</b> links, the field is formatted as follows: - - <table class="list"> - <tr> - <td width="20%">Bytes 1-2:</td> - <td width="80%">Length of soft link value.</td> - </tr> - <tr> - <td><em>Length of soft link value</em> bytes:</td> - <td>A non-NULL-terminated string storing the value of the - soft link. - </td> - </tr> - </table> - </p> - - <p> - For <b>external</b> links, the field is formatted as follows: - - <table class="list"> - <tr> - <td width="20%">Bytes 1-2:</td> - <td width="80%">Length of external link value.</td> - </tr> - <tr> - <td><em>Length of external link value</em> bytes:</td> - <td>The first byte contains the version number in the - upper 4 bits and flags in the lower 4 bits for the external - link. Both version and flags are defined to be zero in - this document. The remaining bytes consist of two - NULL-terminated strings, with no padding between them. - The first string is the name of the HDF5 file containing - the object linked to and the second string is the full path - to the object linked to, within the HDF5 file’s - group hierarchy. - </td> - </tr> - </table> - </p> - - <p> - For <b>user-defined</b> links, the field is formatted as follows: - - <table class="list"> - <tr> - <td width="20%">Bytes 1-2:</td> - <td width="80%">Length of user-defined data.</td> - </tr> - <tr> - <td><em>Length of user-defined link value</em> bytes:</td> - <td>The data supplied for the user-defined link type.</td> - </tr> - </table> - </p> - - </td> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>A hard link (should never be stored in the file)</td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>A soft link.</td> + </tr> + <tr> + <td align="center"><code>2-63</code></td> + <td>Reserved for future HDF5 internal use.</td> + </tr> + <tr> + <td align="center"><code>64</code></td> + <td>An external link.</td> + </tr> + <tr> + <td align="center"><code>65-255</code></td> + <td>Reserved, but available for user-defined link types.</td> + </tr> + </table> + <p></p> + + <p> + This field is present if bit 3 of <em>Flags</em> is set. + </p></td> </tr> - </table> - </div> + + <tr> + <td><p>Creation Order</p></td> + <td><p>This 64-bit value is an index of the link’s + creation time within the group. Values start at 0 when the group is + created an increment by one for each link added to the group. + Removing a link from a group does not change existing links’ + creation order field.</p> + <p> + This field is present if bit 2 of <em>Flags</em> is set. + </p></td> + </tr> + + <tr> + <td><p>Link Name Character Set</p></td> + <td><p>This is the character set for encoding the + link’s name:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding (this should never be stored + in the file)</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding</td> + </tr> + </table> + <p></p> + + <p> + This field is present if bit 4 of <em>Flags</em> is set. + </p></td> + </tr> + + <tr> + <td><p>Length of link name</p></td> + <td><p> + This is the length of the link’s name. The size of this field + depends on bits 0 and 1 of <em>Flags</em>. + </p></td> + </tr> + + <tr> + <td><p>Link name</p></td> + <td><p>This is the name of the link, non-NULL terminated.</p></td> + </tr> + + <tr> + <td><p>Link information</p></td> + <td><p> + The format of this field depends on the <em>link type</em>. + </p> + <p> + For <b>hard</b> links, the field is formatted as follows: + + </p> + <table class="list"> + <tr> + <td width="20%"><i>Size of Offsets</i> bytes:</td> + <td width="80%">The address of the object header for the + object that the link points to.</td> + </tr> + </table> + <p></p> + + <p> + For <b>soft</b> links, the field is formatted as follows: + + </p> + <table class="list"> + <tr> + <td width="20%">Bytes 1-2:</td> + <td width="80%">Length of soft link value.</td> + </tr> + <tr> + <td><em>Length of soft link value</em> bytes:</td> + <td>A non-NULL-terminated string storing the value of the + soft link.</td> + </tr> + </table> + <p></p> + + <p> + For <b>external</b> links, the field is formatted as follows: + + </p> + <table class="list"> + <tr> + <td width="20%">Bytes 1-2:</td> + <td width="80%">Length of external link value.</td> + </tr> + <tr> + <td><em>Length of external link value</em> bytes:</td> + <td>The first byte contains the version number in the upper 4 + bits and flags in the lower 4 bits for the external link. Both + version and flags are defined to be zero in this document. The + remaining bytes consist of two NULL-terminated strings, with no + padding between them. The first string is the name of the HDF5 + file containing the object linked to and the second string is the + full path to the object linked to, within the HDF5 file’s + group hierarchy.</td> + </tr> + </table> + <p></p> + + <p> + For <b>user-defined</b> links, the field is formatted as follows: + + </p> + <table class="list"> + <tr> + <td width="20%">Bytes 1-2:</td> + <td width="80%">Length of user-defined data.</td> + </tr> + <tr> + <td><em>Length of user-defined link value</em> bytes:</td> + <td>The data supplied for the user-defined link type.</td> + </tr> + </table> + <p></p></td> + </tr> + </table> +</div> <br /> -<h4><a name="ExternalFileListMessage">IV.A.2.h. The Data Storage - -External Data Files Message</a></h4> +<h4> + <a name="ExternalFileListMessage">IV.A.2.h. The Data Storage - + External Data Files Message</a> +</h4> - <!-- start msgdesc table --> - <center> +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> External - Data Files</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0007</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>The external data storage message indicates that the data - for an object is stored outside the HDF5 file. The filename of - the object is stored as a Universal Resource Location (URL) of - the actual filename containing the data. An external file list - record also contains the byte offset of the start of the data - within the file and the amount of space reserved in the file - for that data.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - External File List Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td colspan="3">Reserved (zero)</td> - </tr> - - <tr> - <td colspan="2">Allocated Slots</td> - <td colspan="2">Used Slots</td> - </tr> - - <tr> - <td colspan="4"><br />Heap Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Slot Definitions...<br /><br /></td> - </tr> - </table> + <tr> + <td colspan="2"><b>Header Message Name:</b> External Data Files</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0007</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>The external data storage message indicates that the data + for an object is stored outside the HDF5 file. The filename of the + object is stored as a Universal Resource Location (URL) of the + actual filename containing the data. An external file list record + also contains the byte offset of the start of the data within the + file and the amount of space reserved in the file for that data.</td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption>External File List Message</caption> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> - </div> + <tr> + <td>Version</td> + <td colspan="3">Reserved (zero)</td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td> - <p>The version number information is used for changes in the format of - External Data Storage Message and is described here: - <table class="list"> - <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> - </tr> - <tr> - <td align="center"><code>0</code></td> - <td>Never used.</td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td>The current version used by the library.</td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>Allocated Slots</p></td> - <td> - <p>The total number of slots allocated in the message. Its value must be at least as - large as the value contained in the Used Slots field. (The current library simply - uses the number of Used Slots for this message)</p> - </td> - </tr> - - <tr> - <td><p>Used Slots</p></td> - <td> - <p>The number of initial slots which contains valid information.</p> - </td> - </tr> - - <tr> - <td><p>Heap Address</p></td> - <td> - <p>This is the address of a local heap which contains the names for the external - files (The local heap information can be found in Disk Format Level 1D in this - document). The name at offset zero in the heap is always the empty string.</p> - </td> - </tr> - - <tr> - <td><p>Slot Definitions</p></td> - <td> - <p>The slot definitions are stored in order according to the array addresses they - represent.</p> - </td> - </tr> - - </table> - </div> + <tr> + <td colspan="2">Allocated Slots</td> + <td colspan="2">Used Slots</td> + </tr> - <br /> - <div align="center"> - <table class="format"> - <caption> - External File List Slot - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td colspan="4"><br />Name Offset in Local Heap<sup>L</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Offset in External Data File<sup>L</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Data Size in External File<sup>L</sup><br /><br /></td> - </tr> - </table> + <tr> + <td colspan="4"><br />Heap Address<sup>O</sup><br /> + <br /></td> + </tr> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td colspan="4"><br />Slot Definitions...<br /> + <br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Name Offset in Local Heap</p></td> - <td> - <p>The byte offset within the local name heap for the name - of the file. File names are stored as a URL which has a - protocol name, a host name, a port number, and a file - name: - <code><em>protocol</em>:<em>port</em>//<em>host</em>/<em>file</em></code>. - If the protocol is omitted then “file:” is assumed. If - the port number is omitted then a default port for that - protocol is used. If both the protocol and the port - number are omitted then the colon can also be omitted. If - the double slash and host name are omitted then - “localhost” is assumed. The file name is the only - mandatory part, and if the leading slash is missing then - it is relative to the application’s current working - directory (the use of relative names is not - recommended). - </p> - </td> - </tr> - - <tr> - <td><p>Offset in External Data File</p></td> - <td> - <p>This is the byte offset to the start of the data in the - specified file. For files that contain data for a single - dataset this will usually be zero.</p> - </td> - </tr> - - <tr> - <td><p>Data Size in External File</p></td> - <td> - <p>This is the total number of bytes reserved in the - specified file for raw data storage. For a file that - contains exactly one complete dataset which is not - extendable, the size will usually be the exact size of the - dataset. However, by making the size larger one allows - HDF5 to extend the dataset. The size can be set to a value - larger than the entire file since HDF5 will read zeroes - past the end of the file without failing.</p> - </td> - </tr> - </table> - </div> - - -<br /> -<h4><a name="LayoutMessage">IV.A.2.i. The Data Storage - Layout -Message</a></h4> - - <!-- start msgdesc table --> - <center> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the + format of External Data Storage Message and is described here:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>The current version used by the library.</td> + </tr> + </table> + <p></p> + + </td> + </tr> + + <tr> + <td><p>Allocated Slots</p></td> + <td> + <p>The total number of slots allocated in the message. Its value + must be at least as large as the value contained in the Used Slots + field. (The current library simply uses the number of Used Slots + for this message)</p> + </td> + </tr> + + <tr> + <td><p>Used Slots</p></td> + <td> + <p>The number of initial slots which contains valid information.</p> + </td> + </tr> + + <tr> + <td><p>Heap Address</p></td> + <td> + <p>This is the address of a local heap which contains the names + for the external files (The local heap information can be found in + Disk Format Level 1D in this document). The name at offset zero in + the heap is always the empty string.</p> + </td> + </tr> + + <tr> + <td><p>Slot Definitions</p></td> + <td> + <p>The slot definitions are stored in order according to the + array addresses they represent.</p> + </td> + </tr> + + </table> +</div> + +<br /> +<div align="center"> + <table class="format"> + <caption>External File List Slot</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Name Offset in Local Heap<sup>L</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Offset in External Data File<sup>L</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data Size in External File<sup>L</sup><br /> + <br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘L’ in the + above table are of the size specified in “Size of + Lengths” field in the superblock.)</td> + </tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Name Offset in Local Heap</p></td> + <td> + <p> + The byte offset within the local name heap for the name of the + file. File names are stored as a URL which has a protocol name, a + host name, a port number, and a file name: + <code> + <em>protocol</em>:<em>port</em>//<em>host</em>/<em>file</em> + </code> + . If the protocol is omitted then “file:” is assumed. + If the port number is omitted then a default port for that protocol + is used. If both the protocol and the port number are omitted then + the colon can also be omitted. If the double slash and host name + are omitted then “localhost” is assumed. The file name + is the only mandatory part, and if the leading slash is missing + then it is relative to the application’s current working + directory (the use of relative names is not recommended). + </p> + </td> + </tr> + + <tr> + <td><p>Offset in External Data File</p></td> + <td> + <p>This is the byte offset to the start of the data in the + specified file. For files that contain data for a single dataset + this will usually be zero.</p> + </td> + </tr> + + <tr> + <td><p>Data Size in External File</p></td> + <td> + <p>This is the total number of bytes reserved in the specified + file for raw data storage. For a file that contains exactly one + complete dataset which is not extendable, the size will usually be + the exact size of the dataset. However, by making the size larger + one allows HDF5 to extend the dataset. The size can be set to a + value larger than the entire file since HDF5 will read zeroes past + the end of the file without failing.</p> + </td> + </tr> + </table> +</div> + + +<br /> +<h4> + <a name="LayoutMessage">IV.A.2.i. The Data Storage - Layout Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Data Storage - - Layout</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0008</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies</td></tr> - <tr><td colspan="2"><b>Status:</b> Required for datasets; may not - be repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>Data layout describes how the elements of a multi-dimensional - array are stored in the HDF5 file. Three types of data layout - are supported: - <ol> - <li>Contiguous: The array is stored in one contiguous area of - the file. This layout requires that the size of the array be - constant: data manipulations such as chunking, compression, - checksums, or encryption are not permitted. The message stores - the total storage size of the array. The offset of an element - from the beginning of the storage area is computed as in a C - array.</li> - <li>Chunked: The array domain is regularly decomposed into - chunks, and each chunk is allocated and stored separately. This - layout supports arbitrary element traversals, compression, - encryption, and checksums. (these features are described - in other messages). The message stores the size of a chunk - instead of the size of the entire array; the storage size of - the entire array can be calculated by traversing the B-tree - that stores the chunk addresses.</li> - <li>Compact: The array is stored in one contiguous block, as - part of this object header message.</li> - </ol></td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Data Layout Message (Versions 1 and 2) - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Dimensionality</td> - <td>Layout Class</td> - <td>Reserved <em>(zero)</em></td> - </tr> - - <tr> - <td colspan="4">Reserved <em>(zero)</em></td> - </tr> - - <tr> - <td colspan="4"><br />Data Address<sup>O</sup> <em>(optional)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4">Dimension 0 Size</td> - </tr> - - <tr> - <td colspan="4">Dimension 1 Size</td> - </tr> - - <tr> - <td colspan="4">...</td> - </tr> - - <tr> - <td colspan="4">Dimension #n Size</td> - </tr> - - <tr> - <td colspan="4">Dataset Element Size <em>(optional)</em></td> - </tr> - - <tr> - <td colspan="4">Compact Data Size <em>(optional)</em></td> - </tr> - - <tr> - <td colspan="4"><br />Compact Data... <em>(variable size, optional)</em><br /><br /></td> - </tr> - </table> + <tr> + <td colspan="2"><b>Header Message Name:</b> Data Storage - + Layout</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0008</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Required for datasets; may not be + repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>Data layout describes how the elements of a + multi-dimensional array are stored in the HDF5 file. Three types of + data layout are supported: + <ol> + <li>Contiguous: The array is stored in one contiguous area of + the file. This layout requires that the size of the array be + constant: data manipulations such as chunking, compression, + checksums, or encryption are not permitted. The message stores the + total storage size of the array. The offset of an element from the + beginning of the storage area is computed as in a C array.</li> + <li>Chunked: The array domain is regularly decomposed into + chunks, and each chunk is allocated and stored separately. This + layout supports arbitrary element traversals, compression, + encryption, and checksums. (these features are described in other + messages). The message stores the size of a chunk instead of the + size of the entire array; the storage size of the entire array can + be calculated by traversing the B-tree that stores the chunk + addresses.</li> + <li>Compact: The array is stored in one contiguous block, as + part of this object header message.</li> + </ol> + </td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption>Data Layout Message (Versions 1 and 2)</caption> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> - </div> + <tr> + <td>Version</td> + <td>Dimensionality</td> + <td>Layout Class</td> + <td>Reserved <em>(zero)</em></td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td> - <p>The version number information is used for changes in the format of the data - layout message and is described here: - <table class="list"> - <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Never used.</td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>Used by version 1.4 and before of the library to encode layout information. - Data space is always allocated when the data set is created.</td> - </tr> - - <tr> - <td align="center"><code>2</code></td> - <td>Used by version 1.6.x of the library to encode layout information. - Data space is allocated only when it is necessary.</td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Dimensionality</p></td> - <td><p>An array has a fixed dimensionality. This field - specifies the number of dimension size fields later in the - message. The value stored for chunked storage is 1 greater than - the number of dimensions in the dataset’s dataspace. - For example, 2 is stored for a 1 dimensional dataset. - </p> - </td> - </tr> - - <tr> - <td><p>Layout Class</p></td> - <td><p>The layout class specifies the type of storage for the data - and how the other fields of the layout message are to be - interpreted. - - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Compact Storage - </td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>Contiguous Storage - </td> - </tr> - - <tr> - <td align="center"><code>2</code></td> - <td>Chunked Storage - </td> - </tr> - </table> - </p> - </td> - </tr> - - <tr> - <td><p>Data Address</p></td> - <td><p>For contiguous storage, this is the address of the raw - data in the file. For chunked storage this is the address - of the v1 B-tree that is used to look up the addresses of the - chunks. This field is not present for compact storage. - If the version for this message is greater than 1, the address - may have the “undefined address” value, to indicate that - storage has not yet been allocated for this array.</p> - </td> - </tr> - - <tr> - <td><p>Dimension #n Size</p></td> - <td><p>For contiguous and compact storage the dimensions define - the entire size of the array while for chunked storage they define - the size of a single chunk. In all cases, they are in units of - array elements (not bytes). The first dimension stored in the list - of dimensions is the slowest changing dimension and the last - dimension stored is the fastest changing dimension. - </p> - </td> - </tr> - - <tr> - <td><p>Dataset Element Size</p></td> - <td><p>The size of a dataset element, in bytes. This field is only - present for chunked storage. - </p> - </td> - </tr> - - <tr> - <td><p>Compact Data Size</p></td> - <td><p>This field is only present for compact data storage. - It contains the size of the raw data for the dataset array, in - bytes.</p> - </td> - </tr> + <tr> + <td colspan="4">Reserved <em>(zero)</em></td> + </tr> - <tr> - <td><p>Compact Data</p></td> - <td><p>This field is only present for compact data storage. - It contains the raw data for the dataset array.</p> - </td> - </tr> - </table> - </div> + <tr> + <td colspan="4"><br />Data Address<sup>O</sup> <em>(optional)</em><br /> + <br /></td> + </tr> - <br /> - <p>Version 3 of this message re-structured the format into specific - properties that are required for each layout class.</p> - - - <div align="center"> - <table class="format"> - <caption> - <b>Data Layout Message (Version 3)</b> - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Layout Class</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Properties <em>(variable size)</em><br /><br /></td> - </tr> - </table> - </div> + <tr> + <td colspan="4">Dimension 0 Size</td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td> - <p>The version number information is used for changes in the format of layout message - and is described here: - <table class="list"> - <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>3</code></td> - <td>Used by the version 1.6.3 and later of the library to store properties - for each layout class.</td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Layout Class</p></td> - <td><p>The layout class specifies the type of storage for the data - and how the other fields of the layout message are to be - interpreted. - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Compact Storage - </td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>Contiguous Storage - </td> - </tr> - - <tr> - <td align="center"><code>2</code></td> - <td>Chunked Storage - </td> - </tr> - </table> - </p> - </td> - </tr> - - <tr> - <td><p>Properties</p></td> - <td><p>This variable-sized field encodes information specific to each - layout class and is described below. If there is no property - information specified for a layout class, the size of this field - is zero bytes.</p></td> - </tr> - </table> - </div> + <tr> + <td colspan="4">Dimension 1 Size</td> + </tr> - <br /> - <p>Class-specific information for compact layout (Class 0): (Note: The dimensionality information - is in the Dataspace message)</p> - - - <div align="center"> - <table class="format"> - <caption> - Compact Storage Property Description - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td colspan="2">Size</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Raw Data... <em>(variable size)</em><br /><br /></td> - </tr> - </table> - </div> + <tr> + <td colspan="4">...</td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Size</p></td> - <td><p>This field contains the size of the raw data for the dataset - array, in bytes. - </p> - </td> - </tr> - - <tr> - <td><p>Raw Data</p></td> - <td><p>This field contains the raw data for the dataset array.</p></td> - </tr> - </table> - </div> + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + <tr> + <td colspan="4">Dataset Element Size <em>(optional)</em></td> + </tr> - <br /> - <p>Class-specific information for contiguous layout (Class 1): (Note: The dimensionality information - is in the Dataspace message)</p> - - - <div align="center"> - <table class="format"> - <caption> - Contiguous Storage Property Description - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Size<sup>L</sup><br /><br /></td> - </tr> - </table> + <tr> + <td colspan="4">Compact Data Size <em>(optional)</em></td> + </tr> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td colspan="4"><br />Compact Data... <em>(variable size, + optional)</em><br /> + <br /></td> + </tr> + </table> + + <table class="note"> <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Address</p></td> - <td><p>This is the address of the raw data in the file. - The address may have the “undefined address” value, to indicate - that storage has not yet been allocated for this array.</p></td> - </tr> - - <tr> - <td><p>Size</p></td> - <td><p>This field contains the size allocated to store the raw data, - in bytes. - </p> - </td> - </tr> - </table> - </div> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the + format of the data layout message and is described here:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> - <br /> - <p>Class-specific information for chunked layout (Class 2):</p> - - - <div align="center"> - <table class="format"> - <caption> - Chunked Storage Property Description - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Dimensionality</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td colspan="4">Dimension 0 Size</td> - </tr> - - <tr> - <td colspan="4">Dimension 1 Size</td> - </tr> - - <tr> - <td colspan="4">...</td> - </tr> - - <tr> - <td colspan="4">Dimension #n Size</td> - </tr> - - <tr> - <td colspan="4">Dataset Element Size</td> - </tr> - </table> + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Used by version 1.4 and before of the library to encode + layout information. Data space is always allocated when the data + set is created.</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Used by version 1.6.x of the library to encode layout + information. Data space is allocated only when it is necessary.</td> + </tr> + </table> + <p></p> + </td> + </tr> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <td><p>Dimensionality</p></td> + <td><p>An array has a fixed dimensionality. This field + specifies the number of dimension size fields later in the message. + The value stored for chunked storage is 1 greater than the number + of dimensions in the dataset’s dataspace. For example, 2 is + stored for a 1 dimensional dataset.</p></td> + </tr> - </div> + <tr> + <td><p>Layout Class</p></td> + <td><p>The layout class specifies the type of storage for + the data and how the other fields of the layout message are to be + interpreted.</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Dimensionality</p></td> - <td><p>A chunk has a fixed dimensionality. This field specifies - the number of dimension size fields later in the message.</p></td> - </tr> - - <tr> - <td><p>Address</p></td> - <td><p>This is the address of the v1 B-tree that is used to look up the - addresses of the chunks that actually store portions of the array - data. The address may have the “undefined address” value, to - indicate that storage has not yet been allocated for this array.</p></td> - </tr> - - <tr> - <td><p>Dimension #n Size</p></td> - <td><p>These values define the dimension size of a single chunk, in - units of array elements (not bytes). The first dimension stored in - the list of dimensions is the slowest changing dimension and the - last dimension stored is the fastest changing dimension. - </p> - </td> - </tr> - - <tr> - <td><p>Dataset Element Size</p></td> - <td><p>The size of a dataset element, in bytes. - </p> - </td> - </tr> - </table> - </div> + <tr> + <td align="center"><code>0</code></td> + <td>Compact Storage</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Contiguous Storage</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Chunked Storage</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Data Address</p></td> + <td><p>For contiguous storage, this is the address of the + raw data in the file. For chunked storage this is the address of + the v1 B-tree that is used to look up the addresses of the chunks. + This field is not present for compact storage. If the version for + this message is greater than 1, the address may have the + “undefined address” value, to indicate that storage has + not yet been allocated for this array.</p></td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td><p>For contiguous and compact storage the dimensions + define the entire size of the array while for chunked storage they + define the size of a single chunk. In all cases, they are in units + of array elements (not bytes). The first dimension stored in the + list of dimensions is the slowest changing dimension and the last + dimension stored is the fastest changing dimension.</p></td> + </tr> + + <tr> + <td><p>Dataset Element Size</p></td> + <td><p>The size of a dataset element, in bytes. This field + is only present for chunked storage.</p></td> + </tr> + + <tr> + <td><p>Compact Data Size</p></td> + <td><p>This field is only present for compact data storage. + It contains the size of the raw data for the dataset array, in + bytes.</p></td> + </tr> + + <tr> + <td><p>Compact Data</p></td> + <td><p>This field is only present for compact data storage. + It contains the raw data for the dataset array.</p></td> + </tr> + </table> +</div> <br /> -<h4><a name="BogusMessage">IV.A.2.j. The Bogus Message</a></h4> +<p>Version 3 of this message re-structured the format into specific + properties that are required for each layout class.</p> - <!-- start msgdesc table --> - <center> + +<div align="center"> + <table class="format"> + <caption> + <b>Data Layout Message (Version 3)</b> + </caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Layout Class</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Properties <em>(variable size)</em><br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td> + <p>The version number information is used for changes in the + format of layout message and is described here:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Used by the version 1.6.3 and later of the library to + store properties for each layout class.</td> + </tr> + </table> + <p></p> + </td> + </tr> + + <tr> + <td><p>Layout Class</p></td> + <td><p>The layout class specifies the type of storage for + the data and how the other fields of the layout message are to be + interpreted.</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Compact Storage</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Contiguous Storage</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Chunked Storage</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Properties</p></td> + <td><p>This variable-sized field encodes information + specific to each layout class and is described below. If there is + no property information specified for a layout class, the size of + this field is zero bytes.</p></td> + </tr> + </table> +</div> + +<br /> +<p>Class-specific information for compact layout (Class 0): (Note: + The dimensionality information is in the Dataspace message)</p> + + +<div align="center"> + <table class="format"> + <caption>Compact Storage Property Description</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="2">Size</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Raw Data... <em>(variable size)</em><br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Size</p></td> + <td><p>This field contains the size of the raw data for the + dataset array, in bytes.</p></td> + </tr> + + <tr> + <td><p>Raw Data</p></td> + <td><p>This field contains the raw data for the dataset + array.</p></td> + </tr> + </table> +</div> + + +<br /> +<p>Class-specific information for contiguous layout (Class 1): + (Note: The dimensionality information is in the Dataspace message)</p> + + +<div align="center"> + <table class="format"> + <caption>Contiguous Storage Property Description</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Size<sup>L</sup><br /> + <br /></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + <tr> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This is the address of the raw data in the file. The + address may have the “undefined address” value, to + indicate that storage has not yet been allocated for this array.</p></td> + </tr> + + <tr> + <td><p>Size</p></td> + <td><p>This field contains the size allocated to store the + raw data, in bytes.</p></td> + </tr> + </table> +</div> + + +<br /> +<p>Class-specific information for chunked layout (Class 2):</p> + + +<div align="center"> + <table class="format"> + <caption>Chunked Storage Property Description</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Dimensionality</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Address<sup>O</sup><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4">Dimension 0 Size</td> + </tr> + + <tr> + <td colspan="4">Dimension 1 Size</td> + </tr> + + <tr> + <td colspan="4">...</td> + </tr> + + <tr> + <td colspan="4">Dimension #n Size</td> + </tr> + + <tr> + <td colspan="4">Dataset Element Size</td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> + +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Dimensionality</p></td> + <td><p>A chunk has a fixed dimensionality. This field + specifies the number of dimension size fields later in the message.</p></td> + </tr> + + <tr> + <td><p>Address</p></td> + <td><p>This is the address of the v1 B-tree that is used to + look up the addresses of the chunks that actually store portions of + the array data. The address may have the “undefined + address” value, to indicate that storage has not yet been + allocated for this array.</p></td> + </tr> + + <tr> + <td><p>Dimension #n Size</p></td> + <td><p>These values define the dimension size of a single + chunk, in units of array elements (not bytes). The first dimension + stored in the list of dimensions is the slowest changing dimension + and the last dimension stored is the fastest changing dimension.</p></td> + </tr> + + <tr> + <td><p>Dataset Element Size</p></td> + <td><p>The size of a dataset element, in bytes.</p></td> + </tr> + </table> +</div> + +<br /> +<h4> + <a name="BogusMessage">IV.A.2.j. The Bogus Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Bogus</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0009</td></tr> - <tr><td colspan="2"><b>Length:</b> 4 bytes</td></tr> - <tr><td colspan="2"><b>Status:</b> For testing only; should never - be stored in a valid file.</td></tr> - <tr><td><b>Description:</b></td> - <td>This message is used for testing the HDF5 Library’s - response to an “unknown” message type and should - never be encountered in a valid HDF5 file.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Bogus Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td colspan="4">Bogus Value</td> - </tr> - </table> - </div> + <tr> + <td colspan="2"><b>Header Message Name:</b> Bogus</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0009</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> 4 bytes</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> For testing only; should never be + stored in a valid file.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>This message is used for testing the HDF5 Library’s + response to an “unknown” message type and should never + be encountered in a valid HDF5 file.</td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Bogus Value</p></td> - <td> - <p>This value should always be: <code>0xdeadbeef</code>.</p> - </td> - </tr> - </table> - </div> +<div align="center"> + <table class="format"> + <caption>Bogus Message</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Bogus Value</td> + </tr> + </table> +</div> <br /> -<h4><a name="GroupInfoMessage">IV.A.2.k. The Group Info Message -</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Bogus Value</p></td> + <td> + <p> + This value should always be: + <code>0xdeadbeef</code> + . + </p> + </td> + </tr> + </table> +</div> + +<br /> +<h4> + <a name="GroupInfoMessage">IV.A.2.k. The Group Info Message </a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Group Info</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x000A</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td><p>This message stores information for the constants defining - a “new style” group’s behavior. Constant - information will be stored in this message and variable - information will be stored in the - <a href="#LinkInfoMessage">Link Info</a> message.</p> - <p>Note: the “estimated entry” information below is - used when determining the size of the object header for the - group when it is created.</p></td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Group Info Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Flags</td> - <td colspan="2">Link Phase Change: Maximum Compact Value <em>(optional)</em></td> - </tr> - <tr> - <td colspan="2">Link Phase Change: Minimum Dense Value <em>(optional)</em></td> - <td colspan="2">Estimated Number of Entries <em>(optional)</em></td> - </tr> - <tr> - <td colspan="2">Estimated Link Name Length of Entries <em>(optional)</em></td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <tr> + <td colspan="2"><b>Header Message Name:</b> Group Info</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x000A</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td><p> + This message stores information for the constants defining a + “new style” group’s behavior. Constant + information will be stored in this message and variable information + will be stored in the <a href="#LinkInfoMessage">Link Info</a> + message. + </p> + <p>Note: the “estimated entry” information below is + used when determining the size of the object header for the group + when it is created.</p></td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - </table> - </div> +<div align="center"> + <table class="format"> + <caption>Group Info Message</caption> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number for this message. This document describes version 0.</p> - </td> - </tr> - - <tr> - <td><p>Flags</p></td> - <td><p>This is the group information flag with the following definition: - - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>If set, link phase change values are stored. - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td>If set, the estimated entry information is non-default - and is stored. - </td> - </tr> - <tr> - <td align="center"><code>2-7</code></td> - <td>Reserved</td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Link Phase Change: Maximum Compact Value</p></td> - <td><p>The is the maximum number of links to store “compactly” (in - the group’s object header).</p> - <p>This field is present if bit 0 of <em>Flags</em> is set.</p> - </td> - </tr> - - <tr> - <td><p>Link Phase Change: Minimum Dense Value</p></td> - <td><p>This is the minimum number of links to store “densely” (in - the group’s fractal heap). The fractal heap’s address is - located in the <a href="#LinkInfoMessage">Link Info</a> - message.</p> - <p>This field is present if bit 0 of <em>Flags</em> is set.</p> - </td> - </tr> - - <tr> - <td><p>Estimated Number of Entries</p></td> - <td><p>This is the estimated number of entries in groups.</p> - <p>If this field is not present, the default value of <code>4</code> - will be used for the estimated number of group entries.</p> - <p>This field is present if bit 1 of <em>Flags</em> is set.</p> - </td> - </tr> - - <tr> - <td><p>Estimated Link Name Length of Entries</p></td> - <td><p>This is the estimated length of entry name.</p> - <p>If this field is not present, the default value of <code>8</code> - will be used for the estimated link name length of group entries.</p> - <p>This field is present if bit 1 of <em>Flags</em> is set.</p> - </td> - </tr> + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> - </table> - </div> - </p> + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Link Phase Change: Maximum Compact Value <em>(optional)</em></td> + </tr> + <tr> + <td colspan="2">Link Phase Change: Minimum Dense Value <em>(optional)</em></td> + <td colspan="2">Estimated Number of Entries <em>(optional)</em></td> + </tr> + <tr> + <td colspan="2">Estimated Link Name Length of Entries <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + </table> +</div> <br /> -<h4><a name="FilterMessage">IV.A.2.l. The Data Storage - Filter -Pipeline Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document + describes version 0.</p></td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This is the group information flag with the following + definition:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, link phase change values are stored.</td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, the estimated entry information is non-default + and is stored.</td> + </tr> + <tr> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Link Phase Change: Maximum Compact Value</p></td> + <td><p>The is the maximum number of links to store + “compactly” (in the group’s object header).</p> + <p> + This field is present if bit 0 of <em>Flags</em> is set. + </p></td> + </tr> + + <tr> + <td><p>Link Phase Change: Minimum Dense Value</p></td> + <td><p> + This is the minimum number of links to store “densely” + (in the group’s fractal heap). The fractal heap’s + address is located in the <a href="#LinkInfoMessage">Link Info</a> + message. + </p> + <p> + This field is present if bit 0 of <em>Flags</em> is set. + </p></td> + </tr> + + <tr> + <td><p>Estimated Number of Entries</p></td> + <td><p>This is the estimated number of entries in groups.</p> + <p> + If this field is not present, the default value of + <code>4</code> + will be used for the estimated number of group entries. + </p> + <p> + This field is present if bit 1 of <em>Flags</em> is set. + </p></td> + </tr> + + <tr> + <td><p>Estimated Link Name Length of Entries</p></td> + <td><p>This is the estimated length of entry name.</p> + <p> + If this field is not present, the default value of + <code>8</code> + will be used for the estimated link name length of group entries. + </p> + <p> + This field is present if bit 1 of <em>Flags</em> is set. + </p></td> + </tr> + + </table> +</div> +<p></p> + +<br /> +<h4> + <a name="FilterMessage">IV.A.2.l. The Data Storage - Filter + Pipeline Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> - Data Storage - Filter Pipeline</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x000B</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td><p>This message describes the filter pipeline which should - be applied to the data stream by providing filter identification - numbers, flags, a name, and client data.</p> - <p>This message may be present in the object headers of both - dataset and group objects. For datasets, it specifies the - filters to apply to raw data. For groups, it specifies the - filters to apply to the group’s fractal heap. Currently, - only datasets using chunked data storage use the filter - pipeline on their raw data.</p></td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Filter Pipeline Message - Version 1 - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Number of Filters</td> - <td colspan="2">Reserved (zero)</td> - </tr> - - <tr> - <td colspan="4">Reserved (zero)</td> - </tr> - - <tr> - <td colspan="4"><br />Filter Description List <em>(variable size)</em><br /><br /></td> - </tr> - </table> - </div> + <tr> + <td colspan="2"><b>Header Message Name:</b> Data Storage - + Filter Pipeline</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x000B</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td><p>This message describes the filter pipeline which + should be applied to the data stream by providing filter + identification numbers, flags, a name, and client data.</p> + <p>This message may be present in the object headers of both + dataset and group objects. For datasets, it specifies the filters + to apply to raw data. For groups, it specifies the filters to apply + to the group’s fractal heap. Currently, only datasets using + chunked data storage use the filter pipeline on their raw data.</p></td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number for this message. This table - describes version 1.</p></td> - </tr> - - <tr> - <td><p>Number of Filters</p></td> - <td><p>The total number of filters described in this - message. The maximum possible number of filters in a - message is 32.</p></td> - </tr> - - <tr> - <td><p>Filter Description List</p></td> - <td><p>A description of each filter. A filter description - appears in the next table.</p></td> - </tr> - </table> - </div> +<div align="center"> + <table class="format"> + <caption>Filter Pipeline Message - Version 1</caption> - <br /> - <div align="center"> - <table class="format"> - <caption> - Filter Description - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td colspan="2">Filter Identification Value</td> - <td colspan="2">Name Length</td> - </tr> - - <tr> - <td colspan="2">Flags</td> - <td colspan="2">Number Client Data Values</td> - </tr> - - <tr> - <td colspan="4"><br />Name <em>(variable size, optional)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Client Data <em>(variable size, optional)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4">Padding <em>(variable size, optional)</em></td> - </tr> - </table> - </div> + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Filter Identification Value</p></td> - <td> - <p> - This value, often referred to as a filter identifier, - is designed to be a unique identifier for the filter. - Values from zero through 32,767 are reserved for filters - supported by The HDF Group in the HDF5 Library and for - filters requested and supported by third parties. - Filters supported by The HDF Group are documented immediately - below. Information on 3rd-party filters can be found at - The HDF Group’s - <a href="http://www.hdfgroup.org/services/contributions.html"> - Contributions</a> page.</p> - - <p> - To request a filter identifier, please contact - The HDF Group’s Help Desk at - <img src="Graphics/help.png" valign="middle" height="14" - alt="The HDF Group Help Desk">. - You will be asked to provide the following information:</p> - <ol> - <li>Contact information for the developer requesting the - new identifier</li> - <li>A short description of the new filter</li> - <li>Links to any relevant information, including licensing - information</li> - </ol> - <p> - Values from 32768 to 65535 are reserved for non-distributed uses - (for example, internal company usage) or for application usage - when testing a feature. The HDF Group does not track or document - the use of the filters with identifiers from this range.</p> - - <p> - The filters currently in library version 1.8.0 are - listed below: - - <table class="list"> - <tr> - <th width="20%" align="center">Identification</th> - <th width="15%" align="left">Name</th> - <th width="65%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>N/A</td> - <td>Reserved</td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>deflate</td> - <td>GZIP deflate compression</td> - </tr> - - <tr> - <td align="center"><code>2</code></td> - <td>shuffle</td> - <td>Data element shuffling</td> - </tr> - - <tr> - <td align="center"><code>3</code></td> - <td>fletcher32</td> - <td>Fletcher32 checksum</td> - </tr> - - <tr> - <td align="center"><code>4</code></td> - <td>szip</td> - <td>SZIP compression</td> - </tr> - - <tr> - <td align="center"><code>5</code></td> - <td>nbit</td> - <td>N-bit packing</td> - </tr> - - <tr> - <td align="center"><code>6</code></td> - <td>scaleoffset</td> - <td>Scale and offset encoded values</td> - </tr> - </table> - </p></td> - </tr> - - <tr> - <td><p>Name Length</p></td> - <td><p>Each filter has an optional null-terminated ASCII name - and this field holds the length of the name including the - null termination padded with nulls to be a multiple of - eight. If the filter has no name then a value of zero is - stored in this field.</p></td> - </tr> - - <tr> - <td><p>Flags</p></td> - <td><p>The flags indicate certain properties for a filter. The - bit values defined so far are: - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>If set then the filter is an optional filter. - During output, if an optional filter fails it will be - silently skipped in the pipeline.</td> - </tr> - - <tr> - <td align="center"><code>1-15</code></td> - <td>Reserved (zero)</td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Number of Client Data Values</p></td> - <td><p>Each filter can store integer values to control - how the filter operates. The number of entries in the - <em>Client Data</em> array is stored in this field.</p></td> - </tr> - - <tr> - <td><p>Name</p></td> - <td><p>If the <em>Name Length</em> field is non-zero then it will - contain the size of this field, padded to a multiple of eight. This - field contains a null-terminated, ASCII character - string to serve as a comment/name for the filter.</p></td> - </tr> - - <tr> - <td><p>Client Data</p></td> - <td><p>This is an array of four-byte integers which will be - passed to the filter function. The <em>Client Data Number</em> of - Values determines the number of elements in the array.</p></td> - </tr> - - <tr> - <td><p>Padding</p></td> - <td><p>Four bytes of zeroes are added to the message at this - point if the Client Data Number of Values field contains - an odd number.</p></td> - </tr> - </table> - </div> + <tr> + <td>Version</td> + <td>Number of Filters</td> + <td colspan="2">Reserved (zero)</td> + </tr> - <br /> - <div align="center"> - <table class="format"> - <caption> - Filter Pipeline Message - Version 2 - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Number of Filters</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Filter Description List <em>(variable size)</em><br /><br /></td> - </tr> - </table> - </div> + <tr> + <td colspan="4">Reserved (zero)</td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number for this message. This table - describes version 2.</p></td> - </tr> - - <tr> - <td><p>Number of Filters</p></td> - <td><p>The total number of filters described in this - message. The maximum possible number of filters in a - message is 32.</p></td> - </tr> - - <tr> - <td><p>Filter Description List</p></td> - <td><p>A description of each filter. A filter description - appears in the next table.</p></td> - </tr> - </table> - </div> + <tr> + <td colspan="4"><br />Filter Description List <em>(variable + size)</em><br /> + <br /></td> + </tr> + </table> +</div> - <br /> - <div align="center"> - <table class="format"> - <caption> - Filter Description - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td colspan="2">Filter Identification Value</td> - <td colspan="2">Name Length <em>(optional)</em></td> - </tr> - - <tr> - <td colspan="2">Flags</td> - <td colspan="2">Number Client Data Values</td> - </tr> - - <tr> - <td colspan="4"><br />Name <em>(variable size, optional)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Client Data <em>(variable size, optional)</em><br /><br /></td> - </tr> - </table> - </div> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Filter Identification Value</p></td> - <td> - <p> - This value, often referred to as a filter identifier, - is designed to be a unique identifier for the filter. - Values from zero through 32,767 are reserved for filters - supported by The HDF Group in the HDF5 Library and for - filters requested and supported by third parties. - Filters supported by The HDF Group are documented immediately - below. Information on 3rd-party filters can be found at - The HDF Group’s - <a href="http://www.hdfgroup.org/services/contributions.html"> - Contributions</a> page.</p> - - <p> - To request a filter identifier, please contact - The HDF Group’s Help Desk at - <img src="Graphics/help.png" valign="middle" height="14" - alt="The HDF Group Help Desk">. - You will be asked to provide the following information:</p> - <ol> - <li>Contact information for the developer requesting the - new identifier</li> - <li>A short description of the new filter</li> - <li>Links to any relevant information, including licensing - information</li> - </ol> - <p> - Values from 32768 to 65535 are reserved for non-distributed uses - (for example, internal company usage) or for application usage - when testing a feature. The HDF Group does not track or document - the use of the filters with identifiers from this range.</p> - - <p> - The filters currently in library version 1.8.0 are - listed below: - - <table class="list"> - <tr> - <th width="20%" align="center">Identification</th> - <th width="15%" align="left">Name</th> - <th width="65%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>N/A</td> - <td>Reserved</td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>deflate</td> - <td>GZIP deflate compression</td> - </tr> - - <tr> - <td align="center"><code>2</code></td> - <td>shuffle</td> - <td>Data element shuffling</td> - </tr> - - <tr> - <td align="center"><code>3</code></td> - <td>fletcher32</td> - <td>Fletcher32 checksum</td> - </tr> - - <tr> - <td align="center"><code>4</code></td> - <td>szip</td> - <td>SZIP compression</td> - </tr> - - <tr> - <td align="center"><code>5</code></td> - <td>nbit</td> - <td>N-bit packing</td> - </tr> - - <tr> - <td align="center"><code>6</code></td> - <td>scaleoffset</td> - <td>Scale and offset encoded values</td> - </tr> - </table> - </p></td> - </tr> - - <tr> - <td><p>Name Length</p></td> - <td><p>Each filter has an optional null-terminated ASCII name - and this field holds the length of the name including the - null termination padded with nulls to be a multiple of - eight. If the filter has no name then a value of zero is - stored in this field.</p> - <p>Filters with IDs less than 256 (in other words, filters - that are defined in this format documentation) do not store - the <em>Name Length</em> or <em>Name</em> fields. - </p> - </td> - </tr> - - <tr> - <td><p>Flags</p></td> - <td><p>The flags indicate certain properties for a filter. The - bit values defined so far are: - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>If set then the filter is an optional filter. - During output, if an optional filter fails it will be - silently skipped in the pipeline.</td> - </tr> - - <tr> - <td align="center"><code>1-15</code></td> - <td>Reserved (zero)</td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Number of Client Data Values</p></td> - <td><p>Each filter can store integer values to control - how the filter operates. The number of entries in the - <em>Client Data</em> array is stored in this field.</p></td> - </tr> - - <tr> - <td><p>Name</p></td> - <td><p>If the <em>Name Length</em> field is non-zero then it will - contain the size of this field, <em>not</em> padded to a multiple - of eight. This field contains a <em>non-</em>null-terminated, - ASCII character string to serve as a comment/name for the filter. - </p> - <p>Filters that are defined in this format documentation - such as deflate and shuffle do not store the <em>Name - Length</em> or <em>Name</em> fields. - </p> - </td> - </tr> - - <tr> - <td><p>Client Data</p></td> - <td><p>This is an array of four-byte integers which will be - passed to the filter function. The Client Data Number of - Values</em> determines the number of elements in the array.</p> - </td> - </tr> - </table> - </div> + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This table + describes version 1.</p></td> + </tr> + + <tr> + <td><p>Number of Filters</p></td> + <td><p>The total number of filters described in this + message. The maximum possible number of filters in a message is 32.</p></td> + </tr> + + <tr> + <td><p>Filter Description List</p></td> + <td><p>A description of each filter. A filter description + appears in the next table.</p></td> + </tr> + </table> +</div> <br /> -<h4><a name="AttributeMessage">IV.A.2.m. The Attribute Message</a></h4> +<div align="center"> + <table class="format"> + <caption>Filter Description</caption> - <!-- start msgdesc table --> - <center> + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="2">Filter Identification Value</td> + <td colspan="2">Name Length</td> + </tr> + + <tr> + <td colspan="2">Flags</td> + <td colspan="2">Number Client Data Values</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size, optional)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Client Data <em>(variable size, + optional)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4">Padding <em>(variable size, optional)</em></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Filter Identification Value</p></td> + <td> + <p> + This value, often referred to as a filter identifier, is designed + to be a unique identifier for the filter. Values from zero through + 32,767 are reserved for filters supported by The HDF Group in the + HDF5 Library and for filters requested and supported by third + parties. Filters supported by The HDF Group are documented + immediately below. Information on 3rd-party filters can be found at + The HDF Group’s <a + href="http://www.hdfgroup.org/services/contributions.html"> + Contributions</a> page. + </p> + + <p> + To request a filter identifier, please contact The HDF + Group’s Help Desk at <img src="Graphics/help.png" + valign="middle" height="14" alt="The HDF Group Help Desk">. + You will be asked to provide the following information: + </p> + <ol> + <li>Contact information for the developer requesting the new + identifier</li> + <li>A short description of the new filter</li> + <li>Links to any relevant information, including licensing + information</li> + </ol> + <p>Values from 32768 to 65535 are reserved for non-distributed + uses (for example, internal company usage) or for application usage + when testing a feature. The HDF Group does not track or document + the use of the filters with identifiers from this range.</p> + + <p>The filters currently in library version 1.8.0 are listed + below:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Identification</th> + <th width="15%" align="left">Name</th> + <th width="65%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>N/A</td> + <td>Reserved</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>deflate</td> + <td>GZIP deflate compression</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>shuffle</td> + <td>Data element shuffling</td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>fletcher32</td> + <td>Fletcher32 checksum</td> + </tr> + + <tr> + <td align="center"><code>4</code></td> + <td>szip</td> + <td>SZIP compression</td> + </tr> + + <tr> + <td align="center"><code>5</code></td> + <td>nbit</td> + <td>N-bit packing</td> + </tr> + + <tr> + <td align="center"><code>6</code></td> + <td>scaleoffset</td> + <td>Scale and offset encoded values</td> + </tr> + </table> + <p></p> + </td> + </tr> + + <tr> + <td><p>Name Length</p></td> + <td><p>Each filter has an optional null-terminated ASCII + name and this field holds the length of the name including the null + termination padded with nulls to be a multiple of eight. If the + filter has no name then a value of zero is stored in this field.</p></td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>The flags indicate certain properties for a filter. + The bit values defined so far are:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set then the filter is an optional filter. During + output, if an optional filter fails it will be silently skipped + in the pipeline.</td> + </tr> + + <tr> + <td align="center"><code>1-15</code></td> + <td>Reserved (zero)</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Number of Client Data Values</p></td> + <td><p> + Each filter can store integer values to control how the filter + operates. The number of entries in the <em>Client Data</em> array + is stored in this field. + </p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p> + If the <em>Name Length</em> field is non-zero then it will contain + the size of this field, padded to a multiple of eight. This field + contains a null-terminated, ASCII character string to serve as a + comment/name for the filter. + </p></td> + </tr> + + <tr> + <td><p>Client Data</p></td> + <td><p> + This is an array of four-byte integers which will be passed to the + filter function. The <em>Client Data Number</em> of Values + determines the number of elements in the array. + </p></td> + </tr> + + <tr> + <td><p>Padding</p></td> + <td><p>Four bytes of zeroes are added to the message at this + point if the Client Data Number of Values field contains an odd + number.</p></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="format"> + <caption>Filter Pipeline Message - Version 2</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Number of Filters</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Filter Description List <em>(variable + size)</em><br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This table + describes version 2.</p></td> + </tr> + + <tr> + <td><p>Number of Filters</p></td> + <td><p>The total number of filters described in this + message. The maximum possible number of filters in a message is 32.</p></td> + </tr> + + <tr> + <td><p>Filter Description List</p></td> + <td><p>A description of each filter. A filter description + appears in the next table.</p></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="format"> + <caption>Filter Description</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="2">Filter Identification Value</td> + <td colspan="2">Name Length <em>(optional)</em></td> + </tr> + + <tr> + <td colspan="2">Flags</td> + <td colspan="2">Number Client Data Values</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size, optional)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Client Data <em>(variable size, + optional)</em><br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Filter Identification Value</p></td> + <td> + <p> + This value, often referred to as a filter identifier, is designed + to be a unique identifier for the filter. Values from zero through + 32,767 are reserved for filters supported by The HDF Group in the + HDF5 Library and for filters requested and supported by third + parties. Filters supported by The HDF Group are documented + immediately below. Information on 3rd-party filters can be found at + The HDF Group’s <a + href="http://www.hdfgroup.org/services/contributions.html"> + Contributions</a> page. + </p> + + <p> + To request a filter identifier, please contact The HDF + Group’s Help Desk at <img src="Graphics/help.png" + valign="middle" height="14" alt="The HDF Group Help Desk">. + You will be asked to provide the following information: + </p> + <ol> + <li>Contact information for the developer requesting the new + identifier</li> + <li>A short description of the new filter</li> + <li>Links to any relevant information, including licensing + information</li> + </ol> + <p>Values from 32768 to 65535 are reserved for non-distributed + uses (for example, internal company usage) or for application usage + when testing a feature. The HDF Group does not track or document + the use of the filters with identifiers from this range.</p> + + <p>The filters currently in library version 1.8.0 are listed + below:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Identification</th> + <th width="15%" align="left">Name</th> + <th width="65%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>N/A</td> + <td>Reserved</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>deflate</td> + <td>GZIP deflate compression</td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>shuffle</td> + <td>Data element shuffling</td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>fletcher32</td> + <td>Fletcher32 checksum</td> + </tr> + + <tr> + <td align="center"><code>4</code></td> + <td>szip</td> + <td>SZIP compression</td> + </tr> + + <tr> + <td align="center"><code>5</code></td> + <td>nbit</td> + <td>N-bit packing</td> + </tr> + + <tr> + <td align="center"><code>6</code></td> + <td>scaleoffset</td> + <td>Scale and offset encoded values</td> + </tr> + </table> + <p></p> + </td> + </tr> + + <tr> + <td><p>Name Length</p></td> + <td><p>Each filter has an optional null-terminated ASCII + name and this field holds the length of the name including the null + termination padded with nulls to be a multiple of eight. If the + filter has no name then a value of zero is stored in this field.</p> + <p> + Filters with IDs less than 256 (in other words, filters that are + defined in this format documentation) do not store the <em>Name + Length</em> or <em>Name</em> fields. + </p></td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>The flags indicate certain properties for a filter. + The bit values defined so far are:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set then the filter is an optional filter. During + output, if an optional filter fails it will be silently skipped + in the pipeline.</td> + </tr> + + <tr> + <td align="center"><code>1-15</code></td> + <td>Reserved (zero)</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Number of Client Data Values</p></td> + <td><p> + Each filter can store integer values to control how the filter + operates. The number of entries in the <em>Client Data</em> array + is stored in this field. + </p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p> + If the <em>Name Length</em> field is non-zero then it will contain + the size of this field, <em>not</em> padded to a multiple of eight. + This field contains a <em>non-</em>null-terminated, ASCII character + string to serve as a comment/name for the filter. + </p> + <p> + Filters that are defined in this format documentation such as + deflate and shuffle do not store the <em>Name Length</em> or <em>Name</em> + fields. + </p></td> + </tr> + + <tr> + <td><p>Client Data</p></td> + <td><p> + This is an array of four-byte integers which will be passed to the + filter function. The Client Data Number of Values<em></em> + determines the number of elements in the array. + </p></td> + </tr> + </table> +</div> + +<br /> +<h4> + <a name="AttributeMessage">IV.A.2.m. The Attribute Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Attribute</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x000C</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td><p>The <em>Attribute</em> message is used to store objects - in the HDF5 file which are used as attributes, or - “metadata” about the current object. An attribute - is a small dataset; it has a name, a datatype, a dataspace, and - raw data. Since attributes are stored in the object header, they - should be relatively small (in other words, less than 64KB). - They can be associated with any type of object which has an - object header (groups, datasets, or committed (named) - datatypes).</p> - <p>In 1.8.x versions of the library, attributes can be larger - than 64KB. See the - <a href="UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FAttributes%2FHDF5_Attributes.htm%3Frhtocid%3Dtoc8.2_1%23TOC_8_5_Special_Issuesbc-13"> - “Special Issues”</a> section of the Attributes chapter - in the <cite>HDF5 User’s Guide</cite> for more information.</p> - <p>Note: Attributes on an object must have unique names: - the HDF5 Library currently enforces this by causing the - creation of an attribute with a duplicate name to fail. - Attributes on different objects may have the same name, - however.</p></td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Attribute Message (Version 1) - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Reserved (zero)</td> - <td colspan="2">Name Size</td> - </tr> - - <tr> - <td colspan="2">Datatype Size</td> - <td colspan="2">Dataspace Size</td> - </tr> - - <tr> - <td colspan="4"><br />Name <em>(variable size)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Datatype <em>(variable size)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Dataspace <em>(variable size)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Data <em>(variable size)</em><br /><br /></td> - </tr> - </table> - </div> + <tr> + <td colspan="2"><b>Header Message Name:</b> Attribute</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x000C</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td><p> + The <em>Attribute</em> message is used to store objects in the HDF5 + file which are used as attributes, or “metadata” about + the current object. An attribute is a small dataset; it has a name, + a datatype, a dataspace, and raw data. Since attributes are stored + in the object header, they should be relatively small (in other + words, less than 64KB). They can be associated with any type of + object which has an object header (groups, datasets, or committed + (named) datatypes). + </p> + <p> + In 1.8.x versions of the library, attributes can be larger than + 64KB. See the <a + href="UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_User_Guide%2FAttributes%2FHDF5_Attributes.htm%3Frhtocid%3Dtoc8.2_1%23TOC_8_5_Special_Issuesbc-13"> + “Special Issues”</a> section of the Attributes chapter in + the <cite>HDF5 User Guide</cite> for more information. + </p> + <p>Note: Attributes on an object must have unique names: the + HDF5 Library currently enforces this by causing the creation of an + attribute with a duplicate name to fail. Attributes on different + objects may have the same name, however.</p></td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number information is used for changes in the format of the - attribute message and is described here: - <table class="list"> - <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Never used.</td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>Used by the library before version 1.6 to encode attribute message. - This version does not support shared datatypes.</td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Name Size</p></td> - <td><p>The length of the attribute name in bytes including the - null terminator. Note that the <em>Name</em> field below may - contain additional padding not represented by this - field.</p></td> - </tr> - - <tr> - <td><p>Datatype Size</p></td> - <td><p>The length of the datatype description in the <em>Datatype</em> - field below. Note that the <em>Datatype</em> field may contain - additional padding not represented by this field.</p></td> - </tr> - - <tr> - <td><p>Dataspace Size</p></td> - <td><p>The length of the dataspace description in the <em>Dataspace</em> - field below. Note that the <em>Dataspace</em> field may contain - additional padding not represented by this field.</p></td> - </tr> - - <tr> - <td><p>Name</p></td> - <td><p>The null-terminated attribute name. This field is - padded with additional null characters to make it a - multiple of eight bytes.</p></td> - </tr> - - <tr> - <td><p>Datatype</p></td> - <td><p>The datatype description follows the same format as - described for the datatype object header message. This - field is padded with additional zero bytes to make it a - multiple of eight bytes.</p></td> - </tr> - - <tr> - <td><p>Dataspace</p></td> - <td><p>The dataspace description follows the same format as - described for the dataspace object header message. This - field is padded with additional zero bytes to make it a - multiple of eight bytes.</p></td> - </tr> - - <tr> - <td><p>Data</p></td> - <td><p>The raw data for the attribute. The size is determined - from the datatype and dataspace descriptions. This - field is <em>not</em> padded with additional bytes.</p></td> - </tr> - </table> - </div> +<div align="center"> + <table class="format"> + <caption>Attribute Message (Version 1)</caption> - <br /> - <div align="center"> - <table class="format"> - <caption> - Attribute Message (Version 2) - </caption> - - <tr align="center"> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Flags</td> - <td colspan="2">Name Size</td> - </tr> - - <tr> - <td colspan="2">Datatype Size</td> - <td colspan="2">Dataspace Size</td> - </tr> - - <tr> - <td colspan="4"><br />Name <em>(variable size)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Datatype <em>(variable size)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Dataspace <em>(variable size)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Data <em>(variable size)</em><br /><br /></td> - </tr> - </table> - </div> + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number information is used for changes in the - format of the attribute message and is described here: + <tr> + <td>Version</td> + <td>Reserved (zero)</td> + <td colspan="2">Name Size</td> + </tr> + + <tr> + <td colspan="2">Datatype Size</td> + <td colspan="2">Dataspace Size</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Datatype <em>(variable size)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dataspace <em>(variable size)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data <em>(variable size)</em><br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number information is used for changes in + the format of the attribute message and is described here:</p> <table class="list"> - <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>2</code></td> - <td>Used by the library of version 1.6.x and after to encode - attribute messages. - This version supports shared datatypes. The fields of - name, datatype, and dataspace are not padded with - additional bytes of zero. - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Flags</p></td> - <td><p>This bit field contains extra information about - interpreting the attribute message: - - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>If set, datatype is shared.</td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>If set, dataspace is shared.</td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Name Size</p></td> - <td><p>The length of the attribute name in bytes including the - null terminator.</p></td> - </tr> - - <tr> - <td><p>Datatype Size</p></td> - <td><p>The length of the datatype description in the <em>Datatype</em> - field below.</p></td> - </tr> - - <tr> - <td><p>Dataspace Size</p></td> - <td><p>The length of the dataspace description in the <em>Dataspace</em> - field below.</p></td> - </tr> - - <tr> - <td><p>Name</p></td> - <td><p>The null-terminated attribute name. This field is <em>not</em> - padded with additional bytes.</p></td> - </tr> - - <tr> - <td><p>Datatype</p></td> - <td><p>The datatype description follows the same format as - described for the datatype object header message. - </p> - <p>If the - <em>Flag</em> field indicates this attribute’s datatype is - shared, this field will contain a “shared message” encoding - instead of the datatype encoding. - </p> - <p>This field is <em>not</em> padded with additional bytes. - </p> - </td> - </tr> - - <tr> - <td><p>Dataspace</p></td> - <td><p>The dataspace description follows the same format as - described for the dataspace object header message. - </p> - <p>If the - <em>Flag</em> field indicates this attribute’s dataspace is - shared, this field will contain a “shared message” encoding - instead of the dataspace encoding. - </p> - <p>This field is <em>not</em> padded with additional bytes.</p> - </td> - </tr> - - <tr> - <td><p>Data</p></td> - <td><p>The raw data for the attribute. The size is determined - from the datatype and dataspace descriptions. - </p> - <p>This field is <em>not</em> padded with additional zero bytes. - </p> - </td> - </tr> - </table> - </div> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> - <br /> - <div align="center"> - <table class="format"> - <caption> - Attribute Message (Version 3) - </caption> - - <tr align="center"> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Flags</td> - <td colspan="2">Name Size</td> - </tr> - - <tr> - <td colspan="2">Datatype Size</td> - <td colspan="2">Dataspace Size</td> - </tr> - - <tr> - <td>Name Character Set Encoding</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Name <em>(variable size)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Datatype <em>(variable size)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Dataspace <em>(variable size)</em><br /><br /></td> - </tr> - - <tr> - <td colspan="4"><br />Data <em>(variable size)</em><br /><br /></td> - </tr> - </table> - </div> + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number information is used for changes in the - format of the attribute message and is described here: + <tr> + <td align="center"><code>1</code></td> + <td>Used by the library before version 1.6 to encode + attribute message. This version does not support shared + datatypes.</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Name Size</p></td> + <td><p> + The length of the attribute name in bytes including the null + terminator. Note that the <em>Name</em> field below may contain + additional padding not represented by this field. + </p></td> + </tr> + + <tr> + <td><p>Datatype Size</p></td> + <td><p> + The length of the datatype description in the <em>Datatype</em> + field below. Note that the <em>Datatype</em> field may contain + additional padding not represented by this field. + </p></td> + </tr> + + <tr> + <td><p>Dataspace Size</p></td> + <td><p> + The length of the dataspace description in the <em>Dataspace</em> + field below. Note that the <em>Dataspace</em> field may contain + additional padding not represented by this field. + </p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p>The null-terminated attribute name. This field is + padded with additional null characters to make it a multiple of + eight bytes.</p></td> + </tr> + + <tr> + <td><p>Datatype</p></td> + <td><p>The datatype description follows the same format as + described for the datatype object header message. This field is + padded with additional zero bytes to make it a multiple of eight + bytes.</p></td> + </tr> + + <tr> + <td><p>Dataspace</p></td> + <td><p>The dataspace description follows the same format as + described for the dataspace object header message. This field is + padded with additional zero bytes to make it a multiple of eight + bytes.</p></td> + </tr> + + <tr> + <td><p>Data</p></td> + <td><p> + The raw data for the attribute. The size is determined from the + datatype and dataspace descriptions. This field is <em>not</em> + padded with additional bytes. + </p></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="format"> + <caption>Attribute Message (Version 2)</caption> + + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Name Size</td> + </tr> + + <tr> + <td colspan="2">Datatype Size</td> + <td colspan="2">Dataspace Size</td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Datatype <em>(variable size)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dataspace <em>(variable size)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data <em>(variable size)</em><br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number information is used for changes in + the format of the attribute message and is described here:</p> <table class="list"> - <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>3</code></td> - <td>Used by the library of version 1.8.x and after to - encode attribute messages. - This version supports attributes with non-ASCII names. - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Flags</p></td> - <td><p>This bit field contains extra information about - interpreting the attribute message: - - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>If set, datatype is shared.</td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>If set, dataspace is shared.</td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Name Size</p></td> - <td><p>The length of the attribute name in bytes including the - null terminator.</p></td> - </tr> - - <tr> - <td><p>Datatype Size</p></td> - <td><p>The length of the datatype description in the <em>Datatype</em> - field below.</p></td> - </tr> - - <tr> - <td><p>Dataspace Size</p></td> - <td><p>The length of the dataspace description in the <em>Dataspace</em> - field below.</p></td> - </tr> - - <tr> - <td><p>Name Character Set Encoding</p></td> - <td><p>The character set encoding for the attribute’s name: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>ASCII character set encoding - </td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>UTF-8 character set encoding - </td> - </tr> - </table> - </p> - </td> - </tr> - - <tr> - <td><p>Name</p></td> - <td><p>The null-terminated attribute name. This field is <em>not</em> - padded with additional bytes.</p></td> - </tr> - - <tr> - <td><p>Datatype</p></td> - <td><p>The datatype description follows the same format as - described for the datatype object header message. - </p> - <p>If the - <em>Flag</em> field indicates this attribute’s datatype is - shared, this field will contain a “shared message” encoding - instead of the datatype encoding. - </p> - <p>This field is <em>not</em> padded with additional bytes. - </p> - </td> - </tr> - - <tr> - <td><p>Dataspace</p></td> - <td><p>The dataspace description follows the same format as - described for the dataspace object header message. - </p> - <p>If the - <em>Flag</em> field indicates this attribute’s dataspace is - shared, this field will contain a “shared message” encoding - instead of the dataspace encoding. - </p> - <p>This field is <em>not</em> padded with additional bytes.</p> - </td> - </tr> - - <tr> - <td><p>Data</p></td> - <td><p>The raw data for the attribute. The size is determined - from the datatype and dataspace descriptions. - </p> - <p>This field is <em>not</em> padded with additional zero bytes. - </p> - </td> - </tr> - </table> - </div> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>Used by the library of version 1.6.x and after to encode + attribute messages. This version supports shared datatypes. The + fields of name, datatype, and dataspace are not padded with + additional bytes of zero.</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This bit field contains extra information about + interpreting the attribute message:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, datatype is shared.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>If set, dataspace is shared.</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Name Size</p></td> + <td><p>The length of the attribute name in bytes including + the null terminator.</p></td> + </tr> + + <tr> + <td><p>Datatype Size</p></td> + <td><p> + The length of the datatype description in the <em>Datatype</em> + field below. + </p></td> + </tr> + + <tr> + <td><p>Dataspace Size</p></td> + <td><p> + The length of the dataspace description in the <em>Dataspace</em> + field below. + </p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p> + The null-terminated attribute name. This field is <em>not</em> + padded with additional bytes. + </p></td> + </tr> + + <tr> + <td><p>Datatype</p></td> + <td><p>The datatype description follows the same format as + described for the datatype object header message.</p> + <p> + If the <em>Flag</em> field indicates this attribute’s + datatype is shared, this field will contain a “shared + message” encoding instead of the datatype encoding. + </p> + <p> + This field is <em>not</em> padded with additional bytes. + </p></td> + </tr> + + <tr> + <td><p>Dataspace</p></td> + <td><p>The dataspace description follows the same format as + described for the dataspace object header message.</p> + <p> + If the <em>Flag</em> field indicates this attribute’s + dataspace is shared, this field will contain a “shared + message” encoding instead of the dataspace encoding. + </p> + <p> + This field is <em>not</em> padded with additional bytes. + </p></td> + </tr> + + <tr> + <td><p>Data</p></td> + <td><p>The raw data for the attribute. The size is + determined from the datatype and dataspace descriptions.</p> + <p> + This field is <em>not</em> padded with additional zero bytes. + </p></td> + </tr> + </table> +</div> <br /> -<h4><a name="CommentMessage">IV.A.2.n. The Object Comment -Message</a></h4> +<div align="center"> + <table class="format"> + <caption>Attribute Message (Version 3)</caption> - <!-- start msgdesc table --> - <center> + <tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Name Size</td> + </tr> + + <tr> + <td colspan="2">Datatype Size</td> + <td colspan="2">Dataspace Size</td> + </tr> + + <tr> + <td>Name Character Set Encoding</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Name <em>(variable size)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Datatype <em>(variable size)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Dataspace <em>(variable size)</em><br /> + <br /></td> + </tr> + + <tr> + <td colspan="4"><br />Data <em>(variable size)</em><br /> + <br /></td> + </tr> + </table> +</div> + +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>The version number information is used for changes in + the format of the attribute message and is described here:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>Used by the library of version 1.8.x and after to encode + attribute messages. This version supports attributes with + non-ASCII names.</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This bit field contains extra information about + interpreting the attribute message:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, datatype is shared.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>If set, dataspace is shared.</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Name Size</p></td> + <td><p>The length of the attribute name in bytes including + the null terminator.</p></td> + </tr> + + <tr> + <td><p>Datatype Size</p></td> + <td><p> + The length of the datatype description in the <em>Datatype</em> + field below. + </p></td> + </tr> + + <tr> + <td><p>Dataspace Size</p></td> + <td><p> + The length of the dataspace description in the <em>Dataspace</em> + field below. + </p></td> + </tr> + + <tr> + <td><p>Name Character Set Encoding</p></td> + <td><p>The character set encoding for the attribute’s + name:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>ASCII character set encoding</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>UTF-8 character set encoding</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Name</p></td> + <td><p> + The null-terminated attribute name. This field is <em>not</em> + padded with additional bytes. + </p></td> + </tr> + + <tr> + <td><p>Datatype</p></td> + <td><p>The datatype description follows the same format as + described for the datatype object header message.</p> + <p> + If the <em>Flag</em> field indicates this attribute’s + datatype is shared, this field will contain a “shared + message” encoding instead of the datatype encoding. + </p> + <p> + This field is <em>not</em> padded with additional bytes. + </p></td> + </tr> + + <tr> + <td><p>Dataspace</p></td> + <td><p>The dataspace description follows the same format as + described for the dataspace object header message.</p> + <p> + If the <em>Flag</em> field indicates this attribute’s + dataspace is shared, this field will contain a “shared + message” encoding instead of the dataspace encoding. + </p> + <p> + This field is <em>not</em> padded with additional bytes. + </p></td> + </tr> + + <tr> + <td><p>Data</p></td> + <td><p>The raw data for the attribute. The size is + determined from the datatype and dataspace descriptions.</p> + <p> + This field is <em>not</em> padded with additional zero bytes. + </p></td> + </tr> + </table> +</div> + +<br /> +<h4> + <a name="CommentMessage">IV.A.2.n. The Object Comment Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Object - Comment</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x000D</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>The object comment is designed to be a short description of - an object. An object comment is a sequence of non-zero - (<code>\0</code>) ASCII characters with no other formatting - included by the library.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Name Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td colspan="4"><br />Comment <em>(variable size)</em><br /><br /></td> - </tr> - </table> - </div> + <tr> + <td colspan="2"><b>Header Message Name:</b> Object Comment</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x000D</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>The object comment is designed to be a short description of + an object. An object comment is a sequence of non-zero (<code>\0</code>) + ASCII characters with no other formatting included by the library. + </td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Name</p></td> - <td><p>A null terminated ASCII character string.</p></td> - </tr> - </table> - </div> +<div align="center"> + <table class="format"> + <caption>Name Message</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4"><br />Comment <em>(variable size)</em><br /> + <br /></td> + </tr> + </table> +</div> <br /> -<h4><a name="OldModificationTimeMessage">IV.A.2.o. The Object -Modification Time (Old) Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Name</p></td> + <td><p>A null terminated ASCII character string.</p></td> + </tr> + </table> +</div> + +<br /> +<h4> + <a name="OldModificationTimeMessage">IV.A.2.o. The Object + Modification Time (Old) Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Object - Modification Time (Old)</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x000E</td></tr> - <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td><p>The object modification date and time is a timestamp - which indicates (using ISO-8601 date and time format) the last - modification of an object. The time is updated when any object - header message changes according to the system clock where the - change was posted. All fields of this message should be - interpreted as coordinated universal time (UTC).</p> - <p>This modification time message is deprecated in favor of - the “new” <a href="#ModificationTimeMessage">Object - Modification Time</a> message and is no longer written to the - file in versions of the HDF5 Library after the 1.6.0 - version.</p></td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Modification Time Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td colspan="4">Year</td> - </tr> - - <tr> - <td colspan="2">Month</td> - <td colspan="2">Day of Month</td> - </tr> - - <tr> - <td colspan="2">Hour</td> - <td colspan="2">Minute</td> - </tr> - - <tr> - <td colspan="2">Second</td> - <td colspan="2">Reserved</td> - </tr> - </table> - </div> + <tr> + <td colspan="2"><b>Header Message Name:</b> Object Modification + Time (Old)</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x000E</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Fixed</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td><p>The object modification date and time is a timestamp + which indicates (using ISO-8601 date and time format) the last + modification of an object. The time is updated when any object + header message changes according to the system clock where the + change was posted. All fields of this message should be interpreted + as coordinated universal time (UTC).</p> + <p> + This modification time message is deprecated in favor of the + “new” <a href="#ModificationTimeMessage">Object + Modification Time</a> message and is no longer written to the file in + versions of the HDF5 Library after the 1.6.0 version. + </p></td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Year</p></td> - <td><p>The four-digit year as an ASCII string. For example, - <code>1998</code>. - </p></td> - </tr> - - <tr> - <td><p>Month</p></td> - <td><p>The month number as a two digit ASCII string where - January is <code>01</code> and December is <code>12</code>.</p></td> - </tr> - - <tr> - <td><p>Day of Month</p></td> - <td><p>The day number within the month as a two digit ASCII - string. The first day of the month is <code>01</code>.</p></td> - </tr> - - <tr> - <td><p>Hour</p></td> - <td><p>The hour of the day as a two digit ASCII string where - midnight is <code>00</code> and 11:00pm is <code>23</code>.</p></td> - </tr> - - <tr> - <td><p>Minute</p></td> - <td><p>The minute of the hour as a two digit ASCII string where - the first minute of the hour is <code>00</code> and - the last is <code>59</code>.</p></td> - </tr> - - <tr> - <td><p>Second</p></td> - <td><p>The second of the minute as a two digit ASCII string - where the first second of the minute is <code>00</code> - and the last is <code>59</code>.</p></td> - </tr> - - <tr> - <td><p>Reserved</p></td> - <td><p>This field is reserved and should always be zero.</p></td> - </tr> - </table> - </div> +<div align="center"> + <table class="format"> + <caption>Modification Time Message</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td colspan="4">Year</td> + </tr> + + <tr> + <td colspan="2">Month</td> + <td colspan="2">Day of Month</td> + </tr> + + <tr> + <td colspan="2">Hour</td> + <td colspan="2">Minute</td> + </tr> + + <tr> + <td colspan="2">Second</td> + <td colspan="2">Reserved</td> + </tr> + </table> +</div> <br /> -<h4><a name="SOHMTableMessage">IV.A.2.p. The Shared Message Table -Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Year</p></td> + <td><p> + The four-digit year as an ASCII string. For example, + <code>1998</code> + . + </p></td> + </tr> + + <tr> + <td><p>Month</p></td> + <td><p> + The month number as a two digit ASCII string where January is + <code>01</code> + and December is + <code>12</code> + . + </p></td> + </tr> + + <tr> + <td><p>Day of Month</p></td> + <td><p> + The day number within the month as a two digit ASCII string. The + first day of the month is + <code>01</code> + . + </p></td> + </tr> + + <tr> + <td><p>Hour</p></td> + <td><p> + The hour of the day as a two digit ASCII string where midnight is + <code>00</code> + and 11:00pm is + <code>23</code> + . + </p></td> + </tr> + + <tr> + <td><p>Minute</p></td> + <td><p> + The minute of the hour as a two digit ASCII string where the first + minute of the hour is + <code>00</code> + and the last is + <code>59</code> + . + </p></td> + </tr> + + <tr> + <td><p>Second</p></td> + <td><p> + The second of the minute as a two digit ASCII string where the + first second of the minute is + <code>00</code> + and the last is + <code>59</code> + . + </p></td> + </tr> + + <tr> + <td><p>Reserved</p></td> + <td><p>This field is reserved and should always be zero.</p></td> + </tr> + </table> +</div> + +<br /> +<h4> + <a name="SOHMTableMessage">IV.A.2.p. The Shared Message Table + Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Shared Message - Table</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x000F</td></tr> - <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>This message is used to locate the table of shared object - header message (SOHM) indexes. Each index consists of information - to find the shared messages from either the heap or object header. - This message is <em>only</em> found in the superblock - extension.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Shared Message Table Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Shared Object Header Message Table Address<sup>O</sup><br /><br /></td> - </tr> - - <tr> - <td>Number of Indices</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> + <tr> + <td colspan="2"><b>Header Message Name:</b> Shared Message Table</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x000F</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Fixed</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>This message is used to locate the table of shared object + header message (SOHM) indexes. Each index consists of information to + find the shared messages from either the heap or object header. This + message is <em>only</em> found in the superblock extension. + </td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - </table> +<div align="center"> + <table class="format"> + <caption>Shared Message Table Message</caption> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> - </div> + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number for this message. This document describes version 0.</p></td> - </tr> - - <tr> - <td><p>Shared Object Header Message Table Address</p></td> - <td><p>This field is the address of the master table for shared - object header message indexes.</p> - </td> - </tr> - - <tr> - <td><p>Number of Indices</p></td> - <td><p>This field is the number of indices in the master table. - </p></td> - </tr> + <tr> + <td colspan="4"><br />Shared Object Header Message Table + Address<sup>O</sup><br /> + <br /></td> + </tr> - </table> - </div> + <tr> + <td>Number of Indices</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> + +</div> <br /> -<h4><a name="ContinuationMessage">IV.A.2.q. The Object Header -Continuation Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document + describes version 0.</p></td> + </tr> + + <tr> + <td><p>Shared Object Header Message Table Address</p></td> + <td><p>This field is the address of the master table for + shared object header message indexes.</p></td> + </tr> + + <tr> + <td><p>Number of Indices</p></td> + <td><p>This field is the number of indices in the master + table.</p></td> + </tr> + + </table> +</div> + +<br /> +<h4> + <a name="ContinuationMessage">IV.A.2.q. The Object Header + Continuation Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Object Header - Continuation</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0010</td></tr> - <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>The object header continuation is the location in the file - of a block containing more header messages for the current data - object. This can be used when header blocks become too large or - are likely to change over time.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Object Header Continuation Message - </caption> + <tr> + <td colspan="2"><b>Header Message Name:</b> Object Header + Continuation</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0010</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Fixed</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>The object header continuation is the location in the file + of a block containing more header messages for the current data + object. This can be used when header blocks become too large or are + likely to change over time.</td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption>Object Header Continuation Message</caption> <tr> - <th width=25%>byte</th> - <th width=25%>byte</th> - <th width=25%>byte</th> - <th width=25%>byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> </tr> <tr> - <td colspan="4"><br />Offset<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Offset<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Length<sup>L</sup><br /><br /></td> + <td colspan="4"><br />Length<sup>L</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>Offset</p></td> - <td><p>This value is the address in the file where the - header continuation block is located.</p></td> + <td><p>Offset</p></td> + <td><p>This value is the address in the file where the + header continuation block is located.</p></td> </tr> <tr> - <td><p>Length</p></td> - <td><p>This value is the length in bytes of the header continuation - block in the file.</p></td> + <td><p>Length</p></td> + <td><p>This value is the length in bytes of the header + continuation block in the file.</p></td> </tr> - </table> - </div> - <br /> + </table> +</div> +<br /> - <p>The format of the header continuation block that this message points - to depends on the version of the object header that the message is - contained within. - </p> - - <p> - Continuation blocks for version 1 object headers have no special - formatting information; they are merely a list of object header - message info sequences (type, size, flags, reserved bytes and data - for each message sequence). See the description - of <a href="#V1ObjectHeaderPrefix">Version 1 Data Object Header Prefix.</a> - </p> - - <p>Continuation blocks for version 2 object headers <em>do</em> have - special formatting information as described here - (see also the description of - <a href="#V2ObjectHeaderPrefix">Version 2 Data Object Header Prefix.</a>): - </p> - <div align="center"> - <table class="format"> - <caption> - Version 2 Object Header Continuation Block - </caption> - - <tr> - <th>byte</th> - <th>byte</th> - <th>byte</th> - <th>byte</th> - </tr> - - <tr> - <td colspan="4">Signature</td> - </tr> - <tr> - <td>Header Message Type #1</td> - <td colspan="2">Size of Header Message Data #1</td> - <td>Header Message #1 Flags</td> - </tr> - - <tr> - <td colspan="2">Header Message #1 Creation Order <em>(optional)</em></td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Header Message Data #1<br /><br /></td> - </tr> - - <tr> - <td colspan="4">.<br />.<br />.<br /></td> - </tr> - - <tr> - <td>Header Message Type #n</td> - <td colspan="2">Size of Header Message Data #n</td> - <td>Header Message #n Flags</td> - </tr> - - <tr> - <td colspan="2">Header Message #n Creation Order <em>(optional)</em></td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br />Header Message Data #n<br /><br /></td> - </tr> - - <tr> - <td colspan="4">Gap <em>(optional, variable size)</em></td> - </tr> - - <tr> - <td colspan="4">Checksum</td> - </tr> - </table> - </div> +<p>The format of the header continuation block that this message + points to depends on the version of the object header that the message + is contained within.</p> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Signature</p></td> - <td> - <p>The ASCII character string “<code>OCHK</code>” - is used to indicate the - beginning of an object header continuation block. This gives file - consistency checking utilities a better chance of reconstructing a - damaged file. - </p> - </td> - </tr> - - <tr> - <td><p>Header Message #n Type</p></td> - <td> - <p>Same format as version 1 of the object header, described above. - </p></td> - </tr> - - <tr> - <td><p>Size of Header Message #n Data</p></td> - <td> - <p>Same format as version 1 of the object header, described above. - </p></td> - </tr> - - <tr> - <td><p>Header Message #n Flags</p></td> - <td> - <p>Same format as version 1 of the object header, described above. - </p></td> - </tr> - - <tr> - <td><p>Header Message #n Creation Order</p></td> - <td> - <p>This field stores the order that a message of a given type - was created in.</p> - <p>This field is present if bit 2 of <em>flags</em> is set.</p> - </td> - </tr> - - <tr> - <td><p>Header Message #n Data</p></td> - <td> - <p>Same format as version 1 of the object header, described above. - </p></td> - </tr> - - <tr> - <td><p>Gap</p></td> - <td> - <p>A gap in an object header chunk is inferred by the end of the - messages for the chunk before the beginning of the chunk’s - checksum. Gaps are always smaller than the size of an - object header message prefix (message type + message size + - message flags).</p> - <p>Gaps are formed when a message (typically an attribute message) - in an earlier chunk is deleted and a message from a later - chunk that does not quite fit into the free space is moved - into the earlier chunk.</p> - </td> - </tr> - - <tr> - <td><p>Checksum</p></td> - <td> - <p>This is the checksum for the object header chunk. - </p> - </td> +<p> + Continuation blocks for version 1 object headers have no special + formatting information; they are merely a list of object header message + info sequences (type, size, flags, reserved bytes and data for each + message sequence). See the description of <a + href="#V1ObjectHeaderPrefix">Version 1 Data Object Header Prefix.</a> +</p> + +<p> + Continuation blocks for version 2 object headers <em>do</em> have + special formatting information as described here (see also the + description of <a href="#V2ObjectHeaderPrefix">Version 2 Data + Object Header Prefix.</a>): +</p> +<div align="center"> + <table class="format"> + <caption>Version 2 Object Header Continuation Block</caption> + + <tr> + <th>byte</th> + <th>byte</th> + <th>byte</th> + <th>byte</th> + </tr> + + <tr> + <td colspan="4">Signature</td> + </tr> + <tr> + <td>Header Message Type #1</td> + <td colspan="2">Size of Header Message Data #1</td> + <td>Header Message #1 Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #1 Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #1<br /> + <br /></td> + </tr> + + <tr> + <td colspan="4">.<br />.<br />.<br /></td> + </tr> + + <tr> + <td>Header Message Type #n</td> + <td colspan="2">Size of Header Message Data #n</td> + <td>Header Message #n Flags</td> + </tr> + + <tr> + <td colspan="2">Header Message #n Creation Order <em>(optional)</em></td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br />Header Message Data #n<br /> + <br /></td> </tr> - </table> - </div> + + <tr> + <td colspan="4">Gap <em>(optional, variable size)</em></td> + </tr> + + <tr> + <td colspan="4">Checksum</td> + </tr> + </table> +</div> <br /> -<h4><a name="SymbolTableMessage">IV.A.2.r. The Symbol Table -Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Signature</p></td> + <td> + <p> + The ASCII character string “ + <code>OCHK</code> + ” is used to indicate the beginning of an object header + continuation block. This gives file consistency checking utilities + a better chance of reconstructing a damaged file. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Type</p></td> + <td> + <p>Same format as version 1 of the object header, described + above.</p> + </td> + </tr> + + <tr> + <td><p>Size of Header Message #n Data</p></td> + <td> + <p>Same format as version 1 of the object header, described + above.</p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Flags</p></td> + <td> + <p>Same format as version 1 of the object header, described + above.</p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Creation Order</p></td> + <td> + <p>This field stores the order that a message of a given type + was created in.</p> + <p> + This field is present if bit 2 of <em>flags</em> is set. + </p> + </td> + </tr> + + <tr> + <td><p>Header Message #n Data</p></td> + <td> + <p>Same format as version 1 of the object header, described + above.</p> + </td> + </tr> + + <tr> + <td><p>Gap</p></td> + <td> + <p>A gap in an object header chunk is inferred by the end of the + messages for the chunk before the beginning of the chunk’s + checksum. Gaps are always smaller than the size of an object header + message prefix (message type + message size + message flags).</p> + <p>Gaps are formed when a message (typically an attribute + message) in an earlier chunk is deleted and a message from a later + chunk that does not quite fit into the free space is moved into the + earlier chunk.</p> + </td> + </tr> + + <tr> + <td><p>Checksum</p></td> + <td> + <p>This is the checksum for the object header chunk.</p> + </td> + </tr> + </table> +</div> + +<br /> +<h4> + <a name="SymbolTableMessage">IV.A.2.r. The Symbol Table Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Symbol Table - Message</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0011</td></tr> - <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> - <tr><td colspan="2"><b>Status:</b> Required for - “old style” groups; may not be repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>Each “old style” group has a v1 B-tree and a - local heap for storing symbol table entries, which are located - with this message.</td></tr> - <tr><td colspan="2"><b>Format of data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> + <tr> + <td colspan="2"><b>Header Message Name:</b> Symbol Table Message</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0011</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Fixed</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Required for “old + style” groups; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>Each “old style” group has a v1 B-tree and a + local heap for storing symbol table entries, which are located with + this message.</td> + </tr> + <tr> + <td colspan="2"><b>Format of data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> <caption> - <b>Symbol Table Message</b> + <b>Symbol Table Message</b> </caption> <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> </tr> <tr> - <td colspan="4"><br />v1 B-tree Address<sup>O</sup><br /><br /></td> + <td colspan="4"><br />v1 B-tree Address<sup>O</sup><br /> + <br /></td> </tr> <tr> - <td colspan="4"><br />Local Heap Address<sup>O</sup><br /><br /></td> + <td colspan="4"><br />Local Heap Address<sup>O</sup><br /> + <br /></td> </tr> - </table> + </table> - <table class="note"> + <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> +<br /> +<div align="center"> + <table class="desc"> <tr> - <th width="30%">Field Name</th> - <th>Description</th> + <th width="30%">Field Name</th> + <th>Description</th> </tr> <tr> - <td><p>v1 B-tree Address</p></td> - <td><p>This value is the address of the v1 B-tree containing the - symbol table entries for the group.</p></td> + <td><p>v1 B-tree Address</p></td> + <td><p>This value is the address of the v1 B-tree containing + the symbol table entries for the group.</p></td> </tr> <tr> - <td><p>Local Heap Address</p></td> - <td><p>This value is the address of the local heap containing - the link names for the symbol table entries for the group.</p></td> + <td><p>Local Heap Address</p></td> + <td><p>This value is the address of the local heap + containing the link names for the symbol table entries for the + group.</p></td> </tr> - </table> - </div> + </table> +</div> <br /> -<h4><a name="ModificationTimeMessage">IV.A.2.s. The Object -Modification Time Message</a></h4> +<h4> + <a name="ModificationTimeMessage">IV.A.2.s. The Object Modification + Time Message</a> +</h4> - <!-- start msgdesc table --> - <center> +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Object - Modification Time</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0012</td></tr> - <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>The object modification time is a timestamp which indicates - the time of the last modification of an object. The time is - updated when any object header message changes according to - the system clock where the change was posted.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Modification Time Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td colspan="3">Reserved (zero)</td> - </tr> - - <tr> - <td colspan="4">Seconds After UNIX Epoch</td> - </tr> - </table> - </div> + <tr> + <td colspan="2"><b>Header Message Name:</b> Object Modification + Time</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0012</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Fixed</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>The object modification time is a timestamp which indicates + the time of the last modification of an object. The time is updated + when any object header message changes according to the system clock + where the change was posted.</td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number is used for changes in the format of Object Modification Time - and is described here: - <table class="list"> - <tr> - <th width="20%" align="center">Version</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>Never used.</td> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>Used by Version 1.6.1 and after of the library to encode time. In - this version, the time is the seconds after Epoch.</td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Seconds After UNIX Epoch</p></td> - <td><p>A 32-bit unsigned integer value that stores the number of - seconds since 0 hours, 0 minutes, 0 seconds, January 1, 1970, - Coordinated Universal Time.</p></td> - </tr> - </table> - </div> +<div align="center"> + <table class="format"> + <caption>Modification Time Message</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3">Reserved (zero)</td> + </tr> + + <tr> + <td colspan="4">Seconds After UNIX Epoch</td> + </tr> + </table> +</div> <br /> -<h4><a name="BtreeKValuesMessage">IV.A.2.t. The B-tree -‘K’ Values Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Version</p></td> + <td><p>The version number is used for changes in the format + of Object Modification Time and is described here:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Version</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>Never used.</td> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>Used by Version 1.6.1 and after of the library to encode + time. In this version, the time is the seconds after Epoch.</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Seconds After UNIX Epoch</p></td> + <td><p>A 32-bit unsigned integer value that stores the + number of seconds since 0 hours, 0 minutes, 0 seconds, January 1, + 1970, Coordinated Universal Time.</p></td> + </tr> + </table> +</div> + +<br /> +<h4> + <a name="BtreeKValuesMessage">IV.A.2.t. The B-tree ‘K’ + Values Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> B-tree - ‘K’ Values</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0013</td></tr> - <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>This message retrieves non-default ‘K’ values - for internal and leaf nodes of a group or indexed storage v1 - B-trees. This message is <em>only</em> found in the superblock - extension.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - B-tree ‘K’ Values Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td colspan="2">Indexed Storage Internal Node K</td> - <td bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="2">Group Internal Node K</td> - <td colspan="2">Group Leaf Node K</td> - </tr> - </table> - </div> + <tr> + <td colspan="2"><b>Header Message Name:</b> B-tree + ‘K’ Values</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0013</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Fixed</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>This message retrieves non-default ‘K’ values + for internal and leaf nodes of a group or indexed storage v1 + B-trees. This message is <em>only</em> found in the superblock + extension. + </td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number for this message. This document describes - version 0.</p> - </td> - </tr> - - <tr> - <td><p>Indexed Storage Internal Node K</p></td> - <td><p>This is the node ‘K’ value for each internal node of an - indexed storage v1 B-tree. See the description of this field - in version 0 and 1 of the superblock as well the section on - v1 B-trees. - </p> - </td> - </tr> - - <tr> - <td><p>Group Internal Node K</p></td> - <td><p>This is the node ‘K’ value for each internal node of a group - v1 B-tree. See the description of this field in version 0 and - 1 of the superblock as well as the section on v1 B-trees. - </p> - </td> - </tr> - - <tr> - <td><p>Group Leaf Node K</p></td> - <td><p>This is the node ‘K’ value for each leaf node of a group v1 - B-tree. See the description of this field in version 0 and 1 - of the superblock as well as the section on v1 B-trees. - </p> - </td> - </tr> +<div align="center"> + <table class="format"> + <caption>B-tree ‘K’ Values Message</caption> - </table> - </div> + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="2">Indexed Storage Internal Node K</td> + <td bgcolor="#DDDDDD"><em>This space inserted only to align + table nicely</em></td> + </tr> + + <tr> + <td colspan="2">Group Internal Node K</td> + <td colspan="2">Group Leaf Node K</td> + </tr> + </table> +</div> <br /> -<h4><a name="DrvInfoMessage">IV.A.2.u. The Driver Info -Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document + describes version 0.</p></td> + </tr> + + <tr> + <td><p>Indexed Storage Internal Node K</p></td> + <td><p>This is the node ‘K’ value for each + internal node of an indexed storage v1 B-tree. See the description + of this field in version 0 and 1 of the superblock as well the + section on v1 B-trees.</p></td> + </tr> + + <tr> + <td><p>Group Internal Node K</p></td> + <td><p>This is the node ‘K’ value for each + internal node of a group v1 B-tree. See the description of this + field in version 0 and 1 of the superblock as well as the section + on v1 B-trees.</p></td> + </tr> + + <tr> + <td><p>Group Leaf Node K</p></td> + <td><p>This is the node ‘K’ value for each leaf + node of a group v1 B-tree. See the description of this field in + version 0 and 1 of the superblock as well as the section on v1 + B-trees.</p></td> + </tr> + + </table> +</div> + +<br /> +<h4> + <a name="DrvInfoMessage">IV.A.2.u. The Driver Info Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Driver - Info</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0014</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - - <tr><td> - <b>Description:</b></td> - <td>This message contains information needed by the file driver - to reopen a file. This message is <em>only</em> found in the - superblock extension: see the <a href="#SuperblockExt"> - “Disk Format: Level 0C - Superblock Extension”</a> - section for more information. For more information on the fields - in the driver info message, see the <a href="#DriverInfo"> - “Disk Format : Level 0B - File Driver Info”</a> - section; those who use the multi and family file drivers will - find this section particularly helpful.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Driver Info Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - <tr> - <td colspan="4"><br />Driver Identification</td> - </tr> - - <tr> - <td colspan="2">Driver Information Size</td> - <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4"><br /><br />Driver Information <em>(variable size)</em><br /><br /><br /></td> - </tr> + <tr> + <td colspan="2"><b>Header Message Name:</b> Driver Info</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0014</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> - </table> - </div> + <tr> + <td><b>Description:</b></td> + <td>This message contains information needed by the file driver + to reopen a file. This message is <em>only</em> found in the + superblock extension: see the <a href="#SuperblockExt"> + “Disk Format: Level 0C - Superblock Extension”</a> section + for more information. For more information on the fields in the + driver info message, see the <a href="#DriverInfo"> “Disk + Format : Level 0B - File Driver Info”</a> section; those who use + the multi and family file drivers will find this section + particularly helpful. + </td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number for this message. This document describes - version 0.</p> - </td> - </tr> - - <tr> - <td><p>Driver Identification</p></td> - <td><p>This is an eight-byte ASCII string without null termination which - identifies the driver. - </p> - </td> - </tr> - - <tr> - <td><p>Driver Information Size</p></td> - <td><p>The size in bytes of the <em>Driver Information</em> field of this - message.</p> - </td> - </tr> - - <tr> - <td><p>Driver Information</p></td> - <td><p>Driver information is stored in a format defined by the file driver.</p> - </td> - </tr> - </table> - </div> +<div align="center"> + <table class="format"> + <caption>Driver Info Message</caption> + + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + <tr> + <td colspan="4"><br />Driver Identification</td> + </tr> + + <tr> + <td colspan="2">Driver Information Size</td> + <td colspan="2" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4"><br /> + <br />Driver Information <em>(variable size)</em><br /> + <br /> + <br /></td> + </tr> + + </table> +</div> <br /> -<h4><a name="AinfoMessage">IV.A.2.v. The Attribute Info -Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document + describes version 0.</p></td> + </tr> + + <tr> + <td><p>Driver Identification</p></td> + <td><p>This is an eight-byte ASCII string without null + termination which identifies the driver.</p></td> + </tr> + + <tr> + <td><p>Driver Information Size</p></td> + <td><p> + The size in bytes of the <em>Driver Information</em> field of this + message. + </p></td> + </tr> + + <tr> + <td><p>Driver Information</p></td> + <td><p>Driver information is stored in a format defined by + the file driver.</p></td> + </tr> + </table> +</div> + +<br /> +<h4> + <a name="AinfoMessage">IV.A.2.v. The Attribute Info Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Attribute - Info</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0015</td></tr> - <tr><td colspan="2"><b>Length:</b> Varies</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>This message stores information about the attributes on an - object, such as the maximum creation index for the attributes - created and the location of the attribute storage when the - attributes are stored “densely”.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Attribute Info Message - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Flags</td> - <td colspan="2">Maximum Creation Index <em>(optional)</em></td> - </tr> - <tr> - <td colspan="4"><br />Fractal Heap Address<sup>O</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4"><br />Attribute Name v2 B-tree Address<sup>O</sup><br /><br /></td> - </tr> - <tr> - <td colspan="4"><br />Attribute Creation Order v2 B-tree Address<sup>O</sup> <em>(optional)</em><br /><br /></td> - </tr> + <tr> + <td colspan="2"><b>Header Message Name:</b> Attribute Info</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0015</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Varies</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>This message stores information about the attributes on an + object, such as the maximum creation index for the attributes + created and the location of the attribute storage when the + attributes are stored “densely”.</td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - </table> +<div align="center"> + <table class="format"> + <caption>Attribute Info Message</caption> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> - </table> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td>Flags</td> + <td colspan="2">Maximum Creation Index <em>(optional)</em></td> + </tr> + <tr> + <td colspan="4"><br />Fractal Heap Address<sup>O</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4"><br />Attribute Name v2 B-tree Address<sup>O</sup><br /> + <br /></td> + </tr> + <tr> + <td colspan="4"><br />Attribute Creation Order v2 B-tree + Address<sup>O</sup> <em>(optional)</em><br /> + <br /></td> + </tr> - </div> + </table> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number for this message. This document describes - version 0.</p> - </td> - </tr> - - <tr> - <td><p>Flags</p></td> - <td><p>This is the attribute index information flag with the - following definition: - - <table class="list"> - <tr> - <th width="20%" align="center">Bit</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>0</code></td> - <td>If set, creation order for attributes is tracked. - </td> - </tr> - <tr> - <td align="center"><code>1</code></td> - <td>If set, creation order for attributes is indexed. - </td> - </tr> - <tr> - <td align="center"><code>2-7</code></td> - <td>Reserved</td> - </tr> - </table></p> - - </td> - </tr> - - <tr> - <td><p>Maximum Creation Index</p></td> - <td><p>The is the maximum creation order index value for the - attributes on the object.</p> - <p>This field is present if bit 0 of <em>Flags</em> is set.</p> - </td> - </tr> - - <tr> - <td><p>Fractal Heap Address</p></td> - <td><p>This is the address of the fractal heap to store dense - attributes.</p> - </td> - </tr> - - <tr> - <td><p>Attribute Name v2 B-tree Address</p></td> - <td><p>This is the address of the version 2 B-tree to index the - names of densely stored attributes.</p> - </td> - </tr> - - <tr> - <td><p>Attribute Creation Order v2 B-tree Address</p></td> - <td><p>This is the address of the version 2 B-tree to index the - creation order of densely stored attributes.</p> - <p>This field is present if bit 1 of <em>Flags</em> is set.</p> - </td> - </tr> + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + </table> - </table> - </div> +</div> <br /> -<h4><a name="RefCountMessage">IV.A.2.w. The Object Reference -Count Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document + describes version 0.</p></td> + </tr> + + <tr> + <td><p>Flags</p></td> + <td><p>This is the attribute index information flag with the + following definition:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Bit</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>0</code></td> + <td>If set, creation order for attributes is tracked.</td> + </tr> + <tr> + <td align="center"><code>1</code></td> + <td>If set, creation order for attributes is indexed.</td> + </tr> + <tr> + <td align="center"><code>2-7</code></td> + <td>Reserved</td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Maximum Creation Index</p></td> + <td><p>The is the maximum creation order index value for the + attributes on the object.</p> + <p> + This field is present if bit 0 of <em>Flags</em> is set. + </p></td> + </tr> + + <tr> + <td><p>Fractal Heap Address</p></td> + <td><p>This is the address of the fractal heap to store + dense attributes.</p></td> + </tr> + + <tr> + <td><p>Attribute Name v2 B-tree Address</p></td> + <td><p>This is the address of the version 2 B-tree to index + the names of densely stored attributes.</p></td> + </tr> + + <tr> + <td><p>Attribute Creation Order v2 B-tree Address</p></td> + <td><p>This is the address of the version 2 B-tree to index + the creation order of densely stored attributes.</p> + <p> + This field is present if bit 1 of <em>Flags</em> is set. + </p></td> + </tr> + + </table> +</div> + +<br /> +<h4> + <a name="RefCountMessage">IV.A.2.w. The Object Reference Count + Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> Object Reference - Count</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0016</td></tr> - <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td><b>Description:</b></td> - <td>This message stores the number of hard links (in groups or - objects) pointing to an object: in other words, its - <em>reference count</em>.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - Object Reference Count - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted only to align table nicely</em></td> - </tr> - - <tr> - <td colspan="4">Reference count</td> - </tr> - </table> - </div> + <tr> + <td colspan="2"><b>Header Message Name:</b> Object Reference + Count</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0016</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Fixed</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>This message stores the number of hard links (in groups or + objects) pointing to an object: in other words, its <em>reference + count</em>. + </td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>The version number for this message. This document describes - version 0.</p> - </td> - </tr> - - <tr> - <td><p>Reference Count</p></td> - <td><p>The unsigned 32-bit integer is the reference count for the - object. This message is only present in “version 2” - (or later) object headers, and if not present those object - header versions, the reference count for the object is assumed - to be 1.</p> - </td> - </tr> +<div align="center"> + <table class="format"> + <caption>Object Reference Count</caption> - </table> - </div> + <tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr> + <td>Version</td> + <td colspan="3" bgcolor="#DDDDDD"><em>This space inserted + only to align table nicely</em></td> + </tr> + + <tr> + <td colspan="4">Reference count</td> + </tr> + </table> +</div> <br /> -<h4><a name="FsinfoMessage">IV.A.2.x. The File Space Info -Message</a></h4> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> - <!-- start msgdesc table --> - <center> + <tr> + <td><p>Version</p></td> + <td><p>The version number for this message. This document + describes version 0.</p></td> + </tr> + + <tr> + <td><p>Reference Count</p></td> + <td><p>The unsigned 32-bit integer is the reference count + for the object. This message is only present in “version + 2” (or later) object headers, and if not present those object + header versions, the reference count for the object is assumed to + be 1.</p></td> + </tr> + + </table> +</div> + +<br /> +<h4> + <a name="FsinfoMessage">IV.A.2.x. The File Space Info Message</a> +</h4> + +<!-- start msgdesc table --> +<center> <table class="msgdesc"> - <tr><td colspan="2"><b>Header Message Name:</b> File Space - Info</td></tr> - <tr><td colspan="2"><b>Header Message Type:</b> 0x0018</td></tr> - <tr><td colspan="2"><b>Length:</b> Fixed</td></tr> - <tr><td colspan="2"><b>Status:</b> Optional; may not be - repeated.</td></tr> - <tr><td> - <b>Description:</b></td> - <td>This message stores the file space management strategy (see - description below) that the library uses in handling file space - request for the file. It also contains the free-space section - threshold used by the library’s free-space managers for - the file. If the strategy is 1, this message also contains the - addresses of the file’s free-space managers which track - free space for each type of file space allocation. There are - six basic types of file space allocation: superblock, B-tree, - raw data, global heap, local heap, and object header. See the - description of <a href="#FreeSpaceManager">Free-space - Manager</a> as well the description of allocation types in - <a href="#AppendixB">Appendix B</a>.</td></tr> - <tr><td colspan="2"><b>Format of Data:</b> See the tables - below.</td></tr> - </table></center> - <!-- end msgdesc table --> - - <div align="center"> - <table class="format"> - <caption> - File Space Info - </caption> - - <tr> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - <th width="25%">byte</th> - </tr> - - <tr> - <td>Version</td> - <td>Strategy</td> - <td colspan="2">Threshold<sup>L</sup></td> - </tr> - <tr> - <td colspan="4">Super-block Free-space Manager Address<sup>O</sup></td> - </tr> - <tr> - <td colspan="4">B-tree Free-space Manager Address<sup>O</sup></td> - </tr> - <tr> - <td colspan="4">Raw Data Free-space Manager Address<sup>O</sup></td> - </tr> - <tr> - <td colspan="4">Global Heap Free-space Manager Address<sup>O</sup></td> - </tr> - <tr> - <td colspan="4">Local Heap Free-space Manager Address<sup>O</sup></td> - </tr> - <tr> - <td colspan="4">Object Header Free-space Manager Address<sup>O</sup></td> - </tr> - </table> + <tr> + <td colspan="2"><b>Header Message Name:</b> File Space Info</td> + </tr> + <tr> + <td colspan="2"><b>Header Message Type:</b> 0x0018</td> + </tr> + <tr> + <td colspan="2"><b>Length:</b> Fixed</td> + </tr> + <tr> + <td colspan="2"><b>Status:</b> Optional; may not be repeated.</td> + </tr> + <tr> + <td><b>Description:</b></td> + <td>This message stores the file space management strategy (see + description below) that the library uses in handling file space + request for the file. It also contains the free-space section + threshold used by the library’s free-space managers for the + file. If the strategy is 1, this message also contains the addresses + of the file’s free-space managers which track free space for + each type of file space allocation. There are six basic types of + file space allocation: superblock, B-tree, raw data, global heap, + local heap, and object header. See the description of <a + href="#FreeSpaceManager">Free-space Manager</a> as well the + description of allocation types in <a href="#AppendixB">Appendix + B</a>. + </td> + </tr> + <tr> + <td colspan="2"><b>Format of Data:</b> See the tables below.</td> + </tr> + </table> +</center> +<!-- end msgdesc table --> + +<div align="center"> + <table class="format"> + <caption>File Space Info</caption> - <table class="note"> <tr> - <td width="60%"> </td> - <td width="40%"> - (Items marked with an ‘O’ in the above table are of the size - specified in “Size of Offsets” field in the superblock.) - </td></tr> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + <tr> - <td> </td> - <td> - (Items marked with an ‘L’ in the above table are of the size - specified in “Size of Lengths” field in the superblock.) - </td></tr> - </table> + <td>Version</td> + <td>Strategy</td> + <td colspan="2">Threshold<sup>L</sup></td> + </tr> + <tr> + <td colspan="4">Super-block Free-space Manager Address<sup>O</sup></td> + </tr> + <tr> + <td colspan="4">B-tree Free-space Manager Address<sup>O</sup></td> + </tr> + <tr> + <td colspan="4">Raw Data Free-space Manager Address<sup>O</sup></td> + </tr> + <tr> + <td colspan="4">Global Heap Free-space Manager Address<sup>O</sup></td> + </tr> + <tr> + <td colspan="4">Local Heap Free-space Manager Address<sup>O</sup></td> + </tr> + <tr> + <td colspan="4">Object Header Free-space Manager Address<sup>O</sup></td> + </tr> + </table> + + <table class="note"> + <tr> + <td width="60%"> </td> + <td width="40%">(Items marked with an ‘O’ in the + above table are of the size specified in “Size of + Offsets” field in the superblock.)</td> + </tr> + <tr> + <td> </td> + <td>(Items marked with an ‘L’ in the above table are + of the size specified in “Size of Lengths” field in the + superblock.)</td> + </tr> + </table> - </div> +</div> - <br /> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Field Name</th> - <th>Description</th> - </tr> - - <tr> - <td><p>Version</p></td> - <td><p>This is the version number of this message. This document describes - version 0.</p> - </td> - </tr> - - <tr> - <td><p>Strategy</p></td> - <td><p>This is the file space management strategy for the file. - There are four types of strategies: - <table class="list"> - <tr> - <th width="20%" align="center">Value</th> - <th width="80%" align="left">Description</th> - </tr> - - <tr> - <td align="center"><code>1</code></td> - <td>With this strategy, the HDF5 Library’s free-space managers track the - free space that results from the manipulation of HDF5 objects - in the HDF5 file. The free space information is saved when the - file is closed, and reloaded when the file is reopened. - <br /> - When space is needed for file metadata or raw data, - the HDF5 Library first requests space from the library’s free-space - managers. If the request is not satisfied, the library requests space - from the aggregators. If the request is still not satisfied, - the library requests space from the virtual file driver. - That is, the library will use all of the mechanisms for allocating - space. - </td> - </tr> - - <tr> - <td align="center"><code>2</code></td> - <td>This is the HDF5 Library’s default file space management strategy. - With this strategy, the library’s free-space managers track the free space - that results from the manipulation of HDF5 objects in the HDF5 file. - The free space information is NOT saved when the file is closed and - the free space that exists upon file closing becomes unaccounted - space in the file. - <br /> - As with strategy #1, the library will try all of the mechanisms - for allocating space. When space is needed for file metadata or - raw data, the library first requests space from the free-space - managers. If the request is not satisfied, the library requests - space from the aggregators. If the request is still not satisfied, - the library requests space from the virtual file driver. - </td> - </tr> - - <tr> - <td align="center"><code>3</code></td> - <td>With this strategy, the HDF5 Library does not track free space that results - from the manipulation of HDF5 objects in the HDF5 file and - the free space becomes unaccounted space in the file. - <br /> - When space is needed for file metadata or raw data, - the library first requests space from the aggregators. - If the request is not satisfied, the library requests space from - the virtual file driver. - </td> - </tr> - <tr> - <td align="center"><code>4</code></td> - <td>With this strategy, the HDF5 Library does not track free space that results - from the manipulation of HDF5 objects in the HDF5 file and - the free space becomes unaccounted space in the file. - <br /> - When space is needed for file metadata or raw data, - the library requests space from the virtual file driver. - </td> - </tr> - </table></p> - </td> - </tr> - - <tr> - <td><p>Threshold</p></td> - <td><p>This is the free-space section threshold. - The library’s free-space managers will track only - free-space sections with size greater than or equal to - <em>threshold</em>. The default is to track free-space - sections of all sizes.</p> - </td> - </tr> - <tr> - <td><p>Superblock Free-space Manager Address</p></td> - <td><p>This is the address of the free-space manager for - H5FD_MEM_SUPER allocation type. - </p> - </td> - </tr> - - <tr> - <td><p>B-tree Free-space Manager Address</p></td> - <td><p>This is the address of the free-space manager for - H5FD_MEM_BTREE allocation type. - </p> - </td> - </tr> - - <tr> - <td><p>Raw Data Free-space Manager Address</p></td> - <td><p>This is the address of the free-space manager for - H5FD_MEM_DRAW allocation type. - </p> - </td> - </tr> - - <tr> - <td><p>Global Heap Free-space Manager Address</p></td> - <td><p>This is the address of the free-space manager for - H5FD_MEM_GHEAP allocation type. - </p> - </td> - </tr> - - <tr> - <td><p>Local Heap Free-space Manager Address</p></td> - <td><p>This is the address of the free-space manager for - H5FD_MEM_LHEAP allocation type. - </p> - </td> - </tr> - - <tr> - <td><p>Object Header Free-space Manager Address</p></td> - <td><p>This is the address of the free-space manager for - H5FD_MEM_OHDR allocation type. - </p> - </td> - </tr> - </table> - </div> - <br /> +<br /> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Field Name</th> + <th>Description</th> + </tr> + + <tr> + <td><p>Version</p></td> + <td><p>This is the version number of this message. This + document describes version 0.</p></td> + </tr> + + <tr> + <td><p>Strategy</p></td> + <td><p>This is the file space management strategy for the + file. There are four types of strategies:</p> + <table class="list"> + <tr> + <th width="20%" align="center">Value</th> + <th width="80%" align="left">Description</th> + </tr> + + <tr> + <td align="center"><code>1</code></td> + <td>With this strategy, the HDF5 Library’s free-space + managers track the free space that results from the manipulation + of HDF5 objects in the HDF5 file. The free space information is + saved when the file is closed, and reloaded when the file is + reopened. <br /> When space is needed for file metadata or raw + data, the HDF5 Library first requests space from the + library’s free-space managers. If the request is not + satisfied, the library requests space from the aggregators. If + the request is still not satisfied, the library requests space + from the virtual file driver. That is, the library will use all + of the mechanisms for allocating space. + </td> + </tr> + + <tr> + <td align="center"><code>2</code></td> + <td>This is the HDF5 Library’s default file space + management strategy. With this strategy, the library’s + free-space managers track the free space that results from the + manipulation of HDF5 objects in the HDF5 file. The free space + information is NOT saved when the file is closed and the free + space that exists upon file closing becomes unaccounted space in + the file. <br /> As with strategy #1, the library will try all + of the mechanisms for allocating space. When space is needed for + file metadata or raw data, the library first requests space from + the free-space managers. If the request is not satisfied, the + library requests space from the aggregators. If the request is + still not satisfied, the library requests space from the virtual + file driver. + </td> + </tr> + + <tr> + <td align="center"><code>3</code></td> + <td>With this strategy, the HDF5 Library does not track free + space that results from the manipulation of HDF5 objects in the + HDF5 file and the free space becomes unaccounted space in the + file. <br /> When space is needed for file metadata or raw data, + the library first requests space from the aggregators. If the + request is not satisfied, the library requests space from the + virtual file driver. + </td> + </tr> + <tr> + <td align="center"><code>4</code></td> + <td>With this strategy, the HDF5 Library does not track free + space that results from the manipulation of HDF5 objects in the + HDF5 file and the free space becomes unaccounted space in the + file. <br /> When space is needed for file metadata or raw data, + the library requests space from the virtual file driver. + </td> + </tr> + </table> + <p></p></td> + </tr> + + <tr> + <td><p>Threshold</p></td> + <td><p> + This is the free-space section threshold. The library’s + free-space managers will track only free-space sections with size + greater than or equal to <em>threshold</em>. The default is to + track free-space sections of all sizes. + </p></td> + </tr> + <tr> + <td><p>Superblock Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_SUPER allocation type.</p></td> + </tr> + + <tr> + <td><p>B-tree Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_BTREE allocation type.</p></td> + </tr> + + <tr> + <td><p>Raw Data Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_DRAW allocation type.</p></td> + </tr> + + <tr> + <td><p>Global Heap Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_GHEAP allocation type.</p></td> + </tr> + + <tr> + <td><p>Local Heap Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_LHEAP allocation type.</p></td> + </tr> + + <tr> + <td><p>Object Header Free-space Manager Address</p></td> + <td><p>This is the address of the free-space manager for + H5FD_MEM_OHDR allocation type.</p></td> + </tr> + </table> +</div> +<br /> <br /> -<h3><a name="DataStorage"> -IV.B. Disk Format: Level 2B - Data Object Data Storage</a></h3> +<h3> + <a name="DataStorage"> IV.B. Disk Format: Level 2B - Data Object + Data Storage</a> +</h3> <p>The data for an object is stored separately from its header - information in the file and may not actually be located in the HDF5 file - itself if the header indicates that the data is stored externally. The - information for each record in the object is stored according to the - dimensionality of the object (indicated in the dataspace header message). - Multi-dimensional array data is stored in C order; in other words, the - “last” dimension changes fastest.</p> - -<p>Data whose elements are composed of atomic datatypes are stored in IEEE - format, unless they are specifically defined as being stored in a different - machine format with the architecture-type information from the datatype - header message. This means that each architecture will need to [potentially] - byte-swap data values into the internal representation for that particular - machine.</p> - -<p> Data with a variable-length datatype is stored in the global heap - of the HDF5 file. Global heap identifiers are stored in the - data object storage.</p> - -<p>Data whose elements are composed of reference datatypes are stored in - several different ways depending on the particular reference type involved. - Object pointers are just stored as the offset of the object header being - pointed to with the size of the pointer being the same number of bytes as - offsets in the file.</p> + information in the file and may not actually be located in the HDF5 + file itself if the header indicates that the data is stored externally. + The information for each record in the object is stored according to + the dimensionality of the object (indicated in the dataspace header + message). Multi-dimensional array data is stored in C order; in other + words, the “last” dimension changes fastest.</p> + +<p>Data whose elements are composed of atomic datatypes are stored + in IEEE format, unless they are specifically defined as being stored in + a different machine format with the architecture-type information from + the datatype header message. This means that each architecture will + need to [potentially] byte-swap data values into the internal + representation for that particular machine.</p> + +<p>Data with a variable-length datatype is stored in the global heap + of the HDF5 file. Global heap identifiers are stored in the data object + storage.</p> + +<p>Data whose elements are composed of reference datatypes are + stored in several different ways depending on the particular reference + type involved. Object pointers are just stored as the offset of the + object header being pointed to with the size of the pointer being the + same number of bytes as offsets in the file.</p> <p>Dataset region references are stored as a heap-ID which points to -the following information within the file-heap: an offset of the object -pointed to, number-type information (same format as header message), -dimensionality information (same format as header message), sub-set start -and end information (in other words, a coordinate location for each), -and field start and end names (in other words, a [pointer to the] string -indicating the first field included and a [pointer to the] string name -for the last field). </p> + the following information within the file-heap: an offset of the object + pointed to, number-type information (same format as header message), + dimensionality information (same format as header message), sub-set + start and end information (in other words, a coordinate location for + each), and field start and end names (in other words, a [pointer to + the] string indicating the first field included and a [pointer to the] + string name for the last field).</p> -<p>Data of a compound datatype is stored as a contiguous stream of the items - in the structure, with each item formatted according to its datatype.</p> +<p>Data of a compound datatype is stored as a contiguous stream of + the items in the structure, with each item formatted according to its + datatype.</p> <br /> <br /> <hr /> -<h2><a name="AppendixA"> -V. Appendix A: Definitions</a></h2> +<h2> + <a name="AppendixA"> V. Appendix A: Definitions</a> +</h2> -<p>Definitions of various terms used in this document are included in -this section.</p> +<p>Definitions of various terms used in this document are included + in this section.</p> - <div align="center"> +<div align="center"> <table class="glossary"> - <tr> - <th width="20%">Term</th> - <th>Definition</th> - </tr> + <tr> + <th width="20%">Term</th> + <th>Definition</th> + </tr> - <tr> - <td>Undefined Address</td> - <td>The <a name="UndefinedAddress">undefined - address</a> for a file is a file address with all bits - set: in other words, <code>0xffff...ff</code>.</td> - </tr> + <tr> + <td>Undefined Address</td> + <td>The <a name="UndefinedAddress">undefined address</a> for a + file is a file address with all bits set: in other words, <code>0xffff...ff</code>. + </td> + </tr> - <tr> - <td>Unlimited Size</td> - <td>The <a name="UnlimitedDim">unlimited size</a> - for a size is a value with all bits set: in other words, - <code>0xffff...ff</code>.</td> - </tr> + <tr> + <td>Unlimited Size</td> + <td>The <a name="UnlimitedDim">unlimited size</a> for a size is + a value with all bits set: in other words, <code>0xffff...ff</code>. + </td> + </tr> </table> - </div> +</div> <br /> <br /> <hr /> -<h2><a name="AppendixB"> -VI. Appendix B: File Memory Allocation Types</a></h2> +<h2> + <a name="AppendixB"> VI. Appendix B: File Memory Allocation Types</a> +</h2> -<p>There are six basic types of file memory allocation as follows: -</p> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Basic Allocation Type</th> - <th>Description</th> - </tr> - - <tr> - <td>H5FD_MEM_SUPER</td> - <td>File memory allocated for <em>Superblock.</em></td> - </tr> - - <tr> - <td>H5FD_MEM_BTREE</td> - <td>File memory allocated for <em>B-tree.</em></td> - </tr> - - <tr> - <td>H5FD_MEM_DRAW</td> - <td>File memory allocated for raw data.</td> - </tr> - - <tr> - <td>H5FD_MEM_GHEAP</td> - <td>File memory allocated for <em>Global Heap.</em></td> - </tr> - - <tr> - <td>H5FD_MEM_LHEAP</td> - <td>File memory allocated for <em>Local Heap.</em></td> - </tr> - - <tr> - <td>H5FD_MEM_OHDR</td> - <td>File memory allocated for <em>Object Header.</em></td> - </tr> - </table> - </div> +<p>There are six basic types of file memory allocation as follows:</p> +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Basic Allocation Type</th> + <th>Description</th> + </tr> -<p>There are other file memory allocation types that are mapped to the -above six basic allocation types because they are similar in nature. -The mapping is listed in the following table: -</p> + <tr> + <td>H5FD_MEM_SUPER</td> + <td>File memory allocated for <em>Superblock.</em></td> + </tr> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Basic Allocation Type</th> - <th>Mapping of Allocation Types to Basic Allocation Types</th> - </tr> - - <tr> - <td>H5FD_MEM_SUPER</td> - <td><em>none</em></td> - </tr> - - <tr> - <td>H5FD_MEM_BTREE</td> - <td>H5FD_MEM_SOHM_INDEX</td> - </tr> - - <tr> - <td>H5FD_MEM_DRAW</td> - <td>H5FD_MEM_FHEAP_HUGE_OBJ</td> - </tr> - - <tr> - <td>H5FD_MEM_GHEAP</td> - <td><em>none</em></td> - </tr> - - <tr> - <td>H5FD_MEM_LHEAP</td> - <td>H5FD_MEM_FHEAP_DBLOCK, H5FD_MEM_FSPACE_SINFO</td> - </tr> - - <tr> - <td>H5FD_MEM_OHDR</td> - <td>H5FD_MEM_FHEAP_HDR, H5FD_MEM_FHEAP_IBLOCK, H5FD_MEM_FSPACE_HDR, H5FD_MEM_SOHM_TABLE</td> - </tr> - </table> - </div> + <tr> + <td>H5FD_MEM_BTREE</td> + <td>File memory allocated for <em>B-tree.</em></td> + </tr> -<p>Allocation types that are mapped to basic allocation types are described below: -</p> + <tr> + <td>H5FD_MEM_DRAW</td> + <td>File memory allocated for raw data.</td> + </tr> - <div align="center"> - <table class="desc"> - <tr> - <th width="30%">Allocation Type</th> - <th>Description</th> - </tr> - - <tr> - <td>H5FD_MEM_FHEAP_HDR</td> - <td>File memory allocated for <em>Fractal Heap Header.</em></td> - </tr> - - <tr> - <td>H5FD_MEM_FHEAP_DBLOCK</td> - <td>File memory allocated for <em>Fractal Heap Direct Blocks.</em></td> - </tr> - - <tr> - <td>H5FD_MEM_FHEAP_IBLOCK</td> - <td>File memory allocated for <em>Fractal Heap Indirect Blocks.</em></td> - </tr> - - <tr> - <td>H5FD_MEM_FHEAP_HUGE_OBJ</td> - <td>File memory allocated for huge objects in the fractal heap.</td> - </tr> - - <tr> - <td>H5FD_MEM_FSPACE_HDR</td> - <td>File memory allocated for <em>Free-space Manager Header.</em></td> - </tr> - - <tr> - <td>H5FD_MEM_FSPACE_SINFO</td> - <td>File memory allocated for <em>Free-space Section List</em> of the free-space manager.</td> - </tr> - <tr> - <td>H5FD_MEM_SOHM_TABLE</td> - <td>File memory allocated for <em>Shared Object Header Message Table.</em></td> - </tr> - <tr> - <td>H5FD_MEM_SOHM_INDEX</td> - <td>File memory allocated for <em>Shared Message Record List.</em></td> - </tr> - </table> - </div> -</body> + <tr> + <td>H5FD_MEM_GHEAP</td> + <td>File memory allocated for <em>Global Heap.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_LHEAP</td> + <td>File memory allocated for <em>Local Heap.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_OHDR</td> + <td>File memory allocated for <em>Object Header.</em></td> + </tr> + </table> +</div> + +<p>There are other file memory allocation types that are mapped to + the above six basic allocation types because they are similar in + nature. The mapping is listed in the following table:</p> + +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Basic Allocation Type</th> + <th>Mapping of Allocation Types to Basic Allocation Types</th> + </tr> + + <tr> + <td>H5FD_MEM_SUPER</td> + <td><em>none</em></td> + </tr> + + <tr> + <td>H5FD_MEM_BTREE</td> + <td>H5FD_MEM_SOHM_INDEX</td> + </tr> + + <tr> + <td>H5FD_MEM_DRAW</td> + <td>H5FD_MEM_FHEAP_HUGE_OBJ</td> + </tr> + + <tr> + <td>H5FD_MEM_GHEAP</td> + <td><em>none</em></td> + </tr> + + <tr> + <td>H5FD_MEM_LHEAP</td> + <td>H5FD_MEM_FHEAP_DBLOCK, H5FD_MEM_FSPACE_SINFO</td> + </tr> + + <tr> + <td>H5FD_MEM_OHDR</td> + <td>H5FD_MEM_FHEAP_HDR, H5FD_MEM_FHEAP_IBLOCK, + H5FD_MEM_FSPACE_HDR, H5FD_MEM_SOHM_TABLE</td> + </tr> + </table> +</div> + +<p>Allocation types that are mapped to basic allocation types are + described below:</p> + +<div align="center"> + <table class="desc"> + <tr> + <th width="30%">Allocation Type</th> + <th>Description</th> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_HDR</td> + <td>File memory allocated for <em>Fractal Heap Header.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_DBLOCK</td> + <td>File memory allocated for <em>Fractal Heap Direct + Blocks.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_IBLOCK</td> + <td>File memory allocated for <em>Fractal Heap Indirect + Blocks.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FHEAP_HUGE_OBJ</td> + <td>File memory allocated for huge objects in the fractal heap.</td> + </tr> + + <tr> + <td>H5FD_MEM_FSPACE_HDR</td> + <td>File memory allocated for <em>Free-space Manager + Header.</em></td> + </tr> + + <tr> + <td>H5FD_MEM_FSPACE_SINFO</td> + <td>File memory allocated for <em>Free-space Section List</em> + of the free-space manager. + </td> + </tr> + <tr> + <td>H5FD_MEM_SOHM_TABLE</td> + <td>File memory allocated for <em>Shared Object Header + Message Table.</em></td> + </tr> + <tr> + <td>H5FD_MEM_SOHM_INDEX</td> + <td>File memory allocated for <em>Shared Message Record + List.</em></td> + </tr> + </table> +</div> +</head> +<body></body> </html> diff --git a/doxygen/examples/H5.format.html b/doxygen/examples/H5.format.html index 47e19bf..9134d35 100644 --- a/doxygen/examples/H5.format.html +++ b/doxygen/examples/H5.format.html @@ -418,7 +418,7 @@ <p>This document describes the lower-level data objects; the higher-level objects and their properties are described - in the <a href="UG/HDF5_Users_Guide-Responsive HTML5/index.html"><cite>HDF5 User’s Guide</cite></a>.</p> + in the <a href="UG/HDF5_User_Guide-Responsive HTML5/index.html"><cite>HDF5 User Guide</cite></a>.</p> <p>Three levels of information comprise the file format. Level 0 contains basic information for identifying and diff --git a/doxygen/examples/ThreadSafeLibrary.html b/doxygen/examples/ThreadSafeLibrary.html index 97f7742..5824dc6 100644 --- a/doxygen/examples/ThreadSafeLibrary.html +++ b/doxygen/examples/ThreadSafeLibrary.html @@ -20,9 +20,9 @@ The following code is placed at the beginning of H5private.h: </blockquote> <p> -<code>H5_HAVE_THREADSAFE</code> is defined when the HDF-5 library is +<code>H5_HAVE_THREADSAFE</code> is defined when the HDF5 library is compiled with the --enable-threadsafe configuration option. In general, -code for the non-threadsafe version of HDF-5 library are placed within +code for the non-threadsafe version of HDF5 library are placed within the <code>#else</code> part of the conditional compilation. The exception to this rule are the changes to the <code>FUNC_ENTER</code> (in H5private.h), <code>HRETURN</code> and <code>HRETURN_ERROR</code> (in @@ -438,7 +438,7 @@ described in Appendix D and may be found in <code>H5TS.c</code>. <p> Except where stated, all tests involve 16 simultaneous threads that make -use of HDF-5 API calls without any explicit synchronization typically +use of HDF5 API calls without any explicit synchronization typically required in a non-threadsafe environment. </p> @@ -453,7 +453,7 @@ dataset's named value. <p> The main thread would join with all 16 threads and attempt to match the -resulting HDF-5 file with expected results - that each dataset contains +resulting HDF5 file with expected results - that each dataset contains the correct value (0 for <i>zero</i>, 1 for <i>one</i> etc ...) and all datasets were correctly created. </p> @@ -473,7 +473,7 @@ name. <p> The error stack implementation runs correctly if it reports 15 instances -of the dataset name conflict error and finally generates a correct HDF-5 +of the dataset name conflict error and finally generates a correct HDF5 containing that single dataset. Each thread should report its own stack of errors with a thread number associated with it. </p> diff --git a/doxygen/examples/core_menu.md b/doxygen/examples/core_menu.md new file mode 100644 index 0000000..3fd7d11 --- /dev/null +++ b/doxygen/examples/core_menu.md @@ -0,0 +1,69 @@ +<b>Core Library</b> + +- @ref H5A "Attributes (H5A)" +<br /> +HDF5 attribute is a small metadata object describing the nature and/or intended usage of a primary data object. + +- @ref H5D "Datasets (H5D)" +<br /> +Manage HDF5 datasets, including the transfer of data between memory and disk and the description of dataset properties. + +- @ref H5S "Dataspaces (H5S)" +<br /> +HDF5 dataspaces describe the shape of datasets in memory or in HDF5 files. + +- @ref H5T "Datatypes (H5T)" +<br /> +HDF5 datatypes describe the element type of HDF5 datasets and attributes. + +- @ref H5E "Error Handling (H5E)" +<br /> +HDF5 library error reporting. + +- @ref H5ES "Event Set (H5ES)" +<br /> +HDF5 event set life cycle used with HDF5 VOL connectors that enable the asynchronous feature in HDF5. + +- @ref H5F "Files (H5F)" +<br /> +Manage HDF5 files. + +- @ref H5Z "Filters (H5Z)" +<br /> +Manage HDF5 user-defined filters + +- @ref H5G "Groups (H5G)" +<br /> +Manage HDF5 groups. + +- @ref H5I "Identifiers (H5I)" +<br /> +Manage identifiers defined by the HDF5 library. + +- @ref H5 "Library General (H5)" +<br /> +Manage the life cycle of HDF5 library instances. + +- @ref H5L "Links (H5L)" +<br /> +Manage HDF5 links and link types. + +- @ref H5O "Objects (H5O)" +<br /> +Manage HDF5 objects (groups, datasets, datatype objects). + +- @ref H5P "Property Lists (H5P)" +<br /> +HDF5 property lists are the main vehicle to configure the behavior of HDF5 API functions. + +- @ref H5PL "Dynamically-loaded Plugins (H5PL)" +<br /> +Manage the loading behavior of HDF5 plugins. + +- @ref H5R "References (H5R)" +<br /> +Manage HDF5 references (HDF5 objects, attributes, and selections on datasets a.k.a. dataset regions). + +- @ref H5VL "VOL Connector (H5VL)" +<br /> +Manage HDF5 VOL connector plugins. diff --git a/doxygen/examples/fortran_menu.md b/doxygen/examples/fortran_menu.md new file mode 100644 index 0000000..8ef4ead --- /dev/null +++ b/doxygen/examples/fortran_menu.md @@ -0,0 +1,73 @@ +<b>Fortran Library</b> + +- @ref FH5A "Attributes (H5A)" +<br /> +HDF5 attribute is a small metadata object describing the nature and/or intended usage of a primary data object. + +- @ref FH5D "Datasets (H5D)" +<br /> +Manage HDF5 datasets, including the transfer of data between memory and disk and the description of dataset properties. + +- @ref FH5S "Dataspaces (H5S)" +<br /> +HDF5 dataspaces describe the shape of datasets in memory or in HDF5 files. + +- @ref FH5T "Datatypes (H5T)" +<br /> +HDF5 datatypes describe the element type of HDF5 datasets and attributes. + +- @ref FH5E "Error Handling (H5E)" +<br /> +HDF5 library error reporting. + +- @ref FH5F "Files (H5F)" +<br /> +Manage HDF5 files. + +- @ref FH5Z "Filters (H5Z)" +<br /> +Manage HDF5 user-defined filters + +- @ref FH5G "Groups (H5G)" +<br /> +Manage HDF5 groups. + +- @ref FH5I "Identifiers (H5I)" +<br /> +Manage identifiers defined by the HDF5 library. + +- @ref FH5 "Library General (H5)" +<br /> +Manage the life cycle of HDF5 library instances. + +- @ref FH5L "Links (H5L)" +<br /> +Manage HDF5 links and link types. + +- @ref FH5O "Objects (H5O)" +<br /> +Manage HDF5 objects (groups, datasets, datatype objects). + +- @ref FH5P "Property Lists (H5P)" +<br /> +HDF5 property lists are the main vehicle to configure the behavior of HDF5 API functions. + +- @ref FH5R "References (H5R)" +<br /> +Manage HDF5 references (HDF5 objects, attributes, and selections on datasets a.k.a. dataset regions). + +- @ref FH5LT "High Level Lite (H5LT)" +<br /> +Functions to simplify creating and manipulating datasets, attributes and other features + +- @ref FH5IM "High Level Image (H5IM)" +<br /> +Creating and manipulating HDF5 datasets intended to be interpreted as images + +- @ref FH5TB "High Level Table (H5TB)" +<br /> +Creating and manipulating HDF5 datasets intended to be interpreted as tables + +- @ref FH5DS "High Level Dimension Scale (H5DS)" +<br /> +Creating and manipulating HDF5 datasets that are associated with the dimension of another HDF5 dataset diff --git a/doxygen/examples/high_level_menu.md b/doxygen/examples/high_level_menu.md new file mode 100644 index 0000000..d209bf4 --- /dev/null +++ b/doxygen/examples/high_level_menu.md @@ -0,0 +1,30 @@ +<b>High-level library</b> +<br /> +The high-level HDF5 library includes several sets of convenience and standard-use APIs to +facilitate common HDF5 operations. + +- @ref H5LT +<br /> +Functions to simplify creating and manipulating datasets, attributes and other features + +- @ref H5IM +<br /> +Creating and manipulating HDF5 datasets intended to be interpreted as images + +- @ref H5TB +<br /> +Creating and manipulating HDF5 datasets intended to be interpreted as tables + +- @ref H5PT +<br /> +Creating and manipulating HDF5 datasets to support append- and read-only operations on table data + +- @ref H5DS +<br /> +Creating and manipulating HDF5 datasets that are associated with the dimension of another HDF5 dataset + +- @ref H5DO +<br /> +Bypassing default HDF5 behavior in order to optimize for specific use cases + +- @ref H5LR "Extensions (H5LR, H5LT)" diff --git a/doxygen/examples/java_menu.md b/doxygen/examples/java_menu.md new file mode 100644 index 0000000..1236838 --- /dev/null +++ b/doxygen/examples/java_menu.md @@ -0,0 +1,84 @@ +<b>Java Library</b> + @ref HDF5LIB + +- @ref JH5 +<br /> +This package is the Java interface for the HDF5 library. + +- @ref JH5A +<br /> +This package is the Java interface for the HDF5 library attribute APIs. + +- @ref JH5D +<br /> +This package is the Java interface for the HDF5 library dataset APIs. + +- @ref JH5S +<br /> +This package is the Java interface for the HDF5 library dataspace APIs. + +- @ref JH5T +<br /> +This package is the Java interface for the HDF5 library datatype APIs. + +- @ref JH5E +<br /> +This package is the Java interface for the HDF5 library error APIs. + +- @ref JH5F +<br /> +This package is the Java interface for the HDF5 library file APIs. + +- @ref JH5Z +<br /> +This package is the Java interface for the HDF5 library filter APIs. + +- @ref JH5G +<br /> +This package is the Java interface for the HDF5 library group APIs. + +- @ref JH5I +<br /> +This package is the Java interface for the HDF5 library identifier APIs. + +- @ref JH5L +<br /> +This package is the Java interface for the HDF5 library links APIs. + +- @ref JH5O +<br /> +This package is the Java interface for the HDF5 library object APIs. + +- @ref JH5P +<br /> +This package is the Java interface for the HDF5 library property list APIs. + +- @ref JH5PL +<br /> +This package is the Java interface for the HDF5 library plugin APIs. + +- @ref JH5R +<br /> +This package is the Java interface for the HDF5 library reference APIs. + +- @ref JH5VL +<br /> +This package is the Java interface for the HDF5 library VOL connector APIs. + +- @ref HDF5CONST +<br /> +This class contains C constants and enumerated types of HDF5 library. + +- @ref HDFNATIVE +<br /> +This class encapsulates native methods to deal with arrays of numbers, + * converting from numbers to bytes and bytes to numbers. + +- @ref HDFARRAY +<br /> +This is a class for handling multidimensional arrays for HDF. + +- @ref ERRORS +<br /> +The class HDF5Exception returns errors from the Java HDF5 Interface. +
\ No newline at end of file diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml index 24642b5..f7c47bf 100644 --- a/doxygen/hdf5doxy_layout.xml +++ b/doxygen/hdf5doxy_layout.xml @@ -3,8 +3,9 @@ <!-- Navigation index tabs for HTML output --> <navindex> <tab type="user" url="index.html" title="Overview" /> - <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/Learning+HDF5" title="Getting started" /> + <tab type="user" url="@ref GettingStarted" title="Getting started" /> <tab type="user" url="@ref Cookbook" title="Cookbook" /> + <tab type="user" url="@ref UG" title="User Guide" /> <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+User+Guides" title="User Guides" /> <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Application+Developer%27s+Guide" title="Application Developer's Guide" /> <tab type="user" url="@ref GLS" title="Glossary" /> diff --git a/doxygen/img/DataGroup.png b/doxygen/img/DataGroup.png Binary files differnew file mode 100644 index 0000000..4edeba3 --- /dev/null +++ b/doxygen/img/DataGroup.png diff --git a/doxygen/img/Dmodel_fig1.gif b/doxygen/img/Dmodel_fig1.gif Binary files differnew file mode 100644 index 0000000..ca8093c --- /dev/null +++ b/doxygen/img/Dmodel_fig1.gif diff --git a/doxygen/img/Dmodel_fig10.gif b/doxygen/img/Dmodel_fig10.gif Binary files differnew file mode 100644 index 0000000..c6a9916 --- /dev/null +++ b/doxygen/img/Dmodel_fig10.gif diff --git a/doxygen/img/Dmodel_fig11_b.gif b/doxygen/img/Dmodel_fig11_b.gif Binary files differnew file mode 100644 index 0000000..19ea9fb --- /dev/null +++ b/doxygen/img/Dmodel_fig11_b.gif diff --git a/doxygen/img/Dmodel_fig12_a.gif b/doxygen/img/Dmodel_fig12_a.gif Binary files differnew file mode 100644 index 0000000..1f597df --- /dev/null +++ b/doxygen/img/Dmodel_fig12_a.gif diff --git a/doxygen/img/Dmodel_fig12_b.gif b/doxygen/img/Dmodel_fig12_b.gif Binary files differnew file mode 100644 index 0000000..f271082 --- /dev/null +++ b/doxygen/img/Dmodel_fig12_b.gif diff --git a/doxygen/img/Dmodel_fig14_a.gif b/doxygen/img/Dmodel_fig14_a.gif Binary files differnew file mode 100644 index 0000000..45d6c6c --- /dev/null +++ b/doxygen/img/Dmodel_fig14_a.gif diff --git a/doxygen/img/Dmodel_fig14_b.gif b/doxygen/img/Dmodel_fig14_b.gif Binary files differnew file mode 100644 index 0000000..12a667d --- /dev/null +++ b/doxygen/img/Dmodel_fig14_b.gif diff --git a/doxygen/img/Dmodel_fig14_c.gif b/doxygen/img/Dmodel_fig14_c.gif Binary files differnew file mode 100644 index 0000000..0c06049 --- /dev/null +++ b/doxygen/img/Dmodel_fig14_c.gif diff --git a/doxygen/img/Dmodel_fig14_d.gif b/doxygen/img/Dmodel_fig14_d.gif Binary files differnew file mode 100644 index 0000000..7cb8956 --- /dev/null +++ b/doxygen/img/Dmodel_fig14_d.gif diff --git a/doxygen/img/Dmodel_fig2.gif b/doxygen/img/Dmodel_fig2.gif Binary files differnew file mode 100644 index 0000000..c2c9d04 --- /dev/null +++ b/doxygen/img/Dmodel_fig2.gif diff --git a/doxygen/img/Dmodel_fig3_a.gif b/doxygen/img/Dmodel_fig3_a.gif Binary files differnew file mode 100644 index 0000000..9f00832 --- /dev/null +++ b/doxygen/img/Dmodel_fig3_a.gif diff --git a/doxygen/img/Dmodel_fig3_c.gif b/doxygen/img/Dmodel_fig3_c.gif Binary files differnew file mode 100644 index 0000000..8529181 --- /dev/null +++ b/doxygen/img/Dmodel_fig3_c.gif diff --git a/doxygen/img/Dmodel_fig4_a.gif b/doxygen/img/Dmodel_fig4_a.gif Binary files differnew file mode 100644 index 0000000..c7fdce1 --- /dev/null +++ b/doxygen/img/Dmodel_fig4_a.gif diff --git a/doxygen/img/Dmodel_fig4_b.gif b/doxygen/img/Dmodel_fig4_b.gif Binary files differnew file mode 100644 index 0000000..34053d5 --- /dev/null +++ b/doxygen/img/Dmodel_fig4_b.gif diff --git a/doxygen/img/Dmodel_fig5.gif b/doxygen/img/Dmodel_fig5.gif Binary files differnew file mode 100644 index 0000000..69e11f5 --- /dev/null +++ b/doxygen/img/Dmodel_fig5.gif diff --git a/doxygen/img/Dmodel_fig6.gif b/doxygen/img/Dmodel_fig6.gif Binary files differnew file mode 100644 index 0000000..bf677c2 --- /dev/null +++ b/doxygen/img/Dmodel_fig6.gif diff --git a/doxygen/img/Dmodel_fig7_b.gif b/doxygen/img/Dmodel_fig7_b.gif Binary files differnew file mode 100644 index 0000000..da27fa0 --- /dev/null +++ b/doxygen/img/Dmodel_fig7_b.gif diff --git a/doxygen/img/Dmodel_fig8.gif b/doxygen/img/Dmodel_fig8.gif Binary files differnew file mode 100644 index 0000000..27305a8 --- /dev/null +++ b/doxygen/img/Dmodel_fig8.gif diff --git a/doxygen/img/Dmodel_fig9.gif b/doxygen/img/Dmodel_fig9.gif Binary files differnew file mode 100644 index 0000000..31893bf --- /dev/null +++ b/doxygen/img/Dmodel_fig9.gif diff --git a/doxygen/img/Dsets_NbitFloating1.gif b/doxygen/img/Dsets_NbitFloating1.gif Binary files differnew file mode 100644 index 0000000..3d3ce19 --- /dev/null +++ b/doxygen/img/Dsets_NbitFloating1.gif diff --git a/doxygen/img/Dsets_NbitFloating2.gif b/doxygen/img/Dsets_NbitFloating2.gif Binary files differnew file mode 100644 index 0000000..cdb5a90 --- /dev/null +++ b/doxygen/img/Dsets_NbitFloating2.gif diff --git a/doxygen/img/Dsets_NbitInteger1.gif b/doxygen/img/Dsets_NbitInteger1.gif Binary files differnew file mode 100644 index 0000000..656fb8d --- /dev/null +++ b/doxygen/img/Dsets_NbitInteger1.gif diff --git a/doxygen/img/Dsets_NbitInteger2.gif b/doxygen/img/Dsets_NbitInteger2.gif Binary files differnew file mode 100644 index 0000000..e100ebe --- /dev/null +++ b/doxygen/img/Dsets_NbitInteger2.gif diff --git a/doxygen/img/Dsets_fig1.gif b/doxygen/img/Dsets_fig1.gif Binary files differnew file mode 100644 index 0000000..c8f3349 --- /dev/null +++ b/doxygen/img/Dsets_fig1.gif diff --git a/doxygen/img/Dsets_fig10.gif b/doxygen/img/Dsets_fig10.gif Binary files differnew file mode 100644 index 0000000..4593cc1 --- /dev/null +++ b/doxygen/img/Dsets_fig10.gif diff --git a/doxygen/img/Dsets_fig11.gif b/doxygen/img/Dsets_fig11.gif Binary files differnew file mode 100644 index 0000000..573701a --- /dev/null +++ b/doxygen/img/Dsets_fig11.gif diff --git a/doxygen/img/Dsets_fig12.gif b/doxygen/img/Dsets_fig12.gif Binary files differnew file mode 100644 index 0000000..d9ddd2b --- /dev/null +++ b/doxygen/img/Dsets_fig12.gif diff --git a/doxygen/img/Dsets_fig2.gif b/doxygen/img/Dsets_fig2.gif Binary files differnew file mode 100644 index 0000000..8ecc2c7 --- /dev/null +++ b/doxygen/img/Dsets_fig2.gif diff --git a/doxygen/img/Dsets_fig3.gif b/doxygen/img/Dsets_fig3.gif Binary files differnew file mode 100644 index 0000000..642715e --- /dev/null +++ b/doxygen/img/Dsets_fig3.gif diff --git a/doxygen/img/Dsets_fig4.gif b/doxygen/img/Dsets_fig4.gif Binary files differnew file mode 100644 index 0000000..a24ccc9 --- /dev/null +++ b/doxygen/img/Dsets_fig4.gif diff --git a/doxygen/img/Dsets_fig5.gif b/doxygen/img/Dsets_fig5.gif Binary files differnew file mode 100644 index 0000000..78c953e --- /dev/null +++ b/doxygen/img/Dsets_fig5.gif diff --git a/doxygen/img/Dsets_fig6.gif b/doxygen/img/Dsets_fig6.gif Binary files differnew file mode 100644 index 0000000..ea15564 --- /dev/null +++ b/doxygen/img/Dsets_fig6.gif diff --git a/doxygen/img/Dsets_fig7.gif b/doxygen/img/Dsets_fig7.gif Binary files differnew file mode 100644 index 0000000..f7f6b9e --- /dev/null +++ b/doxygen/img/Dsets_fig7.gif diff --git a/doxygen/img/Dsets_fig8.gif b/doxygen/img/Dsets_fig8.gif Binary files differnew file mode 100644 index 0000000..91cb6aa --- /dev/null +++ b/doxygen/img/Dsets_fig8.gif diff --git a/doxygen/img/Dsets_fig9.gif b/doxygen/img/Dsets_fig9.gif Binary files differnew file mode 100644 index 0000000..802ca52 --- /dev/null +++ b/doxygen/img/Dsets_fig9.gif diff --git a/doxygen/img/Dspace_CvsF1.gif b/doxygen/img/Dspace_CvsF1.gif Binary files differnew file mode 100644 index 0000000..716b9f1 --- /dev/null +++ b/doxygen/img/Dspace_CvsF1.gif diff --git a/doxygen/img/Dspace_CvsF2.gif b/doxygen/img/Dspace_CvsF2.gif Binary files differnew file mode 100644 index 0000000..716b9f1 --- /dev/null +++ b/doxygen/img/Dspace_CvsF2.gif diff --git a/doxygen/img/Dspace_CvsF3.gif b/doxygen/img/Dspace_CvsF3.gif Binary files differnew file mode 100644 index 0000000..59c31ff --- /dev/null +++ b/doxygen/img/Dspace_CvsF3.gif diff --git a/doxygen/img/Dspace_CvsF4.gif b/doxygen/img/Dspace_CvsF4.gif Binary files differnew file mode 100644 index 0000000..e97b006 --- /dev/null +++ b/doxygen/img/Dspace_CvsF4.gif diff --git a/doxygen/img/Dspace_combine.gif b/doxygen/img/Dspace_combine.gif Binary files differnew file mode 100644 index 0000000..8da2397 --- /dev/null +++ b/doxygen/img/Dspace_combine.gif diff --git a/doxygen/img/Dspace_complex.gif b/doxygen/img/Dspace_complex.gif Binary files differnew file mode 100644 index 0000000..53e92ee --- /dev/null +++ b/doxygen/img/Dspace_complex.gif diff --git a/doxygen/img/Dspace_features.gif b/doxygen/img/Dspace_features.gif Binary files differnew file mode 100644 index 0000000..d94b4e4 --- /dev/null +++ b/doxygen/img/Dspace_features.gif diff --git a/doxygen/img/Dspace_features_cmpd.gif b/doxygen/img/Dspace_features_cmpd.gif Binary files differnew file mode 100644 index 0000000..f24ee99 --- /dev/null +++ b/doxygen/img/Dspace_features_cmpd.gif diff --git a/doxygen/img/Dspace_move.gif b/doxygen/img/Dspace_move.gif Binary files differnew file mode 100644 index 0000000..5debd75 --- /dev/null +++ b/doxygen/img/Dspace_move.gif diff --git a/doxygen/img/Dspace_point.gif b/doxygen/img/Dspace_point.gif Binary files differnew file mode 100644 index 0000000..92ad3a8 --- /dev/null +++ b/doxygen/img/Dspace_point.gif diff --git a/doxygen/img/Dspace_read.gif b/doxygen/img/Dspace_read.gif Binary files differnew file mode 100644 index 0000000..28c67f4 --- /dev/null +++ b/doxygen/img/Dspace_read.gif diff --git a/doxygen/img/Dspace_select.gif b/doxygen/img/Dspace_select.gif Binary files differnew file mode 100644 index 0000000..b9f4851 --- /dev/null +++ b/doxygen/img/Dspace_select.gif diff --git a/doxygen/img/Dspace_separate.gif b/doxygen/img/Dspace_separate.gif Binary files differnew file mode 100644 index 0000000..ba4ba8c --- /dev/null +++ b/doxygen/img/Dspace_separate.gif diff --git a/doxygen/img/Dspace_simple.gif b/doxygen/img/Dspace_simple.gif Binary files differnew file mode 100644 index 0000000..ff3eca5 --- /dev/null +++ b/doxygen/img/Dspace_simple.gif diff --git a/doxygen/img/Dspace_subset.gif b/doxygen/img/Dspace_subset.gif Binary files differnew file mode 100644 index 0000000..b353175 --- /dev/null +++ b/doxygen/img/Dspace_subset.gif diff --git a/doxygen/img/Dspace_three_datasets.gif b/doxygen/img/Dspace_three_datasets.gif Binary files differnew file mode 100644 index 0000000..4af222f --- /dev/null +++ b/doxygen/img/Dspace_three_datasets.gif diff --git a/doxygen/img/Dspace_transfer.gif b/doxygen/img/Dspace_transfer.gif Binary files differnew file mode 100644 index 0000000..7de0231 --- /dev/null +++ b/doxygen/img/Dspace_transfer.gif diff --git a/doxygen/img/Dspace_write1to2.gif b/doxygen/img/Dspace_write1to2.gif Binary files differnew file mode 100644 index 0000000..5735bc7 --- /dev/null +++ b/doxygen/img/Dspace_write1to2.gif diff --git a/doxygen/img/Dtypes_fig1.gif b/doxygen/img/Dtypes_fig1.gif Binary files differnew file mode 100644 index 0000000..484f54f --- /dev/null +++ b/doxygen/img/Dtypes_fig1.gif diff --git a/doxygen/img/Dtypes_fig10.gif b/doxygen/img/Dtypes_fig10.gif Binary files differnew file mode 100644 index 0000000..60c8ba9 --- /dev/null +++ b/doxygen/img/Dtypes_fig10.gif diff --git a/doxygen/img/Dtypes_fig11.gif b/doxygen/img/Dtypes_fig11.gif Binary files differnew file mode 100644 index 0000000..b5eda71 --- /dev/null +++ b/doxygen/img/Dtypes_fig11.gif diff --git a/doxygen/img/Dtypes_fig12.gif b/doxygen/img/Dtypes_fig12.gif Binary files differnew file mode 100644 index 0000000..ee911b7 --- /dev/null +++ b/doxygen/img/Dtypes_fig12.gif diff --git a/doxygen/img/Dtypes_fig13a.gif b/doxygen/img/Dtypes_fig13a.gif Binary files differnew file mode 100644 index 0000000..2f47b71 --- /dev/null +++ b/doxygen/img/Dtypes_fig13a.gif diff --git a/doxygen/img/Dtypes_fig13b.gif b/doxygen/img/Dtypes_fig13b.gif Binary files differnew file mode 100644 index 0000000..fe3b5fb --- /dev/null +++ b/doxygen/img/Dtypes_fig13b.gif diff --git a/doxygen/img/Dtypes_fig13c.gif b/doxygen/img/Dtypes_fig13c.gif Binary files differnew file mode 100644 index 0000000..afd2834 --- /dev/null +++ b/doxygen/img/Dtypes_fig13c.gif diff --git a/doxygen/img/Dtypes_fig13d.gif b/doxygen/img/Dtypes_fig13d.gif Binary files differnew file mode 100644 index 0000000..48805d8 --- /dev/null +++ b/doxygen/img/Dtypes_fig13d.gif diff --git a/doxygen/img/Dtypes_fig14.gif b/doxygen/img/Dtypes_fig14.gif Binary files differnew file mode 100644 index 0000000..8f4d787 --- /dev/null +++ b/doxygen/img/Dtypes_fig14.gif diff --git a/doxygen/img/Dtypes_fig15.gif b/doxygen/img/Dtypes_fig15.gif Binary files differnew file mode 100644 index 0000000..82a34d0 --- /dev/null +++ b/doxygen/img/Dtypes_fig15.gif diff --git a/doxygen/img/Dtypes_fig16.gif b/doxygen/img/Dtypes_fig16.gif Binary files differnew file mode 100644 index 0000000..e83d379 --- /dev/null +++ b/doxygen/img/Dtypes_fig16.gif diff --git a/doxygen/img/Dtypes_fig16a.gif b/doxygen/img/Dtypes_fig16a.gif Binary files differnew file mode 100644 index 0000000..7e68cc0 --- /dev/null +++ b/doxygen/img/Dtypes_fig16a.gif diff --git a/doxygen/img/Dtypes_fig16b.gif b/doxygen/img/Dtypes_fig16b.gif Binary files differnew file mode 100644 index 0000000..b7919be --- /dev/null +++ b/doxygen/img/Dtypes_fig16b.gif diff --git a/doxygen/img/Dtypes_fig16c.gif b/doxygen/img/Dtypes_fig16c.gif Binary files differnew file mode 100644 index 0000000..cca285a --- /dev/null +++ b/doxygen/img/Dtypes_fig16c.gif diff --git a/doxygen/img/Dtypes_fig16d.gif b/doxygen/img/Dtypes_fig16d.gif Binary files differnew file mode 100644 index 0000000..8ca0fd7 --- /dev/null +++ b/doxygen/img/Dtypes_fig16d.gif diff --git a/doxygen/img/Dtypes_fig17a.gif b/doxygen/img/Dtypes_fig17a.gif Binary files differnew file mode 100644 index 0000000..cdfaa29 --- /dev/null +++ b/doxygen/img/Dtypes_fig17a.gif diff --git a/doxygen/img/Dtypes_fig17b.gif b/doxygen/img/Dtypes_fig17b.gif Binary files differnew file mode 100644 index 0000000..4a3ba33 --- /dev/null +++ b/doxygen/img/Dtypes_fig17b.gif diff --git a/doxygen/img/Dtypes_fig18.gif b/doxygen/img/Dtypes_fig18.gif Binary files differnew file mode 100644 index 0000000..73c33e0 --- /dev/null +++ b/doxygen/img/Dtypes_fig18.gif diff --git a/doxygen/img/Dtypes_fig19.gif b/doxygen/img/Dtypes_fig19.gif Binary files differnew file mode 100644 index 0000000..38ea6d4 --- /dev/null +++ b/doxygen/img/Dtypes_fig19.gif diff --git a/doxygen/img/Dtypes_fig2.gif b/doxygen/img/Dtypes_fig2.gif Binary files differnew file mode 100644 index 0000000..52285a6 --- /dev/null +++ b/doxygen/img/Dtypes_fig2.gif diff --git a/doxygen/img/Dtypes_fig20a.gif b/doxygen/img/Dtypes_fig20a.gif Binary files differnew file mode 100644 index 0000000..8406e77 --- /dev/null +++ b/doxygen/img/Dtypes_fig20a.gif diff --git a/doxygen/img/Dtypes_fig20b.gif b/doxygen/img/Dtypes_fig20b.gif Binary files differnew file mode 100644 index 0000000..3f2331d --- /dev/null +++ b/doxygen/img/Dtypes_fig20b.gif diff --git a/doxygen/img/Dtypes_fig20c.gif b/doxygen/img/Dtypes_fig20c.gif Binary files differnew file mode 100644 index 0000000..5b60165 --- /dev/null +++ b/doxygen/img/Dtypes_fig20c.gif diff --git a/doxygen/img/Dtypes_fig20d.gif b/doxygen/img/Dtypes_fig20d.gif Binary files differnew file mode 100644 index 0000000..fdcb59a --- /dev/null +++ b/doxygen/img/Dtypes_fig20d.gif diff --git a/doxygen/img/Dtypes_fig21.gif b/doxygen/img/Dtypes_fig21.gif Binary files differnew file mode 100644 index 0000000..6d30528 --- /dev/null +++ b/doxygen/img/Dtypes_fig21.gif diff --git a/doxygen/img/Dtypes_fig22.gif b/doxygen/img/Dtypes_fig22.gif Binary files differnew file mode 100644 index 0000000..5e2ca99 --- /dev/null +++ b/doxygen/img/Dtypes_fig22.gif diff --git a/doxygen/img/Dtypes_fig23.gif b/doxygen/img/Dtypes_fig23.gif Binary files differnew file mode 100644 index 0000000..f0c9882 --- /dev/null +++ b/doxygen/img/Dtypes_fig23.gif diff --git a/doxygen/img/Dtypes_fig24.gif b/doxygen/img/Dtypes_fig24.gif Binary files differnew file mode 100644 index 0000000..a1c28f4 --- /dev/null +++ b/doxygen/img/Dtypes_fig24.gif diff --git a/doxygen/img/Dtypes_fig25a.gif b/doxygen/img/Dtypes_fig25a.gif Binary files differnew file mode 100644 index 0000000..16d3bcc --- /dev/null +++ b/doxygen/img/Dtypes_fig25a.gif diff --git a/doxygen/img/Dtypes_fig25c.gif b/doxygen/img/Dtypes_fig25c.gif Binary files differnew file mode 100644 index 0000000..a625b74 --- /dev/null +++ b/doxygen/img/Dtypes_fig25c.gif diff --git a/doxygen/img/Dtypes_fig26.gif b/doxygen/img/Dtypes_fig26.gif Binary files differnew file mode 100644 index 0000000..24b34fb --- /dev/null +++ b/doxygen/img/Dtypes_fig26.gif diff --git a/doxygen/img/Dtypes_fig27.gif b/doxygen/img/Dtypes_fig27.gif Binary files differnew file mode 100644 index 0000000..71f182a --- /dev/null +++ b/doxygen/img/Dtypes_fig27.gif diff --git a/doxygen/img/Dtypes_fig28.gif b/doxygen/img/Dtypes_fig28.gif Binary files differnew file mode 100644 index 0000000..56d8d1b --- /dev/null +++ b/doxygen/img/Dtypes_fig28.gif diff --git a/doxygen/img/Dtypes_fig3.gif b/doxygen/img/Dtypes_fig3.gif Binary files differnew file mode 100644 index 0000000..993d12e --- /dev/null +++ b/doxygen/img/Dtypes_fig3.gif diff --git a/doxygen/img/Dtypes_fig4.gif b/doxygen/img/Dtypes_fig4.gif Binary files differnew file mode 100644 index 0000000..67aedef --- /dev/null +++ b/doxygen/img/Dtypes_fig4.gif diff --git a/doxygen/img/Dtypes_fig5.gif b/doxygen/img/Dtypes_fig5.gif Binary files differnew file mode 100644 index 0000000..075417d --- /dev/null +++ b/doxygen/img/Dtypes_fig5.gif diff --git a/doxygen/img/Dtypes_fig6.gif b/doxygen/img/Dtypes_fig6.gif Binary files differnew file mode 100644 index 0000000..516ab95 --- /dev/null +++ b/doxygen/img/Dtypes_fig6.gif diff --git a/doxygen/img/Dtypes_fig7.gif b/doxygen/img/Dtypes_fig7.gif Binary files differnew file mode 100644 index 0000000..c18e9dc --- /dev/null +++ b/doxygen/img/Dtypes_fig7.gif diff --git a/doxygen/img/Dtypes_fig8.gif b/doxygen/img/Dtypes_fig8.gif Binary files differnew file mode 100644 index 0000000..d75d998 --- /dev/null +++ b/doxygen/img/Dtypes_fig8.gif diff --git a/doxygen/img/Dtypes_fig9.gif b/doxygen/img/Dtypes_fig9.gif Binary files differnew file mode 100644 index 0000000..873f0ab --- /dev/null +++ b/doxygen/img/Dtypes_fig9.gif diff --git a/doxygen/img/Files_fig3.gif b/doxygen/img/Files_fig3.gif Binary files differnew file mode 100644 index 0000000..6912f5c --- /dev/null +++ b/doxygen/img/Files_fig3.gif diff --git a/doxygen/img/Files_fig4.gif b/doxygen/img/Files_fig4.gif Binary files differnew file mode 100644 index 0000000..b4ff107 --- /dev/null +++ b/doxygen/img/Files_fig4.gif diff --git a/doxygen/img/Groups_fig1.gif b/doxygen/img/Groups_fig1.gif Binary files differnew file mode 100644 index 0000000..193fff9 --- /dev/null +++ b/doxygen/img/Groups_fig1.gif diff --git a/doxygen/img/Groups_fig10_a.gif b/doxygen/img/Groups_fig10_a.gif Binary files differnew file mode 100644 index 0000000..6595b34 --- /dev/null +++ b/doxygen/img/Groups_fig10_a.gif diff --git a/doxygen/img/Groups_fig10_b.gif b/doxygen/img/Groups_fig10_b.gif Binary files differnew file mode 100644 index 0000000..9e7c234 --- /dev/null +++ b/doxygen/img/Groups_fig10_b.gif diff --git a/doxygen/img/Groups_fig10_c.gif b/doxygen/img/Groups_fig10_c.gif Binary files differnew file mode 100644 index 0000000..20900ac --- /dev/null +++ b/doxygen/img/Groups_fig10_c.gif diff --git a/doxygen/img/Groups_fig10_d.gif b/doxygen/img/Groups_fig10_d.gif Binary files differnew file mode 100644 index 0000000..7251919 --- /dev/null +++ b/doxygen/img/Groups_fig10_d.gif diff --git a/doxygen/img/Groups_fig11_a.gif b/doxygen/img/Groups_fig11_a.gif Binary files differnew file mode 100644 index 0000000..1d041d0 --- /dev/null +++ b/doxygen/img/Groups_fig11_a.gif diff --git a/doxygen/img/Groups_fig11_b.gif b/doxygen/img/Groups_fig11_b.gif Binary files differnew file mode 100644 index 0000000..732109b --- /dev/null +++ b/doxygen/img/Groups_fig11_b.gif diff --git a/doxygen/img/Groups_fig11_c.gif b/doxygen/img/Groups_fig11_c.gif Binary files differnew file mode 100644 index 0000000..f1444eb --- /dev/null +++ b/doxygen/img/Groups_fig11_c.gif diff --git a/doxygen/img/Groups_fig11_d.gif b/doxygen/img/Groups_fig11_d.gif Binary files differnew file mode 100644 index 0000000..ee1b740 --- /dev/null +++ b/doxygen/img/Groups_fig11_d.gif diff --git a/doxygen/img/Groups_fig2.gif b/doxygen/img/Groups_fig2.gif Binary files differnew file mode 100644 index 0000000..d14b0ff --- /dev/null +++ b/doxygen/img/Groups_fig2.gif diff --git a/doxygen/img/Groups_fig3.gif b/doxygen/img/Groups_fig3.gif Binary files differnew file mode 100644 index 0000000..aaa1fe7 --- /dev/null +++ b/doxygen/img/Groups_fig3.gif diff --git a/doxygen/img/Groups_fig4.gif b/doxygen/img/Groups_fig4.gif Binary files differnew file mode 100644 index 0000000..a077bf3 --- /dev/null +++ b/doxygen/img/Groups_fig4.gif diff --git a/doxygen/img/Groups_fig5.gif b/doxygen/img/Groups_fig5.gif Binary files differnew file mode 100644 index 0000000..55ddc3c --- /dev/null +++ b/doxygen/img/Groups_fig5.gif diff --git a/doxygen/img/Groups_fig6.gif b/doxygen/img/Groups_fig6.gif Binary files differnew file mode 100644 index 0000000..53a18d4 --- /dev/null +++ b/doxygen/img/Groups_fig6.gif diff --git a/doxygen/img/Groups_fig9_a.gif b/doxygen/img/Groups_fig9_a.gif Binary files differnew file mode 100644 index 0000000..af0ab69 --- /dev/null +++ b/doxygen/img/Groups_fig9_a.gif diff --git a/doxygen/img/Groups_fig9_aa.gif b/doxygen/img/Groups_fig9_aa.gif Binary files differnew file mode 100644 index 0000000..43ed356 --- /dev/null +++ b/doxygen/img/Groups_fig9_aa.gif diff --git a/doxygen/img/Groups_fig9_b.gif b/doxygen/img/Groups_fig9_b.gif Binary files differnew file mode 100644 index 0000000..b07ec9c --- /dev/null +++ b/doxygen/img/Groups_fig9_b.gif diff --git a/doxygen/img/Groups_fig9_bb.gif b/doxygen/img/Groups_fig9_bb.gif Binary files differnew file mode 100644 index 0000000..e13f534 --- /dev/null +++ b/doxygen/img/Groups_fig9_bb.gif diff --git a/doxygen/img/LBDsetSubRWProg.png b/doxygen/img/LBDsetSubRWProg.png Binary files differnew file mode 100644 index 0000000..4627740 --- /dev/null +++ b/doxygen/img/LBDsetSubRWProg.png diff --git a/doxygen/img/Pmodel_fig2.gif b/doxygen/img/Pmodel_fig2.gif Binary files differnew file mode 100644 index 0000000..8be15fb --- /dev/null +++ b/doxygen/img/Pmodel_fig2.gif diff --git a/doxygen/img/Pmodel_fig3.gif b/doxygen/img/Pmodel_fig3.gif Binary files differnew file mode 100644 index 0000000..211f2ab --- /dev/null +++ b/doxygen/img/Pmodel_fig3.gif diff --git a/doxygen/img/Pmodel_fig5_a.gif b/doxygen/img/Pmodel_fig5_a.gif Binary files differnew file mode 100644 index 0000000..6607b1c --- /dev/null +++ b/doxygen/img/Pmodel_fig5_a.gif diff --git a/doxygen/img/Pmodel_fig5_b.gif b/doxygen/img/Pmodel_fig5_b.gif Binary files differnew file mode 100644 index 0000000..548df28 --- /dev/null +++ b/doxygen/img/Pmodel_fig5_b.gif diff --git a/doxygen/img/Pmodel_fig5_c.gif b/doxygen/img/Pmodel_fig5_c.gif Binary files differnew file mode 100644 index 0000000..459bc66 --- /dev/null +++ b/doxygen/img/Pmodel_fig5_c.gif diff --git a/doxygen/img/Pmodel_fig5_d.gif b/doxygen/img/Pmodel_fig5_d.gif Binary files differnew file mode 100644 index 0000000..207350d --- /dev/null +++ b/doxygen/img/Pmodel_fig5_d.gif diff --git a/doxygen/img/Pmodel_fig5_e.gif b/doxygen/img/Pmodel_fig5_e.gif Binary files differnew file mode 100644 index 0000000..ee4f656 --- /dev/null +++ b/doxygen/img/Pmodel_fig5_e.gif diff --git a/doxygen/img/Pmodel_fig6.gif b/doxygen/img/Pmodel_fig6.gif Binary files differnew file mode 100644 index 0000000..2dac825 --- /dev/null +++ b/doxygen/img/Pmodel_fig6.gif diff --git a/doxygen/img/PropListClassInheritance.gif b/doxygen/img/PropListClassInheritance.gif Binary files differnew file mode 100644 index 0000000..c6f0309 --- /dev/null +++ b/doxygen/img/PropListClassInheritance.gif diff --git a/doxygen/img/PropListEcosystem.gif b/doxygen/img/PropListEcosystem.gif Binary files differnew file mode 100644 index 0000000..cf77ba4 --- /dev/null +++ b/doxygen/img/PropListEcosystem.gif diff --git a/doxygen/img/Shared_Attribute.jpg b/doxygen/img/Shared_Attribute.jpg Binary files differnew file mode 100644 index 0000000..058eeec --- /dev/null +++ b/doxygen/img/Shared_Attribute.jpg diff --git a/doxygen/img/StormDataset.png b/doxygen/img/StormDataset.png Binary files differnew file mode 100644 index 0000000..da44335 --- /dev/null +++ b/doxygen/img/StormDataset.png diff --git a/doxygen/img/UML_Attribute.jpg b/doxygen/img/UML_Attribute.jpg Binary files differnew file mode 100644 index 0000000..5b3db7d --- /dev/null +++ b/doxygen/img/UML_Attribute.jpg diff --git a/doxygen/img/UML_FileAndProps.gif b/doxygen/img/UML_FileAndProps.gif Binary files differnew file mode 100644 index 0000000..1de96c6 --- /dev/null +++ b/doxygen/img/UML_FileAndProps.gif diff --git a/doxygen/img/VFL_Drivers.gif b/doxygen/img/VFL_Drivers.gif Binary files differnew file mode 100644 index 0000000..4b626c6 --- /dev/null +++ b/doxygen/img/VFL_Drivers.gif diff --git a/doxygen/img/cmpnddtype.png b/doxygen/img/cmpnddtype.png Binary files differnew file mode 100644 index 0000000..53b4afd --- /dev/null +++ b/doxygen/img/cmpnddtype.png diff --git a/doxygen/img/crtatt.png b/doxygen/img/crtatt.png Binary files differnew file mode 100644 index 0000000..93ac36c --- /dev/null +++ b/doxygen/img/crtatt.png diff --git a/doxygen/img/crtdset.png b/doxygen/img/crtdset.png Binary files differnew file mode 100644 index 0000000..9cc3085 --- /dev/null +++ b/doxygen/img/crtdset.png diff --git a/doxygen/img/crtf-pic.png b/doxygen/img/crtf-pic.png Binary files differnew file mode 100644 index 0000000..f7c49b8 --- /dev/null +++ b/doxygen/img/crtf-pic.png diff --git a/doxygen/img/crtgrp.png b/doxygen/img/crtgrp.png Binary files differnew file mode 100644 index 0000000..506bc68 --- /dev/null +++ b/doxygen/img/crtgrp.png diff --git a/doxygen/img/dataset.png b/doxygen/img/dataset.png Binary files differnew file mode 100644 index 0000000..1524417 --- /dev/null +++ b/doxygen/img/dataset.png diff --git a/doxygen/img/datasetwdata.png b/doxygen/img/datasetwdata.png Binary files differnew file mode 100644 index 0000000..5f03827 --- /dev/null +++ b/doxygen/img/datasetwdata.png diff --git a/doxygen/img/dataspace.png b/doxygen/img/dataspace.png Binary files differnew file mode 100644 index 0000000..95e0b7d --- /dev/null +++ b/doxygen/img/dataspace.png diff --git a/doxygen/img/dataspace1.png b/doxygen/img/dataspace1.png Binary files differnew file mode 100644 index 0000000..f21a5f5 --- /dev/null +++ b/doxygen/img/dataspace1.png diff --git a/doxygen/img/datatype.png b/doxygen/img/datatype.png Binary files differnew file mode 100644 index 0000000..6ea5732 --- /dev/null +++ b/doxygen/img/datatype.png diff --git a/doxygen/img/dtypes_fig25b.gif b/doxygen/img/dtypes_fig25b.gif Binary files differnew file mode 100644 index 0000000..9dbc225 --- /dev/null +++ b/doxygen/img/dtypes_fig25b.gif diff --git a/doxygen/img/fileobj.png b/doxygen/img/fileobj.png Binary files differnew file mode 100644 index 0000000..ae5212d --- /dev/null +++ b/doxygen/img/fileobj.png diff --git a/doxygen/img/group.png b/doxygen/img/group.png Binary files differnew file mode 100644 index 0000000..7fec7fc --- /dev/null +++ b/doxygen/img/group.png diff --git a/doxygen/img/hdfview-anthrstrm-img.png b/doxygen/img/hdfview-anthrstrm-img.png Binary files differnew file mode 100644 index 0000000..add4e48 --- /dev/null +++ b/doxygen/img/hdfview-anthrstrm-img.png diff --git a/doxygen/img/hdfview-anthrstrm-sprdsht.png b/doxygen/img/hdfview-anthrstrm-sprdsht.png Binary files differnew file mode 100644 index 0000000..4584fd5 --- /dev/null +++ b/doxygen/img/hdfview-anthrstrm-sprdsht.png diff --git a/doxygen/img/hdfview-anthrstrm.png b/doxygen/img/hdfview-anthrstrm.png Binary files differnew file mode 100644 index 0000000..afc2de3 --- /dev/null +++ b/doxygen/img/hdfview-anthrstrm.png diff --git a/doxygen/img/hdfview-imgicon.png b/doxygen/img/hdfview-imgicon.png Binary files differnew file mode 100644 index 0000000..f189080 --- /dev/null +++ b/doxygen/img/hdfview-imgicon.png diff --git a/doxygen/img/hdfview-imgprop.png b/doxygen/img/hdfview-imgprop.png Binary files differnew file mode 100644 index 0000000..717727b --- /dev/null +++ b/doxygen/img/hdfview-imgprop.png diff --git a/doxygen/img/hdfview-imgsubset.png b/doxygen/img/hdfview-imgsubset.png Binary files differnew file mode 100644 index 0000000..19cec57 --- /dev/null +++ b/doxygen/img/hdfview-imgsubset.png diff --git a/doxygen/img/hdfview-newcmpd.png b/doxygen/img/hdfview-newcmpd.png Binary files differnew file mode 100644 index 0000000..b07b5f8 --- /dev/null +++ b/doxygen/img/hdfview-newcmpd.png diff --git a/doxygen/img/hdfview-newimgsubset.png b/doxygen/img/hdfview-newimgsubset.png Binary files differnew file mode 100644 index 0000000..fd16b23 --- /dev/null +++ b/doxygen/img/hdfview-newimgsubset.png diff --git a/doxygen/img/hdfview-prop.png b/doxygen/img/hdfview-prop.png Binary files differnew file mode 100644 index 0000000..16c0904 --- /dev/null +++ b/doxygen/img/hdfview-prop.png diff --git a/doxygen/img/hdfview-qf.png b/doxygen/img/hdfview-qf.png Binary files differnew file mode 100644 index 0000000..edc371f --- /dev/null +++ b/doxygen/img/hdfview-qf.png diff --git a/doxygen/img/hdfview-regref.png b/doxygen/img/hdfview-regref.png Binary files differnew file mode 100644 index 0000000..7f2b02a --- /dev/null +++ b/doxygen/img/hdfview-regref.png diff --git a/doxygen/img/hdfview-regref1.png b/doxygen/img/hdfview-regref1.png Binary files differnew file mode 100644 index 0000000..f754931 --- /dev/null +++ b/doxygen/img/hdfview-regref1.png diff --git a/doxygen/img/hdfview-regref2.png b/doxygen/img/hdfview-regref2.png Binary files differnew file mode 100644 index 0000000..5a73c01 --- /dev/null +++ b/doxygen/img/hdfview-regref2.png diff --git a/doxygen/img/hdfview-regrefval.png b/doxygen/img/hdfview-regrefval.png Binary files differnew file mode 100644 index 0000000..e0a666b --- /dev/null +++ b/doxygen/img/hdfview-regrefval.png diff --git a/doxygen/img/hdfview-table.png b/doxygen/img/hdfview-table.png Binary files differnew file mode 100644 index 0000000..69301bc --- /dev/null +++ b/doxygen/img/hdfview-table.png diff --git a/doxygen/img/hdfview-tree.png b/doxygen/img/hdfview-tree.png Binary files differnew file mode 100644 index 0000000..8ba2621 --- /dev/null +++ b/doxygen/img/hdfview-tree.png diff --git a/doxygen/img/imgLBDsetCreate.gif b/doxygen/img/imgLBDsetCreate.gif Binary files differnew file mode 100644 index 0000000..67585ef --- /dev/null +++ b/doxygen/img/imgLBDsetCreate.gif diff --git a/doxygen/img/imgLBDsetSubRW11.png b/doxygen/img/imgLBDsetSubRW11.png Binary files differnew file mode 100644 index 0000000..8b1df86 --- /dev/null +++ b/doxygen/img/imgLBDsetSubRW11.png diff --git a/doxygen/img/imgLBDsetSubRW12.png b/doxygen/img/imgLBDsetSubRW12.png Binary files differnew file mode 100644 index 0000000..976966a --- /dev/null +++ b/doxygen/img/imgLBDsetSubRW12.png diff --git a/doxygen/img/imgLBDsetSubRW31.png b/doxygen/img/imgLBDsetSubRW31.png Binary files differnew file mode 100644 index 0000000..31d5098 --- /dev/null +++ b/doxygen/img/imgLBDsetSubRW31.png diff --git a/doxygen/img/imgLBDsetSubRW32.png b/doxygen/img/imgLBDsetSubRW32.png Binary files differnew file mode 100644 index 0000000..f7d82fd --- /dev/null +++ b/doxygen/img/imgLBDsetSubRW32.png diff --git a/doxygen/img/imgLBDsetSubRW33.png b/doxygen/img/imgLBDsetSubRW33.png Binary files differnew file mode 100644 index 0000000..69a368b --- /dev/null +++ b/doxygen/img/imgLBDsetSubRW33.png diff --git a/doxygen/img/imgLBFile.gif b/doxygen/img/imgLBFile.gif Binary files differnew file mode 100644 index 0000000..b79c6d6 --- /dev/null +++ b/doxygen/img/imgLBFile.gif diff --git a/doxygen/img/imggrpcreate.gif b/doxygen/img/imggrpcreate.gif Binary files differnew file mode 100644 index 0000000..ac1dcf9 --- /dev/null +++ b/doxygen/img/imggrpcreate.gif diff --git a/doxygen/img/imggrpdsets.gif b/doxygen/img/imggrpdsets.gif Binary files differnew file mode 100644 index 0000000..3383dc6 --- /dev/null +++ b/doxygen/img/imggrpdsets.gif diff --git a/doxygen/img/imggrps.gif b/doxygen/img/imggrps.gif Binary files differnew file mode 100644 index 0000000..d48dbab --- /dev/null +++ b/doxygen/img/imggrps.gif diff --git a/doxygen/img/newgroupimage.png b/doxygen/img/newgroupimage.png Binary files differnew file mode 100644 index 0000000..7bc4c90 --- /dev/null +++ b/doxygen/img/newgroupimage.png diff --git a/doxygen/img/noattrs.png b/doxygen/img/noattrs.png Binary files differnew file mode 100644 index 0000000..13abcc5 --- /dev/null +++ b/doxygen/img/noattrs.png diff --git a/doxygen/img/properties.png b/doxygen/img/properties.png Binary files differnew file mode 100644 index 0000000..083dc14 --- /dev/null +++ b/doxygen/img/properties.png diff --git a/doxygen/img/scarletletter.png b/doxygen/img/scarletletter.png Binary files differnew file mode 100644 index 0000000..7c5d2e6 --- /dev/null +++ b/doxygen/img/scarletletter.png diff --git a/doxygen/img/showasimage.png b/doxygen/img/showasimage.png Binary files differnew file mode 100644 index 0000000..8377292 --- /dev/null +++ b/doxygen/img/showasimage.png diff --git a/doxygen/img/storm.png b/doxygen/img/storm.png Binary files differnew file mode 100644 index 0000000..769b037 --- /dev/null +++ b/doxygen/img/storm.png diff --git a/doxygen/img/tutr-lochk.png b/doxygen/img/tutr-lochk.png Binary files differnew file mode 100644 index 0000000..297cd6d --- /dev/null +++ b/doxygen/img/tutr-lochk.png diff --git a/doxygen/img/tutr-lochks.png b/doxygen/img/tutr-lochks.png Binary files differnew file mode 100644 index 0000000..477fc1d --- /dev/null +++ b/doxygen/img/tutr-lochks.png diff --git a/doxygen/img/tutr-locons.png b/doxygen/img/tutr-locons.png Binary files differnew file mode 100644 index 0000000..bea5be4 --- /dev/null +++ b/doxygen/img/tutr-locons.png diff --git a/doxygen/img/vol_architecture.png b/doxygen/img/vol_architecture.png Binary files differnew file mode 100755 index 0000000..10e5596 --- /dev/null +++ b/doxygen/img/vol_architecture.png |
