The ITStatement class

Base class: ITErrorManager

The ITStatement class provides support for the execution of prepared queries that return no rows. For information about the use of prepared statements, see Using prepared statements.

This class provides the following methods.


Method	Description
ITStatement (const ITConnection &)	Creates an ITStatement object for the specified connection.
ITBool Prepare(const ITString &, int nargs = 0, const ITString typeNames = NULL, ITEssential *outerunkns = 0)	Prepare() prepares the statement and creates a list of null-valued parameters. Prepare() takes as an argument an ITString object, which must be a single valid SQL statement. The names of the server types of the parameters that will be created can be supplied as an array of ITStrings. If an application does not provide parameter type names, this method uses parameter types communicated by the server. In the cases when the server does not communicate parameter types (as with UPDATE and DELETE queries) and they are not provided by the application, all parameters are created of the server type varchar(256). The application can provide an array of outer unknown pointers for delegation. After the call to Prepare(), elements of the outer unknowns array (if it was provided) are set to the inner unknowns. If the application provides either type names or outer unknowns, it must set the nargs parameter to their number.
ITBool SetParam(int parmno, ITValue *)	Sets the statement parameter with the number equal to parmno to be the value object passed as the second argument. Returns `TRUE` if successful, `FALSE` if it fails. The previous parameter object is released. Supports binding parameters in both binary and text mode. For more information, see the example in Usage.
int NumParams() const	Returns the number of parameters in a prepared statement. It returns `-1` if the statement has not been successfully prepared.
ITValue *Param(int)	Allows the application to return a ITValue of a parameter. The argument is a zero-based parameter number. Parm() returns `NULL` if there are no parameters or if the parameter number is out of bounds.
const ITString &Command() const	Returns an SQL command verb. Returns ITString::Null if the statement has not been successfully prepared.
const ITString &QueryText() const	Returns the query text. Returns ITString::Null if the statement has not been successfully prepared.
ITBool Exec()	Executes a prepared statement with the current parameter values. Returns `TRUE` if the execution was successful, `FALSE` if it was not. If the query returns rows, Exec() discards them.
long RowCount() const	Returns the number of rows affected by the last execution. Returns `-1` if the statement has not been executed.
ITBool Drop()	Drops the prepared statement and removes the parameter list.

Usage

ITStatement can pass binary data as parameters in prepared SQL DML statements DELETE, INSERT, UPDATE, and SELECT. In addition, SQL SELECT statements with parameters can be executed by using class ITCursor.

The following example shows how can be used to set a parameter to binary data in a prepared INSERT statement. The example uses the table CUSTOMER in the demonstration database STORES7:

#include <it.h>
#include <iostream.h>

int main()
{
    ITDBInfo db("stores7");
    ITConnection conn(db);

    conn.Open();

    if( conn.Error() )
    {
        cout << "Couldn't open connection" << endl;
        return -1;
    }
    ITQuery query( conn );
    ITRow *row;
    // Create the value object encapsulating the datum of SQL type CHAR(15)
    // by fetching a row from the database and calling ITRow::Column()
    if( !(row = query.ExecOneRow( "select lname from customer;" )) )
    {
        cout << "Couldn't select from table customer" << endl;
        return -1;
    }
    ITValue *col = row->Column( 0 );
    if( !col )
    {
        cout << "couldn't instantiate lname column value" << endl;
        return -1;
    }
    row->Release();
    ITDatum *datum;
    col->QueryInterface( ITDatumIID, (void **)&datum );
    if( !datum )
    {
        cout << "couldn't get lname column datum" << endl;
        return -1;
    }
    col->Release();
    // Prepare SQL INSERT statement, set the parameter to the value object that
    // encapsulates lname column value and execute INSERT
    ITStatement stmt( conn );
    if( !stmt.Prepare( "insert into customer (lname) values ( ? );" ) )
    {
        cout << "Could not prepare insert into table customer" << endl;
        return -1;
    }
    if( !stmt.SetParam( 0, datum ) )
    {
        cout << "Could not set statement parameter" << endl;
        return -1;
    }
    if( !stmt.Exec() )
    {
        cout << "Could not execute the statement" << endl;
        return -1;
    }
    return 0;
}