(mysql.info.gz) C API Prepared statement datatypes
Info Catalog
(mysql.info.gz) C API Prepared statements
(mysql.info.gz) C
(mysql.info.gz) C API Prepared statement function overview
22.2.5 C API Prepared Statement Data types
------------------------------------------
* Some incompatible changes were made in MySQL 4.1.2. See
C API Prepared statement functions for details.
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
created by calling `mysql_stmt_init()', which returns a statement
handle, that is, a pointer to a `MYSQL_STMT'. The handle is used
for all subsequent statement-related functions until you close it
with `mysql_stmt_close()'.
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 statement input (data values sent
to the server) and output (result values returned from the
server). For input, it is used with `mysql_stmt_bind_param()' to
bind parameter data values to buffers for use by
`mysql_stmt_execute()'. For output, it is used with
`mysql_stmt_bind_result()' to bind result set buffers for use in
fetching rows with `mysql_stmt_fetch()'.
The `MYSQL_BIND' structure contains the following members for use
by application programs. Each is used both for input and for
output, although 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 statement
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
statement 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. Indicate whether the variable is signed or unsigned by
using the `is_unsigned' member, described later in this list.)
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_stmt_bind_param()', or the maximum number of data
bytes that can be fetched into the buffer when used with
`mysql_stmt_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_stmt_execute()'. For
output value binding, `mysql_stmt_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 data types
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 statement parameter. For output, this value will
be set to true after you fetch a row if the result set column
value returned from the statement is `NULL'.
`my_bool is_unsigned'
This member is used for integer types. (These correspond to
the `MYSQL_TYPE_TINY', `MYSQL_TYPE_SHORT', `MYSQL_TYPE_LONG',
and `MYSQL_TYPE_LONGLONG' type codes.) `is_unsigned' should
be set to true for unsigned types and false for signed types.
`my_bool error'
For output, this member is used output to report data
truncation errors. Truncation reporting must be enabled by
calling `mysql_options()' with the
`MYSQL_REPORT_DATA_TRUNCATION' option. When enabled,
`mysql_stmt_fetch()' returns `MYSQL_DATA_TRUNCATED' and
`error' is true in the `MYSQL_BIND' structures for parameters
in which truncation occurred. Truncation indicates loss of
sign or significant digits, or that a string was too long to
fit in a column. The `error' member was added in MySQL 5.0.3.
To use a `MYSQL_BIND' structure, you should zero its contents to
initialize it, and then set the members just described
appropriately. For example, to declare and initialize an array of
three `MYSQL_BIND' structures, use this code:
MYSQL_BIND bind[3];
memset(bind, 0, sizeof(bind));
`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. C API date handling.
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_type' *Value* *SQL Type* *C Type*
`MYSQL_TYPE_TINY' `TINYINT' `char'
`MYSQL_TYPE_SHORT' `SMALLINT' `short int'
`MYSQL_TYPE_LONG' `INT' `int'
`MYSQL_TYPE_LONGLONG' `BIGINT' `long long int'
`MYSQL_TYPE_FLOAT' `FLOAT' `float'
`MYSQL_TYPE_DOUBLE' `DOUBLE' `double'
`MYSQL_TYPE_TIME' `TIME' `MYSQL_TIME'
`MYSQL_TYPE_DATE' `DATE' `MYSQL_TIME'
`MYSQL_TYPE_DATETIME' `DATETIME' `MYSQL_TIME'
`MYSQL_TYPE_TIMESTAMP' `TIMESTAMP' `MYSQL_TIME'
`MYSQL_TYPE_STRING' `CHAR'
`MYSQL_TYPE_VAR_STRING' `VARCHAR'
`MYSQL_TYPE_TINY_BLOB' `TINYBLOB/TINYTEXT'
`MYSQL_TYPE_BLOB' `BLOB/TEXT'
`MYSQL_TYPE_MEDIUM_BLOB' `MEDIUMBLOB/MEDIUMTEXT'
`MYSQL_TYPE_LONG_BLOB' `LONGBLOB/LONGTEXT'
Implicit type conversion may be performed in both directions.
Info Catalog
(mysql.info.gz) C API Prepared statements
(mysql.info.gz) C
(mysql.info.gz) C API Prepared statement function overview
automatically generated byinfo2html