An Important Word (and a Warning) About Error Conditions

Now that you know everything there is need to know about DevKit input and output, it's time to discuss DevKit command functions in detail. But first, we need to have a brief but very important discussion of the way in which DevKit commands return error-related information.

As you'll see from the command function prototypes, all DevKit command functions return an error handle of type dvkerr_t. You can declare variables of this type statically, and use them as follows:

 

    {
        dvkerr_t err;
        lpar_t erritem;
        /* ... */
        err = lkt_dbsearch( /* parameters */ );
        if (DVKERR(err)) {
                fprintf(stderr, "dbsearch returned error %d (%s)\n",
                        DVKERR(err), dvkerr_get_string(err));
                if ((erritem = dvkerr_get_item(err))) {
                        lpar_fprintf(stderr, erritem, -1);
                }
                dvkerr_clear(err);
        }
        /* ... */
        err = lkt_dbdelete( /* parameter */ );
        if (DVKERR(err)) {
                fprintf(stderr, "dbdelete returned error %d (%s)\n",
                        DVKERR(err), dvkerr_get_string(err));
                if ((erritem = dvkerr_get_item(err))) {
                        lpar_fprintf(stderr, erritem, -1);
                }
                dvkerr_clear(err);
        }
        /* ... */
    }

 

Note the static declaration of err in this example and its assignment to the return value of two DevKit command functions.

Note: You can also allocate an error handle dynamically, but you are then responsible for eventually freeing the storage.

 

As the example shows, an error handle can be reused after being cleared with the function dvkerr_clear.

When a DevKit command returns, the error handle must be tested with the macro DVKERR, which returns a nonnegative integer error code.

Note: All error codes returnable by DevKit commands begin with the prefix DVK_ERR_, and are defined in the header file devkit.h. See your copy of devkit.h for a complete list of error codes, and their general meanings.

 

The zero code (DVK_OK) is reserved for successful command termination, thus, the first invocation of DVKERR in our example works as a true/false test: was there an error, or not. If there was an error, our example prints the error code, and then an explanatory string which is the return value of the function dvkerr_get_string.

The string returned by dvkerr_get_string is a static string explaining the general nature of the error type. To supply you with as much useful information as possible, an error item might also be returned in the error handle. This error item (if it exists) is a copy of the lpar that caused or occasioned the error: an lpar with an illegal or out-of-range value, a record containing an empty searchable text attribute, and so on.

Since the error item is a dynamically allocated object, you must call the function dvkerr_clear to release the storage associated with the item, whether or not you choose to access the item with dvkerr_get_item. It is good practice to call dvkerr_clear after every DevKit command invocation, or at least after all those that return a non-zero error code.

Note: Calling dvkerr_clear is unnecessary, but harmless, in the case of command success.
Warning: Reusing error handles without clearing them causes memory leak in your program. That memory leak is equal to the storage associated with any dynamically allocated error items. This storage can easily build up to a critical level in long-running applications or servers.