Last modified: 11 November 2009
Name: H5Lget_info_by_idx
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` )

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

Description:
  `H5Lget_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_field`, `order`, 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_field`, `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 `H5Literate` 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 (.).

Parameters:

  hid_t `loc_id` | IN: File or group identifier specifying location of subject group
  const char *`group_name` | IN: Name of subject group
  H5_index_t `index_field` | 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_info_t *`link_val` | OUT: Buffer in which link value is returned
  hid_t `lapl_id` | IN: Link access property list

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

Fortran90 Interface: h5lget_info_by_idx_f

      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

History:

  Release | C
  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.