H5R: Reference Interface

Reference API Functions

H5Rcreate H5Rdereference

H5Rget_region H5Rget_object_type

Name: H5Rcreate

Signature:

herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id )

Purpose:

Creates a reference.

Description:

H5Rcreate creates the reference, ref, of the type specified in ref_type, pointing to the object name located at loc_id.

The parameters loc_id and name are used to locate the object.

The parameter space_id identifies the region to be pointed to (for dataset region references).

Parameters:

void *ref

OUT: Reference created by the function call.

hid_t loc_id

IN: Location identifier used to locate the object being pointed to.

const char *name

IN: Name of object at location loc_id.

H5R_type_t ref_type

IN: Type of reference.

hid_t space_id

IN: Dataspace identifier with selection. Used for dataset region references.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5Rdereference

Signature:

hid_t H5Rdereference(hid_t dataset, H5R_type_t ref_type, void *ref )

Purpose:

Opens the HDF5 object referenced.

Description:

Given a reference to some object, H5Rdereference opens that object and returns an identifier.

The parameter ref_type specifies the reference type of ref. ref_type may contain either of the following values:

• H5R_OBJECT (0)
• H5R_DATASET_REGION (1)

Parameters:

hid_t dataset

IN: Dataset containing reference object.

H5R_type_t ref_type

IN: The reference type of ref.

void *ref

IN: Reference to open.

Returns:

Returns valid identifier if successful; otherwise returns a negative value.

Name: H5Rget_region

Signature:

hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, void *ref )

Purpose:

Retrieves a dataspace with the specified region selected.

Description:

Given a reference to an object ref, H5Rget_region creates a copy of the dataspace of the dataset pointed to and defines a selection in the copy which is the region pointed to.

The parameter ref_type specifies the reference type of ref. ref_type may contain the following value:

• H5R_DATASET_REGION (1)

Parameters:

hid_t dataset,

IN: Dataset containing reference object.

H5R_type_t ref_type,

IN: The reference type of ref.

void *ref

IN: Reference to open.

Returns:

Returns a valid identifier if successful; otherwise returns a negative value.

Name: H5Rget_object_type

Signature:

int H5Rget_object_type(hid_t id, void *ref )

Purpose:

Retrieves the type of object that an object reference points to.

Description:

Given a reference to an object ref, H5Rget_object_type returns the type of the object pointed to.

Parameters:

hid_t id,

IN: The dataset containing the reference object or the location identifier of the object that the dataset is located within.

void *ref

IN: Reference to query.

Returns:

Returns an object type as defined in H5Gpublic.h; otherwise returns H5G_UNKNOWN.