PreparedStatement.h File Reference

⬅
Macros | Typedefs
PreparedStatement.h File Reference

## Detailed Description

A PreparedStatement represents 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, photo) VALUES(?, ?)

There are two in parameters in this statement, the parameter for setting the name has index 1 and the one for the photo 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 photo we submit a binary value using the method PreparedStatement_setBlob().

## Example

To summarize, here is the code in context.

PreparedStatement_T p = Connection_prepareStatement(con, "INSERT INTO employee(name, photo) VALUES(?, ?)");
PreparedStatement_setString(p, 1, "Kamiya Kaoru");
PreparedStatement_setBlob(p, 2, jpeg, jpeg_size);
PreparedStatement_execute(p);
Connection_prepareStatement
PreparedStatement_T Connection_prepareStatement(T C, const char *sql,...)
Prepares a SQL statement for execution.
PreparedStatement_setString
void PreparedStatement_setString(T P, int parameterIndex, const char *x)
Sets the in parameter at index parameterIndex to the given string value.
PreparedStatement_execute
void PreparedStatement_execute(T P)
Executes the prepared SQL statement.
PreparedStatement_setBlob
void PreparedStatement_setBlob(T P, int parameterIndex, const void *x, int size)
Sets the in parameter at index parameterIndex to the given blob value.

## 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, photo) VALUES(?, ?)");
for (int i = 0; employees[i]; i++)
{
PreparedStatement_setString(p, 1, employees[i].name);
PreparedStatement_setBlob(p, 2, employees[i].photo.data, employees[i].photo.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, "%oru%");
ResultSet_T r = PreparedStatement_executeQuery(p);
while (ResultSet_next(r))
printf("employee.id = %d\n", ResultSet_getInt(r, 1));
PreparedStatement_executeQuery
ResultSet_T PreparedStatement_executeQuery(T P)
Executes the prepared SQL query.
ResultSet_next
bool ResultSet_next(T R)
Moves the cursor to the next row.
ResultSet_getInt
int ResultSet_getInt(T R, int columnIndex)
Gets the designated column's value as an int.

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

## Date and Time

PreparedStatement_setTimestamp() can be used to set a Unix timestamp value as a `time_t` type. To set Date, Time or DateTime values, simply use PreparedStatement_setString() to set a time string in a format understood by your database. For instance to set a SQL Date value,,

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

## SQL Injection Prevention

Prepared Statement is particularly useful when dealing with user-submitted data, as properly used Prepared Statements provide strong protection against SQL injection attacks. By separating SQL logic from data, PreparedStatements ensure that user input is treated as data only, not as part of the SQL command.

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

Note
  Remember that parameter indices in PreparedStatement are 1-based, not 0-based.
  To minimizes memory allocation and avoid unnecessary data copying, string and blob values are set by reference and MUST remain valid until either PreparedStatement_execute() or PreparedStatement_executeQuery() is called.

See also
  Connection.h ResultSet.h SQLException.h

## Macros
#define | T PreparedStatement_T

## Typedefs
typedef struct PreparedStatement_S * | T

## Functions
Parameters
void | PreparedStatement_setString (T P, int parameterIndex, const char *x)
| Sets the in parameter at index `parameterIndex` to the given string value.
void | PreparedStatement_setSString (T P, int parameterIndex, const char *x, int size)
| Sets the in parameter at index `parameterIndex` to the given `sized` string value.
void | PreparedStatement_setInt (T P, int parameterIndex, int x)
| Sets the in parameter at index `parameterIndex` to the given int value.
void | PreparedStatement_setLLong (T P, int parameterIndex, long long x)
| Sets the in parameter at index `parameterIndex` to the given long long value.
void | PreparedStatement_setDouble (T P, int parameterIndex, double x)
| Sets the in parameter at index `parameterIndex` to the given double value.
void | PreparedStatement_setBlob (T P, int parameterIndex, const void *x, int size)
| Sets the in parameter at index `parameterIndex` to the given blob value.
void | PreparedStatement_setTimestamp (T P, int parameterIndex, time_t x)
| Sets the in parameter at index `parameterIndex` to the given Unix timestamp value.
void | PreparedStatement_setNull (T P, int parameterIndex)
| Sets the in parameter at index `parameterIndex` to SQL NULL.
Functions
void | PreparedStatement_execute (T P)
| Executes the prepared SQL statement.
ResultSet_T | PreparedStatement_executeQuery (T P)
| Executes the prepared SQL query.
long long | PreparedStatement_rowsChanged (T P)
| Gets the number of rows affected by the most recent SQL statement.
Properties
int | PreparedStatement_getParameterCount (T P)
| Gets the number of parameters in the prepared statement.

## Macro Definition Documentation

## ◆ T

#define T PreparedStatement_T

## Typedef Documentation

## ◆ T

typedef struct PreparedStatement_S* T

## Function Documentation

## ◆ PreparedStatement_setString()

void PreparedStatement_setString | ( | T | P,
|  | int | parameterIndex,
|  | const char * | x )

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

This method is less efficient than PreparedStatement_setSString() as it needs to calculate the string length. Use PreparedStatement_setSString() if you know the size of the string.

Parameters

  P | A PreparedStatement object
  parameterIndex | The first parameter is 1, the second is 2, ...
  x | The string value to set. The string must be a '\0' terminated C-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
  PreparedStatement_setSString

## ◆ PreparedStatement_setSString()

void PreparedStatement_setSString | ( | T | P,
|  | int | parameterIndex,
|  | const char * | x,
|  | int | size )

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

This method is more efficient than PreparedStatement_setString() as it doesn't need to calculate the string length.

Parameters

  P | A PreparedStatement object
  parameterIndex | The first parameter is 1, the second is 2, ...
  x | The string value to set. The string need not be '\0' terminated. NULL is allowed to indicate a SQL NULL value.
  size | The length of the byte string. For instance, the value returned by `strlen(3)`. If size is negative, it will be treated as 0.

Exceptions

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

See also
  SQLException.h
  PreparedStatement_setString

## ◆ PreparedStatement_setInt()

void 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

Exceptions

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

See also
  SQLException.h

## ◆ PreparedStatement_setLLong()

void PreparedStatement_setLLong | ( | T | P,
|  | int | parameterIndex,
|  | long long | 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

Exceptions

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

See also
  SQLException.h

## ◆ PreparedStatement_setDouble()

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

## ◆ PreparedStatement_setBlob()

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. NULL is allowed to indicate a SQL NULL value
  size | The number of bytes in the blob. If size is negative, it will be treated as 0.

Exceptions

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

See also
  SQLException.h

## ◆ PreparedStatement_setTimestamp()

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 a UTC timestamp, representing the number of seconds since the Unix epoch, regardless of the system's local timezone. For instance, a value returned by `time(3)` is appropriate for this parameter.

Note on database-specific behavior:

- SQLite: Stores the time_t value as a 64-bit integer. This preserves the exact UTC timestamp, which can be correctly interpreted in any timezone when retrieved.
- MySQL, PostgreSQL and Oracle: Convert and store the timestamp in their respective datetime formats, preserving the UTC value.

This approach ensures consistent timestamp handling across different timezones and database systems. When retrieving the timestamp, use appropriate time conversion functions to interpret the value in the desired timezone.

Parameters

  P | A PreparedStatement object
  parameterIndex | The first parameter is 1, the second is 2, ...
  x | The UTC 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

## ◆ PreparedStatement_setNull()

void PreparedStatement_setNull | ( | T | P,
|  | int | parameterIndex )

Sets the in parameter at index `parameterIndex` to SQL NULL.

Parameters

  P | A PreparedStatement object
  parameterIndex | The first parameter is 1, the second is 2,..

Exceptions

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

See also
  SQLException.h

## ◆ PreparedStatement_execute()

void PreparedStatement_execute | ( | T | P | ) |

Executes the prepared SQL statement.

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

## ◆ PreparedStatement_executeQuery()

ResultSet_T PreparedStatement_executeQuery | ( | T | P | ) |

Executes the prepared SQL query.

Executes the prepared SQL statement, which returns a single ResultSet object. A ResultSet is valid 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

## ◆ PreparedStatement_rowsChanged()

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

Gets the number of rows affected by the most recent SQL statement.

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

## ◆ PreparedStatement_getParameterCount()

int PreparedStatement_getParameterCount | ( | T | P | ) |

Gets the number of parameters in the prepared statement.

Parameters

  P | A PreparedStatement object

Returns
  The number of in parameters in this prepared statement

Copyright © Tildeslash Ltd. All rights reserved.