H5O: Object Interface

object_info, in which the object information is returned, is a struct of type H5O_info_t. This struct type is described in the H5Oget_info function entry.

If loc_id fully specifies the group in which the object resides, group_name can be a dot (.).

The link access property list, lapl_id, is not currently used; it should be passed in as NULL.

  SUBROUTINE h5oget_info_by_idx_f(loc_id, group_name, index_field, order, n, &
       object_info, hdferr, lapl_id)

    USE, INTRINSIC :: ISO_C_BINDING
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)            :: loc_id
    CHARACTER(LEN=*), INTENT(IN)            :: group_name
    INTEGER         , INTENT(IN)            :: index_field
    INTEGER         , INTENT(IN)            :: order
    INTEGER(HSIZE_T), INTENT(IN)            :: n
    TYPE(h5o_info_t), INTENT(OUT), TARGET   :: object_info
    INTEGER         , INTENT(OUT)           :: hdferr
    INTEGER(HID_T)  , INTENT(IN) , OPTIONAL :: lapl_id

Inputs:

  loc_id      - File or group identifier specifying location of group 
                in which object is located.
  group_name  - Name of group in which object is located.
  index_field - Index or field that determines the order.
  order       - Order within field or index.
  n           - Object for which information is to be returned

Outputs:

  object_info - Buffer in which to return object information.
  hdferr      - Returns 0 if successful and -1 if fails.

Optional parameters:

  lapl_id     - Link access property list. (Not currently used.)

Related Fortran2003 Derived Type: h5o_info_t

  TYPE, BIND(C) :: space_t
     INTEGER(hsize_t) :: total ! Total space for storing object header in file
     INTEGER(hsize_t) :: meta  ! Space within header for object header metadata 
                               ! information
     INTEGER(hsize_t) :: mesg  ! Space within header for actual message 
                               ! information
     INTEGER(hsize_t) :: free  ! Free space within object header
  END TYPE space_t

  TYPE, BIND(C) :: mesg_t
     INTEGER(c_int64_t) :: present ! Flags to indicate presence of message type 
                                   ! in header 
     INTEGER(c_int64_t) :: shared  ! Flags to indicate message type is shared 
                                   ! in header
  END TYPE mesg_t
  
  TYPE, BIND(C) :: hdr_t
     INTEGER :: version ! Version number of header format in file
     INTEGER :: nmesgs  ! Number of object header messages
     INTEGER :: nchunks ! Number of object header chunks
     INTEGER :: flags   ! Object header status flags
     TYPE(space_t)  :: space   
     TYPE(mesg_t)   :: mesg
  END TYPE hdr_t

  ! Extra metadata storage for obj & attributes
  TYPE, BIND(C) :: H5_ih_info_t
     INTEGER(hsize_t) :: index_size ! btree and/or list
     INTEGER(hsize_t) :: heap_size
  END TYPE H5_ih_info_t

  TYPE, BIND(C) :: meta_size_t
     TYPE(H5_ih_info_t) :: obj  ! v1/v2 B-tree & local/fractal heap for 
                                ! groups, B-tree for chunked datasets
     TYPE(H5_ih_info_t) :: attr ! v2 B-tree & heap for attributes
  ENDTYPE meta_size_t
  
  TYPE, BIND(C) :: h5o_info_t
     INTEGER(C_LONG)  :: fileno     ! File number that object is located in
     INTEGER(haddr_t) :: addr       ! Object address in file  
     INTEGER(C_INT)   :: type       ! Basic object type (group, dataset, etc.) 
     INTEGER          :: rc         ! Reference count of object

     INTEGER, DIMENSION(8) :: atime ! Access time        !    -- NOTE --
     INTEGER, DIMENSION(8) :: mtime ! Modification time  ! Returns an integer 
     INTEGER, DIMENSION(8) :: ctime ! Change time        ! array as specified 
     INTEGER, DIMENSION(8) :: btime ! Birth time         ! in Fortran intrinsic 
                                                         ! DATE_AND_TIME(VALUES)

     INTEGER(hsize_t) :: num_attrs  ! # of attributes attached to object

     TYPE(hdr_t) :: hdr

     TYPE(meta_size_t) :: meta_size
  END TYPE h5o_info_t

The struct H5O_info_t is defined in H5Opublic.h and described in the H5Oget_info function entry.

The link access property list, lapl_id, is not currently used; it should be passed in as H5P_DEFAULT.

  SUBROUTINE h5oget_info_by_name_f(loc_id, name, object_info, hdferr,  &
        lapl_id)

    INTEGER(HID_T)  , INTENT(IN)            :: loc_id
    CHARACTER(LEN=*), INTENT(IN)            :: name
    TYPE(h5o_info_t), INTENT(OUT), TARGET   :: object_info
    INTEGER         , INTENT(OUT)           :: hdferr
    INTEGER(HID_T)  , INTENT(IN) , OPTIONAL :: lapl_id

Inputs:

  loc_id      - File or group identifier specifying location of group 
                in which object is located.
  name        - Name of group, relative to loc_id.

Outputs:

  object_info - Buffer in which to return object information.
  hdferr      - Returns 0 if successful and -1 if fails.

Optional parameters:

  lapl_id     - Link access property list.

Related Fortran2003 Derived Type: h5o_info_t

  TYPE, BIND(C) :: space_t
     INTEGER(hsize_t) :: total ! Total space for storing object header in file
     INTEGER(hsize_t) :: meta  ! Space within header for object header metadata 
                               ! information
     INTEGER(hsize_t) :: mesg  ! Space within header for actual message 
                               ! information
     INTEGER(hsize_t) :: free  ! Free space within object header
  END TYPE space_t

  TYPE, BIND(C) :: mesg_t
     INTEGER(c_int64_t) :: present ! Flags to indicate presence of message type 
                                   ! in header 
     INTEGER(c_int64_t) :: shared  ! Flags to indicate message type is shared 
                                   ! in header
  END TYPE mesg_t
  
  TYPE, BIND(C) :: hdr_t
     INTEGER :: version ! Version number of header format in file
     INTEGER :: nmesgs  ! Number of object header messages
     INTEGER :: nchunks ! Number of object header chunks
     INTEGER :: flags   ! Object header status flags
     TYPE(space_t)  :: space   
     TYPE(mesg_t)   :: mesg
  END TYPE hdr_t

  ! Extra metadata storage for obj & attributes
  TYPE, BIND(C) :: H5_ih_info_t
     INTEGER(hsize_t) :: index_size ! btree and/or list
     INTEGER(hsize_t) :: heap_size
  END TYPE H5_ih_info_t

  TYPE, BIND(C) :: meta_size_t
     TYPE(H5_ih_info_t) :: obj  ! v1/v2 B-tree & local/fractal heap for 
                                ! groups, B-tree for chunked datasets
     TYPE(H5_ih_info_t) :: attr ! v2 B-tree & heap for attributes
  ENDTYPE meta_size_t
  
  TYPE, BIND(C) :: h5o_info_t
     INTEGER(C_LONG)  :: fileno     ! File number that object is located in
     INTEGER(haddr_t) :: addr       ! Object address in file  
     INTEGER(C_INT)   :: type       ! Basic object type (group, dataset, etc.) 
     INTEGER          :: rc         ! Reference count of object

     INTEGER, DIMENSION(8) :: atime ! Access time        !    -- NOTE --
     INTEGER, DIMENSION(8) :: mtime ! Modification time  ! Returns an integer 
     INTEGER, DIMENSION(8) :: ctime ! Change time        ! array as specified 
     INTEGER, DIMENSION(8) :: btime ! Birth time         ! in Fortran intrinsic 
                                                         ! DATE_AND_TIME(VALUES)

     INTEGER(hsize_t) :: num_attrs  ! # of attributes attached to object

     TYPE(hdr_t) :: hdr

     TYPE(meta_size_t) :: meta_size
  END TYPE h5o_info_t

An object’s reference count is the number of hard links in the file that point to that object. See the “Programming Model” section of the “HDF5 Groups” chapter in the HDF5 User’s Guide for a more complete discussion of reference counts.

If a user application needs to determine an object’s reference count, an H5Oget_info call is required; the reference count is returned in the rc field of the H5O_info_t struct.

Warning: This function must be used with care! Improper use can lead to inaccessible data, wasted space in the file, or file corruption.

  SUBROUTINE h5oincr_refcount_f(obj_id, hdferr)
    IMPLICIT NONE
    INTEGER(HID_T), INTENT(IN)  :: obj_id
    INTEGER       , INTENT(OUT) :: hdferr

Inputs:

  obj_id  - Object identifier.

Outputs:

  hdferr  - Returns 0 if successful and -1 if fails.

new_loc_id and new_name specify the location and name of the new link while object_id identifies the object that the link points to.

H5Olink is designed for two purposes:

	To create the first hard link to an object that has just been created with H5Dcreate_anon, H5Gcreate_anon, or H5Tcommit_anon.
	To add additional structure to an existing file so that, for example, an object can be shared among multiple groups.

lcpl and lapl are the link creation and access property lists associated with the new link.

    hid_t lcpl_id = H5Pcreate(H5P_LINK_CREATE);  
                                       /* Creates a link creation property
                                       * list (LCPL).                     */
    int status = H5Pset_create_intermediate_group(lcpl_id, TRUE);
                                       /* Sets "create missing intermediate
                                        * groups" property in that LCPL.  */
    hid_t gid  = H5Gcreate_anon(file_id, H5P_DEFAULT, H5P_DEFAULT);
                                       /* Creates a group without linking 
                                        * it into the file structure.     */
    status     = H5Olink(obj_id, file_id, "/A/B01/C", lcpl_id, H5P_DEFAULT);
                                       /* Links group into file structure.*/

Note that unless the object is intended to be temporary, the H5Olink call is mandatory if an object created with one of the H5*create_anon functions (or with H5Tcommit_anon) is to be retained in the file; without an H5Olink call, the object will not be linked into the HDF5 file structure and will be deleted when the file is closed.

  SUBROUTINE h5olink_f(object_id, new_loc_id, new_link_name,  &
            hdferr, lcpl_id, lapl_id)
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)  :: object_id
    INTEGER(HID_T)  , INTENT(IN)  :: new_loc_id
    CHARACTER(LEN=*), INTENT(IN)  :: new_link_name
    INTEGER         , INTENT(OUT) :: hdferr
    INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lcpl_id
    INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lapl_id

Inputs:

  object_id     - Object to be linked.
  new_loc_id    - File or group identifier specifying location at 
                  which object is to be linked.
  new_link_name - Name of link to be created, relative to new_loc_id.

Outputs:

  hdferr        - Returns 0 if successful and -1 if fails.

Optional parameters:

  lcpl_id       - Link creation property list identifier.
  lapl_id       - Link access property list identifier.

This function opens the object in the same manner as H5Gopen, H5Topen, and H5Dopen. However, H5Oopen does not require the type of object to be known beforehand. This can be useful with user-defined links, for instance, when only a path may be known. H5Oopen cannot be used to open a dataspace, attribute, property list, or file.

Once an object of unknown type has been opened with H5Oopen, the type of that object can be determined by means of an H5Iget_type call.

loc_id can be either a file or group identifier. name must be the path to that object relative to loc_id.

lapl_id is the link access property list associated with the link pointing to the object. If default link access properties are appropriate, this can be passed in as H5P_DEFAULT.

When it is no longer needed, the opened object should be closed with H5Oclose, H5Gclose, H5Tclose, or H5Dclose.

  SUBROUTINE h5oopen_f(loc_id, name, obj_id, hdferr, lapl_id)
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)  :: loc_id
    CHARACTER(LEN=*), INTENT(IN)  :: name
    INTEGER(HID_T)  , INTENT(OUT) :: obj_id
    INTEGER         , INTENT(OUT) :: hdferr
    INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lapl_id

Inputs:

  loc_id  - File or group identifier.
  name    - Path to the object, relative to loc_id.

Outputs:

  obj_id  - Object identifier for the opened object.
  hdferr  - Returns 0 if successful and -1 if fails.

Optional parameters:

  lapl_id - Access property list identifier for the 
            link pointing to the object.

loc_id can be either the file identifier or a group identifier in the file. In either case, the HDF5 Library uses the identifier only to identify the file.

The object’s address within the file, addr, is the byte offset of the first byte of the object header from the beginning of the HDF5 file space, i.e., from the beginning of the super block (see the “HDF5 Storage Model” section of the “The HDF5 Data Model and File Structure” chapter of the HDF5 User’ Guide).

addr can be obtained via either of two function calls. H5Gget_objinfo returns the object’s address in the objno field of the H5G_stat_t struct; H5Lget_info returns the address in the address field of the H5L_linkinfo_t struct.

Warning: This function must be used with care! Improper use can lead to inaccessible data, wasted space in the file, or file corruption. This function is dangerous if called on an invalid address. The risk can be safely overcome by retrieving the object address with H5Gget_objinfo or H5Lget_linkinfo immediately before calling H5Oopen_by_addr. The immediacy of the operation can be important; if time has elapsed and the object has been deleted from the file, the address will be invalid and file corruption can result.

 

The address of the HDF5 file on a physical device has no effect on H5Oopen_by_addr, nor does the use of any file driver. As stated above, the object address is its offset within the HDF5 file; HDF5’s file drivers will transparently map this to an address on a storage device.

  SUBROUTINE h5oopen_by_addr_f(loc_id, addr, obj_id, hdferr)
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)  :: loc_id
    INTEGER(HADDR_T), INTENT(IN)  :: addr
    INTEGER(HID_T)  , INTENT(OUT) :: obj_id
    INTEGER         , INTENT(OUT) :: hdferr

Inputs:

  loc_id - File or group identifier.
  addr   - Object's address in the file.

Outputs:

  obj_id - Object identifier for the opened object.
  hdferr - Returns 0 if successful and -1 if fails.

loc_id specifies a file or group. group_name specifies the group relative to loc_id in which the object can be found. If loc_id fully specifies the group in which the object resides, group_name can be a dot (.).

The specific object to be opened within the group is specified by index_type, order, and n as follows:

• index_type specifies the type of index by which objects are ordered. Valid index types include H5_INDEX_NAME, indexed by name, and H5_INDEX_CRT_ORDER, indexed by creation order.
• order specifies the order in which the links are to be referenced for the purposes of this function. Valid orders include H5_ITER_INC for increasing order, H5_ITER_DEC for decreasing order, and H5_ITER_NATIVE. Rather than implying a particular order, H5_ITER_NATIVE instructs the HDF5 Library to iterate through the objects in the fastest available order, i.e., in a natural order.
• n specifies the position of the object within the index. Note that this count is zero-based; 0 (zero) indicates that the function will return the value of the first object; if n is 5, the function will return the value of the sixth object; etc.

If lapl_id specifies the link access property list to be used in accessing the object.

An object opened with this function should be closed when it is no longer needed so that resource leaks will not develop. H5Oclose can be used to close groups, datasets, or committed datatypes.

  SUBROUTINE h5oopen_by_idx_f(loc_id, group_name, index_type, order, n, &
       obj_id, hdferr, lapl_id)
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)            :: loc_id
    CHARACTER(LEN=*), INTENT(IN)            :: group_name
    INTEGER         , INTENT(IN)            :: index_type
    INTEGER         , INTENT(IN)            :: order
    INTEGER(HSIZE_T), INTENT(IN)            :: n
    INTEGER(HID_T)  , INTENT(OUT)           :: obj_id
    INTEGER         , INTENT(OUT)           :: hdferr
    INTEGER(HID_T)  , INTENT(IN) , OPTIONAL :: lapl_id

Inputs:

  loc_id      - A file or group identifier.
  group_name  - Name of group, relative to loc_id, in which object is located.
  index_type  - Type of index by which objects are ordered.
  order       - Order of iteration within index, NOTE: zero-based.
  n           - Object to open.

Outputs:

  obj_id      - An object identifier for the opened object.
  hdferr      - Returns 0 if successful and -1 if fails.

Optional parameters:

  lapl_id     - Link access property list.

The target object is specified by an identifier, object_id.

If comment is the empty string or a null pointer, any existing comment message is removed from the object.

Comments should be relatively short, null-terminated, ASCII strings.

Comments can be attached to any object that has an object header. Datasets, groups, and committed (named) datatypes have object headers. Symbolic links do not have object headers.

If a comment is being added to an object attribute, this comment will be attached to the object to which the attribute belongs and not to the attribute itself.

  SUBROUTINE h5oset_comment_f(obj_id, comment, hdferr)
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)  :: obj_id
    CHARACTER(LEN=*), INTENT(IN)  :: comment
    INTEGER         , INTENT(OUT) :: hdferr

Inputs:

  obj_id    - Identifier of the target object.
  comment   - The new comment.

Outputs:

  hdferr    - Returns 0 if successful and -1 if fails.

The target object is specified by loc_id and name. loc_id can specify any object in the file. name can be one of the following:
  — The name of the object relative to loc_id
  — An absolute name of the object, starting from /, the file’s root group
  — A dot (.), if loc_id fully specifies the object

If comment is the empty string or a null pointer, any existing comment message is removed from the object.

Comments should be relatively short, null-terminated, ASCII strings.

Comments can be attached to any object that has an object header. Datasets, groups, and committed (named) datatypes have object headers. Symbolic links do not have object headers.

If a comment is being added to an object attribute, this comment will be attached to the object to which the attribute belongs and not to the attribute itself.

lapl_id contains a link access property list identifier. A link access property list can come into play when traversing links to access an object.

  SUBROUTINE h5oset_comment_by_name_f(loc_id, name, comment, hdferr, &
        lapl_id)
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)  :: loc_id
    CHARACTER(LEN=*), INTENT(IN)  :: name
    CHARACTER(LEN=*), INTENT(IN)  :: comment
    INTEGER         , INTENT(OUT) :: hdferr
    INTEGER(HID_T)  , INTENT(IN), OPTIONAL :: lapl_id

Inputs:

  loc_id   - Identifier of a file, group, dataset, or named datatype.
  name     - Name of the object whose comment is to be set or reset, 
              specified as a path relative to loc_id. 
  comment  - The new comment.

Outputs:

  hdferr   - Returns 0 if successful and -1 if fails.

Optional parameters:

  lapl_id  - Link access property list identifier.

If object_id is a group identifier, that group serves as the root of a recursive iteration. If object_id is a file identifier, that file’s root group serves as the root of the recursive iteration. If object_id is any other type of object, such as a dataset or named datatype, there is no iteration.

Two parameters are used to establish the iteration: index_type and order.

index_type specifies the index to be used. If the links in a group 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 unnecesary, so the iteration may begin more quickly. Valid values include the following:

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

Note that the index type passed in index_type is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alpha-numeric order by name, or name order. (Name order is the native order used by the HDF5 Library and is always available.)

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

The protoype of the callback function op is as follows (as defined in the source code file H5Opublic.h):

The parameters of this callback function have the following values or meanings:

	o_id	Object that serves as root of the iteration; same value as the H5Ovisit object_id parameter
	name	Name of object, relative to o_id, being examined at current step of the iteration
	object_info	H5O_info_t struct containing information regarding that object
	op_data	User-defined pointer to data required by the application in processing the object; a pass-through of the op_data pointer provided with the H5Ovisit_by_name function call

The H5O_info_t struct is defined in H5Opublic.h and described in the H5Oget_info function entry.

The return values from an operator are:

• Zero causes the visit iterator to continue, returning zero when all group members have been processed.
• A positive value causes the visit iterator to immediately return that positive value, indicating short-circuit success.
• A negative value causes the visit iterator to immediately return that value, indicating failure.

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

H5Lvisit and H5Ovisit are companion functions: one for examining and operating on links; the other for examining and operating on the objects that those links point to. Both functions ensure that by the time the function completes successfully, every link or object below the specified point in the file has been presented to the application for whatever processing the application requires.

If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

Examples of this kind of routine include callbacks such as H5Pset_elink_cb and H5Pset_type_conv_cb and functions such as H5Tconvert and H5Ewalk2.

Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.

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

  SUBROUTINE h5ovisit_f(object_id, index_type, order, op, op_data, &
            return_value, hdferr)
    INTEGER(HID_T), INTENT(IN) :: object_id
    INTEGER, INTENT(IN) :: index_type 
    INTEGER, INTENT(IN) :: order

    TYPE(C_FUNPTR):: op
    TYPE(C_PTR)   :: op_data
    INTEGER, INTENT(OUT) :: return_value
    INTEGER, INTENT(OUT) :: hdferr

Inputs:

  object_id  - Identifier of the object at which the recursive iteration 
                begins.
  index_type - Type of index; valid values include:
                H5_INDEX_NAME_F
                H5_INDEX_CRT_ORDER_F
  order      - Order in which index is traversed; valid values include:
                H5_ITER_DEC_F
                H5_ITER_INC_F
                H5_ITER_NATIVE_F
  op         - Callback function passing data regarding the group to the 
               calling application
  op_data    - User-defined pointer to data required by the application 
               for its processing of the group

Outputs:

  return_value - 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.
  hdferr       - Returns 0 if successful and -1 if fails.

The object serving as the root of the iteration is specified by the loc_id / object_name parameter pair. loc_id specifies a file or an object in a file; object_name specifies either an object in the file (with an absolute name based in the file’s root group) or an object name relative to loc_id. If loc_id fully specifies the object that is to serve as the root of the iteration, object_name should be '.' (a dot). (Note that when loc_id fully specifies the the object that is to serve as the root of the iteration, the user may wish to consider using H5Ovisit instead of H5Ovisit_by_name.)

Two parameters are used to establish the iteration: index_type and order.

index_type specifies the index to be used. If the links in a group 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 unnecesary, so the iteration may begin more quickly. Valid values include the following:

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

Note that the index type passed in index_type is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alpha-numeric order by name, or name order. (Name order is the native order used by the HDF5 Library and is always available.)

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

The op callback funtion and the effect of the callback function’s return value on the application are described in H5Ovisit.

The H5O_info_t struct is defined in H5Opublic.h and described in the H5Oget_info function entry.

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

lapl_id is a link access property list. In the general case, when default link access properties are acceptable, this can be passed in as H5P_DEFAULT. An example of a situation that requires a non-default link access property list is when the link is an external link; an external link may require that a link prefix be set in a link access property list (see H5Pset_elink_prefix).
 

H5Lvisit_by_name and H5Ovisit_by_name are companion functions: one for examining and operating on links; the other for examining and operating on the objects that those links point to. Both functions ensure that by the time the function completes successfully, every link or object below the specified point in the file has been presented to the application for whatever processing the application requires.

If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.

Examples of this kind of routine include callbacks such as H5Pset_elink_cb and H5Pset_type_conv_cb and functions such as H5Tconvert and H5Ewalk2.

Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.

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

  SUBROUTINE h5ovisit_by_name_f(loc_id, object_name, index_type, order, &
       op, op_data, return_value, hdferr, lapl_id)
    USE, INTRINSIC :: ISO_C_BINDING
    IMPLICIT NONE
    INTEGER(HID_T)  , INTENT(IN)             :: loc_id
    CHARACTER(LEN=*), INTENT(IN)             :: object_name
    INTEGER         , INTENT(IN)             :: index_type 
    INTEGER         , INTENT(IN)             :: order

    TYPE(C_FUNPTR)                           :: op
    TYPE(C_PTR)                              :: op_data
    INTEGER         , INTENT(OUT)            :: return_value
    INTEGER         , INTENT(OUT)            :: hdferr
    INTEGER(HID_T)  , INTENT(IN) , OPTIONAL  :: lapl_id

Inputs:

  loc_id      - Identifier of a file or group.
  object_name - Name of the object, generally relative to loc_id, that will 
                serve as root of the iteration 
  index_type  - Type of index; valid values include:
                 H5_INDEX_NAME_F
                 H5_INDEX_CRT_ORDER_F
  order       - Order in which index is traversed; valid values include:
                 H5_ITER_DEC_F
                 H5_ITER_INC_F
                 H5_ITER_NATIVE_F
  op          - Callback function passing data regarding the group to the 
                calling application
  op_data     - User-defined pointer to data required by the application for 
                its processing of the group

Outputs:

  return_value - 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.
  hdferr       - Returns 0 if successful and -1 if fails

Optional parameters:

  lapl_id      - Link access property list identifier.

After searching the list of suggested committed datatype paths, H5Ocopy will invoke this callback before searching all committed datatypes in the destination file. This allows a user application to add a customized step to the search process. The callback function is set with H5Pset_mcdt_search_cb and the search process is described in H5Padd_merge_committed_dtype_path.

Valid return values from this callback function are as follows (defined in the enumerated datatype H5O_mcdt_search_ret_t in H5Opublic.h):

H5O_MCDT_SEARCH_ERROR		Aborts H5Ocopy.
H5O_MCDT_SEARCH_CONT		Continues the global search of all committed datatypes in the destination file.
H5O_MCDT_SEARCH_STOP		Stops the search, but continues copying.