Difference between revisions of "OpenDBX/C API/odbx query"
(→Errors) |
(Description) |
||
| Line 8: | Line 8: | ||
unsigned long '''length''' ) | unsigned long '''length''' ) | ||
| − | = Description | + | = Description = |
| − | Sends | + | Sends the given statement to the database server associated to '''handle''' by [[OpenDBX_init|odbx_init()]] for execution. The statement might contain non-displayable characters as arguments in conditions but they have to be escaped via [[OpenDBX_escape|odbx_escape()]] before adding them to the statement. Even more, every argument whose source is not controlled by the programmer should be escaped first to avoid SQL injection attacks to avoid serious harm! |
| − | After invoking odbx_query(), | + | After invoking '''odbx_query()''', one or more result sets will be sent back by the server and are available via [[OpenDBX_result|odbx_result()]]. Before these sets aren't processed by calling [[OpenDBX_row_fetch|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 [[OpenDBX_init|odbx_init()]] which becomes invalid as soon as it was supplied to [[OpenDBX_finish|odbx_finish()]]. | |
| − | + | The statement stored in the '''query''' 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 [[OpenDBX_get_option|odbx_get_option()]]. | |
| − | + | ||
| − | + | The '''length''' parameter should 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 wide characters which use two or four bytes space per character. | |
= Return values = | = Return values = | ||
| Line 35: | Line 35: | ||
* [[OpenDBX_error_type]] | * [[OpenDBX_error_type]] | ||
* [[OpenDBX_result]] | * [[OpenDBX_result]] | ||
| + | * [[OpenDBX_row_fetch]] | ||
---- | ---- | ||
Back to [[OpenDBX API|Overview]] | Back to [[OpenDBX API|Overview]] | ||
Revision as of 22:56, 9 March 2007
#include <odbx.h>
int odbx_query(
odbx_t* handle,
const char* query,
unsigned long length )
Description
Sends the given statement to the database server associated to handle by odbx_init() for execution. The statement might 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 should 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 query 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 should 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 wide characters which use two or four bytes space per character.
Return values
odbx_get_option() 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 query statement correctly
- -ODBX_ERR_PARAM
- Either handle or the query string are NULL or handle is invalid
- -ODBX_ERR_NOMEM
- Allocating the required memory for the query string failed
See also:
Back to Overview
