3.7 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 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 storage.

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 storage owned by that actor contains at least one message describing a storage failure. Use the function qsmm_get_actor_storage to get the handle of storage owned by the small actor.

If an Actor API function returns error code QSMM_ERR_STORAGE, and the actor is the large one, then failed storage can be the storage of that actor itself or the storage of an associated small actor representing the environment state identification engine or the storage 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 is non-empty and contains a message describing the failure.

The following function returns the handle of failed storage 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_env(actpair)))) return storage;
    if ((storage=get_err_storage(qsmm_get_actpair_actor_opt(actpair)))) return storage;
    return 0;
}