OpenDBX/C API/Usage - Revision history

85.18.98.155: /* Processing results */ odbx_field_value can return NULL, not odbx_field_length

2012-10-05T15:18:17Z

‎Processing results: odbx_field_value can return NULL, not odbx_field_length

Nose: /* Retrieving results */

2009-03-18T22:52:46Z

‎Retrieving results

Nose: /* Handling options and capabilities */

2009-03-11T23:01:15Z

‎Handling options and capabilities

Nose: odbx_finish error handling

2009-03-09T22:29:48Z

odbx_finish error handling

Nose: /* Dealing with connections */

2009-03-09T22:27:37Z

‎Dealing with connections

Nose: indention

2009-03-09T20:44:51Z

indention

Nose: links to functions

2009-03-09T20:43:17Z

links to functions

Nose: links to functions

2009-03-09T20:23:47Z

links to functions

Nose: links to functions

2009-03-09T20:22:10Z

links to functions

Nose: links to functions

2009-03-09T20:20:59Z

links to functions

← Older revision		Revision as of 15:18, 5 October 2012
Line 211:		Line 211:


−	Besides [[OpenDBX/API/odbx_column_type\|odbx_column_type]]() these functions don't return error codes. Instead, they return zero ([[OpenDBX/API/odbx_field_length\|odbx_field_length]]()) or NULL ([[OpenDBX/API/odbx_column_name\|odbx_column_name]]() and [[OpenDBX/API/~~odbx_field_length~~\|~~odbx_field_length~~]]()), but you shouldn't check for those because these values are also valid return values.	+	Besides [[OpenDBX/API/odbx_column_type\|odbx_column_type]]() these functions don't return error codes. Instead, they return zero ([[OpenDBX/API/odbx_field_length\|odbx_field_length]]()) or NULL ([[OpenDBX/API/odbx_column_name\|odbx_column_name]]() and [[OpenDBX/API/odbx_field_value\|odbx_field_value]]()), but you shouldn't check for those because these values are also valid return values.

	All numbers are returned as strings from the database regardless if they are integers or floats. If you want to do arithmetic operations, you have to convert them to their machine dependent binary representation first.		All numbers are returned as strings from the database regardless if they are integers or floats. If you want to do arithmetic operations, you have to convert them to their machine dependent binary representation first.

@@ Line 183: / Line 183: @@
+  }
-When you've successfully retrieved a result from the database, you have to use [[OpenDBX/API/odbx_row_fetch|odbx_row_fetch]]() to get the rows subsequently until a return value of zero indicates that no more rows are available. It is essential to fetch all rows of the result, even if you've found the row you've been searching for. Otherwise you will get an error while sending the next query or the outstanding rows are returned before the new result is available.
+When you've successfully retrieved a result from the database, you have to use [[OpenDBX/API/odbx_row_fetch|odbx_row_fetch]]() to get the rows subsequently until it returns ODBX_ROW_DONE which indicates that no more rows are available. It is essential to fetch all rows of the result, even if you've found the row you've been searching for. Otherwise you will get an error while sending the next query or the outstanding rows are returned before the new result is available.
-  while( ( err = odbx_row_fetch( result ) ) != 0 )
+  while( ( err = odbx_row_fetch( result ) ) != ODBX_ROW_DONE )
+  {
       if( err < 0 )

@@ Line 104: / Line 104: @@
+  }
-Capabilities are implemented sets of functions serving a specific purpose, e.g. handling prepared statements. By calling [[OpenDBX/API/odbx_capabilities|odbx_capabilities]]() you can find out what sets of functionality are supported by the backend and you can do this any time after successfully invoking [[OpenDBX/API/odbx_init|odbx_init]](). Each set - the basic set is only the default one which is always available - is fully implemented by the backend, so you don't have to worry that the one or another function might be missing.
+Capabilities are implemented sets of functions serving a specific purpose, e.g. handling large objects. By calling [[OpenDBX/API/odbx_capabilities|odbx_capabilities]]() you can find out what sets of functionality are supported by the backend and you can do this any time after successfully invoking [[OpenDBX/API/odbx_init|odbx_init]](). Each set - the basic set is only the default one which is always available - is fully implemented by the backend, so you don't have to worry that the one or another function might be missing.
   if( ( err = odbx_capabilities( handle, ODBX_CAP_LO ) ) < 0 )

@@ Line 76: / Line 76: @@
 I also strongly recommend to unbind before you terminate your program. Finally call [[OpenDBX/API/odbx_finish|odbx_finish]]() to release all resources and disconnect from the database.
-  odbx_finish( handle );
+  if( ( err = odbx_finish( handle ) ) < 0 )
 == Handling options and capabilities ==

@@ Line 54: / Line 54: @@
+  }
-The values you have to feed to the third parameter may be dependent on the database backend you are using. Please refer to the documentation of the database backend to get further information.
+The values for the ''host'' and ''port'' arguments of [[OpenDBX/API/odbx_init|odbx_init]]() respectively the ''database'', ''who'' and ''cred'' arguments of [[OpenDBX/API/odbx_bind|odbx_bind]]() may be dependent on the database backend you are using. Please refer to the [[OpenDBX/Configuration|OpenDBX backend configuration]] page and the documentation of the database backend to get further information.
 Connecting to the database is done by calling [[OpenDBX/API/odbx_bind|odbx_bind]]() with the initialized handle, the database name and the credentials. The backend will open an connection to the DBMS and authenticates itself by using the user name and password.

← Older revision		Revision as of 20:44, 9 March 2009
Line 16:		Line 16:
	int main( int argc, char* argv[] )		int main( int argc, char* argv[] )
	{		{
−	odbx_t* handle;	+	odbx_t* handle;

−	if( odbx_init( &handle, "mysql", "127.0.0.1", "" ) < 0 )	+	if( odbx_init( &handle, "mysql", "127.0.0.1", "" ) < 0 )
−	{	+	{
−	printf( "Error in odbx_init\n" );	+	printf( "Error in odbx_init\n" );
−	return 1;	+	return 1;
−	}	+	}

−	printf( "Initialized connection\n" );	+	printf( "Initialized connection\n" );

−	if( odbx_finish( handle ) < 0 )	+	if( odbx_finish( handle ) < 0 )
−	{	+	{
−	printf( "Error in odbx_finish\n" );	+	printf( "Error in odbx_finish\n" );
−	return 1;	+	return 1;
−	}	+	}

−	return 0;	+	return 0;
	}		}

@@ Line 194: / Line 194: @@
 == Processing results ==
-After fetching a row, all values of this row are available for further processing, as well as their name, length and type - but the name and the type of a column won't change. Also the number of columns returned by odbx_column_count() is fixed for the whole result.
+After fetching a row, all values of this row are available for further processing, as well as their name, length and type - but the name and the type of a column won't change. Also the number of columns returned by [[OpenDBX/API/odbx_column_count|odbx_column_count]]() is fixed for the whole result.
   int i;
@@ Line 207: / Line 207: @@
-Besides odbx_column_type() these functions don't return error codes and odbx_column_name() only returns NULL if an error occured or the field contains a NULL value. Instead they return zero or NULL, but you shouldn't check for those because these values are also valid return values for odbx_column_count() and odbx_field_{length,value}().
+Besides [[OpenDBX/API/odbx_column_type|odbx_column_type]]() these functions don't return error codes. Instead, they return zero ([[OpenDBX/API/odbx_field_length|odbx_field_length]]()) or NULL ([[OpenDBX/API/odbx_column_name|odbx_column_name]]() and [[OpenDBX/API/odbx_field_length|odbx_field_length]]()), but you shouldn't check for those because these values are also valid return values.
 All numbers are returned as strings from the database regardless if they are integers or floats. If you want to do arithmetic operations, you have to convert them to their machine dependent binary representation first.

@@ Line 147: / Line 147: @@
 == Retrieving results ==
-Once you've send a query to the DBMS, the result sets can be retrieved by odbx_result(). In most backends you are able to specify a timeout and how the result should be retrieved: either one by one, all at once or in chunks. If chunks are not supported, they are returned one by one. The result handle - which you must use to get the rows and the values - is stored in the second parameter after odbx_result() returns. In case your query was not a SELECT-like statement and therefore returns no result, you can check for the number of affected rows instead. SELECT-like statement or not, in each case odbx_result() returns a result structure you have to delete afterwards by calling odbx_result_finish().
+Once you've send a query to the DBMS, the result sets can be retrieved by [[OpenDBX/API/odbx_result|odbx_result]](). In most backends you are able to specify a timeout and how the result should be retrieved: either one by one, all at once or in chunks. If chunks are not supported, they are returned one by one. The result handle - which you must use to get the rows and the values - is stored in the second parameter after [[OpenDBX/API/odbx_result|odbx_resul]]t() returns. In case your query was not a SELECT-like statement and therefore returns no result, you can check for the number of affected rows instead. SELECT-like statement or not, in each case [[OpenDBX/API/odbx_result|odbx_result]]() returns a result structure you have to delete afterwards by calling [[OpenDBX/API/odbx_result_finish|odbx_result_finish]]().
   odbx_result_t* result;
@@ Line 179: / Line 179: @@
+  }
-When you've successfully retrieved a result from the database, you have to use odbx_row_fetch() to get the rows subsequently until a return value of zero indicates that no more rows are available. It is essential to fetch all rows of the result, even if you've found the row you've been searching for. Otherwise you will get an error while sending the next query or the outstanding rows are returned before the new result is available.
+When you've successfully retrieved a result from the database, you have to use [[OpenDBX/API/odbx_row_fetch|odbx_row_fetch]]() to get the rows subsequently until a return value of zero indicates that no more rows are available. It is essential to fetch all rows of the result, even if you've found the row you've been searching for. Otherwise you will get an error while sending the next query or the outstanding rows are returned before the new result is available.
   while( ( err = odbx_row_fetch( result ) ) != 0 )

@@ Line 119: / Line 119: @@
   me'; DELETE FROM mytable WHERE uid LIKE '%
-This results in a valid query with two statements and suddenly all your table entries are gone. To avoid SQL injection, you have to escape every (!) user input you like to use in a query, insert statement or anything else. It's a good idea to escape also strings returned from the database because they could be injected SQL statements too. Fortunately odbx_escape() handles all escaping for you. It prevents any kind of SQL insertion and sometimes replaces special characters in the input string. The result is written to a buffer provided by your program and the parameter containing the length of the buffer will be overwritten by the real length of the result. Unfortunately most backends require that your result buffer is more than twice as big as your input (precisely, 2 * input size + 1 ), so you should first think about how long the user input might be.
+This results in a valid query with two statements and suddenly all your table entries are gone. To avoid SQL injection, you have to escape every (!) user input you like to use in a query, insert statement or anything else. It's a good idea to escape also strings returned from the database because they could be injected SQL statements too. Fortunately [[OpenDBX/API/odbx_escape|odbx_escape]]() handles all escaping for you. It prevents any kind of SQL insertion and sometimes replaces special characters in the input string. The result is written to a buffer provided by your program and the parameter containing the length of the buffer will be overwritten by the real length of the result. Unfortunately most backends require that your result buffer is more than twice as big as your input (precisely, 2 * input size + 1 ), so you should first think about how long the user input might be.
   char to[100];

@@ Line 80: / Line 80: @@
 == Handling options and capabilities ==
-If you want to check for library info or use non-standard options like encrypted data transfer or multi-statement support (provided they are supported), this can be changed after calling odbx_init() and before odbx_bind() by using odbx_{get,set}_options(). The function odbx_get_option() returns info about the library and its implemented functionality while odbx_set_option() can change the default behavior of the library.
+If you want to check for library info or use non-standard options like encrypted data transfer or multi-statement support (provided they are supported), this can be changed after calling [[OpenDBX/API/odbx_init|odbx_init]]() and before [[OpenDBX/API/odbx_bind|odbx_bind]]() by using odbx_{get,set}_option(). The function [[OpenDBX/API/odbx_get_option|odbx_get_option]]() returns info about the library and its implemented functionality while [[OpenDBX/API/odbx_set_option|odbx_set_option]]() can change the default behavior of the library.
   int safe;
@@ Line 100: / Line 100: @@
+  }
-Capabilities are implemented sets of functions serving a specific purpose, e.g. handling prepared statements. By calling odbx_capabilities() you can find out what sets of functionality are supported by the backend and you can do this any time after successfully invoking odbx_init(). Each set - the basic set is only the default one which is always available - is fully implemented by the backend, so you don't have to worry that the one or another function might be missing.
+Capabilities are implemented sets of functions serving a specific purpose, e.g. handling prepared statements. By calling [[OpenDBX/API/odbx_capabilities|odbx_capabilities]]() you can find out what sets of functionality are supported by the backend and you can do this any time after successfully invoking [[OpenDBX/API/odbx_init|odbx_init]](). Each set - the basic set is only the default one which is always available - is fully implemented by the backend, so you don't have to worry that the one or another function might be missing.
   if( ( err = odbx_capabilities( handle, ODBX_CAP_LO ) ) < 0 )