Previous Scientific Data Formats: Hierarchical Data Format - HDF5 Next

H5_PARSE

Syntax | Return Value | Arguments | Keywords | Example | Version History | See Also

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.

Two structure fields were added in IDL 6.1. If an H5_PARSE structure from IDL 6.0 is restored the /RELAXED_STRUCTURE_ASSIGNMENT keyword should be used to prevent backward incompatibility.

Syntax

Result = H5_PARSE (File [, /READ_DATA])

or

Result = H5_PARSE (Loc_id, Name [, FILE=string] [, PATH=string] [, /READ_DATA] [, /SHOW_HARDLINKS])

Return Value

The Result is an IDL structure containing the parsed file or group. The fields within each structure in Result depend upon the object type.

Structure Fields Common to All Object Types

Table 3-7: Structure Fields Common to All Object Types

Table 3-7: Structure 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

Table 3-8: Additional Fields for Groups, Datasets, and Named Datatypes

Table 3-8: 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

Table 3-9: Additional Fields for Groups

Table 3-9: Additional Fields for Groups
Field
Description
_COMMENT
Comment string
Additional Fields for Datasets, Attributes, and Named Datatypes

Table 3-10: Additional Fields for Datasets, Attributes,
and Named Datatypes 

Table 3-10: 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 a null string

Additional Fields for Datasets and Attributes

Table 3-11: Additional Fields for Datasets and Attributes

Table 3-11: 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 a null string then the current object is actually a hard link to the object denoted by this string.

Additional Fields for Links

Table 3-12: Additional Fields Links

Table 3-12: Additional Fields 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 substructures within Result. The tag names for these substructures 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.

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.

Example

The following example shows how to parse a file, and then prints out 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: 

** Structure <5f24468>, 13 tags, length=6872, data length=6664, 
refs=1:  
   _NAME STRING    'D:\ITT\idl63\examples\data\hdf5_test.h5'  
   _ICONTYPE       STRING    'hdf'  
   _TYPE       STRING    'GROUP'  
   _FILE       STRING    'D:\ITT\idl63\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]

Now print out 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:\ITT\debug\examples\data\hdf5_test.h5'  
   _PATH           STRING    '/images'  
   _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]

Version History

5.6
Introduced
6.2
Added _HARDLINK and _LINKTYPE structure fields.

See Also

H5_BROWSER

  IDL Online Help (March 06, 2007)