summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorFrank Baker <fbaker@hdfgroup.org>2003-06-20 21:53:38 (GMT)
committerFrank Baker <fbaker@hdfgroup.org>2003-06-20 21:53:38 (GMT)
commit2edd657fa0b01d69a4dfe91de207b208d0853c4f (patch)
tree9a38fd94ee740b66ac1ea5fda42e549c90a45837 /doc
parent186565693d522067993ae2059b425676fa6b04af (diff)
downloadhdf5-2edd657fa0b01d69a4dfe91de207b208d0853c4f.zip
hdf5-2edd657fa0b01d69a4dfe91de207b208d0853c4f.tar.gz
hdf5-2edd657fa0b01d69a4dfe91de207b208d0853c4f.tar.bz2
[svn-r7076]
Purpose: Add new tools: h5diff h5perf h5redeploy h5c++ Corrections to h5import Description: h5diff, h5perf, h5redeploy, h5c++ -- Added these tools. h5import -- Corrected the description of the naming convention for output datasets. Other edits based on review comments. Copy edits and source code formatting. Platforms tested: IE 5, Safari
Diffstat (limited to 'doc')
-rw-r--r--doc/html/Tools.html1742
1 files changed, 1114 insertions, 628 deletions
diff --git a/doc/html/Tools.html b/doc/html/Tools.html
index 21f6d9e..a6ebe55 100644
--- a/doc/html/Tools.html
+++ b/doc/html/Tools.html
@@ -60,6 +60,9 @@ to convert files from HDF4 format to HDF5 format and vice versa.
A tool for displaying HDF5 file contents
<li><a href="#Tools-Ls">h5ls</a> --
A tool for listing specified features of HDF5 file contents
+ <li><a href="#Tools-Diff">h5diff</a> --
+ A tool to identify and locate the differences between two HDF5 files
+ <em>(Beta version)</em>
<li><a href="#Tools-Repart">h5repart</a> --
A tool for repartitioning a file, creating a family of files
<li><a href="#Tools-Import">h5import</a> --
@@ -72,10 +75,16 @@ to convert files from HDF4 format to HDF5 format and vice versa.
A tool for converting an HDF5 file to an HDF4 file
<li><a href="#Tools-H4toh5">h4toh5</a> --
A tool for converting an HDF4 file to an HDF5 file
+ <li><a href="#Tools-Perf">h5perf</a> --
+ A tool for measuring HDF5 performance
+ <li><a href="#Tools-Redeploy">h5redeploy</a> --
+ A tool for updating HDF5 compiler tools after installing HDF5
<li><a href="#Tools-H5CC">h5cc</a> --
- A tool for compiling HDF5 programs
+ A tool for compiling HDF5 programs written in C
<li><a href="#Tools-H5FC">h5fc</a> --
A tool for compiling HDF5 programs written in Fortran90
+ <li><a href="#Tools-H5C++">h5c++</a> --
+ A tool for compiling HDF5 programs written in C++
<li><a href="http://hdf.ncsa.uiuc.edu/java-hdf5-html/">Java-based tools for HDF5</a> --
<em>(at <code>http://hdf.ncsa.uiuc.edu/java-hdf5-html/</code>)</em>
<br>
@@ -263,7 +272,7 @@ to convert files from HDF4 format to HDF5 format and vice versa.
Default: 1 in all dimensions.</dd>
<dt><code>--</code></dt>
<dd>Indicate that all following arguments are non-options.
- E.g., to dump a file called `-f', use h5dump -- -f.</dd>
+ E.g., to dump a file called `-f', use h5dump -- -f.</dd>
<dt><em>file</em></dt>
<dd>The file to be examined.</dd>
<br><br>
@@ -444,7 +453,7 @@ to convert files from HDF4 format to HDF5 format and vice versa.
<dt><code>-f</code> &nbsp;&nbsp;or&nbsp;&nbsp;
<code>--full</code>
<dd>Print full path names instead of base names.
- <dt><code>-g</code> &nbsp;&nbsp;or&nbsp;&nbsp;
+ <dt><code>-g</code> &nbsp;&nbsp;or&nbsp;&nbsp;
<code>--group</code>
<dd>Show information about a group, not its contents.
<dt><code>-l</code> &nbsp;&nbsp;or&nbsp;&nbsp;
@@ -493,6 +502,102 @@ to convert files from HDF4 format to HDF5 format and vice versa.
<hr>
<dl>
+<dt><strong>Tool Name:</strong> <a name="Tools-Diff">h5diff</a> &nbsp;&nbsp; <em>(Beta version)</em>
+<dt><strong>Syntax:</strong>
+ <dd><code>h5diff </code> <em>file1</em> <em>file2</em>
+ [<em>OPTIONS</em>]
+ [<em>object1</em> [<em>object2</em> ] ]
+<dt><strong>Purpose:</strong>
+ <dd>Compares two HDF5 files and reports the differences.
+<dt><strong>Description:</strong>
+ <dd><code>h5diff</code> is a command line tool that compares
+ two HDF5 files, <em>file1</em> and <em>file2</em>, and
+ reports the differences between them. 
+ <p>
+ Optionally, <code>h5diff</code> will compare two objects
+ within these files.
+ If only one object, <em>object1</em>, is specified,
+ <code>h5diff</code> will compare
+ <em>object1</em> in <em>file1</em>
+ with <em>object1</em> in <em>file2</em>.
+ In two objects, <em>object1</em> and <em>object2</em>,
+ are specified, <code>h5diff</code> will compare
+ <em>object1</em> in <em>file1</em>
+ with <em>object2</em> in <em>file2</em>.
+ These objects must be HDF5 datasets.
+ <p>
+ <em>object1</em> and <em>object2</em> must be expressed
+ as absolute paths from the respective file's root group.
+ <p>
+ Additional information, with several sample cases,
+ can be found in the document
+ <a href="http://hdf.ncsa.uiuc.edu/HDF5/h5diff/h5diff_design.html">
+ <cite>H5diff Examples</cite></a>.
+<dt><strong>Options and Parameters:</strong>
+ <dl>
+ <dt><em>file1</em>
+ <dt><em>file2</em>
+ <dd>The HDF5 files to be compared.
+ <dt><code>-h</code>
+ <dd>Print all differences.
+ <dt><code>-r</code>
+ <dd>Print only the names of objects that differ;
+ do not print the differences.
+ These objects may be HDF5 datasets, groups,
+ or named datatypes.
+ <dt><code>-n</code> <em>count</em>
+ <dd>Print difference up to <em>count</em> differences,
+ then stop.
+ <em>count</em> must be a positive integer.
+ <dt><code>-d</code> <em>delta</em>
+ <dd>Print only differences that are greater than the
+ limit <em>delta</em>.
+ <em>delta</em> must be a positive number.
+ The comparison criterion is whether the
+ absolute value of the difference of
+ two corresponding values is greater than
+ <em>delta</em>
+ <br>(e.g., <code> |a&ndash;b|&nbsp;&gt;&nbsp;<em>delta</em></code>,
+ where <code>a</code> is a value in <em>file1</em> and
+ <code>b</code> is a value in <em>file2</em>).
+ <dt><code>-p</code> <em>relative</em>
+ <dd>Print only differences that are greater than a
+ relative error.
+ <em>relative</em> must be a positive number.
+ The comparison criterion is whether the
+ absolute value of the difference <code>1</code>
+ and the ratio of two corresponding values
+ is greater than <em>relative</em>
+ (e.g., <code>|1&ndash;(b/a)|&nbsp;&gt;&nbsp;<em>relative</em></code>
+ where <code>a</code> is a value in <em>file1</em> and
+ <code>b</code> is a value in <em>file2</em>).
+ <dt><em>object1</em>
+ <dt><em>object2</em>
+ <dd>Specific object(s) within the files to be compared.
+ </dl>
+<dt><strong>Examples:</strong>
+ <dd>The following <code>h5diff</code> call compares
+ the object <code>/a/b</code> in <code>file1</code>
+ with the object <code>/a/c</code> in <code>file2</code>:<br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;h5diff file1 file2 /a/b /a/c</code>
+ <dd>This <code>h5diff</code> call compares
+ the object <code>/a/b</code> in <code>file1</code>
+ with the same object in <code>file2</code>:<br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;h5diff file1 file2 /a/b</code>
+ <dd>And this <code>h5diff</code> call compares
+ all objects in both files:<br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;h5diff file1 file2</code>
+<!--
+<dt><strong>Current Status:</strong>
+ <dd>
+<dt><strong>See Also:</strong>
+ <dd>
+-->
+</dl>
+
+
+<hr>
+<dl>
<dt><strong>Tool Name:</strong> <a name="Tools-Repart">h5repart</a>
<dt><strong>Syntax:</strong>
<dd><code>h5repart
@@ -547,14 +652,14 @@ to convert files from HDF4 format to HDF5 format and vice versa.
<dt><strong>Syntax:</strong>
<dd><code>h5import
<em>infile</em> <em>in_options</em>
- [<em>infile</em> <em>in_options</em> <b>...</b>]
- -o <em>outfile</em>
- </code>
+ [<em>infile</em> <em>in_options</em> <b>...</b>]
+ -o <em>outfile</em>
+ </code>
<dd><code>h5import
<em>infile</em> <em>in_options</em>
- [<em>infile</em> <em>in_options</em> <b>...</b>]
- -outfile <em>outfile</em>
- </code>
+ [<em>infile</em> <em>in_options</em> <b>...</b>]
+ -outfile <em>outfile</em>
+ </code>
<dd><code>h5import -h</code>
<dd><code>h5import -help</code>
<dt><strong>Purpose:</strong>
@@ -563,624 +668,657 @@ to convert files from HDF4 format to HDF5 format and vice versa.
<dd><code>h5import</code> converts data
from one or more ASCII or binary files, <code><i>infile</i></code>,
into the same number of HDF5 datasets
- in the existing or new HDF5 file, <code><i>outfile</i></code>.
- Data conversion is performed in accordance with the
+ in the existing or new HDF5 file, <code><i>outfile</i></code>.
+ Data conversion is performed in accordance with the
user-specified type and storage properties
- specified in <code><em>in_options</em></code>.
- <p>
- The primary objective of <code>h5import</code> is to
- import floating point or integer data.
+ specified in <code><em>in_options</em></code>.
+ <p>
+ The primary objective of <code>h5import</code> is to
+ import floating point or integer data.
The utility's design allows for future versions that
- accept ASCII text files and store the contents as a
+ accept ASCII text files and store the contents as a
compact array of one-dimensional strings,
- but that capability is not implemented in HDF5 Release 1.6.
+ but that capability is not implemented in HDF5 Release 1.6.
- <p>
- <b>Input data and options:</b><br>
- Input data can be provided in one of the follwing forms:
- <ul><li>As an ASCII, or plain-text, file containing either
- floating point or integer data
- <li>As a binary file containing either 32-bit or
+ <p>
+ <b>Input data and options:</b><br>
+ Input data can be provided in one of the follwing forms:
+ <ul><li>As an ASCII, or plain-text, file containing either
+ floating point or integer data
+ <li>As a binary file containing either 32-bit or
64-bit native floating point data
- <li>As a binary file containing native integer data,
- signed or unsigned and
- 8-bit, 16-bit, 32-bit, or 64-bit.
- <li>As an ASCII, or plain-text, file containing text data.
+ <li>As a binary file containing native integer data,
+ signed or unsigned and
+ 8-bit, 16-bit, 32-bit, or 64-bit.
+ <li>As an ASCII, or plain-text, file containing text data.
(This feature is not implemented in HDF5 Release 1.6.)
- </ul>
- Each input file, <code><i>infile</i></code>,
- contains a single <em>n</em>-dimensional
- array of values of one of the above types expressed
- in the order of fastest-changing dimensions first.
- <p>
- Floating point data in an ASCII input file must be
- expressed in the fixed floating form (e.g., 323.56)
- <code>h5import</code> is designed to accept scientific notation
- (e.g., 3.23E+02) in an ASCII, but that is not implemented in HDF5 release 1.6.
- <p>
- Each input file can be associated with options specifying
- the datatype and storage properties.
- These options can be specified either as
- <em>command line arguments</em>
- or in a <em>configuration file</em>.
- Note that exactly one of these approaches must be used with a
- single input file.
- <p>
- Command line arguments, best used with simple input files,
- can be used to specify
- the class, size, dimensions of the input data and
- a path identifying the output dataset.
- <p>
- The recommended means of specifying input data options
- is in a configuration file; this is also the only means of
- specifying advanced storage features.
- See further discussion in "The configuration file" below.
- <p>
- The only required option for input data is dimension sizes;
- defaults are available for all others.
- <p>
- <code>h5import</code> will accept up to 30 input files in a single call.
- Other considerations, such as the maximum length of a command line,
- may impose a more stringent limitation.
+ </ul>
+ Each input file, <code><i>infile</i></code>,
+ contains a single <em>n</em>-dimensional
+ array of values of one of the above types expressed
+ in the order of fastest-changing dimensions first.
+ <p>
+ Floating point data in an ASCII input file must be
+ expressed in the fixed floating form (e.g., 323.56)
+ <code>h5import</code> is designed to accept scientific notation
+ (e.g., 3.23E+02) in an ASCII, but that is not implemented in HDF5 release 1.6.
+ <p>
+ Each input file can be associated with options specifying
+ the datatype and storage properties.
+ These options can be specified either as
+ <em>command line arguments</em>
+ or in a <em>configuration file</em>.
+ Note that exactly one of these approaches must be used with a
+ single input file.
+ <p>
+ Command line arguments, best used with simple input files,
+ can be used to specify
+ the class, size, dimensions of the input data and
+ a path identifying the output dataset.
+ <p>
+ The recommended means of specifying input data options
+ is in a configuration file; this is also the only means of
+ specifying advanced storage features.
+ See further discussion in "The configuration file" below.
+ <p>
+ The only required option for input data is dimension sizes;
+ defaults are available for all others.
+ <p>
+ <code>h5import</code> will accept up to 30 input files in a single call.
+ Other considerations, such as the maximum length of a command line,
+ may impose a more stringent limitation.
- <p>
- <b>Output data and options:</b><br>
- The name of the output file is specified following
- the <code>-o</code> or <code>-output</code> option
- in <code><i>outfile</i></code>.
- The data from each input file is stored as a separate dataset
- in this output file.
- <code><i>outfile</i></code> may be an existing file.
- If it does not yet exist, <code>h5import</code> will create it.
- <p>
- Output dataset information and storage properties can be
- specified only by means of a configuration file.
- <table width=100% border=0>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- Dataset path
- </td><td>If the groups in the path leading to the dataset
- do not exist, <code>h5import</code> will create them.<br>
- If no group is specified, the dataset will be created
- under the root group.<br>
- If no dataset name is specified, the dataset will be created
- as <code>dataset1</code>.<br>
- <code>h5import</code> does not check for a pre-existing dataset
- of the specified or default name; it overwrites any such dataset
- without offering an opportunity to preserve it.
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- Output type
- </td><td>Datatype parameters for output data
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- &nbsp;&nbsp;&nbsp;&nbsp;Output data class
- </td><td>Signed or unsigned integer or floating point
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- &nbsp;&nbsp;&nbsp;&nbsp;Output data size
- </td><td>8-, 16-, 32-, or 64-bit integer<br>
- 31- or 64-bit floating point
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- &nbsp;&nbsp;&nbsp;&nbsp;Output architecture
- </td><td><code>IEEE</code><br>
- <code>STD</code><br>
- <code>NATIVE</code> (Default)<br>
- Other architectures are included in the <code>h5import</code> design
- but are not implemented in this release.
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- &nbsp;&nbsp;&nbsp;&nbsp;Output byte order
- </td><td>Little- or big-endian.<br>
- Relevant only if output architecture
- is <code>IEEE</code>, <code>UNIX</code>, or <code>STD</code>;
- fixed for other architectures.
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- Dataset&nbsp;layout&nbsp;and&nbsp;storage&nbsp;&nbsp;<br>
- &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;properties
- </td><td>Denote how raw data is to be organized on the disk.
- If none of the following are specified,
- the default configuration is contiguous layout and with no compression.
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- &nbsp;&nbsp;&nbsp;&nbsp;Layout
- </td><td>Contiguous (Default)<br>
- Chunked
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- &nbsp;&nbsp;&nbsp;&nbsp;External storage
- </td><td>Allows raw data to be stored in a non-HDF5 file or in an
- external HDF5 file.<br>
- Requires contiguous layout.
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- &nbsp;&nbsp;&nbsp;&nbsp;Compressed
- </td><td>Sets the type of compression and the
- level to which the dataset must be compressed.<br>
- Requires chunked layout.
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- &nbsp;&nbsp;&nbsp;&nbsp;Extendible
- </td><td>Allows the dimensions of the dataset increase over time
- and/or to be unlimited.<br>
- Requires chunked layout.
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
- &nbsp;&nbsp;&nbsp;&nbsp;Compressed and<br>
- &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extendible
- </td><td>Requires chunked layout.
- </td></tr>
- <tr valign=top align=left><td width=30>&nbsp;</td><td>
-
- </td><td>&nbsp;
- </td></tr>
- </table>
- <p>
+ <p>
+ <b>Output data and options:</b><br>
+ The name of the output file is specified following
+ the <code>-o</code> or <code>-output</code> option
+ in <code><i>outfile</i></code>.
+ The data from each input file is stored as a separate dataset
+ in this output file.
+ <code><i>outfile</i></code> may be an existing file.
+ If it does not yet exist, <code>h5import</code> will create it.
+ <p>
+ Output dataset information and storage properties can be
+ specified only by means of a configuration file.
+ <table width=100% border=0>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ Dataset path
+ </td><td>If the groups in the path leading to the dataset
+ do not exist, <code>h5import</code> will create them.<br>
+ If no group is specified, the dataset will be created
+ as a member of the root group.<br>
+ If no dataset name is specified, the default name is
+ <code>dataset1</code> for the first input dataset,
+ <code>dataset2</code> for the second input dataset,
+ <code>dataset3</code> for the third input dataset,
+ etc.<br>
+ <code>h5import</code> does not overwrite a pre-existing
+ dataset of the specified or default name.
+ When an existing dataset of a confilcting name is
+ encountered, <code>h5import</code> quits with an error;
+ the current input file and any subsequent input files
+ are not processed.
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ Output type
+ </td><td>Datatype parameters for output data
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ &nbsp;&nbsp;&nbsp;&nbsp;Output data class
+ </td><td>Signed or unsigned integer or floating point
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ &nbsp;&nbsp;&nbsp;&nbsp;Output data size
+ </td><td>8-, 16-, 32-, or 64-bit integer<br>
+ 32- or 64-bit floating point
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ &nbsp;&nbsp;&nbsp;&nbsp;Output architecture
+ </td><td><code>IEEE</code><br>
+ <code>STD</code><br>
+ <code>NATIVE</code> (Default)<br>
+ Other architectures are included in the <code>h5import</code> design
+ but are not implemented in this release.
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ &nbsp;&nbsp;&nbsp;&nbsp;Output byte order
+ </td><td>Little- or big-endian.<br>
+ Relevant only if output architecture
+ is <code>IEEE</code>, <code>UNIX</code>, or <code>STD</code>;
+ fixed for other architectures.
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ Dataset&nbsp;layout&nbsp;and&nbsp;storage&nbsp;&nbsp;<br>
+ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;properties
+ </td><td>Denote how raw data is to be organized on the disk.
+ If none of the following are specified,
+ the default configuration is contiguous layout and with no compression.
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ &nbsp;&nbsp;&nbsp;&nbsp;Layout
+ </td><td>Contiguous (Default)<br>
+ Chunked
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ &nbsp;&nbsp;&nbsp;&nbsp;External storage
+ </td><td>Allows raw data to be stored in a non-HDF5 file or in an
+ external HDF5 file.<br>
+ Requires contiguous layout.
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ &nbsp;&nbsp;&nbsp;&nbsp;Compressed
+ </td><td>Sets the type of compression and the
+ level to which the dataset must be compressed.<br>
+ Requires chunked layout.
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ &nbsp;&nbsp;&nbsp;&nbsp;Extendible
+ </td><td>Allows the dimensions of the dataset increase over time
+ and/or to be unlimited.<br>
+ Requires chunked layout.
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+ &nbsp;&nbsp;&nbsp;&nbsp;Compressed and<br>
+ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;extendible
+ </td><td>Requires chunked layout.
+ </td></tr>
+ <tr valign=top align=left><td width=30>&nbsp;</td><td>
+
+ </td><td>&nbsp;
+ </td></tr>
+ </table>
+ <p>
- <p>
- <b>Command-line arguments:</b><br>
- The <code>h5import</code> syntax for the command-line arguments,
- <code><em>in_options</em></code>, is as follows:
- <table width=100% border=0>
- <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>h5import <em>infile</em> -d <em>dim_list</em>
- [-p <em>pathname</em>]
- [-t <em>input_class</em>]
- [-s <em>input_size</em>]
- [<em>infile</em> ...]
- -o <em>outfile</em></code><br>
- or<br>
- <code>h5import <em>infile</em> -dims <em>dim_list</em>
- [-path <em>pathname</em>]
- [-type <em>input_class</em>]
- [-size <em>input_size</em>]
- [<em>infile</em> ...]
- -outfile <em>outfile</em></code><br>
- or<br>
- <code>h5import <em>infile</em> -c <em>config_file</em>
- [<em>infile</em> ...]
- -outfile <em>outfile</em></code>
- </td></tr>
- </table>
- Note the following:
- If the <code>-c <em>config_file</em></code> option is used with
- an input file, no other argument can be used with that input file.
- If the <code>-c <em>config_file</em></code> option is not used with
- an input data file, the <code>-d <em>dim_list</em></code> argument
- (or <code>-dims <em>dim_list</em></code>)
- must be used and any combination of the remaining options may be used.
- Any arguments used must appear in <em>exactly</em> the order used
- in the syntax declarations immediately above.
+ <p>
+ <b>Command-line arguments:</b><br>
+ The <code>h5import</code> syntax for the command-line arguments,
+ <code><em>in_options</em></code>, is as follows:
+ <table width=100% border=0>
+ <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>h5import <em>infile</em> -d <em>dim_list</em>
+ [-p <em>pathname</em>]
+ [-t <em>input_class</em>]
+ [-s <em>input_size</em>]
+ [<em>infile</em> ...]
+ -o <em>outfile</em></code><br>
+ or<br>
+ <code>h5import <em>infile</em> -dims <em>dim_list</em>
+ [-path <em>pathname</em>]
+ [-type <em>input_class</em>]
+ [-size <em>input_size</em>]
+ [<em>infile</em> ...]
+ -outfile <em>outfile</em></code><br>
+ or<br>
+ <code>h5import <em>infile</em> -c <em>config_file</em>
+ [<em>infile</em> ...]
+ -outfile <em>outfile</em></code>
+ </td></tr>
+ </table>
+ Note the following:
+ If the <code>-c <em>config_file</em></code> option is used with
+ an input file, no other argument can be used with that input file.
+ If the <code>-c <em>config_file</em></code> option is not used with
+ an input data file, the <code>-d <em>dim_list</em></code> argument
+ (or <code>-dims <em>dim_list</em></code>)
+ must be used and any combination of the remaining options may be used.
+ Any arguments used must appear in <em>exactly</em> the order used
+ in the syntax declarations immediately above.
- <p>
- <b>The configuration file:</b><br>
- A configuration file is specified with the
- <code>-c <em>config_file</em></code> option:
- <table border=0>
- <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>h5import <em>infile</em> -c <em>config_file</em>
- [<em>infile</em> -c <em>config_file2</em> ...]
- -outfile ><em>outfile</em></code>
- </td></tr>
- </table>
- <p>
- The configuration file is an ASCII file and must be
- organized as "Configuration_Keyword Value" pairs,
- with one pair on each line.
- For example, the line indicating that
- the input data class (configuration keyword <code>INPUT-CLASS</code>)
- is floating point in a text file (value <code>TEXTFP</code>)
- would appear as follows:<br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;INPUT-CLASS&nbsp;TEXTFP</code>
- <p>
+ <p>
+ <b>The configuration file:</b><br>
+ A configuration file is specified with the
+ <code>-c <em>config_file</em></code> option:
+ <table border=0>
+ <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>h5import <em>infile</em> -c <em>config_file</em>
+ [<em>infile</em> -c <em>config_file2</em> ...]
+ -outfile <em>outfile</em></code>
+ </td></tr>
+ </table>
+ <p>
+ The configuration file is an ASCII file and must be
+ organized as "Configuration_Keyword Value" pairs,
+ with one pair on each line.
+ For example, the line indicating that
+ the input data class (configuration keyword <code>INPUT-CLASS</code>)
+ is floating point in a text file (value <code>TEXTFP</code>)
+ would appear as follows:<br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;INPUT-CLASS&nbsp;TEXTFP</code>
+ <p>
A configuration file may have the following keywords each
- followed by one of the following defined values.
- One entry for each of the first two keywords,
- <code>RANK</code> and <code>DIMENSION-SIZES</code>,
- is required; all other keywords are optional.
-
- <p>
- <table width=100% border=0>
- <tr align=left><th valign=top align=left>
- <hr>Keyword&nbsp;&nbsp;<br><code>&nbsp;&nbsp;&nbsp;&nbsp;</code>Value
- </th><th valign=top align=left><hr>Description
- </th></tr>
-
- <tr valign=top align=left><td>
- <hr><code>RANK&nbsp;&nbsp;</code>
- </td><td><hr>The number of dimensions in the dataset. (Required)
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;<em>rank</em></code>
- </td><td>An integer specifying the number of dimensions in the dataset.<br>
- Example: <code> &nbsp; 4 &nbsp; </code> for a 4-dimensional dataset.
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>DIMENSION-SIZES</code>
- </td><td><hr>Sizes of the dataset dimensions. (Required)
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;<em>dim_sizes</em></code>
- </td><td>A string of space-separated integers
- specifying the sizes of the dimensions in the dataset.
- The number of sizes in this entry must match the value in
- the <code>RANK</code> entry.<br>
- Example: <code> &nbsp; 4 3 4 38 &nbsp; </code> for a 4x3x4x38 dataset.
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>PATH</code>
- </td><td><hr>Path of the output dataset.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;<em>path</em></code>
- </td><td>The full HDF5 pathname identifying the output dataset
- relative to the root group within the output file.<br>
- I.e., <code><em>path</em></code> is a string of optional group names,
- each followed by a slash,
- and ending with a dataset name.
- If the groups in the path do no exist, they will be created.<br>
- If <code>PATH</code> is not specified, the default
- <code><em>path</em></code> is <code>/dataset1</code>.<br>
- Example: The configuration file entry
- <table border=0>
- <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>PATH grp1/grp2/dataset1</code>
- </td></tr>
- </table>
- indicates that the output dataset <code>dataset1</code> will be written
- in the group <code>grp2/</code> which is in the group <code>grp1/</code>,
- a member of the root group in the output file.
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>INPUT-CLASS&nbsp;&nbsp;</code>
- </td><td><hr>A string denoting the type of input data.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;TEXTIN</code>
- </td><td>Input is signed integer data in an ASCII file.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;TEXTUIN</code>
- </td><td>Input is unsigned integer data in an ASCII file.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;TEXTFP</code>
- </td><td>Input is floating point data in fixed notation (e.g., 325.34)
- in an ASCII file.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;TEXTFPE</code>
- </td><td>Input is floating point data in scientific notation (e.g., 3.2534E+02)
- in an ASCII file.<br>
- (Not implemented in this release.)
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;IN</code>
- </td><td>Input is signed integer data in a binary file.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;UIN</code>
- </td><td>Input is unsigned integer data in a binary file.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;FP</code>
- </td><td>Input is floating point data in a binary file. (Default)
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;STR</code>
- </td><td>Input is character data in an ASCII file.
- With this value, the configuration keywords
- <code>RANK</code>, <code>DIMENSION-SIZES</code>,
- <code>OUTPUT-CLASS</code>, <code>OUTPUT-SIZE</code>,
- <code>OUTPUT-ARCHITECTURE</code>, and <code>OUTPUT-BYTE-ORDER</code>
- will be ignored.<br>
- (Not implemented in this release.)
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>INPUT-SIZE</code>
- </td><td><hr>An integer denoting the size of the input data, in bits.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;8</code><br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;16</code><br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;32</code><br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;64</code>
- </td><td>For signed and unsigned integer data:
- <code>TEXTIN</code>, <code>TEXTUIN</code>,
- <code>IN</code>, or <code>UIN</code>.
- (Default: <code> 32</code>)
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;32</code><br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;64</code>
- </td><td>For floating point data:
- <code>TEXTFP</code>, <code>TEXTFPE</code>,
- or <code>FP</code>.
- (Default: <code> 32</code>)
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>OUTPUT-CLASS&nbsp;&nbsp;</code>
- </td><td><hr>A string denoting the type of output data.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;IN</code>
- </td><td>Output is signed integer data.<br>
- (Default if <code>INPUT-CLASS</code> is
- <code>IN</code> or <code>TEXTIN</code>)
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;UIN</code>
- </td><td>Output is unsigned integer data.<br>
- (Default if <code>INPUT-CLASS</code> is
- <code>UIN</code> or <code>TEXTUIN</code>)
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;FP</code>
- </td><td>Output is floating point data.<br>
- (Default if <code>INPUT-CLASS</code> is not specified or is
- <code>FP</code>, <code>TEXTFP</code>, or <code>TEXTFPE</code>)
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;STR</code>
- </td><td>Output is character data,
- to be written as a 1-dimensional array of strings.<br>
- (Default if <code>INPUT-CLASS</code> is <code>UIN</code>
- or <code>TEXTUIN</code>)<br>
- (Not implemented in this release.)
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>OUTPUT-SIZE</code>
- </td><td><hr>An integer denoting the size of the output data, in bits.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;8</code><br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;16</code><br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;32</code><br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;64</code>
- </td><td>For signed and unsigned integer data:
- <code>IN</code> or <code>UIN</code>.
- (Default: Same as <code>INPUT-SIZE</code>, else <code> 32</code>)
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;32</code><br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;64</code>
- </td><td>For floating point data:
- <code>FP</code>.
- (Default: Same as <code>INPUT-SIZE</code>, else <code> 32</code>)
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>OUTPUT-ARCHITECTURE</code>
- </td><td><hr>A string denoting the type of output architecture.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;STD</code><br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;IEEE</code><br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;INTEL</code> *<br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;CRAY</code> *<br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;MIPS</code> *<br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;ALPHA</code> *<br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;NATIVE</code><br>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;UNIX</code> *
- </td><td>See the "Predefined Atomic Types" section
- in the "HDF5 Datatypes" chapter
- of the <cite>HDF5 User's Guide</cite>
- for a discussion of these architectures.<br>
- Values marked with an asterisk (*) are not implemented in this release.<br>
- (Default: <code>NATIVE</code>)
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>OUTPUT-BYTE-ORDER</code>
- </td><td><hr>A string denoting the output byte order.
- This entry is ignored if the <code>OUTPUT-ARCHITECTURE</code>
- is not specified or if it is specified as <code>IEEE</code>,
- <code>UNIX</code>, or <code>STD</code>.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;BE</code>
- </td><td>Big-endian. (Default)
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;LE</code>
- </td><td>Little-endian.
- </td></tr>
-
- <tr valign=top align=left><td colspan="2">
- <hr>The following options are disabled by default, making
- the default storage properties no chunking, no compression,
- no external storage, and no extensible dimensions.
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>CHUNKED-DIMENSION</code><br>
- </td><td><hr>Dimension sizes of the chunk for chunked output data.
-<br><b><i>BTW, is this</i></b> <code>CHUNKED-DIMENSION</code> <b><i>or</i></b> <code>CHUNKED-D...-SIZES</code><b><i>?</i></b>
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;<em>chunk_dims</em></code>
- </td><td>A string of space-separated integers specifying the
- dimension sizes of the chunk for chunked output data.
- The number of dimensions must correspond to the value
- of <code>RANK</code>.<br>
- The presence of this field indicates that the
- output dataset is to be stored in chunked layout;
- if this configuration field is absent,
- the dataset will be stored in contiguous layout.
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>COMPRESSION-TYPE</code>
- </td><td><hr>Type of compression to be used with chunked storage.
- Requires that <code>CHUNKED-DIMENSION</code> be specified.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;GZIP</code>
- </td><td>Gzip compression.<br>
- Othe compression algorithms are not implemented
- in this release of <code>h5import</code>.
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>COMPRESSION-PARAM</code>
- </td><td><hr>Compression level.
- Required if <code>COMPRESSION-TYPE</code> is specified.
-<b><i>Since there is a default, is "required" true?</i></b>
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;1</code> through <code>9</code>
- </td><td>Gzip compression levels:
- <code>1</code> will result in the fastest compression
- while <code>9</code> will result in the best compression ratio.
- (Default: 6)
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>EXTERNAL-STORAGE</code>
- </td><td><hr>Name of an external file in which to create the output dataset.
- Cannot be used with <code>CHUNKED-DIMENSIONS</code>,
- <code>COMPRESSION-TYPE</code>, OR <code>MAXIMUM-DIMENSIONS</code>.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;<i>external_file</i>&nbsp;&nbsp;&nbsp;</code>
- <!-- THE EXTRA NON-BREAKING SPACES AT THE END OF THE PRECEDING LINE -->
- <!-- ARE PADDING SPACES TO ENSURE THE PROPER FORMATTING OF THIS TABLE. -->
- </td><td>A string specifying the name of an external file.
- </td></tr>
-
- <tr valign=top align=left><td>
- <hr><code>MAXIMUM-DIMENSIONS</code>
- </td><td><hr>Maximum sizes of all dimensions.
- Requires that <code>CHUNKED-DIMENSION</code> be specified.
- </td></tr>
- <tr valign=top align=left><td>
- <code>&nbsp;&nbsp;&nbsp;&nbsp;<em>max_dims</em></code>
- </td><td>A string of space-separated integers specifying the
- maximum size of each dimension of the output dataset.
- A value of <code>-1</code> for any dimension implies
- unlimited size for that particular dimension.<br>
- The number of dimensions must correspond to the value
- of <code>RANK</code>.<br>
- </td></tr>
-
- <tr valign=top align=left><td><hr></td><td><hr></td></tr>
- </table>
+ followed by one of the following defined values.
+ One entry for each of the first two keywords,
+ <code>RANK</code> and <code>DIMENSION-SIZES</code>,
+ is required; all other keywords are optional.
+
+ <p>
+ <table width=100% border=0>
+ <tr align=left><th valign=top align=left>
+ <hr>Keyword&nbsp;&nbsp;<br><code>&nbsp;&nbsp;&nbsp;&nbsp;</code>Value
+ </th><th valign=top align=left><hr>Description
+ </th></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>RANK&nbsp;&nbsp;</code>
+ </td><td><hr>The number of dimensions in the dataset. (Required)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;<em>rank</em></code>
+ </td><td>An integer specifying the number of dimensions in the dataset.<br>
+ Example: <code> &nbsp; 4 &nbsp; </code> for a 4-dimensional dataset.
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>DIMENSION-SIZES</code>
+ </td><td><hr>Sizes of the dataset dimensions. (Required)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;<em>dim_sizes</em></code>
+ </td><td>A string of space-separated integers
+ specifying the sizes of the dimensions in the dataset.
+ The number of sizes in this entry must match the value in
+ the <code>RANK</code> entry.
+ The fastest-changing dimension must be listed first.<br>
+ Example: <code> &nbsp; 4 3 4 38 &nbsp; </code> for a 38x4x3x4 dataset.
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>PATH</code>
+ </td><td><hr>Path of the output dataset.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;<em>path</em></code>
+ </td><td>The full HDF5 pathname identifying the output dataset
+ relative to the root group within the output file.<br>
+ I.e., <code><em>path</em></code> is a string consisting of
+ optional group names, each followed by a slash,
+ and ending with a dataset name.
+ If the groups in the path do no exist, they will be
+ created.<br>
+ If <code>PATH</code> is not specified, the output dataset
+ is stored as a member of the root group and the
+ default dataset name is
+ <code>dataset1</code> for the first input dataset,
+ <code>dataset2</code> for the second input dataset,
+ <code>dataset3</code> for the third input dataset, etc.<br>
+ Note that <code>h5import</code> does not overwrite a
+ pre-existing dataset of the specified or default name.
+ When an existing dataset of a confilcting name is
+ encountered, <code>h5import</code> quits with an error;
+ the current input file and any subsequent input files
+ are not processed.<br>
+ Example: The configuration file entry
+ <table border=0>
+ <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>PATH grp1/grp2/dataset1</code>
+ </td></tr>
+ </table>
+ indicates that the output dataset <code>dataset1</code> will
+ be written in the group <code>grp2/</code> which is in
+ the group <code>grp1/</code>,
+ a member of the root group in the output file.
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>INPUT-CLASS&nbsp;&nbsp;</code>
+ </td><td><hr>A string denoting the type of input data.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;TEXTIN</code>
+ </td><td>Input is signed integer data in an ASCII file.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;TEXTUIN</code>
+ </td><td>Input is unsigned integer data in an ASCII file.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;TEXTFP</code>
+ </td><td>Input is floating point data in fixed notation (e.g., 325.34)
+ in an ASCII file.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;TEXTFPE</code>
+ </td><td>Input is floating point data in scientific notation (e.g., 3.2534E+02)
+ in an ASCII file.<br>
+ (Not implemented in this release.)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;IN</code>
+ </td><td>Input is signed integer data in a binary file.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;UIN</code>
+ </td><td>Input is unsigned integer data in a binary file.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;FP</code>
+ </td><td>Input is floating point data in a binary file. (Default)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;STR</code>
+ </td><td>Input is character data in an ASCII file.
+ With this value, the configuration keywords
+ <code>RANK</code>, <code>DIMENSION-SIZES</code>,
+ <code>OUTPUT-CLASS</code>, <code>OUTPUT-SIZE</code>,
+ <code>OUTPUT-ARCHITECTURE</code>, and <code>OUTPUT-BYTE-ORDER</code>
+ will be ignored.<br>
+ (Not implemented in this release.)
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>INPUT-SIZE</code>
+ </td><td><hr>An integer denoting the size of the input data, in bits.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;8</code><br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;16</code><br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;32</code><br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;64</code>
+ </td><td>For signed and unsigned integer data:
+ <code>TEXTIN</code>, <code>TEXTUIN</code>,
+ <code>IN</code>, or <code>UIN</code>.
+ (Default: <code> 32</code>)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;32</code><br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;64</code>
+ </td><td>For floating point data:
+ <code>TEXTFP</code>, <code>TEXTFPE</code>,
+ or <code>FP</code>.
+ (Default: <code> 32</code>)
+ </td></tr>
- <p>
- <b>The <code>help</code> option:</b><br>
- The help option, expressed as one of
- <table width=100% border=0>
- <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>h5import -h</code><br>
- or<br>
- <code>h5import -help</code><br>
- </td></tr>
- <tr><td colspan="2">prints the <code>h5import</code> usage summary</td></tr>
- <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- <code>
- h5import -h[elp], OR<br>
+ <tr valign=top align=left><td>
+ <hr><code>OUTPUT-CLASS&nbsp;&nbsp;</code>
+ </td><td><hr>A string denoting the type of output data.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;IN</code>
+ </td><td>Output is signed integer data.<br>
+ (Default if <code>INPUT-CLASS</code> is
+ <code>IN</code> or <code>TEXTIN</code>)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;UIN</code>
+ </td><td>Output is unsigned integer data.<br>
+ (Default if <code>INPUT-CLASS</code> is
+ <code>UIN</code> or <code>TEXTUIN</code>)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;FP</code>
+ </td><td>Output is floating point data.<br>
+ (Default if <code>INPUT-CLASS</code> is not specified or is
+ <code>FP</code>, <code>TEXTFP</code>, or <code>TEXTFPE</code>)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;STR</code>
+ </td><td>Output is character data,
+ to be written as a 1-dimensional array of strings.<br>
+ (Default if <code>INPUT-CLASS</code> is <code>STR</code>)<br>
+ (Not implemented in this release.)
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>OUTPUT-SIZE</code>
+ </td><td><hr>An integer denoting the size of the output data, in bits.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;8</code><br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;16</code><br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;32</code><br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;64</code>
+ </td><td>For signed and unsigned integer data:
+ <code>IN</code> or <code>UIN</code>.
+ (Default: Same as <code>INPUT-SIZE</code>, else <code> 32</code>)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;32</code><br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;64</code>
+ </td><td>For floating point data:
+ <code>FP</code>.
+ (Default: Same as <code>INPUT-SIZE</code>, else <code> 32</code>)
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>OUTPUT-ARCHITECTURE</code>
+ </td><td><hr>A string denoting the type of output architecture.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;NATIVE</code><br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;STD</code><br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;IEEE</code><br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;INTEL</code> *<br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;CRAY</code> *<br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;MIPS</code> *<br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;ALPHA</code> *<br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;UNIX</code> *
+ </td><td>See the "Predefined Atomic Types" section
+ in the "HDF5 Datatypes" chapter
+ of the <cite>HDF5 User's Guide</cite>
+ for a discussion of these architectures.<br>
+ Values marked with an asterisk (*) are not implemented in this release.<br>
+ (Default: <code>NATIVE</code>)
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>OUTPUT-BYTE-ORDER</code>
+ </td><td><hr>A string denoting the output byte order.
+ This entry is ignored if the <code>OUTPUT-ARCHITECTURE</code>
+ is not specified or if it is not specified as <code>IEEE</code>,
+ <code>UNIX</code>, or <code>STD</code>.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;BE</code>
+ </td><td>Big-endian. (Default)
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;LE</code>
+ </td><td>Little-endian.
+ </td></tr>
+
+ <tr valign=top align=left><td colspan="2">
+ <hr>The following options are disabled by default, making
+ the default storage properties no chunking, no compression,
+ no external storage, and no extensible dimensions.
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>CHUNKED-DIMENSION-SIZES</code><br>
+ </td><td><hr>Dimension sizes of the chunk for chunked output data.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;<em>chunk_dims</em></code>
+ </td><td>A string of space-separated integers specifying the
+ dimension sizes of the chunk for chunked output data.
+ The number of dimensions must correspond to the value
+ of <code>RANK</code>.<br>
+ The presence of this field indicates that the
+ output dataset is to be stored in chunked layout;
+ if this configuration field is absent,
+ the dataset will be stored in contiguous layout.
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>COMPRESSION-TYPE</code>
+ </td><td><hr>Type of compression to be used with chunked storage.
+ Requires that <code>CHUNKED-DIMENSION-SIZES</code>
+ be specified.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;GZIP</code>
+ </td><td>Gzip compression.<br>
+ Othe compression algorithms are not implemented
+ in this release of <code>h5import</code>.
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>COMPRESSION-PARAM</code>
+ </td><td><hr>Compression level.
+ Required if <code>COMPRESSION-TYPE</code> is specified.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;1</code> through <code>9</code>
+ </td><td>Gzip compression levels:
+ <code>1</code> will result in the fastest compression
+ while <code>9</code> will result in the
+ best compression ratio.<br>
+ (Default: 6. The default gzip compression level is 6;
+ not all compression methods will have a default level.)
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>EXTERNAL-STORAGE</code>
+ </td><td><hr>Name of an external file in which to create the output dataset.
+ Cannot be used with <code>CHUNKED-DIMENSIONS-SIZES</code>,
+ <code>COMPRESSION-TYPE</code>, OR <code>MAXIMUM-DIMENSIONS</code>.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;<i>external_file</i>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code>
+ <!-- THE EXTRA NON-BREAKING SPACES AT THE END OF THE PRECEDING LINE -->
+ <!-- ARE PADDING SPACES TO ENSURE THE PROPER FORMATTING OF THIS TABLE. -->
+ <!-- DO NOT REMOVE THEM!!!!!!!!!!!!! -->
+ </td><td>A string specifying the name of an external file.
+ </td></tr>
+
+ <tr valign=top align=left><td>
+ <hr><code>MAXIMUM-DIMENSIONS</code>
+ </td><td><hr>Maximum sizes of all dimensions.
+ Requires that <code>CHUNKED-DIMENSION-SIZES</code> be specified.
+ </td></tr>
+ <tr valign=top align=left><td>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;<em>max_dims</em></code>
+ </td><td>A string of space-separated integers specifying the
+ maximum size of each dimension of the output dataset.
+ A value of <code>-1</code> for any dimension implies
+ unlimited size for that particular dimension.<br>
+ The number of dimensions must correspond to the value
+ of <code>RANK</code>.<br>
+ </td></tr>
+
+ <tr valign=top align=left><td><hr></td><td><hr></td></tr>
+ </table>
+
+ <p>
+ <b>The <code>help</code> option:</b><br>
+ The help option, expressed as one of
+ <table width=100% border=0>
+ <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>h5import -h</code><br>
+ or<br>
+ <code>h5import -help</code><br>
+ </td></tr>
+ <tr><td colspan="2">prints the <code>h5import</code> usage summary</td></tr>
+ <tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>
+ h5import -h[elp], OR<br>
h5import &lt;infile&gt; &lt;options&gt;
- [&lt;infile&gt; &lt;options&gt;...]
- -o[utfile] &lt;outfile&gt;</code>
- </td></tr>
- <tr><td colspan="2">then exits.</td></tr>
- </table>
- <p>
-
+ [&lt;infile&gt; &lt;options&gt;...]
+ -o[utfile] &lt;outfile&gt;</code>
+ </td></tr>
+ <tr><td colspan="2">then exits.</td></tr>
+ </table>
+ <p>
+
<dt><strong>Options and Parameters:</strong>
<dl>
<dt><code>infile(s)</code>
<dd>Name of the Input file(s).
<dt><code>in_options</code>
<dd>Input options. Note that while only the <code>-dims</code> argument
- is required, arguments must used in the order in which they are listed below.
- <dl>
- <dt><code>-d <em>dim_list</em></code>
- <dt><code>-dims <em>dim_list</em></code>
- <dd>Input data dimensions.
- <code><em>dim_list</em></code> is a string of
- comma-separated numbers with no spaces
- describing the dimensions of the input data.
- For example, a 50 x 100 2-dimensional array would be
- specified as <code>-dims 50,100</code>.<br>
- Required argument: if no configuration file is used,
- this command-line argument is mandatory.
- <dt><code>-p <em>pathname</em></code>
- <dt><code>-pathname <em>pathname</em></code>
- <dd><code><em>pathname</em></code> is a string consisiting of
- one or more strings separated by '/' specifying the path
- of the dataset in the output file.
- If the groups in the path do no exist, they will be created.<br>
- Optional argument: if not specified,
- the default path is <code>/dataset1</code>.<br>
- <code>h5import</code> does not check for a pre-existing dataset
- of the specified or default name; it overwrites any such dataset
- without offering an opportunity to preserve it.
- <dt><code>-t <em>input_class</em></code>
- <dt><code>-type <em>input_class</em></code>
- <dd><code><em>input_class</em></code> specifies the class of the
- input data and determines the class of the output data.<br>
- Valid values are as defined in the "ZZZinput_classZZZ"
- section of "ZZZconfig_fileZZZ".<br>
- Optional argument: if not specified,
- the default value is <code>FP</code>.
- <dt><code>-s <em>input_size</em></code>
- <dt><code>-size <em>input_size</em></code>
- <dd><code><em>input_size</em></code> specifies the size in bits
- of the input data and determines the size of the output data.<br>
- Valid values for signed or unsigned integers are
- <code>8</code>, <code>16</code>, <code>32</code>, and <code>64</code>.<br>
- Valid values for floating point data are
- <code>32</code> and <code>64</code>.<br>
- Optional argument: if not specified,
- the default value is <code>32</code>.
- <dt><code>-c <em>config_file</em></code>
- <dd><code><em>config_file</em></code> specifies a configuration file.<br>
- This argument replaces all other arguments except
- <code><em>infile</em></code>and <code>-o <em>outfile</em></code>
- </dl>
+ is required, arguments must used in the order in which they are listed below.
+ <dl>
+ <dt><code>-d <em>dim_list</em></code>
+ <dt><code>-dims <em>dim_list</em></code>
+ <dd>Input data dimensions.
+ <code><em>dim_list</em></code> is a string of
+ comma-separated numbers with no spaces
+ describing the dimensions of the input data.
+ For example, a 50 x 100 2-dimensional array would be
+ specified as <code>-dims 50,100</code>.<br>
+ Required argument: if no configuration file is used,
+ this command-line argument is mandatory.
+ <dt><code>-p <em>pathname</em></code>
+ <dt><code>-pathname <em>pathname</em></code>
+ <dd><code><em>pathname</em></code> is a string consisting of
+ one or more strings separated by slashes (<code>/</code>)
+ specifying the path of the dataset in the output file.
+ If the groups in the path do no exist, they will be
+ created.<br>
+ Optional argument: if not specified,
+ the default path is
+ <code>dataset1</code> for the first input dataset,
+ <code>dataset2</code> for the second input dataset,
+ <code>dataset3</code> for the third input dataset,
+ etc.<br>
+ <code>h5import</code> does not overwrite a pre-existing
+ dataset of the specified or default name.
+ When an existing dataset of a confilcting name is
+ encountered, <code>h5import</code> quits with an error;
+ the current input file and any subsequent input files
+ are not processed.
+ <dt><code>-t <em>input_class</em></code>
+ <dt><code>-type <em>input_class</em></code>
+ <dd><code><em>input_class</em></code> specifies the class of the
+ input data and determines the class of the output data.<br>
+ Valid values are as defined in the Keyword/Values table
+ in the section "The configuration file" above.<br>
+ Optional argument: if not specified,
+ the default value is <code>FP</code>.
+ <dt><code>-s <em>input_size</em></code>
+ <dt><code>-size <em>input_size</em></code>
+ <dd><code><em>input_size</em></code> specifies the size in bits
+ of the input data and determines the size of the output data.<br>
+ Valid values for signed or unsigned integers are
+ <code>8</code>, <code>16</code>, <code>32</code>, and <code>64</code>.<br>
+ Valid values for floating point data are
+ <code>32</code> and <code>64</code>.<br>
+ Optional argument: if not specified,
+ the default value is <code>32</code>.
+ <dt><code>-c <em>config_file</em></code>
+ <dd><code><em>config_file</em></code> specifies a
+ configuration file.<br>
+ This argument replaces all other arguments except
+ <code><em>infile</em></code> and
+ <code>-o <em>outfile</em></code>
+ </dl>
<dt><code>outfile</code>
<dd>Name of the HDF5 output file.
</dl>
<dt><strong>Examples:</strong>
<dd><b>Using command-line arguments:</b>
- <table width=100% border=0>
- <tr><td colspan=2>
- <code>h5import infile -dims 2,3,4 -type TEXTIN -size 32 -o out1</code>
- </td></tr><tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- This command creates a file <code>out1</code> containing
- a single 2x3x4 32-bit integer dataset.
- Since no pathname is specified, the dataset is stored
- in <code>out1</code> as <code>/dataset1</code>.
- </td></tr><tr><td colspan=2>
- <code>h5import infile -dims 20,50 -path bin1/dset1 -type FP -size 64 -o out2</code>
- </td></tr><tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
- This command creates a file <code>out2</code> containing
- a single a 20x50 64-bit floating point dataset.
- The dataset is stored in <code>out2</code> as <code>/bin1/dset1</code>.
- </td></tr>
- </table>
+ <table width=100% border=0>
+ <tr><td colspan=2>
+ <code>h5import infile -dims 2,3,4 -type TEXTIN -size 32 -o out1</code>
+ </td></tr><tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ This command creates a file <code>out1</code> containing
+ a single 2x3x4 32-bit integer dataset.
+ Since no pathname is specified, the dataset is stored
+ in <code>out1</code> as <code>/dataset1</code>.
+ </td></tr><tr><td colspan=2>
+ <code>h5import infile -dims 20,50 -path bin1/dset1 -type FP -size 64 -o out2</code>
+ </td></tr><tr><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ This command creates a file <code>out2</code> containing
+ a single a 20x50 64-bit floating point dataset.
+ The dataset is stored in <code>out2</code> as <code>/bin1/dset1</code>.
+ </td></tr>
+ </table>
<dd><b>Sample configuration files:</b><br>
- The following configuration file specifies the following:<br>
- &ndash; The input data is a 5x2x4 floating point array in an ASCII file.<br>
- &ndash; The output dataset will be saved in chunked layout,
- with chunk dimension sizes of 2x2x2.<br>
- &ndash; The output datatype will be 64-bit floating point, little-endian, IEEE.<br>
- &ndash; The output dataset will be stored in <code><em>outfile</em></code>
- at <code>/work/h5/pkamat/First-set</code>.<br>
- &ndash; The maximum dimension sizes of the output dataset
- will be 8x8x(unlimited).
- <pre>
- PATH work h5 pkamat First-set
+ The following configuration file specifies the following:<br>
+ &ndash; The input data is a 5x2x4 floating point array in
+ an ASCII file.<br>
+ &ndash; The output dataset will be saved in chunked layout,
+ with chunk dimension sizes of 2x2x2.<br>
+ &ndash; The output datatype will be 64-bit floating point,
+ little-endian, IEEE.<br>
+ &ndash; The output dataset will be stored in
+ <code><em>outfile</em></code>
+ at <code>/work/h5/pkamat/First-set</code>.<br>
+ &ndash; The maximum dimension sizes of the output dataset
+ will be 8x8x(unlimited).
+ <pre>
+ PATH work/h5/pkamat/First-set
INPUT-CLASS TEXTFP
RANK 3
DIMENSION-SIZES 5 2 4
@@ -1188,31 +1326,33 @@ to convert files from HDF4 format to HDF5 format and vice versa.
OUTPUT-SIZE 64
OUTPUT-ARCHITECTURE IEEE
OUTPUT-BYTE-ORDER LE
- CHUNKED-DIMENSION 2 2 2
+ CHUNKED-DIMENSION-SIZES 2 2 2
MAXIMUM-DIMENSIONS 8 8 -1
- </pre>
-
+ </pre>
+
The next configuration file specifies the following:<br>
- &ndash; The input data is a 6x3x5x2x4 integer array in a binary file.<br>
- &ndash; The output dataset will be saved in chunked layout,
- with chunk dimension sizes of 2x2x2x2x2.<br>
- &ndash; The output datatype will be 32-bit integer in <code>NATIVE</code> format
- (as the output architecure is not specified).<br>
+ &ndash; The input data is a 6x3x5x2x4 integer array in
+ a binary file.<br>
+ &ndash; The output dataset will be saved in chunked layout,
+ with chunk dimension sizes of 2x2x2x2x2.<br>
+ &ndash; The output datatype will be 32-bit integer in
+ <code>NATIVE</code> format
+ (as the output architecure is not specified).<br>
&ndash; The output dataset will be compressed using Gzip compression
- with a compression level of 7.<br>
- &ndash; The output dataset will be stored in <code><em>outfile</em></code>
- at <code>/Second-set</code>.
- <pre>
+ with a compression level of 7.<br>
+ &ndash; The output dataset will be stored in
+ <code><em>outfile</em></code> at <code>/Second-set</code>.
+ <pre>
PATH Second-set
- INPUT-CLASS IN
+ INPUT-CLASS IN
RANK 5
DIMENSION-SIZES 6 3 5 2 4
OUTPUT-CLASS IN
OUTPUT-SIZE 32
- CHUNKED-DIMENSION 2 2 2 2 2
+ CHUNKED-DIMENSION-SIZES 2 2 2 2 2
COMPRESSION-TYPE GZIP
COMPRESSION-PARAM 7
- </pre>
+ </pre>
<!--
@@ -1466,7 +1606,7 @@ to convert files from HDF4 format to HDF5 format and vice versa.
In this inital version, <code>h4toh5</code> converts the following
HDF4 objects:
<center>
- <table width=75% border=0>
+ <table width=75% border=0>
<tr><th width=40% valign=top align=left>
HDF4 Object
</td><th width=60% valign=top align=left>
@@ -1528,6 +1668,279 @@ to convert files from HDF4 format to HDF5 format and vice versa.
<hr>
<dl>
+<dt><strong>Tool Name:</strong> <a name="Tools-Perf">h5perf</a>
+<dt><strong>Syntax:</strong>
+ <dd><code>h5perf </code>[<code>-h </code>|<code> --help</code>]
+ <dd><code>h5perf </code>[<em>options</em>]
+<!--
+ [<code>-a</code> <em>size</em> | <code>--align=</code><em>size</em>]
+ [<code>-A</code> <em>api_list</em> | <code>--api=</code><em>api_list</em>]
+ [<code>-B</code> <em>size</em> | <code>--block-size=</code><em>size</em>]
+ [<code>-c</code> | <code>--chunk</code>]
+ [<code>-C</code> | <code>--collective</code>]
+ [<code>-d</code> <em>N</em> | <code>--num-dsets</code><em>N</em>]
+ [<code>-D</code> <em>debug_flags</em> | <code>--debug=</code><em>debug_flags</em>]
+ [<code>-e</code> <em>size</em> | <code>--num-bytes=</code><em>size</em>]
+ [<code>-F</code> <em>N</em> | <code>--num-files=</code><em>N</em>]
+ [<code>-i</code> <em>N</em> | <code>--num-iterations=</code><em>N</em>]
+ [<code>-I</code> | <code>--interleaved</code>]
+ [<code>-m</code> | <code>--mpi-posix</code>]
+ [<code>-n</code> | <code>--no-fill</code>]
+ [<code>-o</code> <em>file</em> | <code> --output=</code><em>file</em>]
+ [<code>-p</code> <em>N</em> | <code>--min-num-processes=</code><em>N</em>]
+ [<code>-P</code> <em>N</em> | <code>--max-num-processes=</code><em>N</em>]
+ [<code>-T</code> <em>size</em> | <code>--threshold=</code><em>size</em>]
+ [<code>-w</code> | <code>--write-only</code>]
+ [<code>-x</code> <em>size</em> | <code>--min-xfer-size=</code><em>size</em>]
+ [<code>-X</code> <em>size</em> | <code>--max-xfer-size=</code>size<em></em>]
+-->
+
+<dt><strong>Purpose:</strong>
+ <dd>Tests Parallel HDF5 performance.
+<dt><strong>Description:</strong>
+ <dd><code>h5perf</code> provides tools for testing the performance
+ of the Parallel HDF5 library.
+ <p>
+ The following environment variables have the following
+ effects on <code>H5perf</code> behavior:
+ <table border=0>
+ <tr align="left" valign="top"><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>HDF5_NOCLEANUP</code></td><td>
+ If set, <code>h5perf</code> does not remove data files.
+ (Default: Remove)</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <code>HDF5_MPI_INFO</code></td><td>
+ Must be set to a string containing a list of semi-colon separated
+ key=value pairs for the MPI <code>INFO</code> object.<br>
+ Example:</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <code>HDF5_PARAPREFIX&nbsp;&nbsp;</code></td><td>
+ Sets the prefix for paralllel output data files.</td></tr>
+ </table>
+<dt><strong>Options and Parameters:</strong>
+ <dl>
+ <dt>These terms are used as follows in this section:
+ <table border="0">
+ <tr align="left" valign="top"><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <em>file&nbsp;&nbsp;</em></td><td>
+ A filename</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <em>size</em></td><td>
+ A size specifier, expressed as an integer greater than or equal
+ to 0 (zero) followed by a size indicator:<br>
+ &nbsp;&nbsp;&nbsp;&nbsp;<code>K </code> for kilobytes (1024 bytes)<br>
+ &nbsp;&nbsp;&nbsp;&nbsp;<code>M </code> for megabytes (1048576 bytes)<br>
+ &nbsp;&nbsp;&nbsp;&nbsp;<code>G </code> for gigabytes (1073741824 bytes)<br>
+ Example: <code>37M</code> specifies 37 megabytes or 38797312 bytes.</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <em>N</em></td><td>
+ An integer greater than or equal to 0 (zero)</td></tr>
+ </table>
+ <p>
+ <dt><code>-h</code>, <code>--help</code>
+ <dd>Prints a usage message and exits.
+ <dt><code>-a</code> <em>size</em>, <code>--align=</code><em>size</em>
+ <dd>Specifies the alignment of objects in the HDF5 file.
+ (Default: 1)
+ <dt><code>-A</code> <em>api_list</em>, <code>--api=</code><em>api_list</em>
+ <dd>Specifies which APIs to test.
+ <em>api_list</em> is a comma-separated list with the
+ following valid values:
+ <table border="0">
+ <tr align="left" valign="top"><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>phdf5&nbsp;&nbsp;</code></td><td>Parallel HDF5</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <code>mpiio</code></td><td>MPI-I/O</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <code>posix</code></td><td>POSIX</td></tr>
+ </table>
+ (Default: All APIs)<br><br>
+ Example, <code>--api=mpiio,phdf5</code> specifies that the
+ MPI I/O and parallel HDf5 APIs are to be monitored.<br><br>
+ <dt><code>-B</code> <em>size</em>, <code>--block-size=</code><em>size</em>
+ <dd>Specifies the block size within the transfer buffer.
+ (Default: 128K)<br><br>
+ Block size versus transfer buffer size:
+ The <em>transfer buffer size</em> is the size of a
+ buffer in memory. The data in that buffer is broken
+ into <em>block size</em> pieces and written to the
+ file.<br><br>
+ Transfer block size is set by the
+ <code>-x</code> (or <code>--min-xfer-size</code>) and
+ <code>-X</code> (or <code>--max-xfer-size</code>)
+ options.<br>
+ The pattern in which the blocks
+ are written to the file is described in the discussion
+ of the <code>-I</code> (or <code>--interleaved</code>)
+ option.<br><br>
+ <dt><code>-c</code>, <code>--chunk</code>
+ <dd>Creates HDF5 datasets in chunked layout.
+ (Default: Off)
+ <dt><code>-C</code>, <code>--collective</code>
+ <dd>Use collective I/O for the MPI I/O and Parallel HDF5 APIs.<br>
+ (Default: Off, i.e., independent I/O)<br><br>
+ If this option is set and the MPI-I/O and PHDF5 APIs
+ are in use, all the blocks in each transfer buffer
+ will be written at once with an MPI derived type.
+ <br><br>
+ <dt><code>-d</code> <em>N</em>, <code>--num-dsets</code><em>N</em>
+ <dd>Sets the number of datasets per file.
+ (Default: <code>1</code>)
+ <dt><code>-D</code> <em>debug_flags</em>, <code>--debug=</code><em>debug_flags</em>
+ <dd>Sets the debugging level.
+ <em>debug_flags</em> is a comma-separated list of
+ debugging flags with the following valid values:
+ <table border="0">
+ <tr align="left" valign="top"><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ <code>1&nbsp;&nbsp;</code></td><td>Minimal debugging</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <code>2</code></td><td>Moderate debugging (&ldquo;not quite everything&rdquo;)</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <code>3</code></td><td>Extensive debugging (&ldquo;everything&rdquo;)</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <code>4</code></td><td>All possible debugging (&ldquo;the kitchen sink&rdquo;)</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <code>r</code></td><td>Raw data I/O throughput information</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <code>t</code></td><td>Times, in additions to throughputs</td></tr>
+ <tr align="left" valign="top"><td>&nbsp;</td><td>
+ <code>v</code></td><td>Verify data correctness</td></tr>
+ </table>
+ (Default: No debugging)<br><br>
+ Example: <code>--debug=2,r,t</code> specifies to
+ run a moderate level of debugging
+ while collecting raw data I/O throughput information
+ and verifying the correctness of the data.<br><br>
+ <dt><code>-e</code> <em>size</em>, <code>--num-bytes=</code><em>size</em>
+ <dd>Specifies the number of bytes per process per dataset.
+ (Default: <code>256K</code>)
+ <dt><code>-F</code> <em>N</em>, <code>--num-files=</code><em>N</em>
+ <dd>Specifies the number of files.
+ (Default: <code>1</code>)
+ <dt><code>-i</code> <em>N</em>, <code>--num-iterations=</code><em>N</em>
+ <dd>Sets the number of iterations to perform.
+ (Default: <code>1</code>)
+ <dt><code>-I</code>, <code>--interleaved</code>
+ <dd>Sets interleaved block I/O.<br>
+ (Default: Contiguous block I/O)<br><br>
+ Interleaved vs. Contiguous blocks
+ in a parallel environment:<br>
+ When contiguous blocks are written to a dataset,
+ the dataset is divided into <em>m</em> regions,
+ where <em>m</em> is the number of processes writing
+ separate portions of the dataset. Each process
+ then writes data to its own region.
+ When interleaved blocks are written to a dataset,
+ space for the first block of the first process is
+ allocated in the dataset, then space is allocated
+ for the first block of the second process, etc.,
+ until space has been allocated for the first block
+ of each process. Space is then allocated for
+ the second block of the first process,
+ the second block of the second process, etc.<br><br>
+ For example, in the case of a 4 process run
+ with 1M bytes-per-process, 256K transfer buffer size,
+ and 64KB block size, 16 <em>contiguous</em> blocks
+ per process would be written to the file in the
+ manner<br>
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;1111111111111111222222222222222233333333333333334444444444444444</code><br>
+ while 16 interleaved blocks per process would be
+ written to the file as
+ <code>&nbsp;&nbsp;&nbsp;&nbsp;1234123412341234123412341234123412341234123412341234123412341234</code><br>
+ If collective I/O is turned on, all of the four
+ blocks per transfer buffer will be written in
+ one collective I/O call.<br><br>
+ <dt><code>-m</code>, <code>--mpi-posix</code>
+ <dd>Sets use of MPI-posix driver for HDF5 I/O.
+ (Default: MPI-I/O driver)
+ <dt><code>-n</code>, <code>--no-fill</code>
+ <dd>Specifies to not write fill values to HDF5 datasets.
+ This option is supported only in HDF5 Release v1.6 or later.<br>
+ (Default: Off, i.e., write fill values)
+ <dt><code>-o</code> <em>file</em>, <code> --output=</code><em>file</em>
+ <dd>Sets the output file for raw data to <em>file</em>.
+ (Default: None)
+ <dt><code>-p</code> <em>N</em>, <code>--min-num-processes=</code><em>N</em>
+ <dd>Sets the minimum number of processes to be used.
+ (Default: <code>1</code>)
+ <dt><code>-P</code> <em>N</em>, <code>--max-num-processes=</code><em>N</em>
+ <dd>Sets the maximum number of processes to be used.<br>
+ (Default: All <code>MPI_COMM_WORLD</code>processes)
+ <dt><code>-T</code> <em>size</em>, <code>--threshold=</code><em>size</em>
+ <dd>Sets the threshold for alignment of objects in the HDF5 file.
+ (Default: <code>1</code>)
+ <dt><code>-w</code>, <code>--write-only</code>
+ <dd>Performs only write tests, not read tests.
+ (Default: Read and write tests)
+ <dt><code>-x</code> <em>size</em>, <code>--min-xfer-size=</code><em>size</em>
+ <dd>Sets the minimum transfer buffer size.
+ (Default: <code>128K</code>)
+ <dt><code>-X</code> <em>size</em>, <code>--max-xfer-size=</code>size<em></em>
+ <dd>Sets the maximum transfer buffer size.
+ (Default: <code>1M</code>)
+ </dl>
+<!--
+<dt><strong>Current Status:</strong>
+ <dd>
+<dt><strong>See Also:</strong>
+ <dd>
+-->
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Tool Name:</strong> <a name="Tools-Redeploy">h5redeploy</a>
+<dt><strong>Syntax:</strong>
+ <dd><code>h5redeploy </code>
+ [<code>help </code> | <code>-help</code>]
+ <dd><code>h5redeploy </code>
+ [<code>-echo</code>]
+ [<code>-force</code>]
+ [<code>-prefix=</code><em>dir</em>]
+ [<code>-tool=</code><em>tool</em>]
+ [<code>-show</code>]
+<dt><strong>Purpose:</strong>
+ <dd>Updates HDF5 compiler tools after an HDF5 software installation
+ in a new location.
+<dt><strong>Description:</strong>
+ <dd><code>h5redeploy</code> updates the HDF5 compiler tools after
+ the HDF5 software has been installed in a new location.
+
+<dt><strong>Options and Parameters:</strong>
+ <dl>
+ <dt><code>help</code>, <code>-help</code>
+ <dd>Prints a help message.
+ <dt><code>-echo</code>
+ <dd>Shows all the shell commands executed.
+ <dt><code>-force</code>
+ <dd>Performs the requested action without offerring any prompt
+ requesting confirmation.
+ <dt><code>-prefix=</code><em>dir</em>
+ <dd>Specifies a new directory in which to find the
+ HDF5 subdirectories <code>lib/</code> and
+ <code>include/</code>.<br>
+ (Default: current working directory)
+ <dt><code>-tool=</code><em>tool</em>
+ <dd>Specifies the tool to update.
+ <em>tool</em> must be in the current directory
+ and must be writable.<br>
+ (Default: <code>h5cc</code>)
+ <dt><code>-show</code>
+ <dd>Shows all of the shell commands to be executed
+ without actually executing them.
+ </dl>
+<!--
+<dt><strong>Current Status:</strong>
+ <dd>
+<dt><strong>See Also:</strong>
+ <dd>
+-->
+</dl>
+
+
+<hr>
+<dl>
<dt><strong>Tool Name:</strong> <a name="Tools-H5CC">h5cc</a>
<dt><strong>Syntax:</strong>
<dd><code>h5cc
@@ -1537,7 +1950,7 @@ to convert files from HDF4 format to HDF5 format and vice versa.
<dt><strong>Description:</strong>
<dd><code>h5cc</code> can be used in much the same way MPIch is used
to compile an HDF5 program. It takes care of specifying where the
- HDF5 header files and libraries are on the commandline.
+ HDF5 header files and libraries are on the command line.
<p>
<code>h5cc</code> supercedes all other compiler scripts in that
if you've used them to compile the HDF5 library, then
@@ -1571,9 +1984,9 @@ to convert files from HDF4 format to HDF5 format and vice versa.
<dd>Show all the shell commands executed.
<dt><code>-prefix=DIR</code>
<dd>Use the directory <code><em>DIR</em></code> to find the HDF5
- <code>lib/</code> and <code>include/</code> subdirectories.
+ <code>lib/</code> and <code>include/</code> subdirectories.
<br>
- Default: prefix specified when configuring HDF5.
+ Default: prefix specified when configuring HDF5.
<dt><code>-show</code>
<dd>Show the commands without executing them.
<dt><code>-shlib</code>
@@ -1582,7 +1995,7 @@ to convert files from HDF4 format to HDF5 format and vice versa.
<dd>Compile using static HDF5 libraries [default].
<dt><em>&lt;compile line&gt;</em>
<dd>The normal compile line options for your compiler.
- <code>h5cc</code> uses the same compiler you used to compile HDF5.
+ <code>h5cc</code> uses the same compiler you used to compile HDF5.
Check your compiler's manual for more information on which
options are needed.
</dl>
@@ -1619,7 +2032,7 @@ to convert files from HDF4 format to HDF5 format and vice versa.
<dd><p>
<code>h5fc</code> can be used in much the same way MPIch is used
to compile an HDF5 program. It takes care of specifying where the
- HDF5 header files and libraries are on the commandline.
+ HDF5 header files and libraries are on the command line.
<p>
<code>h5fc</code> supercedes all other compiler scripts in that
if you've used them to compile the HDF5 Fortran library, then
@@ -1638,7 +2051,7 @@ to convert files from HDF4 format to HDF5 format and vice versa.
An example of how to use <code>h5fc</code> to compile the program
<code>hdf_prog</code>, which consists of modules
<code>prog1.f90</code> and <code>prog2.f90</code>
- and uses the HDF5 Fortran library, would be as follows:
+ and uses the HDF5 Fortran library, would be as follows:
<pre>
# h5fc -c prog1.f90
# h5fc -c prog2.f90
@@ -1653,16 +2066,16 @@ to convert files from HDF4 format to HDF5 format and vice versa.
<dd>Show all the shell commands executed.
<dt><code>-prefix=DIR</code>
<dd>Use the directory <code>DIR</code> to find HDF5
- <code>lib/</code> and <code>include/</code> subdirectories
- <br>
+ <code>lib/</code> and <code>include/</code> subdirectories
+ <br>
Default: prefix specified when configuring HDF5.
<dt><code>-show</code>
<dd>Show the commands without executing them.
<dt><em>&lt;compile line&gt;</em>
<dd>The normal compile line options for your compiler.
- <code>h5fc</code> uses the same compiler you used
+ <code>h5fc</code> uses the same compiler you used
to compile HDF5. Check your compiler's manual for
- more information on which options are needed.
+ more information on which options are needed.
</dl>
<dt><strong>Environment Variables:</strong>
<dd>When set, these environment variables override some of the built-in
@@ -1682,6 +2095,79 @@ to convert files from HDF4 format to HDF5 format and vice versa.
</dl>
+<hr>
+<dl>
+<dt><strong>Tool Name:</strong> <a name="Tools-H5C++">h5c++</a>
+<dt><strong>Syntax:</strong>
+ <dd><code>h5c++
+ [</code><em>OPTIONS</em><code>]</code> <em>&lt;compile line&gt;</em>
+<dt><strong>Purpose:</strong>
+ <dd>Helper script to compile HDF5 C++ applications.
+<dt><strong>Description:</strong>
+ <dd><p>
+ <code>h5c++</code> can be used in much the same way MPIch is used
+ to compile an HDF5 program. It takes care of specifying where the
+ HDF5 header files and libraries are on the command line.
+ <p>
+ <code>h5c++</code> supercedes all other compiler scripts in that
+ if you've used one set of compiler scripts to compile the
+ HDF5 C++ library, then <code>h5c++</code> uses those same scripts.
+ For example, when compiling an MPIch program,
+ you use the <code>mpiCC</code> script.
+ <p>
+ Some programs use HDF5 in only a few modules. It isn't necessary
+ to use <code>h5c++</code> to compile those modules which don't use
+ HDF5. In fact, since <code>h5c++</code> is only a convenience
+ script, you are still able to compile HDF5 C++ modules in the
+ normal way. In that case, you will have to specify the HDF5 libraries
+ and include paths yourself.
+ <p>
+ An example of how to use <code>h5c++</code> to compile the program
+ <code>hdf_prog</code>, which consists of modules
+ <code>prog1.cpp</code> and <code>prog2.cpp</code>
+ and uses the HDF5 C++ library, would be as follows:
+ <pre>
+ # h5c++ -c prog1.cpp
+ # h5c++ -c prog2.cpp
+ # h5c++ -o hdf_prog prog1.o prog2.o</pre>
+<dt><strong>Options and Parameters:</strong>
+ <dd>
+ <dl>
+ <dt><code>-help</code>
+ <dd>Prints a help message.
+ <dt><code>-echo</code>
+ <dd>Show all the shell commands executed.
+ <dt><code>-prefix=DIR</code>
+ <dd>Use the directory <code>DIR</code> to find HDF5
+ <code>lib/</code> and <code>include/</code> subdirectories
+ <br>
+ Default: prefix specified when configuring HDF5.
+ <dt><code>-show</code>
+ <dd>Show the commands without executing them.
+ <dt><em>&lt;compile line&gt;</em>
+ <dd>The normal compile line options for your compiler.
+ <code>h5c++</code> uses the same compiler you used
+ to compile HDF5. Check your compiler's manual for
+ more information on which options are needed.
+ </dl>
+<dt><strong>Environment Variables:</strong>
+ <dd>When set, these environment variables override some of the built-in
+ defaults of <code>h5c++</code>.
+ <dl>
+ <dt><code>HDF5_CXX</code>
+ <dd>Use a different C++ compiler.
+ <dt><code>HDF5_CXXLINKER</code>
+ <dd>Use a different linker.
+ </dl>
+<!--
+<dt><strong>Current Status:</strong>
+ <dd>
+<dt><strong>See Also:</strong>
+ <dd>
+ -->
+</dl>
+
+
<!-- Template, next 40 lines -->
<!-- Template, next 40 lines -->
<!-- Template, next 40 lines
@@ -1768,7 +2254,7 @@ And in this document, the
Describes HDF5 Release 1.5, Unreleased Development Branch
</address><!-- #EndLibraryItem -->
-Last modified: 30 May 2003
+Last modified: 11 June 2003
</body>
</html>