C API Prepared Statement Datatypes

Note: The API for prepared statements is still subject to revision. This information is provided for early adopters, but please be aware that the API may change.

Prepared statements mainly use the MYSQL_STMT and MYSQL_BIND data structures. A third structure, MYSQL_TIME, is used to transfer temporal data.

MYSQL_STMT This structure represents a prepared statement. A statement is prepared by calling mysql_prepare(), which returns a statement handle, that is, a pointer to a MYSQL_STMT. The handle is used for all subsequent statement-related functions. The MYSQL_STMT structure has no members that are for application use. Multiple statement handles can be associated with a single connection. The limit on the number of handles depends on the available system resources.
MYSQL_BIND This structure is used both for query input (data values sent to the server) and output (result values returned from the server). For input, it is used with mysql_bind_param() to bind parameter data values to buffers for use by mysql_execute(). For output, it is used with mysql_bind_result() to bind result set buffers for use in fetching rows with mysql_fetch(). The MYSQL_BIND structure contains the following members for use by application programs. Each is used both for input and for output, though sometimes for different purposes depending on the direction of data transfer.
enum enum_field_types buffer_type The type of the buffer. The allowable buffer_type values are listed later in this section. For input, buffer_type indicates what type of value you are binding to a query parameter. For output, it indicates what type of value you expect to receive in a result buffer.
void *buffer For input, this is a pointer to the buffer in which a query parameter's data value is stored. For output, it is a pointer to the buffer in which to return a result set column value. For numeric column types, buffer should point to a variable of the proper C type. (If you are associating the variable with a column that has the UNSIGNED attribute, the variable should be an unsigned C type.) For date and time column types, buffer should point to a MYSQL_TIME structure. For character and binary string column types, buffer should point to a character buffer.
unsigned long buffer_length The actual size of *buffer in bytes. This indicates the maximum amount of data that can be stored in the buffer. For character and binary C data, the buffer_length value specifies the length of *buffer when used with mysql_bind_param(), or the maximum number of data bytes that can be fetched into the buffer when used with mysql_bind_result().
unsigned long *length A pointer to an unsigned long variable that indicates the actual number of bytes of data stored in *buffer. length is used for character or binary C data. For input parameter data binding, length points to an unsigned long variable that indicates the length of the parameter value stored in *buffer; this is used by mysql_execute(). If length is a null pointer, the protocol assumes that all character and binary data are null-terminated. For output value binding, mysql_fetch() places the length of the column value that is returned into the variable that length points to. length is ignored for numeric and temporal datatypes because the length of the data value is determined by the buffer_type value.
my_bool *is_null This member points to a my_bool variable that is true if a value is NULL, false if it is not NULL. For input, set *is_null to true to indicate that you are passing a NULL value as a query parameter. For output, this value will be set to true after you fetch a row if the result value returned from the query is NULL.
MYSQL_TIME This structure is used to send and receive DATE, TIME, DATETIME, and TIMESTAMP data directly to and from the server. This is done by setting the buffer_type member of a MYSQL_BIND structure to one of the temporal types, and setting the buffer member to point to a MYSQL_TIME structure. The MYSQL_TIME structure contains the following members:
unsigned int year The year.
unsigned int month The month of the year.
unsigned int day The day of the month.
unsigned int hour The hour of the day.
unsigned int minute The minute of the hour.
unsigned int second The second of the minute.
my_bool neg A boolean flag to indicate whether the time is negative.
unsigned long second_part The fractional part of the second. This member currently is unused.

The following table shows the allowable values that may be specified in the buffer_type member of MYSQL_BIND structures. The table also shows those SQL types that correspond most closely to each buffer_type value, and, for numeric and temporal types, the corresponding C type.

buffer_typeValueSQL TypeC Type
MYSQL_TYPE_TINYTINYINTchar
MYSQL_TYPE_SHORTSMALLINTshort int
MYSQL_TYPE_LONGINTlong int
MYSQL_TYPE_LONGLONGBIGINTlong long int
MYSQL_TYPE_FLOATFLOATfloat
MYSQL_TYPE_DOUBLEDOUBLEdouble
MYSQL_TYPE_TIMETIMEMYSQL_TIME
MYSQL_TYPE_DATEDATEMYSQL_TIME
MYSQL_TYPE_DATETIMEDATETIMEMYSQL_TIME
MYSQL_TYPE_TIMESTAMPTIMESTAMPMYSQL_TIME
MYSQL_TYPE_STRINGCHAR 
MYSQL_TYPE_VAR_STRINGVARCHAR 
MYSQL_TYPE_TINY_BLOBTINYBLOB/TINYTEXT 
MYSQL_TYPE_BLOBBLOB/TEXT 
MYSQL_TYPE_MEDIUM_BLOBMEDIUMBLOB/MEDIUMTEXT 
MYSQL_TYPE_LONG_BLOBLONGBLOB/LONGTEXT 

Implicit type conversion may be performed in both directions.