Author: paul
Date: 2007-02-07 18:58:10 +0100 (Wed, 07 Feb 2007)
New Revision: 4846
Log:
r15979@frost: paul | 2007-02-07 11:54:28 -0600
C API binary protocol: General revisions.
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:19514
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:19514
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:15979
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-07 17:27:08 UTC (rev 4845)
+++ trunk/refman-4.1/apis-c.xml 2007-02-07 17:58:10 UTC (rev 4846)
Changed blocks: 17, Lines Added: 134, Lines Deleted: 85; 17498 bytes
@@ -7854,14 +7854,14 @@
</para>
<para>
- Prepared statements use these data structures:
+ Prepared statements use several data structures:
</para>
<itemizedlist>
<listitem>
<para>
- To prepare a statement, call
+ To prepare a statement, pass the statement string to
<literal>mysql_stmt_init()</literal>, which returns a pointer
to a <literal>MYSQL_STMT</literal> data structure.
</para>
@@ -7887,8 +7887,8 @@
</itemizedlist>
<para>
- The following descriptions provide additional detail on the use of
- the prepared statement data types.
+ The following discussion describes the prepared statement data
+ types in detail.
</para>
<itemizedlist>
@@ -7914,9 +7914,10 @@
<para>
The <literal>MYSQL_STMT</literal> structure has no members
- that are for application use. Also, you should not try to make
- a copy of a <literal>MYSQL_STMT</literal> structure. There is
- no guarantee that such a copy will be usable.
+ that are intended for application use. Also, you should not
+ try to make a copy of a <literal>MYSQL_STMT</literal>
+ structure. There is no guarantee that such a copy will be
+ usable.
</para>
<para>
@@ -7972,15 +7973,15 @@
</para>
<programlisting>
-MYSQL_BIND bind[3];
+MYSQL_BIND bind[3];
memset(bind, 0, sizeof(bind));
</programlisting>
<para>
The <literal>MYSQL_BIND</literal> structure contains the
- following members for use by application programs. A given
- member might be used for different purposes, depending on
- whether the structure is used for input or output.
+ following members for use by application programs. For several
+ of the members, the manner of use depends on whether the
+ structure is used for input or output.
</para>
<itemizedlist>
@@ -8007,19 +8008,21 @@
</para>
<para>
- For input, this is a pointer to the buffer in which a
- statement parameter's data value is stored. When you call
+ For input, <literal>buffer</literal> is a pointer to the
+ buffer in which a 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.
+ value that you have stored in the buffer 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.
+ For output, <literal>buffer</literal> 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>
@@ -8027,9 +8030,9 @@
<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
+ (For <literal>char</literal> or integer variables, you
+ should also indicate whether the variable has the
+ <literal>unsigned</literal> attribute by setting the
<literal>is_unsigned</literal> member, described later in
this list.) For date and time data types,
<literal>buffer</literal> should point to a
@@ -8064,27 +8067,48 @@
A pointer to an <literal>unsigned long</literal> variable
that indicates the actual number of bytes of data stored
in <literal>*buffer</literal>. <literal>length</literal>
- is used for character or binary C data. For input
- parameter data binding, <literal>length</literal> points
- to an <literal>unsigned long</literal> variable that
- indicates the actual length of the parameter value stored
- in <literal>*buffer</literal>; this is used by
- <literal>mysql_stmt_execute()</literal>. For output value
- binding, the return value of
+ is used for character or binary C data.
+ </para>
+
+ <para>
+ For input parameter data binding,
+ <literal>length</literal> points to an <literal>unsigned
+ long</literal> variable that indicates the actual length
+ of the parameter value stored in
+ <literal>*buffer</literal>; this is used by
+ <literal>mysql_stmt_execute()</literal>.
+ </para>
+
+ <para>
+ For output value binding, the return value of
<literal>mysql_stmt_fetch()</literal> determines the
- interpretation of the length. If
- <literal>mysql_stmt_fetch()</literal> returns 0,
- <literal>*length</literal> indicates the actual length of
- the parameter value. If
- <literal>mysql_stmt_fetch()</literal> returns
- <literal>MYSQL_DATA_TRUNCATED</literal>,
- <literal>*length</literal> indicates the non-truncated
- length of the parameter value. In this case, the minimum
- of <literal>*length</literal> and
- <literal>buffer_length</literal> indicates the actual
- length of the value.
+ interpretation of the length:
</para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If <literal>mysql_stmt_fetch()</literal> returns 0,
+ <literal>*length</literal> indicates the actual length
+ of the parameter value.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If <literal>mysql_stmt_fetch()</literal> returns
+ <literal>MYSQL_DATA_TRUNCATED</literal>,
+ <literal>*length</literal> indicates the non-truncated
+ length of the parameter value. In this case, the
+ minimum of <literal>*length</literal> and
+ <literal>buffer_length</literal> indicates the actual
+ length of the value.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
<para>
<literal>length</literal> is ignored for numeric and
temporal data types because the length of the data value
@@ -8104,15 +8128,13 @@
<literal>NULL</literal>. For input, set
<literal>*is_null</literal> to true to indicate that you
are passing a <literal>NULL</literal> value as a statement
- parameter. For output, this value is set to true after you
- fetch a row if the result set column value returned from
- the statement is <literal>NULL</literal>.
+ parameter.
</para>
<para>
<literal>is_null</literal> is a pointer to a boolean
- rather than a boolean scalar so that it can be used in the
- following way:
+ rather than a boolean scalar to provide flexibility in how
+ you specify <literal>NULL</literal> values:
</para>
<itemizedlist>
@@ -8121,31 +8143,41 @@
<para>
If your data values are always
<literal>NULL</literal>, use
- <literal>MYSQL_TYPE_NULL</literal> to bind the column.
+ <literal>MYSQL_TYPE_NULL</literal> as the
+ <literal>buffer_type</literal> value when you bind the
+ column. The other members do not matter.
</para>
</listitem>
<listitem>
<para>
If your data values are always <literal>NOT
- NULL</literal>, set <literal>is_null = (my_bool*)
- 0</literal>.
+ NULL</literal>, set the other members appropriately
+ for the variable you are binding, and set
+ <literal>is_null = (my_bool*) 0</literal>.
</para>
</listitem>
<listitem>
<para>
- In all other cases, you should set
- <literal>is_null</literal> to the address of a
- <literal>my_bool</literal> variable and change that
- variable's value appropriately between executions to
- indicate whether data values are
- <literal>NULL</literal> or <literal>NOT
- NULL</literal>.
+ In all other cases, set the other members
+ appriopriate, and set <literal>is_null</literal> to
+ the address of a <literal>my_bool</literal> variable.
+ Set that variable's value to true or false
+ appropriately between executions to indicate whether
+ data values are <literal>NULL</literal> or
+ <literal>NOT NULL</literal>, respectively.
</para>
</listitem>
</itemizedlist>
+
+ <para>
+ For output, the value pointed to by
+ <literal>is_null</literal> is set to true after you fetch
+ a row if the result set column value returned from the
+ statement is <literal>NULL</literal>.
+ </para>
</listitem>
<listitem>
@@ -8165,8 +8197,8 @@
<literal>buffer</literal>, specify a type code of
<literal>MYSQL_TYPE_TINY</literal> and set
<literal>is_unsigned</literal> to false. If you bind an
- <literal>unsigned char</literal> insteaad, the type code
- is the same, but <literal>is_unsigned</literal> should be
+ <literal>unsigned char</literal> instead, the type code is
+ the same, but <literal>is_unsigned</literal> should be
true.
</para>
@@ -8174,12 +8206,14 @@
<literal>is_unsigned</literal> indicates nothing about the
signedness of the SQL value that you are sending or
receiving. For example, if you use an
- <literal>int</literal> (signed) variable to supply a value
- for a <literal>BIGINT UNSIGNED</literal> column,
- <literal>is_unsigned</literal> should be false. If you use
- an <literal>unsigned int</literal> variable to supply a
- value for a <literal>BIGINT</literal> (signed) column,
- <literal>is_unsigned</literal> should be true. MySQL
+ <literal>int</literal> variable to supply a value for a
+ <literal>BIGINT UNSIGNED</literal> column,
+ <literal>is_unsigned</literal> should be false because
+ <literal>int</literal> is a signed type. If you use an
+ <literal>unsigned int</literal> variable to supply a value
+ for a <literal>BIGINT</literal> column,
+ <literal>is_unsigned</literal> should be true because
+ <literal>unsigned int</literal> is an unsigned type. MySQL
performs the proper conversion between signed and unsigned
values in both directions, although a warning occurs if
truncation results.
@@ -8220,8 +8254,8 @@
<informaltable>
<tgroup cols="2">
- <colspec colwidth="45*"/>
- <colspec colwidth="55*"/>
+ <colspec colwidth="40*"/>
+ <colspec colwidth="60*"/>
<tbody>
<row>
<entry><emphasis role="bold">Member</emphasis></entry>
@@ -8274,7 +8308,7 @@
<para>
Only those parts of a <literal>MYSQL_TIME</literal> structure
- that apply to a given type of temporal value are used: The
+ that apply to a given type of temporal value are used. The
<literal>year</literal>, <literal>month</literal>, and
<literal>day</literal> elements are used for
<literal>DATE</literal>, <literal>DATETIME</literal>, and
@@ -8293,14 +8327,16 @@
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 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.
+ value should be chosen according to the data type of the C
+ language variable that you are binding. If the variable is
+ <literal>unsigned</literal>, you should also set the
+ <literal>is_unsigned</literal> member to true.
</para>
<informaltable>
<tgroup cols="2">
- <colspec colwidth="35*"/>
- <colspec colwidth="65*"/>
+ <colspec colwidth="30*"/>
+ <colspec colwidth="70*"/>
<tbody>
<row>
<entry><emphasis role="bold">C Variable Type</emphasis></entry>
@@ -8354,26 +8390,37 @@
<entry><literal>char[]</literal></entry>
<entry><literal>MYSQL_TYPE_BLOB</literal> (for binary data)</entry>
</row>
+ <row>
+ <entry/>
+ <entry><literal>MYSQL_TYPE_NULL</literal></entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
<para>
+ The use of <literal>MYSQL_TYPE_NULL</literal> is described earlier
+ in connection with the <literal>is_null</literal> member.
+ </para>
+
+ <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 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.
+ 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. If you
+ use an <literal>unsigned</literal> variable, you should also set
+ the <literal>is_unsigned</literal> member to true. Note that
+ <literal>DECIMAL</literal> values are returned as strings.
</para>
<informaltable>
<tgroup cols="3">
- <colspec colwidth="33*"/>
- <colspec colwidth="33*"/>
- <colspec colwidth="33*"/>
+ <colspec colwidth="30*"/>
+ <colspec colwidth="35*"/>
+ <colspec colwidth="35*"/>
<tbody>
<row>
<entry><emphasis role="bold">SQL Type</emphasis></entry>
@@ -8482,15 +8529,16 @@
</para>
<para>
- For input character (non-binary) string data, the value is assumed
- to be in the character set indicated by the
+ For input character (non-binary) string data (indicated by
+ <literal>MYSQL_TYPE_STRING</literal>), 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.
+ <literal>MYSQL_TYPE_BLOB</literal>), 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>
@@ -9413,7 +9461,8 @@
<para>
To bind a column, an application calls
<literal>mysql_stmt_bind_result()</literal> and passes the type,
- address, and the address of the length buffer.
+ address, and length of the output buffer into which the value
+ should be stored.
<xref linkend="c-api-prepared-statement-datatypes"/>, describes
the members of each <literal>MYSQL_BIND</literal> element and
how they should be set to receive output values.
Modified: trunk/refman-5.0/apis-c.xml
===================================================================
--- trunk/refman-5.0/apis-c.xml 2007-02-07 17:27:08 UTC (rev 4845)
+++ trunk/refman-5.0/apis-c.xml 2007-02-07 17:58:10 UTC (rev 4846)
Changed blocks: 17, Lines Added: 134, Lines Deleted: 85; 17541 bytes
@@ -7945,14 +7945,14 @@
<title>C API Prepared Statement Data types</title>
<para>
- Prepared statements use these data structures:
+ Prepared statements use several data structures:
</para>
<itemizedlist>
<listitem>
<para>
- To prepare a statement, call
+ To prepare a statement, pass the statement string to
<literal>mysql_stmt_init()</literal>, which returns a pointer
to a <literal>MYSQL_STMT</literal> data structure.
</para>
@@ -7978,8 +7978,8 @@
</itemizedlist>
<para>
- The following descriptions provide additional detail on the use of
- the prepared statement data types.
+ The following discussion describes the prepared statement data
+ types in detail.
</para>
<itemizedlist>
@@ -8005,9 +8005,10 @@
<para>
The <literal>MYSQL_STMT</literal> structure has no members
- that are for application use. Also, you should not try to make
- a copy of a <literal>MYSQL_STMT</literal> structure. There is
- no guarantee that such a copy will be usable.
+ that are intended for application use. Also, you should not
+ try to make a copy of a <literal>MYSQL_STMT</literal>
+ structure. There is no guarantee that such a copy will be
+ usable.
</para>
<para>
@@ -8063,15 +8064,15 @@
</para>
<programlisting>
-MYSQL_BIND bind[3];
+MYSQL_BIND bind[3];
memset(bind, 0, sizeof(bind));
</programlisting>
<para>
The <literal>MYSQL_BIND</literal> structure contains the
- following members for use by application programs. A given
- member might be used for different purposes, depending on
- whether the structure is used for input or output.
+ following members for use by application programs. For several
+ of the members, the manner of use depends on whether the
+ structure is used for input or output.
</para>
<itemizedlist>
@@ -8098,19 +8099,21 @@
</para>
<para>
- For input, this is a pointer to the buffer in which a
- statement parameter's data value is stored. When you call
+ For input, <literal>buffer</literal> is a pointer to the
+ buffer in which a 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.
+ value that you have stored in the buffer 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.
+ For output, <literal>buffer</literal> 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>
@@ -8118,9 +8121,9 @@
<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
+ (For <literal>char</literal> or integer variables, you
+ should also indicate whether the variable has the
+ <literal>unsigned</literal> attribute by setting the
<literal>is_unsigned</literal> member, described later in
this list.) For date and time data types,
<literal>buffer</literal> should point to a
@@ -8155,27 +8158,48 @@
A pointer to an <literal>unsigned long</literal> variable
that indicates the actual number of bytes of data stored
in <literal>*buffer</literal>. <literal>length</literal>
- is used for character or binary C data. For input
- parameter data binding, <literal>length</literal> points
- to an <literal>unsigned long</literal> variable that
- indicates the actual length of the parameter value stored
- in <literal>*buffer</literal>; this is used by
- <literal>mysql_stmt_execute()</literal>. For output value
- binding, the return value of
+ is used for character or binary C data.
+ </para>
+
+ <para>
+ For input parameter data binding,
+ <literal>length</literal> points to an <literal>unsigned
+ long</literal> variable that indicates the actual length
+ of the parameter value stored in
+ <literal>*buffer</literal>; this is used by
+ <literal>mysql_stmt_execute()</literal>.
+ </para>
+
+ <para>
+ For output value binding, the return value of
<literal>mysql_stmt_fetch()</literal> determines the
- interpretation of the length. If
- <literal>mysql_stmt_fetch()</literal> returns 0,
- <literal>*length</literal> indicates the actual length of
- the parameter value. If
- <literal>mysql_stmt_fetch()</literal> returns
- <literal>MYSQL_DATA_TRUNCATED</literal>,
- <literal>*length</literal> indicates the non-truncated
- length of the parameter value. In this case, the minimum
- of <literal>*length</literal> and
- <literal>buffer_length</literal> indicates the actual
- length of the value.
+ interpretation of the length:
</para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If <literal>mysql_stmt_fetch()</literal> returns 0,
+ <literal>*length</literal> indicates the actual length
+ of the parameter value.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If <literal>mysql_stmt_fetch()</literal> returns
+ <literal>MYSQL_DATA_TRUNCATED</literal>,
+ <literal>*length</literal> indicates the non-truncated
+ length of the parameter value. In this case, the
+ minimum of <literal>*length</literal> and
+ <literal>buffer_length</literal> indicates the actual
+ length of the value.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
<para>
<literal>length</literal> is ignored for numeric and
temporal data types because the length of the data value
@@ -8195,15 +8219,13 @@
<literal>NULL</literal>. For input, set
<literal>*is_null</literal> to true to indicate that you
are passing a <literal>NULL</literal> value as a statement
- parameter. For output, this value is set to true after you
- fetch a row if the result set column value returned from
- the statement is <literal>NULL</literal>.
+ parameter.
</para>
<para>
<literal>is_null</literal> is a pointer to a boolean
- rather than a boolean scalar so that it can be used in the
- following way:
+ rather than a boolean scalar to provide flexibility in how
+ you specify <literal>NULL</literal> values:
</para>
<itemizedlist>
@@ -8212,31 +8234,41 @@
<para>
If your data values are always
<literal>NULL</literal>, use
- <literal>MYSQL_TYPE_NULL</literal> to bind the column.
+ <literal>MYSQL_TYPE_NULL</literal> as the
+ <literal>buffer_type</literal> value when you bind the
+ column. The other members do not matter.
</para>
</listitem>
<listitem>
<para>
If your data values are always <literal>NOT
- NULL</literal>, set <literal>is_null = (my_bool*)
- 0</literal>.
+ NULL</literal>, set the other members appropriately
+ for the variable you are binding, and set
+ <literal>is_null = (my_bool*) 0</literal>.
</para>
</listitem>
<listitem>
<para>
- In all other cases, you should set
- <literal>is_null</literal> to the address of a
- <literal>my_bool</literal> variable and change that
- variable's value appropriately between executions to
- indicate whether data values are
- <literal>NULL</literal> or <literal>NOT
- NULL</literal>.
+ In all other cases, set the other members
+ appriopriate, and set <literal>is_null</literal> to
+ the address of a <literal>my_bool</literal> variable.
+ Set that variable's value to true or false
+ appropriately between executions to indicate whether
+ data values are <literal>NULL</literal> or
+ <literal>NOT NULL</literal>, respectively.
</para>
</listitem>
</itemizedlist>
+
+ <para>
+ For output, the value pointed to by
+ <literal>is_null</literal> is set to true after you fetch
+ a row if the result set column value returned from the
+ statement is <literal>NULL</literal>.
+ </para>
</listitem>
<listitem>
@@ -8256,8 +8288,8 @@
<literal>buffer</literal>, specify a type code of
<literal>MYSQL_TYPE_TINY</literal> and set
<literal>is_unsigned</literal> to false. If you bind an
- <literal>unsigned char</literal> insteaad, the type code
- is the same, but <literal>is_unsigned</literal> should be
+ <literal>unsigned char</literal> instead, the type code is
+ the same, but <literal>is_unsigned</literal> should be
true.
</para>
@@ -8265,12 +8297,14 @@
<literal>is_unsigned</literal> indicates nothing about the
signedness of the SQL value that you are sending or
receiving. For example, if you use an
- <literal>int</literal> (signed) variable to supply a value
- for a <literal>BIGINT UNSIGNED</literal> column,
- <literal>is_unsigned</literal> should be false. If you use
- an <literal>unsigned int</literal> variable to supply a
- value for a <literal>BIGINT</literal> (signed) column,
- <literal>is_unsigned</literal> should be true. MySQL
+ <literal>int</literal> variable to supply a value for a
+ <literal>BIGINT UNSIGNED</literal> column,
+ <literal>is_unsigned</literal> should be false because
+ <literal>int</literal> is a signed type. If you use an
+ <literal>unsigned int</literal> variable to supply a value
+ for a <literal>BIGINT</literal> column,
+ <literal>is_unsigned</literal> should be true because
+ <literal>unsigned int</literal> is an unsigned type. MySQL
performs the proper conversion between signed and unsigned
values in both directions, although a warning occurs if
truncation results.
@@ -8336,8 +8370,8 @@
<informaltable>
<tgroup cols="2">
- <colspec colwidth="45*"/>
- <colspec colwidth="55*"/>
+ <colspec colwidth="40*"/>
+ <colspec colwidth="60*"/>
<tbody>
<row>
<entry><emphasis role="bold">Member</emphasis></entry>
@@ -8390,7 +8424,7 @@
<para>
Only those parts of a <literal>MYSQL_TIME</literal> structure
- that apply to a given type of temporal value are used: The
+ that apply to a given type of temporal value are used. The
<literal>year</literal>, <literal>month</literal>, and
<literal>day</literal> elements are used for
<literal>DATE</literal>, <literal>DATETIME</literal>, and
@@ -8409,14 +8443,16 @@
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 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.
+ value should be chosen according to the data type of the C
+ language variable that you are binding. If the variable is
+ <literal>unsigned</literal>, you should also set the
+ <literal>is_unsigned</literal> member to true.
</para>
<informaltable>
<tgroup cols="2">
- <colspec colwidth="35*"/>
- <colspec colwidth="65*"/>
+ <colspec colwidth="30*"/>
+ <colspec colwidth="70*"/>
<tbody>
<row>
<entry><emphasis role="bold">C Variable Type</emphasis></entry>
@@ -8470,26 +8506,37 @@
<entry><literal>char[]</literal></entry>
<entry><literal>MYSQL_TYPE_BLOB</literal> (for binary data)</entry>
</row>
+ <row>
+ <entry/>
+ <entry><literal>MYSQL_TYPE_NULL</literal></entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
<para>
+ The use of <literal>MYSQL_TYPE_NULL</literal> is described earlier
+ in connection with the <literal>is_null</literal> member.
+ </para>
+
+ <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 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.
+ 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. If you
+ use an <literal>unsigned</literal> variable, you should also set
+ the <literal>is_unsigned</literal> member to true. Note that
+ <literal>DECIMAL</literal> values are returned as strings.
</para>
<informaltable>
<tgroup cols="3">
- <colspec colwidth="33*"/>
- <colspec colwidth="33*"/>
- <colspec colwidth="33*"/>
+ <colspec colwidth="30*"/>
+ <colspec colwidth="35*"/>
+ <colspec colwidth="35*"/>
<tbody>
<row>
<entry><emphasis role="bold">SQL Type</emphasis></entry>
@@ -8608,15 +8655,16 @@
</para>
<para>
- For input character (non-binary) string data, the value is assumed
- to be in the character set indicated by the
+ For input character (non-binary) string data (indicated by
+ <literal>MYSQL_TYPE_STRING</literal>), 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.
+ <literal>MYSQL_TYPE_BLOB</literal>), 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>
@@ -9601,7 +9649,8 @@
<para>
To bind a column, an application calls
<literal>mysql_stmt_bind_result()</literal> and passes the type,
- address, and the address of the length buffer.
+ address, and length of the output buffer into which the value
+ should be stored.
<xref linkend="c-api-prepared-statement-datatypes"/>, describes
the members of each <literal>MYSQL_BIND</literal> element and
how they should be set to receive output values.
Modified: trunk/refman-5.1/apis-c.xml
===================================================================
--- trunk/refman-5.1/apis-c.xml 2007-02-07 17:27:08 UTC (rev 4845)
+++ trunk/refman-5.1/apis-c.xml 2007-02-07 17:58:10 UTC (rev 4846)
Changed blocks: 17, Lines Added: 134, Lines Deleted: 85; 17541 bytes
@@ -8064,14 +8064,14 @@
<title>C API Prepared Statement Data types</title>
<para>
- Prepared statements use these data structures:
+ Prepared statements use several data structures:
</para>
<itemizedlist>
<listitem>
<para>
- To prepare a statement, call
+ To prepare a statement, pass the statement string to
<literal>mysql_stmt_init()</literal>, which returns a pointer
to a <literal>MYSQL_STMT</literal> data structure.
</para>
@@ -8097,8 +8097,8 @@
</itemizedlist>
<para>
- The following descriptions provide additional detail on the use of
- the prepared statement data types.
+ The following discussion describes the prepared statement data
+ types in detail.
</para>
<itemizedlist>
@@ -8124,9 +8124,10 @@
<para>
The <literal>MYSQL_STMT</literal> structure has no members
- that are for application use. Also, you should not try to make
- a copy of a <literal>MYSQL_STMT</literal> structure. There is
- no guarantee that such a copy will be usable.
+ that are intended for application use. Also, you should not
+ try to make a copy of a <literal>MYSQL_STMT</literal>
+ structure. There is no guarantee that such a copy will be
+ usable.
</para>
<para>
@@ -8182,15 +8183,15 @@
</para>
<programlisting>
-MYSQL_BIND bind[3];
+MYSQL_BIND bind[3];
memset(bind, 0, sizeof(bind));
</programlisting>
<para>
The <literal>MYSQL_BIND</literal> structure contains the
- following members for use by application programs. A given
- member might be used for different purposes, depending on
- whether the structure is used for input or output.
+ following members for use by application programs. For several
+ of the members, the manner of use depends on whether the
+ structure is used for input or output.
</para>
<itemizedlist>
@@ -8217,19 +8218,21 @@
</para>
<para>
- For input, this is a pointer to the buffer in which a
- statement parameter's data value is stored. When you call
+ For input, <literal>buffer</literal> is a pointer to the
+ buffer in which a 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.
+ value that you have stored in the buffer 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.
+ For output, <literal>buffer</literal> 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>
@@ -8237,9 +8240,9 @@
<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
+ (For <literal>char</literal> or integer variables, you
+ should also indicate whether the variable has the
+ <literal>unsigned</literal> attribute by setting the
<literal>is_unsigned</literal> member, described later in
this list.) For date and time data types,
<literal>buffer</literal> should point to a
@@ -8274,27 +8277,48 @@
A pointer to an <literal>unsigned long</literal> variable
that indicates the actual number of bytes of data stored
in <literal>*buffer</literal>. <literal>length</literal>
- is used for character or binary C data. For input
- parameter data binding, <literal>length</literal> points
- to an <literal>unsigned long</literal> variable that
- indicates the actual length of the parameter value stored
- in <literal>*buffer</literal>; this is used by
- <literal>mysql_stmt_execute()</literal>. For output value
- binding, the return value of
+ is used for character or binary C data.
+ </para>
+
+ <para>
+ For input parameter data binding,
+ <literal>length</literal> points to an <literal>unsigned
+ long</literal> variable that indicates the actual length
+ of the parameter value stored in
+ <literal>*buffer</literal>; this is used by
+ <literal>mysql_stmt_execute()</literal>.
+ </para>
+
+ <para>
+ For output value binding, the return value of
<literal>mysql_stmt_fetch()</literal> determines the
- interpretation of the length. If
- <literal>mysql_stmt_fetch()</literal> returns 0,
- <literal>*length</literal> indicates the actual length of
- the parameter value. If
- <literal>mysql_stmt_fetch()</literal> returns
- <literal>MYSQL_DATA_TRUNCATED</literal>,
- <literal>*length</literal> indicates the non-truncated
- length of the parameter value. In this case, the minimum
- of <literal>*length</literal> and
- <literal>buffer_length</literal> indicates the actual
- length of the value.
+ interpretation of the length:
</para>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If <literal>mysql_stmt_fetch()</literal> returns 0,
+ <literal>*length</literal> indicates the actual length
+ of the parameter value.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If <literal>mysql_stmt_fetch()</literal> returns
+ <literal>MYSQL_DATA_TRUNCATED</literal>,
+ <literal>*length</literal> indicates the non-truncated
+ length of the parameter value. In this case, the
+ minimum of <literal>*length</literal> and
+ <literal>buffer_length</literal> indicates the actual
+ length of the value.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
<para>
<literal>length</literal> is ignored for numeric and
temporal data types because the length of the data value
@@ -8314,15 +8338,13 @@
<literal>NULL</literal>. For input, set
<literal>*is_null</literal> to true to indicate that you
are passing a <literal>NULL</literal> value as a statement
- parameter. For output, this value is set to true after you
- fetch a row if the result set column value returned from
- the statement is <literal>NULL</literal>.
+ parameter.
</para>
<para>
<literal>is_null</literal> is a pointer to a boolean
- rather than a boolean scalar so that it can be used in the
- following way:
+ rather than a boolean scalar to provide flexibility in how
+ you specify <literal>NULL</literal> values:
</para>
<itemizedlist>
@@ -8331,31 +8353,41 @@
<para>
If your data values are always
<literal>NULL</literal>, use
- <literal>MYSQL_TYPE_NULL</literal> to bind the column.
+ <literal>MYSQL_TYPE_NULL</literal> as the
+ <literal>buffer_type</literal> value when you bind the
+ column. The other members do not matter.
</para>
</listitem>
<listitem>
<para>
If your data values are always <literal>NOT
- NULL</literal>, set <literal>is_null = (my_bool*)
- 0</literal>.
+ NULL</literal>, set the other members appropriately
+ for the variable you are binding, and set
+ <literal>is_null = (my_bool*) 0</literal>.
</para>
</listitem>
<listitem>
<para>
- In all other cases, you should set
- <literal>is_null</literal> to the address of a
- <literal>my_bool</literal> variable and change that
- variable's value appropriately between executions to
- indicate whether data values are
- <literal>NULL</literal> or <literal>NOT
- NULL</literal>.
+ In all other cases, set the other members
+ appriopriate, and set <literal>is_null</literal> to
+ the address of a <literal>my_bool</literal> variable.
+ Set that variable's value to true or false
+ appropriately between executions to indicate whether
+ data values are <literal>NULL</literal> or
+ <literal>NOT NULL</literal>, respectively.
</para>
</listitem>
</itemizedlist>
+
+ <para>
+ For output, the value pointed to by
+ <literal>is_null</literal> is set to true after you fetch
+ a row if the result set column value returned from the
+ statement is <literal>NULL</literal>.
+ </para>
</listitem>
<listitem>
@@ -8375,8 +8407,8 @@
<literal>buffer</literal>, specify a type code of
<literal>MYSQL_TYPE_TINY</literal> and set
<literal>is_unsigned</literal> to false. If you bind an
- <literal>unsigned char</literal> insteaad, the type code
- is the same, but <literal>is_unsigned</literal> should be
+ <literal>unsigned char</literal> instead, the type code is
+ the same, but <literal>is_unsigned</literal> should be
true.
</para>
@@ -8384,12 +8416,14 @@
<literal>is_unsigned</literal> indicates nothing about the
signedness of the SQL value that you are sending or
receiving. For example, if you use an
- <literal>int</literal> (signed) variable to supply a value
- for a <literal>BIGINT UNSIGNED</literal> column,
- <literal>is_unsigned</literal> should be false. If you use
- an <literal>unsigned int</literal> variable to supply a
- value for a <literal>BIGINT</literal> (signed) column,
- <literal>is_unsigned</literal> should be true. MySQL
+ <literal>int</literal> variable to supply a value for a
+ <literal>BIGINT UNSIGNED</literal> column,
+ <literal>is_unsigned</literal> should be false because
+ <literal>int</literal> is a signed type. If you use an
+ <literal>unsigned int</literal> variable to supply a value
+ for a <literal>BIGINT</literal> column,
+ <literal>is_unsigned</literal> should be true because
+ <literal>unsigned int</literal> is an unsigned type. MySQL
performs the proper conversion between signed and unsigned
values in both directions, although a warning occurs if
truncation results.
@@ -8454,8 +8488,8 @@
<informaltable>
<tgroup cols="2">
- <colspec colwidth="45*"/>
- <colspec colwidth="55*"/>
+ <colspec colwidth="40*"/>
+ <colspec colwidth="60*"/>
<tbody>
<row>
<entry><emphasis role="bold">Member</emphasis></entry>
@@ -8508,7 +8542,7 @@
<para>
Only those parts of a <literal>MYSQL_TIME</literal> structure
- that apply to a given type of temporal value are used: The
+ that apply to a given type of temporal value are used. The
<literal>year</literal>, <literal>month</literal>, and
<literal>day</literal> elements are used for
<literal>DATE</literal>, <literal>DATETIME</literal>, and
@@ -8527,14 +8561,16 @@
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 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.
+ value should be chosen according to the data type of the C
+ language variable that you are binding. If the variable is
+ <literal>unsigned</literal>, you should also set the
+ <literal>is_unsigned</literal> member to true.
</para>
<informaltable>
<tgroup cols="2">
- <colspec colwidth="35*"/>
- <colspec colwidth="65*"/>
+ <colspec colwidth="30*"/>
+ <colspec colwidth="70*"/>
<tbody>
<row>
<entry><emphasis role="bold">C Variable Type</emphasis></entry>
@@ -8588,26 +8624,37 @@
<entry><literal>char[]</literal></entry>
<entry><literal>MYSQL_TYPE_BLOB</literal> (for binary data)</entry>
</row>
+ <row>
+ <entry/>
+ <entry><literal>MYSQL_TYPE_NULL</literal></entry>
+ </row>
</tbody>
</tgroup>
</informaltable>
<para>
+ The use of <literal>MYSQL_TYPE_NULL</literal> is described earlier
+ in connection with the <literal>is_null</literal> member.
+ </para>
+
+ <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 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.
+ 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. If you
+ use an <literal>unsigned</literal> variable, you should also set
+ the <literal>is_unsigned</literal> member to true. Note that
+ <literal>DECIMAL</literal> values are returned as strings.
</para>
<informaltable>
<tgroup cols="3">
- <colspec colwidth="33*"/>
- <colspec colwidth="33*"/>
- <colspec colwidth="33*"/>
+ <colspec colwidth="30*"/>
+ <colspec colwidth="35*"/>
+ <colspec colwidth="35*"/>
<tbody>
<row>
<entry><emphasis role="bold">SQL Type</emphasis></entry>
@@ -8726,15 +8773,16 @@
</para>
<para>
- For input character (non-binary) string data, the value is assumed
- to be in the character set indicated by the
+ For input character (non-binary) string data (indicated by
+ <literal>MYSQL_TYPE_STRING</literal>), 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.
+ <literal>MYSQL_TYPE_BLOB</literal>), 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>
@@ -9649,7 +9697,8 @@
<para>
To bind a column, an application calls
<literal>mysql_stmt_bind_result()</literal> and passes the type,
- address, and the address of the length buffer.
+ address, and length of the output buffer into which the value
+ should be stored.
<xref linkend="c-api-prepared-statement-datatypes"/>, describes
the members of each <literal>MYSQL_BIND</literal> element and
how they should be set to receive output values.
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r4846 - in trunk: . refman-4.1 refman-5.0 refman-5.1 | paul | 7 Feb |
