Routines (alphabetical) > Routines: H > HDF Routines > HDF_PARSE

# HDF_PARSE

The HDF_PARSE function recursively descends through an HDF4 file and creates an ordered hash containing object information and data.

Note: This function is not part of the standard HDF interface but is provided as a programming convenience. Its IDL source code is in the file `hdf_parse.pro`, located in the IDL `lib` directory.

## Example

The following example shows how to parse a file and print the tags of the ordered hash:

File = FILEPATH('vattr_example.hdf', SUBDIR=['examples','data'])

Result = HDF_PARSE(File)

Result

IDL prints:

{

"_NAME": "C:\\<etc.>\\vattr_example.hdf",

"_TYPE": "GROUP",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/",

"MetObs": {

"_NAME": "MetObs",

"_TYPE": "VDATA",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/",

"_COUNT": 10,

"_NFIELDS": 1,

"_FIELD_NAMES": ["TempDP"],

"TempDP": {

"_NAME": "TempDP",

"_TYPE": "VDATA_FIELD",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/MetObs",

"_ORDER": 1,

"_IDL_DATATYPE": "INT",

"_DATA": "<unread>",

"field_contents": {

"_NAME": "field_contents",

"_TYPE": "ATTRIBUTE",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/MetObs/TempDP",

"_IDL_DATATYPE": "STRING",

"_DATA": "Dew point temperature in degrees Celsius."

}

},

"vdata_contents": {

"_NAME": "vdata_contents",

"_TYPE": "ATTRIBUTE",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/MetObs",

"_IDL_DATATYPE": "STRING",

"_DATA": "Ground station meteorological observations."

},

"num_stations": {

"_NAME": "num_stations",

"_TYPE": "ATTRIBUTE",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/MetObs",

"_IDL_DATATYPE": "INT",

"_DATA": [10]

}

},

"vdata_contents": {

"_NAME": "vdata_contents",

"_TYPE": "VDATA",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/",

"_COUNT": 1,

"_NFIELDS": 1,

"_FIELD_NAMES": ["VALUES"],

"VALUES": {

"_NAME": "VALUES",

"_TYPE": "VDATA_FIELD",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/vdata_contents",

"_ORDER": 43,

"_IDL_DATATYPE": "BYTE",

"_DATA": "<unread>

}

},

"num_stations": {

"_NAME": "num_stations",

"_TYPE": "VDATA",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/",

"_COUNT": 1,

"_NFIELDS": 1,

"_FIELD_NAMES": ["VALUES"],

"VALUES": {

"_NAME": "VALUES",

"_TYPE": "VDATA_FIELD",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/num_stations",

"_ORDER": 1,

"_IDL_DATATYPE": "INT",

"_DATA": "<unread>"

}

},

"field_contents": {

"_NAME": "field_contents",

"_TYPE": "VDATA",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/",

"_COUNT": 1,

"_NFIELDS": 1,

"_FIELD_NAMES": ["VALUES"],

"VALUES": {

"_NAME": "VALUES",

"_TYPE": "VDATA_FIELD",

"_FILE": "C:\\<etc.>\\vattr_example.hdf",

"_PATH": "/field_contents",

"_ORDER": 41,

"_IDL_DATATYPE": "BYTE",

"_DATA": "<unread>"

}

}

}

The next example uses the READ_DATA keyword and prints the contents of a VData field:

File = FILEPATH('vattr_example.hdf', SUBDIR=['examples','data'])

Result = HDF_PARSE(File, /READ_DATA)

Print, Result['num_stations', 'VALUES', '_DATA']

IDL prints:

10

## Syntax

Result = HDF_PARSE(File, [/ READ_DATA])

## Return Value

The Result is an ordered hash containing the parsed file. The tags in the hash depend upon the object type, as outlined in the tables below.

#### Tags common to all object types

Tag | Description
--- | ---
_NAME | Object name (or filename if at top level)
_TYPE | Object type, which can be any of the following: VGROUP, VDATA, VDATA_FIELD, SD, IMAGE, ATTRIBUTE, ANNOTATION, or PALETTE
_FILE | The filename to which the object belongs
_PATH | The full path within the file to the object. If the object is at the root level of the file, then this field is set to '`/`'.

#### Tags associated with VGroups

All objects within the group will be added to the group's hash with their names as the keys.

#### Tags associated with VData

Tag | Description
--- | ---
_COUNT | The number of records in the data
_NFIELDS | The number of fields in the dataset
_FIELD_NAMES | A string array with the names of all fields within the VData. If there are no fields, this value is set to !NULL.

Fields within the VData will be added as fields to the ordered hash with the field names as the hash key names. See the next table for a description of the fields.

If the VData contains attributes or annotations, they will be added to the Vdata hash with the attribute or annotation names for the keys.

#### Tags associated with VData fields

Tag | Description
--- | ---
_ORDER | The number of entries (the order) of the field
_IDL_DATATYPE | String value corresponding to the IDL data type of the field values
_DATA | If the READ_DATA keyword is set, this field contains the data from the file. Otherwise, it contains the string `<unread>`.

If the field contains attributes, they will be added to the data field's hash with the attribute names for the keys.

#### Tags associated with Scientific Datasets (SDs)

Tag | Description
--- | ---
_NDIMENSIONS | Number of dimensions
_DIMENSIONS | Dimensions of the dataset
_IDL_DATATYPE | A string corresponding to the IDL data type of the dataset
_DATA | If the READ_DATA keyword is set, this field contains the data from the file. Otherwise, it contains the string `<unread>`.

If the dataset contains attributes, they will be added to the dataset's hash, with the attribute names for the keys.

#### Tags associated with images

Tag | Description
--- | ---
_RASTER_TYPE | HDF4 contains three types of raster images: `GR` - General Raster `8BIT` - 8-bit raster image (RIS8) `24BIT` - 24-bit raster image (RIS24)
_NDIMENSIONS | The number of dimensions in the image.
_DIMENSIONS | The image dimensions
_IDL_DATATYPE | String value corresponding to the IDL data type of the image.
_INTERLACE | An integer corresponding to the interlace mode of the image data. Possible values are: 0: Pixel interlace 1: Line interlace 2: Component interlace
_DATA | If the READ_DATA keyword is set, this field contains the data from the file. Otherwise, it contains the string `<unread>`.

If the image contains attributes, they will be added to the dataset's hash, with the attribute names for the keys.

#### Tags associated with attributes

Tag | Description
--- | ---
_IDL_DATATYPE | A string corresponding to the IDL data type of the dataset
_DATA | The data from the attribute. The HDF_PARSE function always reads data from attributes, regardless of the READ_DATA keyword setting.

#### Tags associated with annotations

Tag | Description
--- | ---
_DATA | The value stored in the annotation. The HDF_PARSE function always reads data from annotations, regardless of the READ_DATA keyword setting.

#### Tags associated with palettes

Tag | Description
--- | ---
_DATA | The value stored in the annotation. The HDF_PARSE function always reads data frompalettes, regardless of the READ_DATA keyword setting.

## Arguments

### File

A string that specifies the file to be parsed.

## Keywords

### READ_DATA

If you set this keyword, all data from scientific datasets, images, and VData fields will be read from the file. If you do not set this keyword, the _DATA field for these object types will be set to the string `'<unread>'`.

## Version History

8.4.1 | Introduced

## See Also

H5_PARSE