Routines (alphabetical) > Routines: H > HDF5 Routines > H5D_READ

# 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:

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_READ, H5S_CREATE_SIMPLE, H5S_SELECT_ELEMENTS, H5S_SELECT_HYPERSLAB