Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

SQLDBC::SQLDBC_Statement Class Reference

#include <SQLDBC.h>

Inheritance diagram for SQLDBC::SQLDBC_Statement:

SQLDBC::SQLDBC_ConnectionItem SQLDBC::SQLDBC_PreparedStatement List of all members.

Detailed Description

An SQLDBC_Statement is a class for executing SQL statements immediately.

With this class applications can handle all DDL and DML commands without parameter markers. Parameter markers are the '?' or ':<name>' tags. Use SQLDBC_Connection::createStatement from the connection object to get a new SQLDBC_Statement object.

Use the execute() member function to execute the SQL statement.

The SQL statement may contain ASCII or UCS2 characters and must not be zero-terminated. The execute() member function converts it automatically to the correct code set according to the encoding of the database. In this way it is possible to write portable code for UNICODE and non-UNICODE databases. To increase performance, applications should use UCS2 statements only for UNICODE databases.

Example:
Execution of a SQL statement
   SQLDBC_Statement *stmt = conn->createStatement();
   SQLDBC_Retcode rc = stmt->execute("SELECT * FROM DUAL");
   if (rc != SQLDBC_OK) {
     // Handle error ...
   }
   

After execution, the application must check the return code of the command. If an SQL error occurred the error() member function returns error details.

See also:
SQLDBC_ErrorHndl for more informations.
Query statements like SELECT or CALL DBPROC commands may produce a result set. Applications should check this with the isQuery() or getResultSet() member function.

Example:
Check if a result set exists.
   if (stmt->isQuery()) {
      SQLDBC_ResultSet *result = stmt->getResultSet();
      // Retrieving result ...
   }
   

The getResultSet() member function returns a reference to an SQLDBC_ResultSet object. Applications can use SQLDBC_ResultSet for retrieving data from the result set of the query statement or to navigate within result sets. An opened result set is automatically closed by reusing the execute() member function or by closing the object with an SQLDBC_Connection::releaseStatement().

See also:
SQLDBC_ResultSet for more informations about result sets.
Prior to executing an SQL statement, the application can set the name of the result set with the setCursorName() member function, or it can set the type of the result set with setResultSetType() to modify the behavior of the result set.

For non-query SQL statements the application can check the number of modified rows with the getRowsAffected() member function.

Note:
:

Definition at line 1625 of file SQLDBC.h.

Public Types

Public Methods

Protected Methods


Member Enumeration Documentation

enum SQLDBC::SQLDBC_Statement::ConcurrencyType
 

Enumeration values:
CONCUR_UPDATABLE  The result can be updated (FOR UPDATE).
CONCUR_READ_ONLY  The result cannot be updated.

Definition at line 1893 of file SQLDBC.h.

enum SQLDBC::SQLDBC_Statement::HoldabilityType
 

Enumeration values:
CURSOR_HOLD_OVER_COMMIT  The result persists after a COMMIT command.
CURSOR_CLOSE_ON_COMMIT  The result is closed on COMMIT.

Definition at line 1914 of file SQLDBC.h.

enum SQLDBC::SQLDBC_Statement::ResultSetType
 

Enumeration values:
FORWARD_ONLY  The result set can be scrolled forward only.
SCROLL_SENSITIVE  The content of the result set may change.
SCROLL_INSENSITIVE  The content of the result set cannot not change (FOR REUSE).

Definition at line 1853 of file SQLDBC.h.


Member Function Documentation

const SQLDBC_Retcode SQLDBC::SQLDBC_Statement::addBatch const char *    sql
 

Adds a statement to the batch.

The must be end with a zero-terminator and in ASCII code.

Parameters:
sql The statement to be added
Returns:
SQLDBC_OK on success

const SQLDBC_Retcode SQLDBC::SQLDBC_Statement::addBatch const char *    sql,
SQLDBC_StringEncoding    encoding
 

Adds a statement to the batch.

The must be end with a zero-terminator.

Parameters:
sql The statement to be added
encoding Encoding of the statement
Returns:
SQLDBC_OK on success

const SQLDBC_Retcode SQLDBC::SQLDBC_Statement::addBatch const char *    sql,
SQLDBC_Length    sqlLength,
SQLDBC_StringEncoding    encoding
 

Adds a statement to the batch.

Statements for batched execution must not return result sets.

Parameters:
sql The statement to be added
sqlLength Length in Bytes of the statement
encoding Encoding of the statement
Returns:
SQLDBC_OK on success
See also:
addBatch()

void SQLDBC::SQLDBC_Statement::clearBatch  
 

Clears the array of batched statements.

void SQLDBC::SQLDBC_ConnectionItem::clearError   [inherited]
 

Deletes the error has been stored.

void SQLDBC::SQLDBC_Statement::clearResultSet   [protected]
 

void SQLDBC::SQLDBC_ConnectionItem::clearWarnings   [inherited]
 

Deletes the warning stored in the SQLWarning object.

SQLDBC_ErrorHndl& SQLDBC::SQLDBC_ConnectionItem::error   [inherited]
 

Returns a reference to the ErrorHndl object.

Note:
Applications should retrieve the content of the SQLDBC_ErrorHndl object immediatly since an new call to any SQLDBC function except the warning() method will empty SQLDBC_ErrorHndl object.
Returns:
An SQLDBC_ErrorHndl object.

SQLDBC_Retcode SQLDBC::SQLDBC_Statement::execute const char *    sql
 

Executes an ASCII coded zero-terminated SQL statement.

The SQL statement is executed immediately on sending a DBS request to the database. In case of an error, the SQLDBC_ErrorHndl object (to be queried using error()) of this object is set. If the executed SQL statement is a query, a result set is created. The application can check this using isQuery(), and obtain retrieve the resultset using getResultSet().

Parameters:
sql The zero-terminated ASCII coded SQL statement to be execute.
Returns:
SQLDBC_OK on success, or else SQLDBC_NOT_OK. In this case check the error instance.

SQLDBC_Retcode SQLDBC::SQLDBC_Statement::execute const char *    sql,
const SQLDBC_StringEncoding    encoding
 

Executes an UNICODE/ASCII coded zero-terminated SQL statement.

The SQL statement is executed immediately on sending a DBS request to the database. In case of an error, the SQLDBC_ErrorHndl object (to be queried using error()) of this object is set. If the executed SQL statement is a query, a result set is created. The application can check this using isQuery(), and obtain retrieve the resultset using getResultSet().

Parameters:
sql The zero-terminated SQL statement to be executed. The coding of this string argument depends from the encoding argument.
encoding The character coding of the SQL statement.
Returns:
SQLDBC_OK on success, or else SQLDBC_NOT_OK. In this case check the error instance.

SQLDBC_Retcode SQLDBC::SQLDBC_Statement::execute const char *    sql,
const SQLDBC_Length    sqlLength,
const SQLDBC_StringEncoding    encoding
 

Executes an UNICODE/ASCII coded SQL statement.

The SQL statement is executed immediately on sending a DBS request to the database. In case of an error, the SQLDBC_ErrorHndl object (to be queried using error()) of this object is set. If the executed SQL statement is a query, a result set is created. The application can check this using isQuery(), and obtain retrieve the ResultSet using getResultSet().

Parameters:
sql The SQL statement to be executed. The coding of this string argument depends from the encoding argument.
sqlLength The length in bytes of the of the SQL statement
encoding The character coding of the SQL statement
Returns:
SQLDBC_OK on success, or else SQLDBC_NOT_OK. In this case check the error instance.

const SQLDBC_Retcode SQLDBC::SQLDBC_Statement::executeBatch  
 

Executes the statements previously input via addBatch().

Returns:
SQLDBC_OK on success, SQLDBC_NOT_OK on error, SQLDBC_NO_DATA_FOUND if there are no SQL statements to execute.

const SQLDBC_UInt4 SQLDBC::SQLDBC_Statement::getBatchSize   const
 

Returns the size of the row status array.

Returns:
The number of elements of the row status array, which is also the number of array elements that are used for batch execution.

SQLDBC_Retcode SQLDBC::SQLDBC_Statement::getCursorName char *    buffer,
const SQLDBC_StringEncoding    encoding,
const SQLDBC_Length    bufferSize,
SQLDBC_Length   bufferLength
const
 

Retrieves the cursor name.

The cursor name may be set by:

  • The setCursorName() member function
  • A named query statement
  • A database procedure returning a result table

Parameters:
buffer The buffer into which the zero-terminated cursor name is copied.
encoding Encoding of the buffer where the cursor name is stored.
bufferSize Maximum size of the buffer in bytes.
bufferLength [out] Number of bytes copied to the buffer, except the number of bytes necessary for the zero-terminator. If the source string exceeds the bufferSize. SQLDBC_DATA_TRUNC will be returned and the bufferLength set to the number of bytes (except terminator bytes) needed to copy without truncation.
Returns:
SQLDBC_OK on success, SQLDBC_DATA_TRUNC if the provided buffer wasn't able store the complete name.
See also:
setCursorName

SQLDBC_Retcode SQLDBC::SQLDBC_Statement::getLastInsertedKey SQLDBC_Int4    tag,
SQLDBC_HostType    type,
void *    paramAddr,
SQLDBC_Length   lengthIndicator,
SQLDBC_Length    size,
SQLDBC_Bool    terminate = SQLDBC_TRUE
 

Retrieves the key that was inserted by the last insert operation.

Parameters:
tag The tag that describes whether to get the last or the first serial key. One of SQLDBC_FIRST_INSERTED_SERIAL, SQLDBC_LAST_INSERTED_SERIAL.
type The output host type.
paramAddr The parameter address.
lengthIndicator The length or indicator value.
size The size of the output parameter, in bytes.
terminate Whether output strings are terminated. Default is SQLDBC_TRUE.
Returns:
SQLDBC_OK, if the value is returned, SQLDBC_NOT_OK if an error is set, SQLDBC_NO_DATA_FOUND if the statement didn't inserted any key, or didn't report them to the interface.

const SQLDBC_UInt4 SQLDBC::SQLDBC_Statement::getMaxRows   const
 

Returns the maximum number of rows allowed in a result set.

This value may be set with setMaxRows before the execution of an SQL statement.

Returns:
Maximum number of rows of a result set.
See also:
setMaxRows

SQLDBC_ResultSet* SQLDBC::SQLDBC_Statement::getResultSet  
 

Retrieves a reference to the SQLDBC_ResultSet object.

Returns:
A reference to an SQLDBC_ResultSet object if the statement object has a result set, NULL otherwise.
See also:
isQuery

const ConcurrencyType SQLDBC::SQLDBC_Statement::getResultSetConcurrencyType   const
 

Retrieves the type of the result set concurrency.

There are two kinds of concurrency:

Returns:
type of the result set concurrency

const ResultSetType SQLDBC::SQLDBC_Statement::getResultSetType   const
 

Returns the type of a result set.

If the requested result set type isn't allowed for this SQL statement, the SQLDBC changes it to an allowed one. Check this with getResultSetType() if the execute() member function returns with a warning.

Returns:
FORWARD_ONLY, SCROLL_SENSITIVE or SCROLL_INSENSITIVE
See also:
setResultSetType
Todo:
Implement this method

const SQLDBC_Int4 SQLDBC::SQLDBC_Statement::getRowsAffected   const
 

Returns the number of rows affected by the executed SQL statement.

This method returns a non-zero value if more than one row was addressed by the SQL statement. If the return value is lower than zero, more than one rows was addressed but the exact number of addressed rows cannot be determined.

Returns:
Number of addressed rows

const SQLDBC_Int4* SQLDBC::SQLDBC_Statement::getRowStatus   const
 

Returns the row status array.

The row status array describes the state of each row. The size of the row status array is increased by each addBatch() function call.

Returns:
A pointer to the first element of the row status array.
See also:
addBatch()

SQLDBC_Retcode SQLDBC::SQLDBC_Statement::getTableName char *    buffer,
const SQLDBC_StringEncoding    encoding,
const SQLDBC_Length    bufferSize,
SQLDBC_Length   bufferLength
const
 

Retrieves the table name (for SELECT FOR UPDATE commands).

Parameters:
buffer The buffer in which into the table name is copied.
encoding Encoding of the buffer where the table name is stored.
bufferSize Size (in bytes) of the buffer
bufferLength [out] Number of bytes copied to the buffer, except the number of bytes necessary for the zero-terminator. If the source string exceeds the bufferSize value SQLDBC_DATA_TRUNC will be returned and the bufferLength set to the number of bytes (except the terminator bytes) needed to copy the table name without truncation.
Returns:
SQLDBC_OK on success, SQLDBC_DATA_TRUNC if the provided buffer wasn't able to store the complete name.

SQLDBC_Bool SQLDBC::SQLDBC_Statement::isQuery   const
 

Checks if the SQL statement is a query.

A statement is a query only if it returns a result set. This can be determined only after execution of the statement object.

Note:
This method is overridden by the SQLDBC_PreparedStatement class, which can determine the query property before the statement is executed.
Returns:
SQLDBC_TRUE if the statement does produce a result set, SQLDBC_FALSE if not, or if it cannot be determined.
See also:
getResultSet

SQLDBC_Retcode SQLDBC::SQLDBC_Statement::setCommandInfo const char *    buffer,
SQLDBC_Length    bufferLength,
SQLDBC_Int4    lineNumber
 

Sets the command info.

Sets the command info and a line number (for example name of programm and current line number). This will be send to the database kernel as part of a parse order. If the kernel runs in a special diagnose mode these information will be stored in a system table and can be used to profile your application. The column info and line number will be unset after the next execute of a SQL command at this statement handle.

Parameters:
buffer The command info.
bufferLength Length in bytes of the buffer. In case a zero-terminated string passed on in the buffer argument, you can set the bufferLength to SQLDBC_NTS. Set bufferLength to SQLDBC_NULL_DATA if you want to unset the command info and line number.
lineNumber The line number.
Returns:
SQLDBC_OK on success, SQLDBC_DATA_TRUNC if the provided buffer was too long or SQLDBC_NOT_OK in case of an error.

void SQLDBC::SQLDBC_Statement::setCursorName const char *    buffer,
SQLDBC_Length    bufferLength,
const SQLDBC_StringEncoding    encoding
 

Sets the cursor name.

Setting the cursorname affects only query and database procedure commands. For DDL-, INSERT-, UPDATE- and DELETE- commands setting the cursorname has no effect.

Parameters:
buffer The new cursor name.
bufferLength Length in bytes of the buffer. In case a zero-terminated string passed on in the buffer argument, you can set the bufferLength to SQLDBC_NTS.
encoding Encoding of the cursor name.
Returns:
none
See also:
getCursorName

void SQLDBC::SQLDBC_Statement::setMaxRows SQLDBC_UInt4    rows
 

Limits the number of rows of an SQLDBC_ResultSet object.

The number of rows of the result set is truncated if the result of a query statement is larger than this limit. The default setting is 'unlimited' (0). Setting this limit does not affect an already executed SQL statement.

Parameters:
rows [in] Maximum number of rows of a result set
Returns:
none
See also:
getMaxRows

void SQLDBC::SQLDBC_Statement::setResultSetConcurrencyType ConcurrencyType    type
 

Sets the type of the result set concurrency.

There are two kinds of concurrency:

The default setting for the concurrency is CONCUR_READ_ONLY

Parameters:
type [in] The result set type. Possible values are: CONCUR_READ_ONLY CONCUR_UPDATABLE
Returns:
none
Todo:
Implement this method

void SQLDBC::SQLDBC_Statement::setResultSetFetchSize SQLDBC_Int2    rows
 

Sets the maximum number of be rows that can be fetched at once.

Sets the maximum number of rows to be fetched from a result set. Use this to manipulate the number of rows in the order interface. Use a value > 0 to set the maximum number of rows. Use a value <= 0 to reset this limit to the default value. The default value is 'unlimited' (32767). Setting this value does not affect an already executed SQL statement.

Parameters:
rows [in] Number of Rows to be fetched.
Returns:
none

void SQLDBC::SQLDBC_Statement::setResultSetType ResultSetType    type
 

Sets the type of a result set.

A result set is only created by a query command.

There are three kind of result sets:

The default for the result set type is SCROLL_INSENSITIVE

Parameters:
type [in] The result set type. Possible values are: FORWARD_ONLY, SCROLL_SENSITIVE, SCROLL_INSENSITIVE
Returns:
none
See also:
getResultSetType
Todo:
Implement this method

SQLDBC_SQLWarning* SQLDBC::SQLDBC_ConnectionItem::warning   [inherited]
 

Returns a reference to an SQLWarning object stored in the SQLDBC_ConnectionItem object.

Note:
Getting the reference to the SQLWarning object will not clear the ErrorHndl object. All other function calls will empty the ErrorHndl object.
Returns:
The SQLWarning object stored in the item.


Friends And Related Function Documentation

friend class SQLDBC_Connection [friend]
 

Connection to the database kernel.

This class combines the functions necesary for managing a connection to the database. If a new connection object is created, it is not connected. The connection to the database is established when a successful connect() call was performed.

Todo:
Check more parameters after connection (version).

Distribute the results of a COMMIT or ROLLBACK statment into dependent objects (for correct handling of PUTVAL commands).

Reimplemented from SQLDBC::SQLDBC_ConnectionItem.

Reimplemented in SQLDBC::SQLDBC_PreparedStatement.

Definition at line 2031 of file SQLDBC.h.

friend class SQLDBC_PreparedStatement [friend]
 

A class for preparing and executing SQL statements.

A prepared SQL command can be parsed and contain input and output parameters. Parameters are marked with a '?' or ':<name>' tag. All DML commands can be parsed. DDL commands can be parsed, too. However, it is not recommended to do so. Prepared SQL commands increase the performance since they are parsed only once and executed several times. Applications only need to change the content of the bound parameters and execute the command again.

All prepared SQL commands are stored in an internally managed ParseInfo Cache . The ParseInfo Cache shares this information with different prepared SQL statements within the same connection.

The SQL statement may contain ASCII or UCS2 characters and must not zero-terminated. The execute() member function converts it to the adequate code set considering the code of the database. Therefore it is possible to write portable code for UNICODE and non-UNICODE databases.

Note:
To increase the performance, applications must use UCS2 statements for UNICODE databases only.
Example:
Preparation and execution of an SQL statement.
   SQLDBC_PrepareStatement *stmt = conn->createPreparedStatement();
   SQLDBC_Retcode rc = stmt->prepare("SELECT * FROM DUAL");
   if (rc != SQLDBC_OK) {
     // Handle error ...
   }
   rc = stmt->execute();
   if (rc != SQLDBC_OK) {
     // Handle error ...
   }
   

Hints:
  • The application must call createPreparedStatement() to retrieve a prepared SQL statement
  • For parsing the SQL statement, call the prepare() member function,
  • For a single-row execution, use the execute() member function,
  • For mass execution, bind arrays of parameter values, use setBatchSize() to set the row array size to the number of array elements bound, and use the execute() method.
  • Use the isQuery() method to check whether the parsed statement creates a result set upon execution.
  • Use SQLDBC_Statement for a direct execution, since the prepared statement inherits all direct-execution functions from SQLDBC_Statement.
  • The current result set is deleted when
    • A new statement is parsed
    • The statement is re-executed
    • The statement is deleted
Todo:
binding parameter by name

Reimplemented from SQLDBC::SQLDBC_ConnectionItem.

Definition at line 2032 of file SQLDBC.h.


The documentation for this class was generated from the following file: