Author: paul
Date: 2007-11-04 03:04:16 +0100 (Sun, 04 Nov 2007)
New Revision: 8525
Log:
r26546@frost: paul | 2007-11-03 20:58:11 -0500
Reformat.
Modified:
trunk/refman-4.1/apis-c.xml
trunk/refman-4.1/dba-core.xml
trunk/refman-4.1/errors-problems.xml
trunk/refman-4.1/news-3.23.xml
trunk/refman-4.1/news-4.0.xml
trunk/refman-4.1/sql-syntax.xml
trunk/refman-5.0/apis-c.xml
trunk/refman-5.0/dba-core.xml
trunk/refman-5.0/errors-problems.xml
trunk/refman-5.0/replication-solutions.xml
trunk/refman-5.0/restrictions.xml
trunk/refman-5.0/se-federated.xml
trunk/refman-5.0/sql-syntax.xml
trunk/refman-5.0/stored-procedures.xml
trunk/refman-5.1/apis-c.xml
trunk/refman-5.1/dba-core.xml
trunk/refman-5.1/errors-problems-core.xml
trunk/refman-5.1/extending-mysql.xml
trunk/refman-5.1/mysql-cluster-configuration.xml
trunk/refman-5.1/replication-solutions.xml
trunk/refman-5.1/restrictions.xml
trunk/refman-5.1/se-federated.xml
trunk/refman-5.1/sql-syntax.xml
trunk/refman-5.1/stored-procedures.xml
trunk/refman-6.0/apis-c.xml
trunk/refman-6.0/dba-core.xml
trunk/refman-6.0/errors-problems.xml
trunk/refman-6.0/extending-mysql.xml
trunk/refman-6.0/optimization.xml
trunk/refman-6.0/replication-solutions.xml
trunk/refman-6.0/restrictions.xml
trunk/refman-6.0/se-federated.xml
trunk/refman-6.0/sql-syntax.xml
trunk/refman-6.0/stored-procedures.xml
trunk/refman-common/connector-j.xml
trunk/refman-common/connector-net.xml
trunk/refman-common/news-cj-core.xml
trunk/refman-common/news-cmxj-core.xml
trunk/refman-common/news-cnet-core.xml
trunk/refman-common/news-codbc-core.xml
trunk/refman-common/news-innodb.xml
trunk/refman-common/news-mysql-proxy-core.xml
trunk/refman-common/news-vstudioplugin-core.xml
trunk/refman-common/replication-drbd.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:32228
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:26545
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:21581
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:32228
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:26546
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:21581
Modified: trunk/refman-4.1/apis-c.xml
===================================================================
--- trunk/refman-4.1/apis-c.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-4.1/apis-c.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 102, Lines Added: 500, Lines Deleted: 407; 82924 bytes
@@ -1312,8 +1312,8 @@
<para>
After you are done with a result set, call
- <function role="capi">mysql_free_result()</function> to free the memory used for
- it.
+ <function role="capi">mysql_free_result()</function> to free the
+ memory used for it.
</para>
<para>
@@ -1329,12 +1329,13 @@
<function role="capi">mysql_store_result()</function> is that
because the rows have all been fetched to the client, you not only
can access rows sequentially, you can move back and forth in the
- result set using <function role="capi">mysql_data_seek()</function> or
+ result set using
+ <function role="capi">mysql_data_seek()</function> or
<function role="capi">mysql_row_seek()</function> to change the
current row position within the result set. You can also find out
how many rows there are by calling
- <function role="capi">mysql_num_rows()</function>. On the other hand, the memory
- requirements for
+ <function role="capi">mysql_num_rows()</function>. On the other
+ hand, the memory requirements for
<function role="capi">mysql_store_result()</function> may be very
high for large result sets and you are more likely to encounter
out-of-memory conditions.
@@ -2117,8 +2118,8 @@
<para>
This function requires that the result set structure contains
the entire result of the query, so
- <function role="capi">mysql_data_seek()</function> may be used only in
- conjunction with
+ <function role="capi">mysql_data_seek()</function> may be used
+ only in conjunction with
<function role="capi">mysql_store_result()</function>, not with
<function role="capi">mysql_use_result()</function>.
</para>
@@ -2159,9 +2160,9 @@
<para>
Does a <literal>DBUG_PUSH</literal> with the given string.
- <function role="capi">mysql_debug()</function> uses the Fred Fish debug
- library. To use this function, you must compile the client
- library to support debugging. See
+ <function role="capi">mysql_debug()</function> uses the Fred
+ Fish debug library. To use this function, you must compile the
+ client library to support debugging. See
<ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
Internals: Porting</ulink>.
</para>
@@ -2674,19 +2675,21 @@
</indexterm>
<para>
- You should use <function role="capi">mysql_real_escape_string()</function>
+ You should use
+ <function role="capi">mysql_real_escape_string()</function>
instead!
</para>
<para>
This function is identical to
- <function role="capi">mysql_real_escape_string()</function> except that
- <function role="capi">mysql_real_escape_string()</function> takes a connection
- handler as its first argument and escapes the string according
- to the current character set.
- <function role="capi">mysql_escape_string()</function> does not take a
- connection argument and does not respect the current character
- set.
+ <function role="capi">mysql_real_escape_string()</function>
+ except that
+ <function role="capi">mysql_real_escape_string()</function>
+ takes a connection handler as its first argument and escapes the
+ string according to the current character set.
+ <function role="capi">mysql_escape_string()</function> does not
+ take a connection argument and does not respect the current
+ character set.
</para>
</section>
@@ -2794,7 +2797,8 @@
<literal>MYSQL_FIELD</literal> structure. You may use this
function to retrieve the definition for an arbitrary column. The
value of <literal>fieldnr</literal> should be in the range from
- 0 to <function role="capi">mysql_num_fields(result)-1</function>.
+ 0 to
+ <function role="capi">mysql_num_fields(result)-1</function>.
</para>
<para>
@@ -3314,9 +3318,10 @@
Frees the memory allocated for a result set by
<function role="capi">mysql_store_result()</function>,
<function role="capi">mysql_use_result()</function>,
- <function role="capi">mysql_list_dbs()</function>, and so forth. When you are
- done with a result set, you must free the memory it uses by
- calling <function role="capi">mysql_free_result()</function>.
+ <function role="capi">mysql_list_dbs()</function>, and so forth.
+ When you are done with a result set, you must free the memory it
+ uses by calling
+ <function role="capi">mysql_free_result()</function>.
</para>
<para>
@@ -3644,10 +3649,10 @@
<literal>length</literal> bytes long. You must allocate the
<literal>to</literal> buffer to be at least
<literal>length*2+1</literal> bytes long. When
- <function role="capi">mysql_hex_string()</function> returns, the contents of
- <literal>to</literal> is a null-terminated string. The return
- value is the length of the encoded string, not including the
- terminating null character.
+ <function role="capi">mysql_hex_string()</function> returns, the
+ contents of <literal>to</literal> is a null-terminated string.
+ The return value is the length of the encoded string, not
+ including the terminating null character.
</para>
<para>
@@ -3660,8 +3665,8 @@
</para>
<para>
- <function role="capi">mysql_hex_string()</function> was added in MySQL 4.0.23
- and 4.1.8.
+ <function role="capi">mysql_hex_string()</function> was added in
+ MySQL 4.0.23 and 4.1.8.
</para>
<para>
@@ -4309,8 +4314,8 @@
<quote><literal>%</literal></quote> or
<quote><literal>_</literal></quote>, or may be a
<literal>NULL</literal> pointer to match all databases. Calling
- <function role="capi">mysql_list_dbs()</function> is similar to executing the
- query <literal>SHOW databases [LIKE
+ <function role="capi">mysql_list_dbs()</function> is similar to
+ executing the query <literal>SHOW databases [LIKE
<replaceable>wild</replaceable>]</literal>.
</para>
@@ -4413,8 +4418,8 @@
characters <quote><literal>%</literal></quote> or
<quote><literal>_</literal></quote>, or may be a
<literal>NULL</literal> pointer to match all fields. Calling
- <function role="capi">mysql_list_fields()</function> is similar to executing
- the query <literal>SHOW COLUMNS FROM
+ <function role="capi">mysql_list_fields()</function> is similar
+ to executing the query <literal>SHOW COLUMNS FROM
<replaceable>tbl_name</replaceable> [LIKE
<replaceable>wild</replaceable>]</literal>.
</para>
@@ -4612,8 +4617,8 @@
</para>
<para>
- <function role="capi">mysql_num_rows()</function> is intended for use with
- statements that return a result set, such as
+ <function role="capi">mysql_num_rows()</function> is intended
+ for use with statements that return a result set, such as
<literal>SELECT</literal>. For statements such as
<literal>INSERT</literal>, <literal>UPDATE</literal>, or
<literal>DELETE</literal>, the number of affected rows can be
@@ -4702,10 +4707,11 @@
</para>
<para>
- <function role="capi">mysql_more_results()</function> true if more results
- exist from the currently executed statement, in which case the
- application must call <function role="capi">mysql_next_result()</function> to
- fetch the results.
+ <function role="capi">mysql_more_results()</function> true if
+ more results exist from the currently executed statement, in
+ which case the application must call
+ <function role="capi">mysql_next_result()</function> to fetch
+ the results.
</para>
<para>
@@ -4723,8 +4729,8 @@
<para>
In most cases, you can call
- <function role="capi">mysql_next_result()</function> instead to test whether
- more results exist and initiate retrieval if so.
+ <function role="capi">mysql_next_result()</function> instead to
+ test whether more results exist and initiate retrieval if so.
</para>
<para>
@@ -4765,18 +4771,22 @@
<para>
If more statement results exist,
- <function role="capi">mysql_next_result()</function> reads the next statement
- result and returns the status back to the application.
+ <function role="capi">mysql_next_result()</function> reads the
+ next statement result and returns the status back to the
+ application.
</para>
<para>
- Before calling <function role="capi">mysql_next_result()</function>, you must
- call <function role="capi">mysql_free_result()</function> for the preceding
- statement if it is a query that returned a result set.
+ Before calling
+ <function role="capi">mysql_next_result()</function>, you must
+ call <function role="capi">mysql_free_result()</function> for
+ the preceding statement if it is a query that returned a result
+ set.
</para>
<para>
- After calling <function role="capi">mysql_next_result()</function> the state
+ After calling
+ <function role="capi">mysql_next_result()</function> the state
of the connection is as if you had called
<function role="capi">mysql_real_query()</function> or
<function role="capi">mysql_query()</function> for the next
@@ -4788,9 +4798,9 @@
</para>
<para>
- If <function role="capi">mysql_next_result()</function> returns an error, no
- other statements are executed and there are no more results to
- fetch.
+ If <function role="capi">mysql_next_result()</function> returns
+ an error, no other statements are executed and there are no more
+ results to fetch.
</para>
<para>
@@ -5034,16 +5044,18 @@
</para>
<para>
- The use of <function role="capi">mysql_num_rows()</function> depends on
- whether you use
+ The use of <function role="capi">mysql_num_rows()</function>
+ depends on whether you use
<function role="capi">mysql_store_result()</function> or
<function role="capi">mysql_use_result()</function> to return
the result set. If you use
<function role="capi">mysql_store_result()</function>,
- <function role="capi">mysql_num_rows()</function> may be called immediately.
- If you use <function role="capi">mysql_use_result()</function>,
- <function role="capi">mysql_num_rows()</function> does not return the correct
- value until all the rows in the result set have been retrieved.
+ <function role="capi">mysql_num_rows()</function> may be called
+ immediately. If you use
+ <function role="capi">mysql_use_result()</function>,
+ <function role="capi">mysql_num_rows()</function> does not
+ return the correct value until all the rows in the result set
+ have been retrieved.
</para>
<para>
@@ -5877,7 +5889,8 @@
parameters use whatever character set has been configured
for the <literal>MYSQL</literal> object. By default, this is
<literal>latin1</literal>, but can be changed by calling
- <function role="capi">mysql_options(mysql, MYSQL_SET_CHARSET_NAME,
+ <function role="capi">mysql_options(mysql,
+ MYSQL_SET_CHARSET_NAME,
"<replaceable>charset_name</replaceable>")</function> prior
to connecting.
</para>
@@ -5986,7 +5999,8 @@
<entry>Use SSL (encrypted protocol). This option should not be set by
application programs; it is set internally in the
client library. Instead, use
- <function role="capi">mysql_ssl_set()</function> before calling
+ <function role="capi">mysql_ssl_set()</function>
+ before calling
<function role="capi">mysql_real_connect()</function>.</entry>
</row>
</tbody>
@@ -6002,7 +6016,8 @@
result for every call to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -6304,21 +6319,23 @@
<literal>length*2+1</literal> bytes long. (In the worst case,
each character may need to be encoded as using two bytes, and
you need room for the terminating null byte.) When
- <function role="capi">mysql_real_escape_string()</function> returns, the
- contents of <literal>to</literal> is a null-terminated string.
- The return value is the length of the encoded string, not
- including the terminating null character.
+ <function role="capi">mysql_real_escape_string()</function>
+ returns, the contents of <literal>to</literal> is a
+ null-terminated string. The return value is the length of the
+ encoded string, not including the terminating null character.
</para>
<para>
If you need to change the character set of the connection, you
- should use the <function role="capi">mysql_set_character_set()</function>
+ should use the
+ <function role="capi">mysql_set_character_set()</function>
function rather than executing a <literal>SET NAMES</literal>
(or <literal>SET CHARACTER SET</literal>) statement.
- <function role="capi">mysql_set_character_set()</function> works like
- <literal>SET NAMES</literal> but also affects the character set
- used by <function role="capi">mysql_real_escape_string()</function>, which
- <literal>SET NAMES</literal> does not.
+ <function role="capi">mysql_set_character_set()</function> works
+ like <literal>SET NAMES</literal> but also affects the character
+ set used by
+ <function role="capi">mysql_real_escape_string()</function>,
+ which <literal>SET NAMES</literal> does not.
</para>
<para>
@@ -6813,7 +6830,8 @@
<function role="capi">mysql_row_tell()</function> or from
<function role="capi">mysql_row_seek()</function>. This value is
not a row number; if you want to seek to a row within a result
- set by number, use <function role="capi">mysql_data_seek()</function> instead.
+ set by number, use
+ <function role="capi">mysql_data_seek()</function> instead.
</para>
<para>
@@ -6920,9 +6938,9 @@
</para>
<para>
- <function role="capi">mysql_select_db()</function> fails unless the connected
- user can be authenticated as having permission to use the
- database.
+ <function role="capi">mysql_select_db()</function> fails unless
+ the connected user can be authenticated as having permission to
+ use the database.
</para>
<para>
@@ -7071,14 +7089,15 @@
Sets the <literal>LOAD LOCAL DATA INFILE</literal> handler
callback functions to the defaults used internally by the C
client library. The library calls this function automatically if
- <function role="capi">mysql_set_local_infile_handler()</function> has not been
- called or does not supply valid functions for each of its
- callbacks.
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ has not been called or does not supply valid functions for each
+ of its callbacks.
</para>
<para>
- The <function role="capi">mysql_set_local_infile_default()</function> function
- was added in MySQL 4.1.2.
+ The
+ <function role="capi">mysql_set_local_infile_default()</function>
+ function was added in MySQL 4.1.2.
</para>
<para>
@@ -7126,8 +7145,9 @@
</para>
<para>
- To use <function role="capi">mysql_set_local_infile_handler()</function>, you
- must write the following callback functions:
+ To use
+ <function role="capi">mysql_set_local_infile_handler()</function>,
+ you must write the following callback functions:
</para>
<programlisting>
@@ -7218,10 +7238,10 @@
<para>
After calling
- <function role="capi">mysql_set_local_infile_handler()</function> in your C
- code and passing pointers to your callback functions, you can
- then issue a <literal>LOAD DATA LOCAL INFILE</literal> statement
- (for example, by using
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ in your C code and passing pointers to your callback functions,
+ you can then issue a <literal>LOAD DATA LOCAL INFILE</literal>
+ statement (for example, by using
<function role="capi">mysql_query()</function>). The client
library automatically invokes your callbacks. The filename
specified in <literal>LOAD DATA LOCAL INFILE</literal> will be
@@ -7230,8 +7250,9 @@
</para>
<para>
- The <function role="capi">mysql_set_local_infile_handler()</function> function
- was added in MySQL 4.1.2.
+ The
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ function was added in MySQL 4.1.2.
</para>
<para>
@@ -7296,7 +7317,8 @@
results from calls to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -7366,9 +7388,9 @@
<para>
The server didn't support
- <function role="capi">mysql_set_server_option()</function> (which is the
- case that the server is older than 4.1.1) or the server
- didn't support the option one tried to set.
+ <function role="capi">mysql_set_server_option()</function>
+ (which is the case that the server is older than 4.1.1) or
+ the server didn't support the option one tried to set.
</para>
</listitem>
@@ -7403,8 +7425,9 @@
are planned to make it possible to choose the desired level.
Dynamically linked executables which have been compiled with
older versions of the <literal>libmysqlclient</literal> headers
- and call <function role="capi">mysql_shutdown()</function> need to be used
- with the old <literal>libmysqlclient</literal> dynamic library.
+ and call <function role="capi">mysql_shutdown()</function> need
+ to be used with the old <literal>libmysqlclient</literal>
+ dynamic library.
</para>
<para>
@@ -7571,14 +7594,14 @@
</para>
<para>
- <function role="capi">mysql_ssl_set()</function> is used for establishing
- secure connections using SSL. It must be called before
- <function role="capi">mysql_real_connect()</function>.
+ <function role="capi">mysql_ssl_set()</function> is used for
+ establishing secure connections using SSL. It must be called
+ before <function role="capi">mysql_real_connect()</function>.
</para>
<para>
- <function role="capi">mysql_ssl_set()</function> does nothing unless OpenSSL
- support is enabled in the client library.
+ <function role="capi">mysql_ssl_set()</function> does nothing
+ unless OpenSSL support is enabled in the client library.
</para>
<para>
@@ -7750,8 +7773,8 @@
(<literal>SELECT</literal>, <literal>SHOW</literal>,
<literal>DESCRIBE</literal>, <literal>EXPLAIN</literal>,
<literal>CHECK TABLE</literal>, and so forth). You must also
- call <function role="capi">mysql_free_result()</function> after you are done
- with the result set.
+ call <function role="capi">mysql_free_result()</function> after
+ you are done with the result set.
</para>
<para>
@@ -7772,7 +7795,8 @@
results from calls to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -7818,8 +7842,8 @@
After you have called
<function role="capi">mysql_store_result()</function> and gotten
back a result that isn't a null pointer, you can call
- <function role="capi">mysql_num_rows()</function> to find out how many rows
- are in the result set.
+ <function role="capi">mysql_num_rows()</function> to find out
+ how many rows are in the result set.
</para>
<para>
@@ -7927,15 +7951,16 @@
<para>
Returns the thread ID of the current connection. This value can
- be used as an argument to <function role="capi">mysql_kill()</function> to
- kill the thread.
+ be used as an argument to
+ <function role="capi">mysql_kill()</function> to kill the
+ thread.
</para>
<para>
If the connection is lost and you reconnect with
- <function role="capi">mysql_ping()</function>, the thread ID changes. This
- means you should not get the thread ID and store it for later.
- You should get it when you need it.
+ <function role="capi">mysql_ping()</function>, the thread ID
+ changes. This means you should not get the thread ID and store
+ it for later. You should get it when you need it.
</para>
<para>
@@ -8019,7 +8044,8 @@
</para>
<para>
- You may not use <function role="capi">mysql_data_seek()</function>,
+ You may not use
+ <function role="capi">mysql_data_seek()</function>,
<function role="capi">mysql_row_seek()</function>,
<function role="capi">mysql_row_tell()</function>,
<function role="capi">mysql_num_rows()</function>, or
@@ -8029,12 +8055,13 @@
issue other queries until
<function role="capi">mysql_use_result()</function> has
finished. (However, after you have fetched all the rows,
- <function role="capi">mysql_num_rows()</function> accurately returns the
- number of rows fetched.)
+ <function role="capi">mysql_num_rows()</function> accurately
+ returns the number of rows fetched.)
</para>
<para>
- You must call <function role="capi">mysql_free_result()</function> once you
+ You must call
+ <function role="capi">mysql_free_result()</function> once you
are done with the result set.
</para>
@@ -8255,8 +8282,9 @@
<listitem>
<para>
To prepare a statement, pass the statement string to
- <function role="capi">mysql_stmt_init()</function>, which returns a pointer
- to a <literal>MYSQL_STMT</literal> data structure.
+ <function role="capi">mysql_stmt_init()</function>, which
+ returns a pointer to a <literal>MYSQL_STMT</literal> data
+ structure.
</para>
</listitem>
@@ -8264,9 +8292,10 @@
<para>
To provide input parameters for a prepared statement, set up
<literal>MYSQL_BIND</literal> structures and pass them to
- <function role="capi">mysql_stmt_bind_param()</function>. To receive output
- column values, set up <literal>MYSQL_BIND</literal> structures
- and pass them to <function role="capi">mysql_stmt_bind_result()</function>.
+ <function role="capi">mysql_stmt_bind_param()</function>. To
+ receive output column values, set up
+ <literal>MYSQL_BIND</literal> structures and pass them to
+ <function role="capi">mysql_stmt_bind_result()</function>.
</para>
</listitem>
@@ -8297,12 +8326,13 @@
<para>
This structure represents a prepared statement. A statement is
- created by calling <function role="capi">mysql_stmt_init()</function>, which
+ created by calling
+ <function role="capi">mysql_stmt_init()</function>, which
returns a statement handle (that is, a pointer to a
<literal>MYSQL_STMT</literal>). The handle is used for all
subsequent operations with the statement until you close it
- with <function role="capi">mysql_stmt_close()</function>, at which point the
- handle becomes invalid.
+ with <function role="capi">mysql_stmt_close()</function>, at
+ which point the handle becomes invalid.
</para>
<para>
@@ -8340,8 +8370,8 @@
<listitem>
<para>
For input, <literal>MYSQL_BIND</literal> is used with
- <function role="capi">mysql_stmt_bind_param()</function> to bind
- parameter data values to buffers for use by
+ <function role="capi">mysql_stmt_bind_param()</function>
+ to bind parameter data values to buffers for use by
<function role="capi">mysql_stmt_execute()</function>.
</para>
</listitem>
@@ -8349,8 +8379,8 @@
<listitem>
<para>
For output, <literal>MYSQL_BIND</literal> is used with
- <function role="capi">mysql_stmt_bind_result()</function> to bind result
- set buffers for use in fetching rows with
+ <function role="capi">mysql_stmt_bind_result()</function>
+ to bind result set buffers for use in fetching rows with
<function role="capi">mysql_stmt_fetch()</function>.
</para>
</listitem>
@@ -8411,16 +8441,17 @@
For input, <literal>buffer</literal> is a pointer to the
variable in which a statement parameter's data value is
stored. When you call
- <function role="capi">mysql_stmt_execute()</function>, MySQL takes the
- value that you have stored in the variable and uses it in
- place of the corresponding parameter marker in the
- statement.
+ <function role="capi">mysql_stmt_execute()</function>,
+ MySQL takes the value that you have stored in the variable
+ and uses it in place of the corresponding parameter marker
+ in the statement.
</para>
<para>
For output, <literal>buffer</literal> is a pointer to the
variable in which to return a result set column value.
- When you call <function role="capi">mysql_stmt_fetch()</function>, MySQL
+ When you call
+ <function role="capi">mysql_stmt_fetch()</function>, MySQL
returns a column value and stores it in this variable. You
can access the value when the call returns.
</para>
@@ -8459,9 +8490,10 @@
stored in the buffer. For character and binary C data, the
<literal>buffer_length</literal> value specifies the
length of <literal>*buffer</literal> when used with
- <function role="capi">mysql_stmt_bind_param()</function> to specify
- input values, or the maximum number of output data bytes
- that can be fetched into the buffer when used with
+ <function role="capi">mysql_stmt_bind_param()</function>
+ to specify input values, or the maximum number of output
+ data bytes that can be fetched into the buffer when used
+ with
<function role="capi">mysql_stmt_bind_result()</function>.
</para>
</listitem>
@@ -8489,24 +8521,24 @@
<para>
For output value binding, the return value of
- <function role="capi">mysql_stmt_fetch()</function> determines the
- interpretation of the length:
+ <function role="capi">mysql_stmt_fetch()</function>
+ determines the interpretation of the length:
</para>
<itemizedlist>
<listitem>
<para>
- If <function role="capi">mysql_stmt_fetch()</function> returns 0,
- <literal>*length</literal> indicates the actual length
- of the parameter value.
+ If <function role="capi">mysql_stmt_fetch()</function>
+ returns 0, <literal>*length</literal> indicates the
+ actual length of the parameter value.
</para>
</listitem>
<listitem>
<para>
- If <function role="capi">mysql_stmt_fetch()</function> returns
- <literal>MYSQL_DATA_TRUNCATED</literal>,
+ If <function role="capi">mysql_stmt_fetch()</function>
+ 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
@@ -9012,11 +9044,12 @@
<literal>'12.345'</literal>. If you specify
<literal>MYSQL_TYPE_NEWDECIMAL</literal> and bind a string
buffer to the <literal>MYSQL_BIND</literal> structure,
- <function role="capi">mysql_stmt_fetch()</function> stores the value in the
- buffer without conversion. If instead you specify a numeric
- variable and type code, <function role="capi">mysql_stmt_fetch()</function>
- converts the string-format <literal>DECIMAL</literal> value to
- numeric form.
+ <function role="capi">mysql_stmt_fetch()</function> stores the
+ value in the buffer without conversion. If instead you specify
+ a numeric variable and type code,
+ <function role="capi">mysql_stmt_fetch()</function> converts
+ the string-format <literal>DECIMAL</literal> value to numeric
+ form.
</para>
</listitem>
@@ -9052,26 +9085,27 @@
check the type codes for each column of the result set. This might
be desirable if you want to determine which variable types would
be best to use to avoid type conversions. To get the type codes,
- call <function role="capi">mysql_stmt_result_metadata()</function> after
- executing the prepared statement with
- <function role="capi">mysql_stmt_execute()</function>. The metadata provides
- access to the type codes for the result set as described in
- <xref linkend="mysql-stmt-result-metadata"/>, and
+ call <function role="capi">mysql_stmt_result_metadata()</function>
+ after executing the prepared statement with
+ <function role="capi">mysql_stmt_execute()</function>. The
+ metadata provides access to the type codes for the result set as
+ described in <xref linkend="mysql-stmt-result-metadata"/>, and
<xref linkend="c-api-datatypes"/>.
</para>
<para>
If you cause the <literal>max_length</literal> member of the
<literal>MYSQL_FIELD</literal> column metadata structures to be
- set (by calling <function role="capi">mysql_stmt_attr_set()</function>), be
- aware that the <literal>max_length</literal> values for the result
- set indicate the lengths of the longest string representation of
- the result values, not the lengths of the binary representation.
- That is, <literal>max_length</literal> does not necessarily
- correspond to the size of the buffers needed to fetch the values
- with the binary protocol used for prepared statements. The size of
- the buffers should be chosen according to the types of the
- variables into which you fetch the values.
+ set (by calling
+ <function role="capi">mysql_stmt_attr_set()</function>), be aware
+ that the <literal>max_length</literal> values for the result set
+ indicate the lengths of the longest string representation of the
+ result values, not the lengths of the binary representation. That
+ is, <literal>max_length</literal> does not necessarily correspond
+ to the size of the buffers needed to fetch the values with the
+ binary protocol used for prepared statements. The size of the
+ buffers should be chosen according to the types of the variables
+ into which you fetch the values.
</para>
<para>
@@ -9237,7 +9271,8 @@
<row>
<entry><function role="capi">mysql_stmt_row_seek()</function></entry>
<entry>Seeks to a row offset in a statement result set, using value returned
- from <function role="capi">mysql_stmt_row_tell()</function></entry>
+ from
+ <function role="capi">mysql_stmt_row_tell()</function></entry>
</row>
<row>
<entry><function role="capi">mysql_stmt_row_tell()</function></entry>
@@ -9260,49 +9295,55 @@
</informaltable>
<para>
- Call <function role="capi">mysql_stmt_init()</function> to create a statement
- handle, then <function role="capi">mysql_stmt_prepare()</function> to prepare it,
- <function role="capi">mysql_stmt_bind_param()</function> to supply the parameter
- data, and <function role="capi">mysql_stmt_execute()</function> to execute the
- statement. You can repeat the
- <function role="capi">mysql_stmt_execute()</function> by changing parameter
- values in the respective buffers supplied through
+ Call <function role="capi">mysql_stmt_init()</function> to create
+ a statement handle, then
+ <function role="capi">mysql_stmt_prepare()</function> to prepare
+ it, <function role="capi">mysql_stmt_bind_param()</function> to
+ supply the parameter data, and
+ <function role="capi">mysql_stmt_execute()</function> to execute
+ the statement. You can repeat the
+ <function role="capi">mysql_stmt_execute()</function> by changing
+ parameter values in the respective buffers supplied through
<function role="capi">mysql_stmt_bind_param()</function>.
</para>
<para>
If the statement is a <literal>SELECT</literal> or any other
statement that produces a result set,
- <function role="capi">mysql_stmt_prepare()</function> also returns the result
- set metadata information in the form of a
+ <function role="capi">mysql_stmt_prepare()</function> also returns
+ the result set metadata information in the form of a
<literal>MYSQL_RES</literal> result set through
<function role="capi">mysql_stmt_result_metadata()</function>.
</para>
<para>
You can supply the result buffers using
- <function role="capi">mysql_stmt_bind_result()</function>, so that the
- <function role="capi">mysql_stmt_fetch()</function> automatically returns data
- to these buffers. This is row-by-row fetching.
+ <function role="capi">mysql_stmt_bind_result()</function>, so that
+ the <function role="capi">mysql_stmt_fetch()</function>
+ automatically returns data to these buffers. This is row-by-row
+ fetching.
</para>
<para>
You can also send the text or binary data in chunks to server
- using <function role="capi">mysql_stmt_send_long_data()</function>. See
+ using
+ <function role="capi">mysql_stmt_send_long_data()</function>. See
<xref linkend="mysql-stmt-send-long-data"/>.
</para>
<para>
When statement execution has been completed, the statement handle
- must be closed using <function role="capi">mysql_stmt_close()</function> so that
- all resources associated with it can be freed.
+ must be closed using
+ <function role="capi">mysql_stmt_close()</function> so that all
+ resources associated with it can be freed.
</para>
<para>
If you obtained a <literal>SELECT</literal> statement's result set
metadata by calling
- <function role="capi">mysql_stmt_result_metadata()</function>, you should also
- free the metadata using <function role="capi">mysql_free_result()</function>.
+ <function role="capi">mysql_stmt_result_metadata()</function>, you
+ should also free the metadata using
+ <function role="capi">mysql_free_result()</function>.
</para>
<para>
@@ -9319,37 +9360,38 @@
<listitem>
<para>
Create a prepared statement handle with
- <function role="capi">mysql_stmt_init()</function>. To prepare the statement
- on the server, call <function role="capi">mysql_stmt_prepare()</function>
- and pass it a string containing the SQL statement.
+ <function role="capi">mysql_stmt_init()</function>. To prepare
+ the statement on the server, call
+ <function role="capi">mysql_stmt_prepare()</function> and pass
+ it a string containing the SQL statement.
</para>
</listitem>
<listitem>
<para>
If the statement produces a result set, call
- <function role="capi">mysql_stmt_result_metadata()</function> to obtain the
- result set metadata. This metadata is itself in the form of
- result set, albeit a separate one from the one that contains
- the rows returned by the query. The metadata result set
- indicates how many columns are in the result and contains
- information about each column.
+ <function role="capi">mysql_stmt_result_metadata()</function>
+ to obtain the result set metadata. This metadata is itself in
+ the form of result set, albeit a separate one from the one
+ that contains the rows returned by the query. The metadata
+ result set indicates how many columns are in the result and
+ contains information about each column.
</para>
</listitem>
<listitem>
<para>
Set the values of any parameters using
- <function role="capi">mysql_stmt_bind_param()</function>. All parameters
- must be set. Otherwise, statement execution returns an error
- or produces unexpected results.
+ <function role="capi">mysql_stmt_bind_param()</function>. All
+ parameters must be set. Otherwise, statement execution returns
+ an error or produces unexpected results.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_execute()</function> to execute the
- statement.
+ Call <function role="capi">mysql_stmt_execute()</function> to
+ execute the statement.
</para>
</listitem>
@@ -9364,8 +9406,8 @@
<listitem>
<para>
Fetch the data into the buffers row by row by calling
- <function role="capi">mysql_stmt_fetch()</function> repeatedly until no more
- rows are found.
+ <function role="capi">mysql_stmt_fetch()</function> repeatedly
+ until no more rows are found.
</para>
</listitem>
@@ -9379,8 +9421,8 @@
</orderedlist>
<para>
- When <function role="capi">mysql_stmt_prepare()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_prepare()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9406,8 +9448,8 @@
</itemizedlist>
<para>
- When <function role="capi">mysql_stmt_execute()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_execute()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9433,8 +9475,8 @@
</itemizedlist>
<para>
- When <function role="capi">mysql_stmt_fetch()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_fetch()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9467,8 +9509,8 @@
<para>
For prepared statements that are executed with the
<function role="capi">mysql_stmt_prepare()</function> and
- <function role="capi">mysql_stmt_execute()</function> C API functions, the
- server writes <literal>Prepare</literal> and
+ <function role="capi">mysql_stmt_execute()</function> C API
+ functions, the server writes <literal>Prepare</literal> and
<literal>Execute</literal> lines to the general query log so that
you can tell when statements are prepared and executed.
</para>
@@ -9481,23 +9523,23 @@
<listitem>
<para>
- Call <function role="capi">mysql_stmt_prepare()</function> to prepare the
- statement string <literal>"SELECT ?"</literal>.
+ Call <function role="capi">mysql_stmt_prepare()</function> to
+ prepare the statement string <literal>"SELECT ?"</literal>.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_bind_param()</function> to bind the
- value <literal>3</literal> to the parameter in the prepared
- statement.
+ Call <function role="capi">mysql_stmt_bind_param()</function>
+ to bind the value <literal>3</literal> to the parameter in the
+ prepared statement.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_execute()</function> to execute the
- prepared statement.
+ Call <function role="capi">mysql_stmt_execute()</function> to
+ execute the prepared statement.
</para>
</listitem>
@@ -9611,9 +9653,9 @@
<para>
Also in 4.1.2, the signature of the
- <function role="capi">mysql_stmt_prepare()</function> function was changed to
- <literal>int mysql_stmt_prepare(MYSQL_STMT *stmt, const char
- *query, unsigned long length)</literal>. To create a
+ <function role="capi">mysql_stmt_prepare()</function> function was
+ changed to <literal>int mysql_stmt_prepare(MYSQL_STMT *stmt, const
+ char *query, unsigned long length)</literal>. To create a
<literal>MYSQL_STMT</literal> handle, you should use the
<function role="capi">mysql_stmt_init()</function> function.
</para>
@@ -9642,8 +9684,8 @@
<literal>UPDATE</literal>, <literal>DELETE</literal>, or
<literal>INSERT</literal> statements. For
<literal>SELECT</literal> statements,
- <function role="capi">mysql_stmt_affected_rows()</function> works like
- <function role="capi">mysql_num_rows()</function>.
+ <function role="capi">mysql_stmt_affected_rows()</function>
+ works like <function role="capi">mysql_num_rows()</function>.
</para>
<para>
@@ -9661,11 +9703,14 @@
matched the <literal>WHERE</literal> clause in the query, or
that no query has yet been executed. -1 indicates that the query
returned an error or that, for a <literal>SELECT</literal>
- query, <function role="capi">mysql_stmt_affected_rows()</function> was called
- prior to calling <function role="capi">mysql_stmt_store_result()</function>.
- Because <function role="capi">mysql_stmt_affected_rows()</function> returns an
- unsigned value, you can check for -1 by comparing the return
- value to <literal>(my_ulonglong)-1</literal> (or to
+ query,
+ <function role="capi">mysql_stmt_affected_rows()</function> was
+ called prior to calling
+ <function role="capi">mysql_stmt_store_result()</function>.
+ Because
+ <function role="capi">mysql_stmt_affected_rows()</function>
+ returns an unsigned value, you can check for -1 by comparing the
+ return value to <literal>(my_ulonglong)-1</literal> (or to
<literal>(my_ulonglong)~0</literal>, which is equivalent).
</para>
@@ -9687,7 +9732,8 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_affected_rows()</function>,
+ For the usage of
+ <function role="capi">mysql_stmt_affected_rows()</function>,
refer to the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
@@ -9786,8 +9832,8 @@
<literal>my_bool *</literal>. If <literal>arg</literal> points
to the value <literal>1</literal>, then the metadata
<literal>MYSQL_FIELD->max_length</literal> in
- <function role="capi">mysql_stmt_store_result()</function> is updated when the
- prepared statement is executed.
+ <function role="capi">mysql_stmt_store_result()</function> is
+ updated when the prepared statement is executed.
</para>
<note>
@@ -9843,9 +9889,10 @@
</para>
<para>
- <function role="capi">mysql_stmt_bind_param()</function> is used to bind input
- data for the parameter markers in the SQL statement that was
- passed to <function role="capi">mysql_stmt_prepare()</function>. It uses
+ <function role="capi">mysql_stmt_bind_param()</function> is used
+ to bind input data for the parameter markers in the SQL
+ statement that was passed to
+ <function role="capi">mysql_stmt_prepare()</function>. It uses
<literal>MYSQL_BIND</literal> structures to supply the data.
<literal>bind</literal> is the address of an array of
<literal>MYSQL_BIND</literal> structures. The client library
@@ -9936,8 +9983,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_bind_param()</function>,
- refer to the Example from <xref linkend="mysql-stmt-execute"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_bind_param()</function>, refer
+ to the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
</section>
@@ -9960,44 +10008,47 @@
</para>
<para>
- <function role="capi">mysql_stmt_bind_result()</function> is used to associate
- (that is, bind) output columns in the result set to data buffers
- and length buffers. When <function role="capi">mysql_stmt_fetch()</function>
- is called to fetch data, the MySQL client/server protocol places
- the data for the bound columns into the specified buffers.
+ <function role="capi">mysql_stmt_bind_result()</function> is
+ used to associate (that is, bind) output columns in the result
+ set to data buffers and length buffers. When
+ <function role="capi">mysql_stmt_fetch()</function> is called to
+ fetch data, the MySQL client/server protocol places the data for
+ the bound columns into the specified buffers.
</para>
<para>
All columns must be bound to buffers prior to calling
- <function role="capi">mysql_stmt_fetch()</function>. <literal>bind</literal>
- is the address of an array of <literal>MYSQL_BIND</literal>
- structures. The client library expects the array to contain one
- element for each column of the result set. If you do not bind
- columns to <literal>MYSQL_BIND</literal> structures,
- <function role="capi">mysql_stmt_fetch()</function> simply ignores the data
- fetch. The buffers should be large enough to hold the data
- values, because the protocol doesn't return data values in
- chunks.
+ <function role="capi">mysql_stmt_fetch()</function>.
+ <literal>bind</literal> is the address of an array of
+ <literal>MYSQL_BIND</literal> structures. The client library
+ expects the array to contain one element for each column of the
+ result set. If you do not bind columns to
+ <literal>MYSQL_BIND</literal> structures,
+ <function role="capi">mysql_stmt_fetch()</function> simply
+ ignores the data fetch. The buffers should be large enough to
+ hold the data values, because the protocol doesn't return data
+ values in chunks.
</para>
<para>
A column can be bound or rebound at any time, even after a
result set has been partially retrieved. The new binding takes
- effect the next time <function role="capi">mysql_stmt_fetch()</function> is
- called. Suppose that an application binds the columns in a
- result set and calls <function role="capi">mysql_stmt_fetch()</function>. The
- client/server protocol returns data in the bound buffers. Then
- suppose that the application binds the columns to a different
- set of buffers. The protocol places data into the newly bound
- buffers when the next call to
+ effect the next time
+ <function role="capi">mysql_stmt_fetch()</function> is called.
+ Suppose that an application binds the columns in a result set
+ and calls <function role="capi">mysql_stmt_fetch()</function>.
+ The client/server protocol returns data in the bound buffers.
+ Then suppose that the application binds the columns to a
+ different set of buffers. The protocol places data into the
+ newly bound buffers when the next call to
<function role="capi">mysql_stmt_fetch()</function> occurs.
</para>
<para>
To bind a column, an application calls
- <function role="capi">mysql_stmt_bind_result()</function> and passes the type,
- address, and length of the output buffer into which the value
- should be stored.
+ <function role="capi">mysql_stmt_bind_result()</function> and
+ passes the type, 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.
@@ -10061,8 +10112,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_bind_result()</function>,
- refer to the Example from <xref linkend="mysql-stmt-fetch"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_bind_result()</function>, refer
+ to the Example from <xref linkend="mysql-stmt-fetch"/>.
</para>
</section>
@@ -10085,8 +10137,9 @@
<para>
Closes the prepared statement.
- <function role="capi">mysql_stmt_close()</function> also deallocates the
- statement handle pointed to by <literal>stmt</literal>.
+ <function role="capi">mysql_stmt_close()</function> also
+ deallocates the statement handle pointed to by
+ <literal>stmt</literal>.
</para>
<para>
@@ -10140,7 +10193,8 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_close()</function>, refer to
+ For the usage of
+ <function role="capi">mysql_stmt_close()</function>, refer to
the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
@@ -10173,8 +10227,9 @@
<para>
This function requires that the statement result set structure
contains the entire result of the last executed query, so
- <function role="capi">mysql_stmt_data_seek()</function> may be used only in
- conjunction with <function role="capi">mysql_stmt_store_result()</function>.
+ <function role="capi">mysql_stmt_data_seek()</function> may be
+ used only in conjunction with
+ <function role="capi">mysql_stmt_store_result()</function>.
</para>
<para>
@@ -10335,32 +10390,35 @@
</para>
<para>
- <function role="capi">mysql_stmt_execute()</function> executes the prepared
- query associated with the statement handle. The currently bound
- parameter marker values are sent to server during this call, and
- the server replaces the markers with this newly supplied data.
+ <function role="capi">mysql_stmt_execute()</function> executes
+ the prepared query associated with the statement handle. The
+ currently bound parameter marker values are sent to server
+ during this call, and the server replaces the markers with this
+ newly supplied data.
</para>
<para>
If the statement is an <literal>UPDATE</literal>,
<literal>DELETE</literal>, or <literal>INSERT</literal>, the
total number of changed, deleted, or inserted rows can be found
- by calling <function role="capi">mysql_stmt_affected_rows()</function>. If
+ by calling
+ <function role="capi">mysql_stmt_affected_rows()</function>. If
this is a statement such as <literal>SELECT</literal> that
generates a result set, you must call
- <function role="capi">mysql_stmt_fetch()</function> to fetch the data prior to
- calling any other functions that result in query processing. For
- more information on how to fetch the results, refer to
- <xref linkend="mysql-stmt-fetch"/>.
+ <function role="capi">mysql_stmt_fetch()</function> to fetch the
+ data prior to calling any other functions that result in query
+ processing. For more information on how to fetch the results,
+ refer to <xref linkend="mysql-stmt-fetch"/>.
</para>
<para>
For statements that generate a result set, you can request that
- <function role="capi">mysql_stmt_execute()</function> open a cursor for the
- statement by calling <function role="capi">mysql_stmt_attr_set()</function>
- before executing the statement. If you execute a statement
- multiple times, <function role="capi">mysql_stmt_execute()</function> closes
- any open cursor before opening a new one.
+ <function role="capi">mysql_stmt_execute()</function> open a
+ cursor for the statement by calling
+ <function role="capi">mysql_stmt_attr_set()</function> before
+ executing the statement. If you execute a statement multiple
+ times, <function role="capi">mysql_stmt_execute()</function>
+ closes any open cursor before opening a new one.
</para>
<remark role="note">
@@ -10657,16 +10715,18 @@
</para>
<para>
- <function role="capi">mysql_stmt_fetch()</function> returns the next row in
- the result set. It can be called only while the result set
- exists; that is, after a call to
- <function role="capi">mysql_stmt_execute()</function> for a statement such as
- <literal>SELECT</literal> that creates a result set.
+ <function role="capi">mysql_stmt_fetch()</function> returns the
+ next row in the result set. It can be called only while the
+ result set exists; that is, after a call to
+ <function role="capi">mysql_stmt_execute()</function> for a
+ statement such as <literal>SELECT</literal> that creates a
+ result set.
</para>
<para>
- <function role="capi">mysql_stmt_fetch()</function> returns row data using the
- buffers bound by <function role="capi">mysql_stmt_bind_result()</function>. It
+ <function role="capi">mysql_stmt_fetch()</function> returns row
+ data using the buffers bound by
+ <function role="capi">mysql_stmt_bind_result()</function>. It
returns the data in those buffers for all the columns in the
current row set and the lengths are returned to the
<literal>length</literal> pointer. All columns must be bound by
@@ -10677,8 +10737,8 @@
<para>
By default, result sets are fetched unbuffered a row at a time
from the server. To buffer the entire result set on the client,
- call <function role="capi">mysql_stmt_store_result()</function> after binding
- the data buffers and before caling
+ call <function role="capi">mysql_stmt_store_result()</function>
+ after binding the data buffers and before caling
<function role="capi">mysql_stmt_fetch()</function>.
</para>
@@ -10887,11 +10947,12 @@
<para>
The following example demonstrates how to fetch data from a
- table using <function role="capi">mysql_stmt_result_metadata()</function>,
+ table using
+ <function role="capi">mysql_stmt_result_metadata()</function>,
<function role="capi">mysql_stmt_bind_result()</function>, and
- <function role="capi">mysql_stmt_fetch()</function>. (This example expects to
- retrieve the two rows inserted by the example shown in
- <xref linkend="mysql-stmt-execute"/>.) The
+ <function role="capi">mysql_stmt_fetch()</function>. (This
+ example expects to retrieve the two rows inserted by the example
+ shown in <xref linkend="mysql-stmt-execute"/>.) The
<literal>mysql</literal> variable is assumed to be a valid
connection handle.
</para>
@@ -11079,37 +11140,41 @@
<para>
In some cases you might want to determine the length of a column
value before fetching it with
- <function role="capi">mysql_stmt_fetch()</function>. For example, the value
- might be a long string or <literal>BLOB</literal> value for
- which you want to know how much space must be allocated. To
- accomplish this, you can use these strategies:
+ <function role="capi">mysql_stmt_fetch()</function>. For
+ example, the value might be a long string or
+ <literal>BLOB</literal> value for which you want to know how
+ much space must be allocated. To accomplish this, you can use
+ these strategies:
</para>
<itemizedlist>
<listitem>
<para>
- Before invoking <function role="capi">mysql_stmt_fetch()</function> to
+ Before invoking
+ <function role="capi">mysql_stmt_fetch()</function> to
retrieve individual rows, invoke
- <function role="capi">mysql_stmt_store_result()</function> to buffer the
- entire result on the client side. Then the maximal length of
- column values will be indicated by the
+ <function role="capi">mysql_stmt_store_result()</function>
+ to buffer the entire result on the client side. Then the
+ maximal length of column values will be indicated by the
<literal>max_length</literal> member of the result set
metadata returned by
- <function role="capi">mysql_stmt_result_metadata()</function>. This
- strategy requires that you pass
+ <function role="capi">mysql_stmt_result_metadata()</function>.
+ This strategy requires that you pass
<literal>STMT_ATTR_UPDATE_MAX_LENGTH</literal> to
- <function role="capi">mysql_stmt_attr_set()</function> or the
- <literal>max_length</literal> values will not be calculated.
+ <function role="capi">mysql_stmt_attr_set()</function> or
+ the <literal>max_length</literal> values will not be
+ calculated.
</para>
</listitem>
<listitem>
<para>
- Invoke <function role="capi">mysql_stmt_fetch()</function> with a
- zero-length buffer for the column in question and a pointer
- in which the real length can be stored. Then use the real
- length with <function role="capi">mysql_stmt_fetch_column()</function>.
+ Invoke <function role="capi">mysql_stmt_fetch()</function>
+ with a zero-length buffer for the column in question and a
+ pointer in which the real length can be stored. Then use the
+ real length with
+ <function role="capi">mysql_stmt_fetch_column()</function>.
</para>
<programlisting>
@@ -11233,8 +11298,8 @@
</para>
<para>
- <function role="capi">mysql_stmt_field_count()</function> can be called after
- you have prepared a statement by invoking
+ <function role="capi">mysql_stmt_field_count()</function> can be
+ called after you have prepared a statement by invoking
<function role="capi">mysql_stmt_prepare()</function>.
</para>
@@ -11281,8 +11346,9 @@
<para>
Releases memory associated with the result set produced by
execution of the prepared statement. If there is a cursor open
- for the statement, <function role="capi">mysql_stmt_free_result()</function>
- closes it.
+ for the statement,
+ <function role="capi">mysql_stmt_free_result()</function> closes
+ it.
</para>
<para>
@@ -11322,7 +11388,8 @@
<para>
Create a <literal>MYSQL_STMT</literal> handle. The handle should
- be freed with <function role="capi">mysql_stmt_close(MYSQL_STMT *)</function>.
+ be freed with <function role="capi">mysql_stmt_close(MYSQL_STMT
+ *)</function>.
</para>
<para>
@@ -11444,25 +11511,29 @@
</para>
<para>
- The use of <function role="capi">mysql_stmt_num_rows()</function> depends on
- whether you used <function role="capi">mysql_stmt_store_result()</function> to
+ The use of
+ <function role="capi">mysql_stmt_num_rows()</function> depends
+ on whether you used
+ <function role="capi">mysql_stmt_store_result()</function> to
buffer the entire result set in the statement handle.
</para>
<para>
- If you use <function role="capi">mysql_stmt_store_result()</function>,
- <function role="capi">mysql_stmt_num_rows()</function> may be called
- immediately. Otherwise, the row count is unavailable unless you
- count the rows as you fetch them.
+ If you use
+ <function role="capi">mysql_stmt_store_result()</function>,
+ <function role="capi">mysql_stmt_num_rows()</function> may be
+ called immediately. Otherwise, the row count is unavailable
+ unless you count the rows as you fetch them.
</para>
<para>
- <function role="capi">mysql_stmt_num_rows()</function> is intended for use
- with statements that return a result set, such as
- <literal>SELECT</literal>. For statements such as
+ <function role="capi">mysql_stmt_num_rows()</function> is
+ intended for use with statements that return a result set, such
+ as <literal>SELECT</literal>. For statements such as
<literal>INSERT</literal>, <literal>UPDATE</literal>, or
<literal>DELETE</literal>, the number of affected rows can be
- obtained with <function role="capi">mysql_stmt_affected_rows()</function>.
+ obtained with
+ <function role="capi">mysql_stmt_affected_rows()</function>.
</para>
<para>
@@ -11535,8 +11606,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_param_count()</function>,
- refer to the Example from <xref linkend="mysql-stmt-execute"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_param_count()</function>, refer
+ to the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
</section>
@@ -11595,11 +11667,12 @@
<para>
Given the statement handle returned by
- <function role="capi">mysql_stmt_init()</function>, prepares the SQL statement
- pointed to by the string <literal>stmt_str</literal> and returns
- a status value. The string length should be given by the
- <literal>length</literal> argument. The string must consist of a
- single SQL statement. You should not add a terminating semicolon
+ <function role="capi">mysql_stmt_init()</function>, prepares the
+ SQL statement pointed to by the string
+ <literal>stmt_str</literal> and returns a status value. The
+ string length should be given by the <literal>length</literal>
+ argument. The string must consist of a single SQL statement. You
+ should not add a terminating semicolon
(<quote><literal>;</literal></quote>) or <literal>\g</literal>
to the statement.
</para>
@@ -11628,8 +11701,8 @@
<para>
The parameter markers must be bound to application variables
- using <function role="capi">mysql_stmt_bind_param()</function> before
- executing the statement.
+ using <function role="capi">mysql_stmt_bind_param()</function>
+ before executing the statement.
</para>
<para>
@@ -11705,8 +11778,8 @@
<para>
If the prepare operation was unsuccessful (that is,
- <function role="capi">mysql_stmt_prepare()</function> returns non-zero), the
- error message can be obtained by calling
+ <function role="capi">mysql_stmt_prepare()</function> returns
+ non-zero), the error message can be obtained by calling
<function role="capi">mysql_stmt_error()</function>.
</para>
@@ -11715,8 +11788,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_prepare()</function>, refer
- to the Example from <xref linkend="mysql-stmt-execute"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_prepare()</function>, refer to
+ the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
</section>
@@ -11740,8 +11814,8 @@
<para>
Reset the prepared statement on the client and server to state
after prepare. This is mainly used to reset data sent with
- <function role="capi">mysql_stmt_send_long_data()</function>. Any open cursor
- for the statement is closed.
+ <function role="capi">mysql_stmt_send_long_data()</function>.
+ Any open cursor for the statement is closed.
</para>
<para>
@@ -11830,10 +11904,11 @@
</para>
<para>
- If a statement passed to <function role="capi">mysql_stmt_prepare()</function>
- is one that produces a result set,
- <function role="capi">mysql_stmt_result_metadata()</function> returns the
- result set metadata in the form of a pointer to a
+ If a statement passed to
+ <function role="capi">mysql_stmt_prepare()</function> is one
+ that produces a result set,
+ <function role="capi">mysql_stmt_result_metadata()</function>
+ returns the result set metadata in the form of a pointer to a
<literal>MYSQL_RES</literal> structure that can be used to
process the meta information such as total number of fields and
individual field information. This result set pointer can be
@@ -11896,16 +11971,16 @@
<para>
The result set structure should be freed when you are done with
it, which you can do by passing it to
- <function role="capi">mysql_free_result()</function>. This is similar to the
- way you free a result set obtained from a call to
+ <function role="capi">mysql_free_result()</function>. This is
+ similar to the way you free a result set obtained from a call to
<function role="capi">mysql_store_result()</function>.
</para>
<para>
The result set returned by
- <function role="capi">mysql_stmt_result_metadata()</function> contains only
- metadata. It does not contain any row results. The rows are
- obtained by using the statement handle with
+ <function role="capi">mysql_stmt_result_metadata()</function>
+ contains only metadata. It does not contain any row results. The
+ rows are obtained by using the statement handle with
<function role="capi">mysql_stmt_fetch()</function>.
</para>
@@ -11957,8 +12032,8 @@
<para>
For the usage of
- <function role="capi">mysql_stmt_result_metadata()</function>, refer to the
- Example from <xref linkend="mysql-stmt-fetch"/>.
+ <function role="capi">mysql_stmt_result_metadata()</function>,
+ refer to the Example from <xref linkend="mysql-stmt-fetch"/>.
</para>
</section>
@@ -11985,16 +12060,18 @@
set. The <literal>offset</literal> value is a row offset that
should be a value returned from
<function role="capi">mysql_stmt_row_tell()</function> or from
- <function role="capi">mysql_stmt_row_seek()</function>. This value is not a
- row number; if you want to seek to a row within a result set by
- number, use <function role="capi">mysql_stmt_data_seek()</function> instead.
+ <function role="capi">mysql_stmt_row_seek()</function>. This
+ value is not a row number; if you want to seek to a row within a
+ result set by number, use
+ <function role="capi">mysql_stmt_data_seek()</function> instead.
</para>
<para>
This function requires that the result set structure contains
the entire result of the query, so
- <function role="capi">mysql_stmt_row_seek()</function> may be used only in
- conjunction with <function role="capi">mysql_stmt_store_result()</function>.
+ <function role="capi">mysql_stmt_row_seek()</function> may be
+ used only in conjunction with
+ <function role="capi">mysql_stmt_store_result()</function>.
</para>
<para>
@@ -12040,13 +12117,16 @@
<para>
Returns the current position of the row cursor for the last
- <function role="capi">mysql_stmt_fetch()</function>. This value can be used as
- an argument to <function role="capi">mysql_stmt_row_seek()</function>.
+ <function role="capi">mysql_stmt_fetch()</function>. This value
+ can be used as an argument to
+ <function role="capi">mysql_stmt_row_seek()</function>.
</para>
<para>
- You should use <function role="capi">mysql_stmt_row_tell()</function> only
- after <function role="capi">mysql_stmt_store_result()</function>.
+ You should use
+ <function role="capi">mysql_stmt_row_tell()</function> only
+ after
+ <function role="capi">mysql_stmt_store_result()</function>.
</para>
<para>
@@ -12092,10 +12172,10 @@
<para>
Allows an application to send parameter data to the server in
pieces (or <quote>chunks</quote>). Call this function after
- <function role="capi">mysql_stmt_bind_param()</function> and before
- <function role="capi">mysql_stmt_execute()</function>. It can be called
- multiple times to send the parts of a character or binary data
- value for a column, which must be one of the
+ <function role="capi">mysql_stmt_bind_param()</function> and
+ before <function role="capi">mysql_stmt_execute()</function>. It
+ can be called multiple times to send the parts of a character or
+ binary data value for a column, which must be one of the
<literal>TEXT</literal> or <literal>BLOB</literal> data types.
</para>
@@ -12109,9 +12189,11 @@
<note>
<para>
- The next <function role="capi">mysql_stmt_execute()</function> call ignores
- the bind buffer for all parameters that have been used with
- <function role="capi">mysql_stmt_send_long_data()</function> since last
+ The next <function role="capi">mysql_stmt_execute()</function>
+ call ignores the bind buffer for all parameters that have been
+ used with
+ <function role="capi">mysql_stmt_send_long_data()</function>
+ since last
<function role="capi">mysql_stmt_execute()</function> or
<function role="capi">mysql_stmt_reset()</function>.
</para>
@@ -12328,31 +12410,35 @@
<literal>SHOW</literal>, <literal>DESCRIBE</literal>, and
<literal>EXPLAIN</literal>. By default, result sets for
successfully executed prepared statements are not buffered on
- the client and <function role="capi">mysql_stmt_fetch()</function> fetches
- them one at a time from the server. To cause the complete result
- set to be buffered on the client, call
- <function role="capi">mysql_stmt_store_result()</function> after binding data
- buffers with <function role="capi">mysql_stmt_bind_result()</function> and
- before calling <function role="capi">mysql_stmt_fetch()</function> to fetch
+ the client and
+ <function role="capi">mysql_stmt_fetch()</function> fetches them
+ one at a time from the server. To cause the complete result set
+ to be buffered on the client, call
+ <function role="capi">mysql_stmt_store_result()</function> after
+ binding data buffers with
+ <function role="capi">mysql_stmt_bind_result()</function> and
+ before calling
+ <function role="capi">mysql_stmt_fetch()</function> to fetch
rows. (For an example, see <xref linkend="mysql-stmt-fetch"/>.)
</para>
<para>
- <function role="capi">mysql_stmt_store_result()</function> is optional for
- result set processing, unless you will call
+ <function role="capi">mysql_stmt_store_result()</function> is
+ optional for result set processing, unless you will call
<function role="capi">mysql_stmt_data_seek()</function>,
<function role="capi">mysql_stmt_row_seek()</function>, or
- <function role="capi">mysql_stmt_row_tell()</function>. Those functions
- require a seekable result set.
+ <function role="capi">mysql_stmt_row_tell()</function>. Those
+ functions require a seekable result set.
</para>
<para>
It is unnecessary to call
- <function role="capi">mysql_stmt_store_result()</function> after executing a
- SQL statement that does not produce a result set, but if you do,
- it does not harm or cause any notable performance problem. You
- can detect whether the statement produced a result set by
- checking if <function role="capi">mysql_stmt_result_metadata()</function>
+ <function role="capi">mysql_stmt_store_result()</function> after
+ executing a SQL statement that does not produce a result set,
+ but if you do, it does not harm or cause any notable performance
+ problem. You can detect whether the statement produced a result
+ set by checking if
+ <function role="capi">mysql_stmt_result_metadata()</function>
returns <literal>NULL</literal>. For more information, refer to
<xref linkend="mysql-stmt-result-metadata"/>.
</para>
@@ -12361,12 +12447,13 @@
<para>
MySQL doesn't by default calculate
<literal>MYSQL_FIELD->max_length</literal> for all columns
- in <function role="capi">mysql_stmt_store_result()</function> because
- calculating this would slow down
- <function role="capi">mysql_stmt_store_result()</function> considerably and
- most applications doesn't need <literal>max_length</literal>.
- If you want <literal>max_length</literal> to be updated, you
- can call <function role="capi">mysql_stmt_attr_set(MYSQL_STMT,
+ in <function role="capi">mysql_stmt_store_result()</function>
+ because calculating this would slow down
+ <function role="capi">mysql_stmt_store_result()</function>
+ considerably and most applications doesn't need
+ <literal>max_length</literal>. If you want
+ <literal>max_length</literal> to be updated, you can call
+ <function role="capi">mysql_stmt_attr_set(MYSQL_STMT,
STMT_ATTR_UPDATE_MAX_LENGTH, &flag)</function> to enable
this. See <xref linkend="mysql-stmt-attr-set"/>.
</para>
@@ -12541,11 +12628,11 @@
check whether more results exist and process them in turn if so.
To support multiple-result processing, the C API includes the
<function role="capi">mysql_more_results()</function> and
- <function role="capi">mysql_next_result()</function> functions. Generally, these
- functions are used at the end of a loop that iterates as long as
- more results are available. <emphasis>Failure to process the
- result this way may result in a dropped connection to the
- server.</emphasis>
+ <function role="capi">mysql_next_result()</function> functions.
+ Generally, these functions are used at the end of a loop that
+ iterates as long as more results are available. <emphasis>Failure
+ to process the result this way may result in a dropped connection
+ to the server.</emphasis>
</para>
<para>
@@ -12606,7 +12693,8 @@
<listitem>
<para>
After the connection to the server has been established, you
- can use the <function role="capi">mysql_set_server_option()</function>
+ can use the
+ <function role="capi">mysql_set_server_option()</function>
function to enable or disable multiple-statement execution by
passing it an argument of
<literal>MYSQL_OPTION_MULTI_STATEMENTS_ON</literal> or
@@ -12652,9 +12740,9 @@
<listitem>
<para>
At the end of the loop, call
- <function role="capi">mysql_next_result()</function> to check whether
- another result exists and initiate retrieval for it if so. If
- no more results are available, exit the loop.
+ <function role="capi">mysql_next_result()</function> to check
+ whether another result exists and initiate retrieval for it if
+ so. If no more results are available, exit the loop.
</para>
</listitem>
@@ -12723,10 +12811,10 @@
<para>
The final part of the loop can be reduced to a simple test of
- whether <function role="capi">mysql_next_result()</function> returns non-zero.
- The code as written distinguishes between no more results and an
- error, which allows a message to be printed for the latter
- occurrence.
+ whether <function role="capi">mysql_next_result()</function>
+ returns non-zero. The code as written distinguishes between no
+ more results and an error, which allows a message to be printed
+ for the latter occurrence.
</para>
</section>
@@ -12747,9 +12835,11 @@
<para>
To send temporal data values, create a prepared statement using
- <function role="capi">mysql_stmt_prepare()</function>. Then, before calling
- <function role="capi">mysql_stmt_execute()</function> to execute the statement,
- use the following procedure to set up each temporal parameter:
+ <function role="capi">mysql_stmt_prepare()</function>. Then,
+ before calling
+ <function role="capi">mysql_stmt_execute()</function> to execute
+ the statement, use the following procedure to set up each temporal
+ parameter:
</para>
<orderedlist>
@@ -12789,8 +12879,8 @@
</orderedlist>
<para>
- Use <function role="capi">mysql_stmt_bind_param()</function> to bind the
- parameter data to the statement. Then you can call
+ Use <function role="capi">mysql_stmt_bind_param()</function> to
+ bind the parameter data to the statement. Then you can call
<function role="capi">mysql_stmt_execute()</function>.
</para>
@@ -12800,9 +12890,10 @@
value you expect to receive, and the <literal>buffer</literal>
member to the address of a <literal>MYSQL_TIME</literal> structure
into which the returned value should be placed. Use
- <function role="capi">mysql_stmt_bind_result()</function> to bind the buffers to the
- statement after calling <function role="capi">mysql_stmt_execute()</function>
- and before fetching the results.
+ <function role="capi">mysql_stmt_bind_result()</function> to bind
+ the buffers to the statement after calling
+ <function role="capi">mysql_stmt_execute()</function> and before
+ fetching the results.
</para>
<para>
@@ -13378,15 +13469,16 @@
<listitem>
<para>
- <function role="capi">mysql_num_rows()</function> returns the number of
- rows in a result set. With
+ <function role="capi">mysql_num_rows()</function> returns
+ the number of rows in a result set. With
<function role="capi">mysql_store_result()</function>,
- <function role="capi">mysql_num_rows()</function> may be called as soon as
+ <function role="capi">mysql_num_rows()</function> may be
+ called as soon as
<function role="capi">mysql_store_result()</function>
returns. With
<function role="capi">mysql_use_result()</function>,
- <function role="capi">mysql_num_rows()</function> may be called only after
- you have fetched all the rows with
+ <function role="capi">mysql_num_rows()</function> may be
+ called only after you have fetched all the rows with
<function role="capi">mysql_fetch_row()</function>.
</para>
</listitem>
@@ -13819,11 +13911,12 @@
<listitem>
<para>
- If you use <function role="capi">mysql_use_result()</function>,
- you must ensure that no other thread is using the same
- connection until the result set is closed. However, it really
- is best for threaded clients that share the same connection to
- use <function role="capi">mysql_store_result()</function>.
+ If you use
+ <function role="capi">mysql_use_result()</function>, you must
+ ensure that no other thread is using the same connection until
+ the result set is closed. However, it really is best for
+ threaded clients that share the same connection to use
+ <function role="capi">mysql_store_result()</function>.
</para>
</listitem>
@@ -13850,8 +13943,8 @@
<listitem>
<para>
- <function role="capi">mysql_ping()</function> does not attempt a
- reconnection if the connection is down. It returns an error
+ <function role="capi">mysql_ping()</function> does not attempt
+ a reconnection if the connection is down. It returns an error
instead.
</para>
</listitem>
Modified: trunk/refman-4.1/dba-core.xml
===================================================================
--- trunk/refman-4.1/dba-core.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-4.1/dba-core.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 4, Lines Added: 12, Lines Deleted: 7; 2435 bytes
@@ -12566,7 +12566,8 @@
<listitem>
<para>
MySQL C API: Use the
- <function role="capi">mysql_real_escape_string()</function> API call.
+ <function role="capi">mysql_real_escape_string()</function>
+ API call.
</para>
</listitem>
@@ -13258,7 +13259,8 @@
<command>configure</command> with the
<option>--enable-local-infile</option> option, <literal>LOAD
DATA LOCAL</literal> cannot be used by any client unless it
- is written explicitly to invoke <function role="capi">mysql_options(...
+ is written explicitly to invoke
+ <function role="capi">mysql_options(...
MYSQL_OPT_LOCAL_INFILE, 0)</function>. See
<xref linkend="mysql-options"/>.
</para>
@@ -18856,7 +18858,8 @@
<para>
To establish a secure connection from within an application
- program, use the <function role="capi">mysql_ssl_set()</function> C API
+ program, use the
+ <function role="capi">mysql_ssl_set()</function> C API
function to set the appropriate certificate options before
calling <function role="capi">mysql_real_connect()</function>.
See <xref linkend="mysql-ssl-set"/>.
@@ -22040,10 +22043,12 @@
</para>
<para>
- You should use <function role="capi">mysql_real_escape_string()</function>
- when escaping strings for an SQL query.
- <function role="capi">mysql_real_escape_string()</function> is identical to
- the old <function role="capi">mysql_escape_string()</function> function,
+ You should use
+ <function role="capi">mysql_real_escape_string()</function> when
+ escaping strings for an SQL query.
+ <function role="capi">mysql_real_escape_string()</function> is
+ identical to the old
+ <function role="capi">mysql_escape_string()</function> function,
except that it takes the <literal>MYSQL</literal> connection
handle as the first parameter so that the appropriate character
set can be taken into account when escaping characters.
Modified: trunk/refman-4.1/errors-problems.xml
===================================================================
--- trunk/refman-4.1/errors-problems.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-4.1/errors-problems.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 4, Lines Added: 16, Lines Deleted: 13; 2889 bytes
@@ -1041,9 +1041,9 @@
If not, correct the query and try again. Otherwise, you can
invoke <command>mysql</command> with the
<option>--quick</option> option. This causes it to use the
- <function role="capi">mysql_use_result()</function> C API function to
- retrieve the result set, which places less of a load on the
- client (but more on the server).
+ <function role="capi">mysql_use_result()</function> C API
+ function to retrieve the result set, which places less of a
+ load on the client (but more on the server).
</para>
</section>
@@ -1188,9 +1188,9 @@
<para>
The solution to this is to either do a
- <function role="capi">mysql_ping()</function> on the connection if there
- has been a long time since the last query (this is what
- <literal>MyODBC</literal> does) or set
+ <function role="capi">mysql_ping()</function> on the
+ connection if there has been a long time since the last
+ query (this is what <literal>MyODBC</literal> does) or set
<literal>wait_timeout</literal> on the
<command>mysqld</command> server so high that it in
practice never times out.
@@ -1512,7 +1512,8 @@
<listitem>
<para>
The client program did not call
- <function role="capi">mysql_close()</function> before exiting.
+ <function role="capi">mysql_close()</function> before
+ exiting.
</para>
</listitem>
@@ -2051,12 +2052,14 @@
<para>
This can happen, for example, if you are using
- <function role="capi">mysql_use_result()</function> and try to execute a new
- query before you have called
- <function role="capi">mysql_free_result()</function>. It can also happen if
- you try to execute two queries that return data without
- calling <function role="capi">mysql_use_result()</function> or
- <function role="capi">mysql_store_result()</function> in between.
+ <function role="capi">mysql_use_result()</function> and try to
+ execute a new query before you have called
+ <function role="capi">mysql_free_result()</function>. It can
+ also happen if you try to execute two queries that return data
+ without calling
+ <function role="capi">mysql_use_result()</function> or
+ <function role="capi">mysql_store_result()</function> in
+ between.
</para>
</section>
Modified: trunk/refman-4.1/news-3.23.xml
===================================================================
--- trunk/refman-4.1/news-3.23.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-4.1/news-3.23.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 4, Lines Deleted: 5; 1038 bytes
@@ -4502,11 +4502,10 @@
<command>safe_mysqld</command>,
<command>mysql.server</command>, and
<command>mysql_install_db</command> have been modified to use
- <literal>my_print_defaults</literal> instead of various
- hacks to read the <filename>my.cnf</filename> files. In
- addition, the handling of various paths has been made more
- consistent with how <command>mysqld</command> handles them by
- default.
+ <literal>my_print_defaults</literal> instead of various hacks
+ to read the <filename>my.cnf</filename> files. In addition,
+ the handling of various paths has been made more consistent
+ with how <command>mysqld</command> handles them by default.
</para>
</listitem>
Modified: trunk/refman-4.1/news-4.0.xml
===================================================================
--- trunk/refman-4.1/news-4.0.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-4.1/news-4.0.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 5, Lines Deleted: 4; 881 bytes
@@ -619,10 +619,11 @@
<listitem>
<para>
- Added the <function role="capi">mysql_get_client_version()</function> C API
- function to the embedded server library. (It was present in
- the regular client library but inadvertently omitted from the
- embedded library.) (Bug #10266)
+ Added the
+ <function role="capi">mysql_get_client_version()</function> C
+ API function to the embedded server library. (It was present
+ in the regular client library but inadvertently omitted from
+ the embedded library.) (Bug #10266)
</para>
</listitem>
Modified: trunk/refman-4.1/sql-syntax.xml
===================================================================
--- trunk/refman-4.1/sql-syntax.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-4.1/sql-syntax.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 4, Lines Deleted: 3; 861 bytes
@@ -20546,9 +20546,10 @@
<para>
SQL syntax for prepared statements is distinct from using prepared
statement API calls. For example, you cannot use the
- <function role="capi">mysql_stmt_prepare()</function> C API function to prepare
- a <literal>PREPARE</literal>, <literal>EXECUTE</literal>, or
- <literal>DEALLOCATE PREPARE</literal> statement.
+ <function role="capi">mysql_stmt_prepare()</function> C API
+ function to prepare a <literal>PREPARE</literal>,
+ <literal>EXECUTE</literal>, or <literal>DEALLOCATE
+ PREPARE</literal> statement.
</para>
<para>
Modified: trunk/refman-5.0/apis-c.xml
===================================================================
--- trunk/refman-5.0/apis-c.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.0/apis-c.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 106, Lines Added: 521, Lines Deleted: 427; 87242 bytes
@@ -1343,8 +1343,8 @@
<para>
After you are done with a result set, call
- <function role="capi">mysql_free_result()</function> to free the memory used for
- it.
+ <function role="capi">mysql_free_result()</function> to free the
+ memory used for it.
</para>
<para>
@@ -1360,12 +1360,13 @@
<function role="capi">mysql_store_result()</function> is that
because the rows have all been fetched to the client, you not only
can access rows sequentially, you can move back and forth in the
- result set using <function role="capi">mysql_data_seek()</function> or
+ result set using
+ <function role="capi">mysql_data_seek()</function> or
<function role="capi">mysql_row_seek()</function> to change the
current row position within the result set. You can also find out
how many rows there are by calling
- <function role="capi">mysql_num_rows()</function>. On the other hand, the memory
- requirements for
+ <function role="capi">mysql_num_rows()</function>. On the other
+ hand, the memory requirements for
<function role="capi">mysql_store_result()</function> may be very
high for large result sets and you are more likely to encounter
out-of-memory conditions.
@@ -2146,8 +2147,8 @@
<para>
This function requires that the result set structure contains
the entire result of the query, so
- <function role="capi">mysql_data_seek()</function> may be used only in
- conjunction with
+ <function role="capi">mysql_data_seek()</function> may be used
+ only in conjunction with
<function role="capi">mysql_store_result()</function>, not with
<function role="capi">mysql_use_result()</function>.
</para>
@@ -2188,9 +2189,9 @@
<para>
Does a <literal>DBUG_PUSH</literal> with the given string.
- <function role="capi">mysql_debug()</function> uses the Fred Fish debug
- library. To use this function, you must compile the client
- library to support debugging. See
+ <function role="capi">mysql_debug()</function> uses the Fred
+ Fish debug library. To use this function, you must compile the
+ client library to support debugging. See
<ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
Internals: Porting</ulink>.
</para>
@@ -2703,19 +2704,21 @@
</indexterm>
<para>
- You should use <function role="capi">mysql_real_escape_string()</function>
+ You should use
+ <function role="capi">mysql_real_escape_string()</function>
instead!
</para>
<para>
This function is identical to
- <function role="capi">mysql_real_escape_string()</function> except that
- <function role="capi">mysql_real_escape_string()</function> takes a connection
- handler as its first argument and escapes the string according
- to the current character set.
- <function role="capi">mysql_escape_string()</function> does not take a
- connection argument and does not respect the current character
- set.
+ <function role="capi">mysql_real_escape_string()</function>
+ except that
+ <function role="capi">mysql_real_escape_string()</function>
+ takes a connection handler as its first argument and escapes the
+ string according to the current character set.
+ <function role="capi">mysql_escape_string()</function> does not
+ take a connection argument and does not respect the current
+ character set.
</para>
</section>
@@ -2823,7 +2826,8 @@
<literal>MYSQL_FIELD</literal> structure. You may use this
function to retrieve the definition for an arbitrary column. The
value of <literal>fieldnr</literal> should be in the range from
- 0 to <function role="capi">mysql_num_fields(result)-1</function>.
+ 0 to
+ <function role="capi">mysql_num_fields(result)-1</function>.
</para>
<para>
@@ -3337,9 +3341,10 @@
Frees the memory allocated for a result set by
<function role="capi">mysql_store_result()</function>,
<function role="capi">mysql_use_result()</function>,
- <function role="capi">mysql_list_dbs()</function>, and so forth. When you are
- done with a result set, you must free the memory it uses by
- calling <function role="capi">mysql_free_result()</function>.
+ <function role="capi">mysql_list_dbs()</function>, and so forth.
+ When you are done with a result set, you must free the memory it
+ uses by calling
+ <function role="capi">mysql_free_result()</function>.
</para>
<para>
@@ -3384,7 +3389,8 @@
<para>
This function provides information about the default client
character set. The default character set may be changed with the
- <function role="capi">mysql_set_character_set()</function> function.
+ <function role="capi">mysql_set_character_set()</function>
+ function.
</para>
<para>
@@ -3691,8 +3697,8 @@
</para>
<para>
- <function role="capi">mysql_get_ssl_cipher()</function> returns the SSL cipher
- used for the given connection to the server.
+ <function role="capi">mysql_get_ssl_cipher()</function> returns
+ the SSL cipher used for the given connection to the server.
<literal>mysql</literal> is the connection handler returned from
<function role="capi">mysql_init()</function>.
</para>
@@ -3746,10 +3752,10 @@
<literal>length</literal> bytes long. You must allocate the
<literal>to</literal> buffer to be at least
<literal>length*2+1</literal> bytes long. When
- <function role="capi">mysql_hex_string()</function> returns, the contents of
- <literal>to</literal> is a null-terminated string. The return
- value is the length of the encoded string, not including the
- terminating null character.
+ <function role="capi">mysql_hex_string()</function> returns, the
+ contents of <literal>to</literal> is a null-terminated string.
+ The return value is the length of the encoded string, not
+ including the terminating null character.
</para>
<para>
@@ -4406,8 +4412,8 @@
<quote><literal>%</literal></quote> or
<quote><literal>_</literal></quote>, or may be a
<literal>NULL</literal> pointer to match all databases. Calling
- <function role="capi">mysql_list_dbs()</function> is similar to executing the
- query <literal>SHOW databases [LIKE
+ <function role="capi">mysql_list_dbs()</function> is similar to
+ executing the query <literal>SHOW databases [LIKE
<replaceable>wild</replaceable>]</literal>.
</para>
@@ -4510,8 +4516,8 @@
<quote><literal>%</literal></quote> or
<quote><literal>_</literal></quote>, or may be a
<literal>NULL</literal> pointer to match all fields. Calling
- <function role="capi">mysql_list_fields()</function> is similar to executing
- the query <literal>SHOW COLUMNS FROM
+ <function role="capi">mysql_list_fields()</function> is similar
+ to executing the query <literal>SHOW COLUMNS FROM
<replaceable>tbl_name</replaceable> [LIKE
<replaceable>wild</replaceable>]</literal>.
</para>
@@ -4698,8 +4704,8 @@
<quote><literal>%</literal></quote> or
<quote><literal>_</literal></quote>, or may be a
<literal>NULL</literal> pointer to match all tables. Calling
- <function role="capi">mysql_list_tables()</function> is similar to executing
- the query <literal>SHOW tables [LIKE
+ <function role="capi">mysql_list_tables()</function> is similar
+ to executing the query <literal>SHOW tables [LIKE
<replaceable>wild</replaceable>]</literal>.
</para>
@@ -4791,10 +4797,11 @@
</para>
<para>
- <function role="capi">mysql_more_results()</function> true if more results
- exist from the currently executed statement, in which case the
- application must call <function role="capi">mysql_next_result()</function> to
- fetch the results.
+ <function role="capi">mysql_more_results()</function> true if
+ more results exist from the currently executed statement, in
+ which case the application must call
+ <function role="capi">mysql_next_result()</function> to fetch
+ the results.
</para>
<para>
@@ -4808,8 +4815,8 @@
<para>
In most cases, you can call
- <function role="capi">mysql_next_result()</function> instead to test whether
- more results exist and initiate retrieval if so.
+ <function role="capi">mysql_next_result()</function> instead to
+ test whether more results exist and initiate retrieval if so.
</para>
<para>
@@ -4852,18 +4859,22 @@
<para>
If more statement results exist,
- <function role="capi">mysql_next_result()</function> reads the next statement
- result and returns the status back to the application.
+ <function role="capi">mysql_next_result()</function> reads the
+ next statement result and returns the status back to the
+ application.
</para>
<para>
- Before calling <function role="capi">mysql_next_result()</function>, you must
- call <function role="capi">mysql_free_result()</function> for the preceding
- statement if it is a query that returned a result set.
+ Before calling
+ <function role="capi">mysql_next_result()</function>, you must
+ call <function role="capi">mysql_free_result()</function> for
+ the preceding statement if it is a query that returned a result
+ set.
</para>
<para>
- After calling <function role="capi">mysql_next_result()</function> the state
+ After calling
+ <function role="capi">mysql_next_result()</function> the state
of the connection is as if you had called
<function role="capi">mysql_real_query()</function> or
<function role="capi">mysql_query()</function> for the next
@@ -4875,9 +4886,9 @@
</para>
<para>
- If <function role="capi">mysql_next_result()</function> returns an error, no
- other statements are executed and there are no more results to
- fetch.
+ If <function role="capi">mysql_next_result()</function> returns
+ an error, no other statements are executed and there are no more
+ results to fetch.
</para>
<para>
@@ -4893,8 +4904,8 @@
might be returned by statements executed within the procedure.
In addition, because <literal>CALL</literal> can return multiple
results, you should process those results using a loop that
- calls <function role="capi">mysql_next_result()</function> to determine
- whether there are more results.
+ calls <function role="capi">mysql_next_result()</function> to
+ determine whether there are more results.
</para>
<para>
@@ -5124,21 +5135,23 @@
</para>
<para>
- The use of <function role="capi">mysql_num_rows()</function> depends on
- whether you use
+ The use of <function role="capi">mysql_num_rows()</function>
+ depends on whether you use
<function role="capi">mysql_store_result()</function> or
<function role="capi">mysql_use_result()</function> to return
the result set. If you use
<function role="capi">mysql_store_result()</function>,
- <function role="capi">mysql_num_rows()</function> may be called immediately.
- If you use <function role="capi">mysql_use_result()</function>,
- <function role="capi">mysql_num_rows()</function> does not return the correct
- value until all the rows in the result set have been retrieved.
+ <function role="capi">mysql_num_rows()</function> may be called
+ immediately. If you use
+ <function role="capi">mysql_use_result()</function>,
+ <function role="capi">mysql_num_rows()</function> does not
+ return the correct value until all the rows in the result set
+ have been retrieved.
</para>
<para>
- <function role="capi">mysql_num_rows()</function> is intended for use with
- statements that return a result set, such as
+ <function role="capi">mysql_num_rows()</function> is intended
+ for use with statements that return a result set, such as
<literal>SELECT</literal>. For statements such as
<literal>INSERT</literal>, <literal>UPDATE</literal>, or
<literal>DELETE</literal>, the number of affected rows can be
@@ -6017,7 +6030,8 @@
parameters use whatever character set has been configured
for the <literal>MYSQL</literal> object. By default, this is
<literal>latin1</literal>, but can be changed by calling
- <function role="capi">mysql_options(mysql, MYSQL_SET_CHARSET_NAME,
+ <function role="capi">mysql_options(mysql,
+ MYSQL_SET_CHARSET_NAME,
"<replaceable>charset_name</replaceable>")</function> prior
to connecting.
</para>
@@ -6127,7 +6141,8 @@
<entry>Use SSL (encrypted protocol). This option should not be set by
application programs; it is set internally in the
client library. Instead, use
- <function role="capi">mysql_ssl_set()</function> before calling
+ <function role="capi">mysql_ssl_set()</function>
+ before calling
<function role="capi">mysql_real_connect()</function>.</entry>
</row>
</tbody>
@@ -6156,7 +6171,8 @@
result for every call to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -6462,21 +6478,23 @@
<literal>length*2+1</literal> bytes long. (In the worst case,
each character may need to be encoded as using two bytes, and
you need room for the terminating null byte.) When
- <function role="capi">mysql_real_escape_string()</function> returns, the
- contents of <literal>to</literal> is a null-terminated string.
- The return value is the length of the encoded string, not
- including the terminating null character.
+ <function role="capi">mysql_real_escape_string()</function>
+ returns, the contents of <literal>to</literal> is a
+ null-terminated string. The return value is the length of the
+ encoded string, not including the terminating null character.
</para>
<para>
If you need to change the character set of the connection, you
- should use the <function role="capi">mysql_set_character_set()</function>
+ should use the
+ <function role="capi">mysql_set_character_set()</function>
function rather than executing a <literal>SET NAMES</literal>
(or <literal>SET CHARACTER SET</literal>) statement.
- <function role="capi">mysql_set_character_set()</function> works like
- <literal>SET NAMES</literal> but also affects the character set
- used by <function role="capi">mysql_real_escape_string()</function>, which
- <literal>SET NAMES</literal> does not.
+ <function role="capi">mysql_set_character_set()</function> works
+ like <literal>SET NAMES</literal> but also affects the character
+ set used by
+ <function role="capi">mysql_real_escape_string()</function>,
+ which <literal>SET NAMES</literal> does not.
</para>
<para>
@@ -6978,7 +6996,8 @@
<function role="capi">mysql_row_tell()</function> or from
<function role="capi">mysql_row_seek()</function>. This value is
not a row number; if you want to seek to a row within a result
- set by number, use <function role="capi">mysql_data_seek()</function> instead.
+ set by number, use
+ <function role="capi">mysql_data_seek()</function> instead.
</para>
<para>
@@ -7085,9 +7104,9 @@
</para>
<para>
- <function role="capi">mysql_select_db()</function> fails unless the connected
- user can be authenticated as having permission to use the
- database.
+ <function role="capi">mysql_select_db()</function> fails unless
+ the connected user can be authenticated as having permission to
+ use the database.
</para>
<para>
@@ -7236,14 +7255,15 @@
Sets the <literal>LOAD LOCAL DATA INFILE</literal> handler
callback functions to the defaults used internally by the C
client library. The library calls this function automatically if
- <function role="capi">mysql_set_local_infile_handler()</function> has not been
- called or does not supply valid functions for each of its
- callbacks.
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ has not been called or does not supply valid functions for each
+ of its callbacks.
</para>
<para>
- The <function role="capi">mysql_set_local_infile_default()</function> function
- was added in MySQL 4.1.2.
+ The
+ <function role="capi">mysql_set_local_infile_default()</function>
+ function was added in MySQL 4.1.2.
</para>
<para>
@@ -7291,8 +7311,9 @@
</para>
<para>
- To use <function role="capi">mysql_set_local_infile_handler()</function>, you
- must write the following callback functions:
+ To use
+ <function role="capi">mysql_set_local_infile_handler()</function>,
+ you must write the following callback functions:
</para>
<programlisting>
@@ -7383,10 +7404,10 @@
<para>
After calling
- <function role="capi">mysql_set_local_infile_handler()</function> in your C
- code and passing pointers to your callback functions, you can
- then issue a <literal>LOAD DATA LOCAL INFILE</literal> statement
- (for example, by using
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ in your C code and passing pointers to your callback functions,
+ you can then issue a <literal>LOAD DATA LOCAL INFILE</literal>
+ statement (for example, by using
<function role="capi">mysql_query()</function>). The client
library automatically invokes your callbacks. The filename
specified in <literal>LOAD DATA LOCAL INFILE</literal> will be
@@ -7395,8 +7416,9 @@
</para>
<para>
- The <function role="capi">mysql_set_local_infile_handler()</function> function
- was added in MySQL 4.1.2.
+ The
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ function was added in MySQL 4.1.2.
</para>
<para>
@@ -7461,7 +7483,8 @@
results from calls to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -7531,9 +7554,9 @@
<para>
The server didn't support
- <function role="capi">mysql_set_server_option()</function> (which is the
- case that the server is older than 4.1.1) or the server
- didn't support the option one tried to set.
+ <function role="capi">mysql_set_server_option()</function>
+ (which is the case that the server is older than 4.1.1) or
+ the server didn't support the option one tried to set.
</para>
</listitem>
@@ -7568,8 +7591,9 @@
are planned to make it possible to choose the desired level.
Dynamically linked executables which have been compiled with
older versions of the <literal>libmysqlclient</literal> headers
- and call <function role="capi">mysql_shutdown()</function> need to be used
- with the old <literal>libmysqlclient</literal> dynamic library.
+ and call <function role="capi">mysql_shutdown()</function> need
+ to be used with the old <literal>libmysqlclient</literal>
+ dynamic library.
</para>
<para>
@@ -7732,14 +7756,14 @@
</para>
<para>
- <function role="capi">mysql_ssl_set()</function> is used for establishing
- secure connections using SSL. It must be called before
- <function role="capi">mysql_real_connect()</function>.
+ <function role="capi">mysql_ssl_set()</function> is used for
+ establishing secure connections using SSL. It must be called
+ before <function role="capi">mysql_real_connect()</function>.
</para>
<para>
- <function role="capi">mysql_ssl_set()</function> does nothing unless OpenSSL
- support is enabled in the client library.
+ <function role="capi">mysql_ssl_set()</function> does nothing
+ unless OpenSSL support is enabled in the client library.
</para>
<para>
@@ -7911,8 +7935,8 @@
(<literal>SELECT</literal>, <literal>SHOW</literal>,
<literal>DESCRIBE</literal>, <literal>EXPLAIN</literal>,
<literal>CHECK TABLE</literal>, and so forth). You must also
- call <function role="capi">mysql_free_result()</function> after you are done
- with the result set.
+ call <function role="capi">mysql_free_result()</function> after
+ you are done with the result set.
</para>
<para>
@@ -7933,7 +7957,8 @@
results from calls to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -7979,8 +8004,8 @@
After you have called
<function role="capi">mysql_store_result()</function> and gotten
back a result that isn't a null pointer, you can call
- <function role="capi">mysql_num_rows()</function> to find out how many rows
- are in the result set.
+ <function role="capi">mysql_num_rows()</function> to find out
+ how many rows are in the result set.
</para>
<para>
@@ -8088,15 +8113,16 @@
<para>
Returns the thread ID of the current connection. This value can
- be used as an argument to <function role="capi">mysql_kill()</function> to
- kill the thread.
+ be used as an argument to
+ <function role="capi">mysql_kill()</function> to kill the
+ thread.
</para>
<para>
If the connection is lost and you reconnect with
- <function role="capi">mysql_ping()</function>, the thread ID changes. This
- means you should not get the thread ID and store it for later.
- You should get it when you need it.
+ <function role="capi">mysql_ping()</function>, the thread ID
+ changes. This means you should not get the thread ID and store
+ it for later. You should get it when you need it.
</para>
<para>
@@ -8180,7 +8206,8 @@
</para>
<para>
- You may not use <function role="capi">mysql_data_seek()</function>,
+ You may not use
+ <function role="capi">mysql_data_seek()</function>,
<function role="capi">mysql_row_seek()</function>,
<function role="capi">mysql_row_tell()</function>,
<function role="capi">mysql_num_rows()</function>, or
@@ -8190,12 +8217,13 @@
issue other queries until
<function role="capi">mysql_use_result()</function> has
finished. (However, after you have fetched all the rows,
- <function role="capi">mysql_num_rows()</function> accurately returns the
- number of rows fetched.)
+ <function role="capi">mysql_num_rows()</function> accurately
+ returns the number of rows fetched.)
</para>
<para>
- You must call <function role="capi">mysql_free_result()</function> once you
+ You must call
+ <function role="capi">mysql_free_result()</function> once you
are done with the result set.
</para>
@@ -8331,11 +8359,11 @@
The MySQL client/server protocol provides for the use of prepared
statements. This capability uses the <literal>MYSQL_STMT</literal>
statement handler data structure returned by the
- <function role="capi">mysql_stmt_init()</function> initialization function.
- Prepared execution is an efficient way to execute a statement more
- than once. The statement is first parsed to prepare it for
- execution. Then it is executed one or more times at a later time,
- using the statement handle returned by the initialization
+ <function role="capi">mysql_stmt_init()</function> initialization
+ function. Prepared execution is an efficient way to execute a
+ statement more than once. The statement is first parsed to prepare
+ it for execution. Then it is executed one or more times at a later
+ time, using the statement handle returned by the initialization
function.
</para>
@@ -8404,8 +8432,9 @@
<listitem>
<para>
To prepare a statement, pass the statement string to
- <function role="capi">mysql_stmt_init()</function>, which returns a pointer
- to a <literal>MYSQL_STMT</literal> data structure.
+ <function role="capi">mysql_stmt_init()</function>, which
+ returns a pointer to a <literal>MYSQL_STMT</literal> data
+ structure.
</para>
</listitem>
@@ -8413,9 +8442,10 @@
<para>
To provide input parameters for a prepared statement, set up
<literal>MYSQL_BIND</literal> structures and pass them to
- <function role="capi">mysql_stmt_bind_param()</function>. To receive output
- column values, set up <literal>MYSQL_BIND</literal> structures
- and pass them to <function role="capi">mysql_stmt_bind_result()</function>.
+ <function role="capi">mysql_stmt_bind_param()</function>. To
+ receive output column values, set up
+ <literal>MYSQL_BIND</literal> structures and pass them to
+ <function role="capi">mysql_stmt_bind_result()</function>.
</para>
</listitem>
@@ -8446,12 +8476,13 @@
<para>
This structure represents a prepared statement. A statement is
- created by calling <function role="capi">mysql_stmt_init()</function>, which
+ created by calling
+ <function role="capi">mysql_stmt_init()</function>, which
returns a statement handle (that is, a pointer to a
<literal>MYSQL_STMT</literal>). The handle is used for all
subsequent operations with the statement until you close it
- with <function role="capi">mysql_stmt_close()</function>, at which point the
- handle becomes invalid.
+ with <function role="capi">mysql_stmt_close()</function>, at
+ which point the handle becomes invalid.
</para>
<para>
@@ -8489,8 +8520,8 @@
<listitem>
<para>
For input, <literal>MYSQL_BIND</literal> is used with
- <function role="capi">mysql_stmt_bind_param()</function> to bind
- parameter data values to buffers for use by
+ <function role="capi">mysql_stmt_bind_param()</function>
+ to bind parameter data values to buffers for use by
<function role="capi">mysql_stmt_execute()</function>.
</para>
</listitem>
@@ -8498,8 +8529,8 @@
<listitem>
<para>
For output, <literal>MYSQL_BIND</literal> is used with
- <function role="capi">mysql_stmt_bind_result()</function> to bind result
- set buffers for use in fetching rows with
+ <function role="capi">mysql_stmt_bind_result()</function>
+ to bind result set buffers for use in fetching rows with
<function role="capi">mysql_stmt_fetch()</function>.
</para>
</listitem>
@@ -8560,16 +8591,17 @@
For input, <literal>buffer</literal> is a pointer to the
variable in which a statement parameter's data value is
stored. When you call
- <function role="capi">mysql_stmt_execute()</function>, MySQL takes the
- value that you have stored in the variable and uses it in
- place of the corresponding parameter marker in the
- statement.
+ <function role="capi">mysql_stmt_execute()</function>,
+ MySQL takes the value that you have stored in the variable
+ and uses it in place of the corresponding parameter marker
+ in the statement.
</para>
<para>
For output, <literal>buffer</literal> is a pointer to the
variable in which to return a result set column value.
- When you call <function role="capi">mysql_stmt_fetch()</function>, MySQL
+ When you call
+ <function role="capi">mysql_stmt_fetch()</function>, MySQL
returns a column value and stores it in this variable. You
can access the value when the call returns.
</para>
@@ -8608,9 +8640,10 @@
stored in the buffer. For character and binary C data, the
<literal>buffer_length</literal> value specifies the
length of <literal>*buffer</literal> when used with
- <function role="capi">mysql_stmt_bind_param()</function> to specify
- input values, or the maximum number of output data bytes
- that can be fetched into the buffer when used with
+ <function role="capi">mysql_stmt_bind_param()</function>
+ to specify input values, or the maximum number of output
+ data bytes that can be fetched into the buffer when used
+ with
<function role="capi">mysql_stmt_bind_result()</function>.
</para>
</listitem>
@@ -8638,24 +8671,24 @@
<para>
For output value binding, the return value of
- <function role="capi">mysql_stmt_fetch()</function> determines the
- interpretation of the length:
+ <function role="capi">mysql_stmt_fetch()</function>
+ determines the interpretation of the length:
</para>
<itemizedlist>
<listitem>
<para>
- If <function role="capi">mysql_stmt_fetch()</function> returns 0,
- <literal>*length</literal> indicates the actual length
- of the parameter value.
+ If <function role="capi">mysql_stmt_fetch()</function>
+ returns 0, <literal>*length</literal> indicates the
+ actual length of the parameter value.
</para>
</listitem>
<listitem>
<para>
- If <function role="capi">mysql_stmt_fetch()</function> returns
- <literal>MYSQL_DATA_TRUNCATED</literal>,
+ If <function role="capi">mysql_stmt_fetch()</function>
+ 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
@@ -8804,8 +8837,8 @@
<function role="capi">mysql_options()</function> with the
<literal>MYSQL_REPORT_DATA_TRUNCATION</literal> option.)
When truncation reporting is enabled,
- <function role="capi">mysql_stmt_fetch()</function> returns
- <literal>MYSQL_DATA_TRUNCATED</literal> and
+ <function role="capi">mysql_stmt_fetch()</function>
+ returns <literal>MYSQL_DATA_TRUNCATED</literal> and
<literal>*error</literal> is true in the
<literal>MYSQL_BIND</literal> structures for parameters in
which truncation occurred. Truncation indicates loss of
@@ -9196,11 +9229,12 @@
<literal>'12.345'</literal>. If you specify
<literal>MYSQL_TYPE_NEWDECIMAL</literal> and bind a string
buffer to the <literal>MYSQL_BIND</literal> structure,
- <function role="capi">mysql_stmt_fetch()</function> stores the value in the
- buffer without conversion. If instead you specify a numeric
- variable and type code, <function role="capi">mysql_stmt_fetch()</function>
- converts the string-format <literal>DECIMAL</literal> value to
- numeric form.
+ <function role="capi">mysql_stmt_fetch()</function> stores the
+ value in the buffer without conversion. If instead you specify
+ a numeric variable and type code,
+ <function role="capi">mysql_stmt_fetch()</function> converts
+ the string-format <literal>DECIMAL</literal> value to numeric
+ form.
</para>
</listitem>
@@ -9236,26 +9270,27 @@
check the type codes for each column of the result set. This might
be desirable if you want to determine which variable types would
be best to use to avoid type conversions. To get the type codes,
- call <function role="capi">mysql_stmt_result_metadata()</function> after
- executing the prepared statement with
- <function role="capi">mysql_stmt_execute()</function>. The metadata provides
- access to the type codes for the result set as described in
- <xref linkend="mysql-stmt-result-metadata"/>, and
+ call <function role="capi">mysql_stmt_result_metadata()</function>
+ after executing the prepared statement with
+ <function role="capi">mysql_stmt_execute()</function>. The
+ metadata provides access to the type codes for the result set as
+ described in <xref linkend="mysql-stmt-result-metadata"/>, and
<xref linkend="c-api-datatypes"/>.
</para>
<para>
If you cause the <literal>max_length</literal> member of the
<literal>MYSQL_FIELD</literal> column metadata structures to be
- set (by calling <function role="capi">mysql_stmt_attr_set()</function>), be
- aware that the <literal>max_length</literal> values for the result
- set indicate the lengths of the longest string representation of
- the result values, not the lengths of the binary representation.
- That is, <literal>max_length</literal> does not necessarily
- correspond to the size of the buffers needed to fetch the values
- with the binary protocol used for prepared statements. The size of
- the buffers should be chosen according to the types of the
- variables into which you fetch the values.
+ set (by calling
+ <function role="capi">mysql_stmt_attr_set()</function>), be aware
+ that the <literal>max_length</literal> values for the result set
+ indicate the lengths of the longest string representation of the
+ result values, not the lengths of the binary representation. That
+ is, <literal>max_length</literal> does not necessarily correspond
+ to the size of the buffers needed to fetch the values with the
+ binary protocol used for prepared statements. The size of the
+ buffers should be chosen according to the types of the variables
+ into which you fetch the values.
</para>
<para>
@@ -9413,7 +9448,8 @@
<row>
<entry><function role="capi">mysql_stmt_row_seek()</function></entry>
<entry>Seeks to a row offset in a statement result set, using value returned
- from <function role="capi">mysql_stmt_row_tell()</function></entry>
+ from
+ <function role="capi">mysql_stmt_row_tell()</function></entry>
</row>
<row>
<entry><function role="capi">mysql_stmt_row_tell()</function></entry>
@@ -9436,49 +9472,55 @@
</informaltable>
<para>
- Call <function role="capi">mysql_stmt_init()</function> to create a statement
- handle, then <function role="capi">mysql_stmt_prepare()</function> to prepare it,
- <function role="capi">mysql_stmt_bind_param()</function> to supply the parameter
- data, and <function role="capi">mysql_stmt_execute()</function> to execute the
- statement. You can repeat the
- <function role="capi">mysql_stmt_execute()</function> by changing parameter
- values in the respective buffers supplied through
+ Call <function role="capi">mysql_stmt_init()</function> to create
+ a statement handle, then
+ <function role="capi">mysql_stmt_prepare()</function> to prepare
+ it, <function role="capi">mysql_stmt_bind_param()</function> to
+ supply the parameter data, and
+ <function role="capi">mysql_stmt_execute()</function> to execute
+ the statement. You can repeat the
+ <function role="capi">mysql_stmt_execute()</function> by changing
+ parameter values in the respective buffers supplied through
<function role="capi">mysql_stmt_bind_param()</function>.
</para>
<para>
If the statement is a <literal>SELECT</literal> or any other
statement that produces a result set,
- <function role="capi">mysql_stmt_prepare()</function> also returns the result
- set metadata information in the form of a
+ <function role="capi">mysql_stmt_prepare()</function> also returns
+ the result set metadata information in the form of a
<literal>MYSQL_RES</literal> result set through
<function role="capi">mysql_stmt_result_metadata()</function>.
</para>
<para>
You can supply the result buffers using
- <function role="capi">mysql_stmt_bind_result()</function>, so that the
- <function role="capi">mysql_stmt_fetch()</function> automatically returns data
- to these buffers. This is row-by-row fetching.
+ <function role="capi">mysql_stmt_bind_result()</function>, so that
+ the <function role="capi">mysql_stmt_fetch()</function>
+ automatically returns data to these buffers. This is row-by-row
+ fetching.
</para>
<para>
You can also send the text or binary data in chunks to server
- using <function role="capi">mysql_stmt_send_long_data()</function>. See
+ using
+ <function role="capi">mysql_stmt_send_long_data()</function>. See
<xref linkend="mysql-stmt-send-long-data"/>.
</para>
<para>
When statement execution has been completed, the statement handle
- must be closed using <function role="capi">mysql_stmt_close()</function> so that
- all resources associated with it can be freed.
+ must be closed using
+ <function role="capi">mysql_stmt_close()</function> so that all
+ resources associated with it can be freed.
</para>
<para>
If you obtained a <literal>SELECT</literal> statement's result set
metadata by calling
- <function role="capi">mysql_stmt_result_metadata()</function>, you should also
- free the metadata using <function role="capi">mysql_free_result()</function>.
+ <function role="capi">mysql_stmt_result_metadata()</function>, you
+ should also free the metadata using
+ <function role="capi">mysql_free_result()</function>.
</para>
<para>
@@ -9495,37 +9537,38 @@
<listitem>
<para>
Create a prepared statement handle with
- <function role="capi">mysql_stmt_init()</function>. To prepare the statement
- on the server, call <function role="capi">mysql_stmt_prepare()</function>
- and pass it a string containing the SQL statement.
+ <function role="capi">mysql_stmt_init()</function>. To prepare
+ the statement on the server, call
+ <function role="capi">mysql_stmt_prepare()</function> and pass
+ it a string containing the SQL statement.
</para>
</listitem>
<listitem>
<para>
If the statement produces a result set, call
- <function role="capi">mysql_stmt_result_metadata()</function> to obtain the
- result set metadata. This metadata is itself in the form of
- result set, albeit a separate one from the one that contains
- the rows returned by the query. The metadata result set
- indicates how many columns are in the result and contains
- information about each column.
+ <function role="capi">mysql_stmt_result_metadata()</function>
+ to obtain the result set metadata. This metadata is itself in
+ the form of result set, albeit a separate one from the one
+ that contains the rows returned by the query. The metadata
+ result set indicates how many columns are in the result and
+ contains information about each column.
</para>
</listitem>
<listitem>
<para>
Set the values of any parameters using
- <function role="capi">mysql_stmt_bind_param()</function>. All parameters
- must be set. Otherwise, statement execution returns an error
- or produces unexpected results.
+ <function role="capi">mysql_stmt_bind_param()</function>. All
+ parameters must be set. Otherwise, statement execution returns
+ an error or produces unexpected results.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_execute()</function> to execute the
- statement.
+ Call <function role="capi">mysql_stmt_execute()</function> to
+ execute the statement.
</para>
</listitem>
@@ -9540,8 +9583,8 @@
<listitem>
<para>
Fetch the data into the buffers row by row by calling
- <function role="capi">mysql_stmt_fetch()</function> repeatedly until no more
- rows are found.
+ <function role="capi">mysql_stmt_fetch()</function> repeatedly
+ until no more rows are found.
</para>
</listitem>
@@ -9555,8 +9598,8 @@
</orderedlist>
<para>
- When <function role="capi">mysql_stmt_prepare()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_prepare()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9582,8 +9625,8 @@
</itemizedlist>
<para>
- When <function role="capi">mysql_stmt_execute()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_execute()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9609,8 +9652,8 @@
</itemizedlist>
<para>
- When <function role="capi">mysql_stmt_fetch()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_fetch()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9643,8 +9686,8 @@
<para>
For prepared statements that are executed with the
<function role="capi">mysql_stmt_prepare()</function> and
- <function role="capi">mysql_stmt_execute()</function> C API functions, the
- server writes <literal>Prepare</literal> and
+ <function role="capi">mysql_stmt_execute()</function> C API
+ functions, the server writes <literal>Prepare</literal> and
<literal>Execute</literal> lines to the general query log so that
you can tell when statements are prepared and executed.
</para>
@@ -9657,23 +9700,23 @@
<listitem>
<para>
- Call <function role="capi">mysql_stmt_prepare()</function> to prepare the
- statement string <literal>"SELECT ?"</literal>.
+ Call <function role="capi">mysql_stmt_prepare()</function> to
+ prepare the statement string <literal>"SELECT ?"</literal>.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_bind_param()</function> to bind the
- value <literal>3</literal> to the parameter in the prepared
- statement.
+ Call <function role="capi">mysql_stmt_bind_param()</function>
+ to bind the value <literal>3</literal> to the parameter in the
+ prepared statement.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_execute()</function> to execute the
- prepared statement.
+ Call <function role="capi">mysql_stmt_execute()</function> to
+ execute the prepared statement.
</para>
</listitem>
@@ -9754,8 +9797,8 @@
<literal>UPDATE</literal>, <literal>DELETE</literal>, or
<literal>INSERT</literal> statements. For
<literal>SELECT</literal> statements,
- <function role="capi">mysql_stmt_affected_rows()</function> works like
- <function role="capi">mysql_num_rows()</function>.
+ <function role="capi">mysql_stmt_affected_rows()</function>
+ works like <function role="capi">mysql_num_rows()</function>.
</para>
<para>
@@ -9769,11 +9812,14 @@
matched the <literal>WHERE</literal> clause in the query, or
that no query has yet been executed. -1 indicates that the query
returned an error or that, for a <literal>SELECT</literal>
- query, <function role="capi">mysql_stmt_affected_rows()</function> was called
- prior to calling <function role="capi">mysql_stmt_store_result()</function>.
- Because <function role="capi">mysql_stmt_affected_rows()</function> returns an
- unsigned value, you can check for -1 by comparing the return
- value to <literal>(my_ulonglong)-1</literal> (or to
+ query,
+ <function role="capi">mysql_stmt_affected_rows()</function> was
+ called prior to calling
+ <function role="capi">mysql_stmt_store_result()</function>.
+ Because
+ <function role="capi">mysql_stmt_affected_rows()</function>
+ returns an unsigned value, you can check for -1 by comparing the
+ return value to <literal>(my_ulonglong)-1</literal> (or to
<literal>(my_ulonglong)~0</literal>, which is equivalent).
</para>
@@ -9795,7 +9841,8 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_affected_rows()</function>,
+ For the usage of
+ <function role="capi">mysql_stmt_affected_rows()</function>,
refer to the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
@@ -9921,8 +9968,8 @@
<entry><literal>STMT_ATTR_CURSOR_TYPE</literal></entry>
<entry><literal>unsigned long *</literal></entry>
<entry>Type of cursor to open for statement when
- <function role="capi">mysql_stmt_execute()</function> is invoked.
- <literal>*arg</literal> can be
+ <function role="capi">mysql_stmt_execute()</function> is
+ invoked. <literal>*arg</literal> can be
<literal>CURSOR_TYPE_NO_CURSOR</literal> (the default)
or <literal>CURSOR_TYPE_READ_ONLY</literal>.</entry>
</row>
@@ -9953,21 +10000,21 @@
If you use the <literal>STMT_ATTR_CURSOR_TYPE</literal> option
with <literal>CURSOR_TYPE_READ_ONLY</literal>, a cursor is
opened for the statement when you invoke
- <function role="capi">mysql_stmt_execute()</function>. If there is already an
- open cursor from a previous
- <function role="capi">mysql_stmt_execute()</function> call, it closes the
- cursor before opening a new one.
- <function role="capi">mysql_stmt_reset()</function> also closes any open
- cursor before preparing the statement for re-execution.
- <function role="capi">mysql_stmt_free_result()</function> closes any open
- cursor.
+ <function role="capi">mysql_stmt_execute()</function>. If there
+ is already an open cursor from a previous
+ <function role="capi">mysql_stmt_execute()</function> call, it
+ closes the cursor before opening a new one.
+ <function role="capi">mysql_stmt_reset()</function> also closes
+ any open cursor before preparing the statement for re-execution.
+ <function role="capi">mysql_stmt_free_result()</function> closes
+ any open cursor.
</para>
<para>
If you open a cursor for a prepared statement,
- <function role="capi">mysql_stmt_store_result()</function> is unnecessary,
- because that function causes the result set to be buffered on
- the client side.
+ <function role="capi">mysql_stmt_store_result()</function> is
+ unnecessary, because that function causes the result set to be
+ buffered on the client side.
</para>
<para>
@@ -10037,9 +10084,10 @@
</para>
<para>
- <function role="capi">mysql_stmt_bind_param()</function> is used to bind input
- data for the parameter markers in the SQL statement that was
- passed to <function role="capi">mysql_stmt_prepare()</function>. It uses
+ <function role="capi">mysql_stmt_bind_param()</function> is used
+ to bind input data for the parameter markers in the SQL
+ statement that was passed to
+ <function role="capi">mysql_stmt_prepare()</function>. It uses
<literal>MYSQL_BIND</literal> structures to supply the data.
<literal>bind</literal> is the address of an array of
<literal>MYSQL_BIND</literal> structures. The client library
@@ -10126,8 +10174,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_bind_param()</function>,
- refer to the Example from <xref linkend="mysql-stmt-execute"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_bind_param()</function>, refer
+ to the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
</section>
@@ -10150,44 +10199,47 @@
</para>
<para>
- <function role="capi">mysql_stmt_bind_result()</function> is used to associate
- (that is, bind) output columns in the result set to data buffers
- and length buffers. When <function role="capi">mysql_stmt_fetch()</function>
- is called to fetch data, the MySQL client/server protocol places
- the data for the bound columns into the specified buffers.
+ <function role="capi">mysql_stmt_bind_result()</function> is
+ used to associate (that is, bind) output columns in the result
+ set to data buffers and length buffers. When
+ <function role="capi">mysql_stmt_fetch()</function> is called to
+ fetch data, the MySQL client/server protocol places the data for
+ the bound columns into the specified buffers.
</para>
<para>
All columns must be bound to buffers prior to calling
- <function role="capi">mysql_stmt_fetch()</function>. <literal>bind</literal>
- is the address of an array of <literal>MYSQL_BIND</literal>
- structures. The client library expects the array to contain one
- element for each column of the result set. If you do not bind
- columns to <literal>MYSQL_BIND</literal> structures,
- <function role="capi">mysql_stmt_fetch()</function> simply ignores the data
- fetch. The buffers should be large enough to hold the data
- values, because the protocol doesn't return data values in
- chunks.
+ <function role="capi">mysql_stmt_fetch()</function>.
+ <literal>bind</literal> is the address of an array of
+ <literal>MYSQL_BIND</literal> structures. The client library
+ expects the array to contain one element for each column of the
+ result set. If you do not bind columns to
+ <literal>MYSQL_BIND</literal> structures,
+ <function role="capi">mysql_stmt_fetch()</function> simply
+ ignores the data fetch. The buffers should be large enough to
+ hold the data values, because the protocol doesn't return data
+ values in chunks.
</para>
<para>
A column can be bound or rebound at any time, even after a
result set has been partially retrieved. The new binding takes
- effect the next time <function role="capi">mysql_stmt_fetch()</function> is
- called. Suppose that an application binds the columns in a
- result set and calls <function role="capi">mysql_stmt_fetch()</function>. The
- client/server protocol returns data in the bound buffers. Then
- suppose that the application binds the columns to a different
- set of buffers. The protocol places data into the newly bound
- buffers when the next call to
+ effect the next time
+ <function role="capi">mysql_stmt_fetch()</function> is called.
+ Suppose that an application binds the columns in a result set
+ and calls <function role="capi">mysql_stmt_fetch()</function>.
+ The client/server protocol returns data in the bound buffers.
+ Then suppose that the application binds the columns to a
+ different set of buffers. The protocol places data into the
+ newly bound buffers when the next call to
<function role="capi">mysql_stmt_fetch()</function> occurs.
</para>
<para>
To bind a column, an application calls
- <function role="capi">mysql_stmt_bind_result()</function> and passes the type,
- address, and length of the output buffer into which the value
- should be stored.
+ <function role="capi">mysql_stmt_bind_result()</function> and
+ passes the type, 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.
@@ -10247,8 +10299,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_bind_result()</function>,
- refer to the Example from <xref linkend="mysql-stmt-fetch"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_bind_result()</function>, refer
+ to the Example from <xref linkend="mysql-stmt-fetch"/>.
</para>
</section>
@@ -10271,8 +10324,9 @@
<para>
Closes the prepared statement.
- <function role="capi">mysql_stmt_close()</function> also deallocates the
- statement handle pointed to by <literal>stmt</literal>.
+ <function role="capi">mysql_stmt_close()</function> also
+ deallocates the statement handle pointed to by
+ <literal>stmt</literal>.
</para>
<para>
@@ -10322,7 +10376,8 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_close()</function>, refer to
+ For the usage of
+ <function role="capi">mysql_stmt_close()</function>, refer to
the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
@@ -10355,8 +10410,9 @@
<para>
This function requires that the statement result set structure
contains the entire result of the last executed query, so
- <function role="capi">mysql_stmt_data_seek()</function> may be used only in
- conjunction with <function role="capi">mysql_stmt_store_result()</function>.
+ <function role="capi">mysql_stmt_data_seek()</function> may be
+ used only in conjunction with
+ <function role="capi">mysql_stmt_store_result()</function>.
</para>
<para>
@@ -10505,32 +10561,35 @@
</para>
<para>
- <function role="capi">mysql_stmt_execute()</function> executes the prepared
- query associated with the statement handle. The currently bound
- parameter marker values are sent to server during this call, and
- the server replaces the markers with this newly supplied data.
+ <function role="capi">mysql_stmt_execute()</function> executes
+ the prepared query associated with the statement handle. The
+ currently bound parameter marker values are sent to server
+ during this call, and the server replaces the markers with this
+ newly supplied data.
</para>
<para>
If the statement is an <literal>UPDATE</literal>,
<literal>DELETE</literal>, or <literal>INSERT</literal>, the
total number of changed, deleted, or inserted rows can be found
- by calling <function role="capi">mysql_stmt_affected_rows()</function>. If
+ by calling
+ <function role="capi">mysql_stmt_affected_rows()</function>. If
this is a statement such as <literal>SELECT</literal> that
generates a result set, you must call
- <function role="capi">mysql_stmt_fetch()</function> to fetch the data prior to
- calling any other functions that result in query processing. For
- more information on how to fetch the results, refer to
- <xref linkend="mysql-stmt-fetch"/>.
+ <function role="capi">mysql_stmt_fetch()</function> to fetch the
+ data prior to calling any other functions that result in query
+ processing. For more information on how to fetch the results,
+ refer to <xref linkend="mysql-stmt-fetch"/>.
</para>
<para>
For statements that generate a result set, you can request that
- <function role="capi">mysql_stmt_execute()</function> open a cursor for the
- statement by calling <function role="capi">mysql_stmt_attr_set()</function>
- before executing the statement. If you execute a statement
- multiple times, <function role="capi">mysql_stmt_execute()</function> closes
- any open cursor before opening a new one.
+ <function role="capi">mysql_stmt_execute()</function> open a
+ cursor for the statement by calling
+ <function role="capi">mysql_stmt_attr_set()</function> before
+ executing the statement. If you execute a statement multiple
+ times, <function role="capi">mysql_stmt_execute()</function>
+ closes any open cursor before opening a new one.
</para>
<remark role="note">
@@ -10823,16 +10882,18 @@
</para>
<para>
- <function role="capi">mysql_stmt_fetch()</function> returns the next row in
- the result set. It can be called only while the result set
- exists; that is, after a call to
- <function role="capi">mysql_stmt_execute()</function> for a statement such as
- <literal>SELECT</literal> that creates a result set.
+ <function role="capi">mysql_stmt_fetch()</function> returns the
+ next row in the result set. It can be called only while the
+ result set exists; that is, after a call to
+ <function role="capi">mysql_stmt_execute()</function> for a
+ statement such as <literal>SELECT</literal> that creates a
+ result set.
</para>
<para>
- <function role="capi">mysql_stmt_fetch()</function> returns row data using the
- buffers bound by <function role="capi">mysql_stmt_bind_result()</function>. It
+ <function role="capi">mysql_stmt_fetch()</function> returns row
+ data using the buffers bound by
+ <function role="capi">mysql_stmt_bind_result()</function>. It
returns the data in those buffers for all the columns in the
current row set and the lengths are returned to the
<literal>length</literal> pointer. All columns must be bound by
@@ -10843,8 +10904,8 @@
<para>
By default, result sets are fetched unbuffered a row at a time
from the server. To buffer the entire result set on the client,
- call <function role="capi">mysql_stmt_store_result()</function> after binding
- the data buffers and before caling
+ call <function role="capi">mysql_stmt_store_result()</function>
+ after binding the data buffers and before caling
<function role="capi">mysql_stmt_fetch()</function>.
</para>
@@ -11050,11 +11111,12 @@
<para>
The following example demonstrates how to fetch data from a
- table using <function role="capi">mysql_stmt_result_metadata()</function>,
+ table using
+ <function role="capi">mysql_stmt_result_metadata()</function>,
<function role="capi">mysql_stmt_bind_result()</function>, and
- <function role="capi">mysql_stmt_fetch()</function>. (This example expects to
- retrieve the two rows inserted by the example shown in
- <xref linkend="mysql-stmt-execute"/>.) The
+ <function role="capi">mysql_stmt_fetch()</function>. (This
+ example expects to retrieve the two rows inserted by the example
+ shown in <xref linkend="mysql-stmt-execute"/>.) The
<literal>mysql</literal> variable is assumed to be a valid
connection handle.
</para>
@@ -11247,37 +11309,41 @@
<para>
In some cases you might want to determine the length of a column
value before fetching it with
- <function role="capi">mysql_stmt_fetch()</function>. For example, the value
- might be a long string or <literal>BLOB</literal> value for
- which you want to know how much space must be allocated. To
- accomplish this, you can use these strategies:
+ <function role="capi">mysql_stmt_fetch()</function>. For
+ example, the value might be a long string or
+ <literal>BLOB</literal> value for which you want to know how
+ much space must be allocated. To accomplish this, you can use
+ these strategies:
</para>
<itemizedlist>
<listitem>
<para>
- Before invoking <function role="capi">mysql_stmt_fetch()</function> to
+ Before invoking
+ <function role="capi">mysql_stmt_fetch()</function> to
retrieve individual rows, invoke
- <function role="capi">mysql_stmt_store_result()</function> to buffer the
- entire result on the client side. Then the maximal length of
- column values will be indicated by the
+ <function role="capi">mysql_stmt_store_result()</function>
+ to buffer the entire result on the client side. Then the
+ maximal length of column values will be indicated by the
<literal>max_length</literal> member of the result set
metadata returned by
- <function role="capi">mysql_stmt_result_metadata()</function>. This
- strategy requires that you pass
+ <function role="capi">mysql_stmt_result_metadata()</function>.
+ This strategy requires that you pass
<literal>STMT_ATTR_UPDATE_MAX_LENGTH</literal> to
- <function role="capi">mysql_stmt_attr_set()</function> or the
- <literal>max_length</literal> values will not be calculated.
+ <function role="capi">mysql_stmt_attr_set()</function> or
+ the <literal>max_length</literal> values will not be
+ calculated.
</para>
</listitem>
<listitem>
<para>
- Invoke <function role="capi">mysql_stmt_fetch()</function> with a
- zero-length buffer for the column in question and a pointer
- in which the real length can be stored. Then use the real
- length with <function role="capi">mysql_stmt_fetch_column()</function>.
+ Invoke <function role="capi">mysql_stmt_fetch()</function>
+ with a zero-length buffer for the column in question and a
+ pointer in which the real length can be stored. Then use the
+ real length with
+ <function role="capi">mysql_stmt_fetch_column()</function>.
</para>
<programlisting>
@@ -11397,8 +11463,8 @@
</para>
<para>
- <function role="capi">mysql_stmt_field_count()</function> can be called after
- you have prepared a statement by invoking
+ <function role="capi">mysql_stmt_field_count()</function> can be
+ called after you have prepared a statement by invoking
<function role="capi">mysql_stmt_prepare()</function>.
</para>
@@ -11441,8 +11507,9 @@
<para>
Releases memory associated with the result set produced by
execution of the prepared statement. If there is a cursor open
- for the statement, <function role="capi">mysql_stmt_free_result()</function>
- closes it.
+ for the statement,
+ <function role="capi">mysql_stmt_free_result()</function> closes
+ it.
</para>
<para>
@@ -11478,7 +11545,8 @@
<para>
Create a <literal>MYSQL_STMT</literal> handle. The handle should
- be freed with <function role="capi">mysql_stmt_close(MYSQL_STMT *)</function>.
+ be freed with <function role="capi">mysql_stmt_close(MYSQL_STMT
+ *)</function>.
</para>
<para>
@@ -11592,25 +11660,29 @@
</para>
<para>
- The use of <function role="capi">mysql_stmt_num_rows()</function> depends on
- whether you used <function role="capi">mysql_stmt_store_result()</function> to
+ The use of
+ <function role="capi">mysql_stmt_num_rows()</function> depends
+ on whether you used
+ <function role="capi">mysql_stmt_store_result()</function> to
buffer the entire result set in the statement handle.
</para>
<para>
- If you use <function role="capi">mysql_stmt_store_result()</function>,
- <function role="capi">mysql_stmt_num_rows()</function> may be called
- immediately. Otherwise, the row count is unavailable unless you
- count the rows as you fetch them.
+ If you use
+ <function role="capi">mysql_stmt_store_result()</function>,
+ <function role="capi">mysql_stmt_num_rows()</function> may be
+ called immediately. Otherwise, the row count is unavailable
+ unless you count the rows as you fetch them.
</para>
<para>
- <function role="capi">mysql_stmt_num_rows()</function> is intended for use
- with statements that return a result set, such as
- <literal>SELECT</literal>. For statements such as
+ <function role="capi">mysql_stmt_num_rows()</function> is
+ intended for use with statements that return a result set, such
+ as <literal>SELECT</literal>. For statements such as
<literal>INSERT</literal>, <literal>UPDATE</literal>, or
<literal>DELETE</literal>, the number of affected rows can be
- obtained with <function role="capi">mysql_stmt_affected_rows()</function>.
+ obtained with
+ <function role="capi">mysql_stmt_affected_rows()</function>.
</para>
<para>
@@ -11675,8 +11747,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_param_count()</function>,
- refer to the Example from <xref linkend="mysql-stmt-execute"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_param_count()</function>, refer
+ to the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
</section>
@@ -11731,11 +11804,12 @@
<para>
Given the statement handle returned by
- <function role="capi">mysql_stmt_init()</function>, prepares the SQL statement
- pointed to by the string <literal>stmt_str</literal> and returns
- a status value. The string length should be given by the
- <literal>length</literal> argument. The string must consist of a
- single SQL statement. You should not add a terminating semicolon
+ <function role="capi">mysql_stmt_init()</function>, prepares the
+ SQL statement pointed to by the string
+ <literal>stmt_str</literal> and returns a status value. The
+ string length should be given by the <literal>length</literal>
+ argument. The string must consist of a single SQL statement. You
+ should not add a terminating semicolon
(<quote><literal>;</literal></quote>) or <literal>\g</literal>
to the statement.
</para>
@@ -11764,8 +11838,8 @@
<para>
The parameter markers must be bound to application variables
- using <function role="capi">mysql_stmt_bind_param()</function> before
- executing the statement.
+ using <function role="capi">mysql_stmt_bind_param()</function>
+ before executing the statement.
</para>
<para>
@@ -11837,8 +11911,8 @@
<para>
If the prepare operation was unsuccessful (that is,
- <function role="capi">mysql_stmt_prepare()</function> returns non-zero), the
- error message can be obtained by calling
+ <function role="capi">mysql_stmt_prepare()</function> returns
+ non-zero), the error message can be obtained by calling
<function role="capi">mysql_stmt_error()</function>.
</para>
@@ -11847,8 +11921,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_prepare()</function>, refer
- to the Example from <xref linkend="mysql-stmt-execute"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_prepare()</function>, refer to
+ the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
</section>
@@ -11872,8 +11947,8 @@
<para>
Reset the prepared statement on the client and server to state
after prepare. This is mainly used to reset data sent with
- <function role="capi">mysql_stmt_send_long_data()</function>. Any open cursor
- for the statement is closed.
+ <function role="capi">mysql_stmt_send_long_data()</function>.
+ Any open cursor for the statement is closed.
</para>
<para>
@@ -11958,10 +12033,11 @@
</para>
<para>
- If a statement passed to <function role="capi">mysql_stmt_prepare()</function>
- is one that produces a result set,
- <function role="capi">mysql_stmt_result_metadata()</function> returns the
- result set metadata in the form of a pointer to a
+ If a statement passed to
+ <function role="capi">mysql_stmt_prepare()</function> is one
+ that produces a result set,
+ <function role="capi">mysql_stmt_result_metadata()</function>
+ returns the result set metadata in the form of a pointer to a
<literal>MYSQL_RES</literal> structure that can be used to
process the meta information such as total number of fields and
individual field information. This result set pointer can be
@@ -12024,16 +12100,16 @@
<para>
The result set structure should be freed when you are done with
it, which you can do by passing it to
- <function role="capi">mysql_free_result()</function>. This is similar to the
- way you free a result set obtained from a call to
+ <function role="capi">mysql_free_result()</function>. This is
+ similar to the way you free a result set obtained from a call to
<function role="capi">mysql_store_result()</function>.
</para>
<para>
The result set returned by
- <function role="capi">mysql_stmt_result_metadata()</function> contains only
- metadata. It does not contain any row results. The rows are
- obtained by using the statement handle with
+ <function role="capi">mysql_stmt_result_metadata()</function>
+ contains only metadata. It does not contain any row results. The
+ rows are obtained by using the statement handle with
<function role="capi">mysql_stmt_fetch()</function>.
</para>
@@ -12081,8 +12157,8 @@
<para>
For the usage of
- <function role="capi">mysql_stmt_result_metadata()</function>, refer to the
- Example from <xref linkend="mysql-stmt-fetch"/>.
+ <function role="capi">mysql_stmt_result_metadata()</function>,
+ refer to the Example from <xref linkend="mysql-stmt-fetch"/>.
</para>
</section>
@@ -12109,16 +12185,18 @@
set. The <literal>offset</literal> value is a row offset that
should be a value returned from
<function role="capi">mysql_stmt_row_tell()</function> or from
- <function role="capi">mysql_stmt_row_seek()</function>. This value is not a
- row number; if you want to seek to a row within a result set by
- number, use <function role="capi">mysql_stmt_data_seek()</function> instead.
+ <function role="capi">mysql_stmt_row_seek()</function>. This
+ value is not a row number; if you want to seek to a row within a
+ result set by number, use
+ <function role="capi">mysql_stmt_data_seek()</function> instead.
</para>
<para>
This function requires that the result set structure contains
the entire result of the query, so
- <function role="capi">mysql_stmt_row_seek()</function> may be used only in
- conjunction with <function role="capi">mysql_stmt_store_result()</function>.
+ <function role="capi">mysql_stmt_row_seek()</function> may be
+ used only in conjunction with
+ <function role="capi">mysql_stmt_store_result()</function>.
</para>
<para>
@@ -12160,13 +12238,16 @@
<para>
Returns the current position of the row cursor for the last
- <function role="capi">mysql_stmt_fetch()</function>. This value can be used as
- an argument to <function role="capi">mysql_stmt_row_seek()</function>.
+ <function role="capi">mysql_stmt_fetch()</function>. This value
+ can be used as an argument to
+ <function role="capi">mysql_stmt_row_seek()</function>.
</para>
<para>
- You should use <function role="capi">mysql_stmt_row_tell()</function> only
- after <function role="capi">mysql_stmt_store_result()</function>.
+ You should use
+ <function role="capi">mysql_stmt_row_tell()</function> only
+ after
+ <function role="capi">mysql_stmt_store_result()</function>.
</para>
<para>
@@ -12208,10 +12289,10 @@
<para>
Allows an application to send parameter data to the server in
pieces (or <quote>chunks</quote>). Call this function after
- <function role="capi">mysql_stmt_bind_param()</function> and before
- <function role="capi">mysql_stmt_execute()</function>. It can be called
- multiple times to send the parts of a character or binary data
- value for a column, which must be one of the
+ <function role="capi">mysql_stmt_bind_param()</function> and
+ before <function role="capi">mysql_stmt_execute()</function>. It
+ can be called multiple times to send the parts of a character or
+ binary data value for a column, which must be one of the
<literal>TEXT</literal> or <literal>BLOB</literal> data types.
</para>
@@ -12225,9 +12306,11 @@
<note>
<para>
- The next <function role="capi">mysql_stmt_execute()</function> call ignores
- the bind buffer for all parameters that have been used with
- <function role="capi">mysql_stmt_send_long_data()</function> since last
+ The next <function role="capi">mysql_stmt_execute()</function>
+ call ignores the bind buffer for all parameters that have been
+ used with
+ <function role="capi">mysql_stmt_send_long_data()</function>
+ since last
<function role="capi">mysql_stmt_execute()</function> or
<function role="capi">mysql_stmt_reset()</function>.
</para>
@@ -12446,31 +12529,35 @@
<literal>SHOW</literal>, <literal>DESCRIBE</literal>, and
<literal>EXPLAIN</literal>. By default, result sets for
successfully executed prepared statements are not buffered on
- the client and <function role="capi">mysql_stmt_fetch()</function> fetches
- them one at a time from the server. To cause the complete result
- set to be buffered on the client, call
- <function role="capi">mysql_stmt_store_result()</function> after binding data
- buffers with <function role="capi">mysql_stmt_bind_result()</function> and
- before calling <function role="capi">mysql_stmt_fetch()</function> to fetch
+ the client and
+ <function role="capi">mysql_stmt_fetch()</function> fetches them
+ one at a time from the server. To cause the complete result set
+ to be buffered on the client, call
+ <function role="capi">mysql_stmt_store_result()</function> after
+ binding data buffers with
+ <function role="capi">mysql_stmt_bind_result()</function> and
+ before calling
+ <function role="capi">mysql_stmt_fetch()</function> to fetch
rows. (For an example, see <xref linkend="mysql-stmt-fetch"/>.)
</para>
<para>
- <function role="capi">mysql_stmt_store_result()</function> is optional for
- result set processing, unless you will call
+ <function role="capi">mysql_stmt_store_result()</function> is
+ optional for result set processing, unless you will call
<function role="capi">mysql_stmt_data_seek()</function>,
<function role="capi">mysql_stmt_row_seek()</function>, or
- <function role="capi">mysql_stmt_row_tell()</function>. Those functions
- require a seekable result set.
+ <function role="capi">mysql_stmt_row_tell()</function>. Those
+ functions require a seekable result set.
</para>
<para>
It is unnecessary to call
- <function role="capi">mysql_stmt_store_result()</function> after executing a
- SQL statement that does not produce a result set, but if you do,
- it does not harm or cause any notable performance problem. You
- can detect whether the statement produced a result set by
- checking if <function role="capi">mysql_stmt_result_metadata()</function>
+ <function role="capi">mysql_stmt_store_result()</function> after
+ executing a SQL statement that does not produce a result set,
+ but if you do, it does not harm or cause any notable performance
+ problem. You can detect whether the statement produced a result
+ set by checking if
+ <function role="capi">mysql_stmt_result_metadata()</function>
returns <literal>NULL</literal>. For more information, refer to
<xref linkend="mysql-stmt-result-metadata"/>.
</para>
@@ -12479,12 +12566,13 @@
<para>
MySQL doesn't by default calculate
<literal>MYSQL_FIELD->max_length</literal> for all columns
- in <function role="capi">mysql_stmt_store_result()</function> because
- calculating this would slow down
- <function role="capi">mysql_stmt_store_result()</function> considerably and
- most applications doesn't need <literal>max_length</literal>.
- If you want <literal>max_length</literal> to be updated, you
- can call <function role="capi">mysql_stmt_attr_set(MYSQL_STMT,
+ in <function role="capi">mysql_stmt_store_result()</function>
+ because calculating this would slow down
+ <function role="capi">mysql_stmt_store_result()</function>
+ considerably and most applications doesn't need
+ <literal>max_length</literal>. If you want
+ <literal>max_length</literal> to be updated, you can call
+ <function role="capi">mysql_stmt_attr_set(MYSQL_STMT,
STMT_ATTR_UPDATE_MAX_LENGTH, &flag)</function> to enable
this. See <xref linkend="mysql-stmt-attr-set"/>.
</para>
@@ -12656,11 +12744,11 @@
check whether more results exist and process them in turn if so.
To support multiple-result processing, the C API includes the
<function role="capi">mysql_more_results()</function> and
- <function role="capi">mysql_next_result()</function> functions. Generally, these
- functions are used at the end of a loop that iterates as long as
- more results are available. <emphasis>Failure to process the
- result this way may result in a dropped connection to the
- server.</emphasis>
+ <function role="capi">mysql_next_result()</function> functions.
+ Generally, these functions are used at the end of a loop that
+ iterates as long as more results are available. <emphasis>Failure
+ to process the result this way may result in a dropped connection
+ to the server.</emphasis>
</para>
<para>
@@ -12737,7 +12825,8 @@
<listitem>
<para>
After the connection to the server has been established, you
- can use the <function role="capi">mysql_set_server_option()</function>
+ can use the
+ <function role="capi">mysql_set_server_option()</function>
function to enable or disable multiple-statement execution by
passing it an argument of
<literal>MYSQL_OPTION_MULTI_STATEMENTS_ON</literal> or
@@ -12789,9 +12878,9 @@
<listitem>
<para>
At the end of the loop, call
- <function role="capi">mysql_next_result()</function> to check whether
- another result exists and initiate retrieval for it if so. If
- no more results are available, exit the loop.
+ <function role="capi">mysql_next_result()</function> to check
+ whether another result exists and initiate retrieval for it if
+ so. If no more results are available, exit the loop.
</para>
</listitem>
@@ -12860,10 +12949,10 @@
<para>
The final part of the loop can be reduced to a simple test of
- whether <function role="capi">mysql_next_result()</function> returns non-zero.
- The code as written distinguishes between no more results and an
- error, which allows a message to be printed for the latter
- occurrence.
+ whether <function role="capi">mysql_next_result()</function>
+ returns non-zero. The code as written distinguishes between no
+ more results and an error, which allows a message to be printed
+ for the latter occurrence.
</para>
</section>
@@ -12884,9 +12973,11 @@
<para>
To send temporal data values, create a prepared statement using
- <function role="capi">mysql_stmt_prepare()</function>. Then, before calling
- <function role="capi">mysql_stmt_execute()</function> to execute the statement,
- use the following procedure to set up each temporal parameter:
+ <function role="capi">mysql_stmt_prepare()</function>. Then,
+ before calling
+ <function role="capi">mysql_stmt_execute()</function> to execute
+ the statement, use the following procedure to set up each temporal
+ parameter:
</para>
<orderedlist>
@@ -12926,8 +13017,8 @@
</orderedlist>
<para>
- Use <function role="capi">mysql_stmt_bind_param()</function> to bind the
- parameter data to the statement. Then you can call
+ Use <function role="capi">mysql_stmt_bind_param()</function> to
+ bind the parameter data to the statement. Then you can call
<function role="capi">mysql_stmt_execute()</function>.
</para>
@@ -12937,9 +13028,10 @@
value you expect to receive, and the <literal>buffer</literal>
member to the address of a <literal>MYSQL_TIME</literal> structure
into which the returned value should be placed. Use
- <function role="capi">mysql_stmt_bind_result()</function> to bind the buffers to the
- statement after calling <function role="capi">mysql_stmt_execute()</function>
- and before fetching the results.
+ <function role="capi">mysql_stmt_bind_result()</function> to bind
+ the buffers to the statement after calling
+ <function role="capi">mysql_stmt_execute()</function> and before
+ fetching the results.
</para>
<para>
@@ -13410,8 +13502,8 @@
<listitem>
<para>
- <function role="capi">mysql_ping()</function> does not attempt a
- reconnection if the connection is down. It returns an error
+ <function role="capi">mysql_ping()</function> does not attempt
+ a reconnection if the connection is down. It returns an error
instead.
</para>
</listitem>
@@ -13535,15 +13627,16 @@
<listitem>
<para>
- <function role="capi">mysql_num_rows()</function> returns the number of
- rows in a result set. With
+ <function role="capi">mysql_num_rows()</function> returns
+ the number of rows in a result set. With
<function role="capi">mysql_store_result()</function>,
- <function role="capi">mysql_num_rows()</function> may be called as soon as
+ <function role="capi">mysql_num_rows()</function> may be
+ called as soon as
<function role="capi">mysql_store_result()</function>
returns. With
<function role="capi">mysql_use_result()</function>,
- <function role="capi">mysql_num_rows()</function> may be called only after
- you have fetched all the rows with
+ <function role="capi">mysql_num_rows()</function> may be
+ called only after you have fetched all the rows with
<function role="capi">mysql_fetch_row()</function>.
</para>
</listitem>
@@ -13970,11 +14063,12 @@
<listitem>
<para>
- If you use <function role="capi">mysql_use_result()</function>,
- you must ensure that no other thread is using the same
- connection until the result set is closed. However, it really
- is best for threaded clients that share the same connection to
- use <function role="capi">mysql_store_result()</function>.
+ If you use
+ <function role="capi">mysql_use_result()</function>, you must
+ ensure that no other thread is using the same connection until
+ the result set is closed. However, it really is best for
+ threaded clients that share the same connection to use
+ <function role="capi">mysql_store_result()</function>.
</para>
</listitem>
Modified: trunk/refman-5.0/dba-core.xml
===================================================================
--- trunk/refman-5.0/dba-core.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.0/dba-core.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 4, Lines Added: 17, Lines Deleted: 12; 3247 bytes
@@ -16328,7 +16328,8 @@
<listitem>
<para>
MySQL C API: Use the
- <function role="capi">mysql_real_escape_string()</function> API call.
+ <function role="capi">mysql_real_escape_string()</function>
+ API call.
</para>
</listitem>
@@ -17081,7 +17082,8 @@
<command>configure</command> with the
<option>--enable-local-infile</option> option, <literal>LOAD
DATA LOCAL</literal> cannot be used by any client unless it
- is written explicitly to invoke <function role="capi">mysql_options(...
+ is written explicitly to invoke
+ <function role="capi">mysql_options(...
MYSQL_OPT_LOCAL_INFILE, 0)</function>. See
<xref linkend="mysql-options"/>.
</para>
@@ -22892,16 +22894,17 @@
<para>
To establish a secure connection from within an application
- program, use the <function role="capi">mysql_ssl_set()</function> C API
+ program, use the
+ <function role="capi">mysql_ssl_set()</function> C API
function to set the appropriate certificate options before
calling <function role="capi">mysql_real_connect()</function>.
See <xref linkend="mysql-ssl-set"/>. After the connection is
established, you can use
- <function role="capi">mysql_get_ssl_cipher()</function> to determine whether
- SSL is in use. A non-<literal>NULL</literal> return value
- indicates a secure connection and names the SSL cipher used
- for encryption. A <literal>NULL</literal> return value
- indicates that SSL is not being used. See
+ <function role="capi">mysql_get_ssl_cipher()</function> to
+ determine whether SSL is in use. A non-<literal>NULL</literal>
+ return value indicates a secure connection and names the SSL
+ cipher used for encryption. A <literal>NULL</literal> return
+ value indicates that SSL is not being used. See
<xref linkend="mysql-get-ssl-cipher"/>.
</para>
@@ -26043,10 +26046,12 @@
</para>
<para>
- You should use <function role="capi">mysql_real_escape_string()</function>
- when escaping strings for an SQL query.
- <function role="capi">mysql_real_escape_string()</function> is identical to
- the old <function role="capi">mysql_escape_string()</function> function,
+ You should use
+ <function role="capi">mysql_real_escape_string()</function> when
+ escaping strings for an SQL query.
+ <function role="capi">mysql_real_escape_string()</function> is
+ identical to the old
+ <function role="capi">mysql_escape_string()</function> function,
except that it takes the <literal>MYSQL</literal> connection
handle as the first parameter so that the appropriate character
set can be taken into account when escaping characters.
Modified: trunk/refman-5.0/errors-problems.xml
===================================================================
--- trunk/refman-5.0/errors-problems.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.0/errors-problems.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 4, Lines Added: 16, Lines Deleted: 13; 2889 bytes
@@ -1040,9 +1040,9 @@
If not, correct the query and try again. Otherwise, you can
invoke <command>mysql</command> with the
<option>--quick</option> option. This causes it to use the
- <function role="capi">mysql_use_result()</function> C API function to
- retrieve the result set, which places less of a load on the
- client (but more on the server).
+ <function role="capi">mysql_use_result()</function> C API
+ function to retrieve the result set, which places less of a
+ load on the client (but more on the server).
</para>
</section>
@@ -1188,9 +1188,9 @@
<para>
The solution to this is to either do a
- <function role="capi">mysql_ping()</function> on the connection if there
- has been a long time since the last query (this is what
- <literal>MyODBC</literal> does) or set
+ <function role="capi">mysql_ping()</function> on the
+ connection if there has been a long time since the last
+ query (this is what <literal>MyODBC</literal> does) or set
<literal>wait_timeout</literal> on the
<command>mysqld</command> server so high that it in
practice never times out.
@@ -1479,7 +1479,8 @@
<listitem>
<para>
The client program did not call
- <function role="capi">mysql_close()</function> before exiting.
+ <function role="capi">mysql_close()</function> before
+ exiting.
</para>
</listitem>
@@ -1971,12 +1972,14 @@
<para>
This can happen, for example, if you are using
- <function role="capi">mysql_use_result()</function> and try to execute a new
- query before you have called
- <function role="capi">mysql_free_result()</function>. It can also happen if
- you try to execute two queries that return data without
- calling <function role="capi">mysql_use_result()</function> or
- <function role="capi">mysql_store_result()</function> in between.
+ <function role="capi">mysql_use_result()</function> and try to
+ execute a new query before you have called
+ <function role="capi">mysql_free_result()</function>. It can
+ also happen if you try to execute two queries that return data
+ without calling
+ <function role="capi">mysql_use_result()</function> or
+ <function role="capi">mysql_store_result()</function> in
+ between.
</para>
</section>
Modified: trunk/refman-5.0/replication-solutions.xml
===================================================================
--- trunk/refman-5.0/replication-solutions.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.0/replication-solutions.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 3, Lines Added: 9, Lines Deleted: 8; 1866 bytes
@@ -15,8 +15,8 @@
<para>
For information on using replication in a backup environment,
- including notes on the setup, backup procedure, and files to back up,
- see <xref linkend="replication-solutions-backups"/>.
+ including notes on the setup, backup procedure, and files to back
+ up, see <xref linkend="replication-solutions-backups"/>.
</para>
<para>
@@ -65,8 +65,8 @@
<para>
You can use replication as a backup solution by replicating data
from the master to a slave, and then backing up the data slave.
- Because the slave can be paused and shut down without affecting the
- running operation of the master you can produce an effective
+ Because the slave can be paused and shut down without affecting
+ the running operation of the master you can produce an effective
snapshot of 'live' data that would otherwise require a shutdown of
the master database.
</para>
@@ -79,10 +79,11 @@
</para>
<para>
- If you are using replication as a solution to enable you to back up
- the data on the master, and the size of your database is not too
- large, then the <literal>mysqldump</literal> tool may be suitable.
- See <xref linkend="replication-solutions-backups-mysqldump"/>.
+ If you are using replication as a solution to enable you to back
+ up the data on the master, and the size of your database is not
+ too large, then the <literal>mysqldump</literal> tool may be
+ suitable. See
+ <xref linkend="replication-solutions-backups-mysqldump"/>.
</para>
<para>
Modified: trunk/refman-5.0/restrictions.xml
===================================================================
--- trunk/refman-5.0/restrictions.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.0/restrictions.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 7, Lines Deleted: 6; 1193 bytes
@@ -327,12 +327,13 @@
<para>
Server-side cursors are implemented beginning with the C API in
- MySQL 5.0.2 via the <function role="capi">mysql_stmt_attr_set()</function>
- function. A server-side cursor allows a result set to be generated
- on the server side, but not transferred to the client except for
- those rows that the client requests. For example, if a client
- executes a query but is only interested in the first row, the
- remaining rows are not transferred.
+ MySQL 5.0.2 via the
+ <function role="capi">mysql_stmt_attr_set()</function> function. A
+ server-side cursor allows a result set to be generated on the
+ server side, but not transferred to the client except for those
+ rows that the client requests. For example, if a client executes a
+ query but is only interested in the first row, the remaining rows
+ are not transferred.
</para>
<para>
Modified: trunk/refman-5.0/se-federated.xml
===================================================================
--- trunk/refman-5.0/se-federated.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.0/se-federated.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 4, Lines Deleted: 3; 902 bytes
@@ -150,9 +150,10 @@
<para>
The local server communicates with the remote server using MySQL
client C API functions. It invokes
- <function role="capi">mysql_real_query()</function> to send the statement. To
- read a result set, it uses <function role="capi">mysql_store_result()</function>
- and fetches rows one at a time using
+ <function role="capi">mysql_real_query()</function> to send the
+ statement. To read a result set, it uses
+ <function role="capi">mysql_store_result()</function> and fetches
+ rows one at a time using
<function role="capi">mysql_fetch_row()</function>.
</para>
Modified: trunk/refman-5.0/sql-syntax.xml
===================================================================
--- trunk/refman-5.0/sql-syntax.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.0/sql-syntax.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 4, Lines Deleted: 3; 861 bytes
@@ -23546,9 +23546,10 @@
<para>
SQL syntax for prepared statements is distinct from using prepared
statement API calls. For example, you cannot use the
- <function role="capi">mysql_stmt_prepare()</function> C API function to prepare
- a <literal>PREPARE</literal>, <literal>EXECUTE</literal>, or
- <literal>DEALLOCATE PREPARE</literal> statement.
+ <function role="capi">mysql_stmt_prepare()</function> C API
+ function to prepare a <literal>PREPARE</literal>,
+ <literal>EXECUTE</literal>, or <literal>DEALLOCATE
+ PREPARE</literal> statement.
</para>
<para>
Modified: trunk/refman-5.0/stored-procedures.xml
===================================================================
--- trunk/refman-5.0/stored-procedures.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.0/stored-procedures.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 2, Lines Deleted: 1; 803 bytes
@@ -1046,7 +1046,8 @@
the result sets returned by statements executed within the
procedure, as well as a result to indicate the call status. To
process the result of a <literal>CALL</literal> statement, use a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
Modified: trunk/refman-5.1/apis-c.xml
===================================================================
--- trunk/refman-5.1/apis-c.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.1/apis-c.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 107, Lines Added: 524, Lines Deleted: 430; 87798 bytes
@@ -1328,8 +1328,8 @@
<para>
After you are done with a result set, call
- <function role="capi">mysql_free_result()</function> to free the memory used for
- it.
+ <function role="capi">mysql_free_result()</function> to free the
+ memory used for it.
</para>
<para>
@@ -1345,12 +1345,13 @@
<function role="capi">mysql_store_result()</function> is that
because the rows have all been fetched to the client, you not only
can access rows sequentially, you can move back and forth in the
- result set using <function role="capi">mysql_data_seek()</function> or
+ result set using
+ <function role="capi">mysql_data_seek()</function> or
<function role="capi">mysql_row_seek()</function> to change the
current row position within the result set. You can also find out
how many rows there are by calling
- <function role="capi">mysql_num_rows()</function>. On the other hand, the memory
- requirements for
+ <function role="capi">mysql_num_rows()</function>. On the other
+ hand, the memory requirements for
<function role="capi">mysql_store_result()</function> may be very
high for large result sets and you are more likely to encounter
out-of-memory conditions.
@@ -2130,8 +2131,8 @@
<para>
This function requires that the result set structure contains
the entire result of the query, so
- <function role="capi">mysql_data_seek()</function> may be used only in
- conjunction with
+ <function role="capi">mysql_data_seek()</function> may be used
+ only in conjunction with
<function role="capi">mysql_store_result()</function>, not with
<function role="capi">mysql_use_result()</function>.
</para>
@@ -2172,9 +2173,9 @@
<para>
Does a <literal>DBUG_PUSH</literal> with the given string.
- <function role="capi">mysql_debug()</function> uses the Fred Fish debug
- library. To use this function, you must compile the client
- library to support debugging. See
+ <function role="capi">mysql_debug()</function> uses the Fred
+ Fish debug library. To use this function, you must compile the
+ client library to support debugging. See
<ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
Internals: Porting</ulink>.
</para>
@@ -2687,19 +2688,21 @@
</indexterm>
<para>
- You should use <function role="capi">mysql_real_escape_string()</function>
+ You should use
+ <function role="capi">mysql_real_escape_string()</function>
instead!
</para>
<para>
This function is identical to
- <function role="capi">mysql_real_escape_string()</function> except that
- <function role="capi">mysql_real_escape_string()</function> takes a connection
- handler as its first argument and escapes the string according
- to the current character set.
- <function role="capi">mysql_escape_string()</function> does not take a
- connection argument and does not respect the current character
- set.
+ <function role="capi">mysql_real_escape_string()</function>
+ except that
+ <function role="capi">mysql_real_escape_string()</function>
+ takes a connection handler as its first argument and escapes the
+ string according to the current character set.
+ <function role="capi">mysql_escape_string()</function> does not
+ take a connection argument and does not respect the current
+ character set.
</para>
</section>
@@ -2807,7 +2810,8 @@
<literal>MYSQL_FIELD</literal> structure. You may use this
function to retrieve the definition for an arbitrary column. The
value of <literal>fieldnr</literal> should be in the range from
- 0 to <function role="capi">mysql_num_fields(result)-1</function>.
+ 0 to
+ <function role="capi">mysql_num_fields(result)-1</function>.
</para>
<para>
@@ -3321,9 +3325,10 @@
Frees the memory allocated for a result set by
<function role="capi">mysql_store_result()</function>,
<function role="capi">mysql_use_result()</function>,
- <function role="capi">mysql_list_dbs()</function>, and so forth. When you are
- done with a result set, you must free the memory it uses by
- calling <function role="capi">mysql_free_result()</function>.
+ <function role="capi">mysql_list_dbs()</function>, and so forth.
+ When you are done with a result set, you must free the memory it
+ uses by calling
+ <function role="capi">mysql_free_result()</function>.
</para>
<para>
@@ -3368,7 +3373,8 @@
<para>
This function provides information about the default client
character set. The default character set may be changed with the
- <function role="capi">mysql_set_character_set()</function> function.
+ <function role="capi">mysql_set_character_set()</function>
+ function.
</para>
<para>
@@ -3671,8 +3677,8 @@
</para>
<para>
- <function role="capi">mysql_get_ssl_cipher()</function> returns the SSL cipher
- used for the given connection to the server.
+ <function role="capi">mysql_get_ssl_cipher()</function> returns
+ the SSL cipher used for the given connection to the server.
<literal>mysql</literal> is the connection handler returned from
<function role="capi">mysql_init()</function>.
</para>
@@ -3726,10 +3732,10 @@
<literal>length</literal> bytes long. You must allocate the
<literal>to</literal> buffer to be at least
<literal>length*2+1</literal> bytes long. When
- <function role="capi">mysql_hex_string()</function> returns, the contents of
- <literal>to</literal> is a null-terminated string. The return
- value is the length of the encoded string, not including the
- terminating null character.
+ <function role="capi">mysql_hex_string()</function> returns, the
+ contents of <literal>to</literal> is a null-terminated string.
+ The return value is the length of the encoded string, not
+ including the terminating null character.
</para>
<para>
@@ -4468,8 +4474,8 @@
<quote><literal>%</literal></quote> or
<quote><literal>_</literal></quote>, or may be a
<literal>NULL</literal> pointer to match all databases. Calling
- <function role="capi">mysql_list_dbs()</function> is similar to executing the
- query <literal>SHOW databases [LIKE
+ <function role="capi">mysql_list_dbs()</function> is similar to
+ executing the query <literal>SHOW databases [LIKE
<replaceable>wild</replaceable>]</literal>.
</para>
@@ -4572,8 +4578,8 @@
<quote><literal>%</literal></quote> or
<quote><literal>_</literal></quote>, or may be a
<literal>NULL</literal> pointer to match all fields. Calling
- <function role="capi">mysql_list_fields()</function> is similar to executing
- the query <literal>SHOW COLUMNS FROM
+ <function role="capi">mysql_list_fields()</function> is similar
+ to executing the query <literal>SHOW COLUMNS FROM
<replaceable>tbl_name</replaceable> [LIKE
<replaceable>wild</replaceable>]</literal>.
</para>
@@ -4760,8 +4766,8 @@
<quote><literal>%</literal></quote> or
<quote><literal>_</literal></quote>, or may be a
<literal>NULL</literal> pointer to match all tables. Calling
- <function role="capi">mysql_list_tables()</function> is similar to executing
- the query <literal>SHOW tables [LIKE
+ <function role="capi">mysql_list_tables()</function> is similar
+ to executing the query <literal>SHOW tables [LIKE
<replaceable>wild</replaceable>]</literal>.
</para>
@@ -4853,10 +4859,11 @@
</para>
<para>
- <function role="capi">mysql_more_results()</function> true if more results
- exist from the currently executed statement, in which case the
- application must call <function role="capi">mysql_next_result()</function> to
- fetch the results.
+ <function role="capi">mysql_more_results()</function> true if
+ more results exist from the currently executed statement, in
+ which case the application must call
+ <function role="capi">mysql_next_result()</function> to fetch
+ the results.
</para>
<para>
@@ -4870,8 +4877,8 @@
<para>
In most cases, you can call
- <function role="capi">mysql_next_result()</function> instead to test whether
- more results exist and initiate retrieval if so.
+ <function role="capi">mysql_next_result()</function> instead to
+ test whether more results exist and initiate retrieval if so.
</para>
<para>
@@ -4914,18 +4921,22 @@
<para>
If more statement results exist,
- <function role="capi">mysql_next_result()</function> reads the next statement
- result and returns the status back to the application.
+ <function role="capi">mysql_next_result()</function> reads the
+ next statement result and returns the status back to the
+ application.
</para>
<para>
- Before calling <function role="capi">mysql_next_result()</function>, you must
- call <function role="capi">mysql_free_result()</function> for the preceding
- statement if it is a query that returned a result set.
+ Before calling
+ <function role="capi">mysql_next_result()</function>, you must
+ call <function role="capi">mysql_free_result()</function> for
+ the preceding statement if it is a query that returned a result
+ set.
</para>
<para>
- After calling <function role="capi">mysql_next_result()</function> the state
+ After calling
+ <function role="capi">mysql_next_result()</function> the state
of the connection is as if you had called
<function role="capi">mysql_real_query()</function> or
<function role="capi">mysql_query()</function> for the next
@@ -4937,9 +4948,9 @@
</para>
<para>
- If <function role="capi">mysql_next_result()</function> returns an error, no
- other statements are executed and there are no more results to
- fetch.
+ If <function role="capi">mysql_next_result()</function> returns
+ an error, no other statements are executed and there are no more
+ results to fetch.
</para>
<para>
@@ -4955,8 +4966,8 @@
might be returned by statements executed within the procedure.
In addition, because <literal>CALL</literal> can return multiple
results, you should process those results using a loop that
- calls <function role="capi">mysql_next_result()</function> to determine
- whether there are more results.
+ calls <function role="capi">mysql_next_result()</function> to
+ determine whether there are more results.
</para>
<para>
@@ -5186,21 +5197,23 @@
</para>
<para>
- The use of <function role="capi">mysql_num_rows()</function> depends on
- whether you use
+ The use of <function role="capi">mysql_num_rows()</function>
+ depends on whether you use
<function role="capi">mysql_store_result()</function> or
<function role="capi">mysql_use_result()</function> to return
the result set. If you use
<function role="capi">mysql_store_result()</function>,
- <function role="capi">mysql_num_rows()</function> may be called immediately.
- If you use <function role="capi">mysql_use_result()</function>,
- <function role="capi">mysql_num_rows()</function> does not return the correct
- value until all the rows in the result set have been retrieved.
+ <function role="capi">mysql_num_rows()</function> may be called
+ immediately. If you use
+ <function role="capi">mysql_use_result()</function>,
+ <function role="capi">mysql_num_rows()</function> does not
+ return the correct value until all the rows in the result set
+ have been retrieved.
</para>
<para>
- <function role="capi">mysql_num_rows()</function> is intended for use with
- statements that return a result set, such as
+ <function role="capi">mysql_num_rows()</function> is intended
+ for use with statements that return a result set, such as
<literal>SELECT</literal>. For statements such as
<literal>INSERT</literal>, <literal>UPDATE</literal>, or
<literal>DELETE</literal>, the number of affected rows can be
@@ -6083,7 +6096,8 @@
parameters use whatever character set has been configured
for the <literal>MYSQL</literal> object. By default, this is
<literal>latin1</literal>, but can be changed by calling
- <function role="capi">mysql_options(mysql, MYSQL_SET_CHARSET_NAME,
+ <function role="capi">mysql_options(mysql,
+ MYSQL_SET_CHARSET_NAME,
"<replaceable>charset_name</replaceable>")</function> prior
to connecting.
</para>
@@ -6193,7 +6207,8 @@
<entry>Use SSL (encrypted protocol). This option should not be set by
application programs; it is set internally in the
client library. Instead, use
- <function role="capi">mysql_ssl_set()</function> before calling
+ <function role="capi">mysql_ssl_set()</function>
+ before calling
<function role="capi">mysql_real_connect()</function>.</entry>
</row>
</tbody>
@@ -6222,7 +6237,8 @@
result for every call to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -6528,21 +6544,23 @@
<literal>length*2+1</literal> bytes long. (In the worst case,
each character may need to be encoded as using two bytes, and
you need room for the terminating null byte.) When
- <function role="capi">mysql_real_escape_string()</function> returns, the
- contents of <literal>to</literal> is a null-terminated string.
- The return value is the length of the encoded string, not
- including the terminating null character.
+ <function role="capi">mysql_real_escape_string()</function>
+ returns, the contents of <literal>to</literal> is a
+ null-terminated string. The return value is the length of the
+ encoded string, not including the terminating null character.
</para>
<para>
If you need to change the character set of the connection, you
- should use the <function role="capi">mysql_set_character_set()</function>
+ should use the
+ <function role="capi">mysql_set_character_set()</function>
function rather than executing a <literal>SET NAMES</literal>
(or <literal>SET CHARACTER SET</literal>) statement.
- <function role="capi">mysql_set_character_set()</function> works like
- <literal>SET NAMES</literal> but also affects the character set
- used by <function role="capi">mysql_real_escape_string()</function>, which
- <literal>SET NAMES</literal> does not.
+ <function role="capi">mysql_set_character_set()</function> works
+ like <literal>SET NAMES</literal> but also affects the character
+ set used by
+ <function role="capi">mysql_real_escape_string()</function>,
+ which <literal>SET NAMES</literal> does not.
</para>
<para>
@@ -7043,7 +7061,8 @@
<function role="capi">mysql_row_tell()</function> or from
<function role="capi">mysql_row_seek()</function>. This value is
not a row number; if you want to seek to a row within a result
- set by number, use <function role="capi">mysql_data_seek()</function> instead.
+ set by number, use
+ <function role="capi">mysql_data_seek()</function> instead.
</para>
<para>
@@ -7150,9 +7169,9 @@
</para>
<para>
- <function role="capi">mysql_select_db()</function> fails unless the connected
- user can be authenticated as having permission to use the
- database.
+ <function role="capi">mysql_select_db()</function> fails unless
+ the connected user can be authenticated as having permission to
+ use the database.
</para>
<para>
@@ -7297,14 +7316,15 @@
Sets the <literal>LOAD LOCAL DATA INFILE</literal> handler
callback functions to the defaults used internally by the C
client library. The library calls this function automatically if
- <function role="capi">mysql_set_local_infile_handler()</function> has not been
- called or does not supply valid functions for each of its
- callbacks.
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ has not been called or does not supply valid functions for each
+ of its callbacks.
</para>
<para>
- The <function role="capi">mysql_set_local_infile_default()</function> function
- was added in MySQL 4.1.2.
+ The
+ <function role="capi">mysql_set_local_infile_default()</function>
+ function was added in MySQL 4.1.2.
</para>
<para>
@@ -7352,8 +7372,9 @@
</para>
<para>
- To use <function role="capi">mysql_set_local_infile_handler()</function>, you
- must write the following callback functions:
+ To use
+ <function role="capi">mysql_set_local_infile_handler()</function>,
+ you must write the following callback functions:
</para>
<programlisting>
@@ -7444,10 +7465,10 @@
<para>
After calling
- <function role="capi">mysql_set_local_infile_handler()</function> in your C
- code and passing pointers to your callback functions, you can
- then issue a <literal>LOAD DATA LOCAL INFILE</literal> statement
- (for example, by using
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ in your C code and passing pointers to your callback functions,
+ you can then issue a <literal>LOAD DATA LOCAL INFILE</literal>
+ statement (for example, by using
<function role="capi">mysql_query()</function>). The client
library automatically invokes your callbacks. The filename
specified in <literal>LOAD DATA LOCAL INFILE</literal> will be
@@ -7456,8 +7477,9 @@
</para>
<para>
- The <function role="capi">mysql_set_local_infile_handler()</function> function
- was added in MySQL 4.1.2.
+ The
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ function was added in MySQL 4.1.2.
</para>
<para>
@@ -7522,7 +7544,8 @@
results from calls to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -7592,9 +7615,9 @@
<para>
The server didn't support
- <function role="capi">mysql_set_server_option()</function> (which is the
- case that the server is older than 4.1.1) or the server
- didn't support the option one tried to set.
+ <function role="capi">mysql_set_server_option()</function>
+ (which is the case that the server is older than 4.1.1) or
+ the server didn't support the option one tried to set.
</para>
</listitem>
@@ -7628,8 +7651,9 @@
are planned to make it possible to choose the desired level.
Dynamically linked executables which have been compiled with
older versions of the <literal>libmysqlclient</literal> headers
- and call <function role="capi">mysql_shutdown()</function> need to be used
- with the old <literal>libmysqlclient</literal> dynamic library.
+ and call <function role="capi">mysql_shutdown()</function> need
+ to be used with the old <literal>libmysqlclient</literal>
+ dynamic library.
</para>
<para>
@@ -7792,14 +7816,14 @@
</para>
<para>
- <function role="capi">mysql_ssl_set()</function> is used for establishing
- secure connections using SSL. It must be called before
- <function role="capi">mysql_real_connect()</function>.
+ <function role="capi">mysql_ssl_set()</function> is used for
+ establishing secure connections using SSL. It must be called
+ before <function role="capi">mysql_real_connect()</function>.
</para>
<para>
- <function role="capi">mysql_ssl_set()</function> does nothing unless OpenSSL
- support is enabled in the client library.
+ <function role="capi">mysql_ssl_set()</function> does nothing
+ unless OpenSSL support is enabled in the client library.
</para>
<para>
@@ -7971,8 +7995,8 @@
(<literal>SELECT</literal>, <literal>SHOW</literal>,
<literal>DESCRIBE</literal>, <literal>EXPLAIN</literal>,
<literal>CHECK TABLE</literal>, and so forth). You must also
- call <function role="capi">mysql_free_result()</function> after you are done
- with the result set.
+ call <function role="capi">mysql_free_result()</function> after
+ you are done with the result set.
</para>
<para>
@@ -7993,7 +8017,8 @@
results from calls to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -8039,8 +8064,8 @@
After you have called
<function role="capi">mysql_store_result()</function> and gotten
back a result that isn't a null pointer, you can call
- <function role="capi">mysql_num_rows()</function> to find out how many rows
- are in the result set.
+ <function role="capi">mysql_num_rows()</function> to find out
+ how many rows are in the result set.
</para>
<para>
@@ -8148,15 +8173,16 @@
<para>
Returns the thread ID of the current connection. This value can
- be used as an argument to <function role="capi">mysql_kill()</function> to
- kill the thread.
+ be used as an argument to
+ <function role="capi">mysql_kill()</function> to kill the
+ thread.
</para>
<para>
If the connection is lost and you reconnect with
- <function role="capi">mysql_ping()</function>, the thread ID changes. This
- means you should not get the thread ID and store it for later.
- You should get it when you need it.
+ <function role="capi">mysql_ping()</function>, the thread ID
+ changes. This means you should not get the thread ID and store
+ it for later. You should get it when you need it.
</para>
<para>
@@ -8240,7 +8266,8 @@
</para>
<para>
- You may not use <function role="capi">mysql_data_seek()</function>,
+ You may not use
+ <function role="capi">mysql_data_seek()</function>,
<function role="capi">mysql_row_seek()</function>,
<function role="capi">mysql_row_tell()</function>,
<function role="capi">mysql_num_rows()</function>, or
@@ -8250,12 +8277,13 @@
issue other queries until
<function role="capi">mysql_use_result()</function> has
finished. (However, after you have fetched all the rows,
- <function role="capi">mysql_num_rows()</function> accurately returns the
- number of rows fetched.)
+ <function role="capi">mysql_num_rows()</function> accurately
+ returns the number of rows fetched.)
</para>
<para>
- You must call <function role="capi">mysql_free_result()</function> once you
+ You must call
+ <function role="capi">mysql_free_result()</function> once you
are done with the result set.
</para>
@@ -8391,11 +8419,11 @@
The MySQL client/server protocol provides for the use of prepared
statements. This capability uses the <literal>MYSQL_STMT</literal>
statement handler data structure returned by the
- <function role="capi">mysql_stmt_init()</function> initialization function.
- Prepared execution is an efficient way to execute a statement more
- than once. The statement is first parsed to prepare it for
- execution. Then it is executed one or more times at a later time,
- using the statement handle returned by the initialization
+ <function role="capi">mysql_stmt_init()</function> initialization
+ function. Prepared execution is an efficient way to execute a
+ statement more than once. The statement is first parsed to prepare
+ it for execution. Then it is executed one or more times at a later
+ time, using the statement handle returned by the initialization
function.
</para>
@@ -8506,8 +8534,9 @@
<listitem>
<para>
To prepare a statement, pass the statement string to
- <function role="capi">mysql_stmt_init()</function>, which returns a pointer
- to a <literal>MYSQL_STMT</literal> data structure.
+ <function role="capi">mysql_stmt_init()</function>, which
+ returns a pointer to a <literal>MYSQL_STMT</literal> data
+ structure.
</para>
</listitem>
@@ -8515,9 +8544,10 @@
<para>
To provide input parameters for a prepared statement, set up
<literal>MYSQL_BIND</literal> structures and pass them to
- <function role="capi">mysql_stmt_bind_param()</function>. To receive output
- column values, set up <literal>MYSQL_BIND</literal> structures
- and pass them to <function role="capi">mysql_stmt_bind_result()</function>.
+ <function role="capi">mysql_stmt_bind_param()</function>. To
+ receive output column values, set up
+ <literal>MYSQL_BIND</literal> structures and pass them to
+ <function role="capi">mysql_stmt_bind_result()</function>.
</para>
</listitem>
@@ -8548,12 +8578,13 @@
<para>
This structure represents a prepared statement. A statement is
- created by calling <function role="capi">mysql_stmt_init()</function>, which
+ created by calling
+ <function role="capi">mysql_stmt_init()</function>, which
returns a statement handle (that is, a pointer to a
<literal>MYSQL_STMT</literal>). The handle is used for all
subsequent operations with the statement until you close it
- with <function role="capi">mysql_stmt_close()</function>, at which point the
- handle becomes invalid.
+ with <function role="capi">mysql_stmt_close()</function>, at
+ which point the handle becomes invalid.
</para>
<para>
@@ -8591,8 +8622,8 @@
<listitem>
<para>
For input, <literal>MYSQL_BIND</literal> is used with
- <function role="capi">mysql_stmt_bind_param()</function> to bind
- parameter data values to buffers for use by
+ <function role="capi">mysql_stmt_bind_param()</function>
+ to bind parameter data values to buffers for use by
<function role="capi">mysql_stmt_execute()</function>.
</para>
</listitem>
@@ -8600,8 +8631,8 @@
<listitem>
<para>
For output, <literal>MYSQL_BIND</literal> is used with
- <function role="capi">mysql_stmt_bind_result()</function> to bind result
- set buffers for use in fetching rows with
+ <function role="capi">mysql_stmt_bind_result()</function>
+ to bind result set buffers for use in fetching rows with
<function role="capi">mysql_stmt_fetch()</function>.
</para>
</listitem>
@@ -8662,16 +8693,17 @@
For input, <literal>buffer</literal> is a pointer to the
variable in which a statement parameter's data value is
stored. When you call
- <function role="capi">mysql_stmt_execute()</function>, MySQL takes the
- value that you have stored in the variable and uses it in
- place of the corresponding parameter marker in the
- statement.
+ <function role="capi">mysql_stmt_execute()</function>,
+ MySQL takes the value that you have stored in the variable
+ and uses it in place of the corresponding parameter marker
+ in the statement.
</para>
<para>
For output, <literal>buffer</literal> is a pointer to the
variable in which to return a result set column value.
- When you call <function role="capi">mysql_stmt_fetch()</function>, MySQL
+ When you call
+ <function role="capi">mysql_stmt_fetch()</function>, MySQL
returns a column value and stores it in this variable. You
can access the value when the call returns.
</para>
@@ -8710,9 +8742,10 @@
stored in the buffer. For character and binary C data, the
<literal>buffer_length</literal> value specifies the
length of <literal>*buffer</literal> when used with
- <function role="capi">mysql_stmt_bind_param()</function> to specify
- input values, or the maximum number of output data bytes
- that can be fetched into the buffer when used with
+ <function role="capi">mysql_stmt_bind_param()</function>
+ to specify input values, or the maximum number of output
+ data bytes that can be fetched into the buffer when used
+ with
<function role="capi">mysql_stmt_bind_result()</function>.
</para>
</listitem>
@@ -8740,24 +8773,24 @@
<para>
For output value binding, the return value of
- <function role="capi">mysql_stmt_fetch()</function> determines the
- interpretation of the length:
+ <function role="capi">mysql_stmt_fetch()</function>
+ determines the interpretation of the length:
</para>
<itemizedlist>
<listitem>
<para>
- If <function role="capi">mysql_stmt_fetch()</function> returns 0,
- <literal>*length</literal> indicates the actual length
- of the parameter value.
+ If <function role="capi">mysql_stmt_fetch()</function>
+ returns 0, <literal>*length</literal> indicates the
+ actual length of the parameter value.
</para>
</listitem>
<listitem>
<para>
- If <function role="capi">mysql_stmt_fetch()</function> returns
- <literal>MYSQL_DATA_TRUNCATED</literal>,
+ If <function role="capi">mysql_stmt_fetch()</function>
+ 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
@@ -8906,8 +8939,8 @@
<function role="capi">mysql_options()</function> with the
<literal>MYSQL_REPORT_DATA_TRUNCATION</literal> option.)
When truncation reporting is enabled,
- <function role="capi">mysql_stmt_fetch()</function> returns
- <literal>MYSQL_DATA_TRUNCATED</literal> and
+ <function role="capi">mysql_stmt_fetch()</function>
+ returns <literal>MYSQL_DATA_TRUNCATED</literal> and
<literal>*error</literal> is true in the
<literal>MYSQL_BIND</literal> structures for parameters in
which truncation occurred. Truncation indicates loss of
@@ -9297,11 +9330,12 @@
<literal>'12.345'</literal>. If you specify
<literal>MYSQL_TYPE_NEWDECIMAL</literal> and bind a string
buffer to the <literal>MYSQL_BIND</literal> structure,
- <function role="capi">mysql_stmt_fetch()</function> stores the value in the
- buffer without conversion. If instead you specify a numeric
- variable and type code, <function role="capi">mysql_stmt_fetch()</function>
- converts the string-format <literal>DECIMAL</literal> value to
- numeric form.
+ <function role="capi">mysql_stmt_fetch()</function> stores the
+ value in the buffer without conversion. If instead you specify
+ a numeric variable and type code,
+ <function role="capi">mysql_stmt_fetch()</function> converts
+ the string-format <literal>DECIMAL</literal> value to numeric
+ form.
</para>
</listitem>
@@ -9337,26 +9371,27 @@
check the type codes for each column of the result set. This might
be desirable if you want to determine which variable types would
be best to use to avoid type conversions. To get the type codes,
- call <function role="capi">mysql_stmt_result_metadata()</function> after
- executing the prepared statement with
- <function role="capi">mysql_stmt_execute()</function>. The metadata provides
- access to the type codes for the result set as described in
- <xref linkend="mysql-stmt-result-metadata"/>, and
+ call <function role="capi">mysql_stmt_result_metadata()</function>
+ after executing the prepared statement with
+ <function role="capi">mysql_stmt_execute()</function>. The
+ metadata provides access to the type codes for the result set as
+ described in <xref linkend="mysql-stmt-result-metadata"/>, and
<xref linkend="c-api-datatypes"/>.
</para>
<para>
If you cause the <literal>max_length</literal> member of the
<literal>MYSQL_FIELD</literal> column metadata structures to be
- set (by calling <function role="capi">mysql_stmt_attr_set()</function>), be
- aware that the <literal>max_length</literal> values for the result
- set indicate the lengths of the longest string representation of
- the result values, not the lengths of the binary representation.
- That is, <literal>max_length</literal> does not necessarily
- correspond to the size of the buffers needed to fetch the values
- with the binary protocol used for prepared statements. The size of
- the buffers should be chosen according to the types of the
- variables into which you fetch the values.
+ set (by calling
+ <function role="capi">mysql_stmt_attr_set()</function>), be aware
+ that the <literal>max_length</literal> values for the result set
+ indicate the lengths of the longest string representation of the
+ result values, not the lengths of the binary representation. That
+ is, <literal>max_length</literal> does not necessarily correspond
+ to the size of the buffers needed to fetch the values with the
+ binary protocol used for prepared statements. The size of the
+ buffers should be chosen according to the types of the variables
+ into which you fetch the values.
</para>
<para>
@@ -9514,7 +9549,8 @@
<row>
<entry><function role="capi">mysql_stmt_row_seek()</function></entry>
<entry>Seeks to a row offset in a statement result set, using value returned
- from <function role="capi">mysql_stmt_row_tell()</function></entry>
+ from
+ <function role="capi">mysql_stmt_row_tell()</function></entry>
</row>
<row>
<entry><function role="capi">mysql_stmt_row_tell()</function></entry>
@@ -9537,49 +9573,55 @@
</informaltable>
<para>
- Call <function role="capi">mysql_stmt_init()</function> to create a statement
- handle, then <function role="capi">mysql_stmt_prepare()</function> to prepare it,
- <function role="capi">mysql_stmt_bind_param()</function> to supply the parameter
- data, and <function role="capi">mysql_stmt_execute()</function> to execute the
- statement. You can repeat the
- <function role="capi">mysql_stmt_execute()</function> by changing parameter
- values in the respective buffers supplied through
+ Call <function role="capi">mysql_stmt_init()</function> to create
+ a statement handle, then
+ <function role="capi">mysql_stmt_prepare()</function> to prepare
+ it, <function role="capi">mysql_stmt_bind_param()</function> to
+ supply the parameter data, and
+ <function role="capi">mysql_stmt_execute()</function> to execute
+ the statement. You can repeat the
+ <function role="capi">mysql_stmt_execute()</function> by changing
+ parameter values in the respective buffers supplied through
<function role="capi">mysql_stmt_bind_param()</function>.
</para>
<para>
If the statement is a <literal>SELECT</literal> or any other
statement that produces a result set,
- <function role="capi">mysql_stmt_prepare()</function> also returns the result
- set metadata information in the form of a
+ <function role="capi">mysql_stmt_prepare()</function> also returns
+ the result set metadata information in the form of a
<literal>MYSQL_RES</literal> result set through
<function role="capi">mysql_stmt_result_metadata()</function>.
</para>
<para>
You can supply the result buffers using
- <function role="capi">mysql_stmt_bind_result()</function>, so that the
- <function role="capi">mysql_stmt_fetch()</function> automatically returns data
- to these buffers. This is row-by-row fetching.
+ <function role="capi">mysql_stmt_bind_result()</function>, so that
+ the <function role="capi">mysql_stmt_fetch()</function>
+ automatically returns data to these buffers. This is row-by-row
+ fetching.
</para>
<para>
You can also send the text or binary data in chunks to server
- using <function role="capi">mysql_stmt_send_long_data()</function>. See
+ using
+ <function role="capi">mysql_stmt_send_long_data()</function>. See
<xref linkend="mysql-stmt-send-long-data"/>.
</para>
<para>
When statement execution has been completed, the statement handle
- must be closed using <function role="capi">mysql_stmt_close()</function> so that
- all resources associated with it can be freed.
+ must be closed using
+ <function role="capi">mysql_stmt_close()</function> so that all
+ resources associated with it can be freed.
</para>
<para>
If you obtained a <literal>SELECT</literal> statement's result set
metadata by calling
- <function role="capi">mysql_stmt_result_metadata()</function>, you should also
- free the metadata using <function role="capi">mysql_free_result()</function>.
+ <function role="capi">mysql_stmt_result_metadata()</function>, you
+ should also free the metadata using
+ <function role="capi">mysql_free_result()</function>.
</para>
<para>
@@ -9596,37 +9638,38 @@
<listitem>
<para>
Create a prepared statement handle with
- <function role="capi">mysql_stmt_init()</function>. To prepare the statement
- on the server, call <function role="capi">mysql_stmt_prepare()</function>
- and pass it a string containing the SQL statement.
+ <function role="capi">mysql_stmt_init()</function>. To prepare
+ the statement on the server, call
+ <function role="capi">mysql_stmt_prepare()</function> and pass
+ it a string containing the SQL statement.
</para>
</listitem>
<listitem>
<para>
If the statement produces a result set, call
- <function role="capi">mysql_stmt_result_metadata()</function> to obtain the
- result set metadata. This metadata is itself in the form of
- result set, albeit a separate one from the one that contains
- the rows returned by the query. The metadata result set
- indicates how many columns are in the result and contains
- information about each column.
+ <function role="capi">mysql_stmt_result_metadata()</function>
+ to obtain the result set metadata. This metadata is itself in
+ the form of result set, albeit a separate one from the one
+ that contains the rows returned by the query. The metadata
+ result set indicates how many columns are in the result and
+ contains information about each column.
</para>
</listitem>
<listitem>
<para>
Set the values of any parameters using
- <function role="capi">mysql_stmt_bind_param()</function>. All parameters
- must be set. Otherwise, statement execution returns an error
- or produces unexpected results.
+ <function role="capi">mysql_stmt_bind_param()</function>. All
+ parameters must be set. Otherwise, statement execution returns
+ an error or produces unexpected results.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_execute()</function> to execute the
- statement.
+ Call <function role="capi">mysql_stmt_execute()</function> to
+ execute the statement.
</para>
</listitem>
@@ -9641,8 +9684,8 @@
<listitem>
<para>
Fetch the data into the buffers row by row by calling
- <function role="capi">mysql_stmt_fetch()</function> repeatedly until no more
- rows are found.
+ <function role="capi">mysql_stmt_fetch()</function> repeatedly
+ until no more rows are found.
</para>
</listitem>
@@ -9656,8 +9699,8 @@
</orderedlist>
<para>
- When <function role="capi">mysql_stmt_prepare()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_prepare()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9683,8 +9726,8 @@
</itemizedlist>
<para>
- When <function role="capi">mysql_stmt_execute()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_execute()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9710,8 +9753,8 @@
</itemizedlist>
<para>
- When <function role="capi">mysql_stmt_fetch()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_fetch()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9744,8 +9787,8 @@
<para>
For prepared statements that are executed with the
<function role="capi">mysql_stmt_prepare()</function> and
- <function role="capi">mysql_stmt_execute()</function> C API functions, the
- server writes <literal>Prepare</literal> and
+ <function role="capi">mysql_stmt_execute()</function> C API
+ functions, the server writes <literal>Prepare</literal> and
<literal>Execute</literal> lines to the general query log so that
you can tell when statements are prepared and executed.
</para>
@@ -9758,23 +9801,23 @@
<listitem>
<para>
- Call <function role="capi">mysql_stmt_prepare()</function> to prepare the
- statement string <literal>"SELECT ?"</literal>.
+ Call <function role="capi">mysql_stmt_prepare()</function> to
+ prepare the statement string <literal>"SELECT ?"</literal>.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_bind_param()</function> to bind the
- value <literal>3</literal> to the parameter in the prepared
- statement.
+ Call <function role="capi">mysql_stmt_bind_param()</function>
+ to bind the value <literal>3</literal> to the parameter in the
+ prepared statement.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_execute()</function> to execute the
- prepared statement.
+ Call <function role="capi">mysql_stmt_execute()</function> to
+ execute the prepared statement.
</para>
</listitem>
@@ -9855,8 +9898,8 @@
<literal>UPDATE</literal>, <literal>DELETE</literal>, or
<literal>INSERT</literal> statements. For
<literal>SELECT</literal> statements,
- <function role="capi">mysql_stmt_affected_rows()</function> works like
- <function role="capi">mysql_num_rows()</function>.
+ <function role="capi">mysql_stmt_affected_rows()</function>
+ works like <function role="capi">mysql_num_rows()</function>.
</para>
<para>
@@ -9870,11 +9913,14 @@
matched the <literal>WHERE</literal> clause in the query, or
that no query has yet been executed. -1 indicates that the query
returned an error or that, for a <literal>SELECT</literal>
- query, <function role="capi">mysql_stmt_affected_rows()</function> was called
- prior to calling <function role="capi">mysql_stmt_store_result()</function>.
- Because <function role="capi">mysql_stmt_affected_rows()</function> returns an
- unsigned value, you can check for -1 by comparing the return
- value to <literal>(my_ulonglong)-1</literal> (or to
+ query,
+ <function role="capi">mysql_stmt_affected_rows()</function> was
+ called prior to calling
+ <function role="capi">mysql_stmt_store_result()</function>.
+ Because
+ <function role="capi">mysql_stmt_affected_rows()</function>
+ returns an unsigned value, you can check for -1 by comparing the
+ return value to <literal>(my_ulonglong)-1</literal> (or to
<literal>(my_ulonglong)~0</literal>, which is equivalent).
</para>
@@ -9896,7 +9942,8 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_affected_rows()</function>,
+ For the usage of
+ <function role="capi">mysql_stmt_affected_rows()</function>,
refer to the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
@@ -9939,9 +9986,9 @@
<note>
<para>
In MySQL ¤t-series;,
- <function role="capi">mysql_stmt_attr_get()</function> originally used
- <literal>unsigned int *</literal>, not <literal>my_bool
- *</literal>, for
+ <function role="capi">mysql_stmt_attr_get()</function>
+ originally used <literal>unsigned int *</literal>, not
+ <literal>my_bool *</literal>, for
<literal>STMT_ATTR_UPDATE_MAX_LENGTH</literal>. This was
corrected in MySQL 5.1.7.
</para>
@@ -10022,8 +10069,8 @@
<entry><literal>STMT_ATTR_CURSOR_TYPE</literal></entry>
<entry><literal>unsigned long *</literal></entry>
<entry>Type of cursor to open for statement when
- <function role="capi">mysql_stmt_execute()</function> is invoked.
- <literal>*arg</literal> can be
+ <function role="capi">mysql_stmt_execute()</function> is
+ invoked. <literal>*arg</literal> can be
<literal>CURSOR_TYPE_NO_CURSOR</literal> (the default)
or <literal>CURSOR_TYPE_READ_ONLY</literal>.</entry>
</row>
@@ -10043,21 +10090,21 @@
If you use the <literal>STMT_ATTR_CURSOR_TYPE</literal> option
with <literal>CURSOR_TYPE_READ_ONLY</literal>, a cursor is
opened for the statement when you invoke
- <function role="capi">mysql_stmt_execute()</function>. If there is already an
- open cursor from a previous
- <function role="capi">mysql_stmt_execute()</function> call, it closes the
- cursor before opening a new one.
- <function role="capi">mysql_stmt_reset()</function> also closes any open
- cursor before preparing the statement for re-execution.
- <function role="capi">mysql_stmt_free_result()</function> closes any open
- cursor.
+ <function role="capi">mysql_stmt_execute()</function>. If there
+ is already an open cursor from a previous
+ <function role="capi">mysql_stmt_execute()</function> call, it
+ closes the cursor before opening a new one.
+ <function role="capi">mysql_stmt_reset()</function> also closes
+ any open cursor before preparing the statement for re-execution.
+ <function role="capi">mysql_stmt_free_result()</function> closes
+ any open cursor.
</para>
<para>
If you open a cursor for a prepared statement,
- <function role="capi">mysql_stmt_store_result()</function> is unnecessary,
- because that function causes the result set to be buffered on
- the client side.
+ <function role="capi">mysql_stmt_store_result()</function> is
+ unnecessary, because that function causes the result set to be
+ buffered on the client side.
</para>
<para>
@@ -10121,9 +10168,10 @@
</para>
<para>
- <function role="capi">mysql_stmt_bind_param()</function> is used to bind input
- data for the parameter markers in the SQL statement that was
- passed to <function role="capi">mysql_stmt_prepare()</function>. It uses
+ <function role="capi">mysql_stmt_bind_param()</function> is used
+ to bind input data for the parameter markers in the SQL
+ statement that was passed to
+ <function role="capi">mysql_stmt_prepare()</function>. It uses
<literal>MYSQL_BIND</literal> structures to supply the data.
<literal>bind</literal> is the address of an array of
<literal>MYSQL_BIND</literal> structures. The client library
@@ -10210,8 +10258,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_bind_param()</function>,
- refer to the Example from <xref linkend="mysql-stmt-execute"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_bind_param()</function>, refer
+ to the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
</section>
@@ -10234,44 +10283,47 @@
</para>
<para>
- <function role="capi">mysql_stmt_bind_result()</function> is used to associate
- (that is, bind) output columns in the result set to data buffers
- and length buffers. When <function role="capi">mysql_stmt_fetch()</function>
- is called to fetch data, the MySQL client/server protocol places
- the data for the bound columns into the specified buffers.
+ <function role="capi">mysql_stmt_bind_result()</function> is
+ used to associate (that is, bind) output columns in the result
+ set to data buffers and length buffers. When
+ <function role="capi">mysql_stmt_fetch()</function> is called to
+ fetch data, the MySQL client/server protocol places the data for
+ the bound columns into the specified buffers.
</para>
<para>
All columns must be bound to buffers prior to calling
- <function role="capi">mysql_stmt_fetch()</function>. <literal>bind</literal>
- is the address of an array of <literal>MYSQL_BIND</literal>
- structures. The client library expects the array to contain one
- element for each column of the result set. If you do not bind
- columns to <literal>MYSQL_BIND</literal> structures,
- <function role="capi">mysql_stmt_fetch()</function> simply ignores the data
- fetch. The buffers should be large enough to hold the data
- values, because the protocol doesn't return data values in
- chunks.
+ <function role="capi">mysql_stmt_fetch()</function>.
+ <literal>bind</literal> is the address of an array of
+ <literal>MYSQL_BIND</literal> structures. The client library
+ expects the array to contain one element for each column of the
+ result set. If you do not bind columns to
+ <literal>MYSQL_BIND</literal> structures,
+ <function role="capi">mysql_stmt_fetch()</function> simply
+ ignores the data fetch. The buffers should be large enough to
+ hold the data values, because the protocol doesn't return data
+ values in chunks.
</para>
<para>
A column can be bound or rebound at any time, even after a
result set has been partially retrieved. The new binding takes
- effect the next time <function role="capi">mysql_stmt_fetch()</function> is
- called. Suppose that an application binds the columns in a
- result set and calls <function role="capi">mysql_stmt_fetch()</function>. The
- client/server protocol returns data in the bound buffers. Then
- suppose that the application binds the columns to a different
- set of buffers. The protocol places data into the newly bound
- buffers when the next call to
+ effect the next time
+ <function role="capi">mysql_stmt_fetch()</function> is called.
+ Suppose that an application binds the columns in a result set
+ and calls <function role="capi">mysql_stmt_fetch()</function>.
+ The client/server protocol returns data in the bound buffers.
+ Then suppose that the application binds the columns to a
+ different set of buffers. The protocol places data into the
+ newly bound buffers when the next call to
<function role="capi">mysql_stmt_fetch()</function> occurs.
</para>
<para>
To bind a column, an application calls
- <function role="capi">mysql_stmt_bind_result()</function> and passes the type,
- address, and length of the output buffer into which the value
- should be stored.
+ <function role="capi">mysql_stmt_bind_result()</function> and
+ passes the type, 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.
@@ -10331,8 +10383,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_bind_result()</function>,
- refer to the Example from <xref linkend="mysql-stmt-fetch"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_bind_result()</function>, refer
+ to the Example from <xref linkend="mysql-stmt-fetch"/>.
</para>
</section>
@@ -10355,8 +10408,9 @@
<para>
Closes the prepared statement.
- <function role="capi">mysql_stmt_close()</function> also deallocates the
- statement handle pointed to by <literal>stmt</literal>.
+ <function role="capi">mysql_stmt_close()</function> also
+ deallocates the statement handle pointed to by
+ <literal>stmt</literal>.
</para>
<para>
@@ -10406,7 +10460,8 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_close()</function>, refer to
+ For the usage of
+ <function role="capi">mysql_stmt_close()</function>, refer to
the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
@@ -10439,8 +10494,9 @@
<para>
This function requires that the statement result set structure
contains the entire result of the last executed query, so
- <function role="capi">mysql_stmt_data_seek()</function> may be used only in
- conjunction with <function role="capi">mysql_stmt_store_result()</function>.
+ <function role="capi">mysql_stmt_data_seek()</function> may be
+ used only in conjunction with
+ <function role="capi">mysql_stmt_store_result()</function>.
</para>
<para>
@@ -10589,32 +10645,35 @@
</para>
<para>
- <function role="capi">mysql_stmt_execute()</function> executes the prepared
- query associated with the statement handle. The currently bound
- parameter marker values are sent to server during this call, and
- the server replaces the markers with this newly supplied data.
+ <function role="capi">mysql_stmt_execute()</function> executes
+ the prepared query associated with the statement handle. The
+ currently bound parameter marker values are sent to server
+ during this call, and the server replaces the markers with this
+ newly supplied data.
</para>
<para>
If the statement is an <literal>UPDATE</literal>,
<literal>DELETE</literal>, or <literal>INSERT</literal>, the
total number of changed, deleted, or inserted rows can be found
- by calling <function role="capi">mysql_stmt_affected_rows()</function>. If
+ by calling
+ <function role="capi">mysql_stmt_affected_rows()</function>. If
this is a statement such as <literal>SELECT</literal> that
generates a result set, you must call
- <function role="capi">mysql_stmt_fetch()</function> to fetch the data prior to
- calling any other functions that result in query processing. For
- more information on how to fetch the results, refer to
- <xref linkend="mysql-stmt-fetch"/>.
+ <function role="capi">mysql_stmt_fetch()</function> to fetch the
+ data prior to calling any other functions that result in query
+ processing. For more information on how to fetch the results,
+ refer to <xref linkend="mysql-stmt-fetch"/>.
</para>
<para>
For statements that generate a result set, you can request that
- <function role="capi">mysql_stmt_execute()</function> open a cursor for the
- statement by calling <function role="capi">mysql_stmt_attr_set()</function>
- before executing the statement. If you execute a statement
- multiple times, <function role="capi">mysql_stmt_execute()</function> closes
- any open cursor before opening a new one.
+ <function role="capi">mysql_stmt_execute()</function> open a
+ cursor for the statement by calling
+ <function role="capi">mysql_stmt_attr_set()</function> before
+ executing the statement. If you execute a statement multiple
+ times, <function role="capi">mysql_stmt_execute()</function>
+ closes any open cursor before opening a new one.
</para>
<remark role="note">
@@ -10907,16 +10966,18 @@
</para>
<para>
- <function role="capi">mysql_stmt_fetch()</function> returns the next row in
- the result set. It can be called only while the result set
- exists; that is, after a call to
- <function role="capi">mysql_stmt_execute()</function> for a statement such as
- <literal>SELECT</literal> that creates a result set.
+ <function role="capi">mysql_stmt_fetch()</function> returns the
+ next row in the result set. It can be called only while the
+ result set exists; that is, after a call to
+ <function role="capi">mysql_stmt_execute()</function> for a
+ statement such as <literal>SELECT</literal> that creates a
+ result set.
</para>
<para>
- <function role="capi">mysql_stmt_fetch()</function> returns row data using the
- buffers bound by <function role="capi">mysql_stmt_bind_result()</function>. It
+ <function role="capi">mysql_stmt_fetch()</function> returns row
+ data using the buffers bound by
+ <function role="capi">mysql_stmt_bind_result()</function>. It
returns the data in those buffers for all the columns in the
current row set and the lengths are returned to the
<literal>length</literal> pointer. All columns must be bound by
@@ -10927,8 +10988,8 @@
<para>
By default, result sets are fetched unbuffered a row at a time
from the server. To buffer the entire result set on the client,
- call <function role="capi">mysql_stmt_store_result()</function> after binding
- the data buffers and before caling
+ call <function role="capi">mysql_stmt_store_result()</function>
+ after binding the data buffers and before caling
<function role="capi">mysql_stmt_fetch()</function>.
</para>
@@ -11134,11 +11195,12 @@
<para>
The following example demonstrates how to fetch data from a
- table using <function role="capi">mysql_stmt_result_metadata()</function>,
+ table using
+ <function role="capi">mysql_stmt_result_metadata()</function>,
<function role="capi">mysql_stmt_bind_result()</function>, and
- <function role="capi">mysql_stmt_fetch()</function>. (This example expects to
- retrieve the two rows inserted by the example shown in
- <xref linkend="mysql-stmt-execute"/>.) The
+ <function role="capi">mysql_stmt_fetch()</function>. (This
+ example expects to retrieve the two rows inserted by the example
+ shown in <xref linkend="mysql-stmt-execute"/>.) The
<literal>mysql</literal> variable is assumed to be a valid
connection handle.
</para>
@@ -11331,37 +11393,41 @@
<para>
In some cases you might want to determine the length of a column
value before fetching it with
- <function role="capi">mysql_stmt_fetch()</function>. For example, the value
- might be a long string or <literal>BLOB</literal> value for
- which you want to know how much space must be allocated. To
- accomplish this, you can use these strategies:
+ <function role="capi">mysql_stmt_fetch()</function>. For
+ example, the value might be a long string or
+ <literal>BLOB</literal> value for which you want to know how
+ much space must be allocated. To accomplish this, you can use
+ these strategies:
</para>
<itemizedlist>
<listitem>
<para>
- Before invoking <function role="capi">mysql_stmt_fetch()</function> to
+ Before invoking
+ <function role="capi">mysql_stmt_fetch()</function> to
retrieve individual rows, invoke
- <function role="capi">mysql_stmt_store_result()</function> to buffer the
- entire result on the client side. Then the maximal length of
- column values will be indicated by the
+ <function role="capi">mysql_stmt_store_result()</function>
+ to buffer the entire result on the client side. Then the
+ maximal length of column values will be indicated by the
<literal>max_length</literal> member of the result set
metadata returned by
- <function role="capi">mysql_stmt_result_metadata()</function>. This
- strategy requires that you pass
+ <function role="capi">mysql_stmt_result_metadata()</function>.
+ This strategy requires that you pass
<literal>STMT_ATTR_UPDATE_MAX_LENGTH</literal> to
- <function role="capi">mysql_stmt_attr_set()</function> or the
- <literal>max_length</literal> values will not be calculated.
+ <function role="capi">mysql_stmt_attr_set()</function> or
+ the <literal>max_length</literal> values will not be
+ calculated.
</para>
</listitem>
<listitem>
<para>
- Invoke <function role="capi">mysql_stmt_fetch()</function> with a
- zero-length buffer for the column in question and a pointer
- in which the real length can be stored. Then use the real
- length with <function role="capi">mysql_stmt_fetch_column()</function>.
+ Invoke <function role="capi">mysql_stmt_fetch()</function>
+ with a zero-length buffer for the column in question and a
+ pointer in which the real length can be stored. Then use the
+ real length with
+ <function role="capi">mysql_stmt_fetch_column()</function>.
</para>
<programlisting>
@@ -11481,8 +11547,8 @@
</para>
<para>
- <function role="capi">mysql_stmt_field_count()</function> can be called after
- you have prepared a statement by invoking
+ <function role="capi">mysql_stmt_field_count()</function> can be
+ called after you have prepared a statement by invoking
<function role="capi">mysql_stmt_prepare()</function>.
</para>
@@ -11525,8 +11591,9 @@
<para>
Releases memory associated with the result set produced by
execution of the prepared statement. If there is a cursor open
- for the statement, <function role="capi">mysql_stmt_free_result()</function>
- closes it.
+ for the statement,
+ <function role="capi">mysql_stmt_free_result()</function> closes
+ it.
</para>
<para>
@@ -11562,7 +11629,8 @@
<para>
Create a <literal>MYSQL_STMT</literal> handle. The handle should
- be freed with <function role="capi">mysql_stmt_close(MYSQL_STMT *)</function>.
+ be freed with <function role="capi">mysql_stmt_close(MYSQL_STMT
+ *)</function>.
</para>
<para>
@@ -11676,25 +11744,29 @@
</para>
<para>
- The use of <function role="capi">mysql_stmt_num_rows()</function> depends on
- whether you used <function role="capi">mysql_stmt_store_result()</function> to
+ The use of
+ <function role="capi">mysql_stmt_num_rows()</function> depends
+ on whether you used
+ <function role="capi">mysql_stmt_store_result()</function> to
buffer the entire result set in the statement handle.
</para>
<para>
- If you use <function role="capi">mysql_stmt_store_result()</function>,
- <function role="capi">mysql_stmt_num_rows()</function> may be called
- immediately. Otherwise, the row count is unavailable unless you
- count the rows as you fetch them.
+ If you use
+ <function role="capi">mysql_stmt_store_result()</function>,
+ <function role="capi">mysql_stmt_num_rows()</function> may be
+ called immediately. Otherwise, the row count is unavailable
+ unless you count the rows as you fetch them.
</para>
<para>
- <function role="capi">mysql_stmt_num_rows()</function> is intended for use
- with statements that return a result set, such as
- <literal>SELECT</literal>. For statements such as
+ <function role="capi">mysql_stmt_num_rows()</function> is
+ intended for use with statements that return a result set, such
+ as <literal>SELECT</literal>. For statements such as
<literal>INSERT</literal>, <literal>UPDATE</literal>, or
<literal>DELETE</literal>, the number of affected rows can be
- obtained with <function role="capi">mysql_stmt_affected_rows()</function>.
+ obtained with
+ <function role="capi">mysql_stmt_affected_rows()</function>.
</para>
<para>
@@ -11759,8 +11831,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_param_count()</function>,
- refer to the Example from <xref linkend="mysql-stmt-execute"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_param_count()</function>, refer
+ to the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
</section>
@@ -11815,11 +11888,12 @@
<para>
Given the statement handle returned by
- <function role="capi">mysql_stmt_init()</function>, prepares the SQL statement
- pointed to by the string <literal>stmt_str</literal> and returns
- a status value. The string length should be given by the
- <literal>length</literal> argument. The string must consist of a
- single SQL statement. You should not add a terminating semicolon
+ <function role="capi">mysql_stmt_init()</function>, prepares the
+ SQL statement pointed to by the string
+ <literal>stmt_str</literal> and returns a status value. The
+ string length should be given by the <literal>length</literal>
+ argument. The string must consist of a single SQL statement. You
+ should not add a terminating semicolon
(<quote><literal>;</literal></quote>) or <literal>\g</literal>
to the statement.
</para>
@@ -11848,8 +11922,8 @@
<para>
The parameter markers must be bound to application variables
- using <function role="capi">mysql_stmt_bind_param()</function> before
- executing the statement.
+ using <function role="capi">mysql_stmt_bind_param()</function>
+ before executing the statement.
</para>
<para>
@@ -11921,8 +11995,8 @@
<para>
If the prepare operation was unsuccessful (that is,
- <function role="capi">mysql_stmt_prepare()</function> returns non-zero), the
- error message can be obtained by calling
+ <function role="capi">mysql_stmt_prepare()</function> returns
+ non-zero), the error message can be obtained by calling
<function role="capi">mysql_stmt_error()</function>.
</para>
@@ -11931,8 +12005,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_prepare()</function>, refer
- to the Example from <xref linkend="mysql-stmt-execute"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_prepare()</function>, refer to
+ the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
</section>
@@ -11956,8 +12031,8 @@
<para>
Reset the prepared statement on the client and server to state
after prepare. This is mainly used to reset data sent with
- <function role="capi">mysql_stmt_send_long_data()</function>. Any open cursor
- for the statement is closed.
+ <function role="capi">mysql_stmt_send_long_data()</function>.
+ Any open cursor for the statement is closed.
</para>
<para>
@@ -12042,10 +12117,11 @@
</para>
<para>
- If a statement passed to <function role="capi">mysql_stmt_prepare()</function>
- is one that produces a result set,
- <function role="capi">mysql_stmt_result_metadata()</function> returns the
- result set metadata in the form of a pointer to a
+ If a statement passed to
+ <function role="capi">mysql_stmt_prepare()</function> is one
+ that produces a result set,
+ <function role="capi">mysql_stmt_result_metadata()</function>
+ returns the result set metadata in the form of a pointer to a
<literal>MYSQL_RES</literal> structure that can be used to
process the meta information such as total number of fields and
individual field information. This result set pointer can be
@@ -12108,16 +12184,16 @@
<para>
The result set structure should be freed when you are done with
it, which you can do by passing it to
- <function role="capi">mysql_free_result()</function>. This is similar to the
- way you free a result set obtained from a call to
+ <function role="capi">mysql_free_result()</function>. This is
+ similar to the way you free a result set obtained from a call to
<function role="capi">mysql_store_result()</function>.
</para>
<para>
The result set returned by
- <function role="capi">mysql_stmt_result_metadata()</function> contains only
- metadata. It does not contain any row results. The rows are
- obtained by using the statement handle with
+ <function role="capi">mysql_stmt_result_metadata()</function>
+ contains only metadata. It does not contain any row results. The
+ rows are obtained by using the statement handle with
<function role="capi">mysql_stmt_fetch()</function>.
</para>
@@ -12165,8 +12241,8 @@
<para>
For the usage of
- <function role="capi">mysql_stmt_result_metadata()</function>, refer to the
- Example from <xref linkend="mysql-stmt-fetch"/>.
+ <function role="capi">mysql_stmt_result_metadata()</function>,
+ refer to the Example from <xref linkend="mysql-stmt-fetch"/>.
</para>
</section>
@@ -12193,16 +12269,18 @@
set. The <literal>offset</literal> value is a row offset that
should be a value returned from
<function role="capi">mysql_stmt_row_tell()</function> or from
- <function role="capi">mysql_stmt_row_seek()</function>. This value is not a
- row number; if you want to seek to a row within a result set by
- number, use <function role="capi">mysql_stmt_data_seek()</function> instead.
+ <function role="capi">mysql_stmt_row_seek()</function>. This
+ value is not a row number; if you want to seek to a row within a
+ result set by number, use
+ <function role="capi">mysql_stmt_data_seek()</function> instead.
</para>
<para>
This function requires that the result set structure contains
the entire result of the query, so
- <function role="capi">mysql_stmt_row_seek()</function> may be used only in
- conjunction with <function role="capi">mysql_stmt_store_result()</function>.
+ <function role="capi">mysql_stmt_row_seek()</function> may be
+ used only in conjunction with
+ <function role="capi">mysql_stmt_store_result()</function>.
</para>
<para>
@@ -12244,13 +12322,16 @@
<para>
Returns the current position of the row cursor for the last
- <function role="capi">mysql_stmt_fetch()</function>. This value can be used as
- an argument to <function role="capi">mysql_stmt_row_seek()</function>.
+ <function role="capi">mysql_stmt_fetch()</function>. This value
+ can be used as an argument to
+ <function role="capi">mysql_stmt_row_seek()</function>.
</para>
<para>
- You should use <function role="capi">mysql_stmt_row_tell()</function> only
- after <function role="capi">mysql_stmt_store_result()</function>.
+ You should use
+ <function role="capi">mysql_stmt_row_tell()</function> only
+ after
+ <function role="capi">mysql_stmt_store_result()</function>.
</para>
<para>
@@ -12292,10 +12373,10 @@
<para>
Allows an application to send parameter data to the server in
pieces (or <quote>chunks</quote>). Call this function after
- <function role="capi">mysql_stmt_bind_param()</function> and before
- <function role="capi">mysql_stmt_execute()</function>. It can be called
- multiple times to send the parts of a character or binary data
- value for a column, which must be one of the
+ <function role="capi">mysql_stmt_bind_param()</function> and
+ before <function role="capi">mysql_stmt_execute()</function>. It
+ can be called multiple times to send the parts of a character or
+ binary data value for a column, which must be one of the
<literal>TEXT</literal> or <literal>BLOB</literal> data types.
</para>
@@ -12309,9 +12390,11 @@
<note>
<para>
- The next <function role="capi">mysql_stmt_execute()</function> call ignores
- the bind buffer for all parameters that have been used with
- <function role="capi">mysql_stmt_send_long_data()</function> since last
+ The next <function role="capi">mysql_stmt_execute()</function>
+ call ignores the bind buffer for all parameters that have been
+ used with
+ <function role="capi">mysql_stmt_send_long_data()</function>
+ since last
<function role="capi">mysql_stmt_execute()</function> or
<function role="capi">mysql_stmt_reset()</function>.
</para>
@@ -12530,31 +12613,35 @@
<literal>SHOW</literal>, <literal>DESCRIBE</literal>, and
<literal>EXPLAIN</literal>. By default, result sets for
successfully executed prepared statements are not buffered on
- the client and <function role="capi">mysql_stmt_fetch()</function> fetches
- them one at a time from the server. To cause the complete result
- set to be buffered on the client, call
- <function role="capi">mysql_stmt_store_result()</function> after binding data
- buffers with <function role="capi">mysql_stmt_bind_result()</function> and
- before calling <function role="capi">mysql_stmt_fetch()</function> to fetch
+ the client and
+ <function role="capi">mysql_stmt_fetch()</function> fetches them
+ one at a time from the server. To cause the complete result set
+ to be buffered on the client, call
+ <function role="capi">mysql_stmt_store_result()</function> after
+ binding data buffers with
+ <function role="capi">mysql_stmt_bind_result()</function> and
+ before calling
+ <function role="capi">mysql_stmt_fetch()</function> to fetch
rows. (For an example, see <xref linkend="mysql-stmt-fetch"/>.)
</para>
<para>
- <function role="capi">mysql_stmt_store_result()</function> is optional for
- result set processing, unless you will call
+ <function role="capi">mysql_stmt_store_result()</function> is
+ optional for result set processing, unless you will call
<function role="capi">mysql_stmt_data_seek()</function>,
<function role="capi">mysql_stmt_row_seek()</function>, or
- <function role="capi">mysql_stmt_row_tell()</function>. Those functions
- require a seekable result set.
+ <function role="capi">mysql_stmt_row_tell()</function>. Those
+ functions require a seekable result set.
</para>
<para>
It is unnecessary to call
- <function role="capi">mysql_stmt_store_result()</function> after executing a
- SQL statement that does not produce a result set, but if you do,
- it does not harm or cause any notable performance problem. You
- can detect whether the statement produced a result set by
- checking if <function role="capi">mysql_stmt_result_metadata()</function>
+ <function role="capi">mysql_stmt_store_result()</function> after
+ executing a SQL statement that does not produce a result set,
+ but if you do, it does not harm or cause any notable performance
+ problem. You can detect whether the statement produced a result
+ set by checking if
+ <function role="capi">mysql_stmt_result_metadata()</function>
returns <literal>NULL</literal>. For more information, refer to
<xref linkend="mysql-stmt-result-metadata"/>.
</para>
@@ -12563,12 +12650,13 @@
<para>
MySQL doesn't by default calculate
<literal>MYSQL_FIELD->max_length</literal> for all columns
- in <function role="capi">mysql_stmt_store_result()</function> because
- calculating this would slow down
- <function role="capi">mysql_stmt_store_result()</function> considerably and
- most applications doesn't need <literal>max_length</literal>.
- If you want <literal>max_length</literal> to be updated, you
- can call <function role="capi">mysql_stmt_attr_set(MYSQL_STMT,
+ in <function role="capi">mysql_stmt_store_result()</function>
+ because calculating this would slow down
+ <function role="capi">mysql_stmt_store_result()</function>
+ considerably and most applications doesn't need
+ <literal>max_length</literal>. If you want
+ <literal>max_length</literal> to be updated, you can call
+ <function role="capi">mysql_stmt_attr_set(MYSQL_STMT,
STMT_ATTR_UPDATE_MAX_LENGTH, &flag)</function> to enable
this. See <xref linkend="mysql-stmt-attr-set"/>.
</para>
@@ -12740,11 +12828,11 @@
check whether more results exist and process them in turn if so.
To support multiple-result processing, the C API includes the
<function role="capi">mysql_more_results()</function> and
- <function role="capi">mysql_next_result()</function> functions. Generally, these
- functions are used at the end of a loop that iterates as long as
- more results are available. <emphasis>Failure to process the
- result this way may result in a dropped connection to the
- server.</emphasis>
+ <function role="capi">mysql_next_result()</function> functions.
+ Generally, these functions are used at the end of a loop that
+ iterates as long as more results are available. <emphasis>Failure
+ to process the result this way may result in a dropped connection
+ to the server.</emphasis>
</para>
<para>
@@ -12821,7 +12909,8 @@
<listitem>
<para>
After the connection to the server has been established, you
- can use the <function role="capi">mysql_set_server_option()</function>
+ can use the
+ <function role="capi">mysql_set_server_option()</function>
function to enable or disable multiple-statement execution by
passing it an argument of
<literal>MYSQL_OPTION_MULTI_STATEMENTS_ON</literal> or
@@ -12873,9 +12962,9 @@
<listitem>
<para>
At the end of the loop, call
- <function role="capi">mysql_next_result()</function> to check whether
- another result exists and initiate retrieval for it if so. If
- no more results are available, exit the loop.
+ <function role="capi">mysql_next_result()</function> to check
+ whether another result exists and initiate retrieval for it if
+ so. If no more results are available, exit the loop.
</para>
</listitem>
@@ -12944,10 +13033,10 @@
<para>
The final part of the loop can be reduced to a simple test of
- whether <function role="capi">mysql_next_result()</function> returns non-zero.
- The code as written distinguishes between no more results and an
- error, which allows a message to be printed for the latter
- occurrence.
+ whether <function role="capi">mysql_next_result()</function>
+ returns non-zero. The code as written distinguishes between no
+ more results and an error, which allows a message to be printed
+ for the latter occurrence.
</para>
</section>
@@ -12968,9 +13057,11 @@
<para>
To send temporal data values, create a prepared statement using
- <function role="capi">mysql_stmt_prepare()</function>. Then, before calling
- <function role="capi">mysql_stmt_execute()</function> to execute the statement,
- use the following procedure to set up each temporal parameter:
+ <function role="capi">mysql_stmt_prepare()</function>. Then,
+ before calling
+ <function role="capi">mysql_stmt_execute()</function> to execute
+ the statement, use the following procedure to set up each temporal
+ parameter:
</para>
<orderedlist>
@@ -13010,8 +13101,8 @@
</orderedlist>
<para>
- Use <function role="capi">mysql_stmt_bind_param()</function> to bind the
- parameter data to the statement. Then you can call
+ Use <function role="capi">mysql_stmt_bind_param()</function> to
+ bind the parameter data to the statement. Then you can call
<function role="capi">mysql_stmt_execute()</function>.
</para>
@@ -13021,9 +13112,10 @@
value you expect to receive, and the <literal>buffer</literal>
member to the address of a <literal>MYSQL_TIME</literal> structure
into which the returned value should be placed. Use
- <function role="capi">mysql_stmt_bind_result()</function> to bind the buffers to the
- statement after calling <function role="capi">mysql_stmt_execute()</function>
- and before fetching the results.
+ <function role="capi">mysql_stmt_bind_result()</function> to bind
+ the buffers to the statement after calling
+ <function role="capi">mysql_stmt_execute()</function> and before
+ fetching the results.
</para>
<para>
@@ -13465,8 +13557,8 @@
<listitem>
<para>
- <function role="capi">mysql_ping()</function> does not attempt a
- reconnection if the connection is down. It returns an error
+ <function role="capi">mysql_ping()</function> does not attempt
+ a reconnection if the connection is down. It returns an error
instead.
</para>
</listitem>
@@ -13590,15 +13682,16 @@
<listitem>
<para>
- <function role="capi">mysql_num_rows()</function> returns the number of
- rows in a result set. With
+ <function role="capi">mysql_num_rows()</function> returns
+ the number of rows in a result set. With
<function role="capi">mysql_store_result()</function>,
- <function role="capi">mysql_num_rows()</function> may be called as soon as
+ <function role="capi">mysql_num_rows()</function> may be
+ called as soon as
<function role="capi">mysql_store_result()</function>
returns. With
<function role="capi">mysql_use_result()</function>,
- <function role="capi">mysql_num_rows()</function> may be called only after
- you have fetched all the rows with
+ <function role="capi">mysql_num_rows()</function> may be
+ called only after you have fetched all the rows with
<function role="capi">mysql_fetch_row()</function>.
</para>
</listitem>
@@ -14030,11 +14123,12 @@
<listitem>
<para>
- If you use <function role="capi">mysql_use_result()</function>,
- you must ensure that no other thread is using the same
- connection until the result set is closed. However, it really
- is best for threaded clients that share the same connection to
- use <function role="capi">mysql_store_result()</function>.
+ If you use
+ <function role="capi">mysql_use_result()</function>, you must
+ ensure that no other thread is using the same connection until
+ the result set is closed. However, it really is best for
+ threaded clients that share the same connection to use
+ <function role="capi">mysql_store_result()</function>.
</para>
</listitem>
Modified: trunk/refman-5.1/dba-core.xml
===================================================================
--- trunk/refman-5.1/dba-core.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.1/dba-core.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 4, Lines Added: 17, Lines Deleted: 12; 3247 bytes
@@ -17436,7 +17436,8 @@
<listitem>
<para>
MySQL C API: Use the
- <function role="capi">mysql_real_escape_string()</function> API call.
+ <function role="capi">mysql_real_escape_string()</function>
+ API call.
</para>
</listitem>
@@ -18218,7 +18219,8 @@
<command>configure</command> with the
<option>--enable-local-infile</option> option, <literal>LOAD
DATA LOCAL</literal> cannot be used by any client unless it
- is written explicitly to invoke <function role="capi">mysql_options(...
+ is written explicitly to invoke
+ <function role="capi">mysql_options(...
MYSQL_OPT_LOCAL_INFILE, 0)</function>. See
<xref linkend="mysql-options"/>.
</para>
@@ -24046,16 +24048,17 @@
<para>
To establish a secure connection from within an application
- program, use the <function role="capi">mysql_ssl_set()</function> C API
+ program, use the
+ <function role="capi">mysql_ssl_set()</function> C API
function to set the appropriate certificate options before
calling <function role="capi">mysql_real_connect()</function>.
See <xref linkend="mysql-ssl-set"/>. After the connection is
established, you can use
- <function role="capi">mysql_get_ssl_cipher()</function> to determine whether
- SSL is in use. A non-<literal>NULL</literal> return value
- indicates a secure connection and names the SSL cipher used
- for encryption. A <literal>NULL</literal> return value
- indicates that SSL is not being used. See
+ <function role="capi">mysql_get_ssl_cipher()</function> to
+ determine whether SSL is in use. A non-<literal>NULL</literal>
+ return value indicates a secure connection and names the SSL
+ cipher used for encryption. A <literal>NULL</literal> return
+ value indicates that SSL is not being used. See
<xref linkend="mysql-get-ssl-cipher"/>.
</para>
@@ -27200,10 +27203,12 @@
</para>
<para>
- You should use <function role="capi">mysql_real_escape_string()</function>
- when escaping strings for an SQL query.
- <function role="capi">mysql_real_escape_string()</function> is identical to
- the old <function role="capi">mysql_escape_string()</function> function,
+ You should use
+ <function role="capi">mysql_real_escape_string()</function> when
+ escaping strings for an SQL query.
+ <function role="capi">mysql_real_escape_string()</function> is
+ identical to the old
+ <function role="capi">mysql_escape_string()</function> function,
except that it takes the <literal>MYSQL</literal> connection
handle as the first parameter so that the appropriate character
set can be taken into account when escaping characters.
Modified: trunk/refman-5.1/errors-problems-core.xml
===================================================================
--- trunk/refman-5.1/errors-problems-core.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.1/errors-problems-core.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 4, Lines Added: 16, Lines Deleted: 13; 2904 bytes
@@ -1044,9 +1044,9 @@
If not, correct the query and try again. Otherwise, you can
invoke <command>mysql</command> with the
<option>--quick</option> option. This causes it to use the
- <function role="capi">mysql_use_result()</function> C API function to
- retrieve the result set, which places less of a load on the
- client (but more on the server).
+ <function role="capi">mysql_use_result()</function> C API
+ function to retrieve the result set, which places less of a
+ load on the client (but more on the server).
</para>
</section>
@@ -1192,9 +1192,9 @@
<para>
The solution to this is to either do a
- <function role="capi">mysql_ping()</function> on the connection if there
- has been a long time since the last query (this is what
- <literal>MyODBC</literal> does) or set
+ <function role="capi">mysql_ping()</function> on the
+ connection if there has been a long time since the last
+ query (this is what <literal>MyODBC</literal> does) or set
<literal>wait_timeout</literal> on the
<command>mysqld</command> server so high that it in
practice never times out.
@@ -1483,7 +1483,8 @@
<listitem>
<para>
The client program did not call
- <function role="capi">mysql_close()</function> before exiting.
+ <function role="capi">mysql_close()</function> before
+ exiting.
</para>
</listitem>
@@ -1975,12 +1976,14 @@
<para>
This can happen, for example, if you are using
- <function role="capi">mysql_use_result()</function> and try to execute a new
- query before you have called
- <function role="capi">mysql_free_result()</function>. It can also happen if
- you try to execute two queries that return data without
- calling <function role="capi">mysql_use_result()</function> or
- <function role="capi">mysql_store_result()</function> in between.
+ <function role="capi">mysql_use_result()</function> and try to
+ execute a new query before you have called
+ <function role="capi">mysql_free_result()</function>. It can
+ also happen if you try to execute two queries that return data
+ without calling
+ <function role="capi">mysql_use_result()</function> or
+ <function role="capi">mysql_store_result()</function> in
+ between.
</para>
</section>
Modified: trunk/refman-5.1/extending-mysql.xml
===================================================================
--- trunk/refman-5.1/extending-mysql.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.1/extending-mysql.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 4, Lines Deleted: 4; 1063 bytes
@@ -1478,10 +1478,10 @@
Parser flags. This is zero if there are no special flags.
Currently, the only non-zero flag is
<literal>MYSQL_FTFLAGS_NEED_COPY</literal>, which means
- that <function>mysql_add_word()</function> must save a copy
- of the word (that is, it cannot use a pointer to the word
- because the word is in a buffer that will be overwritten.)
- This member was added in MySQL 5.1.12.
+ that <function>mysql_add_word()</function> must save a
+ copy of the word (that is, it cannot use a pointer to the
+ word because the word is in a buffer that will be
+ overwritten.) This member was added in MySQL 5.1.12.
</para>
<para>
Modified: trunk/refman-5.1/mysql-cluster-configuration.xml
===================================================================
--- trunk/refman-5.1/mysql-cluster-configuration.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.1/mysql-cluster-configuration.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 1, Lines Deleted: 1; 777 bytes
@@ -4206,7 +4206,7 @@
issued in the management client during a backup, as well as
how often such reports are written to the cluster log
(provided cluster event logging is configured to allow it
- — see
+ — see
<xref linkend="mysql-cluster-logging-and-checkpointing"/>).
<literal>BackupReportFrequency</literal> represents the time
in seconds between backup status reports.
Modified: trunk/refman-5.1/replication-solutions.xml
===================================================================
--- trunk/refman-5.1/replication-solutions.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.1/replication-solutions.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 3, Lines Added: 9, Lines Deleted: 8; 1866 bytes
@@ -15,8 +15,8 @@
<para>
For information on using replication in a backup environment,
- including notes on the setup, backup procedure, and files to back up,
- see <xref linkend="replication-solutions-backups"/>.
+ including notes on the setup, backup procedure, and files to back
+ up, see <xref linkend="replication-solutions-backups"/>.
</para>
<para>
@@ -65,8 +65,8 @@
<para>
You can use replication as a backup solution by replicating data
from the master to a slave, and then backing up the data slave.
- Because the slave can be paused and shut down without affecting the
- running operation of the master you can produce an effective
+ Because the slave can be paused and shut down without affecting
+ the running operation of the master you can produce an effective
snapshot of 'live' data that would otherwise require a shutdown of
the master database.
</para>
@@ -79,10 +79,11 @@
</para>
<para>
- If you are using replication as a solution to enable you to back up
- the data on the master, and the size of your database is not too
- large, then the <literal>mysqldump</literal> tool may be suitable.
- See <xref linkend="replication-solutions-backups-mysqldump"/>.
+ If you are using replication as a solution to enable you to back
+ up the data on the master, and the size of your database is not
+ too large, then the <literal>mysqldump</literal> tool may be
+ suitable. See
+ <xref linkend="replication-solutions-backups-mysqldump"/>.
</para>
<para>
Modified: trunk/refman-5.1/restrictions.xml
===================================================================
--- trunk/refman-5.1/restrictions.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.1/restrictions.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 2, Lines Deleted: 2; 845 bytes
@@ -358,8 +358,8 @@
<para>
Server-side cursors are implemented in the C API via the
- <function role="capi">mysql_stmt_attr_set()</function> function. The same
- implementation is used for cursors in stored routines. A
+ <function role="capi">mysql_stmt_attr_set()</function> function.
+ The same implementation is used for cursors in stored routines. A
server-side cursor allows a result set to be generated on the
server side, but not transferred to the client except for those
rows that the client requests. For example, if a client executes a
Modified: trunk/refman-5.1/se-federated.xml
===================================================================
--- trunk/refman-5.1/se-federated.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.1/se-federated.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 4, Lines Deleted: 3; 902 bytes
@@ -173,9 +173,10 @@
<para>
The local server communicates with the remote server using MySQL
client C API functions. It invokes
- <function role="capi">mysql_real_query()</function> to send the statement. To
- read a result set, it uses <function role="capi">mysql_store_result()</function>
- and fetches rows one at a time using
+ <function role="capi">mysql_real_query()</function> to send the
+ statement. To read a result set, it uses
+ <function role="capi">mysql_store_result()</function> and fetches
+ rows one at a time using
<function role="capi">mysql_fetch_row()</function>.
</para>
Modified: trunk/refman-5.1/sql-syntax.xml
===================================================================
--- trunk/refman-5.1/sql-syntax.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.1/sql-syntax.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 4, Lines Deleted: 3; 861 bytes
@@ -26376,9 +26376,10 @@
<para>
SQL syntax for prepared statements is distinct from using prepared
statement API calls. For example, you cannot use the
- <function role="capi">mysql_stmt_prepare()</function> C API function to prepare
- a <literal>PREPARE</literal>, <literal>EXECUTE</literal>, or
- <literal>DEALLOCATE PREPARE</literal> statement.
+ <function role="capi">mysql_stmt_prepare()</function> C API
+ function to prepare a <literal>PREPARE</literal>,
+ <literal>EXECUTE</literal>, or <literal>DEALLOCATE
+ PREPARE</literal> statement.
</para>
<para>
Modified: trunk/refman-5.1/stored-procedures.xml
===================================================================
--- trunk/refman-5.1/stored-procedures.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-5.1/stored-procedures.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 1, Lines Added: 2, Lines Deleted: 1; 803 bytes
@@ -1016,7 +1016,8 @@
the result sets returned by statements executed within the
procedure, as well as a result to indicate the call status. To
process the result of a <literal>CALL</literal> statement, use a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
Modified: trunk/refman-6.0/apis-c.xml
===================================================================
--- trunk/refman-6.0/apis-c.xml 2007-11-04 02:03:47 UTC (rev 8524)
+++ trunk/refman-6.0/apis-c.xml 2007-11-04 02:04:16 UTC (rev 8525)
Changed blocks: 107, Lines Added: 524, Lines Deleted: 430; 87764 bytes
@@ -1312,8 +1312,8 @@
<para>
After you are done with a result set, call
- <function role="capi">mysql_free_result()</function> to free the memory used for
- it.
+ <function role="capi">mysql_free_result()</function> to free the
+ memory used for it.
</para>
<para>
@@ -1329,12 +1329,13 @@
<function role="capi">mysql_store_result()</function> is that
because the rows have all been fetched to the client, you not only
can access rows sequentially, you can move back and forth in the
- result set using <function role="capi">mysql_data_seek()</function> or
+ result set using
+ <function role="capi">mysql_data_seek()</function> or
<function role="capi">mysql_row_seek()</function> to change the
current row position within the result set. You can also find out
how many rows there are by calling
- <function role="capi">mysql_num_rows()</function>. On the other hand, the memory
- requirements for
+ <function role="capi">mysql_num_rows()</function>. On the other
+ hand, the memory requirements for
<function role="capi">mysql_store_result()</function> may be very
high for large result sets and you are more likely to encounter
out-of-memory conditions.
@@ -2098,8 +2099,8 @@
<para>
This function requires that the result set structure contains
the entire result of the query, so
- <function role="capi">mysql_data_seek()</function> may be used only in
- conjunction with
+ <function role="capi">mysql_data_seek()</function> may be used
+ only in conjunction with
<function role="capi">mysql_store_result()</function>, not with
<function role="capi">mysql_use_result()</function>.
</para>
@@ -2140,9 +2141,9 @@
<para>
Does a <literal>DBUG_PUSH</literal> with the given string.
- <function role="capi">mysql_debug()</function> uses the Fred Fish debug
- library. To use this function, you must compile the client
- library to support debugging. See
+ <function role="capi">mysql_debug()</function> uses the Fred
+ Fish debug library. To use this function, you must compile the
+ client library to support debugging. See
<ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
Internals: Porting</ulink>.
</para>
@@ -2655,19 +2656,21 @@
</indexterm>
<para>
- You should use <function role="capi">mysql_real_escape_string()</function>
+ You should use
+ <function role="capi">mysql_real_escape_string()</function>
instead!
</para>
<para>
This function is identical to
- <function role="capi">mysql_real_escape_string()</function> except that
- <function role="capi">mysql_real_escape_string()</function> takes a connection
- handler as its first argument and escapes the string according
- to the current character set.
- <function role="capi">mysql_escape_string()</function> does not take a
- connection argument and does not respect the current character
- set.
+ <function role="capi">mysql_real_escape_string()</function>
+ except that
+ <function role="capi">mysql_real_escape_string()</function>
+ takes a connection handler as its first argument and escapes the
+ string according to the current character set.
+ <function role="capi">mysql_escape_string()</function> does not
+ take a connection argument and does not respect the current
+ character set.
</para>
</section>
@@ -2775,7 +2778,8 @@
<literal>MYSQL_FIELD</literal> structure. You may use this
function to retrieve the definition for an arbitrary column. The
value of <literal>fieldnr</literal> should be in the range from
- 0 to <function role="capi">mysql_num_fields(result)-1</function>.
+ 0 to
+ <function role="capi">mysql_num_fields(result)-1</function>.
</para>
<para>
@@ -3289,9 +3293,10 @@
Frees the memory allocated for a result set by
<function role="capi">mysql_store_result()</function>,
<function role="capi">mysql_use_result()</function>,
- <function role="capi">mysql_list_dbs()</function>, and so forth. When you are
- done with a result set, you must free the memory it uses by
- calling <function role="capi">mysql_free_result()</function>.
+ <function role="capi">mysql_list_dbs()</function>, and so forth.
+ When you are done with a result set, you must free the memory it
+ uses by calling
+ <function role="capi">mysql_free_result()</function>.
</para>
<para>
@@ -3336,7 +3341,8 @@
<para>
This function provides information about the default client
character set. The default character set may be changed with the
- <function role="capi">mysql_set_character_set()</function> function.
+ <function role="capi">mysql_set_character_set()</function>
+ function.
</para>
<para>
@@ -3639,8 +3645,8 @@
</para>
<para>
- <function role="capi">mysql_get_ssl_cipher()</function> returns the SSL cipher
- used for the given connection to the server.
+ <function role="capi">mysql_get_ssl_cipher()</function> returns
+ the SSL cipher used for the given connection to the server.
<literal>mysql</literal> is the connection handler returned from
<function role="capi">mysql_init()</function>.
</para>
@@ -3690,10 +3696,10 @@
<literal>length</literal> bytes long. You must allocate the
<literal>to</literal> buffer to be at least
<literal>length*2+1</literal> bytes long. When
- <function role="capi">mysql_hex_string()</function> returns, the contents of
- <literal>to</literal> is a null-terminated string. The return
- value is the length of the encoded string, not including the
- terminating null character.
+ <function role="capi">mysql_hex_string()</function> returns, the
+ contents of <literal>to</literal> is a null-terminated string.
+ The return value is the length of the encoded string, not
+ including the terminating null character.
</para>
<para>
@@ -4424,8 +4430,8 @@
<quote><literal>%</literal></quote> or
<quote><literal>_</literal></quote>, or may be a
<literal>NULL</literal> pointer to match all databases. Calling
- <function role="capi">mysql_list_dbs()</function> is similar to executing the
- query <literal>SHOW databases [LIKE
+ <function role="capi">mysql_list_dbs()</function> is similar to
+ executing the query <literal>SHOW databases [LIKE
<replaceable>wild</replaceable>]</literal>.
</para>
@@ -4528,8 +4534,8 @@
<quote><literal>%</literal></quote> or
<quote><literal>_</literal></quote>, or may be a
<literal>NULL</literal> pointer to match all fields. Calling
- <function role="capi">mysql_list_fields()</function> is similar to executing
- the query <literal>SHOW COLUMNS FROM
+ <function role="capi">mysql_list_fields()</function> is similar
+ to executing the query <literal>SHOW COLUMNS FROM
<replaceable>tbl_name</replaceable> [LIKE
<replaceable>wild</replaceable>]</literal>.
</para>
@@ -4716,8 +4722,8 @@
<quote><literal>%</literal></quote> or
<quote><literal>_</literal></quote>, or may be a
<literal>NULL</literal> pointer to match all tables. Calling
- <function role="capi">mysql_list_tables()</function> is similar to executing
- the query <literal>SHOW tables [LIKE
+ <function role="capi">mysql_list_tables()</function> is similar
+ to executing the query <literal>SHOW tables [LIKE
<replaceable>wild</replaceable>]</literal>.
</para>
@@ -4809,10 +4815,11 @@
</para>
<para>
- <function role="capi">mysql_more_results()</function> true if more results
- exist from the currently executed statement, in which case the
- application must call <function role="capi">mysql_next_result()</function> to
- fetch the results.
+ <function role="capi">mysql_more_results()</function> true if
+ more results exist from the currently executed statement, in
+ which case the application must call
+ <function role="capi">mysql_next_result()</function> to fetch
+ the results.
</para>
<para>
@@ -4826,8 +4833,8 @@
<para>
In most cases, you can call
- <function role="capi">mysql_next_result()</function> instead to test whether
- more results exist and initiate retrieval if so.
+ <function role="capi">mysql_next_result()</function> instead to
+ test whether more results exist and initiate retrieval if so.
</para>
<para>
@@ -4870,18 +4877,22 @@
<para>
If more statement results exist,
- <function role="capi">mysql_next_result()</function> reads the next statement
- result and returns the status back to the application.
+ <function role="capi">mysql_next_result()</function> reads the
+ next statement result and returns the status back to the
+ application.
</para>
<para>
- Before calling <function role="capi">mysql_next_result()</function>, you must
- call <function role="capi">mysql_free_result()</function> for the preceding
- statement if it is a query that returned a result set.
+ Before calling
+ <function role="capi">mysql_next_result()</function>, you must
+ call <function role="capi">mysql_free_result()</function> for
+ the preceding statement if it is a query that returned a result
+ set.
</para>
<para>
- After calling <function role="capi">mysql_next_result()</function> the state
+ After calling
+ <function role="capi">mysql_next_result()</function> the state
of the connection is as if you had called
<function role="capi">mysql_real_query()</function> or
<function role="capi">mysql_query()</function> for the next
@@ -4893,9 +4904,9 @@
</para>
<para>
- If <function role="capi">mysql_next_result()</function> returns an error, no
- other statements are executed and there are no more results to
- fetch.
+ If <function role="capi">mysql_next_result()</function> returns
+ an error, no other statements are executed and there are no more
+ results to fetch.
</para>
<para>
@@ -4911,8 +4922,8 @@
might be returned by statements executed within the procedure.
In addition, because <literal>CALL</literal> can return multiple
results, you should process those results using a loop that
- calls <function role="capi">mysql_next_result()</function> to determine
- whether there are more results.
+ calls <function role="capi">mysql_next_result()</function> to
+ determine whether there are more results.
</para>
<para>
@@ -5142,21 +5153,23 @@
</para>
<para>
- The use of <function role="capi">mysql_num_rows()</function> depends on
- whether you use
+ The use of <function role="capi">mysql_num_rows()</function>
+ depends on whether you use
<function role="capi">mysql_store_result()</function> or
<function role="capi">mysql_use_result()</function> to return
the result set. If you use
<function role="capi">mysql_store_result()</function>,
- <function role="capi">mysql_num_rows()</function> may be called immediately.
- If you use <function role="capi">mysql_use_result()</function>,
- <function role="capi">mysql_num_rows()</function> does not return the correct
- value until all the rows in the result set have been retrieved.
+ <function role="capi">mysql_num_rows()</function> may be called
+ immediately. If you use
+ <function role="capi">mysql_use_result()</function>,
+ <function role="capi">mysql_num_rows()</function> does not
+ return the correct value until all the rows in the result set
+ have been retrieved.
</para>
<para>
- <function role="capi">mysql_num_rows()</function> is intended for use with
- statements that return a result set, such as
+ <function role="capi">mysql_num_rows()</function> is intended
+ for use with statements that return a result set, such as
<literal>SELECT</literal>. For statements such as
<literal>INSERT</literal>, <literal>UPDATE</literal>, or
<literal>DELETE</literal>, the number of affected rows can be
@@ -6022,7 +6035,8 @@
parameters use whatever character set has been configured
for the <literal>MYSQL</literal> object. By default, this is
<literal>latin1</literal>, but can be changed by calling
- <function role="capi">mysql_options(mysql, MYSQL_SET_CHARSET_NAME,
+ <function role="capi">mysql_options(mysql,
+ MYSQL_SET_CHARSET_NAME,
"<replaceable>charset_name</replaceable>")</function> prior
to connecting.
</para>
@@ -6132,7 +6146,8 @@
<entry>Use SSL (encrypted protocol). This option should not be set by
application programs; it is set internally in the
client library. Instead, use
- <function role="capi">mysql_ssl_set()</function> before calling
+ <function role="capi">mysql_ssl_set()</function>
+ before calling
<function role="capi">mysql_real_connect()</function>.</entry>
</row>
</tbody>
@@ -6161,7 +6176,8 @@
result for every call to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -6467,21 +6483,23 @@
<literal>length*2+1</literal> bytes long. (In the worst case,
each character may need to be encoded as using two bytes, and
you need room for the terminating null byte.) When
- <function role="capi">mysql_real_escape_string()</function> returns, the
- contents of <literal>to</literal> is a null-terminated string.
- The return value is the length of the encoded string, not
- including the terminating null character.
+ <function role="capi">mysql_real_escape_string()</function>
+ returns, the contents of <literal>to</literal> is a
+ null-terminated string. The return value is the length of the
+ encoded string, not including the terminating null character.
</para>
<para>
If you need to change the character set of the connection, you
- should use the <function role="capi">mysql_set_character_set()</function>
+ should use the
+ <function role="capi">mysql_set_character_set()</function>
function rather than executing a <literal>SET NAMES</literal>
(or <literal>SET CHARACTER SET</literal>) statement.
- <function role="capi">mysql_set_character_set()</function> works like
- <literal>SET NAMES</literal> but also affects the character set
- used by <function role="capi">mysql_real_escape_string()</function>, which
- <literal>SET NAMES</literal> does not.
+ <function role="capi">mysql_set_character_set()</function> works
+ like <literal>SET NAMES</literal> but also affects the character
+ set used by
+ <function role="capi">mysql_real_escape_string()</function>,
+ which <literal>SET NAMES</literal> does not.
</para>
<para>
@@ -6986,7 +7004,8 @@
<function role="capi">mysql_row_tell()</function> or from
<function role="capi">mysql_row_seek()</function>. This value is
not a row number; if you want to seek to a row within a result
- set by number, use <function role="capi">mysql_data_seek()</function> instead.
+ set by number, use
+ <function role="capi">mysql_data_seek()</function> instead.
</para>
<para>
@@ -7093,9 +7112,9 @@
</para>
<para>
- <function role="capi">mysql_select_db()</function> fails unless the connected
- user can be authenticated as having permission to use the
- database.
+ <function role="capi">mysql_select_db()</function> fails unless
+ the connected user can be authenticated as having permission to
+ use the database.
</para>
<para>
@@ -7240,14 +7259,15 @@
Sets the <literal>LOAD LOCAL DATA INFILE</literal> handler
callback functions to the defaults used internally by the C
client library. The library calls this function automatically if
- <function role="capi">mysql_set_local_infile_handler()</function> has not been
- called or does not supply valid functions for each of its
- callbacks.
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ has not been called or does not supply valid functions for each
+ of its callbacks.
</para>
<para>
- The <function role="capi">mysql_set_local_infile_default()</function> function
- was added in MySQL 4.1.2.
+ The
+ <function role="capi">mysql_set_local_infile_default()</function>
+ function was added in MySQL 4.1.2.
</para>
<para>
@@ -7295,8 +7315,9 @@
</para>
<para>
- To use <function role="capi">mysql_set_local_infile_handler()</function>, you
- must write the following callback functions:
+ To use
+ <function role="capi">mysql_set_local_infile_handler()</function>,
+ you must write the following callback functions:
</para>
<programlisting>
@@ -7387,10 +7408,10 @@
<para>
After calling
- <function role="capi">mysql_set_local_infile_handler()</function> in your C
- code and passing pointers to your callback functions, you can
- then issue a <literal>LOAD DATA LOCAL INFILE</literal> statement
- (for example, by using
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ in your C code and passing pointers to your callback functions,
+ you can then issue a <literal>LOAD DATA LOCAL INFILE</literal>
+ statement (for example, by using
<function role="capi">mysql_query()</function>). The client
library automatically invokes your callbacks. The filename
specified in <literal>LOAD DATA LOCAL INFILE</literal> will be
@@ -7399,8 +7420,9 @@
</para>
<para>
- The <function role="capi">mysql_set_local_infile_handler()</function> function
- was added in MySQL 4.1.2.
+ The
+ <function role="capi">mysql_set_local_infile_handler()</function>
+ function was added in MySQL 4.1.2.
</para>
<para>
@@ -7465,7 +7487,8 @@
results from calls to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -7535,9 +7558,9 @@
<para>
The server didn't support
- <function role="capi">mysql_set_server_option()</function> (which is the
- case that the server is older than 4.1.1) or the server
- didn't support the option one tried to set.
+ <function role="capi">mysql_set_server_option()</function>
+ (which is the case that the server is older than 4.1.1) or
+ the server didn't support the option one tried to set.
</para>
</listitem>
@@ -7571,8 +7594,9 @@
are planned to make it possible to choose the desired level.
Dynamically linked executables which have been compiled with
older versions of the <literal>libmysqlclient</literal> headers
- and call <function role="capi">mysql_shutdown()</function> need to be used
- with the old <literal>libmysqlclient</literal> dynamic library.
+ and call <function role="capi">mysql_shutdown()</function> need
+ to be used with the old <literal>libmysqlclient</literal>
+ dynamic library.
</para>
<para>
@@ -7735,14 +7759,14 @@
</para>
<para>
- <function role="capi">mysql_ssl_set()</function> is used for establishing
- secure connections using SSL. It must be called before
- <function role="capi">mysql_real_connect()</function>.
+ <function role="capi">mysql_ssl_set()</function> is used for
+ establishing secure connections using SSL. It must be called
+ before <function role="capi">mysql_real_connect()</function>.
</para>
<para>
- <function role="capi">mysql_ssl_set()</function> does nothing unless OpenSSL
- support is enabled in the client library.
+ <function role="capi">mysql_ssl_set()</function> does nothing
+ unless OpenSSL support is enabled in the client library.
</para>
<para>
@@ -7914,8 +7938,8 @@
(<literal>SELECT</literal>, <literal>SHOW</literal>,
<literal>DESCRIBE</literal>, <literal>EXPLAIN</literal>,
<literal>CHECK TABLE</literal>, and so forth). You must also
- call <function role="capi">mysql_free_result()</function> after you are done
- with the result set.
+ call <function role="capi">mysql_free_result()</function> after
+ you are done with the result set.
</para>
<para>
@@ -7936,7 +7960,8 @@
results from calls to
<function role="capi">mysql_query()</function> or
<function role="capi">mysql_real_query()</function> by using a
- loop that calls <function role="capi">mysql_next_result()</function> to
+ loop that calls
+ <function role="capi">mysql_next_result()</function> to
determine whether there are more results. For an example, see
<xref linkend="c-api-multiple-queries"/>.
</para>
@@ -7982,8 +8007,8 @@
After you have called
<function role="capi">mysql_store_result()</function> and gotten
back a result that isn't a null pointer, you can call
- <function role="capi">mysql_num_rows()</function> to find out how many rows
- are in the result set.
+ <function role="capi">mysql_num_rows()</function> to find out
+ how many rows are in the result set.
</para>
<para>
@@ -8091,15 +8116,16 @@
<para>
Returns the thread ID of the current connection. This value can
- be used as an argument to <function role="capi">mysql_kill()</function> to
- kill the thread.
+ be used as an argument to
+ <function role="capi">mysql_kill()</function> to kill the
+ thread.
</para>
<para>
If the connection is lost and you reconnect with
- <function role="capi">mysql_ping()</function>, the thread ID changes. This
- means you should not get the thread ID and store it for later.
- You should get it when you need it.
+ <function role="capi">mysql_ping()</function>, the thread ID
+ changes. This means you should not get the thread ID and store
+ it for later. You should get it when you need it.
</para>
<para>
@@ -8183,7 +8209,8 @@
</para>
<para>
- You may not use <function role="capi">mysql_data_seek()</function>,
+ You may not use
+ <function role="capi">mysql_data_seek()</function>,
<function role="capi">mysql_row_seek()</function>,
<function role="capi">mysql_row_tell()</function>,
<function role="capi">mysql_num_rows()</function>, or
@@ -8193,12 +8220,13 @@
issue other queries until
<function role="capi">mysql_use_result()</function> has
finished. (However, after you have fetched all the rows,
- <function role="capi">mysql_num_rows()</function> accurately returns the
- number of rows fetched.)
+ <function role="capi">mysql_num_rows()</function> accurately
+ returns the number of rows fetched.)
</para>
<para>
- You must call <function role="capi">mysql_free_result()</function> once you
+ You must call
+ <function role="capi">mysql_free_result()</function> once you
are done with the result set.
</para>
@@ -8334,11 +8362,11 @@
The MySQL client/server protocol provides for the use of prepared
statements. This capability uses the <literal>MYSQL_STMT</literal>
statement handler data structure returned by the
- <function role="capi">mysql_stmt_init()</function> initialization function.
- Prepared execution is an efficient way to execute a statement more
- than once. The statement is first parsed to prepare it for
- execution. Then it is executed one or more times at a later time,
- using the statement handle returned by the initialization
+ <function role="capi">mysql_stmt_init()</function> initialization
+ function. Prepared execution is an efficient way to execute a
+ statement more than once. The statement is first parsed to prepare
+ it for execution. Then it is executed one or more times at a later
+ time, using the statement handle returned by the initialization
function.
</para>
@@ -8422,8 +8450,9 @@
<listitem>
<para>
To prepare a statement, pass the statement string to
- <function role="capi">mysql_stmt_init()</function>, which returns a pointer
- to a <literal>MYSQL_STMT</literal> data structure.
+ <function role="capi">mysql_stmt_init()</function>, which
+ returns a pointer to a <literal>MYSQL_STMT</literal> data
+ structure.
</para>
</listitem>
@@ -8431,9 +8460,10 @@
<para>
To provide input parameters for a prepared statement, set up
<literal>MYSQL_BIND</literal> structures and pass them to
- <function role="capi">mysql_stmt_bind_param()</function>. To receive output
- column values, set up <literal>MYSQL_BIND</literal> structures
- and pass them to <function role="capi">mysql_stmt_bind_result()</function>.
+ <function role="capi">mysql_stmt_bind_param()</function>. To
+ receive output column values, set up
+ <literal>MYSQL_BIND</literal> structures and pass them to
+ <function role="capi">mysql_stmt_bind_result()</function>.
</para>
</listitem>
@@ -8464,12 +8494,13 @@
<para>
This structure represents a prepared statement. A statement is
- created by calling <function role="capi">mysql_stmt_init()</function>, which
+ created by calling
+ <function role="capi">mysql_stmt_init()</function>, which
returns a statement handle (that is, a pointer to a
<literal>MYSQL_STMT</literal>). The handle is used for all
subsequent operations with the statement until you close it
- with <function role="capi">mysql_stmt_close()</function>, at which point the
- handle becomes invalid.
+ with <function role="capi">mysql_stmt_close()</function>, at
+ which point the handle becomes invalid.
</para>
<para>
@@ -8507,8 +8538,8 @@
<listitem>
<para>
For input, <literal>MYSQL_BIND</literal> is used with
- <function role="capi">mysql_stmt_bind_param()</function> to bind
- parameter data values to buffers for use by
+ <function role="capi">mysql_stmt_bind_param()</function>
+ to bind parameter data values to buffers for use by
<function role="capi">mysql_stmt_execute()</function>.
</para>
</listitem>
@@ -8516,8 +8547,8 @@
<listitem>
<para>
For output, <literal>MYSQL_BIND</literal> is used with
- <function role="capi">mysql_stmt_bind_result()</function> to bind result
- set buffers for use in fetching rows with
+ <function role="capi">mysql_stmt_bind_result()</function>
+ to bind result set buffers for use in fetching rows with
<function role="capi">mysql_stmt_fetch()</function>.
</para>
</listitem>
@@ -8578,16 +8609,17 @@
For input, <literal>buffer</literal> is a pointer to the
variable in which a statement parameter's data value is
stored. When you call
- <function role="capi">mysql_stmt_execute()</function>, MySQL takes the
- value that you have stored in the variable and uses it in
- place of the corresponding parameter marker in the
- statement.
+ <function role="capi">mysql_stmt_execute()</function>,
+ MySQL takes the value that you have stored in the variable
+ and uses it in place of the corresponding parameter marker
+ in the statement.
</para>
<para>
For output, <literal>buffer</literal> is a pointer to the
variable in which to return a result set column value.
- When you call <function role="capi">mysql_stmt_fetch()</function>, MySQL
+ When you call
+ <function role="capi">mysql_stmt_fetch()</function>, MySQL
returns a column value and stores it in this variable. You
can access the value when the call returns.
</para>
@@ -8626,9 +8658,10 @@
stored in the buffer. For character and binary C data, the
<literal>buffer_length</literal> value specifies the
length of <literal>*buffer</literal> when used with
- <function role="capi">mysql_stmt_bind_param()</function> to specify
- input values, or the maximum number of output data bytes
- that can be fetched into the buffer when used with
+ <function role="capi">mysql_stmt_bind_param()</function>
+ to specify input values, or the maximum number of output
+ data bytes that can be fetched into the buffer when used
+ with
<function role="capi">mysql_stmt_bind_result()</function>.
</para>
</listitem>
@@ -8656,24 +8689,24 @@
<para>
For output value binding, the return value of
- <function role="capi">mysql_stmt_fetch()</function> determines the
- interpretation of the length:
+ <function role="capi">mysql_stmt_fetch()</function>
+ determines the interpretation of the length:
</para>
<itemizedlist>
<listitem>
<para>
- If <function role="capi">mysql_stmt_fetch()</function> returns 0,
- <literal>*length</literal> indicates the actual length
- of the parameter value.
+ If <function role="capi">mysql_stmt_fetch()</function>
+ returns 0, <literal>*length</literal> indicates the
+ actual length of the parameter value.
</para>
</listitem>
<listitem>
<para>
- If <function role="capi">mysql_stmt_fetch()</function> returns
- <literal>MYSQL_DATA_TRUNCATED</literal>,
+ If <function role="capi">mysql_stmt_fetch()</function>
+ 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
@@ -8822,8 +8855,8 @@
<function role="capi">mysql_options()</function> with the
<literal>MYSQL_REPORT_DATA_TRUNCATION</literal> option.)
When truncation reporting is enabled,
- <function role="capi">mysql_stmt_fetch()</function> returns
- <literal>MYSQL_DATA_TRUNCATED</literal> and
+ <function role="capi">mysql_stmt_fetch()</function>
+ returns <literal>MYSQL_DATA_TRUNCATED</literal> and
<literal>*error</literal> is true in the
<literal>MYSQL_BIND</literal> structures for parameters in
which truncation occurred. Truncation indicates loss of
@@ -9213,11 +9246,12 @@
<literal>'12.345'</literal>. If you specify
<literal>MYSQL_TYPE_NEWDECIMAL</literal> and bind a string
buffer to the <literal>MYSQL_BIND</literal> structure,
- <function role="capi">mysql_stmt_fetch()</function> stores the value in the
- buffer without conversion. If instead you specify a numeric
- variable and type code, <function role="capi">mysql_stmt_fetch()</function>
- converts the string-format <literal>DECIMAL</literal> value to
- numeric form.
+ <function role="capi">mysql_stmt_fetch()</function> stores the
+ value in the buffer without conversion. If instead you specify
+ a numeric variable and type code,
+ <function role="capi">mysql_stmt_fetch()</function> converts
+ the string-format <literal>DECIMAL</literal> value to numeric
+ form.
</para>
</listitem>
@@ -9253,26 +9287,27 @@
check the type codes for each column of the result set. This might
be desirable if you want to determine which variable types would
be best to use to avoid type conversions. To get the type codes,
- call <function role="capi">mysql_stmt_result_metadata()</function> after
- executing the prepared statement with
- <function role="capi">mysql_stmt_execute()</function>. The metadata provides
- access to the type codes for the result set as described in
- <xref linkend="mysql-stmt-result-metadata"/>, and
+ call <function role="capi">mysql_stmt_result_metadata()</function>
+ after executing the prepared statement with
+ <function role="capi">mysql_stmt_execute()</function>. The
+ metadata provides access to the type codes for the result set as
+ described in <xref linkend="mysql-stmt-result-metadata"/>, and
<xref linkend="c-api-datatypes"/>.
</para>
<para>
If you cause the <literal>max_length</literal> member of the
<literal>MYSQL_FIELD</literal> column metadata structures to be
- set (by calling <function role="capi">mysql_stmt_attr_set()</function>), be
- aware that the <literal>max_length</literal> values for the result
- set indicate the lengths of the longest string representation of
- the result values, not the lengths of the binary representation.
- That is, <literal>max_length</literal> does not necessarily
- correspond to the size of the buffers needed to fetch the values
- with the binary protocol used for prepared statements. The size of
- the buffers should be chosen according to the types of the
- variables into which you fetch the values.
+ set (by calling
+ <function role="capi">mysql_stmt_attr_set()</function>), be aware
+ that the <literal>max_length</literal> values for the result set
+ indicate the lengths of the longest string representation of the
+ result values, not the lengths of the binary representation. That
+ is, <literal>max_length</literal> does not necessarily correspond
+ to the size of the buffers needed to fetch the values with the
+ binary protocol used for prepared statements. The size of the
+ buffers should be chosen according to the types of the variables
+ into which you fetch the values.
</para>
<para>
@@ -9430,7 +9465,8 @@
<row>
<entry><function role="capi">mysql_stmt_row_seek()</function></entry>
<entry>Seeks to a row offset in a statement result set, using value returned
- from <function role="capi">mysql_stmt_row_tell()</function></entry>
+ from
+ <function role="capi">mysql_stmt_row_tell()</function></entry>
</row>
<row>
<entry><function role="capi">mysql_stmt_row_tell()</function></entry>
@@ -9453,49 +9489,55 @@
</informaltable>
<para>
- Call <function role="capi">mysql_stmt_init()</function> to create a statement
- handle, then <function role="capi">mysql_stmt_prepare()</function> to prepare it,
- <function role="capi">mysql_stmt_bind_param()</function> to supply the parameter
- data, and <function role="capi">mysql_stmt_execute()</function> to execute the
- statement. You can repeat the
- <function role="capi">mysql_stmt_execute()</function> by changing parameter
- values in the respective buffers supplied through
+ Call <function role="capi">mysql_stmt_init()</function> to create
+ a statement handle, then
+ <function role="capi">mysql_stmt_prepare()</function> to prepare
+ it, <function role="capi">mysql_stmt_bind_param()</function> to
+ supply the parameter data, and
+ <function role="capi">mysql_stmt_execute()</function> to execute
+ the statement. You can repeat the
+ <function role="capi">mysql_stmt_execute()</function> by changing
+ parameter values in the respective buffers supplied through
<function role="capi">mysql_stmt_bind_param()</function>.
</para>
<para>
If the statement is a <literal>SELECT</literal> or any other
statement that produces a result set,
- <function role="capi">mysql_stmt_prepare()</function> also returns the result
- set metadata information in the form of a
+ <function role="capi">mysql_stmt_prepare()</function> also returns
+ the result set metadata information in the form of a
<literal>MYSQL_RES</literal> result set through
<function role="capi">mysql_stmt_result_metadata()</function>.
</para>
<para>
You can supply the result buffers using
- <function role="capi">mysql_stmt_bind_result()</function>, so that the
- <function role="capi">mysql_stmt_fetch()</function> automatically returns data
- to these buffers. This is row-by-row fetching.
+ <function role="capi">mysql_stmt_bind_result()</function>, so that
+ the <function role="capi">mysql_stmt_fetch()</function>
+ automatically returns data to these buffers. This is row-by-row
+ fetching.
</para>
<para>
You can also send the text or binary data in chunks to server
- using <function role="capi">mysql_stmt_send_long_data()</function>. See
+ using
+ <function role="capi">mysql_stmt_send_long_data()</function>. See
<xref linkend="mysql-stmt-send-long-data"/>.
</para>
<para>
When statement execution has been completed, the statement handle
- must be closed using <function role="capi">mysql_stmt_close()</function> so that
- all resources associated with it can be freed.
+ must be closed using
+ <function role="capi">mysql_stmt_close()</function> so that all
+ resources associated with it can be freed.
</para>
<para>
If you obtained a <literal>SELECT</literal> statement's result set
metadata by calling
- <function role="capi">mysql_stmt_result_metadata()</function>, you should also
- free the metadata using <function role="capi">mysql_free_result()</function>.
+ <function role="capi">mysql_stmt_result_metadata()</function>, you
+ should also free the metadata using
+ <function role="capi">mysql_free_result()</function>.
</para>
<para>
@@ -9512,37 +9554,38 @@
<listitem>
<para>
Create a prepared statement handle with
- <function role="capi">mysql_stmt_init()</function>. To prepare the statement
- on the server, call <function role="capi">mysql_stmt_prepare()</function>
- and pass it a string containing the SQL statement.
+ <function role="capi">mysql_stmt_init()</function>. To prepare
+ the statement on the server, call
+ <function role="capi">mysql_stmt_prepare()</function> and pass
+ it a string containing the SQL statement.
</para>
</listitem>
<listitem>
<para>
If the statement produces a result set, call
- <function role="capi">mysql_stmt_result_metadata()</function> to obtain the
- result set metadata. This metadata is itself in the form of
- result set, albeit a separate one from the one that contains
- the rows returned by the query. The metadata result set
- indicates how many columns are in the result and contains
- information about each column.
+ <function role="capi">mysql_stmt_result_metadata()</function>
+ to obtain the result set metadata. This metadata is itself in
+ the form of result set, albeit a separate one from the one
+ that contains the rows returned by the query. The metadata
+ result set indicates how many columns are in the result and
+ contains information about each column.
</para>
</listitem>
<listitem>
<para>
Set the values of any parameters using
- <function role="capi">mysql_stmt_bind_param()</function>. All parameters
- must be set. Otherwise, statement execution returns an error
- or produces unexpected results.
+ <function role="capi">mysql_stmt_bind_param()</function>. All
+ parameters must be set. Otherwise, statement execution returns
+ an error or produces unexpected results.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_execute()</function> to execute the
- statement.
+ Call <function role="capi">mysql_stmt_execute()</function> to
+ execute the statement.
</para>
</listitem>
@@ -9557,8 +9600,8 @@
<listitem>
<para>
Fetch the data into the buffers row by row by calling
- <function role="capi">mysql_stmt_fetch()</function> repeatedly until no more
- rows are found.
+ <function role="capi">mysql_stmt_fetch()</function> repeatedly
+ until no more rows are found.
</para>
</listitem>
@@ -9572,8 +9615,8 @@
</orderedlist>
<para>
- When <function role="capi">mysql_stmt_prepare()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_prepare()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9599,8 +9642,8 @@
</itemizedlist>
<para>
- When <function role="capi">mysql_stmt_execute()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_execute()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9626,8 +9669,8 @@
</itemizedlist>
<para>
- When <function role="capi">mysql_stmt_fetch()</function> is called, the MySQL
- client/server protocol performs these actions:
+ When <function role="capi">mysql_stmt_fetch()</function> is
+ called, the MySQL client/server protocol performs these actions:
</para>
<itemizedlist>
@@ -9660,8 +9703,8 @@
<para>
For prepared statements that are executed with the
<function role="capi">mysql_stmt_prepare()</function> and
- <function role="capi">mysql_stmt_execute()</function> C API functions, the
- server writes <literal>Prepare</literal> and
+ <function role="capi">mysql_stmt_execute()</function> C API
+ functions, the server writes <literal>Prepare</literal> and
<literal>Execute</literal> lines to the general query log so that
you can tell when statements are prepared and executed.
</para>
@@ -9674,23 +9717,23 @@
<listitem>
<para>
- Call <function role="capi">mysql_stmt_prepare()</function> to prepare the
- statement string <literal>"SELECT ?"</literal>.
+ Call <function role="capi">mysql_stmt_prepare()</function> to
+ prepare the statement string <literal>"SELECT ?"</literal>.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_bind_param()</function> to bind the
- value <literal>3</literal> to the parameter in the prepared
- statement.
+ Call <function role="capi">mysql_stmt_bind_param()</function>
+ to bind the value <literal>3</literal> to the parameter in the
+ prepared statement.
</para>
</listitem>
<listitem>
<para>
- Call <function role="capi">mysql_stmt_execute()</function> to execute the
- prepared statement.
+ Call <function role="capi">mysql_stmt_execute()</function> to
+ execute the prepared statement.
</para>
</listitem>
@@ -9771,8 +9814,8 @@
<literal>UPDATE</literal>, <literal>DELETE</literal>, or
<literal>INSERT</literal> statements. For
<literal>SELECT</literal> statements,
- <function role="capi">mysql_stmt_affected_rows()</function> works like
- <function role="capi">mysql_num_rows()</function>.
+ <function role="capi">mysql_stmt_affected_rows()</function>
+ works like <function role="capi">mysql_num_rows()</function>.
</para>
<para>
@@ -9786,11 +9829,14 @@
matched the <literal>WHERE</literal> clause in the query, or
that no query has yet been executed. -1 indicates that the query
returned an error or that, for a <literal>SELECT</literal>
- query, <function role="capi">mysql_stmt_affected_rows()</function> was called
- prior to calling <function role="capi">mysql_stmt_store_result()</function>.
- Because <function role="capi">mysql_stmt_affected_rows()</function> returns an
- unsigned value, you can check for -1 by comparing the return
- value to <literal>(my_ulonglong)-1</literal> (or to
+ query,
+ <function role="capi">mysql_stmt_affected_rows()</function> was
+ called prior to calling
+ <function role="capi">mysql_stmt_store_result()</function>.
+ Because
+ <function role="capi">mysql_stmt_affected_rows()</function>
+ returns an unsigned value, you can check for -1 by comparing the
+ return value to <literal>(my_ulonglong)-1</literal> (or to
<literal>(my_ulonglong)~0</literal>, which is equivalent).
</para>
@@ -9812,7 +9858,8 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_affected_rows()</function>,
+ For the usage of
+ <function role="capi">mysql_stmt_affected_rows()</function>,
refer to the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
@@ -9855,9 +9902,9 @@
<note>
<para>
In MySQL ¤t-series;,
- <function role="capi">mysql_stmt_attr_get()</function> originally used
- <literal>unsigned int *</literal>, not <literal>my_bool
- *</literal>, for
+ <function role="capi">mysql_stmt_attr_get()</function>
+ originally used <literal>unsigned int *</literal>, not
+ <literal>my_bool *</literal>, for
<literal>STMT_ATTR_UPDATE_MAX_LENGTH</literal>.
</para>
</note>
@@ -9937,8 +9984,8 @@
<entry><literal>STMT_ATTR_CURSOR_TYPE</literal></entry>
<entry><literal>unsigned long *</literal></entry>
<entry>Type of cursor to open for statement when
- <function role="capi">mysql_stmt_execute()</function> is invoked.
- <literal>*arg</literal> can be
+ <function role="capi">mysql_stmt_execute()</function> is
+ invoked. <literal>*arg</literal> can be
<literal>CURSOR_TYPE_NO_CURSOR</literal> (the default)
or <literal>CURSOR_TYPE_READ_ONLY</literal>.</entry>
</row>
@@ -9958,21 +10005,21 @@
If you use the <literal>STMT_ATTR_CURSOR_TYPE</literal> option
with <literal>CURSOR_TYPE_READ_ONLY</literal>, a cursor is
opened for the statement when you invoke
- <function role="capi">mysql_stmt_execute()</function>. If there is already an
- open cursor from a previous
- <function role="capi">mysql_stmt_execute()</function> call, it closes the
- cursor before opening a new one.
- <function role="capi">mysql_stmt_reset()</function> also closes any open
- cursor before preparing the statement for re-execution.
- <function role="capi">mysql_stmt_free_result()</function> closes any open
- cursor.
+ <function role="capi">mysql_stmt_execute()</function>. If there
+ is already an open cursor from a previous
+ <function role="capi">mysql_stmt_execute()</function> call, it
+ closes the cursor before opening a new one.
+ <function role="capi">mysql_stmt_reset()</function> also closes
+ any open cursor before preparing the statement for re-execution.
+ <function role="capi">mysql_stmt_free_result()</function> closes
+ any open cursor.
</para>
<para>
If you open a cursor for a prepared statement,
- <function role="capi">mysql_stmt_store_result()</function> is unnecessary,
- because that function causes the result set to be buffered on
- the client side.
+ <function role="capi">mysql_stmt_store_result()</function> is
+ unnecessary, because that function causes the result set to be
+ buffered on the client side.
</para>
<para>
@@ -10036,9 +10083,10 @@
</para>
<para>
- <function role="capi">mysql_stmt_bind_param()</function> is used to bind input
- data for the parameter markers in the SQL statement that was
- passed to <function role="capi">mysql_stmt_prepare()</function>. It uses
+ <function role="capi">mysql_stmt_bind_param()</function> is used
+ to bind input data for the parameter markers in the SQL
+ statement that was passed to
+ <function role="capi">mysql_stmt_prepare()</function>. It uses
<literal>MYSQL_BIND</literal> structures to supply the data.
<literal>bind</literal> is the address of an array of
<literal>MYSQL_BIND</literal> structures. The client library
@@ -10125,8 +10173,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_bind_param()</function>,
- refer to the Example from <xref linkend="mysql-stmt-execute"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_bind_param()</function>, refer
+ to the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
</section>
@@ -10149,44 +10198,47 @@
</para>
<para>
- <function role="capi">mysql_stmt_bind_result()</function> is used to associate
- (that is, bind) output columns in the result set to data buffers
- and length buffers. When <function role="capi">mysql_stmt_fetch()</function>
- is called to fetch data, the MySQL client/server protocol places
- the data for the bound columns into the specified buffers.
+ <function role="capi">mysql_stmt_bind_result()</function> is
+ used to associate (that is, bind) output columns in the result
+ set to data buffers and length buffers. When
+ <function role="capi">mysql_stmt_fetch()</function> is called to
+ fetch data, the MySQL client/server protocol places the data for
+ the bound columns into the specified buffers.
</para>
<para>
All columns must be bound to buffers prior to calling
- <function role="capi">mysql_stmt_fetch()</function>. <literal>bind</literal>
- is the address of an array of <literal>MYSQL_BIND</literal>
- structures. The client library expects the array to contain one
- element for each column of the result set. If you do not bind
- columns to <literal>MYSQL_BIND</literal> structures,
- <function role="capi">mysql_stmt_fetch()</function> simply ignores the data
- fetch. The buffers should be large enough to hold the data
- values, because the protocol doesn't return data values in
- chunks.
+ <function role="capi">mysql_stmt_fetch()</function>.
+ <literal>bind</literal> is the address of an array of
+ <literal>MYSQL_BIND</literal> structures. The client library
+ expects the array to contain one element for each column of the
+ result set. If you do not bind columns to
+ <literal>MYSQL_BIND</literal> structures,
+ <function role="capi">mysql_stmt_fetch()</function> simply
+ ignores the data fetch. The buffers should be large enough to
+ hold the data values, because the protocol doesn't return data
+ values in chunks.
</para>
<para>
A column can be bound or rebound at any time, even after a
result set has been partially retrieved. The new binding takes
- effect the next time <function role="capi">mysql_stmt_fetch()</function> is
- called. Suppose that an application binds the columns in a
- result set and calls <function role="capi">mysql_stmt_fetch()</function>. The
- client/server protocol returns data in the bound buffers. Then
- suppose that the application binds the columns to a different
- set of buffers. The protocol places data into the newly bound
- buffers when the next call to
+ effect the next time
+ <function role="capi">mysql_stmt_fetch()</function> is called.
+ Suppose that an application binds the columns in a result set
+ and calls <function role="capi">mysql_stmt_fetch()</function>.
+ The client/server protocol returns data in the bound buffers.
+ Then suppose that the application binds the columns to a
+ different set of buffers. The protocol places data into the
+ newly bound buffers when the next call to
<function role="capi">mysql_stmt_fetch()</function> occurs.
</para>
<para>
To bind a column, an application calls
- <function role="capi">mysql_stmt_bind_result()</function> and passes the type,
- address, and length of the output buffer into which the value
- should be stored.
+ <function role="capi">mysql_stmt_bind_result()</function> and
+ passes the type, 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.
@@ -10246,8 +10298,9 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_bind_result()</function>,
- refer to the Example from <xref linkend="mysql-stmt-fetch"/>.
+ For the usage of
+ <function role="capi">mysql_stmt_bind_result()</function>, refer
+ to the Example from <xref linkend="mysql-stmt-fetch"/>.
</para>
</section>
@@ -10270,8 +10323,9 @@
<para>
Closes the prepared statement.
- <function role="capi">mysql_stmt_close()</function> also deallocates the
- statement handle pointed to by <literal>stmt</literal>.
+ <function role="capi">mysql_stmt_close()</function> also
+ deallocates the statement handle pointed to by
+ <literal>stmt</literal>.
</para>
<para>
@@ -10321,7 +10375,8 @@
</para>
<para>
- For the usage of <function role="capi">mysql_stmt_close()</function>, refer to
+ For the usage of
+ <function role="capi">mysql_stmt_close()</function>, refer to
the Example from <xref linkend="mysql-stmt-execute"/>.
</para>
@@ -10354,8 +10409,9 @@
<para>
This function requires that the statement result set structure
contains the entire result of the last executed query, so
- <function role="capi">mysql_stmt_data_seek()</function> may be used only in
- conjunction with <function role="capi">mysql_stmt_store_result()</function>.
+ <function role="capi">mysql_stmt_data_seek()</function> may be
+ used only in conjunction with
+ <function role="capi">mysql_stmt_store_result()</function>.
</para>
<para>
@@ -10504,32 +10560,35 @@
</para>
<para>
- <function role="capi">mysql_stmt_execute()</function> executes the prepared
- query associated with the statement handle. The currently bound
- parameter marker values are sent to server during this call, and
- the server replaces the markers with this newly supplied data.
+ <function role="capi">mysql_stmt_execute()</function> executes
+ the prepared query associated with the statement handle. The
+ currently bound parameter marker values are sent to server
+ during this call, and the server replaces the markers with this
+ newly supplied data.
</para>
<para>
If the statement is an <literal>UPDATE</literal>,
<literal>DELETE</literal>, or <literal>INSERT</literal>, the
total number of changed, deleted, or inserted rows can be found
- by calling <function role="capi">mysql_stmt_affected_rows()</function>. If
+ by calling
+ <function role="capi">mysql_stmt_affected_rows()</function>. If
this is a statement such as <literal>SELECT</literal> that
generates a result set, you must call
- <function role="capi">mysql_stmt_fetch()</function> to fetch the data prior to
- calling any other functions that result in query processing. For
- more information on how to fetch the results, refer to
- <xref linkend="mysql-stmt-fetch"/>.
+ <function role="capi">mysql_stmt_fetch()</function> to fetch the
+ data prior to calling any other functions that result in query
+ processing. For more information on how to fetch the results,
+ refer to <xref linkend="mysql-stmt-fetch"/>.
</para>
<para>
For statements that generate a result set, you can request that
- <function role="capi">mysql_stmt_execute()</function> open a cursor for the
- statement by calling <function role="capi">mysql_stmt_attr_set()</function>
- before executing the statement. If you execute a statement
- multiple times, <function role="capi">mysql_stmt_execute()</function> closes
- any open cursor before opening a new one.
+ <function role="capi">mysql_stmt_execute()</function> open a
+ cursor for the statement by calling
+ <function role="capi">mysql_stmt_attr_set()</function> before
+ executing the statement. If you execute a statement multiple
+ times, <function role="capi">mysql_stmt_execute()</function>
+ closes any open cursor before opening a new one.
</para>
<remark role="note">
@@ -10822,16 +10881,18 @@
</para>
<para>
- <function role="capi">mysql_stmt_fetch()</function> returns the next row in
- the result set. It can be called only while the result set
- exists; that is, after a call to
- <function role="capi">mysql_stmt_execute()</function> for a statement such as
- <literal>SELECT</literal> that creates a result set.
+ <function role="capi">mysql_stmt_fetch()</function> returns the
+ next row in the result set. It can be called only while the
+ result set exists; that is, after a call to
+ <function role="capi">mysql_stmt_execute()</function> for a
+ statement such as <literal>SELECT</literal> that creates a
+ result set.
</para>
<para>
- <function role="capi">mysql_stmt_fetch()</function> returns row data using the
- buffers bound by <function role="capi">mysql_stmt_bind_result()</function>. It
+ <function role="capi">mysql_stmt_fetch()</function> returns row
+ data using the buffers bound by
+ <function role="capi">mysql_stmt_bind_result()</function>. It
returns the data in those buffers for all the columns in the
current row set and the lengths are returned to the
<literal>length</literal> pointer. All columns must be bound by
@@ -10842,8 +10903,8 @@
<para>
By default, result sets are fetched unbuffered a row at a time
from the server. To buffer the entire result set on the client,
- call <function role="capi">mysql_stmt_store_result()</function> after binding
- the data buffers and before caling
+ call <function role="capi">mysql_stmt_store_result()</function>
+ after binding the data buffers and before caling
<function role="capi">mysql_stmt_fetch()</function>.
</para>
@@ -11049,11 +11110,12 @@
<para>
The following example demonstrates how to fetch data from a
- table using <function role="capi">mysql_stmt_result_metadata()</function>,
+ table using
+ <function role="capi">mysql_stmt_result_metadata()</function>,
<function role="capi">mysql_stmt_bind_result()</function>, and
- <function role="capi">mysql_stmt_fetch()</function>. (This example expects to
- retrieve the two rows inserted by the example shown in
- <xref linkend="mysql-stmt-execute"/>.) The
+ <function role="capi">mysql_stmt_fetch()</function>. (This
+ example expects to retrieve the two rows inserted by the example
+ shown in <xref linkend="mysql-stmt-execute"/>.) The
<literal>mysql</literal> variable is assumed to be a valid
connection handle.
</para>
@@ -11246,37 +11308,41 @@
<para>
In some cases you might want to determine the length of a column
value before fetching it with
- <function role="capi">mysql_stmt_fetch()</function>. For example, the value
- might be a long string or <literal>BLOB</literal> value for
- which you want to know how much space must be allocated. To
- accomplish this, you can use these strategies:
+ <function role="capi">mysql_stmt_fetch()</function>. For
+ example, the value might be a long string or
+ <literal>BLOB</literal> value for which you want to know how
+ much space must be allocated. To accomplish this, you can use
+ these strategies:
</para>
<itemizedlist>
<listitem>
<para>
- Before invoking <function role="capi">mysql_stmt_fetch()</function> to
+ Before invoking
+ <function role="capi">mysql_stmt_fetch()</function> to
retrieve individual rows, invoke
- <function role="capi">mysql_stmt_store_result()</function> to buffer the
- entire result on the client side. Then the maximal length of
- column values will be indicated by the
+ <function role="capi">mysql_stmt_store_result()</function>
+ to buffer the entire result on the client side. Then the
+ maximal length of column values will be indicated by the
<literal>max_length</literal> member of the result set
metadata returned by
- <function role="capi">mysql_stmt_result_metadata()</function>. This
- strategy requires that you pass
+ <function role="capi">mysql_stmt_result_metadata()</function>.
+ This strategy requires that you pass
<literal>STMT_ATTR_UPDATE_MAX_LENGTH</literal> to
- <function role="capi">mysql_stmt_attr_set()</function> or the
- <literal>max_length</literal> values will not be calculated.
+ <function role="capi">mysql_stmt_attr_set()</function> or
+ the <literal>max_length</literal> values will not be
+ calculated.
</para>
</listitem>
<listitem>
<para>
- Invoke <function role="capi">mysql_stmt_fetch()</function> with a
- zero-length buffer for the column in question and a pointer
- in which the real length can be stored. Then use the real
- length with <function role="capi">mysql_stmt_fetch_column()</function>.
+ Invoke <function role="capi">mysql_stmt_fetch()</function>
+ with a zero-length buffer for the column in question and a
+ pointer in which the real length can be stored. Then use the
+ real length with
+ <function role="capi">mysql_stmt_fetch_column()</function>.
</para>
<programlisting>
@@ -11396,8 +11462,8 @@
</para>
<para>
- <function role="capi">mysql_stmt_field_count()</function> can be called after
- you have prepared a statement by invoking
+ <function role="capi">mysql_stmt_field_count()</function> can be
+ called after you have prepared a statement by invoking
<function role="capi">mysql_stmt_prepare()</function>.
</para>
@@ -11440,8 +11506,9 @@
<para>
Releases memory associated with the result set produced by
execution of the prepared statement. If there is a cursor open
- for the statement, <function role="capi">mysql_stmt_free_result()</function>
- closes it.
+ for the statement,
+ <function role="capi">mysql_stmt_free_result()</function> closes
+ it.
</para>
<para>
@@ -11477,7 +11544,8 @@
<para>
Create a <literal>MYSQL_STMT</literal> handle. The handle should
- be freed with <function role="capi">mysql_stmt_close(MYSQL_STMT *)</function>.
+ be freed with <function role="capi">mysql_stmt_close(MYSQL_STMT
+ *)</function>.
</para>
<para>
@@ -11591,25 +11659,29 @@
</para>
<para>
- The use of <function role="capi">mysql_stmt_num_rows()</function> depends on
- whether you used <function role="capi">mysql_stmt_store_result()</function> to
+ The use of
+ <function role="capi">mysql_stmt_num_rows()</function> depends
+ on whether you used
+ <function role="capi">mysql_stmt_store_result()</function> to
buffer the entire result set in the statement handle.
</para>
<para>
- If you use <function role="capi">mysql_stmt_store_result()</function>,
- <function role="capi">mysql_stmt_num_rows()</function> may be called
- immediately. Otherwise, the row count is unavailable unless you
- count the rows as you fetch them.
+ If you use
+ <function role="capi">mysql_stmt_store_result()<
