Page tree

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

 

JAVA

FORTRAN

C++

C

 

Link

H5L_GET_INFO_BY_IDX

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

Procedure:

H5L_GET_INFO_BY_IDX(loc_id, group_name, index_field, order, n, link_val, lapl_id)

Signature:

herr_t H5Lget_info_by_idx( hid_t loc_id, const char *group_name, H5_index_t index_field, H5_iter_order_t order, hsize_t n, H5L_info_t *link_val, 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_idIN: 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 index_fieldIN: Index or field which determines the order
H5_iter_order_t orderIN: Order within field or index
hsize_t nIN: Link for which to retrieve information
H5L_info_t *link_valOUT: Buffer in which link value is returned
hid_t lapl_idIN: Link access property list

Description:

H5L_GET_INFO_BY_IDX 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 index_fieldorder, and n as follows:

  • index_field 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 index_fieldorder, and n are H5_INDEX_NAMEH5_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_ITERATE for a list of valid values and further discussion regarding index_field 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:

Coming Soon!

History:
Release    C
1.8.0Function introduced in this release.
1.8.2Fortran subroutine added in this release.
1.8.4Fortran subroutine syntax changed in this release.

--- Last Modified: May 02, 2018 | 04:01 PM