Open topic with navigation

TIBCO® Patterns 6.1.2

# 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.

Did you find this helpful?

Yes No
Great!
Thanks for taking the time to give us some feedback.
Sorry about that

Why wasn't this helpful? (check all that apply)

Could not find what I was looking for
Instructions confusing or unclear
Instructions did not work

Want to tell us more?

Please select at least one option or provide details about the issue!!

Error occurred while submitting feedback.

Error2 occurred while submitting feedback.

TIBCO® Patterns

Copyright © 2010-2025. Cloud Software Group, Inc. All Rights Reserved.