From 9fbb176d29403d863c75e405235074e3d476b74e Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Wed, 18 Apr 2001 12:03:21 -0500 Subject: [svn-r3821] Purpose: Repair damaged HTML coding (caused by the Netscape editor) and restore additions since that damage occured. Add h5dump subsetting material. Description: Reverted to earlier version to restore HTML coding. Re-entered h5dump XML material and explanatory comment re h5dump flag parameters. Added h5dump subsetting material. Other editing and formatting within h5dump description. Platforms tested: IE 5 --- doc/html/Tools.html | 1594 ++++++++++++++++++++++----------------------------- 1 file changed, 699 insertions(+), 895 deletions(-) diff --git a/doc/html/Tools.html b/doc/html/Tools.html index 5a2d3d8..13fd62e 100644 --- a/doc/html/Tools.html +++ b/doc/html/Tools.html @@ -1,959 +1,745 @@ - - - - - HDF5/Tools API Specification - - + +HDF5/Tools API Specification + + -

- - - - - - - +

- Introduction to HDF5
- HDF5 User Guide
- Other HDF5 documents and links
- -

- And in this document, the HDF5 Reference Manual
- H5 - H5A - H5D - H5E - H5F - H5G - H5I - H5P - -
- - H5R - H5S - H5T - H5Z - Tools - Datatypes -

+ +

+Introduction to HDF5
+HDF5 User Guide
+Other HDF5 documents and links
+ +

+And in this document, the +HDF5 Reference Manual   +
+H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5I   +H5P   +
+H5R   +H5S   +H5T   +H5Z   +Tools   +Datatypes   +

- -

HDF5 Tools

HDF5 Tool Interfaces

+ +

HDF5 Tools

+ +

HDF5 Tool Interfaces

These tools enable the user to examine HDF5 files interactively. - - - - +
-
-
h5dump -- A tool for displaying - HDF5 file contents
- -
h5ls -- A tool for listing specified - features of HDF5 file contents
- -
h5repart -- A tool for - repartitioning a file, creating a family of files
-
h5toh4 -- A tool for converting - an HDF5 file to an HDF4 file
- -
h4toh5 -- A tool for converting - an HDF4 file to an HDF5 file
-
-
+
+
+
h5dump -- + A tool for displaying HDF5 file contents +
h5ls -- + A tool for listing specified features of HDF5 file contents +
h5repart -- + A tool for repartitioning a file, creating a family of files +
h5toh4 -- + A tool for converting an HDF5 file to an HDF4 file +
h4toh5 -- + A tool for converting an HDF4 file to an HDF5 file +
+

Tool Name: h5dump

Syntax:

h5dump [OPTIONS] file

Purpose:

Displays HDF5 file contents in HDF5 DDL or XML.

Description:

-The h5dump tool enables the user to interactively examine the -contents of an HDF5 file and dump those contents, in human readable form, -to an ASCII file. Optionally, the contents of the file may be dumped as -XML. -

- -

-h5dump dumps an HDF5 file's contents to standard output. It can -display the contents of the whole HDF5 file or selected objects, which -can be groups, datasets, a subset of a dataset, links, attributes, or -data types. -

- -

-The --header option displays object header information only. -

- -

-Names are the absolute names of the objects. h5dump displays -objects in the same order as given on the command line. If a name does -not start with a slash (/), h5dump begins searching for the -specified object starting at the root group. -

- -

-If an object is hard linked with multiple names, h5dump displays -the contents of the object in the first occurrence. Only the link -information is displayed in later occurrences. -

- -

-h5dump assigns a name for any unnamed data type in the form of -#oid1:oid2, where oid1 and -oid2 are the object identifiers assigned by the library. The -unnamed types are displayed within the root group. -

- -

-Data types are displayed with standard type names. For example, if a data -set is created with H5T_NATIVE_INT type and the standard type -name for integer on that machine is H5T_STD_I32BE, -h5dump displays H5T_STD_I32BE as the type of the data -set. -

- -

-h5dump can also be used to dump a subset of data from a dataset. -It operates in much the same way that hyperslabs do in the HDF5 library. -The parameters specified on the command line are passed to the -H5Sselect_hyperslab -function and the resulting selection is then displayed. -

- -

-The h5dump output is described in detail in the DDL for HDF5, the Data Description -Language document. -

- -

-Note: It is no longer permissable to specify multiple attributes, -datasets, data types, groups, or soft links with one flag. For example, -before one could issue the command: -

- -

- h5dump -a /attr1 /attr2 foo.h5 -

- -

-and both /attr1 and /attr2 would be dumped. In order to -do this now, one must issue the command: -

- -

- h5dump -a /attr1 -a /attr2 foo.h5 -

- -

XML Output

-The --xml option selects output in XML. The XML output contains -a complete description of the file, marked up in XML. The XML conforms to -the HDF5 Document Type Definition (DTD), which is available at: -

http://hdf.ncsa.uiuc.edu/DTDs/HDF5-File.dtd

-The XML output is suitable for use with other tools, including the HDF5 Java Tools. -

Options and Parameters:

-h or --help: Print a usage message and exit.
-B or --bootblock: Print the content of the boot block.
- (This option is not yet implemented.)
-H or --header: Print the header only; no data is displayed.
-i or --object-ids: Print the object ids.
-V or --version: Print version number and exit.
-a P or --attribute=P: Print the specified attribute.
-d P or --dataset=P: Print the specified dataset.
-g P or --group=P: Print the specified group and all members.
-l P or --soft-link=P: Print the value(s) of the specified soft link.
-o F or --output=F: Output raw data into file F.
-t T or --datatype=T: Print the specified named data type.
-w N or --width=N: Set the number of columns of output.
-x U or --xml: Output XML instead of DDL.
-D U or --xml-dtd=U: In XML output, refer to the DTD at U instead of the default DTD.
-s L or --start=L: Offset of start of subsetting selection [Default: beginning of - dataset]
-S L or --stride=L: Hyperslab stride [Default: 1 in all dimensions]
-c L or --count=L: Number of blocks to include in selection
-k L or --block=L: Size of block in hyperslab [Default: 1 in all dimensions]
file: The file to be examined.

P - is the full path from the root group to the object.
T - is the name of the data type.
F - is a filename.
N - is an integer greater than 1.
L - is a list of integers the number of which are equal to - the number of dimensions in the dataspace being queried.
U - is a URI (as defined in [IETF RFC - 2396], updated by [IETF RFC - 2732]) that refers to the DTD to be used to - validate the XML.

-Subsetting parameters can be specified in a convenient compact format. -The format is: -

- --dataset="/foo/mydataset[START;STRIDE;COUNT;BLOCK]" -

Tool Name: h5dump +

Syntax: +

h5dump
+        [

OPTIONS] file +

Purpose: +

Displays HDF5 file contents. +

Description: +

h5dump enables the user to interactively examine + the contents of an HDF5 file and dump those contents, in human + readable form, to an ASCII file. +

+ h5dump dumps HDF5 file content to standard output. + It can display the contents of the entire HDF5 file or + selected objects, which can be groups, datasets, a subset of a + dataset, links, attributes, or datatypes. +

+ The --header option displays object header + information only. +

+ Names are the absolute names of the objects. h5dump + displays objects in the order same as the command order. If a + name does not start with a slash, h5dump begins + searching for the specified object starting at the root group. +

+ If an object is hard linked with multiple names, + h5dump displays the content of the object in the + first occurrence. Only the link information is displayed in later + occurrences. +

+ h5dump assigns a name for any unnamed datatype in + the form of + #oid1:oid2, where + oid1 and oid2 are the object identifiers + assigned by the library. The unnamed types are displayed within + the root group. +

+ Datatypes are displayed with standard type names. For example, + if a dataset is created with H5T_NATIVE_INT type + and the standard type name for integer on that machine is + H5T_STD_I32BE, h5dump displays + H5T_STD_I32BE as the type of the dataset. +

+ h5dump can also dump a subset of a dataset. + This feature operates in much the same way as hyperslabs in HDF5; + the parameters specified on the commnd line are passed to the + function + H5Sselect_hyperslab and the resulting selection + is displayed. +

+ The h5dump output is described in detail in the + DDL for HDF5, the + Data Description Language document. +

+ Note: It is not permissable to specify multiple + attributes, datasets, datatypes, groups, or soft links with one + flag. For example, one may not issue the command +
+ + WRONG: + h5dump -a /attr1 /attr2 foo.h5 +
+ to display both /attr1 and /attr2. + One must issue the following command: +
+ + CORRECT: + h5dump -a /attr1 -a /attr2 foo.h5 +
+ +

XML Output: +

With the --xml option, h5dump generates + XML output. This output contains a complete description of the file, + marked up in XML. The XML conforms to the HDF5 Document Type + Definition (DTD) available at + + http://hdf.ncsa.uiuc.edu/DTDs/HDF5-File.dtd. +

+ The XML output is suitable for use with other tools, including the + HDF5 Java Tools. -

-All of the semicolons (;) are required to be there even if you don't -specify a value for the parameter (thereby using the default value). -

Options and Parameters: +
+
-h   or   + --help
+
Print a usage message and exit.
+
-B   or   + --bootblock
+
Print the content of the boot block.
+ (This option is not yet implemented.)
+
-H   or   + --header
+
Print the header only; no data is displayed.
+
-i   or   + --object-ids
+
Print the object ids.
+
-V   or   + --version
+
Print version number and exit.
+
-a P   or   + --attribute=P
+
Print the specified attribute.
+
-d P   or   + --dataset=P
+
Print the specified dataset.
+
-g P   or   + --group=P
+
Print the specified group and all members.
+
-l P   or   + --soft-link=P
+
Print the value(s) of the specified soft link.
+
-o F   or   + --output=F
+
Output raw data into file F.
+
-t T   or   + --datatype=T
+
Print the specified named datatype.
+
-w N   or   + --width=N
+
Set the number of columns of output.
+
-x U   or   + --xml
+
Output XML instead of DDL.
+
-D U   or   + --xml-dtd=U
+
In XML output, refer to the DTD at U + instead of the default DTD.
+
-s L   or   + --start=L
+
Offset of start of subsetting selection. +
+ Default: the beginning of the dataset.
+
-S L   or   + --stride=L
+
Hyperslab stride. +
+ Default: 1 in all dimensions.
+
-c L   or   + --count=L
+
Number of blocks to include in the selection.
+
-k L   or   + --block=L
+
Size of block in hyperslab. +
+ Default: 1 in all dimensions.
+
file
+
The file to be examined.
+

+
The option parameters listed above are defined as follows: +
P -- The full path from the root group to + the object
+
T -- The name of the datatype
+
F -- A filename
+
N -- An integer greater than 1
+
L -- A list of integers, the number of which is + equal to the number of dimensions in the dataspace being + queried
+
U -- A URI (as defined in + [IETF RFC 2396], + updated by + [IETF RFC 2732]) + that refers to the DTD to be used to validate the XML
+

+
Subsetting paramaters can also be expressed in a convenient + compact form, as follows: +
+          + --dataset="/foo/mydataset[START;STRIDE;COUNT;BLOCK]" +
+ All of the semicolons (;) are required, even when + a parameter value is not specified. + When not specified, default parameter values are used. +
+
-

Examples:

Examples:
-
Dumping the group /GroupFoo/GroupBar in the file - quux.h5:
- -
- h5dump -g /GroupFoo/GroupBar quux.h5 -
- -
Dumping the dataset Fnord in the group - /GroupFoo/GroupBar in the file quux.h5:
- -
- h5dump -d /GroupFoo/GroupBar/Fnord quux.h5 -
- -
Dumping the attribute metadata of the dataset - Fnord which is in group /GroupFoo/GroupBar in - the file quux.h5:
- -
- h5dump -a /GroupFoo/GroupBar/Fnord/metadata quux.h5 -
- -
Dumping the attribute metadata which is an attribute - of the root group in the file quux.h5:
- -
- h5dump -a /metadata quux.h5 -
- -
Producing an XML listing of the file bobo.h5:
- -
- h5dump --xml bobo.h5 > bobo.h5.xml -
- -
Dumping a subset of the dataset /GroupFoo/databar in - file quux.h5:
- -
- h5dump -d /GroupFoo/databar --start="1,1" --stride="2,3" --count="3,19" --block="1,1" quux.h5 -
- -
The same example using the short form of specifying the - subsetting parameters:
- -
- h5dump -d "/GroupFoo/databar[1,1;2,3;3,19;1,1]" quux.h5 -
+
Dumping the group /GroupFoo/GroupBar in the file + quux.h5: +
+ h5dump -g /GroupFoo/GroupBar quux.h5 +
+
Dumping the dataset Fnord in the group + /GroupFoo/GroupBar in the file quux.h5: +
+ h5dump -d /GroupFoo/GroupBar/Fnord quux.h5 +
+
Dumping the attribute metadata of the dataset + Fnord which is in group + /GroupFoo/GroupBar in the file quux.h5: +
+ h5dump -a /GroupFoo/GroupBar/Fnord/metadata quux.h5 +
+
Dumping the attribute metadata which is an + attribute of the root group in the file quux.h5: +
+ h5dump -a /metadata quux.h5 +
+
Producing an XML listing of the file bobo.h5: +
+ h5dump --xml bobo.h5 > bobo.h5.xml +
+
Dumping a subset of the dataset /GroupFoo/databar/ + in the file quux.h5 +
+ h5dump -d /GroupFoo/databar --start="1,1" --stride="2,3" + + --count="3,19" --block="1,1" quux.h5 +
+
The same example using the short form to specify the + subsetting parameters: +
+ h5dump -d "/GroupFoo/databar[1,1;2,3;3,19;1,1]" quux.h5 +

- -

Current Status:

The current version of h5dump displays the following - information:

Current Status: +

The current version of h5dump displays the + following information: +

Group +
- group attribute (see Attribute) +
- group member +
+
Dataset +
- dataset attribute (see Attribute) +
- dataset type (see Datatype) +
- dataset space (see Dataspace) +
- dataset data +
+
Attribute +
- attribute type (see Datatype) +
- attribute space (see Dataspace) +
- attribute data +
+
Datatype +
- integer type +
  + - H5T_STD_I8BE, H5T_STD_I8LE, H5T_STD_I16BE, ... +
- floating point type +
  + - H5T_IEEE_F32BE, H5T_IEEE_F32LE, H5T_IEEE_F64BE, ... +
- string type +
- compound type +
  + - named, unnamed and transient compound type +
  + - integer, floating or string type member +
- opaque types +
- reference type +
  + - object references +
  + - data regions +
- enum type +
- variable-length datatypes +
  + - atomic types only +
  + - scalar or single dimensional array of variable-length + types supported +
+
Dataspace +
- scalar and simple space +
+
Soft link +
Hard link +
Loop detection +

+ +

See Also:
-
Group
- -
-
group attribute (see Attribute)
- -
group member
-
- -
Dataset
- -
-
dataset attribute (see Attribute)
- -
dataset type (see Data type)
- -
dataset space (see Data space)
- -
dataset data
-
- -
Attribute
- -
-
attribute type (see Data type)
- -
attribute space (see Data space)
- -
attribute data
-
+
HDF5 Data Description Language syntax at + DDL for HDF5 -
Data type
+
HDF5 XML DTD at + http://hdf.ncsa.uiuc.edu/DTDs/HDF5-File.dtd -
-
integer type
- -
- H5T_STD_I8BE, H5T_STD_I8LE, H5T_STD_I16BE, ...
- -
floating point type
- -
- H5T_IEEE_F32BE, H5T_IEEE_F32LE, H5T_IEEE_F64BE, ...
- -
string type
- -
compound type
- -
- named, unnamed and transient compound type
- -
- integer, floating or string type member
- -
opaque types
- -
reference type
- -
- object references
- -
- data regions
- -
enum type
- -
variable-length datatypes
- -
- atomic types only
- -
- scalar or single dimensional array of variable-length types - supported
-
- -
Data space
- -
-
scalar and simple space
-
- -
Soft link
- -
Hard link
- -
Loop detection
+
HDF5 XML information at + http://hdf.ncsa.uiuc.edu/HDF5/XML/
-

See Also:

HDF5 Data Description Language syntax (DDL - for HDF5)

HDF5 XML DTD: http://hdf.ncsa.uiuc.edu/DTDs/HDF5-File.dtd

HDF5 XML information: http://hdf.ncsa.uiuc.edu/HDF5/XML/

-Tool Name: h5ls
-Syntax:: -h5ls [OPTIONS] file [OBJECTS...]
-Purpose:: -Prints information about a file or dataset.
-Description:: -h5ls prints selected information about file objects in the specified -format.
-Options and Parameters:
Tool Name: h5ls +
Syntax: +: h5ls + [OPTIONS] + file+ [OBJECTS...] +
Purpose: +: Prints information about a file or dataset. +
Description: +: h5ls prints selected information about file objects + in the specified format. +
Options and Parameters: +
+
-h   or   + -?   or   + --help +
Print a usage message and exit. +
-a   or   + --address +
Print addresses for raw data. +
-d   or   --data +
Print the values of datasets. +
-e   or   + --errors +
Show all HDF5 error reporting. +
-f   or   + --full +
Print full path names instead of base names. +
-g   or   + --group +
Show information about a group, not its contents. +
-l   or   + --label +
Label members of compound datasets. +
-r   or   + --recursive +
List all groups recursively, avoiding cycles. +
-s   or   + --string +
Print 1-bytes integer datasets as ASCII. +
-S   or   + --simple +
Use a machine-readable output format. +
-wN   or   + --width=N +
Set the number of columns of output. +
-v   or   + --verbose +
Generate more verbose output. +
-V   or   + --version +
Print version number and exit. +
-x   or   + --hexdump +
Show raw data in hexadecimal format. +
file +
The file name may include a printf(3C) integer format + such as %%05d to open a file family. +
objects +
Each object consists of an HDF5 file name optionally + followed by a slash and an object name within the file + (if no object is specified within the file then the + contents of the root group are displayed). The file name + may include a printf(3C) integer format such + as "%05d" to open a file family. +

+--> +

-Tool Name: h5repart
-Syntax:: -h5repart [-v] [-V] [-[b|m]N[g|m|k]] source_file -dest_file
-Purpose:: -Repartitions a file or family of files.
-Description:: -h5repart splits a single file into a family of files, joins a -family of files into a single file, or copies one family of files to another -while changing the size of the family members. h5repart can also -be used to copy a single file to a single file with holes.
-Options and Parameters:
Options and Parameters: +
+
-v +
Produce verbose output. +
-V +
Print a version number and exit. +
-bN +
The I/O block size, defaults to 1kB +
-mN +
The destination member size or 1GB +
source_file +
The name of the source file +
dest_file +
The name of the destination files +

+--> + -

-Tool Name: h5toh4
-Syntax:: -h5toh4 -h
-Purpose:: -Converts an HDF5 file into an HDF4 file.
-Description:: -h5toh4 is an HDF5 utility which reads an HDF5 file, h5file, -and converts all supported objects and pathways to produce an HDF4 file, -h4file. -If h4file already exists, it will be replaced.
-Options and Parameters:
Options and Parameters: +
+
-h +
Displays a syntax summary. +
-m +
Converts multiple HDF5 files to multiple HDF4 files. +
h5file +
The HDF5 file to be converted. +
h4file +
The HDF4 file to be created. +

+--> + +

-Tool Name: h4toh5
-Syntax:: -h4toh5 -h
-Purpose:: -Converts an HDF4 file to an HDF5 file.
-Description:: -h4toh5 is a file conversion utility that reads an HDF4 file, h4file -(input.hdf for example), and writes an HDF5 file, h5file -(output.h5 for example), containing the same data.
-Options and Parameters:

HDF4 Object	Resulting HDF5 Object
SDS	Dataset
GR, RI8, and RI24 image	Dataset
Vdata	Dataset
Vgroup	Group
Annotation	Attribute
Palette	Dataset

+ HDF4 Object +	+ Resulting HDF5 Object +
+ SDS +	+ Dataset +
+ GR, RI8, and RI24 image +	+ Dataset +
+ Vdata +	+ Dataset +
+ Vgroup +	+ Group +
+ Annotation +	+ Attribute +
+ Palette +	+ Dataset +

- + + + + + + + +

- - - - - - -

Introduction to HDF5 -
HDF5 User Guide -
Other HDF5 documents and links -

And in this document, the HDF5 -Reference Manual -
H5 H5A -H5D -H5E -H5F H5G - -H5I H5P -
H5R H5S -H5T -H5Z Tools Datatypes

- +--> + + +And in this document, the +HDF5 Reference Manual   +
+H5   +H5A   +H5D   +H5E   +H5F   +H5G   +H5I   +H5P   +
+H5R   +H5S   +H5T   +H5Z   +Tools   +Datatypes   + + +

+ +

-HDF Help Desk

+HDF Help Desk + +
+Last modified: 18 April 2001 + +
+Describes HDF5 Release 1.4.1, April 2001 + -
Last modified: 15 December 2000 -
Describes HDF5 Release 1.4, February 2001 -- cgit v0.12