PreparedStatement.h File Reference

Macros | Typedefs | Functions
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 calling Connection_prepareStatement().

Consider this statement:

     INSERT INTO employee(name, picture) VALUES(?, ?)

There are two in parameters in this statement, the parameter for setting the name has index 1 and the one for the picture has index 2. To set the values for the in parameters we use a setter method. Assuming name has a string value we use PreparedStatement_setString(). To set the value of the picture we submit a binary value using the method PreparedStatement_setBlob().

Note that string and blob parameter values are set by reference and 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 employee(name, picture) VALUES(?, ?)");
    PreparedStatement_setString(p, 1, "Kamiya Kaoru");
    PreparedStatement_setBlob(p, 2, jpeg, jpeg_size);
    PreparedStatement_execute(p);

### Reuse:

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 employee(name, picture) VALUES(?, ?)");
    for (int i = 0; employees[i].name; i++)
    {
           PreparedStatement_setString(p, 1, employees[i].name);
           PreparedStatement_setBlob(p, 2, employees[i].picture, employees[i].picture_size);
           PreparedStatement_execute(p);
    }

### Result Sets:

Here is another example where we use a Prepared Statement to execute a query which returns a Result Set:

    PreparedStatement_T p = Connection_prepareStatement(con, "SELECT id FROM employee WHERE name LIKE ?");
    PreparedStatement_setString(p, 1, "%Kaoru%");
    ResultSet_T r = PreparedStatement_executeQuery(p);
    while (ResultSet_next(r))
           printf("employee.id = %d\n", ResultSet_getInt(r, 1));

A ResultSet returned from PreparedStatement_executeQuery() "lives" until the Prepared Statement is executed again or until the Connection is returned to the Connection Pool.

### Date and Time

PreparedStatement provides PreparedStatement_setTimestamp() for setting a Unix timestamp value. To set SQL Date, Time or DateTime values, simply use PreparedStatement_setString() with a time string format understood by your database. For instance to set a SQL Date value,

      PreparedStatement_setString(p, parameterIndex, "2013-12-28");

A PreparedStatement is reentrant, but not thread-safe and should only be used by one thread (at the time).

See Also
  Connection.h ResultSet.h SQLException.h

## Macros
#define | T PreparedStatement_T

## Typedefs
typedef struct PreparedStatement_S * | T

## Functions
void | 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. More...
ResultSet_T | PreparedStatement_executeQuery (T P)
| Executes the prepared SQL statement, which returns a single ResultSet object. More...
long long | PreparedStatement_rowsChanged (T P)
| Returns the number of rows that was inserted, deleted or modified by the most recently completed SQL statement on the database connection. More...
Parameters
void | PreparedStatement_setString (T P, int parameterIndex, const char *x)
| Sets the in parameter at index `parameterIndex` to the given string value. More...
void | PreparedStatement_setInt (T P, int parameterIndex, int x)
| Sets the in parameter at index `parameterIndex` to the given int value. More...
void | PreparedStatement_setLLong (T P, int parameterIndex, long long x)
| Sets the in parameter at index `parameterIndex` to the given long long value. More...
void | PreparedStatement_setDouble (T P, int parameterIndex, double x)
| Sets the in parameter at index `parameterIndex` to the given double value. More...
void | PreparedStatement_setBlob (T P, int parameterIndex, const void *x, int size)
| Sets the in parameter at index `parameterIndex` to the given blob value. More...
void | PreparedStatement_setTimestamp (T P, int parameterIndex, time_t x)
| Sets the in parameter at index `parameterIndex` to the given Unix timestamp value. More...
Properties
int | PreparedStatement_getParameterCount (T P)
| Returns the number of parameters in this prepared statement. More...

## Macro Definition Documentation

#define T PreparedStatement_T

## Typedef Documentation

typedef struct PreparedStatement_S* T

## Function Documentation

void 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. NULL is allowed to indicate a SQL NULL value.

Exceptions

  SQLException | If a database access error occurs or if parameter index is out of range

See Also
  SQLException.h

void PreparedStatement_setInt | ( | T | P,
|  | int | parameterIndex,
|  | int | x
| ) |  |

Sets the in parameter at index `parameterIndex` to the given int value.

In general, on both 32 and 64 bits architecture, `int` is 4 bytes or 32 bits and `long long` is 8 bytes or 64 bits. A `long` type is usually equal to `int` on 32 bits architecture and equal to `long long` on 64 bits architecture. However, the width of integer types are architecture and compiler dependent. The above is usually true, but not necessarily.

Parameters

  P | A PreparedStatement object
  parameterIndex | The first parameter is 1, the second is 2,..
  x | The int value to set

Exceptions

  SQLException | If a database access error occurs or if parameter index is out of range

See Also
  SQLException.h

void PreparedStatement_setLLong | ( | T | P,
|  | int | parameterIndex,
|  | long long | x
| ) |  |

Sets the in parameter at index `parameterIndex` to the given long long value.

In general, on both 32 and 64 bits architecture, `int` is 4 bytes or 32 bits and `long long` is 8 bytes or 64 bits. A `long` type is usually equal to `int` on 32 bits architecture and equal to `long long` on 64 bits architecture. However, the width of integer types are architecture and compiler dependent. The above is usually true, but not necessarily.

Parameters

  P | A PreparedStatement object
  parameterIndex | The first parameter is 1, the second is 2,..
  x | The long long value to set

Exceptions

  SQLException | If a database access error occurs or if parameter index is out of range

See Also
  SQLException.h

void 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

Exceptions

  SQLException | If a database access error occurs or if parameter index is out of range

See Also
  SQLException.h

void 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

Exceptions

  SQLException | If a database access error occurs or if parameter index is out of range

See Also
  SQLException.h

void PreparedStatement_setTimestamp | ( | T | P,
|  | int | parameterIndex,
|  | time_t | x
| ) |  |

Sets the in parameter at index `parameterIndex` to the given Unix timestamp value.

The timestamp value given in `x` is expected to be in the GMT timezone. For instance, a value returned by time(3) which represents the system's notion of the current Greenwich time. SQLite does not have temporal SQL data types per se and using this method with SQLite will store the timestamp value as a numerical type as-is. This is usually what you want anyway, since it is fast, compact and unambiguous.

Parameters

  P | A PreparedStatement object
  parameterIndex | The first parameter is 1, the second is 2,..
  x | The GMT timestamp value to set. E.g. a value returned by time(3)

Exceptions

  SQLException | If a database access error occurs or if parameter index is out of range

See Also
  SQLException.h ResultSet_getTimestamp

void 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

Exceptions

  SQLException | If a database error occurs

See Also
  SQLException.h

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.

Exceptions

  SQLException | If a database error occurs

See Also
  ResultSet.h
  SQLException.h

long long PreparedStatement_rowsChanged | ( | T | P | ) |

Returns the number of rows that was inserted, deleted or modified by the most recently completed SQL statement on the database connection.

If used with a transaction, this method should be called before commit is executed, otherwise 0 is returned.

Parameters

  P | A PreparedStatement object

Returns
  The number of rows changed by the last (DIM) SQL statement

int PreparedStatement_getParameterCount | ( | T | P | ) |

Returns the number of parameters in this prepared statement.

Parameters

  P | A PreparedStatement object

Returns
  The number of parameters in this prepared statement

Copyright © Tildeslash Ltd. All rights reserved.