Notes for Using C++ Driver

The NuoDB C++ API classes are contained in the NuoDB C++ namespace. Your application can use that namespace with the following statement:

A ResultSet behaves differently depending on whether the autocommit property is set on or off. If autocommit is on, you are limited to one active, valid ResultSet. Associated ResultSetMetaData objects, and ResultSet objects returned from Statement::getGeneratedKeys() can also be open at the same time but have the same "shelf life" - They are valid until closed, committed, or another statement is executed by the Statement object. A Statement that returns a ResultSet defers committing the transaction, so iteration over the ResultSet is consistent with the data and the transaction isolation level. Each execution of a Statement will commit any previously deferred transaction and so closes any associated ResultSet.

If autocommit is off, you can have as many ResultSet objects as you need, provided each ResultSet comes from a unique Statement instance. You can not have multiple open ResultSet objects from the same Statement. When a Statement is executed, any currently associated ResultSet is closed and cannot be reopened or reused in any way.

Although we do not support more than one ResultSet from the same Statement, regardless of the autocommit setting, some applications may have success accessing multiple ResultSet objects from the same Statement if the size of the ResultSet was small enough (less than 100KB) for the entire contents of the result to be returned to the client in one response message. In this case, the application can iterate over the ResultSet safely. It is not until the client has to go back to the server for more data that an error occurs. Since the entire ResultSet is already on the client, there is no error. It is not recommended, nor supported, that clients rely on this functionality.

To handle an exception in your client application, catch SQLException. To obtain information about the exception, you can call getSqlcode() or getText() on SQLException. For example, in the case of a lost connection, getSqlcode() returns NETWORK_ERROR, which is -7. For information about error codes, see C++ Driver API Reference and search for NuoDBSqlConstants.

As stated above, much of the NuoDB C++ driver is implemented loosely around the JDBC API. There are a few useful additions to BatchUpdateException. First of all, note that the NuoDB C++ driver, in addition to the NuoDB JDBC driver and any other NuoDB driver that supports executing statement in a batch, will continue executing commands even after the first exception is thrown. Like with JDBC, the NuoDB C++ BatchUpdateException class is derived from SQLException. It is thrown when one or more SQLException exceptions are thrown during a batch update operation. The BatchUpdateException provides the update counts for all commands that were executed successfully during the batch update. The order of elements in the array of update counts corresponds to the order in which commands were added to the batch.

After a command in a batch update fails to execute properly and a BatchUpdateException is thrown, the NuoDB C++ driver continues to process the remaining commands in the batch. The array returned by the method BatchUpdateException.getUpdateCounts() will have an element for every command in the batch rather than only elements for the commands that executed successfully before the error. In the case where the driver continues processing commands, the array element for any command that failed is NuoDB::EXECUTE_FAILED.

In addition to the array returned by getUpdateCounts(), you can also access the SQL code, SQL state and error message text from any command that was unsuccessfully executed in the batch. This is done via the getSqlcode(),getSQLState() and getText() methods which each optionally will take an index corresponding to the command that failed in the batch. If no index is specified, the SQL code, SQL state, or error message text from the first error in the batch will be returned. There is also a getTrace() method which will return the stack trace from the point where the BatchUpdateException was thrown and a getBatchCount() method that will return the number of executed (successful or failed) commands in the batch. For full documentation on the BatchUpdateException API, see the C++ Driver API Reference.

Client connections to a NuoDB database via the C++ driver will support LDAP authentication if enabled in the TE to which the client is connected. See User Authentication Using LDAP for more information.