---

4.4.4 Enumerating Entities ¶

Local entity references of QSMM_LREF_INSTR_META_CLASS and QSMM_LREF_INSTR_CLASS_SET types identify instruction meta-classes and instruction class sets in a multinode model by names. The names are unique in a model context making it possible to use them as names of event handler functions of instruction meta-classes and instruction class sets by default.

Use the following function to enumerate instruction meta-classes, instruction class sets, or nodes in a multinode model.

Function: int qsmm_enum_ent (qsmm_t model, enum qsmm_lref_e ent_type, qsmm_enum_ent_callback_func_t callback_func, void *paramp) ¶

This function enumerates all entities of ent_type type stored in a multinode model. The process of enumeration is repeated calling a callback function callback_func receiving the type of a local entity reference, a local entity identifier, and a user parameter paramp. If the callback function returns a positive value, qsmm_enum_ent continues enumeration. If the callback function returns zero, qsmm_enum_ent terminates enumeration and reports success. If the callback function returns a negative value, qsmm_enum_ent terminates enumeration and reports failure.

The function returns a non-negative value on success or a negative error code on failure. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

The argument ent_type is not QSMM_LREF_INSTR_META_CLASS, QSMM_LREF_INSTR_CLASS_SET, and QSMM_LREF_NODE.

QSMM_ERR_CALLBACK

The callback function reported an error.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

The type of a pointer to a callback function called for every enumerated entity is below.

Data type: qsmm_enum_ent_callback_func_t ¶

This is a type of a callback function pointer with the following declaration:

typedef int
(*qsmm_enum_ent_callback_func_t)(
    qsmm_t model,
    enum qsmm_lref_e lref_type,
    const union qsmm_lref_u *lref_p,
    void *paramp
);

An enumeration function calls the callback function for every enumerated entity of a multinode model. The argument lref_type specifies enumerated entity type as local entity reference type. The argument lref_p specifies an entity identifier as a local entity reference identifier. The argument paramp is a user parameter passed to the enumeration function.

The callback function shall return a positive value to continue the process of enumeration, zero to terminate the process of enumeration, or a negative value on error.

The function qsmm_enum_var_prob uses a callback function of qsmm_enum_ent_callback_func_t type for enumerating controlled probability variables of an instruction class set. The function qsmm_enum_var_prob_out uses this callback function for enumerating output probability variables of a node.

Use the following function to query the type of an entity by its name.

Function: enum qsmm_lref_e qsmm_get_ent_type_by_name (qsmm_t model, const char *ent_name) ¶

This function returns the type of a local entity reference for an entity named ent_name stored in a multinode model. The function only supports local entity references of QSMM_LREF_INSTR_META_CLASS and QSMM_LREF_INSTR_CLASS_SET types. If the entity does not exist or is not an instruction meta-class and instruction class set, the function returns QSMM_LREF_INVALID.