H5_CREATE

The H5_CREATE function creates and closes a new HDF5 file. This is a simplified routine that encapsulates some of the routines listed in the following sections. Dataspaces are all defined as the full extent of the data, and datatypes are created automatically based on the type of the data.

There are two primary scenarios for the use of H5_CREATE. The first is a new HDF5 file being created from structures created in IDL. The second is an HDF5 file read using H5_PARSE, where modifications are then made to the structure.

Note: Passing the output structure of H5_PARSE to H5_CREATE may not always completely reproduce the original file. These routines do not handle references or user-defined datatypes. Additionally, dataset chunking (and therefore dataset extensibility and compression) is not supported.

Note: This function is not part of the standard HDF5 interface, but is provided as a programming convenience.

Examples

As mentioned, there are two primary use cases for H5_CREATE. These are shown in the following example cases.

In the first case, a new HDF5 file is created from structures created in IDL. For example: to create an HDF5 file containing a single data set with a palette attached as an attribute the following code could be used:

grey_scale = byte(bindgen(256)##(bytarr(3)+1b))

palette = {_TYPE:'Attribute', _DATA:grey_scale}

dataset = {_NAME:'Hanning', _TYPE:'Dataset', $

           _DATA:hanning(100,200), PALETTE:palette}

H5_CREATE, 'myfile.h5', dataset

In the second case an HDF5 file is read using H5_PARSE, modifications are made to the structure and the resulting structure is written to a new file. For example, to change the palette in the example file created above so that the colors are reversed:

result = H5_PARSE('myfile.h5', /READ_DATA)

newpalette = reverse(result.hanning.palette._data, 2)

result.hanning.palette._data = newpalette

H5_CREATE, 'myNEWfile.h5', result

Syntax

H5_CREATE, Filename, Structure

Arguments

Filename

The full path name of the file to create. If the file exists it will be overwritten.

Structure

An IDL structure variable (such as one that could be from H5_PARSE) that conforms to the following:

To create an HDF5 Group the following tags can be used:

Field	Description
_NAME	String: Object name
_TYPE (required)	String: “GROUP” (case insensitive)
_COMMENT	String: Any user defined string
STRUCTURES	Any number of additional structures describing datasets, attributes, groups, or links contained with this group

Note: To create a top level group in the file the _NAME field must be defined as the single character /, an empty string, or left undefined, otherwise a group underneath the top level group will be created.

To create an HDF5 Dataset the following tags can be used:

Field	Description
_NAME	String: Object name
_TYPE (required)	String: “DATASET” (case insensitive)
_DATA (required)	Any IDL variable (except HDF5 references) accepted by H5D_WRITE
_DIMENSIONS	A vector containing the dimensions for the dataspace. If not supplied the dimensions will be taken directly from the data.
STRUCTURES	Any number of additional structures describing attributes contained with this dataset

To create an HDF5 Datatype the following tags can be used:

Field	Description
_NAME	String: Object name
_TYPE (required)	String: “DATATYPE” (case insensitive)
_DATA (required)	Any IDL variable (except HDF5 references)
STRUCTURE	Any number of additional structures describing attributes contained within this datatype or describing the individual elements of a compound datatype.

Note: When creating a DATATYPE structure the _DATA tag is required. However, the structure returned from H5_PARSE can also be used and a proper datatype will be created without the _DATA tag as long as the _DATATYPE, _STORAGESIZE, and _SIGN tags returned are intact. If a compound datatype is being created, and the _DATA tag is not present, the additional structures define the fields of the datatype and the _STORAGESIZE and _SIGN tags are ignored.

To create an HDF5 Attribute the following tags can be used:

Field	Description
_NAME	String: Object name
_TYPE (required)	String: “ATTRIBUTE” (case insensitive)
_DATA (required)	Any IDL variable (except HDF5 references) accepted by H5A_WRITE

Note: Note: The ATTRIBUTE structure must be contained within a GROUP or DATASET structure, it cannot be a top level structure.

To create an HDF5 Link the following tags can be used:

Field	Description
_NAME	String: Object name
_TYPE (required)	String: “LINK” (case insensitive)
_DATA (required)	(required) String: The name (with path information) of the object to which the link will point
_LINK_TYPE	String: “SOFT” or “HARD” (case insensitive). If not supplied a soft link is created by default

Note: The _DATA field must contain the full path information, from the top level group, to the object to which the link will point while _NAME contains the name that will appear in the group in which the link structure exists. For example:

{_NAME : "Link1", _TYPE : "LINK", _DATA : "/Group1/MyDataset"}

Note: If the _NAME field is not supplied then the name of the structure tag will be used. Additional tags may exist in the structure(s) but will be ignored.

Keywords

None

Version History

6.2	Introduced