# IBM Visualization Data Explorer Programmer's Reference

[ Bottom of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]

# Chapter 13. System Services

Partial Table-of-Contents

- 13.1 Error Handling and Messages
- 13.2 Timing
- 13.3 Memory Allocation
- 13.4 Object Class
- Type Definitions
- Classes and Subclasses
- Object Routines
- Setting Data Types
- 13.5 Cache
- 13.6 Pending Commands
- 13.7 Looping Support
- 13.8 Parallelism
- 13.9 Basic Data Types
- Points and Vectors
- Lines, Triangles, Quadrilaterals, Tetrahedra, and Cubes
- Colors
- Angles
- Transformation Matrices
- Basic Operations
- 13.10 Module Access
- 13.11 Asynchronous Services

  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

  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:
  1. `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.
  2. `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.
  3. `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.

  [ Top of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]
  [Data Explorer Documentation | QuickStart Guide | User's Guide | User's Reference | Programmer's Reference | Installation and Configuration Guide ]

  [Data Explorer Home Page]

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