H5L_GET_INFO_BY_IDX1

Retrieves metadata for a link in a group, according to the order within a field or index

As of HDF5-1.12 this function has been deprecated in favor of the function H5L_GET_INFO_BY_IDX2 and the macro H5L_GET_INFO_BY_IDX.

Procedure:

H5L_GET_INFO_BY_IDX1 ( loc_id, group_name, idx_type, order, n, linfo, lapl_id )

Signature:

herr_t H5Lget_info_by_idx1 ( hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, 
                        hsize_t n, H5L_info1_t *linfo /*out*/, hid_t lapl_id )

SUBROUTINE h5lget_info_by_idx_f(loc_id, group_name, index_field, order, n, &
               link_type, f_corder_valid, corder, cset, address, val_size, &
               hdferr, lapl_id)
  IMPLICIT NONE
  INTEGER(HID_T), INTENT(IN) :: loc_id 
                             ! File or group identifier specifying 
                             ! location of subject group  
  CHARACTER(LEN=*), INTENT(IN) :: group_name 
                             ! Name of subject group
  INTEGER, INTENT(IN) :: index_field   
                             ! Index/field which determines the order
                             !   H5_INDEX_UNKNOWN_F   - Unknown index type
                             !   H5_INDEX_NAME_F      - Index on names
                             !   H5_INDEX_CRT_ORDER_F - Index on creation order
                             !   H5_INDEX_N_F	      - Number of indices defined
  INTEGER, INTENT(IN) :: order        
                             ! Order in which to iterate over index; 
                             ! Possible values are:
                             !    H5_ITER_UNKNOWN_F  - Unknown order
                             !    H5_ITER_INC_F      - Increasing order
                             !    H5_ITER_DEC_F      - Decreasing order
                             !    H5_ITER_NATIVE_F   - No particular order, 
                             !                         whatever is fastest
  INTEGER(HSIZE_T), INTENT(IN) :: n   
                             ! Attribute’s position in index
  INTEGER, INTENT(OUT) :: link_type 
                             ! Specifies the link class:
     	                     !   H5L_TYPE_HARD_F      - Hard link
     	                     !   H5L_TYPE_SOFT_F      - Soft link
     	                     !   H5L_TYPE_EXTERNAL_F  - External link
     	                     !   H5L_TYPE_ERROR_F     - Error
  LOGICAL, INTENT(OUT) :: f_corder_valid 
                             ! Indicates whether the creation order data is 
                             ! valid for this attribute 
  INTEGER, INTENT(OUT) :: corder 
                             ! Is a positive integer containing the creation 
                             ! order of the attribute
  INTEGER, INTENT(OUT) :: cset 
                             ! Indicates the character set used for the 
                             ! attribute’s name
  INTEGER(HADDR_T), INTENT(OUT) :: address  
                             ! If the link is a hard link, address specifies the 
                             ! file address that the link points to
  INTEGER(SIZE_T), INTENT(OUT) :: val_size 
                             ! If the link is a symbolic link, val_size will be 
                             ! the length of the link value, i.e. the length of 
                             ! the name of the pointed-to object with a null 
                             ! terminator.
  INTEGER, INTENT(OUT) :: hdferr       
                             ! Error code:
                             ! 0 on success and -1 on failure
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id  
                             ! Link access property list
END SUBROUTINE h5lget_info_by_idx_f

Parameters:

hid_t `loc_id`	IN: Location identifier of subject group; may be a file, group, dataset, named datatype or attribute identifier
const char *`group_name`	IN: Name of subject group
H5_index_t `idx_type`	IN: Index or field which determines the order
H5_iter_order_t `order`	IN: Order within field or index
hsize_t `n`	IN: Link for which to retrieve information
H5L_info1_t *`linfo`	OUT: Buffer in which link value is returned (See H5L_GET_INFO1 for information on H5L_info1_t.)
hid_t `lapl_id`	IN: Link access property list

Description:

H5L_GET_INFO_BY_IDX1 returns the metadata for a link in a group according to a specified field or index and a specified order.

The link for which information is to be returned is specified by idx_type, order, and n as follows:

idx_type specifies the field by which the links in group_name are ordered. The links may be indexed on this field, in which case operations seeking specific links are likely to complete more quickly.
order specifies the order in which the links are to be referenced for the purposes of this function.
n specifies the position of the subject link. Note that this count is zero-based; 0 (zero) indicates that the function will return the value of the first link; if n is 5, the function will return the value of the sixth link; etc.

For example, assume that idx_type, order, and n are H5_INDEX_NAME, H5_ITER_DEC, and 5, respectively. H5_INDEX_NAME indicates that the links are accessed in alpha-numeric order by their names. H5_ITER_DEC specifies that the list be traversed in reverse order, or in decremented order. And 5 specifies that this call to the function will return the metadata for the 6th link (n + 1) from the end.

See H5L_ITERATE1 for a list of valid values and further discussion regarding idx_type and order.

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

Returns:

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

Example:

History:

Release	Change
1.12.0	Function was renamed to H5L_GET_INDEX_BY_IDX1 and deprecated.
1.8.0	Function introduced in this release.
1.8.2	Fortran subroutine added in this release.
1.8.4	Fortran subroutine syntax changed in this release.

--- Last Modified: February 13, 2020 | 03:41 PM

Page tree

H5L_GET_INFO_BY_IDX1

Procedure:

Signature:

Parameters:

Description:

Returns:

Example:

History:

The HDF Group

Site

Resources

Connect