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 type. This native type is then converted to an IDL type as shown in the following table:

HDF5 Class

HDF5 Datatype

IDL Type

H5T_INTEGER

H5T_BITFIELD

H5T_ENUM

H5T_NATIVE_UINT8

Byte

H5T_NATIVE_INT8

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_REF_DSETREG

Structure

H5T_FLOAT

H5T_NATIVE_FLOAT

Floating point

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: IDL does not have a signed 8-bit integer type. For the H5T_NATIVE_INT8 datatype, the values are returned as unsigned bytes. In this case, data values from 0-127 are returned unchanged, while data values from -128 to -1 are wrapped into the range 128-255. To convert an array of byte values into signed (16-bit) integers, the following code snippet may be used:

bytedata = H5D_READ(id)

intdata = FIX(bytedata) - 256*(bytedata ge 128)

 

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

See Also

H5D_CLOSE, H5D_OPEN, H5D_WRITE, H5S_CREATE_SIMPLE, H5S_SELECT_ELEMENTS, H5S_SELECT_HYPERSLAB