A multinode model can have an error handler assigned to it.
The error handler is a function called in the case of a failure in any QSMM API function that takes an argument of qsmm_t type and can return an error code of int type.
The default error handler of a multinode model prints information on an occurred error to stderr and calls exit(2).
The output consists of the name of that default error handler function followed by an indented description of an error as object content in JSON format.
If a multinode model does not have an error handler assigned (including the default error handler), or an error handler assigned to the multinode model does not terminate program execution and returns, a failed API function returns a corresponding error code.
Use the following functions to query or set an error handler for a multinode model.
void qsmm_get_err_handler (qsmm_t model, qsmm_err_handler_func_t *func_p, void **param_pp) ¶This function retrieves information on an error handler assigned to a multinode model.
If func_p is not NULL, the function sets *func_p to the pointer to the error handler function or to NULL if the model does not have an error handler function assigned.
If param_pp is not NULL, the function sets *param_pp to the user parameter of that error handler function.
void qsmm_set_err_handler (qsmm_t model, qsmm_err_handler_func_t func, void *paramp) ¶This function assigns an error handler to a multinode model.
The argument func specifies an error handler function.
The argument paramp specifies the user parameter of the error handler function.
If func is NULL, the model does not use an error handler.
An error handler function receives extended information on some types of errors. The header file err.h included in qsmm.h contains a declaration for the type of an error handler function. The Side API also uses that type for the error handler of an interaction side (see Error Handling, for more information).
This is a type of an error handler function pointer with the following declaration:
typedef void
(*qsmm_err_handler_func_t)(
void *rez1,
struct qsmm_except_s *except_p,
void *paramp
);
The argument except_p passes information on an occurred error. The argument paramp is a user parameter specified when setting the error handler function for a multinode model. You should not access the reserved argument rez1.
The description of a structure containing information on an occurred error is below. The header file err.h contains the structure declaration.
This structure is for passing information about an occurred error to an error handler function. The structure contains the following fields.
const char * func_name ¶The name of a QSMM library function where the error occurred. That name might be the name of an internal library function (i.e. not an API function).
int code ¶An error code to return by a failed QSMM API function after returning from the error handler function.
union qsmm_except_u ee ¶Extended information about the occurred error interpreted depending on the field code of this structure.
A list of error codes with extended error information always provided in this field is in the description of qsmm_except_u union.
The description of a union containing extended error information depending on an error code is below. The header file err.h contains the union declaration.
This union contains fields corresponding to error codes that can have associated extended error information.
char * noic ¶Extended information for error code QSMM_ERR_NOIC.
The error code description is “instruction class set is empty.”
This field contains the name of an instruction class set without instruction classes.
int callback ¶Extended information for error code QSMM_ERR_CALLBACK.
The error code description is “callback function reported an error.”
This field contains an error code returned by a callback function.
qsmm_sig_t noprof ¶Extended information for error code QSMM_ERR_NOPROF.
The error code description is “node has no probability profile specified.”
This field contains the identifier of a node without a probability profile specified.
qsmm_sig_t violnode ¶Extended information for error code QSMM_ERR_VIOLNODE.
The error code description is “change violates the parameters of an already created node.”
This field contains the identifier of a node that prevents making a change because it would violate node parameters.
qsmm_sig_t mnode ¶Extended information for error code QSMM_ERR_MNODE.
The error code description is “too many nodes.”
This field contains the maximum allowed number of nodes.
qsmm_mehcall_t stackovr ¶Extended information for error code QSMM_ERR_STACKOVR.
The error code description is “stack overflow.”
This field refers to the parameters of a model event handler call.
They include stack content.
qsmm_msglist_t prg ¶Extended information for error code QSMM_ERR_PRG.
The error code description is “invalid program.”
This field contains a message list that hands over information on errors in an assembler program.
qsmm_storage_t storage ¶Extended information for error code QSMM_ERR_STORAGE.
The error code description is “storage failure.”
This field refers to failed storage.
struct qsmm_except_notfound_s notfound ¶Extended information for error code QSMM_ERR_NOTFOUND.
The error code description is “entity not found.”
struct qsmm_except_type_s type ¶Extended information for error code QSMM_ERR_TYPE.
The error code description is “invalid entity type.”
struct qsmm_except_exist_s exist ¶Extended information for error code QSMM_ERR_EXIST.
The error code description is “entity already exists.”
struct qsmm_except_outcome_s outcome ¶Extended information for error code QSMM_ERR_OUTCOME.
The error code description is “invalid instruction outcome.”
struct qsmm_except_evthndlr_s evthndlr ¶Extended information for error code QSMM_ERR_EVTHNDLR.
The error code description is “event handler function reported an error.”
struct qsmm_except_noeqclas_s noeqclas ¶Extended information for error code QSMM_ERR_NOEQCLAS.
The error code description is “node classes are different.”
struct qsmm_except_profsrcp_s profsrcp ¶Extended information for error code QSMM_ERR_PROFSRCP.
The error code description is “node is a probability profile source for other nodes.”
struct qsmm_except_profsrcu_s profsrcu ¶Extended information for error code QSMM_ERR_PROFSRCU.
The error code description is “node is a user of a source probability profile provided by another node.”
struct qsmm_except_psumgt1_s psumgt1 ¶Extended information for error code QSMM_ERR_PSUMGT1.
The error code description is “sum of probabilities would exceed 1.”
Use the following function to dump the content of qsmm_except_s structure to a stream in JSON format.
void qsmm_except_dump (void *rez1, int indent, const struct qsmm_except_s *except_p, FILE *filep) ¶This function dumps error information in *except_p to a stream filep in JSON format as object content. The argument indent must be non-negative. It specifies left indent—the number of spaces to print at the beginning of each line of output. You should pass 0 for the reserved argument rez1.
The rest of this section contains descriptions of structures that are the fields of qsmm_except_u union.
The header file err.h contains the structure declarations.
Some of them have fields of enum qsmm_lref_e, struct qsmm_gref_s, and struct qsmm_instr_class_s types.
See Entity References, for descriptions of the types.
This structure provides extended information for error code QSMM_ERR_NOTFOUND.
The error code description is “entity not found.”
The structure contains the following field.
struct qsmm_gref_s gref ¶A reference to a not found entity.
This structure provides extended information for error code QSMM_ERR_TYPE.
The error code description is “invalid entity type.”
The structure contains the following fields.
enum qsmm_lref_e type_required ¶A required type for the entity.
struct qsmm_gref_s gref ¶A reference to the entity that has an invalid type.
This structure provides extended information for error code QSMM_ERR_EXIST.
The error code description is “entity already exists.”
The structure contains the following field.
struct qsmm_gref_s gref ¶A reference to an already existing entity.
This structure provides extended information for error code QSMM_ERR_OUTCOME.
The error code description is “invalid instruction outcome.”
The structure contains the following fields.
qsmm_sig_t node ¶The identifier of a node invoked the assembler instruction.
qsmm_sig_t outcome ¶An invalid instruction outcome.
If an event handler did not set an instruction outcome when it was necessary to do so, this field is equal to QSMM_SIG_INVALID.
qsmm_sig_t noutcome ¶The number of outcomes of the assembler instruction.
qsmm_t model ¶A multinode model containing a node invoked the assembler instruction.
qsmm_mehcall_t mehcall ¶The parameters of a model event handler call that should have set a valid instruction outcome.
struct qsmm_instr_class_s instr_class ¶The descriptor of an instruction class for the assembler instruction.
This structure provides extended information for error code QSMM_ERR_EVTHNDLR.
The error code description is “event handler function reported an error.”
The structure contains the following fields.
int rc ¶A negative return value of the event handler function.
int evt ¶An event type passed to the event handler function—one of constants defined by the QSMM_EVT_* macros.
qsmm_mehcall_t mehcall ¶The parameters of the event handler function call.
struct qsmm_gref_s gref ¶A reference to an entity emitting events processed by the event handler function.
This structure provides extended information for error code QSMM_ERR_NOEQCLAS.
The error code description is “node classes are different.”
The structure contains the following fields.
char * node_class_name_1 ¶The name of the first node class, that is, the first instruction class set.
char * node_class_name_2 ¶The name of the second node class, that is, the second instruction class set.
qsmm_sig_t node1 ¶The identifier of a node belonging to the first node class.
If that identifier is QSMM_SIG_INVALID, this parameter is not applicable.
qsmm_sig_t node2 ¶The identifier of a node belonging to the second node class.
If that identifier is QSMM_SIG_INVALID, this parameter is not applicable.
qsmm_t model ¶A multinode model containing the node classes.
This structure provides extended information for error code QSMM_ERR_PROFSRCP.
The error code description is “node is a probability profile source for other nodes.”
The structure contains the following fields.
qsmm_sig_t node_provider ¶The identifier of a node acting as a probability profile source for other nodes.
qsmm_sig_t nnode_user ¶The number of nodes acting as probability profile users.
qsmm_t model ¶A multinode model containing the nodes.
This structure provides extended information for error code QSMM_ERR_PROFSRCU.
The error code description is “node is a user of a source probability profile provided by another node.”
The structure contains the following fields.
qsmm_sig_t node_provider ¶The identifier of a node acting as a probability profile source.
qsmm_sig_t node_user ¶The identifier of a node acting as a probability profile user.
qsmm_t model ¶A multinode model containing the nodes.
This structure provides extended information for error code QSMM_ERR_PSUMGT1.
The error code description is “sum of probabilities would exceed 1.”
The structure contains the following fields.
char * var_name ¶The name of a controlled probability variable with an assigned value.
This assignment causes the sum of probabilities of case instructions in a choice instruction block to exceed 1.
qsmm_sig_t node ¶The identifier of a node containing a state corresponding to a choice instruction block.
qsmm_sig_t state ¶The index of a node state corresponding to a choice instruction block.
qsmm_t model ¶A multinode model containing the node.