Author: paul
Date: 2007-02-06 21:08:24 +0100 (Tue, 06 Feb 2007)
New Revision: 4829
Log:
r19508@polar: paul | 2007-02-06 14:07:17 -0600
C API binary protocol:
Revise the descriptions for the buffer_type and buffer values.
Split the MYSQL_TYPE_xxx table in two: one for input variables,
one for output variables.
Modified:
trunk/refman-4.1/apis-c.xml
trunk/refman-5.0/apis-c.xml
trunk/refman-5.1/apis-c.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:19494
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:15931
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:13520
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:19508
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:15931
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:13520
Modified: trunk/refman-4.1/apis-c.xml
===================================================================
--- trunk/refman-4.1/apis-c.xml 2007-02-06 19:11:18 UTC (rev 4828)
+++ trunk/refman-4.1/apis-c.xml 2007-02-06 20:08:24 UTC (rev 4829)
Changed blocks: 4, Lines Added: 139, Lines Deleted: 54; 10847 bytes
@@ -7994,9 +7994,10 @@
The type of the buffer. The allowable
<literal>buffer_type</literal> values are listed later in
this section. For input, <literal>buffer_type</literal>
- 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.
+ indicates the data type of the C language variable that
+ you are binding to a statement parameter. For output, it
+ indicates the SQL data type of the value that you expect
+ to receive in a result buffer.
</para>
</listitem>
@@ -8007,19 +8008,32 @@
<para>
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 data types,
- <literal>buffer</literal> should point to a variable of
- the proper C type. (For <literal>char</literal> or integer
- variables, indicate whether the variable has the
+ statement parameter's data value is stored. When you call
+ <literal>mysql_stmt_execute()</literal>, MySQL takes the
+ value and uses it in place of the corresponding parameter
+ marker in the statement.
+ </para>
+
+ <para>
+ For output, it is a pointer to the buffer in which to
+ return a result set column value. When you call
+ <literal>mysql_stmt_fetch()</literal>, MySQL returns a
+ column value and stores it in this buffer. You can access
+ the value when the call returns.
+ </para>
+
+ <para>
+ For character (non-binary) and binary string data types,
+ <literal>buffer</literal> should point to a character
+ buffer. For numeric data types, <literal>buffer</literal>
+ should point to a variable of the proper numeric C type.
+ (For <literal>char</literal> or integer variables,
+ indicate whether the variable has the
<literal>unsigned</literal> attribute by using the
<literal>is_unsigned</literal> member, described later in
this list.) For date and time data types,
<literal>buffer</literal> should point to a
- <literal>MYSQL_TIME</literal> structure. For character and
- binary string data types, <literal>buffer</literal> should
- point to a character buffer.
+ <literal>MYSQL_TIME</literal> structure.
</para>
</listitem>
@@ -8278,55 +8292,85 @@
<para>
The following table shows the allowable values that may be
specified in the <literal>buffer_type</literal> member of
- <literal>MYSQL_BIND</literal> structures. The table also shows
- those SQL types that correspond most closely to each
- <literal>buffer_type</literal> value, and, for numeric and
- temporal types, the corresponding recommended C type.
+ <literal>MYSQL_BIND</literal> structures for input values. The
+ <literal>buffer_type</literal> value should be chosen according to
+ the data type of the C language variable that you are binding.
</para>
- <para>
- The types are <quote>recommended</quote> because implicit type
- conversion may be performed in both directions. The
- <literal>buffer_type</literal> value controls the conversion that
- will be performed. For example, to fetch a SQL
- <literal>MEDIUMINT</literal> column value, you can specify a
- <literal>buffer_type</literal> value of
- <literal>MYSQL_TYPE_LONG</literal> and use a C variable of type
- <literal>int</literal> as the destination buffer. If you fetch a
- numeric column with a value of 255 into a
- <literal>char[4]</literal> character array, specify a
- <literal>buffer_type</literal> value of
- <literal>MYSQL_TYPE_STRING</literal> and the resulting value in
- the array will be a 4-byte string containing
- <literal>'255\0'</literal>.
- </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="35*"/>
+ <colspec colwidth="65"/>
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">C Variable Type</emphasis></entry>
+ <entry><literal>buffer_type</literal> <emphasis role="bold">Value</emphasis></entry>
+ </row>
+ <row>
+ <entry><literal>char</literal></entry>
+ <entry><literal>MYSQL_TYPE_TINY</literal></entry>
+ </row>
+ <row>
+ <entry><literal>short int</literal></entry>
+ <entry><literal>MYSQL_TYPE_SHORT</literal></entry>
+ </row>
+ <row>
+ <entry><literal>int</literal></entry>
+ <entry><literal>MYSQL_TYPE_LONG</literal></entry>
+ </row>
+ <row>
+ <entry><literal>long long int</literal></entry>
+ <entry><literal>MYSQL_TYPE_LONGLONG</literal></entry>
+ </row>
+ <row>
+ <entry><literal>float</literal></entry>
+ <entry><literal>MYSQL_TYPE_FLOAT</literal></entry>
+ </row>
+ <row>
+ <entry><literal>double</literal></entry>
+ <entry><literal>MYSQL_TYPE_DOUBLE</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_TIME</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_DATE</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_DATETIME</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_TIMESTAMP</literal></entry>
+ </row>
+ <row>
+ <entry><literal>char[]</literal></entry>
+ <entry><literal>MYSQL_TYPE_STRING</literal> (for non-binary data)</entry>
+ </row>
+ <row>
+ <entry><literal>char[]</literal></entry>
+ <entry><literal>MYSQL_TYPE_BLOB</literal> (for binary data)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
<para>
- For input character (non-binary) string data, the value is assumed
- to be in the character set indicated by the
- <literal>character_set_client</literal> system variable. If the
- value is stored into a column with a different character set, the
- appropriate conversion to that character set occurs. For input
- binary string data (indicated by
- <literal>MYSQL_TYPE_BLOB</literal>, for examplel), the value is
- treated as having the <literal>binary</literal> character set;
- that is, it is treated as a byte string and no conversion occurs.
+ The following table shows the allowable values that may be
+ specified in the <literal>buffer_type</literal> member of
+ <literal>MYSQL_BIND</literal> structures for output values. The
+ <literal>buffer_type</literal> value should be chosen according to
+ the SQL data type of the value that you receive from the server.
+ The table also shows the recommended type of C language variable
+ to bind to the <literal>MYSQL_BIND</literal> structure for each
+ SQL type.
</para>
- <para>
- To determine whether string values in a result set returned from
- the server contain binary or non-binary data, check whether the
- <literal>charsetnr</literal> value of the result set metadata is
- 63. If so, the character set is <literal>binary</literal>, which
- indicates binary rather than non-binary data. This enables you to
- distinguish between <literal>BINARY</literal> and
- <literal>CHAR</literal>, <literal>VARBINARY</literal> and
- <literal>VARCHAR</literal>, and <literal>BLOB</literal> and
- <literal>TEXT</literal>.
- </para>
-
<informaltable>
- <tgroup cols="3">
+ <tgroup cols="2">
<colspec colwidth="33*"/>
<colspec colwidth="33*"/>
<colspec colwidth="33*"/>
@@ -8420,6 +8464,47 @@
</tgroup>
</informaltable>
+ <para>
+ The C language variable types are <quote>recommended</quote>
+ because implicit type conversion may be performed in both
+ directions. The <literal>buffer_type</literal> value controls the
+ conversion that will be performed. For example, to fetch a SQL
+ <literal>MEDIUMINT</literal> column value, you can specify a
+ <literal>buffer_type</literal> value of
+ <literal>MYSQL_TYPE_LONG</literal> and use a C variable of type
+ <literal>int</literal> as the destination buffer. If you fetch a
+ numeric column with a value of 255 into a
+ <literal>char[4]</literal> character array, specify a
+ <literal>buffer_type</literal> value of
+ <literal>MYSQL_TYPE_STRING</literal> and the resulting value in
+ the array will be a 4-byte string containing
+ <literal>'255\0'</literal>.
+ </para>
+
+ <para>
+ For input character (non-binary) string data, the value is assumed
+ to be in the character set indicated by the
+ <literal>character_set_client</literal> system variable. If the
+ value is stored into a column with a different character set, the
+ appropriate conversion to that character set occurs. For input
+ binary string data (indicated by
+ <literal>MYSQL_TYPE_BLOB</literal>, for examplel), the value is
+ treated as having the <literal>binary</literal> character set;
+ that is, it is treated as a byte string and no conversion occurs.
+ </para>
+
+ <para>
+ To determine whether string values in a result set returned from
+ the server contain binary or non-binary data, check whether the
+ <literal>charsetnr</literal> value of the result set metadata is
+ 63. If so, the character set is <literal>binary</literal>, which
+ indicates binary rather than non-binary data. This enables you to
+ distinguish between <literal>BINARY</literal> and
+ <literal>CHAR</literal>, <literal>VARBINARY</literal> and
+ <literal>VARCHAR</literal>, and <literal>BLOB</literal> and
+ <literal>TEXT</literal>.
+ </para>
+
</section>
<section id="c-api-prepared-statement-function-overview">
Modified: trunk/refman-5.0/apis-c.xml
===================================================================
--- trunk/refman-5.0/apis-c.xml 2007-02-06 19:11:18 UTC (rev 4828)
+++ trunk/refman-5.0/apis-c.xml 2007-02-06 20:08:24 UTC (rev 4829)
Changed blocks: 4, Lines Added: 139, Lines Deleted: 54; 10847 bytes
@@ -8085,9 +8085,10 @@
The type of the buffer. The allowable
<literal>buffer_type</literal> values are listed later in
this section. For input, <literal>buffer_type</literal>
- 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.
+ indicates the data type of the C language variable that
+ you are binding to a statement parameter. For output, it
+ indicates the SQL data type of the value that you expect
+ to receive in a result buffer.
</para>
</listitem>
@@ -8098,19 +8099,32 @@
<para>
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 data types,
- <literal>buffer</literal> should point to a variable of
- the proper C type. (For <literal>char</literal> or integer
- variables, indicate whether the variable has the
+ statement parameter's data value is stored. When you call
+ <literal>mysql_stmt_execute()</literal>, MySQL takes the
+ value and uses it in place of the corresponding parameter
+ marker in the statement.
+ </para>
+
+ <para>
+ For output, it is a pointer to the buffer in which to
+ return a result set column value. When you call
+ <literal>mysql_stmt_fetch()</literal>, MySQL returns a
+ column value and stores it in this buffer. You can access
+ the value when the call returns.
+ </para>
+
+ <para>
+ For character (non-binary) and binary string data types,
+ <literal>buffer</literal> should point to a character
+ buffer. For numeric data types, <literal>buffer</literal>
+ should point to a variable of the proper numeric C type.
+ (For <literal>char</literal> or integer variables,
+ indicate whether the variable has the
<literal>unsigned</literal> attribute by using the
<literal>is_unsigned</literal> member, described later in
this list.) For date and time data types,
<literal>buffer</literal> should point to a
- <literal>MYSQL_TIME</literal> structure. For character and
- binary string data types, <literal>buffer</literal> should
- point to a character buffer.
+ <literal>MYSQL_TIME</literal> structure.
</para>
</listitem>
@@ -8394,55 +8408,85 @@
<para>
The following table shows the allowable values that may be
specified in the <literal>buffer_type</literal> member of
- <literal>MYSQL_BIND</literal> structures. The table also shows
- those SQL types that correspond most closely to each
- <literal>buffer_type</literal> value, and, for numeric and
- temporal types, the corresponding recommended C type.
+ <literal>MYSQL_BIND</literal> structures for input values. The
+ <literal>buffer_type</literal> value should be chosen according to
+ the data type of the C language variable that you are binding.
</para>
- <para>
- The types are <quote>recommended</quote> because implicit type
- conversion may be performed in both directions. The
- <literal>buffer_type</literal> value controls the conversion that
- will be performed. For example, to fetch a SQL
- <literal>MEDIUMINT</literal> column value, you can specify a
- <literal>buffer_type</literal> value of
- <literal>MYSQL_TYPE_LONG</literal> and use a C variable of type
- <literal>int</literal> as the destination buffer. If you fetch a
- numeric column with a value of 255 into a
- <literal>char[4]</literal> character array, specify a
- <literal>buffer_type</literal> value of
- <literal>MYSQL_TYPE_STRING</literal> and the resulting value in
- the array will be a 4-byte string containing
- <literal>'255\0'</literal>.
- </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="35*"/>
+ <colspec colwidth="65"/>
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">C Variable Type</emphasis></entry>
+ <entry><literal>buffer_type</literal> <emphasis role="bold">Value</emphasis></entry>
+ </row>
+ <row>
+ <entry><literal>char</literal></entry>
+ <entry><literal>MYSQL_TYPE_TINY</literal></entry>
+ </row>
+ <row>
+ <entry><literal>short int</literal></entry>
+ <entry><literal>MYSQL_TYPE_SHORT</literal></entry>
+ </row>
+ <row>
+ <entry><literal>int</literal></entry>
+ <entry><literal>MYSQL_TYPE_LONG</literal></entry>
+ </row>
+ <row>
+ <entry><literal>long long int</literal></entry>
+ <entry><literal>MYSQL_TYPE_LONGLONG</literal></entry>
+ </row>
+ <row>
+ <entry><literal>float</literal></entry>
+ <entry><literal>MYSQL_TYPE_FLOAT</literal></entry>
+ </row>
+ <row>
+ <entry><literal>double</literal></entry>
+ <entry><literal>MYSQL_TYPE_DOUBLE</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_TIME</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_DATE</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_DATETIME</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_TIMESTAMP</literal></entry>
+ </row>
+ <row>
+ <entry><literal>char[]</literal></entry>
+ <entry><literal>MYSQL_TYPE_STRING</literal> (for non-binary data)</entry>
+ </row>
+ <row>
+ <entry><literal>char[]</literal></entry>
+ <entry><literal>MYSQL_TYPE_BLOB</literal> (for binary data)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
<para>
- For input character (non-binary) string data, the value is assumed
- to be in the character set indicated by the
- <literal>character_set_client</literal> system variable. If the
- value is stored into a column with a different character set, the
- appropriate conversion to that character set occurs. For input
- binary string data (indicated by
- <literal>MYSQL_TYPE_BLOB</literal>, for examplel), the value is
- treated as having the <literal>binary</literal> character set;
- that is, it is treated as a byte string and no conversion occurs.
+ The following table shows the allowable values that may be
+ specified in the <literal>buffer_type</literal> member of
+ <literal>MYSQL_BIND</literal> structures for output values. The
+ <literal>buffer_type</literal> value should be chosen according to
+ the SQL data type of the value that you receive from the server.
+ The table also shows the recommended type of C language variable
+ to bind to the <literal>MYSQL_BIND</literal> structure for each
+ SQL type.
</para>
- <para>
- To determine whether string values in a result set returned from
- the server contain binary or non-binary data, check whether the
- <literal>charsetnr</literal> value of the result set metadata is
- 63. If so, the character set is <literal>binary</literal>, which
- indicates binary rather than non-binary data. This enables you to
- distinguish between <literal>BINARY</literal> and
- <literal>CHAR</literal>, <literal>VARBINARY</literal> and
- <literal>VARCHAR</literal>, and <literal>BLOB</literal> and
- <literal>TEXT</literal>.
- </para>
-
<informaltable>
- <tgroup cols="3">
+ <tgroup cols="2">
<colspec colwidth="33*"/>
<colspec colwidth="33*"/>
<colspec colwidth="33*"/>
@@ -8546,6 +8590,47 @@
</tgroup>
</informaltable>
+ <para>
+ The C language variable types are <quote>recommended</quote>
+ because implicit type conversion may be performed in both
+ directions. The <literal>buffer_type</literal> value controls the
+ conversion that will be performed. For example, to fetch a SQL
+ <literal>MEDIUMINT</literal> column value, you can specify a
+ <literal>buffer_type</literal> value of
+ <literal>MYSQL_TYPE_LONG</literal> and use a C variable of type
+ <literal>int</literal> as the destination buffer. If you fetch a
+ numeric column with a value of 255 into a
+ <literal>char[4]</literal> character array, specify a
+ <literal>buffer_type</literal> value of
+ <literal>MYSQL_TYPE_STRING</literal> and the resulting value in
+ the array will be a 4-byte string containing
+ <literal>'255\0'</literal>.
+ </para>
+
+ <para>
+ For input character (non-binary) string data, the value is assumed
+ to be in the character set indicated by the
+ <literal>character_set_client</literal> system variable. If the
+ value is stored into a column with a different character set, the
+ appropriate conversion to that character set occurs. For input
+ binary string data (indicated by
+ <literal>MYSQL_TYPE_BLOB</literal>, for examplel), the value is
+ treated as having the <literal>binary</literal> character set;
+ that is, it is treated as a byte string and no conversion occurs.
+ </para>
+
+ <para>
+ To determine whether string values in a result set returned from
+ the server contain binary or non-binary data, check whether the
+ <literal>charsetnr</literal> value of the result set metadata is
+ 63. If so, the character set is <literal>binary</literal>, which
+ indicates binary rather than non-binary data. This enables you to
+ distinguish between <literal>BINARY</literal> and
+ <literal>CHAR</literal>, <literal>VARBINARY</literal> and
+ <literal>VARCHAR</literal>, and <literal>BLOB</literal> and
+ <literal>TEXT</literal>.
+ </para>
+
</section>
<section id="c-api-prepared-statement-function-overview">
Modified: trunk/refman-5.1/apis-c.xml
===================================================================
--- trunk/refman-5.1/apis-c.xml 2007-02-06 19:11:18 UTC (rev 4828)
+++ trunk/refman-5.1/apis-c.xml 2007-02-06 20:08:24 UTC (rev 4829)
Changed blocks: 4, Lines Added: 139, Lines Deleted: 54; 10847 bytes
@@ -8204,9 +8204,10 @@
The type of the buffer. The allowable
<literal>buffer_type</literal> values are listed later in
this section. For input, <literal>buffer_type</literal>
- 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.
+ indicates the data type of the C language variable that
+ you are binding to a statement parameter. For output, it
+ indicates the SQL data type of the value that you expect
+ to receive in a result buffer.
</para>
</listitem>
@@ -8217,19 +8218,32 @@
<para>
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 data types,
- <literal>buffer</literal> should point to a variable of
- the proper C type. (For <literal>char</literal> or integer
- variables, indicate whether the variable has the
+ statement parameter's data value is stored. When you call
+ <literal>mysql_stmt_execute()</literal>, MySQL takes the
+ value and uses it in place of the corresponding parameter
+ marker in the statement.
+ </para>
+
+ <para>
+ For output, it is a pointer to the buffer in which to
+ return a result set column value. When you call
+ <literal>mysql_stmt_fetch()</literal>, MySQL returns a
+ column value and stores it in this buffer. You can access
+ the value when the call returns.
+ </para>
+
+ <para>
+ For character (non-binary) and binary string data types,
+ <literal>buffer</literal> should point to a character
+ buffer. For numeric data types, <literal>buffer</literal>
+ should point to a variable of the proper numeric C type.
+ (For <literal>char</literal> or integer variables,
+ indicate whether the variable has the
<literal>unsigned</literal> attribute by using the
<literal>is_unsigned</literal> member, described later in
this list.) For date and time data types,
<literal>buffer</literal> should point to a
- <literal>MYSQL_TIME</literal> structure. For character and
- binary string data types, <literal>buffer</literal> should
- point to a character buffer.
+ <literal>MYSQL_TIME</literal> structure.
</para>
</listitem>
@@ -8512,55 +8526,85 @@
<para>
The following table shows the allowable values that may be
specified in the <literal>buffer_type</literal> member of
- <literal>MYSQL_BIND</literal> structures. The table also shows
- those SQL types that correspond most closely to each
- <literal>buffer_type</literal> value, and, for numeric and
- temporal types, the corresponding recommended C type.
+ <literal>MYSQL_BIND</literal> structures for input values. The
+ <literal>buffer_type</literal> value should be chosen according to
+ the data type of the C language variable that you are binding.
</para>
- <para>
- The types are <quote>recommended</quote> because implicit type
- conversion may be performed in both directions. The
- <literal>buffer_type</literal> value controls the conversion that
- will be performed. For example, to fetch a SQL
- <literal>MEDIUMINT</literal> column value, you can specify a
- <literal>buffer_type</literal> value of
- <literal>MYSQL_TYPE_LONG</literal> and use a C variable of type
- <literal>int</literal> as the destination buffer. If you fetch a
- numeric column with a value of 255 into a
- <literal>char[4]</literal> character array, specify a
- <literal>buffer_type</literal> value of
- <literal>MYSQL_TYPE_STRING</literal> and the resulting value in
- the array will be a 4-byte string containing
- <literal>'255\0'</literal>.
- </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="35*"/>
+ <colspec colwidth="65"/>
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">C Variable Type</emphasis></entry>
+ <entry><literal>buffer_type</literal> <emphasis role="bold">Value</emphasis></entry>
+ </row>
+ <row>
+ <entry><literal>char</literal></entry>
+ <entry><literal>MYSQL_TYPE_TINY</literal></entry>
+ </row>
+ <row>
+ <entry><literal>short int</literal></entry>
+ <entry><literal>MYSQL_TYPE_SHORT</literal></entry>
+ </row>
+ <row>
+ <entry><literal>int</literal></entry>
+ <entry><literal>MYSQL_TYPE_LONG</literal></entry>
+ </row>
+ <row>
+ <entry><literal>long long int</literal></entry>
+ <entry><literal>MYSQL_TYPE_LONGLONG</literal></entry>
+ </row>
+ <row>
+ <entry><literal>float</literal></entry>
+ <entry><literal>MYSQL_TYPE_FLOAT</literal></entry>
+ </row>
+ <row>
+ <entry><literal>double</literal></entry>
+ <entry><literal>MYSQL_TYPE_DOUBLE</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_TIME</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_DATE</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_DATETIME</literal></entry>
+ </row>
+ <row>
+ <entry><literal>MYSQL_TIME</literal></entry>
+ <entry><literal>MYSQL_TYPE_TIMESTAMP</literal></entry>
+ </row>
+ <row>
+ <entry><literal>char[]</literal></entry>
+ <entry><literal>MYSQL_TYPE_STRING</literal> (for non-binary data)</entry>
+ </row>
+ <row>
+ <entry><literal>char[]</literal></entry>
+ <entry><literal>MYSQL_TYPE_BLOB</literal> (for binary data)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
<para>
- For input character (non-binary) string data, the value is assumed
- to be in the character set indicated by the
- <literal>character_set_client</literal> system variable. If the
- value is stored into a column with a different character set, the
- appropriate conversion to that character set occurs. For input
- binary string data (indicated by
- <literal>MYSQL_TYPE_BLOB</literal>, for examplel), the value is
- treated as having the <literal>binary</literal> character set;
- that is, it is treated as a byte string and no conversion occurs.
+ The following table shows the allowable values that may be
+ specified in the <literal>buffer_type</literal> member of
+ <literal>MYSQL_BIND</literal> structures for output values. The
+ <literal>buffer_type</literal> value should be chosen according to
+ the SQL data type of the value that you receive from the server.
+ The table also shows the recommended type of C language variable
+ to bind to the <literal>MYSQL_BIND</literal> structure for each
+ SQL type.
</para>
- <para>
- To determine whether string values in a result set returned from
- the server contain binary or non-binary data, check whether the
- <literal>charsetnr</literal> value of the result set metadata is
- 63. If so, the character set is <literal>binary</literal>, which
- indicates binary rather than non-binary data. This enables you to
- distinguish between <literal>BINARY</literal> and
- <literal>CHAR</literal>, <literal>VARBINARY</literal> and
- <literal>VARCHAR</literal>, and <literal>BLOB</literal> and
- <literal>TEXT</literal>.
- </para>
-
<informaltable>
- <tgroup cols="3">
+ <tgroup cols="2">
<colspec colwidth="33*"/>
<colspec colwidth="33*"/>
<colspec colwidth="33*"/>
@@ -8664,6 +8708,47 @@
</tgroup>
</informaltable>
+ <para>
+ The C language variable types are <quote>recommended</quote>
+ because implicit type conversion may be performed in both
+ directions. The <literal>buffer_type</literal> value controls the
+ conversion that will be performed. For example, to fetch a SQL
+ <literal>MEDIUMINT</literal> column value, you can specify a
+ <literal>buffer_type</literal> value of
+ <literal>MYSQL_TYPE_LONG</literal> and use a C variable of type
+ <literal>int</literal> as the destination buffer. If you fetch a
+ numeric column with a value of 255 into a
+ <literal>char[4]</literal> character array, specify a
+ <literal>buffer_type</literal> value of
+ <literal>MYSQL_TYPE_STRING</literal> and the resulting value in
+ the array will be a 4-byte string containing
+ <literal>'255\0'</literal>.
+ </para>
+
+ <para>
+ For input character (non-binary) string data, the value is assumed
+ to be in the character set indicated by the
+ <literal>character_set_client</literal> system variable. If the
+ value is stored into a column with a different character set, the
+ appropriate conversion to that character set occurs. For input
+ binary string data (indicated by
+ <literal>MYSQL_TYPE_BLOB</literal>, for examplel), the value is
+ treated as having the <literal>binary</literal> character set;
+ that is, it is treated as a byte string and no conversion occurs.
+ </para>
+
+ <para>
+ To determine whether string values in a result set returned from
+ the server contain binary or non-binary data, check whether the
+ <literal>charsetnr</literal> value of the result set metadata is
+ 63. If so, the character set is <literal>binary</literal>, which
+ indicates binary rather than non-binary data. This enables you to
+ distinguish between <literal>BINARY</literal> and
+ <literal>CHAR</literal>, <literal>VARBINARY</literal> and
+ <literal>VARCHAR</literal>, and <literal>BLOB</literal> and
+ <literal>TEXT</literal>.
+ </para>
+
</section>
<section id="c-api-prepared-statement-function-overview">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r4829 - in trunk: . refman-4.1 refman-5.0 refman-5.1 | paul | 6 Feb |
