odbcpp: odbcpp::statement Class Reference

The constructor allocates a statement handle.

This function allocates a statement handle.

The statement is empty.

Parameters:

[in]

conn

The parent connection where this statement will execute.

Exceptions:

odbcpp_error

If the statement handle cannot be allocated, throw an error.

Definition at line 56 of file statement.cpp.

References odbcpp::handle::check(), f_connection, odbcpp::handle::f_handle, and odbcpp::handle::f_handle_type.

Begin an SQL transaction.

This function sends the BEGIN instruction to the driver.

Exceptions:

odbcpp_error

And odbcpp_error will be thrown if the SQL function returns an error.

See also:

execute()

Definition at line 200 of file statement.cpp.

References execute().

Cancel an SQL statement.

This function cancels the last SQL statement sent to the driver with the execute function.

Bug:

With older versions of the ODBC libraries, the cancel() function may actually free the statement under the hood.

Exceptions:

odbcpp_error

And odbcpp_error will be thrown if the SQL function returns an error.

See also:

execute()

Definition at line 250 of file statement.cpp.

References odbcpp::handle::check(), odbcpp::handle::f_handle, f_has_data, and has_data().

Stop using the current cursor.

This function cancels the last SQL statement sent to the driver with the execute function.

Bug:

With older versions of the ODBC libraries, the cancel() function may actually free the statement under the hood.

Exceptions:

odbcpp_error

And odbcpp_error will be thrown if the SQL function returns an error.

See also:

execute()

Definition at line 273 of file statement.cpp.

References odbcpp::handle::check(), odbcpp::handle::f_handle, f_has_data, and has_data().

Query the number of cols resulting from a query.

This function must be called after the execute() function was successfully called.

Returns:

The number of rows that the SQL command generated.

Exceptions:

odbcpp_error

And odbcpp_error will be thrown if the SQL function returns an error.

Definition at line 293 of file statement.cpp.

References odbcpp::handle::check(), odbcpp::handle::f_handle, and has_data().

Commit an SQL transaction.

This function sends the COMMIT instruction to the driver.

Exceptions:

odbcpp_error

And odbcpp_error will be thrown if the SQL function returns an error.

See also:

execute()

Definition at line 215 of file statement.cpp.

References execute().

Execute an SQL statement.

This function executes an SQL statement. The result is kept with the statement object and can be queried after this call.

The execution of SQL statements happen in the backend (the server) and thus are asynchroneous. If a statement is too long, it can be stopped using the cancel() function.

Parameters:

[in]

order

The SQL order(s) to send the database

Exceptions:

odbcpp_error

And odbcpp_error will be thrown if the SQL function returns an error.

See also:

fetch()

cols()

rows()

cancel()

Definition at line 156 of file statement.cpp.

References odbcpp::handle::check(), odbcpp::handle::f_handle, and f_has_data.

Referenced by begin(), commit(), and rollback().

Fetch one row at the specified position.

The fetch() function reads one row of data. Right after a call to the execute() function, you need to call the fetch() function before you can retrieve data.

The orientation and offset pair is defined as follow:

          Orientation                Offset

        SQL_FETCH_NEXT           Unused
        SQL_FETCH_PRIOR          Unused
        SQL_FETCH_FIRST          Unused
        SQL_FETCH_LAST           Unused
        SQL_FETCH_ABSOLUTE       The exact position
        SQL_FETCH_RELATIVE       Added to the current position
        SQL_FETCH_BOOKMARK       Offset in the SQL_ATTR_FETCH_BOOKMARK_PTR array

Parameters:

[in,out]	rec	The record where the row data is saved
[in]	orientation	The direction for the offset
[in]	offset	The offset used to move to that position to fetch

Returns:

true if the function fetched a row, false if there is no more data

Todo:

We need to handle truncated data. When a string buffer is too small, we need to enlarge it and try to read the row again (too bad that we cannot cleanly query the size of the cell as required!)

Bug:

At this time, the function handles the SQL_STILL_EXECUTING return code as an error and generates an exception. I think that calling the rows() function first will prevent this problem.

Bug:

Some ODBC drivers may not support all the orientations. If you do not specify the orientation nor the offset, the simple SQLFetch() function will be used as it has the same effect as the SQL_FETCH_NEXT orientation.

Exceptions:

odbcpp_error

And odbcpp_error will be thrown if the SQL function returns an error.

See also:

rows()

execute()

Definition at line 376 of file statement.cpp.

References odbcpp::record_base::bind(), odbcpp::handle::check(), odbcpp::handle::f_handle, f_no_direct_fetch, odbcpp::record_base::finalize(), and has_data().

Function used to check whether data is available.

Whenever the statement is queried for some kind of data, this function is called. If no SQL data is available, this function generates an exception.

SQL data is available only after a call to execute() and until one of close_cursor(), cancel() and alike functions is called.

Exceptions:

odbcpp_error

This error is thrown if the statement has not yet executed a valid SQL statement. If the last statement executed generated an error, then this function also throws the error.

Definition at line 182 of file statement.cpp.

References f_has_data, and odbcpp::odbcpp_error::ODBCPP_NO_DATA.

Referenced by cancel(), close_cursor(), cols(), fetch(), and rows().

Rollback an SQL transaction.

This function sends the ROLLBACK instruction to the driver.

Exceptions:

odbcpp_error

And odbcpp_error will be thrown if the SQL function returns an error.

See also:

execute()

Definition at line 230 of file statement.cpp.

References execute().

Query the number of rows resulting from a query.

This function must be called after the execute() function was successfully called.

Returns:

The number of rows that the SQL command generated.

Exceptions:

odbcpp_error

And odbcpp_error will be thrown if the SQL function returns an error.

Definition at line 316 of file statement.cpp.

References odbcpp::handle::check(), odbcpp::handle::f_handle, and has_data().

Set a pointer statement attribute.

This function sets one attribute in the statement.

Parameters:

[in]	attr	The attribute to be modified
[in]	ptr	The pointer to the attribute data
[in]	length	The size of the data pointed by ptr, can be SQL_NTS for strings

Exceptions:

odbcpp_error

And odbcpp_error will be thrown if the SQL function returns an error.

Definition at line 97 of file statement.cpp.

References odbcpp::handle::check(), and odbcpp::handle::f_handle.

Set a integer statement attribute.

This function sets one attribute in the statement.

Parameters:

[in]	attr	The attribute to be modified
[in]	integer	The integer attribute data

Exceptions:

odbcpp_error

And odbcpp_error will be thrown if the SQL function returns an error.

Definition at line 79 of file statement.cpp.

References odbcpp::handle::check(), odbcpp::handle::f_handle, and odbcpp::int_to_ptr().

Set whether the SQLFecth() instruction can be used.

There seems to be a bug in the PostgreSQL driver at this time (v8.2, Ubuntu Hardy) that makes the SQLFecth() command crash. Since there has been talked about marking that function as deprecated, it is not a bad thing to mark it as a "don't use".

However, by default we still keep it since many systems still use it.

Note that to be able to use SQLFetchScroll() you need to make use of a dynamic cursor. For that purpose, you need to call the following first:

 conn.set_attr(SQL_ATTR_CURSOR_TYPE, SQL_CURSOR_DYNAMIC);

Parameters:

[in]

no_direct_fetch

If false, use SQLFecth() when orientation is SQL_FETCH_NEXT, if true, never use SQLFetch(), use SQLFetchScroll() instead.

Definition at line 130 of file statement.cpp.

References f_no_direct_fetch.

A pointer to the parent connection.

Each statement is created within a specific connection. This is the pointer back to the parent connection.

Definition at line 54 of file statement.h.

Referenced by statement().

Defines whether data is available.

This variable is set to true after each successful execute() call. This enables the object to have a state and avoid fetching data if the last execute failed or execute was not called.

Definition at line 55 of file statement.h.

Referenced by cancel(), close_cursor(), execute(), and has_data().

Defines whether SQLFetch() can be used.

This variable determines whether the SQLFetch() function can be used or not. By default, the function is used if the orientation is set to SQL_FETCH_NEXT.

There are cases when it is better to always use the SQLFetchScroll() function. In these cases cann the set_no_direct_fetch() function to avoid the SQLFetch() function altogether.

See also:

statement::set_no_direct_fetch()

Definition at line 56 of file statement.h.

Referenced by fetch(), and set_no_direct_fetch().