- Created by Mike McGreevy, last modified by Barbara Jones on Jul 01, 2020
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_id | IN: 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_field | IN: Index or field which determines the order; valid values include: H5_INDEX_NAME H5_INDEX_CRT_ORDER |
H5_iter_order_t order | IN: Order within field or index; valid values include: H5_ITER_DEC H5_ITER_INC H5_ITER_NATIVE |
hsize_t n | IN: Link for which to retrieve information |
char *name | OUT: Buffer in which link value is returned |
size_t size | IN: Size in bytes of name |
hid_t lapl_id | IN: 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_NAME | Alpha-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_INC | Increasing order |
H5_ITER_DEC | Decreasing 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.0 | Function introduced in this release. |
--- Last Modified: July 01, 2020 | 10:47 AM