summaryrefslogtreecommitdiffstats
path: root/doxygen/dox/ViewTools2.dox
diff options
context:
space:
mode:
Diffstat (limited to 'doxygen/dox/ViewTools2.dox')
-rw-r--r--doxygen/dox/ViewTools2.dox786
1 files changed, 786 insertions, 0 deletions
diff --git a/doxygen/dox/ViewTools2.dox b/doxygen/dox/ViewTools2.dox
new file mode 100644
index 0000000..4d8788a
--- /dev/null
+++ b/doxygen/dox/ViewTools2.dox
@@ -0,0 +1,786 @@
+/** @page ViewToolsEdit Command-line Tools For Editing HDF5 Files
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand
+<hr>
+
+\section secViewToolsEditTOC Contents
+<ul>
+<li>\ref secViewToolsEditRemove</li>
+<li>\ref secViewToolsEditChange</li>
+<li>\ref secViewToolsEditApply</li>
+<li>\ref secViewToolsEditCopy</li>
+<li>\ref secViewToolsEditAdd</li>
+</ul>
+
+\section secViewToolsEditRemove Remove Inaccessible Objects and Unused Space in a File
+HDF5 files may accumulate unused space when they are read and rewritten to or if objects are deleted within
+them. With many edits and deletions this unused space can add up to a sizable amount.
+
+The <code style="background-color:whitesmoke;">h5repack</code> tool can be used to remove unused space in an HDF5
+file. If no options other than the input and output HDF5 files are specified on the
+<code style="background-color:whitesmoke;">h5repack</code> command line, it will write the file to the new
+file, getting rid of the unused space:
+\code
+h5repack <input file> <output file>
+\endcode
+
+\section secViewToolsEditChange Change a Dataset's Storage Layout
+The <code style="background-color:whitesmoke;">h5repack</code> utility can be used to change a dataset's storage
+layout. By default, the storage layout of a dataset is defined at creation time and it cannot be changed.
+However, with h5repack you can write an HDF5 file to a new file and change the layout for objects in the new file.
+
+The <code style="background-color:whitesmoke;">-l</code> option in <code style="background-color:whitesmoke;">h5repack</code>
+is used to change the layout for an object. The string following the <code style="background-color:whitesmoke;">-l</code>
+option defines the layout type and parameters for specified objects (or all objects):
+\code
+h5repack -l [list of objects:]<layout type>=<layout parameters> <input file> <output file>
+\endcode
+
+If no object is specified, then everything in the input file will be written to the output file with the specified
+layout type and parameters. If objects are specified then everything in the input file will be written to the
+output file as is, except for those specified objects. They will be written to the output file with the given
+layout type and parameters.
+
+Following is a description of the dataset layouts and the <code style="background-color:whitesmoke;">h5repack</code>
+options to use to change a dataset:
+<table>
+<tr>
+<th>Storage Layout</th><th>h5repack Option</th><th>Description</th>
+</tr>
+<tr>
+<td>Contiguous
+</td>
+<td>CONTI
+</td>
+<td>Data is stored physically together
+</td>
+</tr>
+<tr>
+<td>Chunked
+</td>
+<td>CHUNK=DIM[xDIM...xDIM]
+</td>
+<td>Data is stored in DIM[xDIM...xDIM] chunks
+</td>
+</tr>
+<tr>
+<td>Compact
+</td>
+<td>COMPA
+</td>
+<td>Data is stored in the header of the object (less I/O)
+</td>
+</tr>
+</table>
+
+If you type <code style="background-color:whitesmoke;">h5repack -h</code> on the command line, you will see
+a detailed usage statement with examples of modifying the layout.
+
+In the following example, the dataset <code style="background-color:whitesmoke;">/dset</code> in the file
+dset.h5 is contiguous, as shown by the <code style="background-color:whitesmoke;">h5dump -pH</code> command.
+The <code style="background-color:whitesmoke;">h5repack</code> utility writes dset.h5 to a new file, dsetrpk.h5,
+where the dataset <code style="background-color:whitesmoke;">dset</code> is chunked. This can be seen by examining
+the resulting dsetrpk.h5 file with <code style="background-color:whitesmoke;">h5dump</code>, as shown:
+\code
+$ h5dump -pH dset.h5
+HDF5 "dset.h5" {
+GROUP "/" {
+ DATASET "dset" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
+ STORAGE_LAYOUT {
+ CONTIGUOUS
+ SIZE 96
+ OFFSET 1400
+ }
+ FILTERS {
+ NONE
+ }
+ FILLVALUE {
+ FILL_TIME H5D_FILL_TIME_IFSET
+ VALUE 0
+ }
+ ALLOCATION_TIME {
+ H5D_ALLOC_TIME_LATE
+ }
+ }
+}
+}
+
+$ h5repack -l dset:CHUNK=4x6 dset.h5 dsetrpk.h5
+
+$ h5dump -pH dsetrpk.h5
+HDF5 "dsetrpk.h5" {
+GROUP "/" {
+ DATASET "dset" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
+ STORAGE_LAYOUT {
+ CHUNKED ( 4, 6 )
+ SIZE 96
+ }
+ FILTERS {
+ NONE
+ }
+ FILLVALUE {
+ FILL_TIME H5D_FILL_TIME_IFSET
+ VALUE 0
+ }
+ ALLOCATION_TIME {
+ H5D_ALLOC_TIME_INCR
+ }
+ }
+}
+}
+\endcode
+
+There can be many reasons that the storage layout needs to be changed for a dataset. For example,
+there may be a performance issue with a dataset due to a small chunk size.
+
+\section secViewToolsEditApply Apply Compression Filter to a Dataset
+The <code style="background-color:whitesmoke;">h5repack</code> utility can be used to compress or
+remove compression from a dataset in a file. By default, compression cannot be added to or removed
+from a dataset once it has been created. However, with <code style="background-color:whitesmoke;">h5repack</code>
+you can write a file to a new file and specify a compression filter to apply to a dataset or datasets in the new file.
+
+To apply a filter to an object in an HDF5 file, specify the <code style="background-color:whitesmoke;">-f</code> option,
+where the string following the <code style="background-color:whitesmoke;">-f</code> option defines the filter and
+its parameters (if there are any) to apply to a given object or objects:
+\code
+h5repack -f [list of objects:]<name of filter>=<filter parameters> <input file> <output file>
+\endcode
+
+If no objects are specified then everything in the input file will be written to the output file with
+the filter and parameters specified. If objects are specified, then everything in the input file will
+be written to the output file as is, except for the specified objects. They will be written to the
+output file with the filter and parameters specified.
+
+If you type <code style="background-color:whitesmoke;">h5repack --help</code> on the command line,
+you will see a detailed usage statement with examples of modifying a filter. There are actually
+numerous filters that you can apply to a dataset:
+<table>
+<tr>
+<th>Filter<th></th>Options</th>
+</tr>
+<tr>
+<td>GZIP compression (levels 1-9)
+<td>GZIP=&lt;deflation level&gt;
+</td>
+</tr>
+<tr>
+<td>SZIP compression
+<td>SZIP=<pixels per block,coding>
+</td>
+</tr>
+<tr>
+<td>Shuffle filter
+<td>SHUF
+</td>
+</tr>
+<tr>
+<td>Checksum filter
+<td>FLET
+</td>
+</tr>
+<tr>
+<td>NBIT compression
+<td>NBIT
+</td>
+</tr>
+<tr>
+<td>HDF5 Scale/Offset filter
+<td>SOFF=<scale_factor,scale_type>
+</td>
+</tr>
+<tr>
+<td>User defined filter
+<td>UD=<filter_number,cd_value_count,value_1[,value_2,...,value_N]>
+</td>
+</tr>
+<tr>
+<td>Remove ALL filters
+</td>
+<td>NONE
+</td>
+</tr>
+</table>
+
+Be aware that a dataset must be chunked to apply compression to it. If the dataset is not already chunked,
+then <code style="background-color:whitesmoke;">h5repack</code> will apply chunking to it. Both chunking
+and compression cannot be applied to a dataset at the same time with <code style="background-color:whitesmoke;">h5repack</code>.
+
+In the following example,
+\li <em>h5dump</em> lists the properties for the objects in <em>dset.h5</em>. Note that the dataset <em>dset</em> is contiguous.
+\li <em>h5repack</em> writes dset.h5 into a new file <em>dsetrpk.h5</em>, applying GZIP Level 5 compression to the dataset <em>/dset</em> in dsetrpk.h5.
+\li <em>h5dump</em> lists the properties for the new <em>dsetrpk.h5</em> file. Note that <em>/dset</em> is both compressed and chunked.
+
+<em>Example</em>
+\code
+$ h5dump -pH dset.h5
+HDF5 "dset.h5" {
+GROUP "/" {
+ DATASET "dset" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 12, 18 ) / ( 12, 18 ) }
+ STORAGE_LAYOUT {
+ CONTIGUOUS
+ SIZE 864
+ OFFSET 1400
+ }
+ FILTERS {
+ NONE
+ }
+ FILLVALUE {
+ FILL_TIME H5D_FILL_TIME_IFSET
+ VALUE 0
+ }
+ ALLOCATION_TIME {
+ H5D_ALLOC_TIME_LATE
+ }
+ }
+}
+}
+
+$ h5repack -f dset:GZIP=5 dset.h5 dsetrpk.h5
+
+$ h5dump -pH dsetrpk.h5
+HDF5 "dsetrpk.h5" {
+GROUP "/" {
+ DATASET "dset" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 12, 18 ) / ( 12, 18 ) }
+ STORAGE_LAYOUT {
+ CHUNKED ( 12, 18 )
+ SIZE 160 (5.400:1 COMPRESSION)
+ }
+ FILTERS {
+ COMPRESSION DEFLATE { LEVEL 5 }
+ }
+ FILLVALUE {
+ FILL_TIME H5D_FILL_TIME_IFSET
+ VALUE 0
+ }
+ ALLOCATION_TIME {
+ H5D_ALLOC_TIME_INCR
+ }
+ }
+}
+}
+\endcode
+
+\section secViewToolsEditCopy Copy Objects to Another File
+The <code style="background-color:whitesmoke;">h5copy</code> utility can be used to copy an object or
+objects from one HDF5 file to another or to a different location in the same file. It uses the
+#H5Ocopy and #H5Lcopy APIs in HDF5.
+
+Following are some of the options that can be used with <code style="background-color:whitesmoke;">h5copy</code>.
+<table>
+<tr>
+<th>h5copy Options</th><th>Description</th>
+</tr>
+<tr>
+<td>-i, --input
+</td>
+<td>Input file name
+</td>
+</tr>
+<tr>
+<td>-o, --output
+</td>
+<td>Output file name
+</td>
+</tr>
+<tr>
+<td>-s, --source
+</td>
+<td>Source object name
+</td>
+</tr>
+<tr>
+<td>-d, --destination
+</td>
+<td>Destination object name
+</td>
+</tr>
+<tr>
+<td>-p, --parents
+</td>
+<td>Make parent groups as needed
+</td>
+</tr>
+<tr>
+<td>-v, --verbose
+</td>
+<td>Verbose mode
+</td>
+</tr>
+<tr>
+<td>-f, --flag
+</td>
+<td>Flag type
+</td>
+</tr>
+</table>
+
+For a complete list of options and information on using <code style="background-color:whitesmoke;">h5copy</code>, type:
+\code
+h5copy --help
+\endcode
+
+In the example below, the dataset <code style="background-color:whitesmoke;">/MyGroup/Group_A/dset2</code>
+in <code style="background-color:whitesmoke;">groups.h5</code> gets copied to the root
+("<code style="background-color:whitesmoke;">/</code>") group of a new file,
+<code style="background-color:whitesmoke;">newgroup.h5</code>, with the name
+<code style="background-color:whitesmoke;">dset3</code>:
+\code
+$h5dump -H groups.h5
+HDF5 "groups.h5" {
+GROUP "/" {
+ GROUP "MyGroup" {
+ GROUP "Group_A" {
+ DATASET "dset2" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 2, 10 ) / ( 2, 10 ) }
+ }
+ }
+ GROUP "Group_B" {
+ }
+ DATASET "dset1" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) }
+ }
+ }
+}
+}
+
+$ h5copy -i groups.h5 -o newgroup.h5 -s /MyGroup/Group_A/dset2 -d /dset3
+
+$ h5dump -H newgroup.h5
+HDF5 "newgroup.h5" {
+GROUP "/" {
+ DATASET "dset3" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 2, 10 ) / ( 2, 10 ) }
+ }
+}
+}
+\endcode
+
+There are also <code style="background-color:whitesmoke;">h5copy</code> flags that can be specified
+with the <code style="background-color:whitesmoke;">-f</code> option. In the example below, the
+<code style="background-color:whitesmoke;">-f shallow</code> option specifies to copy only the
+immediate members of the group <code style="background-color:whitesmoke;">/MyGroup</code> from
+the <code style="background-color:whitesmoke;">groups.h5</code> file mentioned above to a new
+file <code style="background-color:whitesmoke;">mygrouponly.h5</code>:
+\code
+h5copy -v -i groups.h5 -o mygrouponly.h5 -s /MyGroup -d /MyGroup -f shallow
+\endcode
+
+The output of the above command is shown below. The verbose option <code style="background-color:whitesmoke;">-v</code>
+describes the action that was taken, as shown in the highlighted text.
+\code
+Copying file <groups.h5> and object </MyGroup> to file <mygrouponly.h5> and object </MyGroup>
+Using shallow flag
+
+$ h5dump -H mygrouponly.h5
+HDF5 "mygrouponly.h5" {
+GROUP "/" {
+ GROUP "MyGroup" {
+ GROUP "Group_A" {
+ }
+ GROUP "Group_B" {
+ }
+ DATASET "dset1" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) }
+ }
+ }
+}
+}
+\endcode
+
+\section secViewToolsEditAdd Add or Remove User Block from File
+The user block is a space in an HDF5 file that is not interpreted by the HDF5 library. It is a property
+list that can be added when creating a file. See the #H5Pset_userblock API in the \ref RM for more
+information regarding this property.
+
+Once created in a file, the user block cannot be removed. However, you can use the
+<code style="background-color:whitesmoke;">h5jam</code> and <code style="background-color:whitesmoke;">h5unjam</code>
+utilities to add or remove a user block from a file into a new file.
+
+These two utilities work similarly, except that <code style="background-color:whitesmoke;">h5jam</code>
+adds a user block to a file and <code style="background-color:whitesmoke;">h5unjam</code> removes the user
+block. You can also overwrite or delete a user block in a file.
+
+Specify the <code style="background-color:whitesmoke;">-h</code> option to see a complete list of options
+that can be used with <code style="background-color:whitesmoke;">h5jam</code> and
+<code style="background-color:whitesmoke;">h5unjam</code>. For example:
+\code
+ h5jam -h
+ h5unjam -h
+\endcode
+
+Below are the basic options for adding or removing a user block with <code style="background-color:whitesmoke;">h5jam</code>
+and <code style="background-color:whitesmoke;">h5unjam</code>:
+
+<table>
+<tr>
+<th>h5copy Options</th><th>Description</th>
+</tr>
+<tr>
+<td>-i
+</td>
+<td>Input File
+</td>
+</tr>
+<tr>
+<td>-o
+</td>
+<td>Output File
+</td>
+</tr>
+<tr>
+<td>-u
+</td>
+<td>File to add or remove from user block
+</td>
+</tr>
+</table>
+
+Let's say you wanted to add the program that creates an HDF5 file to its user block. As an example, you
+can take the <code style="background-color:whitesmoke;">h5_crtgrpar.c</code> program from the
+\ref LBExamples
+and add it to the file it creates, <code style="background-color:whitesmoke;">groups.h5</code>. This can
+be done with <code style="background-color:whitesmoke;">h5jam</code>, as follows:
+\code
+h5jam -i groups.h5 -u h5_crtgrpar.c -o groupsub.h5
+\endcode
+
+You can actually view the file with more <code style="background-color:whitesmoke;">groupsub.h5</code>
+to see that the <code style="background-color:whitesmoke;">h5_crtgrpar.c</code> file is indeed included.
+
+To remove the user block that was just added, type:
+\code
+h5unjam -i groupsub.h5 -u h5_crtgrparNEW.c -o groups-noub.h5
+\endcode
+
+This writes the user block in the file <code style="background-color:whitesmoke;">groupsub.h5</code>
+into <code style="background-color:whitesmoke;">h5_crtgrparNEW.c</code>. The new HDF5 file,
+<code style="background-color:whitesmoke;">groups-noub.h5</code>, will not contain a user block.
+
+<hr>
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand
+
+*/
+
+/** @page ViewToolsConvert Command-line Tools For Converting HDF5 Files
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand
+<hr>
+
+\section secViewToolsConvertTOC Contents
+<ul>
+<li>\ref secViewToolsConvertASCII</li>
+<li>\ref secViewToolsConvertBinary</li>
+<li>\ref secViewToolsConvertExport</li>
+</ul>
+
+\section secViewToolsConvertASCII Output HDF5 Dataset into an ASCII File (to Import into Excel and Other Applications)
+The <code style="background-color:whitesmoke;">h5dump</code> utility can be used to convert an HDF5 dataset
+into an ASCII file, which can then be imported into Excel and other applications. The following options are used:
+<table>
+<tr>
+<th>Options</th><th>Description</th>
+</tr>
+<tr>
+<td> -d D, --dataset=D
+</td>
+<td>Display dataset D
+</td>
+</tr>
+<tr>
+<td> -o F, --output=F
+</td>
+<td>Output raw data into file F
+</td>
+</tr>
+<tr>
+<td> -y, --noindex
+</td>
+<td>Suppress printing of array indices with the data
+</td>
+</tr>
+<tr>
+<td> -w N, --width=N
+</td>
+<td>Set N number of columns of output. A value of 0
+sets the number to 65535 (the maximum)
+</td>
+</tr>
+</table>
+
+As an example, <code style="background-color:whitesmoke;">h5_crtdat.c</code> from the \ref LBDsetCreate
+HDF5 Tutorial topic, creates the file <code style="background-color:whitesmoke;">dset.h5</code> with
+a dataset <code style="background-color:whitesmoke;">/dset</code> that is a 4 x 6 integer array. The
+following is displayed when viewing <code style="background-color:whitesmoke;">dset.h5</code> with
+<code style="background-color:whitesmoke;">h5dump</code>:
+\code
+$ h5dump dset.h5
+HDF5 "dset.h5" {
+GROUP "/" {
+ DATASET "dset" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
+ DATA {
+ (0,0): 1, 2, 3, 4, 5, 6,
+ (1,0): 7, 8, 9, 10, 11, 12,
+ (2,0): 13, 14, 15, 16, 17, 18,
+ (3,0): 19, 20, 21, 22, 23, 24
+ }
+ }
+}
+}
+\endcode
+
+The following command will output the values of the <code style="background-color:whitesmoke;">/dset</code>
+dataset to the ASCII file <code style="background-color:whitesmoke;">dset.asci</code>:
+\code
+h5dump -d /dset -o dset.asci -y -w 50 dset.h5
+\endcode
+
+In particular, note that:
+\li The default behavior of <code style="background-color:whitesmoke;">h5dump</code> is to print indices,
+and the <code style="background-color:whitesmoke;">-y</code> option suppresses this.
+\li The <code style="background-color:whitesmoke;">-w 50</code> option tells
+<code style="background-color:whitesmoke;">h5dump</code> to allow 50 columns for outputting the data. The
+value specified must be large enough to accommodate the dimension size of the dataset multiplied by the
+number of positions and spaces needed to print each value. If the value is not large enough, the output
+will wrap to the next line, and the data will not display as expected in Excel or other applications. To
+ensure that the output does not wrap to the next line, you can also specify 0 (zero) for the
+<code style="background-color:whitesmoke;">-w</code> option.
+
+In addition to creating the ASCII file <code style="background-color:whitesmoke;">dset.asci</code>, the
+above command outputs the metadata of the specified dataset:
+\code
+HDF5 "dset.h5" {
+DATASET "/dset" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
+ DATA {
+ }
+}
+}
+\endcode
+
+The <code style="background-color:whitesmoke;">dset.asci</code> file will contain the values for the dataset:
+\code
+ 1, 2, 3, 4, 5, 6,
+ 7, 8, 9, 10, 11, 12,
+ 13, 14, 15, 16, 17, 18,
+ 19, 20, 21, 22, 23, 24
+\endcode
+
+\section secViewToolsConvertBinary Output HDF5 Dataset into Binary File
+The <code style="background-color:whitesmoke;">h5dump</code> utility can be used to convert an
+HDF5 dataset to a binary file with the following options:
+<table>
+<tr>
+<th>Options</th><th>Description</th>
+</tr>
+<tr>
+<td>-d D, --dataset=D
+</td>
+<td>Display dataset D
+</td>
+</tr>
+<tr>
+<td>-o F, --output=F
+</td>
+<td>Output raw data into file F
+</td>
+</tr>
+<tr>
+<td>-b B, --binary=B
+</td>
+<td>Binary file output of form B.
+Valid values are: LE, BE, NATIVE, FILE
+</td>
+</tr>
+</table>
+
+As an example, <code style="background-color:whitesmoke;">h5_crtdat.c</code> from the
+\ref LBDsetCreate HDF5 Tutorial topic, creates the file dset.h5 with a dataset
+<code style="background-color:whitesmoke;">/dset</code> that is a 4 x 6 integer array. The
+following is displayed when viewing <code style="background-color:whitesmoke;">dset.h5</code>
+with <code style="background-color:whitesmoke;">h5dump</code>:
+\code
+$ h5dump -d /dset/ dset.h5
+HDF5 "dset.h5" {
+DATASET "/dset/" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
+ DATA {
+ (0,0): 1, 2, 3, 4, 5, 6,
+ (1,0): 7, 8, 9, 10, 11, 12,
+ (2,0): 13, 14, 15, 16, 17, 18,
+ (3,0): 19, 20, 21, 22, 23, 24
+ }
+}
+}
+\endcode
+
+As specified by the <code style="background-color:whitesmoke;">-d</code> and
+<code style="background-color:whitesmoke;">-o</code> options, the following
+<code style="background-color:whitesmoke;">h5dump</code> command will output the values of the dataset
+<code style="background-color:whitesmoke;">/dset </code>to a file called
+<code style="background-color:whitesmoke;">dset.bin</code>. The <code style="background-color:whitesmoke;">-b</code>
+option specifies that the output will be binary in Little Endian format (LE).
+
+\code
+h5dump -d /dset -b LE -o dset.bin dset.h5
+\endcode
+
+This command outputs the metadata for the dataset, as well as creating the binary file
+<code style="background-color:whitesmoke;">dset.bin</code>:
+\code
+HDF5 "dset.h5" {
+DATASET "/dset" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
+ DATA {
+ }
+}
+}
+\endcode
+
+If you look at the resulting <code style="background-color:whitesmoke;">dset.bin</code> file with
+a binary editor, you will see that it contains the dataset's values. For example (on Linux) you will see:
+\code
+$ od -t d dset.bin
+0000000 1 2 3 4
+0000020 5 6 7 8
+0000040 9 10 11 12
+0000060 13 14 15 16
+0000100 17 18 19 20
+0000120 21 22 23 24
+0000140
+\endcode
+
+\section secViewToolsConvertExport Export from h5dump and Import into HDF5
+The <code style="background-color:whitesmoke;">h5import</code> utility can use the output of
+<code style="background-color:whitesmoke;">h5dump</code> as input to create a dataset or file.
+
+The <code style="background-color:whitesmoke;">h5dump</code> utility must first create two files:
+\li A DDL file, which will be used as an <code style="background-color:whitesmoke;">h5import</code> configuration file
+\li A raw data file containing the data to be imported
+
+The DDL file must be generated with the <code style="background-color:whitesmoke;">h5dump -p</code> option, to generate properties.
+
+The raw data file that can be imported into HDF5 using this method may contain either numeric or string data with the following restrictions:
+\li Numeric data requires the use of the <code style="background-color:whitesmoke;">h5dump -b</code> option to produce a binary data file.
+\li String data must be written with the <code style="background-color:whitesmoke;">h5dump -y</code> and
+<code style="background-color:whitesmoke;">--width=1</code> options, generating a single column of strings without indices.
+
+Two examples follow: the first imports a dataset with a numeric datatype. Note that numeric data requires
+the use of the <code style="background-color:whitesmoke;">h5dump -b</code> option to produce a binary data
+file. The example program (<code style="background-color:whitesmoke;">h5_crtdat.c</code>) that creates this
+file is included with the \ref IntroHDF5 tutorial and can be obtained from the \ref LBExamples page:
+\code
+h5dump -p -d "/dset" --ddl=dsetbin.dmp -o dset.bin -b dset.h5
+h5import dset.bin -c dsetbin.dmp -o new-dset.h5
+\endcode
+
+The output before and after running these commands is shown below:
+\code
+$ h5dump dset.h5
+HDF5 "dset.h5" {
+GROUP "/" {
+ DATASET "dset" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
+ DATA {
+ (0,0): 1, 2, 3, 4, 5, 6,
+ (1,0): 7, 8, 9, 10, 11, 12,
+ (2,0): 13, 14, 15, 16, 17, 18,
+ (3,0): 19, 20, 21, 22, 23, 24
+ }
+ }
+}
+}
+$ h5dump -p -d "/dset" --ddl=dsetbin.dmp -o dset.bin -b dset.h5
+
+$ h5import dset.bin -c dsetbin.dmp -o new-dset.h5
+
+$ h5dump new-dset.h5
+HDF5 "new-dset.h5" {
+GROUP "/" {
+ DATASET "dset" {
+ DATATYPE H5T_STD_I32BE
+ DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
+ DATA {
+ (0,0): 1, 2, 3, 4, 5, 6,
+ (1,0): 7, 8, 9, 10, 11, 12,
+ (2,0): 13, 14, 15, 16, 17, 18,
+ (3,0): 19, 20, 21, 22, 23, 24
+ }
+ }
+}
+}
+\endcode
+
+The second example imports string data. The example program that creates this file can be downloaded
+from the <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page.
+
+Note that string data requires use of the <code style="background-color:whitesmoke;">h5dump -y</code>
+option to exclude indexes and the <code style="background-color:whitesmoke;">h5dump --width=1</code>
+option to generate a single column of strings. The <code style="background-color:whitesmoke;">-o</code>
+option outputs the data into an ASCII file.
+\code
+h5dump -p -d "/DS1" -O vlstring.dmp -o vlstring.ascii -y --width=1 h5ex_t_vlstring.h5
+h5import vlstring.ascii -c vlstring.dmp -o new-vlstring.h5
+\endcode
+
+The output before and after running these commands is shown below:
+\code
+$ h5dump h5ex_t_vlstring.h5
+HDF5 "h5ex_t_vlstring.h5" {
+GROUP "/" {
+ DATASET "DS1" {
+ DATATYPE H5T_STRING {
+ STRSIZE H5T_VARIABLE;
+ STRPAD H5T_STR_SPACEPAD;
+ CSET H5T_CSET_ASCII;
+ CTYPE H5T_C_S1;
+ }
+ DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
+ DATA {
+ (0): "Parting", "is such", "sweet", "sorrow."
+ }
+ }
+}
+}
+
+$ h5dump -p -d "/DS1" -O vlstring.dmp -o vlstring.ascii -y --width=1 h5ex_t_vlstring.h5
+
+$ h5import vlstring.ascii -c vlstring.dmp -o new-vlstring.h5
+
+$ h5dump new-vlstring.h5
+HDF5 "new-vlstring.h5" {
+GROUP "/" {
+ DATASET "DS1" {
+ DATATYPE H5T_STRING {
+ STRSIZE H5T_VARIABLE;
+ STRPAD H5T_STR_NULLTERM;
+ CSET H5T_CSET_ASCII;
+ CTYPE H5T_C_S1;
+ }
+ DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
+ DATA {
+ (0): "Parting", "is such", "sweet", "sorrow."
+ }
+ }
+}
+\endcode
+
+<hr>
+Navigate back: \ref index "Main" / \ref GettingStarted / \ref ViewToolsCommand
+
+*/
generated by cgit v0.12 at 2024-07-05 01:14:57 (GMT)