OpenDBX/C API/odbx result - Revision history

Nose: moved OpenDBX/API/odbx result to OpenDBX/C API/odbx result

2009-04-28T21:14:09Z

moved OpenDBX/API/odbx result to OpenDBX/C API/odbx result

Nose: 1 revision(s)

2008-05-23T22:49:54Z

1 revision(s)

: docbook2x update

2008-05-23T22:49:54Z

docbook2x update

Nose: 1 revision(s)

2008-05-23T22:33:26Z

1 revision(s)

: docbook2x update

2008-05-23T22:33:26Z

docbook2x update

Nose: retrieve results after errors

2008-03-27T23:08:40Z

retrieve results after errors

Nose: cleanup on error

2008-03-27T22:22:42Z

cleanup on error

Nose: 1 revision(s)

2007-05-19T20:08:36Z

1 revision(s)

: docbook2x update

2007-05-19T20:00:00Z

docbook2x update

Nose: OpenDBX result moved to OpenDBX/API/odbx result

2007-05-17T15:16:59Z

OpenDBX result moved to OpenDBX/API/odbx result

@@ Line 12: / Line 12: @@
 == Description ==
-Retrieves the result of a query statement sent by [[OpenDBX/API/odbx_query|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 [[OpenDBX/API/odbx_result_free|odbx_result_free]](). Result sets for SELECT-like statements returned successfully by this function can be processed by calling [[OpenDBX/API/odbx_row_fetch|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 [[OpenDBX/API/odbx_rows_affected|odbx_rows_affected]]().
+Retrieves the result of a query statement sent by [[OpenDBX/API/odbx_query|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 [[OpenDBX/API/odbx_result_finish|odbx_result_finish]](). Result sets for SELECT-like statements returned successfully by this function can be processed by calling [[OpenDBX/API/odbx_row_fetch|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 [[OpenDBX/API/odbx_rows_affected|odbx_rows_affected]]().
 If a timeout or error occurs, the '''''result''''' pointer is set to NULL. In case of a timeout, [[OpenDBX/API/odbx_result|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 [[OpenDBX/API/odbx_query|odbx_query]]() will return an error.
@@ Line 40: / Line 40: @@
 * [[OpenDBX/API/odbx_rows_affected|odbx_rows_affected]]()
 * [[OpenDBX/API/odbx_row_fetch|odbx_row_fetch]]()
-* [[OpenDBX/API/odbx_result_free|odbx_result_free]]()
+* [[OpenDBX/API/odbx_result_finish|odbx_result_finish]]()

@@ Line 2: / Line 2: @@
 '''Retrieves a result set from the database server'''
-  #include <odbx.h>
+  #include <opendbx/api.h>
-−
   int '''odbx_result'''(
       odbx_t* '''''handle''''',
@@ Line 22: / Line 22: @@
 == Return value ==
-[[OpenDBX/API/odbx_result|odbx_result]]() returns three ("3") if a result set is available and zero if no more results will be returned for the last query string sent via [[OpenDBX/API/odbx_query|odbx_query]]() successfully. Two ("2") is returned if the statement was executed successfully but will not return a results set (like for INSERT, UPDATE and DELETE statements) and one ("1") indicates a timeout.
+[[OpenDBX/API/odbx_result|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 [[OpenDBX/API/odbx_query|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 [[OpenDBX/API/odbx_error|odbx_error]]() and [[OpenDBX/API/odbx_error_type|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 [[OpenDBX/API/odbx_query|odbx_query]]() on the same connection again.
@@ Line 41: / Line 41: @@
 * [[OpenDBX/API/odbx_row_fetch|odbx_row_fetch]]()
 * [[OpenDBX/API/odbx_result_free|odbx_result_free]]()

@@ Line 24: / Line 24: @@
 [[OpenDBX/API/odbx_result|odbx_result]]() returns three ("3") if a result set is available and zero if no more results will be returned for the last query string sent via [[OpenDBX/API/odbx_query|odbx_query]]() successfully. Two ("2") is returned if the statement was executed successfully but will not return a results set (like for INSERT, UPDATE and DELETE statements) and one ("1") indicates a timeout.
-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 [[OpenDBX/API/odbx_error|odbx_error]]() and [[OpenDBX/API/odbx_error_type|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.
+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 [[OpenDBX/API/odbx_error|odbx_error]]() and [[OpenDBX/API/odbx_error_type|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 [[OpenDBX/API/odbx_query|odbx_query]]() on the same connection again.
 == Errors ==

@@ Line 24: / Line 24: @@
 [[OpenDBX/API/odbx_result|odbx_result]]() returns three ("3") if a result set is available and zero if no more results will be returned for the last query string sent via [[OpenDBX/API/odbx_query|odbx_query]]() successfully. Two ("2") is returned if the statement was executed successfully but will not return a results set (like for INSERT, UPDATE and DELETE statements) and one ("1") indicates a timeout.
-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 [[OpenDBX/API/odbx_error|odbx_error]]() and [[OpenDBX/API/odbx_error_type|odbx_error_type]]() to get further details.
+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 [[OpenDBX/API/odbx_error|odbx_error]]() and [[OpenDBX/API/odbx_error_type|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.
 == Errors ==

@@ Line 1: / Line 1: @@
 __NOTOC__
- '''#include <odbx.h>'''
+'''Retrieves a result set from the database server'''
   int '''odbx_result'''(
-      odbx_t* '''handle''',
+      odbx_t* '''''handle''''',
-      odbx_result_t** '''result''',
+      odbx_result_t** '''''result''''',
-      struct timeval* '''timeout''',
+      struct timeval* '''''timeout''''',
-      unsigned long '''chunk''' )
+      unsigned long '''''chunk''''' )
 == Description ==
-Retrieves the result of a query statement sent by [[OpenDBX_query|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 [[OpenDBX_result_free|odbx_result_free()]]. Result sets for SELECT-like statements returned successfully by this function can be processed by calling [[OpenDBX_row_fetch|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 [[OpenDBX_rows_affected|odbx_rows_affected()]].
+Retrieves the result of a query statement sent by [[OpenDBX/API/odbx_query|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 [[OpenDBX/API/odbx_result_free|odbx_result_free]](). Result sets for SELECT-like statements returned successfully by this function can be processed by calling [[OpenDBX/API/odbx_row_fetch|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 [[OpenDBX/API/odbx_rows_affected|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 [[OpenDBX_query|odbx_query()]] will return an error until this is done.
+If a timeout or error occurs, the '''''result''''' pointer is set to NULL. In case of a timeout, [[OpenDBX/API/odbx_result|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 [[OpenDBX/API/odbx_query|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 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. If not, '''odbx_result()''' will return not before a responds arrives.
+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 [[OpenDBX/API/odbx_result|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, [[OpenDBX/API/odbx_result|odbx_result]]() will return not before a responds arrives.
-Dependent on the native database library, it may be possible to retrieve all results at once (if '''chunk''' is zero), one by one or more at once. All positive values including zero are allowed as values for '''chunk''' 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.
+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 values ==
+== Return value ==
-'''odbx_result()''' returns three ("3") if a result set is available and zero if no more results will be returned for the last query string sent via [[OpenDBX_query|odbx_query()]] successfully. Two ("2") is returned if the statement was executed successfully but will not return a results set (like for INSERT, UPDATE and DELETE statements) and one ("1") indicates a timeout.
+[[OpenDBX/API/odbx_result|odbx_result]]() returns three ("3") if a result set is available and zero if no more results will be returned for the last query string sent via [[OpenDBX/API/odbx_query|odbx_query]]() successfully. Two ("2") is returned if the statement was executed successfully but will not return a results set (like for INSERT, UPDATE and DELETE statements) and one ("1") indicates a timeout.
-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 [[OpenDBX_error|odbx_error()]] and [[OpenDBX_error_type|odbx_error_type()]] to get further details.
+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 [[OpenDBX/API/odbx_error|odbx_error]]() and [[OpenDBX/API/odbx_error_type|odbx_error_type]]() to get further details.
 == Errors ==
-; -ODBX_ERR_BACKEND: The native database library returned an error
+; -ODBX_ERR_BACKEND : The native database library returned an error
-; -ODBX_ERR_PARAM: Either '''handle''' or the '''result''' parameter is NULL or '''handle''' is invalid
+; -ODBX_ERR_PARAM : Either '''''handle''''' or '''''result''''' are NULL or '''''handle''''' is invalid
-; -ODBX_ERR_NOMEM: Allocating required memory failed
+; -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
+; -ODBX_ERR_RESULT : Waiting for a response from the server failed because the connection was lost
 == See also ==
-* [[OpenDBX_column_count]]
+* [[OpenDBX/API/odbx_column_count|odbx_column_count]]()
-* [[OpenDBX_column_name]]
+* [[OpenDBX/API/odbx_column_name|odbx_column_name]]()
-* [[OpenDBX_column_type]]
+* [[OpenDBX/API/odbx_column_type|odbx_column_type]]()
-* [[OpenDBX_rows_affected]]
+* [[OpenDBX/API/odbx_rows_affected|odbx_rows_affected]]()
-* [[OpenDBX_row_fetch]]
+* [[OpenDBX/API/odbx_row_fetch|odbx_row_fetch]]()
-* [[OpenDBX_result_free]]
+* [[OpenDBX/API/odbx_result_free|odbx_result_free]]()
 ----
-Back to [[OpenDBX API|Overview]]
+Back to [[OpenDBX/API|Overview]]

← Older revision	Revision as of 21:14, 28 April 2009
(No difference)

← Older revision	Revision as of 22:49, 23 May 2008
(No difference)

← Older revision	Revision as of 22:33, 23 May 2008
(No difference)

← Older revision	Revision as of 20:08, 19 May 2007
(No difference)

← Older revision	Revision as of 15:16, 17 May 2007
(No difference)