The H5_PARSE function recursively descends through an HDF5 file or group and creates an IDL structure containing object information and data.
Note: This function is not part of the standard HDF5 interface, but is provided as a programming convenience.
Tip: After you have parsed the HDF5 file, you can modify the data and then use H5_CREATE to easily create a new HDF5 file.
Example
The following example shows how to parse a file and print the parsed structure.
File = FILEPATH('hdf5_test.h5', SUBDIR=['examples','data'])
Result = H5_PARSE(File)
help, Result, /STRUCTURE
When the above commands are entered, IDL prints something similar to the following:
** Structure <5f24468>, 13 tags, length=6872, data length=6664, refs=1:
_NAME STRING '\examples\data\hdf5_test.h5'
_ICONTYPE STRING 'hdf'
_TYPE STRING 'GROUP'
_FILE STRING '\examples\data\hdf5_test.h5'
_PATH STRING '/'
_COMMENT STRING ''
_2D_INT_ARRAY STRUCT -> <Anonymous> Array[1]
A_NOTE STRUCT -> <Anonymous> Array[1]
SL_TO_3D_INT_ARRAY
STRUCT -> <Anonymous> Array[1]
ARRAYS STRUCT -> <Anonymous> Array[1]
DATATYPES STRUCT -> <Anonymous> Array[1]
IMAGES STRUCT -> <Anonymous> Array[1]
LINKS STRUCT -> <Anonymous> Array[1]
Print the structure of a dataset within the “Images” group:
help, Result.images.eskimo, /STRUCTURE
IDL prints:
** Structure <16f1ca0>, 20 tags, length=840, data length=802, refs=2:
_NAME STRING 'Eskimo'
_ICONTYPE STRING 'binary'
_TYPE STRING 'DATASET'
_FILE STRING 'D:\debug\examples\data\hdf5_test.h5'
_PATH STRING
_DATA STRING '<unread>'
_NDIMENSIONS LONG 2
_DIMENSIONS ULONG64 Array[2]
_NELEMENTS ULONG64 389400
_DATATYPE STRING 'H5T_INTEGER'
_STORAGESIZE ULONG 1
_PRECISION LONG 8
_SIGN STRING 'unsigned'
CLASS STRUCT -> <Anonymous> Array[1]
IMAGE_VERSION STRUCT -> <Anonymous> Array[1]
IMAGE_SUBCLASS STRUCT -> <Anonymous> Array[1]
IMAGE_COLORMODEL
STRUCT -> <Anonymous> Array[1]
IMAGE_MINMAXRANGE
STRUCT -> <Anonymous> Array[1]
IMAGE_TRANSPARENCY
STRUCT -> <Anonymous> Array[1]
PALETTE STRUCT -> <Anonymous> Array[1]
Print the structure of the dataset as an ordered hash:
Result = H5_PARSE(File, /ORDEREDHASH)
Print, Result
IDL prints:
{
"_NAME": "C:\\Program Files\\***\\IDLxx\\examples\\data\\hdf5_test.h5",
"_ICONTYPE": "hdf",
"_TYPE": "GROUP",
"_FILE": "C:\\Program Files\\***\\IDLxx\\examples\\data\\hdf5_test.h5",
"_PATH": "/",
"_COMMENT": "",
"2D int array": {
"_NAME": "2D int array",
"_ICONTYPE": "binary",
"_TYPE": "DATASET",
"_FILE": "C:\\Program Files\\***\\IDLxx\\examples\\data\\hdf5_test.h5",
"_PATH": "/",
"_NDIMENSIONS": 2,
"_DIMENSIONS": [50, 100],
"_NELEMENTS": 5000,
"_DATATYPE": "H5T_INTEGER",
"_STORAGESIZE": 4,
"_PRECISION": 32,
"_SIGN": "signed",
"_DATA": "<unread>"
},
etc.
Syntax
Result = H5_PARSE (File [, /ORDEREDHASH] [, /READ_DATA])
or
Result = H5_PARSE (Loc_id, Name [, FILE=string] [, /ORDEREDHASH] [, PATH=string] [, /READ_DATA] [, /SHOW_HARDLINKS])
Return Value
The Result is an IDL structure or ordered hash containing the parsed file or group. The fields within each structure in Result depend upon the object type.
Structure or Hash Fields Common to All Object Types
|
Field |
Description |
|
_NAME |
Object name, or the filename if at the top level
|
|
_ICONTYPE |
Name of associated icon, used by H5_BROWSER
|
|
_TYPE |
Object type, such as GROUP, DATASET, DATATYPE, ATTRIBUTE, or LINK
|
Additional Fields for Groups, Datasets, and Named Datatypes
|
Field |
Description |
|
_FILE |
The filename to which the object belongs
|
|
_PATH |
Full path to the group, dataset, or datatype within the file
|
Additional Fields for Groups
|
Field |
Description |
|
_COMMENT |
Comment string |
Additional Fields for Datasets, Attributes, and Named Datatypes
|
Field |
Description |
|
_DATATYPE |
Datatype class, such as H5T_INTEGER
|
|
_STORAGESIZE |
Size of each value in bytes
|
|
_PRECISION |
Precision of each value in bits
|
|
_SIGN |
For integers, either ‘signed’ or ‘unsigned’; otherwise an empty string
|
Additional Fields for Datasets and Attributes
|
Field |
Description |
|
_DATA |
Data values stored in the object
|
|
_NDIMENSIONS |
Number of dimensions in the dataspace
|
|
_DIMENSIONS |
List of dataspace dimensions
|
|
_NELEMENTS |
Total number of elements in the dataspace
|
|
_HARDLINK |
Full path to the object being linked to. If this is not an empty string then the current object is actually a hard link to the object denoted by this string.
|
Additional Fields for Links
|
Field |
Description |
|
_LINKTYPE |
If the SHOW_HARDLINKS keyword is set then this field will be added to links and will contain the value ‘HARD’. Soft links will not have this field added.
|
Groups, datasets, datatypes, and attributes will be stored as fields within Result. The tag names for these fields are constructed from the actual object name by converting all non-alphanumeric characters to underscores, and converting all characters to uppercase. If a tag name already exists (for example a datatype and an attribute have the same name) then an appropriate suffix is appended on to the end of the tag name, such as “_ATTR” for attribute, and so on.
If a tag name already exists within the same dataset then the suffix that is appended on to the end of the tag name will consist of _X where X starts with 1 and increments as needed.
Arguments
File
A string giving the name of the file to parse.
Loc_id
An integer giving the file or group identifier to access.
Name
A string giving the name of the group, dataset, or datatype within Loc_id to parse.
Keywords
FILE
Set this optional keyword to a string giving the filename associated with the Loc_id. This keyword is used for filling in the _FILE field within the returned structure, and is not required. The FILE keyword is ignored if the File argument is provided.
ORDEREDHASH
Set this keyword to return an ordered hash in place of a structure. An ordered hash will preserve the case and all special characters in the tag names of objects within the file.
PATH
Set this optional keyword to a string giving the full path associated with the Loc_id. This keyword is used for filling in the _PATH field within the returned structure, and is not required. The PATH keyword is ignored if the File argument is provided.
READ_DATA
If this keyword is set, then all data from datasets is read in and stored in the returned structure. If READ_DATA is not provided then the _DATA field for datasets will be set to the string ‘<unread>’.
Note: For attribute objects all data is automatically read and stored in the structure.
SHOW_HARDLINKS
If this keyword is set, then hardlinks will appear as a LINK structure. The default is to treat hardlinks as copies of the object pointed to.
Note: Because there is no distinguishable difference between a hard link and the object to which the link points, the first object encountered in the file is taken to be the object and any subsequent apparent copies of the object are taken to be links. This may be different than the actual order in the file.
Version History
|
5.6 |
Introduced |
|
6.2 |
Added _HARDLINK and _LINKTYPE structure fields.
|
|
8.4.1 |
Added ORDEREDHASH keyword. |
See Also
H5_BROWSER, H5_CREATE, HDF_PARSE