.. _error-handling-example:

Fetching Error Information
==========================

Two types of errors can be reported: errors in the use or operation of
the OpenAPI, and errors reported by the DBMS. 

There are two
types of OpenAPI function: asynchronous functions which interact with 
the DBMS, and synchronous functions which interact only with the 
OpenAPI. Both types of function report
errors using their control blocks, but in different ways. 

The control block for asynchronous 
functions contains an :attr:`!IIAPI_GENPARM` structure, which has a
:attr:`gp_status` member and a :attr:`gp_errorHandle` member.
The control block for a synchronous function has only a "status" 
member, the exact name of which will depend on the function. For
instance, in 
the case of the :attr:`!IIAPI_INITPARM` for the
:func:`!IIapi_initialize` function,  
its status member is called :attr:`!in_status`.

In the event of an error, detected by the OpenAPI or the DBMS, 
the status is set to :attr:`IIAPI_ST_ERROR` or greater.

In the event of an error in an asynchronous function, the 
:attr:`gp_errorHandle` member of its :attr:`!IIAPI_GENPARM` structure
may be set. The error handle can be used to fetch detailed error 
messages by calling :func:`IIapi_getErrorInfo`. Because a single fault may
cause multiple messages it has to be called repeatedly, until it returns
:attr:`IIAPI_ST_NO_DATA`.

..  NOTE::

    :attr:`!IIAPI_ST_ERROR` indicates an error.  The DBMS session
    remains usable and the application can continue.

    :attr:`!IIAPI_ST_FAILURE` indicates the DBMS session has failed but 
    if there is an
    error handle then additional information 
    will be available using :func:`!IIapi_getErrorInfo`. The DBMS session 
    may no longer be usable. 


..  IMPORTANT::

    The OpenAPI allocates the buffers used for error messages. They 
    are released when the application executes :func:`!IIapi_close`.
    Copy any required error information before doing so.

..  WARNING::

    Failing to call :func:`!IIapi_close` will create a memory leak.

:download:`Download <./examples/errors.py>`

..  LITERALINCLUDE:: ./examples/errors.py
    :linenos:

:download:`Download <./examples/errors.py>`