.. _data-buffer-example:

Setting Up Data Buffers
=======================

Data buffers are needed to receive query results from the DBMS and to 
supply arguments to parameterized SQL statements.

This example sets up data buffers to receive the results of a query that 
returns a single row with two columns:

..  CODE:: none 

    SELECT name, weight
    FROM foo
    WHERE ordernr = 71025

Buffers are required for the value of the result columns, and 
an array of :attr:`!IIAPI_DATAVALUE` is needed to point to them.

In this
example the allocation of buffers is hard-coded for simplicity. In reality
the number, type, and size of the required buffers would generally be 
determined from the 
array of :attr:`!IIAPI_DESCRIPTOR` returned by :func:`!IIapi_getDescriptor`,
and the buffers would be allocated dynamically.

..  NOTE::

    ``asyncio`` is used in this example but it is not essential. 
    To use busy-wait loops instead, see 
    :ref:`asynchronous-functions`. 


:download:`Download <./examples/data-buffer.py>`

..  LITERALINCLUDE:: ./examples/data-buffer.py
    :linenos:

:download:`Download <./examples/data-buffer.py>`