3.6 Getting the Reason of a Storage Failure ¶

When a Storage API function returns error code QSMM_ERR_STORAGE, the function clears a storage message list and adds to it at least one error message describing a failure.

A handle of qsmm_msglist_t type represents a message list. See Messages and Message Lists, for how to work with message lists. Use the following function to obtain a message list associated with a storage instance.

Function: qsmm_msglist_t qsmm_get_storage_msglist (qsmm_storage_t storage) ¶

This function returns the handle of a message list associated with storage. The function never returns NULL.

To dump to stderr the message list of storage in an application program with an executable named prg_name, use lines of code like these:

const int rc=qsmm_msglist_dump(qsmm_get_storage_msglist(storage),
                               prg_name, 0, 0, stderr);
if (rc<0) REPORT_ERROR(rc);

If an Actor API function returns error code QSMM_ERR_STORAGE, and the actor is the small one, the message list of a storage instance owned by the actor contains at least one error message describing a storage failure. Use the function qsmm_get_actor_storage to get the handle of a storage instance owned by the small actor.

If an Actor API function returns error code QSMM_ERR_STORAGE, and the actor is the large one, then a failed storage instance can be the storage instance of the actor itself or the storage instance of an associated small actor representing the environment state identification engine or the storage instance of an associated small actor representing the instruction emitting engine. Provided that all storage message lists were empty before calling the Actor API function, one of them would be non-empty and would contain a message describing the failure.

The following function returns the handle of failed storage instance of a small or large actor or NULL if the storage message lists are empty:

qsmm_storage_t
get_err_storage(
    qsmm_actor_t actor
) {
    qsmm_storage_t storage=qsmm_get_actor_storage(actor);
    if (qsmm_get_msglist_sz(qsmm_get_storage_msglist(storage))) return storage;
    const qsmm_t qsmm_large=qsmm_get_actor_large_model(actor);
    if (!qsmm_large) return 0;
    const qsmm_actpair_t actpair=qsmm_get_actpair(qsmm_large);
    if ((storage=
         get_err_storage(qsmm_get_actpair_actor(actpair,QSMM_ENGINE_ENV))))
        return storage;
    if ((storage=
         get_err_storage(qsmm_get_actpair_actor(actpair,QSMM_ENGINE_IEE))))
        return storage;
    return 0;
}