NAME

       odbx_query - Send a statement to the database server

SYNOPSIS

       #include <opendbx/api.h>

       int odbx_query (odbx_t* handle, const char* stmt, unsigned long length);

DESCRIPTION

       Sends  the  given statement to the database server associated to handle by odbx_init() for
       execution. The statement can contain non-displayable characters as arguments in conditions
       but  they  have  to be escaped via odbx_escape() before adding them to the statement. Even
       more, every argument whose source is not controlled by  the  programmer  must  be  escaped
       first to avoid SQL injection attacks to avoid serious harm!

       After  invoking  odbx_query(), one or more result sets will be sent back by the server and
       are  available  via  odbx_result().  Before  these  sets  aren't  processed   by   calling
       odbx_row_fetch(),  no  other  queries  can  be  sent  to  the  database server. Otherwise,
       odbx_query() will return a backend error from the native database library.

       The first parameter handle is the connection object created and  returned  by  odbx_init()
       which becomes invalid as soon as it was supplied to odbx_finish().

       The  statement  stored  in  the stmt parameter must be a valid statement understood by the
       receiving database server and it should be terminated by a  \0  character.  Some  backends
       support multiple statements per query, which can be tested by calling odbx_get_option().

       The  length  parameter  must  contain  the  length  of  the statement in bytes without the
       terminating \0 character. If variable sized character sets like UTF-8 are used,  the  same
       rule  applies.  This function doesn't support the wide character type (wchar_t) which uses
       two or four bytes per character. If you feed 0 (zero) as length parameter to the function,
       it will calculate the size of the statement on its own.

RETURN VALUE

       odbx_query()  returns  ODBX_ERR_SUCCESS, or an error code whose value is less than zero if
       one of the operations couldn't be completed successfully. Possible error codes are  listed
       in  the  error  section  and they can be feed to odbx_error() and odbx_error_type() to get
       further details.

ERRORS

       -ODBX_ERR_BACKEND
              The native database library returned an error because it wasn't able to handle  the
              statement correctly

       -ODBX_ERR_PARAM
              Either handle or stmt are NULL or handle is invalid

       -ODBX_ERR_NOMEM
              Allocating the required memory for the statement failed

SEE ALSO

       odbx_error(), odbx_error_type(), odbx_escape(), odbx_result()

                                         21 October 2016                            odbx_query(3)