Expand all Collapse all

Jump to ...
Summary
Description
Example
Switch language ...
C
C++
FORTRAN
JAVA

H5L_ITERATE2

Iterates through links in a group

Procedure:

H5L_ITERATE2 ( group_id, idx_type, order, idx_p, op, op_data )

Signature:

herr_t H5Literate2 ( hid_t group_id, H5_index_t idx_type, H5_iter_order_t order,
    hsize_t *idx_p, H5L_iterate2_t op, void *op_data )

SUBROUTINE h5literate_f(group,index_type, order, position,
           op, ctx, return_value, hdferr)
    INTEGER(HID_T) , INTENT(IN) :: group
    INTEGER , INTENT(IN) :: index_type
    INTEGER , INTENT(IN) :: order
    INTEGER(HSIZE_T), INTENT(INOUT) :: position
    TYPE(C_FUNPTR) , INTENT(IN) :: op
    TYPE(C_PTR) , INTENT(IN) :: ctx
    INTEGER , INTENT(OUT) :: return_value
    INTEGER , INTENT(OUT) :: hdferr

Parameters:

Name	Mode	Kind	Description
group_id	IN	handle	File or group identifier
idx_type	IN	choice	Index for iteration order
order	IN	choice	Traversal order
idx_p	INOUT	integer	Iteration position
op	IN	delegate	User-defined operator
op_data	INOUT	opaque	User-supplied context

Description:

H5L_ITERATE2 iterates through the links in a file or group, group_id, in the order of the specified index, idx_type, using a user-defined callback routine op. H5L_ITERATE2 does not recursively follow links into subgroups of the specified group.

Three parameters are used to manage progress of the iteration: idx_type, order, and idx_p.

idx_type specifies the index to be used. If the links have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly.

The choices for idx_type are:

Name	Meaning
H5_INDEX_NAME	Lexicographic order
H5_INDEX_CRT_ORDER	Creation order

order specifies the order in which objects are to be inspected along the index idx_type. The choices for order are:

Name	Meaning
H5_ITER_INC	Increasing order
H5_ITER_DEC	Decreasing order
H5_ITER_NATIVE	Fastest order

idx_p tracks the iteration and allows an iteration to be resumed if it was stopped before all members were processed. It is passed in by the application with a starting point and returned by the library with the point at which the iteration stopped.

op_data is a user-defined pointer to the data required to process links in the course of the iteration. This pointer is passed back to each step of the iteration in the op callback function’s op_data parameter.

op is invoked for each link encounter:

Signature:

herr_t (*H5L_iterate2_t)
(
  hid_t               group,
  const char*         name,
  const H5L_info2_t*  info,
  void*               op_data
)

Info:


typedef struct {
    H5L_type_t          type;           /* Type of link                   */
    hbool_t             corder_valid;   /* Indicate if creation order is valid */
    int64_t             corder;         /* Creation order                 */
    H5T_cset_t          cset;           /* Character set of link name     */
    union {
        H5O_token_t     token;          /* Token of location that hard link points to */
        size_t          val_size;       /* Size of a soft link or UD link value */
    } u;
} H5L_info2_t;

typedef enum {
    H5L_TYPE_ERROR = (-1),      /* Invalid link type id         */
    H5L_TYPE_HARD = 0,          /* Hard link id                 */
    H5L_TYPE_SOFT = 1,          /* Soft link id                 */
    H5L_TYPE_EXTERNAL = 64,     /* External link id             */
    H5L_TYPE_MAX = 255          /* Maximum link type id         */
} H5L_type_t;

/*
 * Character set to use for text strings.  Do not change these values since
 * they appear in HDF5 files!
 */
typedef enum H5T_cset_t {
    H5T_CSET_ERROR       = -1,  /*error                                      */
    H5T_CSET_ASCII       = 0,   /*US ASCII                                   */
    H5T_CSET_UTF8        = 1,   /*UTF-8 Unicode encoding                     */
    H5T_CSET_RESERVED_2  = 2,   /*reserved for later use                     */
    H5T_CSET_RESERVED_3  = 3,   /*reserved for later use                     */
    H5T_CSET_RESERVED_4  = 4,   /*reserved for later use                     */
    H5T_CSET_RESERVED_5  = 5,   /*reserved for later use                     */
    H5T_CSET_RESERVED_6  = 6,   /*reserved for later use                     */
    H5T_CSET_RESERVED_7  = 7,   /*reserved for later use                     */
    H5T_CSET_RESERVED_8  = 8,   /*reserved for later use                     */
    H5T_CSET_RESERVED_9  = 9,   /*reserved for later use                     */
    H5T_CSET_RESERVED_10 = 10,  /*reserved for later use                     */
    H5T_CSET_RESERVED_11 = 11,  /*reserved for later use                     */
    H5T_CSET_RESERVED_12 = 12,  /*reserved for later use                     */
    H5T_CSET_RESERVED_13 = 13,  /*reserved for later use                     */
    H5T_CSET_RESERVED_14 = 14,  /*reserved for later use                     */
    H5T_CSET_RESERVED_15 = 15   /*reserved for later use                     */
} H5T_cset_t;

/* Type for object tokens */
typedef struct H5O_token_t {
    uint8_t __data[H5O_MAX_TOKEN_SIZE];
} H5O_token_t;

Returns:

Return value	Meaning
0	Continue iteration
> 0	Stop iteration; successful termination
< 0	Stop iteration; abnormal termination

op_data is passed to and from each iteration and can be used to supply or aggregate information across iterations.

The behavior of H5L_ITERATE2 is undefined if the link membership of group_id changes during the iteration. This does not limit the ability to change link destinations while iterating, but caution is advised.

For recursive behavior, see the following the H5L_VISIT functions.

Returns:

On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.

On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.

Example:

examples / h5_group.c [135:138]

hdf5_1_12 HDFFV/hdf5 Copy

     * Use iterator to see the names of the objects in the root group.
     */
    idx_f = H5Literate2(file, H5_INDEX_NAME, H5_ITER_INC, NULL, file_info, NULL);

1_8 / FORTRAN / H5G / h5ex_g_iterate_F03.f90

master HDFFV/hdf5-examples Copy

!************************************************************
!
!  This example shows how to iterate over group members using
!  H5Literate.
!
!  This file is intended for use with HDF5 Library version 1.8
!  with --enable-fortran2003 
!
!
!************************************************************
MODULE g_iterate
  
  USE HDF5
  USE ISO_C_BINDING
  IMPLICIT NONE

CONTAINS

!************************************************************
!
!  Operator function.  Prints the name and type of the object
!  being examined.
!
! ************************************************************

  INTEGER FUNCTION op_func(loc_id, name, info, operator_data) bind(C)
    
    USE HDF5
    USE ISO_C_BINDING
    IMPLICIT NONE
    
    INTEGER(HID_T), VALUE :: loc_id
    CHARACTER(LEN=1), DIMENSION(1:10) :: name ! must have LEN=1 for bind(C) strings
    TYPE(C_PTR) :: info
    TYPE(C_PTR) :: operator_data
    
    INTEGER   :: status, i, len

    TYPE(H5O_info_t), TARGET :: infobuf 
    TYPE(C_PTR) :: ptr
    CHARACTER(LEN=10) :: name_string

    !
    ! Get type of the object and display its name and type.
    ! The name of the object is passed to this FUNCTION by
    ! the Library.
    !

    DO i = 1, 10
       name_string(i:i) = name(i)(1:1)
    ENDDO

    CALL H5Oget_info_by_name_f(loc_id, name_string, infobuf, status)

    ! Include the string up to the C NULL CHARACTER
    len = 0
    DO
       IF(name_string(len+1:len+1).EQ.C_NULL_CHAR.OR.len.GE.10) EXIT
       len = len + 1
    ENDDO

    IF(infobuf%type.EQ.H5O_TYPE_GROUP_F)THEN
       WRITE(*,*) "Group: ", name_string(1:len)
    ELSE IF(infobuf%type.EQ.H5O_TYPE_DATASET_F)THEN
       WRITE(*,*) "Dataset: ", name_string(1:len)
    ELSE IF(infobuf%type.EQ.H5O_TYPE_NAMED_DATATYPE_F)THEN
       WRITE(*,*) "Datatype: ", name_string(1:len)
    ELSE
       WRITE(*,*) "Unknown: ", name_string(1:len)
    ENDIF

    op_func = 0 ! return successful

  END FUNCTION op_func

END MODULE g_iterate


PROGRAM main

  USE HDF5
  USE ISO_C_BINDING
  USE g_iterate
  
  IMPLICIT NONE

  CHARACTER(LEN=17), PARAMETER :: filename  = "h5ex_g_iterate.h5"
  INTEGER(HID_T) :: file ! Handle
  INTEGER :: status
  TYPE(C_FUNPTR) :: funptr
  TYPE(C_PTR) :: ptr
  INTEGER(hsize_t) :: idx
  INTEGER :: ret_value
  !
  ! Initialize FORTRAN interface.
  !
  CALL h5open_f(status)
  !
  ! Open file.
  !
  CALL H5Fopen_f(filename, H5F_ACC_RDONLY_F, file, status)
  !
  ! Begin iteration.
  !
  WRITE(*,'(A)') "Objects in root group:"

  idx = 0
  funptr = C_FUNLOC(op_func) ! call back function
  ptr    = C_NULL_PTR

  CALL H5Literate_f(file, H5_INDEX_NAME_F, H5_ITER_NATIVE_F, idx, funptr, ptr, ret_value, status)

  !
  ! Close and release resources.
  !
  CALL H5Fclose_f(file, status)

END PROGRAM main

History:

Release	Change
1.12.0	Function was introduced in this release.

--- Last Modified: February 19, 2020 | 10:46 AM

Page tree

H5L_ITERATE2

Procedure:

Signature:

Parameters:

Description:

Signature:

Info:

Returns:

Returns:

Example:

History:

The HDF Group

Site

Resources

Connect