- Created by Barbara Jones, last modified on Feb 18, 2020
H5O_GET_INFO_BY_IDX1
Retrieves the metadata for an object, identifying the object by an index position
As of HDF5-1.12 this function has been deprecated in favor of the function H5O_GET_INFO_BY_IDX3 or the macro H5O_GET_INFO_BY_IDX.
Procedure:
H5O_GET_INFO_BY_IDX1 ( loc_id, group_name, idx_type, order, n, oinfo, lapl_id )
Signature:
herr_t H5Oget_info_by_idx1 ( hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n,
H5O_info1_t *oinfo, hid_t lapl_id )
SUBROUTINE h5oget_info_by_idx_f(loc_id, group_name, index_field, order, n, &
object_info, hdferr, lapl_id)
USE, INTRINSIC :: ISO_C_BINDING
IMPLICIT NONE
INTEGER(HID_T) , INTENT(IN) :: loc_id
CHARACTER(LEN=*), INTENT(IN) :: group_name
INTEGER , INTENT(IN) :: index_field
INTEGER , INTENT(IN) :: order
INTEGER(HSIZE_T), INTENT(IN) :: n
TYPE(h5o_info_t), INTENT(OUT), TARGET :: object_info
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T) , INTENT(IN) , OPTIONAL :: lapl_idRelated Fortran2003 Derived Type: h5o_info_t
TYPE, BIND(C) :: space_t
INTEGER(hsize_t) :: total ! Total space for storing object header in file
INTEGER(hsize_t) :: meta ! Space within header for object header metadata
! information
INTEGER(hsize_t) :: mesg ! Space within header for actual message
! information
INTEGER(hsize_t) :: free ! Free space within object header
END TYPE space_t
TYPE, BIND(C) :: mesg_t
INTEGER(c_int64_t) :: present ! Flags to indicate presence of message type
! in header
INTEGER(c_int64_t) :: shared ! Flags to indicate message type is shared
! in header
END TYPE mesg_t
TYPE, BIND(C) :: hdr_t
INTEGER :: version ! Version number of header format in file
INTEGER :: nmesgs ! Number of object header messages
INTEGER :: nchunks ! Number of object header chunks
INTEGER :: flags ! Object header status flags
TYPE(space_t) :: space
TYPE(mesg_t) :: mesg
END TYPE hdr_t
! Extra metadata storage for obj & attributes
TYPE, BIND(C) :: H5_ih_info_t
INTEGER(hsize_t) :: index_size ! btree and/or list
INTEGER(hsize_t) :: heap_size
END TYPE H5_ih_info_t
TYPE, BIND(C) :: meta_size_t
TYPE(H5_ih_info_t) :: obj ! v1/v2 B-tree & local/fractal heap for
! groups, B-tree for chunked datasets
TYPE(H5_ih_info_t) :: attr ! v2 B-tree & heap for attributes
ENDTYPE meta_size_t
TYPE, BIND(C) :: h5o_info_t
INTEGER(C_LONG) :: fileno ! File number that object is located in
INTEGER(haddr_t) :: addr ! Object address in file
INTEGER(C_INT) :: type ! Basic object type (group, dataset, etc.)
INTEGER :: rc ! Reference count of object
INTEGER, DIMENSION(8) :: atime ! Access time ! -- NOTE --
INTEGER, DIMENSION(8) :: mtime ! Modification time ! Returns an integer
INTEGER, DIMENSION(8) :: ctime ! Change time ! array as specified
INTEGER, DIMENSION(8) :: btime ! Birth time ! in Fortran intrinsic
! DATE_AND_TIME(VALUES)
INTEGER(hsize_t) :: num_attrs ! # of attributes attached to object
TYPE(hdr_t) :: hdr
TYPE(meta_size_t) :: meta_size
END TYPE h5o_info_t
Parameters:
hid_t loc_id | IN: Location identifier of object; may be a file, group, dataset, named datatype or attribute identifier |
const char *group_name | IN: Name of group in which object is located |
H5_index_t idx_type | IN: Index or field that determines the order |
H5_iter_order_t order | IN: Order within field or index |
hsize_t n | IN: Object for which information is to be returned |
H5O_info1_t *oinfo | OUT: Buffer in which to return object information |
hid_t lapl_id | IN: Link access property list (Not currently used; pass as NULL.) |
Description:
H5O_GET_INFO_BY_IDX1 retrieves the metadata describing an object in the struct oinfo, as specified by the location, loc_id, group name, group_name, the index by which objects in that group are tracked, idx_type, the order by which the index is to be traversed, order, and an object’s position n within that index . If loc_id fully specifies the group in which the object resides, group_name can be a dot (.).
idx_type is of type H5_index_t, defined in H5public.h as:
H5_INDEX_UNKNOWN = -1, /* Unknown index type */
H5_INDEX_NAME, /* Index on names */
H5_INDEX_CRT_ORDER, /* Index on creation order */
H5_INDEX_N /* Number of indices defined */
} H5_index_t;
/*
* Storage info struct used by H5O_info_t and H5F_info_t
*/
typedef struct H5_ih_info_t {
hsize_t index_size; /* btree and/or list */
order is of type H5_iter_order_t defined in H5public.h as:
H5_ITER_N /* Number of iteration orders */ } H5_iter_order_t; /* Iteration callback values */ /* (Actually, any positive value will cause the iterator to stop and pass back * that positive value to the function that called the iterator) */ #define H5_ITER_ERROR (-1)
oinfo, in which the object information is returned, is a struct of type H5O_info1_t:
/* Information struct for object */
/* (For H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx versions 1 & 2) */
typedef struct H5O_info1_t {
unsigned long fileno; /* File number that object is located in */
haddr_t addr; /* Object address in file */
H5O_type_t type; /* Basic object type (group, dataset, etc.) */
unsigned rc; /* Reference count of object */
time_t atime; /* Access time */
time_t mtime; /* Modification time */
time_t ctime; /* Change time */
time_t btime; /* Birth time */
hsize_t num_attrs; /* # of attributes attached to object */
H5O_hdr_info_t hdr; /* Object header information */
/* Extra metadata storage for obj & attributes */
struct {
H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
H5_ih_info_t attr; /* v2 B-tree & heap for attributes */
} meta_size;
The link access property list, lapl_id, is not currently used; it should be passed in as NULL.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
History:
| Release | Change |
|---|---|
| 1.10.5 | The macro H5O_GET_INFO_BY_IDX was removed and the function H5O_GET_INFO_BY_IDX was copied to H5O_GET_INFO_BY_IDX1. |
| 1.10.3 | Function H5O_GET_INFO_BY_IDX was copied to H5O_GET_INFO_BY_IDX1 and the macro H5O_GET_INFO_BY_IDX was created. |
| 1.8.11 | Fortran subroutine introduced in this release. |
| 1.8.0 | Function introduced in this release. |
--- Last Modified: February 18, 2020 | 12:28 PM