1odbx_result(3) OpenDBX odbx_result(3)
2
6 odbx_result - Retrieves a result set from the database server
7
9 #include <opendbx/api.h>
10 int odbx_result (odbx_t* handle, odbx_result_t** result, struct
13 timeval* timeout, unsigned long chunk);
14
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 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 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 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
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 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
73 -ODBX_ERR_BACKEND
74 The native database library returned an error
75 -ODBX_ERR_PARAM
77 Either handle or result are NULL or handle is invalid
78 -ODBX_ERR_NOMEM
80 Allocating the required memory for the result failed
81 -ODBX_ERR_RESULT
83 Waiting for a response from the server failed because the con‐
84 nection was lost
85
87 odbx_column_count(), odbx_column_name(), odbx_column_type(),
88 odbx_rows_affected(), odbx_row_fetch(), odbx_result_finish()
89 19 January 2023 odbx_result(3)