- Created by Barbara Jones, last modified on Feb 19, 2020
H5L_ITERATE2
Iterates through links in a group
Procedure:
H5L_ITERATE2 ( group_id, idx_type, order, idx_p, op, op_data )
Signature:
herr_t H5Literate2 ( hid_t group_id, H5_index_t idx_type, H5_iter_order_t order,
hsize_t *idx_p, H5L_iterate2_t op, void *op_data )
SUBROUTINE h5literate_f(group,index_type, order, position,
op, ctx, return_value, hdferr)
INTEGER(HID_T) , INTENT(IN) :: group
INTEGER , INTENT(IN) :: index_type
INTEGER , INTENT(IN) :: order
INTEGER(HSIZE_T), INTENT(INOUT) :: position
TYPE(C_FUNPTR) , INTENT(IN) :: op
TYPE(C_PTR) , INTENT(IN) :: ctx
INTEGER , INTENT(OUT) :: return_value
INTEGER , INTENT(OUT) :: hdferr
Parameters:
Name | Mode | Kind | Description |
---|---|---|---|
group_id | IN | handle | File or group identifier |
idx_type | IN | choice | Index for iteration order |
order | IN | choice | Traversal order |
idx_p | INOUT | integer | Iteration position |
op | IN | delegate | User-defined operator |
op_data | INOUT | opaque | User-supplied context |
Description:
H5L_ITERATE2 iterates through the links in a file or group, group_id
, in the order of the specified index, idx_type
, using a user-defined callback routine op
. H5L_ITERATE2 does not recursively follow links into subgroups of the specified group.
Three parameters are used to manage progress of the iteration: idx_type
, order
, and idx_p
.
idx_type
specifies the index to be used. If the links have not been indexed by the index type, they will first be sorted by that index then the iteration will begin; if the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly.
The choices for idx_type
are:
Name | Meaning |
---|---|
H5_INDEX_NAME | Lexicographic order |
H5_INDEX_CRT_ORDER | Creation order |
order
specifies the order in which objects are to be inspected along the index idx_type
. The choices for order
are:
Name | Meaning |
---|---|
H5_ITER_INC | Increasing order |
H5_ITER_DEC | Decreasing order |
H5_ITER_NATIVE | Fastest order |
idx_p
tracks the iteration and allows an iteration to be resumed if it was stopped before all members were processed. It is passed in by the application with a starting point and returned by the library with the point at which the iteration stopped.
op_data
is a user-defined pointer to the data required to process links in the course of the iteration. This pointer is passed back to each step of the iteration in the op
callback function’s op_data
parameter.
op
is invoked for each link encounter:
Signature:
herr_t (*H5L_iterate2_t)
(
hid_t group,
const char* name,
const H5L_info2_t* info,
void* op_data
)
Info:
typedef struct {
H5L_type_t type; /* Type of link */
hbool_t corder_valid; /* Indicate if creation order is valid */
int64_t corder; /* Creation order */
H5T_cset_t cset; /* Character set of link name */
union {
H5O_token_t token; /* Token of location that hard link points to */
size_t val_size; /* Size of a soft link or UD link value */
} u;
} H5L_info2_t;
typedef enum {
H5L_TYPE_ERROR = (-1), /* Invalid link type id */
H5L_TYPE_HARD = 0, /* Hard link id */
H5L_TYPE_SOFT = 1, /* Soft link id */
H5L_TYPE_EXTERNAL = 64, /* External link id */
H5L_TYPE_MAX = 255 /* Maximum link type id */
} H5L_type_t;
/*
* Character set to use for text strings. Do not change these values since
* they appear in HDF5 files!
*/
typedef enum H5T_cset_t {
H5T_CSET_ERROR = -1, /*error */
H5T_CSET_ASCII = 0, /*US ASCII */
H5T_CSET_UTF8 = 1, /*UTF-8 Unicode encoding */
H5T_CSET_RESERVED_2 = 2, /*reserved for later use */
H5T_CSET_RESERVED_3 = 3, /*reserved for later use */
H5T_CSET_RESERVED_4 = 4, /*reserved for later use */
H5T_CSET_RESERVED_5 = 5, /*reserved for later use */
H5T_CSET_RESERVED_6 = 6, /*reserved for later use */
H5T_CSET_RESERVED_7 = 7, /*reserved for later use */
H5T_CSET_RESERVED_8 = 8, /*reserved for later use */
H5T_CSET_RESERVED_9 = 9, /*reserved for later use */
H5T_CSET_RESERVED_10 = 10, /*reserved for later use */
H5T_CSET_RESERVED_11 = 11, /*reserved for later use */
H5T_CSET_RESERVED_12 = 12, /*reserved for later use */
H5T_CSET_RESERVED_13 = 13, /*reserved for later use */
H5T_CSET_RESERVED_14 = 14, /*reserved for later use */
H5T_CSET_RESERVED_15 = 15 /*reserved for later use */
} H5T_cset_t;
/* Type for object tokens */
typedef struct H5O_token_t {
uint8_t __data[H5O_MAX_TOKEN_SIZE];
} H5O_token_t;
Returns:
Return value | Meaning |
---|---|
0 | Continue iteration |
> 0 | Stop iteration; successful termination |
< 0 | Stop iteration; abnormal termination |
op_data
is passed to and from each iteration and can be used to supply or aggregate information across iterations.
The behavior of H5L_ITERATE2 is undefined if the link membership of group_id
changes during the iteration. This does not limit the ability to change link destinations while iterating, but caution is advised.
For recursive behavior, see the following the H5L_VISIT functions.
Returns:
On success, returns the return value of the first operator that returns a positive value, or zero if all members were processed with no operator returning non-zero.
On failure, returns a negative value if something goes wrong within the library, or the first negative value returned by an operator.
Example:
Include Bitbucket Server for Confluence: An error occured
Connection to Bitbucket Server could not be established. Verify that you have properly configured the Bitbucket Server application link for your Confluence space and that your Bitbucket Server instance is up and running. Error details: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
Include Bitbucket Server for Confluence: An error occured
Connection to Bitbucket Server could not be established. Verify that you have properly configured the Bitbucket Server application link for your Confluence space and that your Bitbucket Server instance is up and running. Error details: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested targetHistory:
Release | Change |
---|---|
1.12.0 | Function was introduced in this release. |
--- Last Modified: February 19, 2020 | 10:46 AM