Page tree









Retrieves name of the nth link in a group, according to the order within a specified field or index


H5L_GET_NAME_BY_IDX(loc_id, group_name, index_field, order, n, name, size, lapl_id)


ssize_t H5Lget_name_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, char *name, size_t size, hid_t lapl_id )

SUBROUTINE h5lget_info_by_idx_f(loc_id, group_name, index_field, order, n, &
     f_corder_valid, corder, cset, data_size, hdferr, lapl_id)
  INTEGER(HID_T), INTENT(IN) :: loc_id  
                    ! File/group identifier specifying location of subject group
  CHARACTER(LEN=*), INTENT(IN) :: group_name 
                    ! Name of subject group
  INTEGER, INTENT(IN) :: index_field  
                    ! Index or 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
                    ! Attribute’s position in index
  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
                    ! Indicates the character set used for the attribute’s name
  INTEGER(HSIZE_T), INTENT(OUT) :: data_size   
                    ! Indicates the size, in the number of characters, of 
                    ! the attribute
  INTEGER, INTENT(OUT) :: hdferr       
                    ! Error code:
                    ! 0 on success and -1 on failure
                    ! Link access property list
END SUBROUTINE h5lget_info_by_idx_f

hid_t loc_idIN: Location identifier; may be a file, group, dataset, named datatype or attribute identifier
const char *group_name    IN: Name of subject group
H5_index_t index_fieldIN: Index or field which determines the order; valid values include: 
H5_iter_order_t orderIN: Order within field or index; valid values include: 
hsize_t nIN: Link for which to retrieve information
char *nameOUT: Buffer in which link value is returned
size_t sizeIN: Size in bytes of name
hid_t lapl_idIN: Link access property list


H5L_GET_NAME_BY_IDX retrieves the name of the nth link in a group, according to the specified order, order, within a specified field or index, index_field.

index_field specifies the index that is used. Valid values include the following:

H5_INDEX_NAMEAlpha-numeric index on name
H5_INDEX_CRT_ORDER    Index on creation order

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

H5_ITER_INCIncreasing order
H5_ITER_DECDecreasing order
H5_ITER_NATIVE    Fastest available order

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

The size in bytes of name is specified in size. If size is unknown, it can be determined via an initial H5L_GET_NAME_BY_IDX call with name set to NULL; the function's return value will be the size of the name.

Please note that in order for the specified index to correspond to the creation order index, order must be set to H5_ITER_INC or H5_ITER_DEC when calling H5L_GET_NAME_BY_IDX.

The index n passed to H5L_GET_NAME_BY_IDX is the index of the link within the link table, sorted according to order and index_field. If order is H5_ITER_NATIVE, then the link table is not sorted, and it does not matter what index_field is. Specifying H5_ITER_NATIVE does not guarantee any particular order, only that it remains consistent.


Returns the size of the link name if successful; otherwise returns a negative value. 


Release    Change
1.8.0Function introduced in this release.

--- Last Modified: July 01, 2020 | 10:47 AM