.. _varchar-handling-example:

Handling VARCHAR and VARBYTE Data
=================================

Everything in Python is an object, but everything in an Actian SQL DBMS
is a hardware datatype or a C structure. ``ctypes`` 
automatically takes 
care of marshalling the hardware datatypes and C strings
to and from Python, but the other SQL
datatypes need to be accommodated as 
``ctypes`` structures, which have to be defined. 
(See :ref:`Data Marshalling <data-marshalling>` for more information.)

:func:`!VARCHAR()` is 
a straightforward example of an SQL type that requires additional handling.
The DBMS treats it a structure consisting of an unsigned
16-bit length indicator,
followed by up to 32kb of data. :func:`!VARBYTE()` is 
handled exactly the same way.

A simple solution would be to define a function to allocate 
instances of a 32kb structure, large enough to contain the largest possible 
:func:`!VARCHAR()` value. That would be extremely wasteful
if lots of :func:`!VARCHAR()` were needed.

A more economical solution allocates structures just large enough  
for the values that will actually be exchanged, but at the cost of 
a more complex method of allocation. The solution shown here consists
of a function that dynamically defines a class for instances
of the required size, then instantiates one. 

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

..  LITERALINCLUDE:: ./examples/varchar.py
    :linenos:

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