Revision as of 17:53, 5 June 2006

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. Otherwise, if a timeout or error occurs, the "result" pointer is set to NULL and in case of a timeout, odbx_result() should be called again.

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.

Dependent on the backend, it may be possible to retrieve all results at once (if "chunk" is zero), one by one or more at once. 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.

This function must be called multiple times until it returns zero, even if you know your query contains only one statement. If you don't do this, memory may be leaked.

Parameters:

• handle: Connection object created by odbx_init()
• result: Pointer to a result pointer
• timeout: Amount of time waiting for a result
• chunk: Number of rows to fetch at once

Return values:

• Three if a result is available
• Two if the query was not SELECT-like
• One in case of a timeout
• Zero if no more results are available
• Less than zero if an error occured

Errors:

• -ODBX_ERR_BACKEND: Any error returned by the backend
• -ODBX_ERR_PARAM: "handle" or "result" is NULL or "handle" is invalid
• -ODBX_ERR_NOMEM: Allocating new memory failed
• -ODBX_ERR_RESULT: Waiting of result failed

Back to Overview