Previous: Object Handles, Up: Introduction

1.13 Error Handling

If a QSMM API function returns a value of type int, then it can be an error code. All error codes are negative. Zero and positive return values may indicate additional information regarding successful completion of a function call. If a QSMM API function does not return a value of type int, it may not return an error code, because error condition cannot arise within the function, or at least this was assumed when the function had first appeared in the QSMM API.

If not otherwise noted in the description of an error code of a QSMM API function, returning the error code by the function means the system state remains unchanged, i.e. just after calling the function the system is in the same state as just before calling the function.

To get the textual description of an error code, the following API function from the qsmm.h header can be used.

— Function: const char * qsmm_err_str (int err)

This function returns the textual description of QSMM API error code err. For invalid error codes, string "(invalid error code)" is returned.

When you use the QSMM package for creating multinode models, you can associate an error handler with a model. In this case, the error handler may receive extended information on an error occurred. The use of the error handler may eliminate the need to check return codes of calls to QSMM API functions, which take argument qsmm_t, to determine whether any of these functions has failed. See Error Handling for a Multinode Model, for information on using error handlers.