1odbx_result(3)                      OpenDBX                     odbx_result(3)
2
3
4

NAME

6       odbx_result - Retrieves a result set from the database server
7

SYNOPSIS

9       #include <opendbx/api.h>
10
11
12       int odbx_result (odbx_t* handle, odbx_result_t** result, struct
13                       timeval* timeout, unsigned long chunk);
14

DESCRIPTION

16       Retrieves the result of a query statement sent by odbx_query() from the
17       database server. After a statement was successfully executed, a dynami‐
18       cally allocated object representing the result set is stored in  result
19       which must be freed afterwards by odbx_result_finish(). Result sets for
20       SELECT-like statements returned successfully by this  function  can  be
21       processed  by calling odbx_row_fetch() until all rows are retrieved. If
22       the statement was an INSERT, UPDATE, DELETE or a similar statement, the
23       number of affected rows is available via odbx_rows_affected().
24
25       If  a  timeout  or  error occurs, the result pointer is set to NULL. In
26       case of a timeout, odbx_result() should be  called  again  because  the
27       query isn't canceled. This function must be called multiple times until
28       it returns zero, even if the query contains only one statement.  Other‐
29       wise, memory will be leaked and odbx_query() will return an error.
30
31       The  third parameter (timeout) restricts the time the function is wait‐
32       ing for a result form the server. It may be NULL to wait until a result
33       arrives.  Otherwise, it can contain any number of seconds and microsec‐
34       onds in a timeval structure to wait for. The timeval structure must  be
35       set  each time before calling odbx_result() because its content may get
36       changed by the function. If the server doesn't respond within the time‐
37       out,  the query isn't canceled! Instead, the next call to this function
38       will wait for the same result set. Waiting the specified  time  may  be
39       implemented  in the backends if it is possible, but there is no guaran‐
40       tee. If not, odbx_result() will return not before a responds arrives.
41
42       Dependent on the native database library, it may  be  possible  to  re‐
43       trieve all rows at once (if chunk is zero), one by one or more than one
44       row at once. All positive values including zero are allowed  as  values
45       for chunk If paging (more than one row at once) is not supported by the
46       backend, it will use "one by one" or "all at once" if this is the  only
47       option provided.
48

RETURN VALUE

50       odbx_result()  returns ODBX_RES_ROWS ("3") if a result set is available
51       and zero if no more results will be returned for the last query  string
52       sent  via  odbx_query() successfully. ODBX_RES_NOROWS ("2") is returned
53       if the statement was executed successfully but will not  return  a  re‐
54       sults   set  (like  for  INSERT,  UPDATE  and  DELETE  statements)  and
55       ODBX_RES_TIMEOUT ("1") indicates a timeout. As  soon  as  ODBX_RES_DONE
56       ("0")  is returned, the available result sets were processed. The named
57       constants are available since OpenDBX 1.3.2 and the numbers in brackets
58       have  to  be used instead if a previous release is is the basis for the
59       application development.
60
61       It returns an error code whose value is less than zero if  one  of  the
62       operations couldn't be completed successfully. Possible error codes are
63       listed in the error section and they can be feed  to  odbx_error()  and
64       odbx_error_type()  to  get  further details. In this case, the backends
65       are responsible for freeing the data structures they  allocated  inside
66       the  function  and  to  clear  the  errornous result set if there's one
67       available. The backends will also set the given result pointer to  NULL
68       before returning the error. Nevertheless, if a non-fatal error occurred
69       it's possible to retrieve further result sets and this is necessary be‐
70       fore calling odbx_query() on the same connection again.
71

ERRORS

73       -ODBX_ERR_BACKEND
74              The native database library returned an error
75
76       -ODBX_ERR_PARAM
77              Either handle or result are NULL or handle is invalid
78
79       -ODBX_ERR_NOMEM
80              Allocating the required memory for the result failed
81
82       -ODBX_ERR_RESULT
83              Waiting  for  a response from the server failed because the con‐
84              nection was lost
85

SEE ALSO

87       odbx_column_count(),      odbx_column_name(),       odbx_column_type(),
88       odbx_rows_affected(), odbx_row_fetch(), odbx_result_finish()
89
90
91
92                                19 January 2023                 odbx_result(3)
Impressum