Page tree

The license could not be verified: License Certificate has expired!

 

JAVA

FORTRAN

C++

C

 

Link

H5L_GET_NAME_BY_IDX

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

Procedure:

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

Signature:

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)
  IMPLICIT NONE
  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
    
  INTEGER(HSIZE_T), INTENT(IN) :: n   
                    ! 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
  INTEGER, INTENT(OUT) :: cset 
                    ! 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
  INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lapl_id  
                    ! Link access property list
END SUBROUTINE h5lget_info_by_idx_f

Parameters:
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_INDEX_NAME 
         H5_INDEX_CRT_ORDER
H5_iter_order_t orderIN: Order within field or index; valid values include: 
         H5_ITER_DEC 
         H5_ITER_INC 
         H5_ITER_NATIVE
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

Description:

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:

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

Example:

History:
Release    Change
1.8.0Function introduced in this release.

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