Using Callbacks

Callbacks can be used instead of or in addition to busy-wait loops to get notification that an asynchronous OpenAPI function has completed the requested action.

Callbacks are required for handling unpredictable communications from the DBMS, such as various kinds of trace messages (I/O, logging, etc.) and notifications of database events (DBEvents).

When a callback is specified using the IIAPI_GENPARM structure of an OpenAPI asynchronous function control block, the gp_callback attribute is the address of the callback function, and gp_closure can be a pointer to a an optional value that will be passed to the callback as an argument.

Closure is the means by which an application passes information to the callback function.

Callback functions are expected to take two arguments. The first is expected to be a pointer to the closure, and the second is expected to be a pointer to an IIAPI_GENPARM structure.

Callbacks can’t return a value, but if passed a pointer to a structure as the closure they can update its contents. They can also update globals.

Note

This example makes use of the IIapi_getCallbackPtr() and IIapi_getClosure() helper functions provided by pyngres. They are not part of the Actian OpenAPI.

Tip

Refer to the ctypes documentation for additional explanation of callbacks.

Download

import pyngres as py

...

# create example_callback() 
@py.IIapi_callback
def iiapi_trace(trace_block,parmBlock=None):
    '''trace-message callback'''

    # get the trace_block argument as a Python IIAPI_TRACEPARM instance
    trp = py.IIapi_getClosure(trace_block,py.IIAPI_TRACEPARM)
    # extract the tr_message member containing a line of trace info
    tr_message = trp.tr_message
    ...

# install iiapi_trace() as the callback to handle trace-messages
tracer = py.IIapi_getCallbackPtr(iiapi_trace)
sep = py.IIAPI_SETENVPRMPARM()
sep.se_envHandle = envHandle
sep.se_paramID = py.IIAPI_EP_TRACE_FUNC
sep.se_paramValue = tracer
py.IIapi_setEnvParam(sep)

Download