PreparedStatement.h File Reference


Detailed Description

A PreparedStatement represent a single SQL statement pre-compiled into byte code for later execution.

The SQL statement may contain IN parameters of the form "?". Such parameters represent unspecified literal values (or "wildcards") to be filled in later by the various setter methods defined in this interface. Each IN parameter has an associated index number which is its sequence in the statement. The first IN '?' parameter has index 1, the next has index 2 and so on. A PreparedStatement is created by the Connection_prepareStatement() method.

Consider this statement:

  INSERT INTO blobs(key, value) VALUES(?, ?)
 
There are two IN parameters in this statement, the parameter for setting the value of the key has index 1 and the one for the blob has index 2. To set the values for the IN parameters we use a setter method. Assuming key has a string value we use PreparedStatement_setString(). To set the value of the blob we submit a binary value using the method PreparedStatement_setBlob().

Please note that parameter values set in one of the setXXX methods must not "disappear" before either PreparedStatement_execute() or PreparedStatement_executeQuery() is called.

Example:

To summarize, here is the code in context.

 PreparedStatement_T p= Connection_prepareStatement(con, "INSERT INTO blobs(key, value) VALUES(?, ?)");
 PreparedStatement_setString(p, 1, "picture1");
 PreparedStatement_setBlob(p, 2, blob, size);
 PreparedStatement_execute(p);
 

Reuse and ResultSets:

A PreparedStatement can be reused. That is, the method PreparedStatement_execute() can be called one or more times to execute the same statement. Clients can also set new IN parameter values and re-execute the statement as shown in this example:

 PreparedStatement_T p= Connection_prepareStatement(con, "INSERT INTO blobs(key, value) VALUES(?, ?)");
 for(i= 0; data[i]; i++) {
        PreparedStatement_setString(p, 1, data[i].key);
        PreparedStatement_setBlob(p, 2, data[i].value, data[i].size);
        PreparedStatement_execute(p);
}
 
Note, if PreparedStatement_executeQuery() returns a ResultSet then this ResultSet "lives" only until the next call to a PreparedStatement execute method or until the Connection is returned to the Connection Pool.

See also:
Connection.h ResultSet.h


Defines

#define T   PreparedStatement_T

Typedefs

typedef TT

Functions

int PreparedStatement_setString (T P, int parameterIndex, const char *x)
 Sets the IN parameter at index parameterIndex to the given string value.
int PreparedStatement_setInt (T P, int parameterIndex, int x)
 Sets the IN parameter at index parameterIndex to the given int value.
int PreparedStatement_setLLong (T P, int parameterIndex, long long int x)
 Sets the IN parameter at index parameterIndex to the given long long value.
int PreparedStatement_setDouble (T P, int parameterIndex, double x)
 Sets the IN parameter at index parameterIndex to the given double value.
int PreparedStatement_setBlob (T P, int parameterIndex, const void *x, int size)
 Sets the IN parameter at index parameterIndex to the given blob value.
int PreparedStatement_execute (T P)
 Executes the prepared SQL statement, which may be an INSERT, UPDATE, or DELETE statement or an SQL statement that returns nothing, such as an SQL DDL statement.
ResultSet_T PreparedStatement_executeQuery (T P)
 Executes the prepared SQL statement, which returns a single ResultSet object.


Define Documentation

#define T   PreparedStatement_T
 


Typedef Documentation

typedef struct T* T
 


Function Documentation

int PreparedStatement_setString T  P,
int  parameterIndex,
const char *  x
 

Sets the IN parameter at index parameterIndex to the given string value.

Parameters:
P A PreparedStatement object
parameterIndex the first parameter is 1, the second is 2,..
x The string value to set. Must be a NUL terminated string.
Returns:
FALSE if a database error occurred, such as the parameter index is out of range, otherwise TRUE

int PreparedStatement_setInt T  P,
int  parameterIndex,
int  x
 

Sets the IN parameter at index parameterIndex to the given int value.

Parameters:
P A PreparedStatement object
parameterIndex the first parameter is 1, the second is 2,..
x The int value to set
Returns:
FALSE if a database error occurred, such as the parameter index is out of range, otherwise TRUE

int PreparedStatement_setLLong T  P,
int  parameterIndex,
long long int  x
 

Sets the IN parameter at index parameterIndex to the given long long value.

Parameters:
P A PreparedStatement object
parameterIndex the first parameter is 1, the second is 2,..
x The long long value to set
Returns:
FALSE if a database error occurred, such as the parameter index is out of range, otherwise TRUE

int PreparedStatement_setDouble T  P,
int  parameterIndex,
double  x
 

Sets the IN parameter at index parameterIndex to the given double value.

Parameters:
P A PreparedStatement object
parameterIndex the first parameter is 1, the second is 2,..
x The double value to set
Returns:
FALSE if a database error occurred, such as the parameter index is out of range, otherwise TRUE

int PreparedStatement_setBlob T  P,
int  parameterIndex,
const void *  x,
int  size
 

Sets the IN parameter at index parameterIndex to the given blob value.

Parameters:
P A PreparedStatement object
parameterIndex the first parameter is 1, the second is 2,..
x The blob value to set
size the number of bytes in the blob
Returns:
FALSE if a database error occurred, such as the parameter index is out of range, otherwise TRUE

int PreparedStatement_execute T  P  ) 
 

Executes the prepared SQL statement, which may be an INSERT, UPDATE, or DELETE statement or an SQL statement that returns nothing, such as an SQL DDL statement.

Parameters:
P A PreparedStatement object
Returns:
TRUE on success otherwise FALSE on error and the method Connection_getLastError() can be used to obtain the error string.

ResultSet_T PreparedStatement_executeQuery T  P  ) 
 

Executes the prepared SQL statement, which returns a single ResultSet object.

A ResultSet "lives" only until the next call to a PreparedStatement method or until the Connection is returned to the Connection Pool. This means that Result Sets cannot be saved between queries.

Parameters:
P A PreparedStatement object
Returns:
A ResultSet object that contains the data produced by the prepared statement. If there was an error NULL is returned and the method Connection_getLastError() can be used to obtain the error string.
See also:
ResultSet.h

 


Copyright © 2006 Tildeslash Ltd. All rights reserved.