OpenDBX/C++ API/Usage - Revision history

213.136.58.100: ODBC -> ODBX

2009-10-27T19:02:48Z

ODBC -> ODBX

Nose: /* Error handling */

2009-03-19T20:42:25Z

‎Error handling

Nose: /* Using large objects */

2009-03-19T20:21:25Z

‎Using large objects

Nose: /* Retrieving results */

2009-03-18T22:56:28Z

‎Retrieving results

Nose: /* Retrieving results */

2009-03-18T22:49:49Z

‎Retrieving results

Nose: /* Executing statements */

2009-03-18T22:27:21Z

‎Executing statements

Nose: /* Executing statements */

2009-03-18T21:18:17Z

‎Executing statements

Nose: /* Handling options and capabilities */

2009-03-11T23:10:26Z

‎Handling options and capabilities

Nose: /* Handling options and capabilities */

2009-03-11T23:08:20Z

‎Handling options and capabilities

Nose: Conn doc + options and capabilities

2009-03-11T22:49:41Z

Conn doc + options and capabilities

@@ Line 125: / Line 125: @@
 In case the underlying database library requires special handling of large objects (binary or character LOBs), the value of [[OpenDBX/C++ API/1.0/Result#fieldValue|Result::fieldValue]]() has to be feed into the [[OpenDBX/C++ API/1.0/Result#getLob|Result::getLob]]() method. It returns a Lob object which enables the application to read from and write to a large object using [[OpenDBX/C++ API/1.0/Lob#read|Lob::read]]() respectively [[OpenDBX/C++ API/1.0/Lob#write|Lob::write]](). This is only necessary if the [[OpenDBX/C++ API/1.0/Conn#getCapability|Conn::getCapability]]() method returns true when asking for ODBX_CAP_LO.
-  if( db.getCapability( ODBC_CAP_LO ) )
+  if( db.getCapability( ODBX_CAP_LO ) )
+  {
       char buffer[64];

@@ Line 143: / Line 143: @@
 == Error handling ==
-If an error occurs in any of the object methods, the objects will throw an instance of the Exception class with extends the runtime_error exception of the STL. The instance contains an error message, the OpenDBX error code and an error type indicating the severity of the error. This information can be retrieved by the methods Exception::what(), Exception::getCode() and Exception::getType().
+If an error occurs in any of the object methods, the objects will throw an instance of the Exception class with extends the runtime_error exception of the STL. The instance contains an error message, the OpenDBX error code and an error type indicating the severity of the error. This information can be retrieved by the methods [[OpenDBX/C++ API/1.0/Exception#what|Exception::what]](), [[OpenDBX/C++ API/1.0/Exception#getCode|Exception::getCode]]() and [[OpenDBX/C++ API/1.0/Exception#getType|Exception::getType]]().
 == Further examples ==
 A full-featured working example of how to use the OpenDBX C++ API correctly can be found in the test/odbxplus-regression.cpp file of the source distribution available at the [[OpenDBX/Download|download section]].

@@ Line 123: / Line 123: @@
 == Using large objects ==
-In case the unterlying database library requires special handling of large objects (binary or text LOBs), the value of Result::fieldValue() has to be feed into the Result::getLob() method. It returns a Lob object which enables the application to read from and write to a large object using Lob::read() respectively Lob::write(). This is only necessary if the Conn::getCapability() method returns true when asking for ODBX_CAP_LO.
+In case the underlying database library requires special handling of large objects (binary or character LOBs), the value of [[OpenDBX/C++ API/1.0/Result#fieldValue|Result::fieldValue]]() has to be feed into the [[OpenDBX/C++ API/1.0/Result#getLob|Result::getLob]]() method. It returns a Lob object which enables the application to read from and write to a large object using [[OpenDBX/C++ API/1.0/Lob#read|Lob::read]]() respectively [[OpenDBX/C++ API/1.0/Lob#write|Lob::write]](). This is only necessary if the [[OpenDBX/C++ API/1.0/Conn#getCapability|Conn::getCapability]]() method returns true when asking for ODBX_CAP_LO.
 == Error handling ==

@@ Line 108: / Line 108: @@
+      }
+  }
 If the statement may return rows, the [[OpenDBX/C++ API/1.0/Result#columnName|Result::columnName]]() and [[OpenDBX/C++ API/1.0/Result#columnType|Result::columnType]]() methods are able to provide some informations about the columns indexed from 0 to [[OpenDBX/C++ API/1.0/Result#columnCount|Result::columnCount]]()-1. It's also possible to map the column name with the [[OpenDBX/C++ API/1.0/Result#columnPos|Result::columnPos]]() method to the column index which is required be the other column methods. To get the actual value and length of the content in the current row at the given position, the [[OpenDBX/C++ API/1.0/Result#fieldValue|Result::fieldValue]]() and [[OpenDBX/C++ API/1.0/Result#fieldLength|Result::fieldLength]]() must be called. A simple example would be:
@@ Line 113: / Line 115: @@
   for( int i = 0; i < result.columnCount() - 1; i++ )
+  {
-      cout << result.columnName( i ) << ": " << result.fieldValue( i ) << endl;
+      cout << "Name: " << result.columnName( i ) << endl;
+  }

@@ Line 86: / Line 86: @@
 == Retrieving results ==
-Each result set must be retrieved using Result::getResult(), while Result::getRows() fetches a row from the current result set if the statement was a SELECT like statement. Otherwise, Result::rowsAffected() can be used to get the number of rows that were touched by the statement. If the statement may return rows, the Result::columnName() and Result::columnType() methods are able to provide some informations about the columns indexed from 0 to n. It's also possible to map the column name with the Result::columnPos() method to the column index which is required be the other column methods. To get the actual value and length of the content in the current row at the given position, the Result::fieldValue() and Result::fieldLength() must be called.
+Each result set must be retrieved using [[OpenDBX/C++ API/1.0/Result#getResult|Result::getResult]](), while [[OpenDBX/C++ API/1.0/Result#getRow|Result::getRow]]() fetches a row from the current result set if the statement was a SELECT-like statement. Otherwise, [[OpenDBX/C++ API/1.0/Result#rowsAffected|Result::rowsAffected]]() can be used to get the number of rows that were touched by the statement. A typical sequence of commands for retrieving result sets is:
 == Using large objects ==

@@ Line 82: / Line 82: @@
   sql = sql.replace( sql.find( ":uid" ), 4, db.escape( input, escaped ) );
-  Result result = db.create( sql );
+  Result result = db.create( sql ).execute();
 == Retrieving results ==

@@ Line 60: / Line 60: @@
 == Executing statements ==
-The Conn::create() method creates and initializes a new statement instance from a SQL string. Currently, there are only simple statement objects implemented, which needs to be complete statements which can be sent to the database with Stmt::execute(). This method returns a Result object encapsulating one or more result sets returned by the database depending on the statement sent.
+Before you are sending queries to your database, you should be aware of the security issues you will be facing. If you will use any kind of user input in your statements, you will potentially be vulnerable to the injection of code and this can lead to disastrous effects. Imagine for example the following simple statement:
 == Retrieving results ==

@@ Line 56: / Line 56: @@
 Capabilities are implemented sets of functions serving a specific purpose, e.g. handling large objects. By calling [[OpenDBX/C++ API/1.0/Conn|Conn::getCapabilities]]() you can find out what sets of functionality are supported by the backend. You can do this any time after successfully creating a connection object with was initialized with at least the backend parameter. 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.
-  bool use_lo = false;
+  bool use_lo = db.getCapabilites( ODBX_CAP_LO );
-−
- if( db.getCapabilites( ODBX_CAP_LO ) ) {
-     use_lo = true;
-−
 == Executing statements ==

@@ Line 46: / Line 46: @@
 == Handling options and capabilities ==
-Conn::getCapability() tests the implemented capabilites of the underlying database library while Conn::getOption() and Conn::setOption() cas be used to test for and change a number of options. The options must be changed before authenticating the connection with the Conn::bind() method to have any effect. It's also possible to rebind a connection using different credentials after Conn::unbind() had been called. Additionally, the Conn class is able to escape potentially dangerous character sequences with Conn::escape() if e.g. user input should be part of a statement as value.
+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/C++ API/1.0/Conn|Conn::getOption]]() or [[OpenDBX/C++ API/1.0/Conn|Conn::setOption]]](). Conn::getOption() returns info about the library and its implemented functionality while Conn::setOption() can change the default behavior of the library. The options must be changed before authenticating the connection with the Conn::bind() method to have any effect.
 == Executing statements ==

@@ Line 38: / Line 38: @@
 == Dealing with connections ==
-Using the API starts with establishing a connection to the database server by creating an instance of the Conn class with the parameters backend, host and port. Conn::getCapability() tests the implemented capabilites of the underlying database library while Conn::getOption() and Conn::setOption() cas be used to test for and change a number of options. The options must be changed before authenticating the connection with the Conn::bind() method to have any effect. It's also possible to rebind a connection using different credentials after Conn::unbind() had been called. Additionally, the Conn class is able to escape potentially dangerous character sequences with Conn::escape() if e.g. user input should be part of a statement as value.
+Using the API starts with establishing a connection to the database server by creating an instance of the Conn class with the parameters backend, host and port, e.g.
 == Executing statements ==