9.1.5 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.

Only those parts of a MYSQL_TIME structure that apply to a given type of temporal value are used: The year, month, and day elements are used for DATE, DATETIME, and TIMESTAMP values. The hour, minute, and second elements are used for TIME, DATETIME, and TIMESTAMP values. See section 9.1.9 C API Handling of Date and Time Values.

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.

Implicit type conversion may be performed in both directions.

User Comments

Add your own comment.