OpenDBX/C API/odbx result
#include <odbx.h>
int odbx_result(
odbx_t* handle,
odbx_result_t** result,
struct timeval* timeout,
unsigned long chunk )
Description
Retrieves the result of a query statement sent by odbx_query() from the database server. After a statement was successfully executed, a dynamically allocated object representing the result set is stored in result which must be freed afterwards by odbx_result_free(). Result sets for SELECT-like statements returned successfully by this function can be processed by calling odbx_row_fetch() until all rows are retrieved. If the statement was an INSERT, UPDATE, DELETE or a similar statement, the number of affected rows are available via odbx_rows_affected.
If a timeout or error occurs, the result pointer is set to NULL. In case of a timeout, odbx_result() should be called again because the query isn't canceled. This function must be called multiple times until it returns zero, even if the query contains only one statement. Otherwise, memory will be leaked and odbx_query() will return an error until this is done.
The third parameter restricts the time the function is waiting for a result form the server. It may be NULL to wait until a result arrives. Otherwise, it can contain any number of seconds and microseconds in a timeval structure to wait for. The timeval structure must be set each time before calling odbx_result() because its content may be changed by the function. If the server doesn't respond within the timeout, the query isn't canceled! Instead, the next call to this function will wait for the same result set. Waiting the specified time may be implemented in the backends if it is possible, but there is no guarantee. If not, odbx_result() will return not before a responds arrives.
Dependent on the native database library, it may be possible to retrieve all results at once (if chunk is zero), one by one or more at once. All positive values including zero are allowed as values for chunk If paging (more at once) is not supported by the backend, it will use "one by one" or "all at once" if this is the only option provided.
Return values
odbx_result() returns three ("3") if a result set is available and zero if no more results will be returned for the last query string sent via odbx_query() successfully. Two ("2") is returned if the statement was executed successfully but will not return a results set (like for INSERT, UPDATE and DELETE statements) and one ("1") indicates a timeout.
It returns 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
- -ODBX_ERR_PARAM
- Either handle or the result parameter is NULL or handle is invalid
- -ODBX_ERR_NOMEM
- Allocating required memory failed
- -ODBX_ERR_RESULT
- Waiting for a response from the server failed because the connection was lost
See also
- OpenDBX_column_count
- OpenDBX_column_name
- OpenDBX_column_type
- OpenDBX_rows_affected
- OpenDBX_row_fetch
- OpenDBX_result_free
Back to Overview
