summaryrefslogtreecommitdiffstats
path: root/doxygen/dox/ViewTools.dox
diff options
context:
space:
mode:
Diffstat (limited to 'doxygen/dox/ViewTools.dox')
-rw-r--r--doxygen/dox/ViewTools.dox1198
1 files changed, 1198 insertions, 0 deletions
diff --git a/doxygen/dox/ViewTools.dox b/doxygen/dox/ViewTools.dox
new file mode 100644
index 0000000..0b685a0
--- /dev/null
+++ b/doxygen/dox/ViewTools.dox
@@ -0,0 +1,1198 @@
+/** @page ViewTools Tools for Viewing and Editing HDF5 Files
+
+Navigate back: \ref index "Main" / \ref GettingStarted
+<hr>
+
+\section secToolsBasic Basic Facts about HDF5
+The following are basic facts about HDF5 files to keep in mind while completing these tutorial topics:
+\li All HDF5 files contain a root group "/".
+\li There are two primary objects in HDF5, a group and a dataset:<br />
+ Groups allow objects to be organized into a group structure, such as a tree.<br />
+ Datasets contain raw data values.
+\li Additional information about an HDF5 object may optionally be stored in attributes attached to the object.
+
+\section secToolsTopics Tutorial Topics
+<table>
+<tr>
+<th>Tutorial Topic</th>
+<th>Description</th>
+</tr>
+<tr>
+<td>
+@ref LearnHDFView
+</td>
+<td>Use HDFView to create, edit and view files.
+</td>
+</tr>
+<tr>
+<td>
+@ref ViewToolsCommand
+</td>
+<td>Use the HDF5 command-line tools for viewing, editing, and comparing HDF5 files.
+</td>
+</tr>
+<tr>
+<td>@ref ViewToolsJPSS
+</td>
+<td>Use HDF5 tools to examine and work with JPSS NPP files.
+</td>
+</tr>
+</table>
+
+<hr>
+Navigate back: \ref index "Main" / \ref GettingStarted
+
+@page ViewToolsCommand Command-line Tools
+Navigate back: \ref index "Main" / \ref GettingStarted
+<hr>
+
+\section secViewToolsCommandObtain Obtain Tools and Files (Optional)
+Pre-built binaries for Linux and Windows are distributed within the respective HDF5 binary release
+packages, which can be obtained from the <a href="https://portal.hdfgroup.org/display/support/Download+HDF5">Download HDF5</a> page.
+
+HDF5 files can be obtained from various places such as \ref HDF5Examples and <a href="http://www.hdfeos.org/">HDF-EOS and Tools and
+Information Center</a>. Specifically, the following examples are used in this tutorial topic:
+\li HDF5 Files created from compiling the \ref LBExamples
+\li HDF5 Files on the <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page
+\li NPP JPSS files, <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/SVM01_npp_d20130524_t1255132_e1256374_b08146_c20130524192048864992_noaa_ops.h5.gz">SVM01_npp.. (gzipped)</a>
+and <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5.gz">SVM09_npp.. (gzipped)</a>
+\li HDF-EOS <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/OMI-Aura.he5">OMI-Aura file</a>
+
+\section secViewToolsCommandTutor Tutorial Topics
+A variety of command-line tools are included in the HDF5 binary distribution. There are tools to view,
+edit, convert and compare HDF5 files. This tutorial discusses the tools by their functionality. It
+does not cover all of the HDF5 tools.
+
+<table>
+<tr>
+<th>Tool Category</th>
+<th>Topic</th>
+<th>Tools Used</th>
+</tr>
+<tr>
+<td><strong>@ref ViewToolsView</strong></td>
+<td>@ref secViewToolsViewContent</td>
+<td>h5dump and h5ls
+</td>
+</tr>
+<tr>
+<td></td>
+<td>@ref secViewToolsViewDset</td>
+<td>h5dump and h5ls
+</td>
+</tr>
+<tr>
+<td></td>
+<td>@ref secViewToolsViewGrps</td>
+<td>h5dump and h5ls
+</td>
+</tr>
+<tr>
+<td></td>
+<td>@ref secViewToolsViewAttr</td>
+<td>h5dump
+</td>
+</tr>
+<tr>
+<td></td>
+<td>@ref secViewToolsViewSub</td>
+<td>h5dump
+</td>
+</tr>
+<tr>
+<td></td>
+<td>@ref secViewToolsViewDtypes</td>
+<td>h5dump
+</td>
+</tr>
+<tr>
+<td>@ref ViewToolsEdit</td>
+<td>@ref secViewToolsEditRemove</td>
+<td>h5repack
+</td>
+</tr>
+<tr>
+<td></td>
+<td>@ref secViewToolsEditChange</td>
+<td>h5repack
+</td>
+</tr>
+<tr>
+<td></td>
+<td>@ref secViewToolsEditApply</td>
+<td>h5repack
+</td>
+</tr>
+<tr>
+<td></td>
+<td>@ref secViewToolsEditCopy</td>
+<td>h5copy
+</td>
+</tr>
+<tr>
+<td></td>
+<td>@ref secViewToolsEditAdd</td>
+<td>h5jam and h5unjam
+</td>
+</tr>
+<tr>
+<td>@ref ViewToolsConvert</td>
+<td>@ref secViewToolsConvertASCII</td>
+<td>h5dump
+</td>
+</tr>
+<tr>
+<td></td>
+<td>@ref secViewToolsConvertBinary</a></td>
+<td>h5dump
+</td>
+</tr>
+<tr>
+<td></td>
+<td>@ref secViewToolsConvertExport</td>
+<td>h5dump and h5import
+</td>
+</tr>
+</table>
+
+<hr>
+Navigate back: \ref index "Main" / \ref GettingStarted
+
+@page ViewToolsView Command-line Tools For Viewing HDF5 Files
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand
+<hr>
+
+\section secViewToolsViewTOC Contents
+<ul>
+<li>\ref secViewToolsViewContent</li>
+<li>\ref secViewToolsViewDset</li>
+<li>\ref secViewToolsViewGrps</li>
+<li>\ref secViewToolsViewAttr</li>
+<li>\ref secViewToolsViewSub</li>
+<li>\ref secViewToolsViewDtypes</li>
+</ul>
+
+\section secViewToolsViewContent File Content and Structure
+The h5dump and h5ls tools can both be used to view the contents of an HDF5 file. The tools are discussed below:
+<ul>
+<li>\ref subsecViewToolsViewContent_h5dump</li>
+<li>\ref subsecViewToolsViewContent_h5ls</li>
+</ul>
+
+\subsection subsecViewToolsViewContent_h5dump h5dump
+The h5dump tool dumps or displays the contents of an HDF5 file (textually). By default if you specify no options,
+h5dump will display the entire contents of a file. There are many h5dump options for examining specific details
+of a file. To see all of the available h5dump options, specify the <code style="background-color:whitesmoke;">-h</code>
+or <code style="background-color:whitesmoke;">--help</code> option:
+\code
+h5dump -h
+\endcode
+
+The following h5dump options can be helpful in viewing the content and structure of a file:
+<table>
+<tr>
+<th>Option</th>
+<th>Description</th>
+<th>Comment</th>
+</tr>
+<tr>
+<td>-n, --contents
+</td>
+<td>Displays a list of the objects in a file
+</td>
+<td>See @ref subsubsecViewToolsViewContent_h5dumpEx1
+</td>
+</tr>
+<tr>
+<td>-n 1, --contents=1
+</td>
+<td>Displays a list of the objects and attributes in a file
+</td>
+<td>See @ref subsubsecViewToolsViewAttr_h5dumpEx6
+</td>
+</tr>
+<tr>
+<td>-H, --header
+</td>
+<td>Displays header information only (no data)
+</td>
+<td>See @ref subsubsecViewToolsViewContent_h5dumpEx2
+</td>
+</tr>
+<tr>
+<td>-A 0, --onlyattr=0
+</td>
+<td>Suppresses the display of attributes
+</td>
+<td>See @ref subsubsecViewToolsViewContent_h5dumpEx2
+</td>
+</tr>
+<tr>
+<td>-N P, --any_path=P
+</td>
+<td>Displays any object or attribute that matches path P
+</td>
+<td>See @ref subsubsecViewToolsViewAttr_h5dumpEx6
+</td>
+</tr>
+</table>
+
+\subsubsection subsubsecViewToolsViewContent_h5dumpEx1 Example 1
+The following command displays a list of the objects in the file OMI-Aura.he5 (an HDF-EOS5 file):
+\code
+h5dump -n OMI-Aura.he5
+\endcode
+
+As shown in the output below, the objects (groups, datasets) are listed to the left, followed by their
+names. You can see that this file contains two root groups, HDFEOS and HDFEOS INFORMATION:
+\code
+HDF5 "OMI-Aura.he5" {
+FILE_CONTENTS {
+ group /
+ group /HDFEOS
+ group /HDFEOS/ADDITIONAL
+ group /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES
+ group /HDFEOS/GRIDS
+ group /HDFEOS/GRIDS/OMI Column Amount O3
+ group /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields
+ dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/ColumnAmountO3
+ dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/RadiativeCloudFraction
+ dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle
+ dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/ViewingZenithAngle
+ group /HDFEOS INFORMATION
+ dataset /HDFEOS INFORMATION/StructMetadata.0
+ }
+}
+\endcode
+
+\subsubsection subsubsecViewToolsViewContent_h5dumpEx2 Example 2
+The file structure of the OMI-Aura.he5 file can be seen with the following command. The -A 0 option suppresses the display of attributes:
+\code
+h5dump -H -A 0 OMI-Aura.he5
+\endcode
+
+Output of this command is shown below:
+\code
+HDF5 "OMI-Aura.he5" {
+GROUP "/" {
+ GROUP "HDFEOS" {
+ GROUP "ADDITIONAL" {
+ GROUP "FILE_ATTRIBUTES" {
+ }
+ }
+ GROUP "GRIDS" {
+ GROUP "OMI Column Amount O3" {
+ GROUP "Data Fields" {
+ DATASET "ColumnAmountO3" {
+ DATATYPE H5T_IEEE_F32LE
+ DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
+ }
+ DATASET "RadiativeCloudFraction" {
+ DATATYPE H5T_IEEE_F32LE
+ DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
+ }
+ DATASET "SolarZenithAngle" {
+ DATATYPE H5T_IEEE_F32LE
+ DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
+ }
+ DATASET "ViewingZenithAngle" {
+ DATATYPE H5T_IEEE_F32LE
+ DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
+ }
+ }
+ }
+ }
+ }
+ GROUP "HDFEOS INFORMATION" {
+ DATASET "StructMetadata.0" {
+ DATATYPE H5T_STRING {
+ STRSIZE 32000;
+ STRPAD H5T_STR_NULLTERM;
+ CSET H5T_CSET_ASCII;
+ CTYPE H5T_C_S1;
+ }
+ DATASPACE SCALAR
+ }
+ }
+}
+}
+\endcode
+
+\subsection subsecViewToolsViewContent_h5ls h5ls
+The h5ls tool by default just displays the objects in the root group. It will not display
+items in groups beneath the root group unless specified. Useful h5ls options for viewing
+file content and structure are:
+<table>
+<tr>
+<th>Option</th>
+<th>Description</th>
+<th>Comment</th>
+</tr>
+<tr>
+<td>-r
+</td>
+<td>Lists all groups and objects recursively
+</td>
+<td>See @ref subsubsecViewToolsViewContent_h5lsEx3
+</td>
+</tr>
+<tr>
+<td>-v
+</td>
+<td>Generates verbose output (lists dataset properties, attributes
+and attribute values, but no dataset values)
+</td>
+<td>
+</td>
+</tr>
+</table>
+
+\subsubsection subsubsecViewToolsViewContent_h5lsEx3 Example 3
+The following command shows the contents of the HDF-EOS5 file OMI-Aura.he5. The output is similar to h5dump, except that h5ls also shows dataspace information for each dataset:
+\code
+h5ls -r OMI-Aura.he5
+\endcode
+
+The output is shown below:
+\code
+/ Group
+/HDFEOS Group
+/HDFEOS/ADDITIONAL Group
+/HDFEOS/ADDITIONAL/FILE_ATTRIBUTES Group
+/HDFEOS/GRIDS Group
+/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3 Group
+/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields Group
+/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ColumnAmountO3 Dataset {720, 1440}
+/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/RadiativeCloudFraction Dataset {720, 1440}
+/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/SolarZenithAngle Dataset {720, 1440}
+/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ViewingZenithAngle Dataset {720, 1440}
+/HDFEOS\ INFORMATION Group
+/HDFEOS\ INFORMATION/StructMetadata.0 Dataset {SCALAR}
+\endcode
+
+\section secViewToolsViewDset Datasets and Dataset Properties
+Both h5dump and h5ls can be used to view specific datasets.
+<ul>
+<li>\ref subsecViewToolsViewDset_h5dump</li>
+<li>\ref subsecViewToolsViewDset_h5ls</li>
+</ul>
+
+\subsection subsecViewToolsViewDset_h5dump h5dump
+Useful h5dump options for examining specific datasets include:
+<table>
+<tr>
+<th>Option</th>
+<th>Description</th>
+<th>Comment</th>
+</tr>
+<tr>
+<td>-d D, --dataset=D
+</td>
+<td>Displays dataset D
+</td>
+<td>See @ref subsubsecViewToolsViewDset_h5dumpEx4
+</td>
+</tr>
+<tr>
+<td> -H, --header
+</td>
+<td>Displays header information only
+</td>
+<td>See @ref subsubsecViewToolsViewDset_h5dumpEx4
+</td>
+</tr>
+<tr>
+<td>-p, --properties
+</td>
+<td>Displays dataset filters, storage layout, and fill value properties
+</td>
+<td>See @ref subsubsecViewToolsViewDset_h5dumpEx5
+</td>
+</tr>
+<tr>
+<td>-A 0, --onlyattr=0
+</td>
+<td>Suppresses the display of attributes
+</td>
+<td>See @ref subsubsecViewToolsViewContent_h5dumpEx2
+</td>
+</tr>
+<tr>
+<td>-N P, --any_path=P
+</td>
+<td>Displays any object or attribute that matches path P
+</td>
+<td>See @ref subsubsecViewToolsViewAttr_h5dumpEx6
+</td>
+</tr>
+</table>
+
+\subsubsection subsubsecViewToolsViewDset_h5dumpEx4 Example 4
+A specific dataset can be viewed with <code style="background-color:whitesmoke;">h5dump</code> using the <code style="background-color:whitesmoke;">-d D</code> option and specifying the entire
+path and name of the dataset for <code style="background-color:whitesmoke;">D</code>. The path is important in identifying the correct dataset,
+as there can be multiple datasets with the same name. The path can be determined by looking at
+the objects in the file with <code style="background-color:whitesmoke;">h5dump -n</code>.
+
+The following example uses the <code style="background-color:whitesmoke;">groups.h5</code> file that is created by the
+\ref LBExamples
+example <code style="background-color:whitesmoke;">h5_crtgrpar.c</code>. To display <code style="background-color:whitesmoke;">dset1</code> in the <code style="background-color:whitesmoke;">groups.h5</code> file below, specify dataset
+<code style="background-color:whitesmoke;">/MyGroup/dset1</code>. The <code style="background-color:whitesmoke;">-H</code> option is used to suppress printing of the data values:
+
+<em>Contents of groups.h5</em>
+\code
+ $ h5dump -n groups.h5
+ HDF5 "groups.h5" {
+ FILE_CONTENTS {
+ group /
+ group /MyGroup
+ group /MyGroup/Group_A
+ dataset /MyGroup/Group_A/dset2
+ group /MyGroup/Group_B
+ dataset /MyGroup/dset1
+ }
+ }
+\endcode
+
+<em>Display dataset "dset1"</em>
+\code
+ $ h5dump -d "/MyGroup/dset1" -H groups.h5
+ HDF5 "groups.h5" {
+ DATASET "/MyGroup/dset1" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) }
+ }
+ }
+\endcode
+
+\subsubsection subsubsecViewToolsViewDset_h5dumpEx5 Example 5
+The <code style="background-color:whitesmoke;">-p</code> option is used to examine the the dataset filters, storage layout, and fill value properties of a dataset.
+
+This option can be useful for checking how well compression works, or even for analyzing performance
+and dataset size issues related to chunking. (The smaller the chunk size, the more chunks that HDF5
+has to keep track of, which increases the size of the file and potentially affects performance.)
+
+In the file shown below the dataset <code style="background-color:whitesmoke;">/DS1</code> is both chunked and compressed:
+\code
+ $ h5dump -H -p -d "/DS1" h5ex_d_gzip.h5
+ HDF5 "h5ex_d_gzip.h5" {
+ DATASET "/DS1" {
+ DATATYPE H5T_STD_I32LE
+ DATASPACE SIMPLE { ( 32, 64 ) / ( 32, 64 ) }
+ STORAGE_LAYOUT {
+ CHUNKED ( 4, 8 )
+ SIZE 5278 (1.552:1 COMPRESSION)
+ }
+ FILTERS {
+ COMPRESSION DEFLATE { LEVEL 9 }
+ }
+ FILLVALUE {
+ FILL_TIME H5D_FILL_TIME_IFSET
+ VALUE 0
+ }
+ ALLOCATION_TIME {
+ H5D_ALLOC_TIME_INCR
+ }
+ }
+ }
+\endcode
+
+You can obtain the <code style="background-color:whitesmoke;">h5ex_d_gzip.c</code> program that created this file, as well as the file created,
+from the <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page.
+
+\subsection subsecViewToolsViewDset_h5ls h5ls
+Specific datasets can be specified with <code style="background-color:whitesmoke;">h5ls</code> by simply adding the dataset path and dataset after the
+file name. As an example, this command displays dataset <code style="background-color:whitesmoke;">dset2</code> in the <code style="background-color:whitesmoke;">groups.h5</code>
+file used in @ref subsubsecViewToolsViewDset_h5dumpEx4 :
+\code
+h5ls groups.h5/MyGroup/Group_A/dset2
+\endcode
+
+Just the dataspace information gets displayed:
+\code
+dset2 Dataset {2, 10}
+\endcode
+
+The following options can be used to see detailed information about a dataset.
+<table>
+<tr>
+<th>Option</th>
+<th>Description</th>
+</tr>
+<tr>
+<td>-v, --verbose
+</td>
+<td>Generates verbose output (lists dataset properties, attributes
+and attribute values, but no dataset values)
+</td>
+</tr>
+<tr>
+<td>-d, --data
+</td>
+<td>Displays dataset values
+</td>
+</tr>
+</table>
+
+The output of using <code style="background-color:whitesmoke;">-v</code> is shown below:
+\code
+ $ h5ls -v groups.h5/MyGroup/Group_A/dset2
+ Opened "groups.h5" with sec2 driver.
+ dset2 Dataset {2/2, 10/10}
+ Location: 1:3840
+ Links: 1
+ Storage: 80 logical bytes, 80 allocated bytes, 100.00% utilization
+ Type: 32-bit big-endian integer
+\endcode
+
+The output of using <code style="background-color:whitesmoke;">-d</code> is shown below:
+\code
+ $ h5ls -d groups.h5/MyGroup/Group_A/dset2
+ dset2 Dataset {2, 10}
+ Data:
+ (0,0) 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
+\endcode
+
+\section secViewToolsViewGrps Groups
+Both h5dump and h5ls can be used to view specific groups in a file.
+<ul>
+<li>\ref subsecViewToolsViewGrps_h5dump</li>
+<li>\ref subsecViewToolsViewGrps_h5ls</li>
+</ul>
+
+\subsection subsecViewToolsViewGrps_h5dump h5dump
+The <code style="background-color:whitesmoke;">h5dump</code> options that are useful for examining groups are:
+<table>
+<tr>
+<th>Option</th>
+<th>Description</th>
+</tr>
+<tr>
+<td>-g G, --group=G
+</td>
+<td>Displays group G and its members
+</td>
+</tr>
+<tr>
+<td>-H, --header
+</td>
+<td>Displays header information only
+</td>
+</tr>
+<tr>
+<td>-A 0, --onlyattr=0
+</td>
+<td>Suppresses the display of attributes
+</td>
+</tr>
+</table>
+
+To view the contents of the <code style="background-color:whitesmoke;">HDFEOS</code> group in the OMI file mentioned previously, you can specify the path and name of the group as follows:
+\code
+h5dump -g "/HDFEOS" -H -A 0 OMI-Aura.he5
+\endcode
+
+The <code style="background-color:whitesmoke;">-A 0</code> option suppresses attributes and <code style="background-color:whitesmoke;">-H</code> suppresses printing of data values:
+\code
+ HDF5 "OMI-Aura.he5" {
+ GROUP "/HDFEOS" {
+ GROUP "ADDITIONAL" {
+ GROUP "FILE_ATTRIBUTES" {
+ }
+ }
+ GROUP "GRIDS" {
+ GROUP "OMI Column Amount O3" {
+ GROUP "Data Fields" {
+ DATASET "ColumnAmountO3" {
+ DATATYPE H5T_IEEE_F32LE
+ DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
+ }
+ DATASET "RadiativeCloudFraction" {
+ DATATYPE H5T_IEEE_F32LE
+ DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
+ }
+ DATASET "SolarZenithAngle" {
+ DATATYPE H5T_IEEE_F32LE
+ DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
+ }
+ DATASET "ViewingZenithAngle" {
+ DATATYPE H5T_IEEE_F32LE
+ DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
+ }
+ }
+ }
+ }
+ }
+ }
+\endcode
+
+\subsection subsecViewToolsViewGrps_h5ls h5ls
+You can view the contents of a group with <code style="background-color:whitesmoke;">h5ls</code>/ by specifying the group after the file name.
+To use <code style="background-color:whitesmoke;">h5ls</code> to view the contents of the <code style="background-color:whitesmoke;">/HDFEOS</code> group in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type:
+\code
+h5ls -r OMI-Aura.he5/HDFEOS
+\endcode
+
+The output of this command is:
+\code
+ /ADDITIONAL Group
+ /ADDITIONAL/FILE_ATTRIBUTES Group
+ /GRIDS Group
+ /GRIDS/OMI\ Column\ Amount\ O3 Group
+ /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields Group
+ /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ColumnAmountO3 Dataset {720, 1440}
+ /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/RadiativeCloudFraction Dataset {720, 1440}
+ /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/SolarZenithAngle Dataset {720, 1440}
+ /GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ViewingZenithAngle Dataset {720, 1440}
+\endcode
+
+If you specify the <code style="background-color:whitesmoke;">-v</code> option, you can also see the attributes and properties of the datasets.
+
+\section secViewToolsViewAttr Attributes
+
+\subsection subsecViewToolsViewAttr_h5dump h5dump
+Attributes are displayed by default if using <code style="background-color:whitesmoke;">h5dump</code>. Some files contain many attributes, which
+can make it difficult to examine the objects in the file. Shown below are options that can help
+when using <code style="background-color:whitesmoke;">h5dump</code> to work with files that have attributes.
+
+\subsubsection subsubsecViewToolsViewAttr_h5dumpEx6 Example 6
+The <code style="background-color:whitesmoke;">-a</code> A option will display an attribute. However, the path to the attribute must be included
+when specifying this option. For example, to see the <code style="background-color:whitesmoke;">ScaleFactor</code> attribute in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type:
+\code
+h5dump -a "/HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle/ScaleFactor" OMI-Aura.he5
+\endcode
+
+This command displays:
+\code
+ HDF5 "OMI-Aura.he5" {
+ ATTRIBUTE "ScaleFactor" {
+ DATATYPE H5T_IEEE_F64LE
+ DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
+ DATA {
+ (0): 1
+ }
+ }
+ }
+\endcode
+
+How can you determine the path to the attribute? This can be done by looking at the file contents with the <code style="background-color:whitesmoke;">-n 1</code> option:
+\code
+h5dump -n 1 OMI-Aura.he5
+\endcode
+
+Below is a portion of the output for this command:
+\code
+ HDF5 "OMI-Aura.he5" {
+ FILE_CONTENTS {
+ group /
+ group /HDFEOS
+ group /HDFEOS/ADDITIONAL
+ group /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/EndUTC
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleDay
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleDayOfYear
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleMonth
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleYear
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/InstrumentName
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/OrbitNumber
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/OrbitPeriod
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/PGEVersion
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/Period
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/ProcessLevel
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/StartUTC
+ attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/TAI93At0zOfGranule
+
+ ...
+\endcode
+
+There can be multiple objects or attributes with the same name in a file. How can you make sure
+you are finding the correct object or attribute? You can first determine how many attributes
+there are with a specified name, and then examine the paths to them.
+
+The <code style="background-color:whitesmoke;">-N</code> option can be used to display all objects or attributes with a given name.
+For example, there are four attributes with the name <code style="background-color:whitesmoke;">ScaleFactor</code> in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file,
+as can be seen below with the <code style="background-color:whitesmoke;">-N</code> option:
+\code
+h5dump -N ScaleFactor OMI-Aura.he5
+\endcode
+
+It outputs:
+\code
+HDF5 "OMI-Aura.he5" {
+ATTRIBUTE "ScaleFactor" {
+ DATATYPE H5T_IEEE_F64LE
+ DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
+ DATA {
+ (0): 1
+ }
+}
+ATTRIBUTE "ScaleFactor" {
+ DATATYPE H5T_IEEE_F64LE
+ DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
+ DATA {
+ (0): 1
+ }
+}
+ATTRIBUTE "ScaleFactor" {
+ DATATYPE H5T_IEEE_F64LE
+ DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
+ DATA {
+ (0): 1
+ }
+}
+ATTRIBUTE "ScaleFactor" {
+ DATATYPE H5T_IEEE_F64LE
+ DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
+ DATA {
+ (0): 1
+ }
+}
+}
+\endcode
+
+\subsection subsecViewToolsViewAttr_h5ls h5ls
+If you include the <code style="background-color:whitesmoke;">-v</code> (verbose) option for <code style="background-color:whitesmoke;">h5ls</code>, you will see all of the attributes for the
+specified file, dataset or group. You cannot display individual attributes.
+
+\section secViewToolsViewSub Dataset Subset
+
+\subsection subsecViewToolsViewSub_h5dump h5dump
+If you have a very large dataset, you may wish to subset or see just a portion of the dataset.
+This can be done with the following <code style="background-color:whitesmoke;">h5dump</code> options.
+<table>
+<tr>
+<th>Option</th>
+<th>Description</th>
+</tr>
+<tr>
+<td>-d D, --dataset=D
+</td>
+<td>Dataset D
+</td>
+</tr>
+<tr>
+<td>-s START, --start=START
+</td>
+<td>Offset or start of subsetting selection
+</td>
+</tr>
+<tr>
+<td>-S STRIDE, --stride=STRIDE
+</td>
+<td>Stride (sampling along a dimension). The default (unspecified, or 1) selects
+every element along a dimension, a value of 2 selects every other element,
+a value of 3 selects every third element, ...
+</td>
+</tr>
+<tr>
+<td>-c COUNT, --count=COUNT
+</td>
+<td>Number of blocks to include in the selection
+</td>
+</tr>
+<tr>
+<td>-k BLOCK, --block=BLOCK
+</td>
+<td>Size of the block in a hyperslab. The default (unspecified, or 1) is for
+the block size to be the size of a single element.
+</td>
+</tr>
+</table>
+
+The <code style="background-color:whitesmoke;">START (s)</code>, <code style="background-color:whitesmoke;">STRIDE (S)</code>, <code style="background-color:whitesmoke;">COUNT (c)</code>, and <code style="background-color:whitesmoke;">BLOCK (k)</code> options
+define the shape and size of the selection. They are arrays with the same number of dimensions as the rank
+of the dataset's dataspace, and they all work together to define the selection. A change to one of
+these arrays can affect the others.
+
+When specifying these h5dump options, a comma is used as the delimiter for each dimension in the
+option value. For example, with a 2-dimensional dataset, the option value is specified as "H,W",
+where H is the height and W is the width. If the offset is 0 for both dimensions, then
+<code style="background-color:whitesmoke;">START</code> would be specified as follows:
+\code
+-s "0,0"
+\endcode
+
+There is also a shorthand way to specify these options with brackets at the end of the dataset name:
+\code
+-d DATASETNAME[s;S;c;k]
+\endcode
+
+Multiple dimensions are separated by commas. For example, a subset for a 2-dimensional dataset would be specified as follows:
+\code
+-d DATASETNAME[s,s;S,S;c,c;k,k]
+\endcode
+
+For a detailed understanding of how selections works, see the #H5Sselect_hyperslab API in the \ref RM.
+
+The dataset SolarZenithAngle in the OMI-Aura.he5 file can be used to illustrate these options. This
+dataset is a 2-dimensional dataset of size 720 (height) x 1440 (width). Too much data will be displayed
+by simply viewing the specified dataset with the <code style="background-color:whitesmoke;">-d</code> option:
+\code
+h5dump -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" OMI-Aura.he5
+\endcode
+Subsetting narrows down the output that is displayed. In the following example, the first
+15x10 elements (-c "15,10") are specified, beginning with position (0,0) (-s "0,0"):
+\code
+ h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" -s "0,0" -c "15,10" -w 0 OMI-Aura.he5
+\endcode
+
+If using the shorthand method, specify:
+\code
+ h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle[0,0;;15,10;]" -w 0 OMI-Aura.he5
+\endcode
+
+Where,
+\par The <code style="background-color:whitesmoke;">-d</code> option must be specified
+
+before
+\par subsetting options (if not using the shorthand method).
+
+The <code style="background-color:whitesmoke;">-A 0</code> option suppresses the printing of attributes.
+
+The <code style="background-color:whitesmoke;">-w 0</code> option sets the number of columns of output to the maximum allowed value (65535).
+This ensures that there are enough columns specified for displaying the data.
+
+Either command displays:
+\code
+ HDF5 "OMI-Aura.he5" {
+ DATASET "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" {
+ DATATYPE H5T_IEEE_F32LE
+ DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
+ SUBSET {
+ START ( 0, 0 );
+ STRIDE ( 1, 1 );
+ COUNT ( 15, 10 );
+ BLOCK ( 1, 1 );
+ DATA {
+ (0,0): 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403,
+ (1,0): 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071,
+ (2,0): 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867,
+ (3,0): 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632,
+ (4,0): 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429,
+ (5,0): 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225,
+ (6,0): 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021,
+ (7,0): 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715,
+ (8,0): 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511,
+ (9,0): 77.658, 77.658, 77.658, 77.307, 77.307, 77.307, 77.307, 77.307, 77.307, 77.307,
+ (10,0): 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.102, 77.102,
+ (11,0): 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 77.102, 77.102,
+ (12,0): 76.34, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413,
+ (13,0): 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 77.195,
+ (14,0): 78.005, 78.005, 78.005, 78.005, 78.005, 78.005, 76.991, 76.991, 76.991, 76.991
+ }
+ }
+ }
+ }
+\endcode
+
+What if we wish to read three rows of three elements at a time (-c "3,3"), where each element
+is a 2 x 3 block (-k "2,3") and we wish to begin reading from the second row (-s "1,0")?
+
+You can do that with the following command:
+\code
+ h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle"
+ -s "1,0" -S "2,3" -c "3,3" -k "2,3" -w 0 OMI-Aura.he5
+\endcode
+
+In this case, the stride must be specified as 2 by 3 (or larger) to accommodate the reading of 2 by 3 blocks.
+If it is smaller, the command will fail with the error,
+\code
+h5dump error: wrong subset selection; blocks overlap.
+\endcode
+
+The output of the above command is shown below:
+\code
+ HDF5 "OMI-Aura.he5" {
+ DATASET "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" {
+ DATATYPE H5T_IEEE_F32LE
+ DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }
+ SUBSET {
+ START ( 1, 0 );
+ STRIDE ( 2, 3 );
+ COUNT ( 3, 3 );
+ BLOCK ( 2, 3 );
+ DATA {
+ (1,0): 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071,
+ (2,0): 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867,
+ (3,0): 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632,
+ (4,0): 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429,
+ (5,0): 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225,
+ (6,0): 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021
+ }
+ }
+ }
+ }
+\endcode
+
+\section secViewToolsViewDtypes Datatypes
+
+\subsection subsecViewToolsViewDtypes_h5dump h5dump
+The following datatypes are discussed, using the output of <code style="background-color:whitesmoke;">h5dump</code> with HDF5 files from the
+<a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page:
+<ul>
+<li>@ref subsubsecViewToolsViewDtypes_array</li>
+<li>@ref subsubsecViewToolsViewDtypes_objref</li>
+<li>@ref subsubsecViewToolsViewDtypes_regref</li>
+<li>@ref subsubsecViewToolsViewDtypes_string</li>
+</ul>
+
+\subsubsection subsubsecViewToolsViewDtypes_array Array
+Users have been confused by the difference between an Array datatype (#H5T_ARRAY) and a dataset that
+(has a dataspace that) is an array.
+
+Typically, these users want a dataset that has a simple datatype (like integer or float) that is an
+array, like the following dataset <code style="background-color:whitesmoke;">/DS1</code>. It has a datatype of #H5T_STD_I32LE (32-bit Little-Endian Integer)
+and is a 4 by 7 array:
+\code
+$ h5dump h5ex_d_rdwr.h5
+HDF5 "h5ex_d_rdwr.h5" {
+GROUP "/" {
+ DATASET "DS1" {
+ DATATYPE H5T_STD_I32LE
+ DATASPACE SIMPLE { ( 4, 7 ) / ( 4, 7 ) }
+ DATA {
+ (0,0): 0, -1, -2, -3, -4, -5, -6,
+ (1,0): 0, 0, 0, 0, 0, 0, 0,
+ (2,0): 0, 1, 2, 3, 4, 5, 6,
+ (3,0): 0, 2, 4, 6, 8, 10, 12
+ }
+ }
+}
+}
+\endcode
+
+Contrast that with the following dataset that has both an Array datatype and is an array:
+\code
+$ h5dump h5ex_t_array.h5
+HDF5 "h5ex_t_array.h5" {
+GROUP "/" {
+ DATASET "DS1" {
+ DATATYPE H5T_ARRAY { [3][5] H5T_STD_I64LE }
+ DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
+ DATA {
+ (0): [ 0, 0, 0, 0, 0,
+ 0, -1, -2, -3, -4,
+ 0, -2, -4, -6, -8 ],
+ (1): [ 0, 1, 2, 3, 4,
+ 1, 1, 1, 1, 1,
+ 2, 1, 0, -1, -2 ],
+ (2): [ 0, 2, 4, 6, 8,
+ 2, 3, 4, 5, 6,
+ 4, 4, 4, 4, 4 ],
+ (3): [ 0, 3, 6, 9, 12,
+ 3, 5, 7, 9, 11,
+ 6, 7, 8, 9, 10 ]
+ }
+ }
+}
+}
+\endcode
+
+In this file, dataset <code style="background-color:whitesmoke;">/DS1</code> has a datatype of
+\code
+H5T_ARRAY { [3][5] H5T_STD_I64LE }
+\endcode
+and it also has a dataspace of
+\code
+SIMPLE { ( 4 ) / ( 4 ) }
+\endcode
+In other words, it is an array of four elements, in which each element is a 3 by 5 array of #H5T_STD_I64LE.
+
+This dataset is much more complex. Also note that subsetting cannot be done on Array datatypes.
+
+See this <a href="https://portal.hdfgroup.org/display/knowledge/H5T_ARRAY+Datatype">FAQ</a> for more information on the Array datatype.
+
+\subsubsection subsubsecViewToolsViewDtypes_objref Object Reference
+An Object Reference is a reference to an entire object (dataset, group, or named datatype).
+A dataset with an Object Reference datatype consists of one or more Object References.
+An Object Reference dataset can be used as an index to an HDF5 file.
+
+The <code style="background-color:whitesmoke;">/DS1</code> dataset in the following file (<code style="background-color:whitesmoke;">h5ex_t_objref.h5</code>) is an Object Reference dataset.
+It contains two references, one to group <code style="background-color:whitesmoke;">/G1</code> and the other to dataset <code style="background-color:whitesmoke;">/DS2</code>:
+\code
+$ h5dump h5ex_t_objref.h5
+HDF5 "h5ex_t_objref.h5" {
+GROUP "/" {
+ DATASET "DS1" {
+ DATATYPE H5T_REFERENCE { H5T_STD_REF_OBJECT }
+ DATASPACE SIMPLE { ( 2 ) / ( 2 ) }
+ DATA {
+ (0): GROUP 1400 /G1 , DATASET 800 /DS2
+ }
+ }
+ DATASET "DS2" {
+ DATATYPE H5T_STD_I32LE
+ DATASPACE NULL
+ DATA {
+ }
+ }
+ GROUP "G1" {
+ }
+}
+}
+\endcode
+
+\subsubsection subsubsecViewToolsViewDtypes_regref Region Reference
+A Region Reference is a reference to a selection within a dataset. A selection can be either
+individual elements or a hyperslab. In <code style="background-color:whitesmoke;">h5dump</code> you will see the name of the dataset along with
+the elements or slab that is selected. A dataset with a Region Reference datatype consists of
+one or more Region References.
+
+An example of a Region Reference dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.h5</code>) can be found on the
+<a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page,
+under Datatypes. If you examine this dataset with <code style="background-color:whitesmoke;">h5dump</code> you will see that <code style="background-color:whitesmoke;">/DS1</code> is a
+Region Reference dataset as indicated by its datatype, highlighted in bold below:
+\code
+$ h5dump h5ex_t_regref.h5
+HDF5 "h5ex_t_regref.h5" {
+GROUP "/" {
+ DATASET "DS1" {
+ DATATYPE H5T_REFERENCE { H5T_STD_REF_DSETREG }
+ DATASPACE SIMPLE { ( 2 ) / ( 2 ) }
+ DATA {
+ DATASET /DS2 {(0,1), (2,11), (1,0), (2,4)},
+ DATASET /DS2 {(0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)}
+ }
+ }
+ DATASET "DS2" {
+ DATATYPE H5T_STD_I8LE
+ DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) }
+ DATA {
+ (0,0): 84, 104, 101, 32, 113, 117, 105, 99, 107, 32, 98, 114, 111, 119,
+ (0,14): 110, 0,
+ (1,0): 102, 111, 120, 32, 106, 117, 109, 112, 115, 32, 111, 118, 101,
+ (1,13): 114, 32, 0,
+ (2,0): 116, 104, 101, 32, 53, 32, 108, 97, 122, 121, 32, 100, 111, 103,
+ (2,14): 115, 0
+ }
+ }
+}
+}
+\endcode
+
+It contains two Region References:
+\li A selection of four individual elements in dataset <code style="background-color:whitesmoke;">/DS2 : (0,1), (2,11), (1,0), (2,4)</code>
+See the #H5Sselect_elements API in the \ref UG for information on selecting individual elements.
+\li A selection of these blocks in dataset <code style="background-color:whitesmoke;">/DS2 : (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)</code>
+See the #H5Sselect_hyperslab API in the \ref UG for how to do hyperslab selection.
+
+
+If you look at the code that creates the dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.c</code>) you will see that the
+first reference is created with these calls:
+\code
+ status = H5Sselect_elements (space, H5S_SELECT_SET, 4, coords[0]);
+ status = H5Rcreate (&wdata[0], file, DATASET2, H5R_DATASET_REGION, space);
+\endcode
+
+where the buffer containing the coordinates to select is:
+\code
+ coords[4][2] = { {0, 1},
+ {2, 11},
+ {1, 0},
+ {2, 4} },
+\endcode
+
+The second reference is created by calling,
+\code
+ status = H5Sselect_hyperslab (space, H5S_SELECT_SET, start, stride, count, block);
+ status = H5Rcreate (&wdata[1], file, DATASET2, H5R_DATASET_REGION, space);
+\endcode
+where start, stride, count, and block have these values:
+\code
+ start[2] = {0, 0},
+ stride[2] = {2, 11},
+ count[2] = {2, 2},
+ block[2] = {1, 3};
+\endcode
+
+These start, stride, count, and block values will select the elements shown in bold in the dataset:
+\code
+84 104 101 32 113 117 105 99 107 32 98 114 111 119 110 0
+102 111 120 32 106 117 109 112 115 32 111 118 101 114 32 0
+116 104 101 32 53 32 108 97 122 121 32 100 111 103 115 0
+\endcode
+
+If you use <code style="background-color:whitesmoke;">h5dump</code> to select a subset of dataset
+<code style="background-color:whitesmoke;">/DS2</code> with these start, stride, count, and block values, you will see that the same elements are selected:
+\code
+$ h5dump -d "/DS2" -s "0,0" -S "2,11" -c "2,2" -k "1,3" h5ex_t_regref.h5
+HDF5 "h5ex_t_regref.h5" {
+DATASET "/DS2" {
+ DATATYPE H5T_STD_I8LE
+ DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) }
+ SUBSET {
+ START ( 0, 0 );
+ STRIDE ( 2, 11 );
+ COUNT ( 2, 2 );
+ BLOCK ( 1, 3 );
+ DATA {
+ (0,0): 84, 104, 101, 114, 111, 119,
+ (2,0): 116, 104, 101, 100, 111, 103
+ }
+ }
+}
+}
+\endcode
+
+For more information on selections, see the tutorial topic on
+@ref LBDsetSubRW. Also see the
+\ref secViewToolsViewSub tutorial topic on using <code style="background-color:whitesmoke;">h5dump</code> to view a subset.
+
+\subsubsection subsubsecViewToolsViewDtypes_string String
+There are two types of string data, fixed length strings and variable length strings.
+
+Below is the <code style="background-color:whitesmoke;">h5dump</code> output for two files that have the same strings written to them. In one file,
+the strings are fixed in length, and in the other, the strings have different sizes (and are variable in size).
+
+<em>Dataset of Fixed Length Strings</em>
+\code
+HDF5 "h5ex_t_string.h5" {
+GROUP "/" {
+ DATASET "DS1" {
+ DATATYPE H5T_STRING {
+ STRSIZE 7;
+ STRPAD H5T_STR_SPACEPAD;
+ CSET H5T_CSET_ASCII;
+ CTYPE H5T_C_S1;
+ }
+ DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
+ DATA {
+ (0): "Parting", "is such", "sweet ", "sorrow."
+ }
+ }
+}
+}
+\endcode
+
+<em>Dataset of Variable Length Strings</em>
+\code
+HDF5 "h5ex_t_vlstring.h5" {
+GROUP "/" {
+ DATASET "DS1" {
+ DATATYPE H5T_STRING {
+ STRSIZE H5T_VARIABLE;
+ STRPAD H5T_STR_SPACEPAD;
+ CSET H5T_CSET_ASCII;
+ CTYPE H5T_C_S1;
+ }
+ DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
+ DATA {
+ (0): "Parting", "is such", "sweet", "sorrow."
+ }
+ }
+}
+}
+\endcode
+
+You might wonder which to use. Some comments to consider are included below.
+\li In general, a variable length string dataset is more complex than a fixed length string. If you don't
+specifically need a variable length type, then just use the fixed length string.
+\li A variable length dataset consists of pointers to heaps in different locations in the file. For this
+reason, a variable length dataset cannot be compressed. (Basically, the pointers get compressed and
+not the actual data!) If compression is needed, then do not use variable length types.
+\li If you need to create an array of of different length strings, you can either use fixed length strings
+along with compression, or use a variable length string.
+
+<hr>
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand
+
+*/
generated by cgit v0.12 at 2024-11-20 05:02:04 (GMT)