bionic (3) odbx_query.3.gz

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)