Below is the list of changes that have just been committed into a local
mysqldoc repository of jon. When jon does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html
ChangeSet
1.3388 05/08/25 10:41:05 jon@stripped +5 -0
Edited APIs chapter (5.0 and 5.1 versions)
for RefMan Split.
Updated Status files to reflect work +
recent discussions with Connectors team.
refman-5.1/mysql-apis.xml
1.24 05/08/25 10:41:04 jon@stripped +360 -550
Initial RefMan-5.1 version edits (thanks, Paul!)
refman-5.1/Status
1.5 05/08/25 10:41:04 jon@stripped +5 -5
Updating...
refman-5.0/mysql-apis.xml
1.23 05/08/25 10:41:04 jon@stripped +153 -273
RefMan-5.0 version edits (thanks, Paul!)
refman-5.0/Status
1.2 05/08/25 10:41:04 jon@stripped +5 -4
Updating...
refman-4.1/Status
1.13 05/08/25 10:41:04 jon@stripped +6 -5
Updating...
# This is a BitKeeper patch. What follows are the unified diffs for the
# set of deltas contained in the patch. The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User: jon
# Host: gigan.
# Root: /home/jon/bk/mysqldoc
--- 1.12/refman-4.1/Status 2005-08-19 19:44:20 +10:00
+++ 1.13/refman-4.1/Status 2005-08-25 10:41:04 +10:00
@@ -16,27 +16,28 @@
introduction
tutorial
replication
- environment-variables
using-mysql-programs
+ mysql-apis
innodb
error-handling
limits
restrictions
- 4.1 chapters (probably/hopefully) needing minimal if any edits:
- maxdb
- mysql-apis
- mysql-connectors
extending-mysql
problems
regexp
news
-- Chapters that are constant across MySQL versions (refman-common tree):
+- Chapters that are constant across MySQL versions (refman-common tree)
+ or are otherwise not currently part of edits for split:
credits
porting
gpl-license
floss-license-exception
news-x.x sections
+ environment-variables
+ maxdb
+ mysql-connectors
--- 1.1/refman-5.0/Status 2005-08-07 12:38:48 +10:00
+++ 1.2/refman-5.0/Status 2005-08-25 10:41:04 +10:00
@@ -22,23 +22,24 @@
mysql-optimization
ndbcluster (Will update Limitations section after consulting with
Jeb and NDB devs)
+ mysql-apis
- 5.0 chapters awaiting major edits:
[more or less complete]
- 5.0 chapters (probably/hopefully) needing minimal if any edits:
- maxdb
- mysql-apis
- mysql-connectors
extending-mysql
problems
regexp
-- Chapters that are constant across MySQL versions (refman-common tree):
+- Chapters that are constant across MySQL versions (refman-common tree)
+ or are otherwise not currently part of edits for split:
credits
porting
gpl-license
floss-license-exception
news-x.x sections
+ maxdb
+ mysql-connectors
--- 1.4/refman-5.1/Status 2005-08-20 08:20:37 +10:00
+++ 1.5/refman-5.1/Status 2005-08-25 10:41:04 +10:00
@@ -1,5 +1,5 @@
- 5.1 chapters that have been edited:
- [all of them at this point]
+ mysql-apis
- 5.1 chapters awaiting major edits:
preface
@@ -31,19 +31,19 @@
precision-math
- 5.1 chapters (probably/hopefully) needing minimal if any edits:
- maxdb
- mysql-apis
- mysql-connectors
extending-mysql
problems
regexp
environment-variables
-- Chapters that are constant across MySQL versions (refman-common tree):
+- Chapters that are constant across MySQL versions (refman-common tree)
+ or are otherwise not currently part of edits for split:
credits
porting
gpl-license
floss-license-exception
news-x.x sections
+ maxdb
+ mysql-connectors
--- 1.23/refman-5.1/mysql-apis.xml 2005-08-24 06:02:03 +10:00
+++ 1.24/refman-5.1/mysql-apis.xml 2005-08-25 10:41:04 +10:00
@@ -6,12 +6,10 @@
%fixedchars.entities;
<!ENTITY % title.entities SYSTEM "refman-common/titles.ent">
%title.entities;
- <!ENTITY % versions.entities SYSTEM "versions.ent">
- %versions.entities;
]>
-<chapter id="mysql-apis">
+<chapter id='mysql-apis'>
- <title id="title-mysql-apis">&title-mysql-apis;</title>
+ <title id='title-mysql-apis'>&title-mysql-apis;</title>
<indexterm type="concept">
<primary>client tools</primary>
@@ -55,7 +53,7 @@
<section id="libmysqld">
- <title id="title-libmysqld">&title-libmysqld;</title>
+ <title id='title-libmysqld'>&title-libmysqld;</title>
<indexterm type="concept">
<primary>libmysqld</primary>
@@ -67,7 +65,7 @@
<section id="libmysqld-overview">
- <title id="title-libmysqld-overview">&title-libmysqld-overview;</title>
+ <title id='title-libmysqld-overview'>&title-libmysqld-overview;</title>
<para>
The embedded MySQL server library makes it possible to run a
@@ -150,7 +148,7 @@
<section id="libmysqld-compiling">
- <title id="title-libmysqld-compiling">&title-libmysqld-compiling;</title>
+ <title id='title-libmysqld-compiling'>&title-libmysqld-compiling;</title>
<para>
To get a <literal>libmysqld</literal> library you should
@@ -205,7 +203,7 @@
<section id="libmysqld-restrictions">
- <title id="title-libmysqld-restrictions">&title-libmysqld-restrictions;</title>
+ <title id='title-libmysqld-restrictions'>&title-libmysqld-restrictions;</title>
<para>
The embedded server has the following limitations:
@@ -216,7 +214,7 @@
<listitem>
<para>
No support for <literal>ISAM</literal> tables. (This is
- mainly done to make the library smaller)
+ mainly done to make the library smaller.)
</para>
</listitem>
@@ -235,7 +233,7 @@
<listitem>
<para>
No internal RAID support. (This is not normally needed as
- most current operating systems support big files).
+ most current operating systems support big files.)
</para>
</listitem>
@@ -275,7 +273,7 @@
<section id="libmysqld-options">
- <title id="title-libmysqld-options">&title-libmysqld-options;</title>
+ <title id='title-libmysqld-options'>&title-libmysqld-options;</title>
<indexterm type="concept">
<primary>defaults</primary>
@@ -328,7 +326,7 @@
<section id="libmysqld-todo">
- <title id="title-libmysqld-todo">&title-libmysqld-todo;</title>
+ <title id='title-libmysqld-todo'>&title-libmysqld-todo;</title>
<indexterm type="concept">
<primary>TODO</primary>
@@ -375,7 +373,7 @@
<section id="libmysqld-example">
- <title id="title-libmysqld-example">&title-libmysqld-example;</title>
+ <title id='title-libmysqld-example'>&title-libmysqld-example;</title>
<para>
These two example programs should work without any changes on a
@@ -609,8 +607,8 @@
lib := /usr/local/mysql/lib
# If you have not installed the MySQL software yet, try this instead
-#inc := $(HOME)/mysql-4.0/include
-#lib := $(HOME)/mysql-4.0/libmysqld
+#inc := $(HOME)/mysql-5.1/include
+#lib := $(HOME)/mysql-5.1/libmysqld
CC := gcc
CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
@@ -643,7 +641,7 @@
<section id="libmysqld-licensing">
- <title id="title-libmysqld-licensing">&title-libmysqld-licensing;</title>
+ <title id='title-libmysqld-licensing'>&title-libmysqld-licensing;</title>
<para>
We encourage everyone to promote free software by releasing code
@@ -660,7 +658,7 @@
<section id="c">
- <title id="title-c">&title-c;</title>
+ <title id='title-c'>&title-c;</title>
<indexterm type="concept">
<primary>C API</primary>
@@ -740,7 +738,7 @@
<section id="c-api-datatypes">
- <title id="title-c-api-datatypes">&title-c-api-datatypes;</title>
+ <title id='title-c-api-datatypes'>&title-c-api-datatypes;</title>
<itemizedlist>
@@ -1255,8 +1253,7 @@
</row>
<row>
<entry><literal>MYSQL_TYPE_NEWDECIMAL</literal></entry>
- <entry>Precision math <literal>DECIMAL</literal> or <literal>NUMERIC</literal>
- field (MySQL 5.0.3 and up)</entry>
+ <entry>Precision math <literal>DECIMAL</literal> or <literal>NUMERIC</literal></entry>
</row>
<row>
<entry><literal>MYSQL_TYPE_FLOAT</literal></entry>
@@ -1268,7 +1265,7 @@
</row>
<row>
<entry><literal>MYSQL_TYPE_BIT</literal></entry>
- <entry><literal>BIT</literal> field (MySQL 5.0.3 and up)</entry>
+ <entry><literal>BIT</literal> field</entry>
</row>
<row>
<entry><literal>MYSQL_TYPE_TIMESTAMP</literal></entry>
@@ -1347,7 +1344,7 @@
<section id="c-api-function-overview">
- <title id="title-c-api-function-overview">&title-c-api-function-overview;</title>
+ <title id='title-c-api-function-overview'>&title-c-api-function-overview;</title>
<indexterm type="concept">
<primary>C API</primary>
@@ -1488,7 +1485,7 @@
</row>
<row>
<entry><emphasis role="bold">mysql_get_server_version()</emphasis></entry>
- <entry>Returns version number of server as an integer (new in 4.1).</entry>
+ <entry>Returns version number of server as an integer.</entry>
</row>
<row>
<entry><emphasis role="bold">mysql_get_proto_info()</emphasis></entry>
@@ -1726,9 +1723,8 @@
<para>
<literal>mysql_library_init()</literal> and
- <literal>mysql_library_end()</literal> are available as of MySQL
- 5.0.3. These actually are <literal>#define</literal> symbols
- that make them equivalent to
+ <literal>mysql_library_end()</literal> are actually
+ <literal>#define</literal> symbols that make them equivalent to
<literal>mysql_server_init()</literal> and
<literal>mysql_server_end()</literal>, but the names more
clearly indicate that they should be called when beginning and
@@ -1755,7 +1751,7 @@
<literal>reconnect</literal> flag (part of the
<literal>MYSQL</literal> structure) to a value of
<literal>1</literal> in versions of the API strictly older than
- 5.0.3, of <literal>0</literal> in newer versions. A value of
+ 5.0.3, or <literal>0</literal> in newer versions. A value of
<literal>1</literal> for this flag indicates, in the event that
a query cannot be performed because of a lost connection, to try
reconnecting to the server before giving up. When you are done
@@ -1911,7 +1907,7 @@
<section id="c-api-functions">
- <title id="title-c-api-functions">&title-c-api-functions;</title>
+ <title id='title-c-api-functions'>&title-c-api-functions;</title>
<para>
In the descriptions here, a parameter or return value of
@@ -1955,7 +1951,7 @@
<section id="mysql-affected-rows">
- <title id="title-mysql-affected-rows">&title-mysql-affected-rows;</title>
+ <title id='title-mysql-affected-rows'>&title-mysql-affected-rows;</title>
<indexterm type="function">
<primary><literal>mysql_affected_rows()</literal></primary>
@@ -2046,7 +2042,7 @@
<section id="mysql-change-user">
- <title id="title-mysql-change-user">&title-mysql-change-user;</title>
+ <title id='title-mysql-change-user'>&title-mysql-change-user;</title>
<indexterm type="function">
<primary><literal>mysql_change_user()</literal></primary>
@@ -2070,10 +2066,6 @@
</para>
<para>
- This function was introduced in MySQL 3.23.3.
- </para>
-
- <para>
<literal>mysql_change_user()</literal> fails if the connected
user cannot be authenticated or doesn't have permission to use
the database. In this case the user and database are not
@@ -2087,11 +2079,10 @@
</para>
<para>
- Starting from MySQL 4.0.6 this command always performs a
- <literal>ROLLBACK</literal> of any active transactions, closes
- all temporary tables, unlocks all locked tables and resets the
- state as if one had done a new connect. This happens even if
- the user didn't change.
+ This command always performs a <literal>ROLLBACK</literal> of
+ any active transactions, closes all temporary tables, unlocks
+ all locked tables and resets the state as if one had done a
+ new connect. This happens even if the user didn't change.
</para>
<para>
@@ -2222,7 +2213,7 @@
<section id="mysql-character-set-name">
- <title id="title-mysql-character-set-name">&title-mysql-character-set-name;</title>
+ <title id='title-mysql-character-set-name'>&title-mysql-character-set-name;</title>
<indexterm type="function">
<primary><literal>mysql_character_set_name()</literal></primary>
@@ -2261,7 +2252,7 @@
<section id="mysql-close">
- <title id="title-mysql-close">&title-mysql-close;</title>
+ <title id='title-mysql-close'>&title-mysql-close;</title>
<indexterm type="function">
<primary><literal>mysql_close()</literal></primary>
@@ -2304,7 +2295,7 @@
<section id="mysql-connect">
- <title id="title-mysql-connect">&title-mysql-connect;</title>
+ <title id='title-mysql-connect'>&title-mysql-connect;</title>
<indexterm type="function">
<primary><literal>mysql_connect()</literal></primary>
@@ -2368,7 +2359,7 @@
<section id="mysql-create-db">
- <title id="title-mysql-create-db">&title-mysql-create-db;</title>
+ <title id='title-mysql-create-db'>&title-mysql-create-db;</title>
<indexterm type="function">
<primary><literal>mysql_create_db()</literal></primary>
@@ -2467,7 +2458,7 @@
<section id="mysql-data-seek">
- <title id="title-mysql-data-seek">&title-mysql-data-seek;</title>
+ <title id='title-mysql-data-seek'>&title-mysql-data-seek;</title>
<indexterm type="function">
<primary><literal>mysql_data_seek()</literal></primary>
@@ -2517,7 +2508,7 @@
<section id="mysql-debug">
- <title id="title-mysql-debug">&title-mysql-debug;</title>
+ <title id='title-mysql-debug'>&title-mysql-debug;</title>
<indexterm type="function">
<primary><literal>mysql_debug()</literal></primary>
@@ -2574,7 +2565,7 @@
<section id="mysql-drop-db">
- <title id="title-mysql-drop-db">&title-mysql-drop-db;</title>
+ <title id='title-mysql-drop-db'>&title-mysql-drop-db;</title>
<indexterm type="function">
<primary><literal>mysql_drop_db()</literal></primary>
@@ -2671,7 +2662,7 @@
<section id="mysql-dump-debug-info">
- <title id="title-mysql-dump-debug-info">&title-mysql-dump-debug-info;</title>
+ <title id='title-mysql-dump-debug-info'>&title-mysql-dump-debug-info;</title>
<indexterm type="function">
<primary><literal>mysql_dump_debug_info()</literal></primary>
@@ -2752,7 +2743,7 @@
<section id="mysql-eof">
- <title id="title-mysql-eof">&title-mysql-eof;</title>
+ <title id='title-mysql-eof'>&title-mysql-eof;</title>
<indexterm type="function">
<primary><literal>mysql_eof()</literal></primary>
@@ -2877,7 +2868,7 @@
<section id="mysql-errno">
- <title id="title-mysql-errno">&title-mysql-errno;</title>
+ <title id='title-mysql-errno'>&title-mysql-errno;</title>
<indexterm type="function">
<primary><literal>mysql_errno()</literal></primary>
@@ -2940,7 +2931,7 @@
<section id="mysql-error">
- <title id="title-mysql-error">&title-mysql-error;</title>
+ <title id='title-mysql-error'>&title-mysql-error;</title>
<indexterm type="function">
<primary><literal>mysql_error()</literal></primary>
@@ -3014,7 +3005,7 @@
<section id="mysql-escape-string">
- <title id="title-mysql-escape-string">&title-mysql-escape-string;</title>
+ <title id='title-mysql-escape-string'>&title-mysql-escape-string;</title>
<indexterm type="function">
<primary><literal>mysql_escape_string()</literal></primary>
@@ -3040,7 +3031,7 @@
<section id="mysql-fetch-field">
- <title id="title-mysql-fetch-field">&title-mysql-fetch-field;</title>
+ <title id='title-mysql-fetch-field'>&title-mysql-fetch-field;</title>
<indexterm type="function">
<primary><literal>mysql_fetch_field()</literal></primary>
@@ -3119,7 +3110,7 @@
<section id="mysql-fetch-fields">
- <title id="title-mysql-fetch-fields">&title-mysql-fetch-fields;</title>
+ <title id='title-mysql-fetch-fields'>&title-mysql-fetch-fields;</title>
<indexterm type="function">
<primary><literal>mysql_fetch_fields()</literal></primary>
@@ -3178,7 +3169,7 @@
<section id="mysql-fetch-field-direct">
- <title id="title-mysql-fetch-field-direct">&title-mysql-fetch-field-direct;</title>
+ <title id='title-mysql-fetch-field-direct'>&title-mysql-fetch-field-direct;</title>
<indexterm type="function">
<primary><literal>mysql_fetch_field_direct()</literal></primary>
@@ -3240,7 +3231,7 @@
<section id="mysql-fetch-lengths">
- <title id="title-mysql-fetch-lengths">&title-mysql-fetch-lengths;</title>
+ <title id='title-mysql-fetch-lengths'>&title-mysql-fetch-lengths;</title>
<indexterm type="function">
<primary><literal>mysql_fetch_lengths()</literal></primary>
@@ -3322,7 +3313,7 @@
<section id="mysql-fetch-row">
- <title id="title-mysql-fetch-row">&title-mysql-fetch-row;</title>
+ <title id='title-mysql-fetch-row'>&title-mysql-fetch-row;</title>
<indexterm type="function">
<primary><literal>mysql_fetch_row()</literal></primary>
@@ -3439,7 +3430,7 @@
<section id="mysql-field-count">
- <title id="title-mysql-field-count">&title-mysql-field-count;</title>
+ <title id='title-mysql-field-count'>&title-mysql-field-count;</title>
<indexterm type="function">
<primary><literal>mysql_field_count()</literal></primary>
@@ -3451,12 +3442,6 @@
</para>
<para>
- If you are using a version of MySQL earlier than Version
- 3.22.24, you should use <literal>unsigned int
- mysql_num_fields(MYSQL *mysql)</literal> instead.
- </para>
-
- <para>
<emphasis role="bold">Description</emphasis>
</para>
@@ -3551,7 +3536,7 @@
<section id="mysql-field-seek">
- <title id="title-mysql-field-seek">&title-mysql-field-seek;</title>
+ <title id='title-mysql-field-seek'>&title-mysql-field-seek;</title>
<indexterm type="function">
<primary><literal>mysql_field_seek()</literal></primary>
@@ -3597,7 +3582,7 @@
<section id="mysql-field-tell">
- <title id="title-mysql-field-tell">&title-mysql-field-tell;</title>
+ <title id='title-mysql-field-tell'>&title-mysql-field-tell;</title>
<indexterm type="function">
<primary><literal>mysql_field_tell()</literal></primary>
@@ -3638,7 +3623,7 @@
<section id="mysql-free-result">
- <title id="title-mysql-free-result">&title-mysql-free-result;</title>
+ <title id='title-mysql-free-result'>&title-mysql-free-result;</title>
<indexterm type="function">
<primary><literal>mysql_free_result()</literal></primary>
@@ -3685,7 +3670,7 @@
<section id="mysql-get-character-set-info">
- <title id="title-mysql-get-character-set-info">&title-mysql-get-character-set-info;</title>
+ <title id='title-mysql-get-character-set-info'>&title-mysql-get-character-set-info;</title>
<indexterm type="function">
<primary><literal>mysql_get_character_set_info()</literal></primary>
@@ -3707,10 +3692,6 @@
</para>
<para>
- This function was added in MySQL 5.0.10.
- </para>
-
- <para>
<emphasis role="bold">Example</emphasis>
</para>
@@ -3733,7 +3714,7 @@
<section id="mysql-get-client-info">
- <title id="title-mysql-get-client-info">&title-mysql-get-client-info;</title>
+ <title id='title-mysql-get-client-info'>&title-mysql-get-client-info;</title>
<indexterm type="function">
<primary><literal>mysql_get_client_info()</literal></primary>
@@ -3772,7 +3753,7 @@
<section id="mysql-get-client-version">
- <title id="title-mysql-get-client-version">&title-mysql-get-client-version;</title>
+ <title id='title-mysql-get-client-version'>&title-mysql-get-client-version;</title>
<indexterm type="function">
<primary><literal>mysql_get_client_version()</literal></primary>
@@ -3799,10 +3780,6 @@
</para>
<para>
- This function was added in MySQL 4.0.16.
- </para>
-
- <para>
<emphasis role="bold">Return Values</emphasis>
</para>
@@ -3822,7 +3799,7 @@
<section id="mysql-get-host-info">
- <title id="title-mysql-get-host-info">&title-mysql-get-host-info;</title>
+ <title id='title-mysql-get-host-info'>&title-mysql-get-host-info;</title>
<indexterm type="function">
<primary><literal>mysql_get_host_info()</literal></primary>
@@ -3862,7 +3839,7 @@
<section id="mysql-get-proto-info">
- <title id="title-mysql-get-proto-info">&title-mysql-get-proto-info;</title>
+ <title id='title-mysql-get-proto-info'>&title-mysql-get-proto-info;</title>
<indexterm type="function">
<primary><literal>mysql_get_proto_info()</literal></primary>
@@ -3902,7 +3879,7 @@
<section id="mysql-get-server-info">
- <title id="title-mysql-get-server-info">&title-mysql-get-server-info;</title>
+ <title id='title-mysql-get-server-info'>&title-mysql-get-server-info;</title>
<indexterm type="function">
<primary><literal>mysql_get_server_info()</literal></primary>
@@ -3940,7 +3917,7 @@
<section id="mysql-get-server-version">
- <title id="title-mysql-get-server-version">&title-mysql-get-server-version;</title>
+ <title id='title-mysql-get-server-version'>&title-mysql-get-server-version;</title>
<indexterm type="function">
<primary><literal>mysql_get_server_version()</literal></primary>
@@ -3973,7 +3950,7 @@
</programlisting>
<para>
- For example, 4.1.2 is returned as 40102.
+ For example, 5.1.5 is returned as 50105.
</para>
<para>
@@ -3994,7 +3971,7 @@
<section id="mysql-hex-string">
- <title id="title-mysql-hex-string">&title-mysql-hex-string;</title>
+ <title id='title-mysql-hex-string'>&title-mysql-hex-string;</title>
<indexterm type="function">
<primary><literal>mysql_hex_string()</literal></primary>
@@ -4091,7 +4068,7 @@
<section id="mysql-info">
- <title id="title-mysql-info">&title-mysql-info;</title>
+ <title id='title-mysql-info'>&title-mysql-info;</title>
<indexterm type="function">
<primary><literal>mysql_info()</literal></primary>
@@ -4205,7 +4182,7 @@
<section id="mysql-init">
- <title id="title-mysql-init">&title-mysql-init;</title>
+ <title id='title-mysql-init'>&title-mysql-init;</title>
<indexterm type="function">
<primary><literal>mysql_init()</literal></primary>
@@ -4254,7 +4231,7 @@
<section id="mysql-insert-id">
- <title id="title-mysql-insert-id">&title-mysql-insert-id;</title>
+ <title id='title-mysql-insert-id'>&title-mysql-insert-id;</title>
<indexterm type="function">
<primary><literal>mysql_insert_id()</literal></primary>
@@ -4404,7 +4381,7 @@
<section id="mysql-kill">
- <title id="title-mysql-kill">&title-mysql-kill;</title>
+ <title id='title-mysql-kill'>&title-mysql-kill;</title>
<indexterm type="function">
<primary><literal>mysql_kill()</literal></primary>
@@ -4484,7 +4461,7 @@
<section id="mysql-library-init">
- <title id="title-mysql-library-init">&title-mysql-library-init;</title>
+ <title id='title-mysql-library-init'>&title-mysql-library-init;</title>
<indexterm type="function">
<primary><literal>mysql_library_init()</literal></primary>
@@ -4501,8 +4478,7 @@
<para>
This is a synonym for the
- <literal>mysql_server_init()</literal> function. It was added
- in MySQL 5.0.3.
+ <literal>mysql_server_init()</literal> function.
</para>
<para>
@@ -4514,7 +4490,7 @@
<section id="mysql-library-end">
- <title id="title-mysql-library-end">&title-mysql-library-end;</title>
+ <title id='title-mysql-library-end'>&title-mysql-library-end;</title>
<indexterm type="function">
<primary><literal>mysql_library_end()</literal></primary>
@@ -4530,8 +4506,7 @@
<para>
This is a synonym for the
- <literal>mysql_server_end()</literal> function. It was added
- in MySQL 5.0.3.
+ <literal>mysql_server_end()</literal> function.
</para>
<para>
@@ -4543,7 +4518,7 @@
<section id="mysql-list-dbs">
- <title id="title-mysql-list-dbs">&title-mysql-list-dbs;</title>
+ <title id='title-mysql-list-dbs'>&title-mysql-list-dbs;</title>
<indexterm type="function">
<primary><literal>mysql_list_dbs()</literal></primary>
@@ -4647,7 +4622,7 @@
<section id="mysql-list-fields">
- <title id="title-mysql-list-fields">&title-mysql-list-fields;</title>
+ <title id='title-mysql-list-fields'>&title-mysql-list-fields;</title>
<indexterm type="function">
<primary><literal>mysql_list_fields()</literal></primary>
@@ -4748,7 +4723,7 @@
<section id="mysql-list-processes">
- <title id="title-mysql-list-processes">&title-mysql-list-processes;</title>
+ <title id='title-mysql-list-processes'>&title-mysql-list-processes;</title>
<indexterm type="function">
<primary><literal>mysql_list_processes()</literal></primary>
@@ -4836,7 +4811,7 @@
<section id="mysql-list-tables">
- <title id="title-mysql-list-tables">&title-mysql-list-tables;</title>
+ <title id='title-mysql-list-tables'>&title-mysql-list-tables;</title>
<indexterm type="function">
<primary><literal>mysql_list_tables()</literal></primary>
@@ -4860,7 +4835,8 @@
‘<literal>_</literal>’, or may be a
<literal>NULL</literal> pointer to match all tables. Calling
<literal>mysql_list_tables()</literal> is similar to executing
- the query <literal>SHOW tables [LIKE wild]</literal>.
+ the query <literal>SHOW tables [LIKE
+ <replaceable>wild</replaceable>]</literal>.
</para>
<para>
@@ -4929,7 +4905,7 @@
<section id="mysql-num-fields">
- <title id="title-mysql-num-fields">&title-mysql-num-fields;</title>
+ <title id='title-mysql-num-fields'>&title-mysql-num-fields;</title>
<indexterm type="function">
<primary><literal>mysql_num_fields()</literal></primary>
@@ -4945,18 +4921,9 @@
</para>
<para>
- Or:
- </para>
-
- <para>
- <literal>unsigned int mysql_num_fields(MYSQL *mysql)</literal>
- </para>
-
- <para>
- The second form doesn't work on MySQL 3.22.24 or newer. To
- pass a <literal>MYSQL*</literal> argument, you must use
+ To pass a <literal>MYSQL*</literal> argument instead, use
<literal>unsigned int mysql_field_count(MYSQL
- *mysql)</literal> instead.
+ *mysql)</literal>.
</para>
<para>
@@ -5054,7 +5021,7 @@
<section id="mysql-num-rows">
- <title id="title-mysql-num-rows">&title-mysql-num-rows;</title>
+ <title id='title-mysql-num-rows'>&title-mysql-num-rows;</title>
<indexterm type="function">
<primary><literal>mysql_num_rows()</literal></primary>
@@ -5105,7 +5072,7 @@
<section id="mysql-options">
- <title id="title-mysql-options">&title-mysql-options;</title>
+ <title id='title-mysql-options'>&title-mysql-options;</title>
<indexterm type="function">
<primary><literal>mysql_options()</literal></primary>
@@ -5269,13 +5236,13 @@
<entry><literal>my_bool *</literal></entry>
<entry>Enable or disable reporting of data truncation errors for prepared
statements via <literal>MYSQL_BIND.error</literal>.
- (Default: disabled) New in 5.0.3.</entry>
+ (Default: disabled.)</entry>
</row>
<row>
<entry><literal>MYSQL_SECURE_AUTH</literal></entry>
<entry><literal>my_bool*</literal></entry>
- <entry>Whether to connect to a server that does not support the new 4.1.1
- password hashing.</entry>
+ <entry>Whether to connect to a server that does not support the
+ password hashing used in MySQL 4.1.1 and later.</entry>
</row>
<row>
<entry><literal>MYSQL_SET_CHARSET_DIR</literal></entry>
@@ -5386,7 +5353,7 @@
</row>
<row>
<entry><literal>protocol={TCP | SOCKET | PIPE | MEMORY}</literal></entry>
- <entry>The protocol to use when connecting to server (New in 4.1)</entry>
+ <entry>The protocol to use when connecting to the server.</entry>
</row>
<row>
<entry><literal>port</literal></entry>
@@ -5399,8 +5366,7 @@
</row>
<row>
<entry><literal>shared-memory-base-name=<replaceable>name</replaceable></literal></entry>
- <entry>Shared memory name to use to connect to server (default is "MYSQL"). New
- in MySQL 4.1.</entry>
+ <entry>Shared memory name to use to connect to server (default is "MYSQL").</entry>
</row>
<row>
<entry><literal>socket</literal></entry>
@@ -5414,10 +5380,15 @@
</tgroup>
</informaltable>
+ <remark role="todo">
+ [js] Verify that the next statement is still true in 5.1.
+ </remark>
+
<para>
Note that <literal>timeout</literal> has been replaced by
<literal>connect-timeout</literal>, but
- <literal>timeout</literal> still works for a while.
+ <literal>timeout</literal> is still supported in MySQL 5.1 for
+ backwards compatibility.
</para>
<para>
@@ -5461,7 +5432,7 @@
<section id="mysql-ping">
- <title id="title-mysql-ping">&title-mysql-ping;</title>
+ <title id='title-mysql-ping'>&title-mysql-ping;</title>
<indexterm type="function">
<primary><literal>mysql_ping()</literal></primary>
@@ -5540,7 +5511,7 @@
<section id="mysql-query">
- <title id="title-mysql-query">&title-mysql-query;</title>
+ <title id='title-mysql-query'>&title-mysql-query;</title>
<indexterm type="function">
<primary><literal>mysql_query()</literal></primary>
@@ -5642,7 +5613,7 @@
<section id="mysql-real-connect">
- <title id="title-mysql-real-connect">&title-mysql-real-connect;</title>
+ <title id='title-mysql-real-connect'>&title-mysql-real-connect;</title>
<indexterm type="function">
<primary><literal>mysql_real_connect()</literal></primary>
@@ -5808,15 +5779,14 @@
string (separated by
‘<literal>;</literal>’). If this flag
is not set, multiple-statement execution is
- disabled. New in 4.1.</entry>
+ disabled.</entry>
</row>
<row>
<entry><literal>CLIENT_MULTI_RESULTS</literal></entry>
<entry>Tell the server that the client can handle multiple result sets from
multiple-statement executions or stored
procedures. This is automatically set if
- <literal>CLIENT_MULTI_STATEMENTS</literal> is set.
- New in 4.1.</entry>
+ <literal>CLIENT_MULTI_STATEMENTS</literal> is set.</entry>
</row>
<row>
<entry><literal>CLIENT_NO_SCHEMA</literal></entry>
@@ -6009,9 +5979,9 @@
<literal>mysql_real_connect()</literal> sets the
<literal>reconnect</literal> flag (part of the
<literal>MYSQL</literal> structure) to a value of
- <literal>1</literal> in versions of the API strictly older
- than 5.0.3, of <literal>0</literal> in newer versions. A value
- of <literal>1</literal> for this flag indicates, in the event
+ <literal>1</literal> in versions of the API older than 5.0.3,
+ or <literal>0</literal> in newer versions. A value of
+ <literal>1</literal> for this flag indicates, in the event
that a query cannot be performed because of a lost connection,
to try reconnecting to the server before giving up.
</para>
@@ -6020,7 +5990,7 @@
<section id="mysql-real-escape-string">
- <title id="title-mysql-real-escape-string">&title-mysql-real-escape-string;</title>
+ <title id='title-mysql-real-escape-string'>&title-mysql-real-escape-string;</title>
<indexterm type="function">
<primary><literal>mysql_real_escape_string()</literal></primary>
@@ -6141,7 +6111,7 @@
<section id="mysql-real-query">
- <title id="title-mysql-real-query">&title-mysql-real-query;</title>
+ <title id='title-mysql-real-query'>&title-mysql-real-query;</title>
<indexterm type="function">
<primary><literal>mysql_real_query()</literal></primary>
@@ -6245,7 +6215,7 @@
<section id="mysql-reload">
- <title id="title-mysql-reload">&title-mysql-reload;</title>
+ <title id='title-mysql-reload'>&title-mysql-reload;</title>
<indexterm type="function">
<primary><literal>mysql_reload()</literal></primary>
@@ -6331,7 +6301,7 @@
<section id="mysql-row-seek">
- <title id="title-mysql-row-seek">&title-mysql-row-seek;</title>
+ <title id='title-mysql-row-seek'>&title-mysql-row-seek;</title>
<indexterm type="function">
<primary><literal>mysql_row_seek()</literal></primary>
@@ -6385,7 +6355,7 @@
<section id="mysql-row-tell">
- <title id="title-mysql-row-tell">&title-mysql-row-tell;</title>
+ <title id='title-mysql-row-tell'>&title-mysql-row-tell;</title>
<indexterm type="function">
<primary><literal>mysql_row_tell()</literal></primary>
@@ -6432,7 +6402,7 @@
<section id="mysql-select-db">
- <title id="title-mysql-select-db">&title-mysql-select-db;</title>
+ <title id='title-mysql-select-db'>&title-mysql-select-db;</title>
<indexterm type="function">
<primary><literal>mysql_select_db()</literal></primary>
@@ -6521,7 +6491,7 @@
<section id="mysql-set-character-set">
- <title id="title-mysql-set-character-set">&title-mysql-set-character-set;</title>
+ <title id='title-mysql-set-character-set'>&title-mysql-set-character-set;</title>
<indexterm type="function">
<primary><literal>mysql_set_character_set()</literal></primary>
@@ -6549,10 +6519,6 @@
</para>
<para>
- This function was added in MySQL 5.0.7.
- </para>
-
- <para>
<emphasis role="bold">Return Values</emphasis>
</para>
@@ -6584,7 +6550,7 @@
<section id="mysql-set-server-option">
- <title id="title-mysql-set-server-option">&title-mysql-set-server-option;</title>
+ <title id='title-mysql-set-server-option'>&title-mysql-set-server-option;</title>
<indexterm type="function">
<primary><literal>mysql_set_server_option()</literal></primary>
@@ -6685,7 +6651,7 @@
<section id="mysql-shutdown">
- <title id="title-mysql-shutdown">&title-mysql-shutdown;</title>
+ <title id='title-mysql-shutdown'>&title-mysql-shutdown;</title>
<indexterm type="function">
<primary><literal>mysql_shutdown()</literal></primary>
@@ -6700,23 +6666,20 @@
<emphasis role="bold">Description</emphasis>
</para>
+ <remark role="todo">
+ [js] Verify that the next para remains true in 5.1.
+ </remark>
+
<para>
Asks the database server to shut down. The connected user must
- have <literal>SHUTDOWN</literal> privileges. The
- <literal>shutdown_level</literal> argument was added in MySQL
- 4.1.3 (and 5.0.1). The MySQL server currently supports only
- one type (level of gracefulness) of shutdown;
+ have <literal>SHUTDOWN</literal> privileges. MySQL 5.1 servers
+ support only one type of shutdown;
<literal>shutdown_level</literal> must be equal to
- <literal>SHUTDOWN_DEFAULT</literal>. Later we wil add more
- levels and then the <literal>shutdown_level</literal> argument
- will enable us to choose the desired level. MySQL servers and
- MySQL clients before and after 4.1.3 are compatible; MySQL
- servers newer than 4.1.3 accept the
- <literal>mysql_shutdown(MYSQL *mysql)</literal> call, and
- MySQL servers older than 4.1.3 accept the new
- <literal>mysql_shutdown()</literal> call. But dynamically
- linked executables which have been compiled with older
- versions of <literal>libmysqlclient</literal> headers, and
+ <literal>SHUTDOWN_DEFAULT</literal>. Additional shutdown
+ levels are planned and then the <literal>shutdown_level</literal> argument
+ will enable us to choose the desired level. Dynamically linked
+ executables which have been compiled with older versions of
+ <literal>libmysqlclient</literal> headers, and
call <literal>mysql_shutdown()</literal>, need to be used with
the old <literal>libmysqlclient</literal> dynamic library.
</para>
@@ -6786,7 +6749,7 @@
<section id="mysql-sqlstate">
- <title id="title-mysql-sqlstate">&title-mysql-sqlstate;</title>
+ <title id='title-mysql-sqlstate'>&title-mysql-sqlstate;</title>
<indexterm type="function">
<primary><literal>mysql_sqlstate()</literal></primary>
@@ -6810,9 +6773,9 @@
</para>
<para>
- Note that not all MySQL errors are yet mapped to SQLSTATE's.
- The value <literal>'HY000'</literal> (general error) is used
- for unmapped errors.
+ Note that not all MySQL errors are mapped to SQLSTATE error
+ codes. The value <literal>'HY000'</literal> (general error) is
+ used for unmapped errors.
</para>
<para>
@@ -6838,7 +6801,7 @@
<section id="mysql-ssl-set">
- <title id="title-mysql-ssl-set">&title-mysql-ssl-set;</title>
+ <title id='title-mysql-ssl-set'>&title-mysql-ssl-set;</title>
<indexterm type="function">
<primary><literal>mysql_ssl_set()</literal></primary>
@@ -6928,7 +6891,7 @@
<section id="mysql-stat">
- <title id="title-mysql-stat">&title-mysql-stat;</title>
+ <title id='title-mysql-stat'>&title-mysql-stat;</title>
<indexterm type="function">
<primary><literal>mysql_stat()</literal></primary>
@@ -7010,7 +6973,7 @@
<section id="mysql-store-result">
- <title id="title-mysql-store-result">&title-mysql-store-result;</title>
+ <title id='title-mysql-store-result'>&title-mysql-store-result;</title>
<indexterm type="function">
<primary><literal>mysql_store_result()</literal></primary>
@@ -7179,7 +7142,7 @@
<section id="mysql-thread-id">
- <title id="title-mysql-thread-id">&title-mysql-thread-id;</title>
+ <title id='title-mysql-thread-id'>&title-mysql-thread-id;</title>
<indexterm type="function">
<primary><literal>mysql_thread_id()</literal></primary>
@@ -7226,7 +7189,7 @@
<section id="mysql-use-result">
- <title id="title-mysql-use-result">&title-mysql-use-result;</title>
+ <title id='title-mysql-use-result'>&title-mysql-use-result;</title>
<indexterm type="function">
<primary><literal>mysql_use_result()</literal></primary>
@@ -7386,7 +7349,7 @@
<section id="mysql-warning-count">
- <title id="title-mysql-warning-count">&title-mysql-warning-count;</title>
+ <title id='title-mysql-warning-count'>&title-mysql-warning-count;</title>
<indexterm type="function">
<primary><literal>mysql_warning_count()</literal>.</primary>
@@ -7426,7 +7389,7 @@
<section id="mysql-commit">
- <title id="title-mysql-commit">&title-mysql-commit;</title>
+ <title id='title-mysql-commit'>&title-mysql-commit;</title>
<indexterm type="function">
<primary><literal>mysql_commit()</literal>.</primary>
@@ -7445,13 +7408,14 @@
</para>
<para>
- The action of this function is subject to the value of the
- <literal>completion_type</literal> system variable. In
- particular, if the value of <literal>completion_type</literal>
- is 2, the server performs a release after terminating a
- transaction and closes the client connection. The client
- program should call <literal>mysql_close()</literal> to close
- the connection from the client side.
+ In MySQL 5.1, the action of this function is subject to
+ the value of the <literal>completion_type</literal> system
+ variable. In particular, if the value of
+ <literal>completion_type</literal> is 2, the server performs a
+ release after terminating a transaction and closes the client
+ connection. The client program should call
+ <literal>mysql_close()</literal> to close the connection from
+ the client side.
</para>
<para>
@@ -7474,7 +7438,7 @@
<section id="mysql-rollback">
- <title id="title-mysql-rollback">&title-mysql-rollback;</title>
+ <title id='title-mysql-rollback'>&title-mysql-rollback;</title>
<indexterm type="function">
<primary><literal>mysql_rollback()</literal>.</primary>
@@ -7493,13 +7457,14 @@
</para>
<para>
- The action of this function is subject to the value of the
- <literal>completion_type</literal> system variable. In
- particular, if the value of <literal>completion_type</literal>
- is 2, the server performs a release after terminating a
- transaction and closes the client connection. The client
- program should call <literal>mysql_close()</literal> to close
- the connection from the client side.
+ In MySQL 5.1, the action of this function is subject to
+ the value of the <literal>completion_type</literal> system
+ variable. In particular, if the value of
+ <literal>completion_type</literal> is 2, the server performs a
+ release after terminating a transaction and closes the client
+ connection. The client program should call
+ <literal>mysql_close()</literal> to close the connection from
+ the client side.
</para>
<para>
@@ -7522,7 +7487,7 @@
<section id="mysql-autocommit">
- <title id="title-mysql-autocommit">&title-mysql-autocommit;</title>
+ <title id='title-mysql-autocommit'>&title-mysql-autocommit;</title>
<indexterm type="function">
<primary><literal>mysql_autocommit()</literal>.</primary>
@@ -7562,7 +7527,7 @@
<section id="mysql-more-results">
- <title id="title-mysql-more-results">&title-mysql-more-results;</title>
+ <title id='title-mysql-more-results'>&title-mysql-more-results;</title>
<indexterm type="function">
<primary><literal>mysql_more_results()</literal>.</primary>
@@ -7614,7 +7579,7 @@
<section id="mysql-next-result">
- <title id="title-mysql-next-result">&title-mysql-next-result;</title>
+ <title id='title-mysql-next-result'>&title-mysql-next-result;</title>
<indexterm type="function">
<primary><literal>mysql_next_result()</literal>.</primary>
@@ -7745,10 +7710,10 @@
<section id="c-api-prepared-statements">
- <title id="title-c-api-prepared-statements">&title-c-api-prepared-statements;</title>
+ <title id='title-c-api-prepared-statements'>&title-c-api-prepared-statements;</title>
<para>
- As of MySQL 4.1, the client/server protocol provides for the use
+ In MySQL 5.1, the 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 <literal>mysql_stmt_init()</literal>
@@ -7775,28 +7740,25 @@
server more efficient.
</para>
+ <remark role="todo">
+ [js] Verify that the following still holds in 5.1.
+ </remark>
+
<para>
The following statements can be used as prepared statements:
<literal>CREATE TABLE</literal>, <literal>DELETE</literal>,
<literal>DO</literal>, <literal>INSERT</literal>,
<literal>REPLACE</literal>, <literal>SELECT</literal>,
<literal>SET</literal>, <literal>UPDATE</literal>, and most
- <literal>SHOW</literal> statements. Other statements are not yet
- supported.
+ <literal>SHOW</literal> statements. Other statements are not
+ supported in MySQL 5.1.
</para>
</section>
<section id="c-api-prepared-statement-datatypes">
- <title id="title-c-api-prepared-statement-datatypes">&title-c-api-prepared-statement-datatypes;</title>
-
- <para>
- <emphasis role="bold">Note</emphasis>: Some incompatible changes
- were made in MySQL 4.1.2. See
- <xref linkend="c-api-prepared-statement-functions"/> for
- details.
- </para>
+ <title id='title-c-api-prepared-statement-datatypes'>&title-c-api-prepared-statement-datatypes;</title>
<para>
Prepared statements mainly use the <literal>MYSQL_STMT</literal>
@@ -8049,8 +8011,7 @@
<literal>MYSQL_BIND</literal> structures for parameters
in which truncation occurred. Truncation indicates loss
of sign or significant digits, or that a string was too
- long to fit in a column. The <literal>error</literal>
- member was added in MySQL 5.0.3.
+ long to fit in a column.
</para>
</listitem>
@@ -8097,11 +8058,11 @@
following members:
</para>
- <remark role="todo">
- rather than say TIME for the hour item (which doesn't make
- much sense; don't minute/second apply, too), say for each
- temporal type which structure members are used for it.
- </remark>
+<!--
+ TODO: rather than say TIME for the hour item (which doesn't make much
+ sense; don't minute/second apply, too), say for each temporal type
+ which structure members are used for it.
+ -->
<itemizedlist>
@@ -8180,10 +8141,10 @@
<literal>unsigned long second_part</literal>
</para>
- <remark role="todo">
- not quite true that it's unused; we need a good
- characterization of when it's allowable/available.
- </remark>
+<!--
+ TODO: not quite true that it's unused; we need a good characterization
+ of when it's allowable/available.
+-->
<para>
The fractional part of the second. This member currently
@@ -8193,13 +8154,9 @@
</itemizedlist>
- <remark role="todo">
- does neg only to TIME/TIMESTAMP?
- </remark>
-
- <remark role="todo">
- second_part probably applies only to TIMESTAMP?
- </remark>
+<!-- TODO: does neg only to TIME/TIMESTAMP? -->
+
+<!-- TODO: second_part probably applies only to TIMESTAMP? -->
<para>
Only those parts of a <literal>MYSQL_TIME</literal>
@@ -8291,32 +8248,32 @@
<row>
<entry><literal>MYSQL_TYPE_STRING</literal></entry>
<entry><literal>CHAR</literal></entry>
- <entry/>
+ <entry></entry>
</row>
<row>
<entry><literal>MYSQL_TYPE_VAR_STRING</literal></entry>
<entry><literal>VARCHAR</literal></entry>
- <entry/>
+ <entry></entry>
</row>
<row>
<entry><literal>MYSQL_TYPE_TINY_BLOB</literal></entry>
<entry><literal>TINYBLOB/TINYTEXT</literal></entry>
- <entry/>
+ <entry></entry>
</row>
<row>
<entry><literal>MYSQL_TYPE_BLOB</literal></entry>
<entry><literal>BLOB/TEXT</literal></entry>
- <entry/>
+ <entry></entry>
</row>
<row>
<entry><literal>MYSQL_TYPE_MEDIUM_BLOB</literal></entry>
<entry><literal>MEDIUMBLOB/MEDIUMTEXT</literal></entry>
- <entry/>
+ <entry></entry>
</row>
<row>
<entry><literal>MYSQL_TYPE_LONG_BLOB</literal></entry>
<entry><literal>LONGBLOB/LONGTEXT</literal></entry>
- <entry/>
+ <entry></entry>
</row>
</tbody>
</tgroup>
@@ -8326,19 +8283,14 @@
Implicit type conversion may be performed in both directions.
</para>
- <remark role="todo">
- Explain what that means and give some examples. Need list of
- </remark>
-
- <remark>
- allowable/supported conversions
- </remark>
+<!-- TODO: Explain what that means and give some examples. Need list of
+ allowable/supported conversions -->
</section>
<section id="c-api-prepared-statement-function-overview">
- <title id="title-c-api-prepared-statement-function-overview">&title-c-api-prepared-statement-function-overview;</title>
+ <title id='title-c-api-prepared-statement-function-overview'>&title-c-api-prepared-statement-function-overview;</title>
<indexterm type="concept">
<primary>C Prepared statement API</primary>
@@ -8351,26 +8303,14 @@
</indexterm>
<para>
- <emphasis role="bold">Note</emphasis>: Some incompatible changes
- were made in MySQL 4.1.2. See
- <xref linkend="c-api-prepared-statement-functions"/> for
- details.
- </para>
-
- <para>
The functions available for prepared statement processing are
summarized here and described in greater detail in a later
section. See
<xref linkend="c-api-prepared-statement-functions"/>.
</para>
- <remark role="todo">
- missing functions here (that are listed in mysql.h)
- </remark>
-
- <remark>
- mysql_stmt_param_metadata() 4.1.2 [not implemented yet?]
- </remark>
+<!-- TODO: missing functions here (that are listed in mysql.h)
+ mysql_stmt_param_metadata() 4.1.2 [not implemented yet?] -->
<informaltable>
<tgroup cols="2">
@@ -8458,17 +8398,8 @@
<row>
<entry><emphasis role="bold">mysql_stmt_param_count()</emphasis></entry>
<entry>Returns the number of parameters in a prepared SQL statement.
-
- <remark>
- 2004-03-03: mysql_stmt_param_metadata is not
- implemented yet,
- </remark>
-
-
-
- <remark>
- only stub is present in the library
- </remark></entry>
+<!-- 2004-03-03: mysql_stmt_param_metadata is not implemented yet, only
+ stub is present in the library --></entry>
</row>
<row>
<entry><emphasis role="bold">mysql_stmt_param_metadata()</emphasis></entry>
@@ -8477,10 +8408,7 @@
<row>
<entry><emphasis role="bold">mysql_stmt_prepare()</emphasis></entry>
<entry>Prepares an SQL string for execution.
-
- <remark role="todo">
- this description is not helpful.
- </remark></entry>
+<!-- TODO: this description is not helpful. --></entry>
</row>
<row>
<entry><emphasis role="bold">mysql_stmt_reset()</emphasis></entry>
@@ -8722,88 +8650,27 @@
<section id="c-api-prepared-statement-functions">
- <title id="title-c-api-prepared-statement-functions">&title-c-api-prepared-statement-functions;</title>
-
- <para>
- To prepare and execute queries, use the functions in the
- following sections.
- </para>
+ <title id='title-c-api-prepared-statement-functions'>&title-c-api-prepared-statement-functions;</title>
<para>
- In MySQL 4.1.2, the names of several prepared statement
- functions were changed:
- </para>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colwidth="30*"/>
- <colspec colwidth="70*"/>
- <tbody>
- <row>
- <entry><emphasis role="bold">Old Name</emphasis></entry>
- <entry><emphasis role="bold">New Name</emphasis></entry>
- </row>
- <row>
- <entry><literal>mysql_bind_param()</literal></entry>
- <entry><literal>mysql_stmt_bind_param()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_bind_result()</literal></entry>
- <entry><literal>mysql_stmt_bind_result()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_prepare()</literal></entry>
- <entry><literal>mysql_stmt_prepare()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_execute()</literal></entry>
- <entry><literal>mysql_stmt_execute()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_fetch()</literal></entry>
- <entry><literal>mysql_stmt_fetch()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_fetch_column()</literal></entry>
- <entry><literal>mysql_stmt_fetch_column()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_param_count()</literal></entry>
- <entry><literal>mysql_stmt_param_count()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_param_result()</literal></entry>
- <entry><literal>mysql_stmt_param_metadata()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_get_metadata()</literal></entry>
- <entry><literal>mysql_stmt_result_metadata()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_send_long_data()</literal></entry>
- <entry><literal>mysql_stmt_send_long_data()</literal></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ To prepare and execute queries, use the functions described in
+ detail in the following sections.
+ </para>
<para>
- All functions that operate with a <literal>MYSQL_STMT</literal>
- structure begin with the prefix <literal>mysql_stmt_</literal>.
+ Note that all functions operating with a
+ <literal>MYSQL_STMT</literal> structure begin with the prefix
+ <literal>mysql_stmt_</literal>.
</para>
<para>
- Also in 4.1.2, the signature of the
- <literal>mysql_stmt_prepare()</literal> 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
+ To create a <literal>MYSQL_STMT</literal> handle, use the
<literal>mysql_stmt_init()</literal> function.
</para>
<section id="mysql-stmt-affected-rows">
- <title id="title-mysql-stmt-affected-rows">&title-mysql-stmt-affected-rows;</title>
+ <title id='title-mysql-stmt-affected-rows'>&title-mysql-stmt-affected-rows;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_affected_rows()</literal></primary>
@@ -8829,11 +8696,9 @@
<literal>mysql_num_rows()</literal>.
</para>
- <remark role="todo">
- For SELECT, are there any caveats on when you must wait to
- call this function, such as after all the rows have been
- fetched or after calling mysql_stmt_store_result()?
- </remark>
+<!-- TODO: For SELECT, are there any caveats on when you must wait to
+ call this function, such as after all the rows have been fetched
+ or after calling mysql_stmt_store_result()? -->
<para>
<emphasis role="bold">Return Values</emphasis>
@@ -8882,7 +8747,7 @@
<section id="mysql-stmt-attr-get">
- <title id="title-mysql-stmt-attr-get">&title-mysql-stmt-attr-get;</title>
+ <title id='title-mysql-stmt-attr-get'>&title-mysql-stmt-attr-get;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_attr_get()</literal></primary>
@@ -8911,9 +8776,8 @@
</para>
<para>
- See <literal>mysql_stmt_attr_set()</literal> for a list of
- options and option types. See
- <xref linkend="mysql-stmt-attr-set"/>.
+ See <xref linkend="mysql-stmt-attr-set"/> for a list of
+ options and option types.
</para>
<para>
@@ -8937,7 +8801,7 @@
<section id="mysql-stmt-attr-set">
- <title id="title-mysql-stmt-attr-set">&title-mysql-stmt-attr-set;</title>
+ <title id='title-mysql-stmt-attr-set'>&title-mysql-stmt-attr-set;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_attr_set()</literal></primary>
@@ -9023,12 +8887,6 @@
</para>
<para>
- The <literal>STMT_ATTR_CURSOR_TYPE</literal> option was added
- in MySQL 5.0.2. The <literal>STMT_ATTR_PREFETCH_ROWS</literal>
- option was added in MySQL 5.0.6.
- </para>
-
- <para>
<emphasis role="bold">Return Values</emphasis>
</para>
@@ -9049,7 +8907,7 @@
<section id="mysql-stmt-bind-param">
- <title id="title-mysql-stmt-bind-param">&title-mysql-stmt-bind-param;</title>
+ <title id='title-mysql-stmt-bind-param'>&title-mysql-stmt-bind-param;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_bind_param()</literal></primary>
@@ -9174,7 +9032,7 @@
<section id="mysql-stmt-bind-result">
- <title id="title-mysql-stmt-bind-result">&title-mysql-stmt-bind-result;</title>
+ <title id='title-mysql-stmt-bind-result'>&title-mysql-stmt-bind-result;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_bind_result()</literal></primary>
@@ -9294,7 +9152,7 @@
<section id="mysql-stmt-close">
- <title id="title-mysql-stmt-close">&title-mysql-stmt-close;</title>
+ <title id='title-mysql-stmt-close'>&title-mysql-stmt-close;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_close()</literal></primary>
@@ -9369,7 +9227,7 @@
<section id="mysql-stmt-data-seek">
- <title id="title-mysql-stmt-data-seek">&title-mysql-stmt-data-seek;</title>
+ <title id='title-mysql-stmt-data-seek'>&title-mysql-stmt-data-seek;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_data_seek()</literal></primary>
@@ -9418,7 +9276,7 @@
<section id="mysql-stmt-errno">
- <title id="title-mysql-stmt-errno">&title-mysql-stmt-errno;</title>
+ <title id='title-mysql-stmt-errno'>&title-mysql-stmt-errno;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_errno()</literal></primary>
@@ -9468,7 +9326,7 @@
<section id="mysql-stmt-error">
- <title id="title-mysql-stmt-error">&title-mysql-stmt-error;</title>
+ <title id='title-mysql-stmt-error'>&title-mysql-stmt-error;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_error()</literal>.</primary>
@@ -9533,7 +9391,7 @@
<section id="mysql-stmt-execute">
- <title id="title-mysql-stmt-execute">&title-mysql-stmt-execute;</title>
+ <title id='title-mysql-stmt-execute'>&title-mysql-stmt-execute;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_execute()</literal></primary>
@@ -9555,9 +9413,7 @@
supplied data.
</para>
- <remark role="todo">
- what about REPLACE?
- </remark>
+<!-- TODO: what about REPLACE? -->
<para>
If the statement is an <literal>UPDATE</literal>,
@@ -9583,38 +9439,20 @@
before opening a new one.
</para>
- <remark>
- I've commented out the implementation details; they might
- change - PD
- </remark>
-
- <remark>
- @code{mysql_stmt_execute()} opens no cursor for result sets
- that contain
- </remark>
-
- <remark>
- zero rows or one row. It also opens no cursor for statements
- such as
- </remark>
-
- <remark>
- @code{EXPLAIN} and @code{SHOW} statements such as @code{SHOW
- VARIABLES} that
- </remark>
-
- <remark>
- are not based on the contents of @code{INFORMATION_SCHEMA}. In
- such cases,
- </remark>
-
- <remark>
- the result set is transferred to the client implicitly with
- </remark>
+<!-- NOTE: I've commented out the implementation details; they might change - PD -->
- <remark>
- @code{mysql_stmt_store_result()}.
- </remark>
+<!--
+ <para>
+ <literal>mysql_stmt_execute()</literal> opens no cursor for
+ result sets that contain zero rows or one row. It also opens no
+ cursor for <literal>EXPLAIN</literal> or <literal>SHOW</literal>
+ statements (such as <literal>SHOW VARIABLES</literal>) that are
+ not based on the contents of
+ <literal>INFORMATION_SCHEMA</literal>. In such cases, the result
+ set is transferred to the client implicitly with
+ <literal>mysql_stmt_store_result()</literal>.
+ </para>
+-->
<para>
<emphasis role="bold">Return Values</emphasis>
@@ -9866,7 +9704,7 @@
<section id="mysql-stmt-free-result">
- <title id="title-mysql-stmt-free-result">&title-mysql-stmt-free-result;</title>
+ <title id='title-mysql-stmt-free-result'>&title-mysql-stmt-free-result;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_free_result()</literal></primary>
@@ -9905,7 +9743,7 @@
<section id="mysql-stmt-insert-id">
- <title id="title-mysql-stmt-insert-id">&title-mysql-stmt-insert-id;</title>
+ <title id='title-mysql-stmt-insert-id'>&title-mysql-stmt-insert-id;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_insert_id()</literal></primary>
@@ -9924,8 +9762,8 @@
Returns the value generated for an
<literal>AUTO_INCREMENT</literal> column by the prepared
<literal>INSERT</literal> or <literal>UPDATE</literal>
- statement. Use this function after you have executed prepared
- <literal>INSERT</literal> statement into a table which
+ statement. Use this function after you have executed a
+ prepared <literal>INSERT</literal> statement on a table which
contains an <literal>AUTO_INCREMENT</literal> field.
</para>
@@ -9946,19 +9784,10 @@
<literal>AUTO_INCREMENT</literal> value.
</para>
- <remark>
- The last sentence is here as temporary measure only. After
- fixing code
- </remark>
-
- <remark>
- responsible for handling of last_insert_id for prepared
- statements we should
- </remark>
-
- <remark>
- replace it with more precise description.
- </remark>
+<!-- NOTE: The last sentence is here as temporary measure only. After
+ fixing the code responsible for handling of last_insert_id for
+ prepared statements we should replace it with more precise
+ description. -->
<para>
<emphasis role="bold">Errors</emphasis>
@@ -9972,7 +9801,7 @@
<section id="mysql-stmt-fetch">
- <title id="title-mysql-stmt-fetch">&title-mysql-stmt-fetch;</title>
+ <title id='title-mysql-stmt-fetch'>&title-mysql-stmt-fetch;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_fetch()</literal></primary>
@@ -10205,9 +10034,7 @@
</itemizedlist>
- <remark role="todo">
- need to document allowed conversions in both directions
- </remark>
+<!-- TODO: need to document allowed conversions in both directions -->
<para>
<emphasis role="bold">Example</emphasis>
@@ -10404,7 +10231,7 @@
<section id="mysql-stmt-fetch-column">
- <title id="title-mysql-stmt-fetch-column">&title-mysql-stmt-fetch-column;</title>
+ <title id='title-mysql-stmt-fetch-column'>&title-mysql-stmt-fetch-column;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_fetch_column()</literal></primary>
@@ -10473,7 +10300,7 @@
<section id="mysql-stmt-field-count">
- <title id="title-mysql-stmt-field-count">&title-mysql-stmt-field-count;</title>
+ <title id='title-mysql-stmt-field-count'>&title-mysql-stmt-field-count;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_field_count()</literal></primary>
@@ -10522,7 +10349,7 @@
<section id="mysql-stmt-init">
- <title id="title-mysql-stmt-init">&title-mysql-stmt-init;</title>
+ <title id='title-mysql-stmt-init'>&title-mysql-stmt-init;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_init()</literal></primary>
@@ -10573,7 +10400,7 @@
<section id="mysql-stmt-num-rows">
- <title id="title-mysql-stmt-num-rows">&title-mysql-stmt-num-rows;</title>
+ <title id='title-mysql-stmt-num-rows'>&title-mysql-stmt-num-rows;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_num_rows()</literal></primary>
@@ -10605,9 +10432,7 @@
immediately.
</para>
- <remark role="todo">
- and otherwise? Only after all rows have been fetched?
- </remark>
+<!-- TODO: and otherwise? Only after all rows have been fetched? -->
<para>
<emphasis role="bold">Return Values</emphasis>
@@ -10629,7 +10454,7 @@
<section id="mysql-stmt-param-count">
- <title id="title-mysql-stmt-param-count">&title-mysql-stmt-param-count;</title>
+ <title id='title-mysql-stmt-param-count'>&title-mysql-stmt-param-count;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_param_count()</literal></primary>
@@ -10680,7 +10505,7 @@
<section id="mysql-stmt-param-metadata">
- <title id="title-mysql-stmt-param-metadata">&title-mysql-stmt-param-metadata;</title>
+ <title id='title-mysql-stmt-param-metadata'>&title-mysql-stmt-param-metadata;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_param_metadata()</literal></primary>
@@ -10691,9 +10516,7 @@
*stmt)</literal>
</para>
- <remark role="todo">
- fill this in
- </remark>
+<!-- TODO: fill this in -->
<para>
To be added.
@@ -10715,7 +10538,7 @@
<section id="mysql-stmt-prepare">
- <title id="title-mysql-stmt-prepare">&title-mysql-stmt-prepare;</title>
+ <title id='title-mysql-stmt-prepare'>&title-mysql-stmt-prepare;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_prepare()</literal></primary>
@@ -10858,7 +10681,7 @@
<section id="mysql-stmt-reset">
- <title id="title-mysql-stmt-reset">&title-mysql-stmt-reset;</title>
+ <title id='title-mysql-stmt-reset'>&title-mysql-stmt-reset;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_reset()</literal></primary>
@@ -10945,7 +10768,7 @@
<section id="mysql-stmt-result-metadata">
- <title id="title-mysql-stmt-result-metadata">&title-mysql-stmt-result-metadata;</title>
+ <title id='title-mysql-stmt-result-metadata'>&title-mysql-stmt-result-metadata;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_result_metadata</literal>.</primary>
@@ -11092,7 +10915,7 @@
<section id="mysql-stmt-row-seek">
- <title id="title-mysql-stmt-row-seek">&title-mysql-stmt-row-seek;</title>
+ <title id='title-mysql-stmt-row-seek'>&title-mysql-stmt-row-seek;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_row_seek()</literal></primary>
@@ -11118,14 +10941,9 @@
instead.
</para>
- <remark role="todo">
- this para may not make sense. It's written in parallel with
- </remark>
-
- <remark>
- mysql_data_seek(), but there is no corresponding
- mysql_stmt_use_result().
- </remark>
+<!-- TODO: this para may not make sense. It's written in parallel with
+ mysql_data_seek(), but there is no corresponding
+ mysql_stmt_use_result(). -->
<para>
This function requires that the result set structure contains
@@ -11156,7 +10974,7 @@
<section id="mysql-stmt-row-tell">
- <title id="title-mysql-stmt-row-tell">&title-mysql-stmt-row-tell;</title>
+ <title id='title-mysql-stmt-row-tell'>&title-mysql-stmt-row-tell;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_row_tell()</literal></primary>
@@ -11202,7 +11020,7 @@
<section id="mysql-stmt-send-long-data">
- <title id="title-mysql-stmt-send-long-data">&title-mysql-stmt-send-long-data;</title>
+ <title id='title-mysql-stmt-send-long-data'>&title-mysql-stmt-send-long-data;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_send_long_data()</literal>.</primary>
@@ -11319,9 +11137,7 @@
a valid connection handle.
</para>
- <remark role="todo">
- replace this example?
- </remark>
+<!-- TODO: replace this example? -->
<programlisting>
#define INSERT_QUERY "INSERT INTO test_long_data(text_column) VALUES(?)"
@@ -11383,7 +11199,7 @@
<section id="mysql-stmt-sqlstate">
- <title id="title-mysql-stmt-sqlstate">&title-mysql-stmt-sqlstate;</title>
+ <title id='title-mysql-stmt-sqlstate'>&title-mysql-stmt-sqlstate;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_sqlstate()</literal></primary>
@@ -11405,7 +11221,7 @@
the most recently invoked prepared statement API function that
can succeed or fail. The error code consists of five
characters. <literal>"00000"</literal> means <quote>no
- error.</quote> The values are specified by ANSI SQL and ODBC.
+ error</quote>. The values are specified by ANSI SQL and ODBC.
For a list of possible values, see
<xref linkend="error-handling"/>.
</para>
@@ -11429,7 +11245,7 @@
<section id="mysql-stmt-store-result">
- <title id="title-mysql-stmt-store-result">&title-mysql-stmt-store-result;</title>
+ <title id='title-mysql-stmt-store-result'>&title-mysql-stmt-store-result;</title>
<indexterm type="function">
<primary><literal>mysql_stmt_store_result()</literal></primary>
@@ -11553,7 +11369,7 @@
<section id="c-api-prepared-statement-problems">
- <title id="title-c-api-prepared-statement-problems">&title-c-api-prepared-statement-problems;</title>
+ <title id='title-c-api-prepared-statement-problems'>&title-c-api-prepared-statement-problems;</title>
<para>
Here follows a list of the currently known problems with
@@ -11565,8 +11381,8 @@
<listitem>
<para>
<literal>TIME</literal>, <literal>TIMESTAMP</literal>, and
- <literal>DATETIME</literal> don't support sub seconds (for
- example from <literal>DATE_FORMAT()</literal>.
+ <literal>DATETIME</literal> don't support parts of seconds
+ (for example from <literal>DATE_FORMAT()</literal>.
</para>
</listitem>
@@ -11602,17 +11418,18 @@
<section id="c-api-multiple-queries">
- <title id="title-c-api-multiple-queries">&title-c-api-multiple-queries;</title>
+ <title id='title-c-api-multiple-queries'>&title-c-api-multiple-queries;</title>
<para>
- From version 4.1, MySQL supports the execution of multiple
- statements specified in a single query string. To use this
- capability with a given connection, you must specify the
- <literal>CLIENT_MULTI_STATEMENTS</literal> option in the flags
- parameter of <literal>mysql_real_connect()</literal> when
- opening the connection. You can also set this for an existing
- connection by calling
- <literal>mysql_set_server_option(MYSQL_OPTION_MULTI_STATEMENTS_ON)</literal>
+ MySQL 5.1 supports the execution of multiple statements
+ specified in a single query string. To use this capability with
+ a given connection, you must specify the
+ <literal>CLIENT_MULTI_STATEMENTS</literal> option in the
+ <literal>flags</literal> parameter to
+ <literal>mysql_real_connect()</literal> when opening the
+ connection. You can also set this for an existing connection by
+ calling
+ <literal>mysql_set_server_option(MYSQL_OPTION_MULTI_STATEMENTS_ON)</literal>.
</para>
<para>
@@ -11663,15 +11480,15 @@
<section id="c-api-date-handling">
- <title id="title-c-api-date-handling">&title-c-api-date-handling;</title>
+ <title id='title-c-api-date-handling'>&title-c-api-date-handling;</title>
<para>
- The new binary protocol available in MySQL 4.1 and above allows
- you to send and receive date and time values
- (<literal>DATE</literal>, <literal>TIME</literal>,
- <literal>DATETIME</literal>, and <literal>TIMESTAMP</literal>),
- using the <literal>MYSQL_TIME</literal> structure. The members
- of this structure are described in
+ The binary protocol available in MySQL 5.1 allows you to send
+ and receive date and time values (<literal>DATE</literal>,
+ <literal>TIME</literal>, <literal>DATETIME</literal>, and
+ <literal>TIMESTAMP</literal>), using the
+ <literal>MYSQL_TIME</literal> structure. The members of this
+ structure are described in
<xref linkend="c-api-prepared-statement-datatypes"/>.
</para>
@@ -11797,7 +11614,7 @@
<section id="c-thread-functions">
- <title id="title-c-thread-functions">&title-c-thread-functions;</title>
+ <title id='title-c-thread-functions'>&title-c-thread-functions;</title>
<para>
You need to use the following functions when you want to create
@@ -11806,7 +11623,7 @@
<section id="my-init">
- <title id="title-my-init">&title-my-init;</title>
+ <title id='title-my-init'>&title-my-init;</title>
<indexterm type="function">
<primary><literal>my_init()</literal></primary>
@@ -11848,7 +11665,7 @@
<section id="mysql-thread-init">
- <title id="title-mysql-thread-init">&title-mysql-thread-init;</title>
+ <title id='title-mysql-thread-init'>&title-mysql-thread-init;</title>
<indexterm type="function">
<primary><literal>mysql_thread_init()</literal></primary>
@@ -11884,7 +11701,7 @@
<section id="mysql-thread-end">
- <title id="title-mysql-thread-end">&title-mysql-thread-end;</title>
+ <title id='title-mysql-thread-end'>&title-mysql-thread-end;</title>
<indexterm type="function">
<primary><literal>mysql_thread_end()</literal></primary>
@@ -11922,7 +11739,7 @@
<section id="mysql-thread-safe">
- <title id="title-mysql-thread-safe">&title-mysql-thread-safe;</title>
+ <title id='title-mysql-thread-safe'>&title-mysql-thread-safe;</title>
<indexterm type="function">
<primary><literal>mysql_thread_safe()</literal></primary>
@@ -11946,7 +11763,7 @@
</para>
<para>
- 1 is the client is thread-safe, 0 otherwise.
+ 1 if the client is thread-safe, 0 otherwise.
</para>
</section>
@@ -11955,7 +11772,7 @@
<section id="c-embedded-server-func">
- <title id="title-c-embedded-server-func">&title-c-embedded-server-func;</title>
+ <title id='title-c-embedded-server-func'>&title-c-embedded-server-func;</title>
<para>
If you want to allow your application to be linked against the
@@ -11969,11 +11786,10 @@
However, to provide improved memory management, even programs
that are linked with <option>-lmysqlclient</option> rather than
<option>-lmysqld</option> should include calls to begin and end
- use of the library. As of MySQL 5.0.3, the
- <literal>mysql_library_init()</literal> and
- <literal>mysql_library_end()</literal> functions can be used to
- do this. These actually are <literal>#define</literal> symbols
- that make them equivalent to
+ use of the library. The <literal>mysql_library_init()</literal>
+ and <literal>mysql_library_end()</literal> functions can be used
+ to do this. These actually are <literal>#define</literal>
+ symbols that make them equivalent to
<literal>mysql_server_init()</literal> and
<literal>mysql_server_end()</literal>, but the names more
clearly indicate that they should be called when beginning and
@@ -11985,7 +11801,7 @@
<section id="mysql-server-init">
- <title id="title-mysql-server-init">&title-mysql-server-init;</title>
+ <title id='title-mysql-server-init'>&title-mysql-server-init;</title>
<indexterm type="function">
<primary><literal>mysql_server_init()</literal></primary>
@@ -12087,7 +11903,7 @@
<section id="mysql-server-end">
- <title id="title-mysql-server-end">&title-mysql-server-end;</title>
+ <title id='title-mysql-server-end'>&title-mysql-server-end;</title>
<indexterm type="function">
<primary><literal>mysql_server_end()</literal></primary>
@@ -12121,7 +11937,7 @@
<section id="c-api-problems">
- <title id="title-c-api-problems">&title-c-api-problems;</title>
+ <title id='title-c-api-problems'>&title-c-api-problems;</title>
<indexterm type="type">
<primary><literal>mysql_query()</literal></primary>
@@ -12133,7 +11949,7 @@
<section id="null-mysql-store-result">
- <title id="title-null-mysql-store-result">&title-null-mysql-store-result;</title>
+ <title id='title-null-mysql-store-result'>&title-null-mysql-store-result;</title>
<para>
It is possible for <literal>mysql_store_result()</literal> to
@@ -12193,7 +12009,7 @@
<section id="query-results">
- <title id="title-query-results">&title-query-results;</title>
+ <title id='title-query-results'>&title-query-results;</title>
<para>
In addition to the result set returned by a query, you can
@@ -12211,15 +12027,8 @@
</para>
<para>
- In MySQL 3.23, there is an exception when
- <literal>DELETE</literal> is used without a
- <literal>WHERE</literal> clause. In this case, the table
- is re-created as an empty table and
- <literal>mysql_affected_rows()</literal> returns zero for
- the number of records affected. In MySQL 4.0,
- <literal>DELETE</literal> always returns the correct
- number of rows deleted. For a fast recreate, use
- <literal>TRUNCATE TABLE</literal>.
+ For a fast recreate, use <literal>TRUNCATE
+ TABLE</literal>.
</para>
</listitem>
@@ -12266,7 +12075,7 @@
<section id="getting-unique-id">
- <title id="title-getting-unique-id">&title-getting-unique-id;</title>
+ <title id='title-getting-unique-id'>&title-getting-unique-id;</title>
<indexterm type="concept">
<primary>unique ID</primary>
@@ -12364,7 +12173,7 @@
<section id="c-api-linking-problems">
- <title id="title-c-api-linking-problems">&title-c-api-linking-problems;</title>
+ <title id='title-c-api-linking-problems'>&title-c-api-linking-problems;</title>
<indexterm type="concept">
<primary>linking</primary>
@@ -12402,7 +12211,7 @@
<section id="building-clients">
- <title id="title-building-clients">&title-building-clients;</title>
+ <title id='title-building-clients'>&title-building-clients;</title>
<indexterm type="concept">
<primary>client programs</primary>
@@ -12467,7 +12276,7 @@
<section id="threaded-clients">
- <title id="title-threaded-clients">&title-threaded-clients;</title>
+ <title id='title-threaded-clients'>&title-threaded-clients;</title>
<indexterm type="concept">
<primary>clients</primary>
@@ -12489,18 +12298,16 @@
</para>
<para>
- New in 4.0.16: To not abort the program when a connection
- terminates, MySQL blocks <literal>SIGPIPE</literal> on the first
- call to <literal>mysql_server_init</literal>(),
- <literal>mysql_init()</literal> or
+ To avoid aborting the program when a connection terminates,
+ MySQL blocks <literal>SIGPIPE</literal> on the first call to
+ <literal>mysql_server_init</literal>(),
+ <literal>mysql_init()</literal>, or
<literal>mysql_connect()</literal>. If you want to have your own
<literal>SIGPIPE</literal> handler, you should first call
<literal>mysql_server_init()</literal> and then install your
- handler. In older versions of MySQL <literal>SIGPIPE</literal>
- was blocked, but only in the thread safe client library, for
- every call to <literal>mysql_init()</literal>.
+ handler.
</para>
-
+<remark role="todo">[js] Need version info here...</remark>
<para>
In the older binaries we distribute on our Web site
(<ulink url="http://www.mysql.com/"/>), the client libraries are
@@ -12681,7 +12488,7 @@
<section id="php">
- <title id="title-php">&title-php;</title>
+ <title id='title-php'>&title-php;</title>
<indexterm type="concept">
<primary>PHP API</primary>
@@ -12700,17 +12507,23 @@
</para>
<itemizedlist>
-
+
+ <remark role="todo">
+ [js] Apparently the mysql extension supplied with more recent
+ PHP 5 releases *does* support improved password hashing. Need to
+ determine when this started happening and update the following
+ accordingly.
+ </remark>
+
<listitem>
<para>
- <emphasis role="bold">mysql</emphasis> - Available for PHP
- versions 4 and 5, this extension is intended for use with
- MySQL versions prior to MySQL 4.1. This extension does not
- support the improved authentication protocol used in MySQL
- 4.1.1 and later, nor does it support prepared statements or
- multiple statements. If you wish to use this extension with
- MySQL 4.1 and more recent versions of MySQL, you will likely
- want to configure the MySQL server to use the
+ <literal>mysql</literal>: Available for PHP versions 4 and 5,
+ this extension is intended for use with MySQL versions prior
+ to MySQL 4.1. This extension does not support the improved
+ authentication protocol used in MySQL 5.1, nor does it support
+ prepared statements or multiple statements. If you wish to use
+ this extension with MySQL 5.1, you will likely want to
+ configure the MySQL server to use the
<command>--old-passwords</command> option (see
<xref linkend="old-client"/>). This extension is documented on
the PHP Website at <ulink url="http://php.net/mysql"/>.
@@ -12719,15 +12532,14 @@
<listitem>
<para>
- <emphasis role="bold">mysqli</emphasis> - Stands for "MySQL,
- Improved", this extension is available only in PHP 5. It is
- intended for use with MySQL 4.1.1 and later. This extension
- fully supports the authentication protocol used in MySQL 4.1.1
- and subsequent MySQL releases as well as the Prepared
- Statements and Multiple Statements APIs. In addition, this
- extension provides an advanced, object-oriented programming
- interface. You can read the documentation for the
- <emphasis role="bold">mysqli</emphasis> extension at
+ <literal>mysqli</literal> - Stands for "MySQL, Improved"; this
+ extension is available only in PHP 5. It is intended for use
+ with MySQL 4.1.1 and later. This extension fully supports the
+ authentication protocol used in MySQL 5.1, as well as the
+ Prepared Statements and Multiple Statements APIs. In addition,
+ this extension provides an advanced, object-oriented
+ programming interface. You can read the documentation for the
+ <literal>mysqli</literal> extension at
<ulink url="http://php.net/mysqli"/>. A helpful article can be
found at
<ulink url="http://www.zend.com/php5/articles/php5-mysqli.php"/>.
@@ -12743,52 +12555,52 @@
<section id="php-problems">
- <title id="title-php-problems">&title-php-problems;</title>
+ <title id='title-php-problems'>&title-php-problems;</title>
<itemizedlist>
<listitem>
<para>
- Error: "Maximum Execution Time Exceeded" This is a PHP
- limit; go into the <filename>php.ini</filename> file and set
- the maximum execution time up from 30 seconds to something
- higher, as needed. It is also not a bad idea to double the
- RAM allowed per script to 16MB instead of 8MB.
+ <literal>Error: Maximum Execution Time Exceeded</literal>:
+ This is a PHP limit; go into the
+ <filename>php.ini</filename> file and set the maximum
+ execution time up from 30 seconds to something higher, as
+ needed. It is also not a bad idea to double the RAM allowed
+ per script to 16MB instead of 8MB.
</para>
</listitem>
<listitem>
<para>
- Error: "Fatal error: Call to unsupported or undefined
- function mysql_connect() in .." This means that your PHP
- version isn't compiled with MySQL support. You can either
- compile a dynamic MySQL module and load it into PHP or
- recompile PHP with built-in MySQL support. This is described
- in detail in the PHP manual.
+ <literal>Fatal error: Call to unsupported or undefined
+ function mysql_connect() in ...</literal>: This means that
+ your PHP version isn't compiled with MySQL support. You can
+ either compile a dynamic MySQL module and load it into PHP
+ or recompile PHP with built-in MySQL support. This process
+ is described in detail in the PHP manual.
</para>
</listitem>
<listitem>
<para>
- Error: "undefined reference to `uncompress'" This means that
- the client library is compiled with support for a compressed
- client/server protocol. The fix is to add
- <option>-lz</option> last when linking with
- <option>-lmysqlclient</option>.
+ <literal>Error: Undefined reference to
+ 'uncompress'</literal>: This means that the client library
+ is compiled with support for a compressed client/server
+ protocol. The fix is to add <option>-lz</option> last when
+ linking with <option>-lmysqlclient</option>.
</para>
</listitem>
<listitem>
<para>
- Error: "Client does not support authentication protocol"
- This is most often encountered when trying to use the older
- <emphasis role="bold">mysql</emphasis> extension with MySQL
- 4.1.1 and later. Possible solutions are: downgrade to MySQL
- 4.0; switch to PHP 5 and the newer
- <emphasis role="bold">mysqli</emphasis> extension; or
- configure the MySQL server with
- <option>--old-passwords</option>. (See
- <xref linkend="old-client"/>, for more information.)
+ <literal>Error: Client does not support authentication
+ protocol</literal>: This is most often encountered when
+ trying to use the older <literal>mysql</literal> extension
+ with MySQL 4.1.1 and later. Possible solutions are:
+ downgrade to MySQL 4.0; switch to PHP 5 and the newer
+ <literal>mysqli</literal> extension; or configure the MySQL
+ server with <option>--old-passwords</option>. (See
+ <xref linkend="old-client"/> for more information.)
</para>
</listitem>
@@ -12800,7 +12612,7 @@
<section id="perl">
- <title id="title-perl">&title-perl;</title>
+ <title id='title-perl'>&title-perl;</title>
<indexterm type="concept">
<primary>APIs</primary>
@@ -12901,7 +12713,7 @@
<section id="cplusplus">
- <title id="title-cplusplus">&title-cplusplus;</title>
+ <title id='title-cplusplus'>&title-cplusplus;</title>
<indexterm type="concept">
<primary>MySQL++</primary>
@@ -12919,7 +12731,7 @@
<section id="borland-c-plus-plus">
- <title id="title-borland-c-plus-plus">&title-borland-c-plus-plus;</title>
+ <title id='title-borland-c-plus-plus'>&title-borland-c-plus-plus;</title>
<indexterm type="concept">
<primary>Borland C++ compiler</primary>
@@ -12948,7 +12760,7 @@
<section id="python">
- <title id="title-python">&title-python;</title>
+ <title id='title-python'>&title-python;</title>
<indexterm type="concept">
<primary>Python API</primary>
@@ -12964,7 +12776,7 @@
<section id="tcl">
- <title id="title-tcl">&title-tcl;</title>
+ <title id='title-tcl'>&title-tcl;</title>
<indexterm type="concept">
<primary>Tcl API</primary>
@@ -12980,7 +12792,7 @@
<section id="eiffel">
- <title id="title-eiffel">&title-eiffel;</title>
+ <title id='title-eiffel'>&title-eiffel;</title>
<indexterm type="concept">
<primary>Eiffel Wrapper</primary>
@@ -13002,11 +12814,9 @@
<section id="programming-utilities">
- <title id="title-programming-utilities">&title-programming-utilities;</title>
+ <title id='title-programming-utilities'>&title-programming-utilities;</title>
- <remark role="todo">
- my_print_defaults
- </remark>
+<!-- TODO: my_print_defaults -->
<para>
This section describes some utilities that you may find useful
@@ -13055,7 +12865,7 @@
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">MySQL Database System</refmiscinfo>
<refmiscinfo class="source">MySQL</refmiscinfo>
- <refmiscinfo class="version">5.1</refmiscinfo>
+ <refmiscinfo class="version">5.0</refmiscinfo>
<refmiscinfo class="refman">Convert mSQL Programs for Use with MySQL</refmiscinfo>
</refmeta>
--- 1.22/refman-5.0/mysql-apis.xml 2005-08-24 06:02:02 +10:00
+++ 1.23/refman-5.0/mysql-apis.xml 2005-08-25 10:41:04 +10:00
@@ -214,7 +214,7 @@
<listitem>
<para>
No support for <literal>ISAM</literal> tables. (This is
- mainly done to make the library smaller)
+ mainly done to make the library smaller.)
</para>
</listitem>
@@ -233,7 +233,7 @@
<listitem>
<para>
No internal RAID support. (This is not normally needed as
- most current operating systems support big files).
+ most current operating systems support big files.)
</para>
</listitem>
@@ -607,8 +607,8 @@
lib := /usr/local/mysql/lib
# If you have not installed the MySQL software yet, try this instead
-#inc := $(HOME)/mysql-4.0/include
-#lib := $(HOME)/mysql-4.0/libmysqld
+#inc := $(HOME)/mysql-5.0/include
+#lib := $(HOME)/mysql-5.0/libmysqld
CC := gcc
CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT
@@ -1486,7 +1486,7 @@
</row>
<row>
<entry><emphasis role="bold">mysql_get_server_version()</emphasis></entry>
- <entry>Returns version number of server as an integer (new in 4.1).</entry>
+ <entry>Returns version number of server as an integer.</entry>
</row>
<row>
<entry><emphasis role="bold">mysql_get_proto_info()</emphasis></entry>
@@ -1753,7 +1753,7 @@
<literal>reconnect</literal> flag (part of the
<literal>MYSQL</literal> structure) to a value of
<literal>1</literal> in versions of the API strictly older than
- 5.0.3, of <literal>0</literal> in newer versions. A value of
+ 5.0.3, or <literal>0</literal> in newer versions. A value of
<literal>1</literal> for this flag indicates, in the event that
a query cannot be performed because of a lost connection, to try
reconnecting to the server before giving up. When you are done
@@ -2068,10 +2068,6 @@
</para>
<para>
- This function was introduced in MySQL 3.23.3.
- </para>
-
- <para>
<literal>mysql_change_user()</literal> fails if the connected
user cannot be authenticated or doesn't have permission to use
the database. In this case the user and database are not
@@ -2085,11 +2081,10 @@
</para>
<para>
- Starting from MySQL 4.0.6 this command always performs a
- <literal>ROLLBACK</literal> of any active transactions, closes
- all temporary tables, unlocks all locked tables and resets the
- state as if one had done a new connect. This happens even if
- the user didn't change.
+ This command always performs a <literal>ROLLBACK</literal> of
+ any active transactions, closes all temporary tables, unlocks
+ all locked tables and resets the state as if one had done a
+ new connect. This happens even if the user didn't change.
</para>
<para>
@@ -3449,12 +3444,6 @@
</para>
<para>
- If you are using a version of MySQL earlier than Version
- 3.22.24, you should use <literal>unsigned int
- mysql_num_fields(MYSQL *mysql)</literal> instead.
- </para>
-
- <para>
<emphasis role="bold">Description</emphasis>
</para>
@@ -3797,10 +3786,6 @@
</para>
<para>
- This function was added in MySQL 4.0.16.
- </para>
-
- <para>
<emphasis role="bold">Return Values</emphasis>
</para>
@@ -3971,7 +3956,7 @@
</programlisting>
<para>
- For example, 4.1.2 is returned as 40102.
+ For example, 5.0.12 is returned as 500012.
</para>
<para>
@@ -4858,7 +4843,8 @@
‘<literal>_</literal>’, or may be a
<literal>NULL</literal> pointer to match all tables. Calling
<literal>mysql_list_tables()</literal> is similar to executing
- the query <literal>SHOW tables [LIKE wild]</literal>.
+ the query <literal>SHOW tables [LIKE
+ <replaceable>wild</replaceable>]</literal>.
</para>
<para>
@@ -4943,18 +4929,9 @@
</para>
<para>
- Or:
- </para>
-
- <para>
- <literal>unsigned int mysql_num_fields(MYSQL *mysql)</literal>
- </para>
-
- <para>
- The second form doesn't work on MySQL 3.22.24 or newer. To
- pass a <literal>MYSQL*</literal> argument, you must use
+ To pass a <literal>MYSQL*</literal> argument instead, use
<literal>unsigned int mysql_field_count(MYSQL
- *mysql)</literal> instead.
+ *mysql)</literal>.
</para>
<para>
@@ -5272,8 +5249,8 @@
<row>
<entry><literal>MYSQL_SECURE_AUTH</literal></entry>
<entry><literal>my_bool*</literal></entry>
- <entry>Whether to connect to a server that does not support the new 4.1.1
- password hashing.</entry>
+ <entry>Whether to connect to a server that does not support the
+ password hashing used in MySQL 4.1.1 and later.</entry>
</row>
<row>
<entry><literal>MYSQL_SET_CHARSET_DIR</literal></entry>
@@ -5384,7 +5361,7 @@
</row>
<row>
<entry><literal>protocol={TCP | SOCKET | PIPE | MEMORY}</literal></entry>
- <entry>The protocol to use when connecting to server (New in 4.1)</entry>
+ <entry>The protocol to use when connecting to the server.</entry>
</row>
<row>
<entry><literal>port</literal></entry>
@@ -5397,8 +5374,7 @@
</row>
<row>
<entry><literal>shared-memory-base-name=<replaceable>name</replaceable></literal></entry>
- <entry>Shared memory name to use to connect to server (default is "MYSQL"). New
- in MySQL 4.1.</entry>
+ <entry>Shared memory name to use to connect to server (default is "MYSQL").</entry>
</row>
<row>
<entry><literal>socket</literal></entry>
@@ -5415,7 +5391,8 @@
<para>
Note that <literal>timeout</literal> has been replaced by
<literal>connect-timeout</literal>, but
- <literal>timeout</literal> still works for a while.
+ <literal>timeout</literal> is still supported in MySQL 5.0 for
+ backwards compatibility.
</para>
<para>
@@ -5806,15 +5783,14 @@
string (separated by
‘<literal>;</literal>’). If this flag
is not set, multiple-statement execution is
- disabled. New in 4.1.</entry>
+ disabled.</entry>
</row>
<row>
<entry><literal>CLIENT_MULTI_RESULTS</literal></entry>
<entry>Tell the server that the client can handle multiple result sets from
multiple-statement executions or stored
procedures. This is automatically set if
- <literal>CLIENT_MULTI_STATEMENTS</literal> is set.
- New in 4.1.</entry>
+ <literal>CLIENT_MULTI_STATEMENTS</literal> is set.</entry>
</row>
<row>
<entry><literal>CLIENT_NO_SCHEMA</literal></entry>
@@ -6007,9 +5983,9 @@
<literal>mysql_real_connect()</literal> sets the
<literal>reconnect</literal> flag (part of the
<literal>MYSQL</literal> structure) to a value of
- <literal>1</literal> in versions of the API strictly older
- than 5.0.3, of <literal>0</literal> in newer versions. A value
- of <literal>1</literal> for this flag indicates, in the event
+ <literal>1</literal> in versions of the API older than 5.0.3,
+ or <literal>0</literal> in newer versions. A value of
+ <literal>1</literal> for this flag indicates, in the event
that a query cannot be performed because of a lost connection,
to try reconnecting to the server before giving up.
</para>
@@ -6702,19 +6678,13 @@
Asks the database server to shut down. The connected user must
have <literal>SHUTDOWN</literal> privileges. The
<literal>shutdown_level</literal> argument was added in MySQL
- 4.1.3 (and 5.0.1). The MySQL server currently supports only
- one type (level of gracefulness) of shutdown;
+ 5.0.1. MySQL 5.0 servers support only one type of shutdown;
<literal>shutdown_level</literal> must be equal to
- <literal>SHUTDOWN_DEFAULT</literal>. Later we wil add more
- levels and then the <literal>shutdown_level</literal> argument
- will enable us to choose the desired level. MySQL servers and
- MySQL clients before and after 4.1.3 are compatible; MySQL
- servers newer than 4.1.3 accept the
- <literal>mysql_shutdown(MYSQL *mysql)</literal> call, and
- MySQL servers older than 4.1.3 accept the new
- <literal>mysql_shutdown()</literal> call. But dynamically
- linked executables which have been compiled with older
- versions of <literal>libmysqlclient</literal> headers, and
+ <literal>SHUTDOWN_DEFAULT</literal>. Additional shutdown
+ levels are planned and then the <literal>shutdown_level</literal> argument
+ will enable us to choose the desired level. Dynamically linked
+ executables which have been compiled with older versions of
+ <literal>libmysqlclient</literal> headers, and
call <literal>mysql_shutdown()</literal>, need to be used with
the old <literal>libmysqlclient</literal> dynamic library.
</para>
@@ -6808,9 +6778,9 @@
</para>
<para>
- Note that not all MySQL errors are yet mapped to SQLSTATE's.
- The value <literal>'HY000'</literal> (general error) is used
- for unmapped errors.
+ Note that not all MySQL errors are mapped to SQLSTATE error
+ codes. The value <literal>'HY000'</literal> (general error) is
+ used for unmapped errors.
</para>
<para>
@@ -7748,7 +7718,7 @@
<title id='title-c-api-prepared-statements'>&title-c-api-prepared-statements;</title>
<para>
- As of MySQL 4.1, the client/server protocol provides for the use
+ In MySQL 5.0, the 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 <literal>mysql_stmt_init()</literal>
@@ -7781,8 +7751,8 @@
<literal>DO</literal>, <literal>INSERT</literal>,
<literal>REPLACE</literal>, <literal>SELECT</literal>,
<literal>SET</literal>, <literal>UPDATE</literal>, and most
- <literal>SHOW</literal> statements. Other statements are not yet
- supported.
+ <literal>SHOW</literal> statements. Other statements are not
+ supported in MySQL 5.0.
</para>
</section>
@@ -7792,13 +7762,6 @@
<title id='title-c-api-prepared-statement-datatypes'>&title-c-api-prepared-statement-datatypes;</title>
<para>
- <emphasis role="bold">Note</emphasis>: Some incompatible changes
- were made in MySQL 4.1.2. See
- <xref linkend="c-api-prepared-statement-functions"/> for
- details.
- </para>
-
- <para>
Prepared statements mainly use the <literal>MYSQL_STMT</literal>
and <literal>MYSQL_BIND</literal> data structures. A third
structure, <literal>MYSQL_TIME</literal>, is used to transfer
@@ -8322,9 +8285,8 @@
Implicit type conversion may be performed in both directions.
</para>
-<!-- TODO: Explain what that means and give some examples. Need list of -->
-
-<!-- allowable/supported conversions -->
+<!-- TODO: Explain what that means and give some examples. Need list of
+ allowable/supported conversions -->
</section>
@@ -8343,22 +8305,14 @@
</indexterm>
<para>
- <emphasis role="bold">Note</emphasis>: Some incompatible changes
- were made in MySQL 4.1.2. See
- <xref linkend="c-api-prepared-statement-functions"/> for
- details.
- </para>
-
- <para>
The functions available for prepared statement processing are
summarized here and described in greater detail in a later
section. See
<xref linkend="c-api-prepared-statement-functions"/>.
</para>
-<!-- TODO: missing functions here (that are listed in mysql.h) -->
-
-<!-- mysql_stmt_param_metadata() 4.1.2 [not implemented yet?] -->
+<!-- TODO: missing functions here (that are listed in mysql.h)
+ mysql_stmt_param_metadata() 4.1.2 [not implemented yet?] -->
<informaltable>
<tgroup cols="2">
@@ -8446,10 +8400,8 @@
<row>
<entry><emphasis role="bold">mysql_stmt_param_count()</emphasis></entry>
<entry>Returns the number of parameters in a prepared SQL statement.
-
-<!-- 2004-03-03: mysql_stmt_param_metadata is not implemented yet, -->
-
-<!-- only stub is present in the library --></entry>
+<!-- 2004-03-03: mysql_stmt_param_metadata is not implemented yet, only
+ stub is present in the library --></entry>
</row>
<row>
<entry><emphasis role="bold">mysql_stmt_param_metadata()</emphasis></entry>
@@ -8458,7 +8410,6 @@
<row>
<entry><emphasis role="bold">mysql_stmt_prepare()</emphasis></entry>
<entry>Prepares an SQL string for execution.
-
<!-- TODO: this description is not helpful. --></entry>
</row>
<row>
@@ -8704,79 +8655,18 @@
<title id='title-c-api-prepared-statement-functions'>&title-c-api-prepared-statement-functions;</title>
<para>
- To prepare and execute queries, use the functions in the
- following sections.
- </para>
+ To prepare and execute queries, use the functions described in
+ detail in the following sections.
+ </para>
<para>
- In MySQL 4.1.2, the names of several prepared statement
- functions were changed:
- </para>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colwidth="30*"/>
- <colspec colwidth="70*"/>
- <tbody>
- <row>
- <entry><emphasis role="bold">Old Name</emphasis></entry>
- <entry><emphasis role="bold">New Name</emphasis></entry>
- </row>
- <row>
- <entry><literal>mysql_bind_param()</literal></entry>
- <entry><literal>mysql_stmt_bind_param()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_bind_result()</literal></entry>
- <entry><literal>mysql_stmt_bind_result()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_prepare()</literal></entry>
- <entry><literal>mysql_stmt_prepare()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_execute()</literal></entry>
- <entry><literal>mysql_stmt_execute()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_fetch()</literal></entry>
- <entry><literal>mysql_stmt_fetch()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_fetch_column()</literal></entry>
- <entry><literal>mysql_stmt_fetch_column()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_param_count()</literal></entry>
- <entry><literal>mysql_stmt_param_count()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_param_result()</literal></entry>
- <entry><literal>mysql_stmt_param_metadata()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_get_metadata()</literal></entry>
- <entry><literal>mysql_stmt_result_metadata()</literal></entry>
- </row>
- <row>
- <entry><literal>mysql_send_long_data()</literal></entry>
- <entry><literal>mysql_stmt_send_long_data()</literal></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- All functions that operate with a <literal>MYSQL_STMT</literal>
- structure begin with the prefix <literal>mysql_stmt_</literal>.
+ Note that all functions operating with a
+ <literal>MYSQL_STMT</literal> structure begin with the prefix
+ <literal>mysql_stmt_</literal>.
</para>
<para>
- Also in 4.1.2, the signature of the
- <literal>mysql_stmt_prepare()</literal> 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
+ To create a <literal>MYSQL_STMT</literal> handle, use the
<literal>mysql_stmt_init()</literal> function.
</para>
@@ -8808,15 +8698,9 @@
<literal>mysql_num_rows()</literal>.
</para>
-<!-- TODO: For SELECT, are there any caveats on when you must wait to call -->
-
-<!-- this function, such as after all the rows have been fetched or after -->
-
-<!-- calling mysql_stmt_store_result()? -->
-
- <para>
- This function was added in MySQL 4.1.0.
- </para>
+<!-- TODO: For SELECT, are there any caveats on when you must wait to
+ call this function, such as after all the rows have been fetched
+ or after calling mysql_stmt_store_result()? -->
<para>
<emphasis role="bold">Return Values</emphasis>
@@ -8894,9 +8778,8 @@
</para>
<para>
- See <literal>mysql_stmt_attr_set()</literal> for a list of
- options and option types. See
- <xref linkend="mysql-stmt-attr-set"/>.
+ See <xref linkend="mysql-stmt-attr-set"/> for a list of
+ options and option types.
</para>
<para>
@@ -9564,19 +9447,20 @@
before opening a new one.
</para>
-<!-- I've commented out the implementation details; they might change - PD -->
-
-<!-- @code{mysql_stmt_execute()} opens no cursor for result sets that contain -->
-
-<!-- zero rows or one row. It also opens no cursor for statements such as -->
-
-<!-- @code{EXPLAIN} and @code{SHOW} statements such as @code{SHOW VARIABLES} that -->
-
-<!-- are not based on the contents of @code{INFORMATION_SCHEMA}. In such cases, -->
+<!-- NOTE: I've commented out the implementation details; they might change - PD -->
-<!-- the result set is transferred to the client implicitly with -->
-
-<!-- @code{mysql_stmt_store_result()}. -->
+<!--
+ <para>
+ <literal>mysql_stmt_execute()</literal> opens no cursor for
+ result sets that contain zero rows or one row. It also opens no
+ cursor for <literal>EXPLAIN</literal> or <literal>SHOW</literal>
+ statements (such as <literal>SHOW VARIABLES</literal>) that are
+ not based on the contents of
+ <literal>INFORMATION_SCHEMA</literal>. In such cases, the result
+ set is transferred to the client implicitly with
+ <literal>mysql_stmt_store_result()</literal>.
+ </para>
+-->
<para>
<emphasis role="bold">Return Values</emphasis>
@@ -9886,8 +9770,8 @@
Returns the value generated for an
<literal>AUTO_INCREMENT</literal> column by the prepared
<literal>INSERT</literal> or <literal>UPDATE</literal>
- statement. Use this function after you have executed prepared
- <literal>INSERT</literal> statement into a table which
+ statement. Use this function after you have executed a
+ prepared <literal>INSERT</literal> statement on a table which
contains an <literal>AUTO_INCREMENT</literal> field.
</para>
@@ -9908,11 +9792,10 @@
<literal>AUTO_INCREMENT</literal> value.
</para>
-<!-- The last sentence is here as temporary measure only. After fixing code -->
-
-<!-- responsible for handling of last_insert_id for prepared statements we should -->
-
-<!-- replace it with more precise description. -->
+<!-- NOTE: The last sentence is here as temporary measure only. After
+ fixing the code responsible for handling of last_insert_id for
+ prepared statements we should replace it with more precise
+ description. -->
<para>
<emphasis role="bold">Errors</emphasis>
@@ -11066,9 +10949,9 @@
instead.
</para>
-<!-- TODO: this para may not make sense. It's written in parallel with -->
-
-<!-- mysql_data_seek(), but there is no corresponding mysql_stmt_use_result(). -->
+<!-- TODO: this para may not make sense. It's written in parallel with
+ mysql_data_seek(), but there is no corresponding
+ mysql_stmt_use_result(). -->
<para>
This function requires that the result set structure contains
@@ -11346,7 +11229,7 @@
the most recently invoked prepared statement API function that
can succeed or fail. The error code consists of five
characters. <literal>"00000"</literal> means <quote>no
- error.</quote> The values are specified by ANSI SQL and ODBC.
+ error</quote>. The values are specified by ANSI SQL and ODBC.
For a list of possible values, see
<xref linkend="error-handling"/>.
</para>
@@ -11506,8 +11389,8 @@
<listitem>
<para>
<literal>TIME</literal>, <literal>TIMESTAMP</literal>, and
- <literal>DATETIME</literal> don't support sub seconds (for
- example from <literal>DATE_FORMAT()</literal>.
+ <literal>DATETIME</literal> don't support parts of seconds
+ (for example from <literal>DATE_FORMAT()</literal>.
</para>
</listitem>
@@ -11546,14 +11429,15 @@
<title id='title-c-api-multiple-queries'>&title-c-api-multiple-queries;</title>
<para>
- From version 4.1, MySQL supports the execution of multiple
- statements specified in a single query string. To use this
- capability with a given connection, you must specify the
- <literal>CLIENT_MULTI_STATEMENTS</literal> option in the flags
- parameter of <literal>mysql_real_connect()</literal> when
- opening the connection. You can also set this for an existing
- connection by calling
- <literal>mysql_set_server_option(MYSQL_OPTION_MULTI_STATEMENTS_ON)</literal>
+ MySQL 5.0 supports the execution of multiple statements
+ specified in a single query string. To use this capability with
+ a given connection, you must specify the
+ <literal>CLIENT_MULTI_STATEMENTS</literal> option in the
+ <literal>flags</literal> parameter to
+ <literal>mysql_real_connect()</literal> when opening the
+ connection. You can also set this for an existing connection by
+ calling
+ <literal>mysql_set_server_option(MYSQL_OPTION_MULTI_STATEMENTS_ON)</literal>.
</para>
<para>
@@ -11607,12 +11491,12 @@
<title id='title-c-api-date-handling'>&title-c-api-date-handling;</title>
<para>
- The new binary protocol available in MySQL 4.1 and above allows
- you to send and receive date and time values
- (<literal>DATE</literal>, <literal>TIME</literal>,
- <literal>DATETIME</literal>, and <literal>TIMESTAMP</literal>),
- using the <literal>MYSQL_TIME</literal> structure. The members
- of this structure are described in
+ The binary protocol available in MySQL 5.0 allows you to send
+ and receive date and time values (<literal>DATE</literal>,
+ <literal>TIME</literal>, <literal>DATETIME</literal>, and
+ <literal>TIMESTAMP</literal>), using the
+ <literal>MYSQL_TIME</literal> structure. The members of this
+ structure are described in
<xref linkend="c-api-prepared-statement-datatypes"/>.
</para>
@@ -11887,7 +11771,7 @@
</para>
<para>
- 1 is the client is thread-safe, 0 otherwise.
+ 1 if the client is thread-safe, 0 otherwise.
</para>
</section>
@@ -12152,15 +12036,8 @@
</para>
<para>
- In MySQL 3.23, there is an exception when
- <literal>DELETE</literal> is used without a
- <literal>WHERE</literal> clause. In this case, the table
- is re-created as an empty table and
- <literal>mysql_affected_rows()</literal> returns zero for
- the number of records affected. In MySQL 4.0,
- <literal>DELETE</literal> always returns the correct
- number of rows deleted. For a fast recreate, use
- <literal>TRUNCATE TABLE</literal>.
+ For a fast recreate, use <literal>TRUNCATE
+ TABLE</literal>.
</para>
</listitem>
@@ -12430,18 +12307,16 @@
</para>
<para>
- New in 4.0.16: To not abort the program when a connection
- terminates, MySQL blocks <literal>SIGPIPE</literal> on the first
- call to <literal>mysql_server_init</literal>(),
- <literal>mysql_init()</literal> or
+ To avoid aborting the program when a connection terminates,
+ MySQL blocks <literal>SIGPIPE</literal> on the first call to
+ <literal>mysql_server_init</literal>(),
+ <literal>mysql_init()</literal>, or
<literal>mysql_connect()</literal>. If you want to have your own
<literal>SIGPIPE</literal> handler, you should first call
<literal>mysql_server_init()</literal> and then install your
- handler. In older versions of MySQL <literal>SIGPIPE</literal>
- was blocked, but only in the thread safe client library, for
- every call to <literal>mysql_init()</literal>.
+ handler.
</para>
-
+<remark role="todo">[js] Need version info here...</remark>
<para>
In the older binaries we distribute on our Web site
(<ulink url="http://www.mysql.com/"/>), the client libraries are
@@ -12641,17 +12516,23 @@
</para>
<itemizedlist>
-
+
+ <remark role="todo">
+ [js] Apparently the mysql extension supplied with more recent
+ PHP 5 releases *does* support improved password hashing. Need to
+ determine when this started happening and update the following
+ accordingly.
+ </remark>
+
<listitem>
<para>
- <emphasis role="bold">mysql</emphasis> - Available for PHP
- versions 4 and 5, this extension is intended for use with
- MySQL versions prior to MySQL 4.1. This extension does not
- support the improved authentication protocol used in MySQL
- 4.1.1 and later, nor does it support prepared statements or
- multiple statements. If you wish to use this extension with
- MySQL 4.1 and more recent versions of MySQL, you will likely
- want to configure the MySQL server to use the
+ <literal>mysql</literal>: Available for PHP versions 4 and 5,
+ this extension is intended for use with MySQL versions prior
+ to MySQL 4.1. This extension does not support the improved
+ authentication protocol used in MySQL 5.0, nor does it support
+ prepared statements or multiple statements. If you wish to use
+ this extension with MySQL 5.0, you will likely want to
+ configure the MySQL server to use the
<command>--old-passwords</command> option (see
<xref linkend="old-client"/>). This extension is documented on
the PHP Website at <ulink url="http://php.net/mysql"/>.
@@ -12660,15 +12541,14 @@
<listitem>
<para>
- <emphasis role="bold">mysqli</emphasis> - Stands for "MySQL,
- Improved", this extension is available only in PHP 5. It is
- intended for use with MySQL 4.1.1 and later. This extension
- fully supports the authentication protocol used in MySQL 4.1.1
- and subsequent MySQL releases as well as the Prepared
- Statements and Multiple Statements APIs. In addition, this
- extension provides an advanced, object-oriented programming
- interface. You can read the documentation for the
- <emphasis role="bold">mysqli</emphasis> extension at
+ <literal>mysqli</literal> - Stands for "MySQL, Improved"; this
+ extension is available only in PHP 5. It is intended for use
+ with MySQL 4.1.1 and later. This extension fully supports the
+ authentication protocol used in MySQL 5.0, as well as the
+ Prepared Statements and Multiple Statements APIs. In addition,
+ this extension provides an advanced, object-oriented
+ programming interface. You can read the documentation for the
+ <literal>mysqli</literal> extension at
<ulink url="http://php.net/mysqli"/>. A helpful article can be
found at
<ulink url="http://www.zend.com/php5/articles/php5-mysqli.php"/>.
@@ -12690,46 +12570,46 @@
<listitem>
<para>
- Error: "Maximum Execution Time Exceeded" This is a PHP
- limit; go into the <filename>php.ini</filename> file and set
- the maximum execution time up from 30 seconds to something
- higher, as needed. It is also not a bad idea to double the
- RAM allowed per script to 16MB instead of 8MB.
+ <literal>Error: Maximum Execution Time Exceeded</literal>:
+ This is a PHP limit; go into the
+ <filename>php.ini</filename> file and set the maximum
+ execution time up from 30 seconds to something higher, as
+ needed. It is also not a bad idea to double the RAM allowed
+ per script to 16MB instead of 8MB.
</para>
</listitem>
<listitem>
<para>
- Error: "Fatal error: Call to unsupported or undefined
- function mysql_connect() in .." This means that your PHP
- version isn't compiled with MySQL support. You can either
- compile a dynamic MySQL module and load it into PHP or
- recompile PHP with built-in MySQL support. This is described
- in detail in the PHP manual.
+ <literal>Fatal error: Call to unsupported or undefined
+ function mysql_connect() in ...</literal>: This means that
+ your PHP version isn't compiled with MySQL support. You can
+ either compile a dynamic MySQL module and load it into PHP
+ or recompile PHP with built-in MySQL support. This process
+ is described in detail in the PHP manual.
</para>
</listitem>
<listitem>
<para>
- Error: "undefined reference to `uncompress'" This means that
- the client library is compiled with support for a compressed
- client/server protocol. The fix is to add
- <option>-lz</option> last when linking with
- <option>-lmysqlclient</option>.
+ <literal>Error: Undefined reference to
+ 'uncompress'</literal>: This means that the client library
+ is compiled with support for a compressed client/server
+ protocol. The fix is to add <option>-lz</option> last when
+ linking with <option>-lmysqlclient</option>.
</para>
</listitem>
<listitem>
<para>
- Error: "Client does not support authentication protocol"
- This is most often encountered when trying to use the older
- <emphasis role="bold">mysql</emphasis> extension with MySQL
- 4.1.1 and later. Possible solutions are: downgrade to MySQL
- 4.0; switch to PHP 5 and the newer
- <emphasis role="bold">mysqli</emphasis> extension; or
- configure the MySQL server with
- <option>--old-passwords</option>. (See
- <xref linkend="old-client"/>, for more information.)
+ <literal>Error: Client does not support authentication
+ protocol</literal>: This is most often encountered when
+ trying to use the older <literal>mysql</literal> extension
+ with MySQL 4.1.1 and later. Possible solutions are:
+ downgrade to MySQL 4.0; switch to PHP 5 and the newer
+ <literal>mysqli</literal> extension; or configure the MySQL
+ server with <option>--old-passwords</option>. (See
+ <xref linkend="old-client"/> for more information.)
</para>
</listitem>
| Thread |
|---|
| • bk commit - mysqldoc@docsrva tree (jon:1.3388) | jon | 25 Aug |
