Last modified: 7 July 2010
Name: H5LRcreate_ref_to_all
Signature:
return_type H5LRcreate_ref_to_all( hid_t loc_id, const char *group_path, const char *ds_path, H5_index_t index_type, H5_iter_order_t order,
 H5R_type_t ref_type )

Purpose:
Creates a dataset with the region references to the data in all datasets located under a specified group in a file or creates a dataset with object references to all objects (groups or datasets) located under a specified group in a file.

Description:
H5LRcreate_ref_to_all creates a dataset with the region references to the data in all datasets located under a specified group in a file or creates a dataset with object references to all objects (groups or datasets) located under a specified group in a file.

Given a dataset path ds_path in a file specified by the loc_id identifier, the function H5LRcreate_ref_to_all will create a contiguous one-dimensional dataset with the region references or object references depending on the value of the ref_type parameter. When ref_type is H5R_DATASET_REGION, each region reference points to all data in a dataset encountered by an internally called H5Lvisit routine, which starts at the group specified by the loc_id and group_path parameters. In a like manner, when ref_type is H5R_OBJECT, each object reference points to an object (a group or a dataset) encountered by H5Lvisit.

If ds_path does not exist in loc_id then the function will create the path specified by ds_path automatically.

index_type specifies the index to be used. Valid values include the following:

H5_INDEX_NAME         Alpha-numeric index on name
H5_INDEX_CRT_ORDER    Index on creation order

order specifies the order in which objects are to be inspected along the index specified in index_type. Valid values include the following:

H5_ITER_INC       Increasing order
H5_ITER_DEC       Decreasing order
H5_ITER_NATIVE    Fastest available order

For more detailed information on these two parameters, see H5Lvisit.

ref_type specifies the type of the reference to be used. Valid values include the following:

H5R_DATASEY_REGION    Dataset region reference
H5R_OBJECT            Object reference

Parameters:
hid_t loc_id      IN: File or group identifier
const char *group_path      IN: Absolute or relative path to the group at which traversal starts
const char *ds_path      IN: Absolute or relative path to the dataset with region references to be created
H5_index_t index_type      IN: Index type; valid values include:
     H5_INDEX_NAME
     H5_INDEX_CRT_ORDER
H5_iter_order_t order      IN: Order in which index is traversed; valid values include:
     H5_ITER_DEC
     H5_ITER_INC
     H5_ITER_NATIVE
H5R_type_t ref_type      IN: Reference type; valid values include:
     H5R_DATASET_REGION
     H5R_OBJECT

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

Fortran90 Interface: H5LRcreate_ref_to_all_f: USE H5HL_REGION
SUBROUTINE H5LRcreate_ref_to_all_f(loc_id, group_path, ds_path, index_type, order, ref_type, error)
    
  IMPLICIT NONE

  INTEGER(hid_t), INTENT(IN) :: loc_id       ! File or group identifier 
  CHARACTER(LEN=*), INTENT(IN) :: group_path ! Absolute or relative path to the group at 
                                             !  which traversal starts 
  CHARACTER(LEN=*), INTENT(IN) :: ds_path    ! Absolute or relative path to the dataset 
                                             !  with region references to be created  
  INTEGER, INTENT(IN) :: index_type          ! Index type; valid values include:
                                             !     H5_INDEX_NAME_F
                                             !     H5_INDEX_CRT_ORDER_F
  INTEGER, INTENT(IN) :: order               ! Order in which index is traversed; valid values include:
                                             !     H5_ITER_DEC_F
                                             !     H5_ITER_INC_F
                                             !     H5_ITER_NATIVE_F
  INTEGER, INTENT(IN) :: ref_type            ! Reference type; valid values include:  
                                             !     H5R_DATASET_REGION_F
                                             !     H5R_OBJECT_F 
  INTEGER, INTENT(OUT) :: error              ! Error code:
                                             !  0 on success and -1 on failure
END SUBROUTINE H5LRcreate_ref_to_all_f
    

History:
Release     Change
1.0 C function introduced in this release.
1.1 Fortran wrapper introduced in this release.