3089
3089
to point to the buffer of given type. Finally, additional actions
3090
3090
may be taken for some types or use cases:
3092
Binding integer types.
3093
For integer types you might also need to set MYSQL_BIND::is_unsigned
3094
member. Set it to TRUE when binding unsigned char, unsigned short,
3095
unsigned int, unsigned long, unsigned long long.
3097
Binding floating point types.
3098
For floating point types you just need to set
3099
MYSQL_BIND::buffer_type and MYSQL_BIND::buffer. The rest of the
3100
members should be zero-initialized.
3103
You might have a column always NULL, never NULL, or sometimes NULL.
3104
For an always NULL column set MYSQL_BIND::buffer_type to
3105
MYSQL_TYPE_NULL. The rest of the members just need to be
3106
zero-initialized. For never NULL columns set MYSQL_BIND::is_null to
3107
0, or this has already been done if you zero-initialized the entire
3108
structure. If you set MYSQL_TYPE::is_null to point to an
3109
application buffer of type 'my_bool', then this buffer will be
3110
checked on each execution: this way you can set the buffer to TRUE,
3111
or any non-0 value for NULLs, and to FALSE or 0 for not NULL data.
3113
Binding text strings and sequences of bytes.
3114
For strings, in addition to MYSQL_BIND::buffer_type and
3115
MYSQL_BIND::buffer you need to set MYSQL_BIND::length or
3116
MYSQL_BIND::buffer_length.
3117
If 'length' is set, 'buffer_length' is ignored. 'buffer_length'
3118
member should be used when size of string doesn't change between
3119
executions. If you want to vary buffer length for each value, set
3120
'length' to point to an application buffer of type 'unsigned long'
3121
and set this long to length of the string before each
3122
mysql_stmt_execute().
3124
Binding dates and times.
3125
For binding dates and times prepared statements API provides clients
3126
with MYSQL_TIME structure. A pointer to instance of this structure
3127
should be assigned to MYSQL_BIND::buffer whenever MYSQL_TYPE_TIME,
3128
MYSQL_TYPE_DATE, MYSQL_TYPE_DATETIME typecodes are used. When
3129
typecode is MYSQL_TYPE_TIME, only members 'hour', 'minute', 'second'
3130
and 'neg' (is time offset negative) are used. These members only
3131
will be sent to the server.
3132
MYSQL_TYPE_DATE implies use of 'year', 'month', 'day', 'neg'.
3133
MYSQL_TYPE_DATETIME utilizes both parts of MYSQL_TIME structure.
3134
You don't have to set MYSQL_TIME::time_type member: it's not used
3135
when sending data to the server, typecode information is enough.
3136
'second_part' member can hold microsecond precision of time value,
3137
but now it's only supported on protocol level: you can't store
3138
microsecond in a column, or use in temporal calculations. However,
3139
if you send a time value with microsecond part for 'SELECT ?',
3140
statement, you'll get it back unchanged from the server.
3143
If conversion from host language type to data representation,
3144
corresponding to SQL type, is required it's done on the server.
3145
Data truncation is possible when conversion is lossy. For example,
3146
if you supply MYSQL_TYPE_DATETIME value out of valid SQL type
3147
TIMESTAMP range, the same conversion will be applied as if this
3148
value would have been sent as string in the old protocol.
3149
TODO: document how the server will behave in case of truncation/data
3092
Binding integer types.
3093
For integer types you might also need to set MYSQL_BIND::is_unsigned
3094
member. Set it to TRUE when binding unsigned char, unsigned short,
3095
unsigned int, unsigned long, unsigned long long.
3097
Binding floating point types.
3098
For floating point types you just need to set
3099
MYSQL_BIND::buffer_type and MYSQL_BIND::buffer. The rest of the
3100
members should be zero-initialized.
3103
You might have a column always NULL, never NULL, or sometimes
3104
NULL. For an always NULL column set MYSQL_BIND::buffer_type to
3105
MYSQL_TYPE_NULL. The rest of the members just need to be
3106
zero-initialized. For never NULL columns set
3107
MYSQL_BIND::is_null to 0, or this has already been done if you
3108
zero-initialized the entire structure. If you set
3109
MYSQL_TYPE::is_null to point to an application buffer of type
3110
'my_bool', then this buffer will be checked on each execution:
3111
this way you can set the buffer to TRUE, or any non-0 value for
3112
NULLs, and to FALSE or 0 for not NULL data.
3114
Binding text strings and sequences of bytes.
3115
For strings, in addition to MYSQL_BIND::buffer_type and
3116
MYSQL_BIND::buffer you need to set MYSQL_BIND::length or
3117
MYSQL_BIND::buffer_length. If 'length' is set, 'buffer_length'
3118
is ignored. 'buffer_length' member should be used when size of
3119
string doesn't change between executions. If you want to vary
3120
buffer length for each value, set 'length' to point to an
3121
application buffer of type 'unsigned long' and set this long to
3122
length of the string before each mysql_stmt_execute().
3124
Binding dates and times.
3125
For binding dates and times prepared statements API provides
3126
clients with MYSQL_TIME structure. A pointer to instance of this
3127
structure should be assigned to MYSQL_BIND::buffer whenever
3128
MYSQL_TYPE_TIME, MYSQL_TYPE_DATE, MYSQL_TYPE_DATETIME typecodes
3129
are used. When typecode is MYSQL_TYPE_TIME, only members
3130
'hour', 'minute', 'second' and 'neg' (is time offset negative)
3131
are used. These members only will be sent to the server.
3132
MYSQL_TYPE_DATE implies use of 'year', 'month', 'day', 'neg'.
3133
MYSQL_TYPE_DATETIME utilizes both parts of MYSQL_TIME structure.
3134
You don't have to set MYSQL_TIME::time_type member: it's not
3135
used when sending data to the server, typecode information is
3136
enough. 'second_part' member can hold microsecond precision of
3137
time value, but now it's only supported on protocol level: you
3138
can't store microsecond in a column, or use in temporal
3139
calculations. However, if you send a time value with microsecond
3140
part for 'SELECT ?', statement, you'll get it back unchanged
3144
If conversion from host language type to data representation,
3145
corresponding to SQL type, is required it's done on the server.
3146
Data truncation is possible when conversion is lossy. For
3147
example, if you supply MYSQL_TYPE_DATETIME value out of valid
3148
SQL type TIMESTAMP range, the same conversion will be applied as
3149
if this value would have been sent as string in the old
3150
protocol. TODO: document how the server will behave in case of
3151
truncation/data loss.
3152
3153
After variables were bound, you can repeatedly set/change their
3153
3154
values and mysql_stmt_execute() the statement.
3863
3863
static void fetch_datetime_with_conversion(MYSQL_BIND *param,
3864
3864
MYSQL_FIELD *field,
3865
MYSQL_TIME *my_time)
3867
3867
switch (param->buffer_type) {
3868
3868
case MYSQL_TYPE_NULL: /* do nothing */
3870
3870
case MYSQL_TYPE_DATE:
3871
*(MYSQL_TIME *)(param->buffer)= *time;
3872
*param->error= time->time_type != MYSQL_TIMESTAMP_DATE;
3871
*(MYSQL_TIME *)(param->buffer)= *my_time;
3872
*param->error= my_time->time_type != MYSQL_TIMESTAMP_DATE;
3874
3874
case MYSQL_TYPE_TIME:
3875
*(MYSQL_TIME *)(param->buffer)= *time;
3876
*param->error= time->time_type != MYSQL_TIMESTAMP_TIME;
3875
*(MYSQL_TIME *)(param->buffer)= *my_time;
3876
*param->error= my_time->time_type != MYSQL_TIMESTAMP_TIME;
3878
3878
case MYSQL_TYPE_DATETIME:
3879
3879
case MYSQL_TYPE_TIMESTAMP:
3880
*(MYSQL_TIME *)(param->buffer)= *time;
3880
*(MYSQL_TIME *)(param->buffer)= *my_time;
3881
3881
/* No error: time and date are compatible with datetime */
3883
3883
case MYSQL_TYPE_YEAR:
3884
shortstore(param->buffer, time->year);
3884
shortstore(param->buffer, my_time->year);
3885
3885
*param->error= 1;
3887
3887
case MYSQL_TYPE_FLOAT:
3888
3888
case MYSQL_TYPE_DOUBLE:
3890
ulonglong value= TIME_to_ulonglong(time);
3890
ulonglong value= TIME_to_ulonglong(my_time);
3891
3891
fetch_float_with_conversion(param, field,
3892
3892
ulonglong2double(value), DBL_DIG);
added
removed
libmysql/libmysql.c
