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:

    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 ]