ctypes

In Python everything is an object.

Data Marshalling

The OpenAPI and the Actian DBMS products exchange data using C structures and C datatypes. The abstract SQL datatypes such as ANSIDATE and DECIMAL are represented as C structures internally; even VARCHARs are structures.

Python does not understand C structures and the Actian database management systems don’t understand Python objects. In general data has to be marshalled between the two representations using the ctypes package.

pyngres uses ctypes to bind to the OpenAPI and wrap the OpenAPI control blocks. It therefore handles certain simple cases automatically, as in this example of assigning a value to an integer member of a control block:

inp.in_timeout = -1

inp is wrapper around a C structure which has a 32-bit C integer member called in_timeout. The value -1 is a Python int object. In this case ctypes automatically converts the Python value to a C value to assign it in the control block.

In a similar way it also automatically handles Python floating point values, byte strings (which get treated as NUL-terminated C strings), True and False, and None (which gets treated as a zero or a null pointer, as appropriate).

Handlers must be developed for all the remaining SQL datatypes that get exchanged with pyngres. For example, ANSIDATEs must be converted into datetime.date instances if they are to be used in Python code.

Declaring Arrays

The syntax to dynamically declare a ctypes array (list) is not obvious. Consider an SQL query which returns twenty columns. It requires a twenty element array of IIAPI_DATEVALUE. To allocate such an array, first create a factory class, then use it to instantiate the array:

ArrayaOf20Factory = py.IIAPI_DATAVALUE * 20     # create the factory class
array = ArrayaOf20Factory()                     # instantiate the array

Or more concisely, and without cluttering the namespace with obscure classes:

array = (py.IIAPI_DATAVALUE * 20)()

Note

ctypes is complicated and sometimes challenging. There are many tutorials and blogs that discuss how to use it. For the purpose of developing OpenAPI applications it is probably sufficient to follow some of the examples here rather than attempting to master it.

Blogs about ctypes, and contributions on Stackoverflow or generated by AI, should be read with caution. Much of it is stale or obsolete, or worse.