IBM Visualization Data Explorer Programmer's Reference

This chapter describes the programming interface to basic system services: error handling and messages, timing, memory allocation, basic object services, types, Private Objects, String Objects, the cache, parallel programming, some basic convenience types and operations, module access, and asynchronous services.

For detailed descriptions of library routines see Appendix C. "Data Explorer Library Routines".

13.1 Error Handling and Messages

Most Data Explorer library routines return either a pointer or an integer error code. A non-NULL pointer or the nonzero integer constant OK indicates success. NULL or ERROR (defined as zero) indicates failure.

If a library routine fails, it may use DXSetError() to set an error code. If it does, the (user-written) calling routine should return NULL or ERROR to propagate the error back to the user.

However, if the library routine does not set an error code, the calling routine should determine whether the NULL return indicates an error:

If an error is indicated, the calling routine should set an error code (by calling DXSetError()) and return NULL or ERROR.
If no error is indicated, the calling routine should proceed.

For example, DXGetComponentValue() returns NULL if the specified component does not exist, but it does not set an error code: the calling routine must determine whether the absence of that component is an error.

How any one Data Explorer routine handles error codes is described in the relevant entry in Appendix C. "Data Explorer Library Routines".

The error codes are defined as follows:

typedef enum errorcode {
    ERROR_MIN,
    ERROR_NONE,
    ERROR_INTERNAL,
    ERROR_UNEXPECTED,
    ERROR_ASSERTION,
    ERROR_NOT_IMPLEMENTED,
    ERROR_NO_MEMORY,
    ERROR_BAD_CLASS,
    ERROR_BAD_TYPE,
    ERROR_NO_CAMERA,
    ERROR_MISSING_DATA,
    ERROR_INVALID_DATA,
    ERROR_BAD_PARAMETER,
    ERROR_MAX
} ErrorCode;

typedef int Error;
#define ERROR 0
#define OK 1
typedef void *Pointer;
#undef NULL
#define NULL 0

`Error DXSetError() #define DXErrorReturn() #define DXErrorGoto() #define DXASSERT()`	Set an error code and an explanatory message. See Note on Use and DXSetError, DXErrorReturn, DXErrorGoto.
`Error DXAddMessage() #define DXMessageReturn() #define DXMessageGoto()`	Append a message to the current error message. See Note on Use and DXAddMessage, DXMessageReturn, DXMessageGoto.
`void DXWarning()`	Presents a warning message to the user. See DXWarning.
`void DXMessage()`	Presents an informational message to the user. See DXMessage.

Note on Use

Note on Use
When a function signals an error by returning `NULL`, it should also set an error code and an error message, using one of the following error routines: `DXErrorReturn(errorcode, message);` Sets an error code and an error message, then returns `NULL`; this function should be invoked by the lowest-level routine that detects the error. `DXMessageReturn(message);` Appends its own message to the message already recorded; this should be done by routines that: Detect an error returned by a lower-level routine that has already set an error code. Contain useful information to add to the message. `return ERROR;` Is used when an error return is detected from a lower-level routine and the current routine has nothing useful to add to the message. If cleanup is required before return, `DXErrorGoto()` or `DXMessageGoto()` may be used instead. Both routines require an `error:` label, after which cleanup is performed and either `NULL` (as shown here) or `ERROR` is returned. error: ... cleanup goes here ... return NULL;

When a function signals an error by returning NULL, it should also set an error code and an error message, using one of the following error routines:

DXErrorReturn(errorcode, message); Sets an error code and an error message, then returns NULL; this function should be invoked by the lowest-level routine that detects the error.
DXMessageReturn(message); Appends its own message to the message already recorded; this should be done by routines that:
- Detect an error returned by a lower-level routine that has already set an error code.
- Contain useful information to add to the message.
return ERROR; Is used when an error return is detected from a lower-level routine and the current routine has nothing useful to add to the message.

If cleanup is required before return, DXErrorGoto() or DXMessageGoto() may be used instead. Both routines require an error: label, after which cleanup is performed and either NULL (as shown here) or ERROR is returned.

    error:
        ... cleanup goes here ...
        return NULL;

Less Commonly Used Routines

ErrorCode DXGetError()
Returns an error code for the last error that occurred. See DXGetError.
char *DXGetErrorMessage()
Returns the current error message. See DXGetErrorMessage.
void DXResetError()
Resets the error state. See DXResetError.
void DXBeginLongMessage() void DXEndLongMessage();
Together create a single "long" message from multiple calls to DXMessage(). See DXBeginLongMessage, DXEndLongMessage.
void DXDebug() void DXEnableDebug(); int DXQueryDebug();
Operate on global debug keys. See DXDebug, DXEnableDebug, DXQueryDebug.
DXDebug() compares an Array of keys to the global debug keys and calls
DXMessage() if any are common to both.
DXEnableDebug() enables or disables one or more global debug keys.
DXQueryDebug() compares an Array of keys to the global debug keys and
returns "1" if any are common to both.

[Data Explorer Home Page | Contact Data Explorer | Same document on Data Explorer Home Page ]

[IBM Home Page | Order | Search | Contact IBM | Legal ]

`ErrorCode DXGetError()`	Returns an error code for the last error that occurred. See DXGetError.
*`char DXGetErrorMessage()`**	Returns the current error message. See DXGetErrorMessage.
`void DXResetError()`	Resets the error state. See DXResetError.
`void DXBeginLongMessage() void DXEndLongMessage();`	Together create a single "long" message from multiple calls to `DXMessage()`. See DXBeginLongMessage, DXEndLongMessage.
`void DXDebug() void DXEnableDebug(); int DXQueryDebug();`	Operate on global debug keys. See DXDebug, DXEnableDebug, DXQueryDebug. `DXDebug()` compares an Array of keys to the global debug keys and calls `DXMessage()` if any are common to both. `DXEnableDebug()` enables or disables one or more global debug keys. `DXQueryDebug()` compares an Array of keys to the global debug keys and returns "1" if any are common to both.

IBM Visualization Data Explorer Programmer's Reference

Chapter 13. System Services

13.1 Error Handling and Messages