NAME

       odbx_result - Retrieves a result set from the database server

SYNOPSIS

       #include <opendbx/api.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 state‐
       ment was successfully executed, a dynamically allocated object representing the result set is  stored  in
       result which must be freed afterwards by odbx_result_finish(). Result sets for SELECT-like statements re‐
       turned  successfully by this function can be processed by calling odbx_row_fetch() until all rows are re‐
       trieved. If the statement was an INSERT, UPDATE, DELETE or a similar statement, the  number  of  affected
       rows is 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  un‐
       til  it returns zero, even if the query contains only one statement. Otherwise, memory will be leaked and
       odbx_query() will return an error.

       The third parameter (timeout) 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 microsec‐
       onds in a timeval structure to wait for. The timeval structure must  be  set  each  time  before  calling
       odbx_result()  because  its content may get 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 re‐
       sult 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 rows at once (if chunk is
       zero), one by one or more than one row at once. All positive values including zero are allowed as  values
       for chunk If paging (more than one row 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 VALUE

       odbx_result()  returns  ODBX_RES_ROWS ("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. ODBX_RES_NOROWS  ("2")  is  re‐
       turned if the statement was executed successfully but will not return a results set (like for INSERT, UP‐
       DATE  and  DELETE  statements)  and  ODBX_RES_TIMEOUT ("1") indicates a timeout. As soon as ODBX_RES_DONE
       ("0") is returned, the available result sets were processed. The  named  constants  are  available  since
       OpenDBX  1.3.2  and the numbers in brackets have to be used instead if a previous release is is the basis
       for the application development.

       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. In this case, the backends are responsible for freeing  the
       data  structures  they allocated inside the function and to clear the errornous result set if there's one
       available. The backends will also set the given result pointer to NULL before returning the error. Never‐
       theless, if a non-fatal error occurred it's possible to retrieve further result sets and this  is  neces‐
       sary before calling odbx_query() on the same connection again.

ERRORS

       -ODBX_ERR_BACKEND
              The native database library returned an error

       -ODBX_ERR_PARAM
              Either handle or result are NULL or handle is invalid

       -ODBX_ERR_NOMEM
              Allocating the required memory for the result failed

       -ODBX_ERR_RESULT
              Waiting for a response from the server failed because the connection was lost

SEE ALSO

       odbx_column_count(),   odbx_column_name(),  odbx_column_type(),  odbx_rows_affected(),  odbx_row_fetch(),
       odbx_result_finish()

                                                  3 April 2024                                    odbx_result(3)