H5D_READ

The H5D_READ function reads the data within a dataset, converting from the HDF5 file datatype into the HDF5 memory datatype, and finally into the corresponding IDL datatype.

Syntax

Result = H5D_READ(Dataset_id [, Datatype_id] [, FILE_SPACE=id] [, MEMORY_SPACE=id] )

Return Value

Returns an IDL variable containing the specified data. The different return types and storage mechanisms are described below.

Note
The dimensions for the Result variable are constructed using the following precedence rules:

If MEMORY_SPACE is specified, then the dimensions of the MEMORY_SPACE are used.

If only FILE_SPACE is specified, then the dimensions of the FILE_SPACE are used.

If neither MEMORY_SPACE nor FILE_SPACE are specified, then the dimensions are taken from the Dataset_id.

Arguments

Dataset_id

A long integer containing the identifier of the dataset to read.

Datatype_id

A long integer containing the identifier of the memory datatype to read. This argument is used only when reading part of a compound dataset. If Datatype_id is not supplied, the entire dataset is read.

Keywords

FILE_SPACE

Set this keyword to the file dataspace identifier that should be used when reading the dataset. The FILE_SPACE keyword may be used to define hyperslabs or elements for subselection within the dataset. The default is zero (in HDF5 this is equivalent to H5S_ALL), which indicates that the entire dataspace should be read.

MEMORY_SPACE

Set this keyword to the memory dataspace identifier that should be used when copying the data from the file into memory. The MEMORY_SPACE keyword may be used to define hyperslabs or elements in which to place the data. The default is zero (in HDF5 this is equivalent to H5S_ALL), which indicates that the memory dataspace is identical to the file dataspace.

Return Type

When reading in HDF5 datasets, the datatype is first set to the native HDF5 types. These native types are then converted to IDL types as shown in the following table:

Table 3-14: HDF and IDL Datatypes
HDF5 Class	HDF5 Datatype	IDL Type
H5T_INTEGER H5T_BITFIELD H5T_ENUM	H5T_NATIVE_UINT8	Byte
	H5T_NATIVE_INT16	Integer
	H5T_NATIVE_UINT16	Unsigned integer
	H5T_NATIVE_INT32	Long integer
	H5T_NATIVE_UINT32	Unsigned long integer
	H5T_NATIVE_INT64	64-bit integer
	H5T_NATIVE_UINT64	Unsigned 64-bit integer
H5T_REFERENCE	H5T_STD_REF_OBJ	Unsigned 64-bit integer
H5T_REFERENCE	H5T_REF_DSETREG	Structure
H5T_FLOAT	H5T_NATIVE_FLOAT	Floating point
H5T_FLOAT	H5T_NATIVE_DOUBLE	Double-precision floating
H5T_STRING	H5T_C_S1	String
H5T_TIME	H5T_C_S1	String
H5T_COMPOUND	(Member datatypes)	Structure
H5T_ARRAY	(Super datatype)	(Super type)

Note
Multidimensional datasets are returned in IDL column-major order, with the fastest-varying dimensions listed first. HDF5 uses C row-major order, with the fastest-varying dimensions listed last. In both cases, the memory layout for data elements is identical (i.e., no transpose is needed), and only the order of the dimensions is reversed.

Note
For the H5T_ARRAY datatype, the array dimensions are concatenated with the dataset dimensions, with the array dimensions varying more rapidly.

Note
Structure tag names are constructed from H5T_COMPOUND member names by switching to uppercase and converting all non-alphanumeric characters to underscores.

Version History


5.6	Introduced
6.2	Added H5T_STD_REF_DSETREG Datatype (structure IDL type) to the H5T_REFERENCE class
6.3	Added the Datatype_id argument