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 being read using H5_PARSE modifications that are made to the structure with the resulting structure being written to a new file.

Note
Passing the output structure of H5_PARSE to H5_CREATE may not always completely reproduce the original file. Types of things that are not handled by these routines include: references, user-defined datatypes, and the order of items in the file. Additionally, dataset chunking is not supported and thus operations that require chunking are also not supported, for example: dataset extensibility and compression.

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:

Table 3-2: H5_CREATE Group Structure Tags
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 /, a null 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:

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

Table 3-4: H5_CREATE Datatype Structure Tags
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:

Table 3-5: H5_CREATE Attribute Structure Tags
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 at GROUP or DATASET structure, it cannot be a top level structure.

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

Table 3-6: H5_CREATE Link Structure Tags
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

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 could 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

Version History


6.2	Introduced