NAME
odbx_query - Send a statement to the database server
SYNOPSIS
FC#include <opendbx/api.h>F[0]
FCint odbx_queryF[0] FC(odbx_t* handle, const char* stmt, unsigned long length);F[0]
DESCRIPTION
Sends the given statement to the database server associated to FChandleF[0] by FCodbx_initF[0]() for execution. The statement can contain non-displayable characters as arguments in conditions but they have to be escaped via FCodbx_escapeF[0]() 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 FCodbx_queryF[0](), one or more result sets will be sent back by the server and are available via FCodbx_resultF[0](). Before these sets aren't processed by calling FCodbx_row_fetchF[0](), no other queries can be sent to the database server. Otherwise, FCodbx_queryF[0]() will return a backend error from the native database library.
The first parameter FChandleF[0] is the connection object created and returned by FCodbx_initF[0]() which becomes invalid as soon as it was supplied to FCodbx_finishF[0]().
The statement stored in the FCstmtF[0] 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 FCodbx_get_optionF[0]().
The FClengthF[0] 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 FClengthF[0] parameter to the function, it will calculate the size of the statement on its own.
RETURN VALUE
FCodbx_queryF[0]() returns FCODBX_ERR_SUCCESSF[0], 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 FCodbx_errorF[0]() and FCodbx_error_typeF[0]() to get further details.
ERRORS
- -FCODBX_ERR_BACKENDF[0]
-
The native database library returned an error because it wasn't able to handle the statement correctly
- -FCODBX_ERR_PARAMF[0]
-
Either FChandleF[0] or FCstmtF[0] are NULL or FChandleF[0] is invalid
- -FCODBX_ERR_NOMEMF[0]
-
Allocating the required memory for the statement failed
SEE ALSO
FCodbx_errorF[0](), FCodbx_error_typeF[0](), FCodbx_escapeF[0](), FCodbx_resultF[0]()