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  statement 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  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 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 until 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  microseconds  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  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 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 returned if the statement was executed successfully but will  not
       return  a results set (like for INSERT, UPDATE 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. Nevertheless,  if  a
       non-fatal  error  occurred  it's  possible  to  retrieve  further  result sets and this is
       necessary 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()

                                          20 March 2014                            odbx_result(3)