1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
<?xml version="1.0" encoding="UTF-8"?>
<refentry version="5.0-subset Scilab" xml:id="mysql_insert_id" xml:lang="en"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:ns3="http://www.w3.org/1999/xhtml"
xmlns:mml="http://www.w3.org/1998/Math/MathML"
xmlns:db="http://docbook.org/ns/docbook">
<refnamediv>
<refname>mysql_insert_id</refname>
<refpurpose>Returns the value generated for an AUTO_INCREMENT
column by the previous INSERT or UPDATE statement.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Calling Sequence</title>
<synopsis>id_pos = mysql_insert_id(mysql)</synopsis>
</refsynopsisdiv>
<refsection>
<title>Description</title>
<para>Returns the value generated for an AUTO_INCREMENT
column by the previous INSERT or UPDATE statement. </para>
<para>Use this function after you have performed an INSERT
statement into a table that contains an AUTO_INCREMENT field,
or have used INSERT or UPDATE to set a column value with LAST_INSERT_ID(expr).</para>
<para>The return value of <literal>mysql_insert_id</literal> is always
zero unless explicitly updated under one of the following conditions:</para>
<itemizedlist>
<listitem>
<para>INSERT statements that store a value into an AUTO_INCREMENT column.</para>
<para>This is true whether the value is automatically generated by storing
the special values NULL or 0 into the column, or is an explicit nonspecial value.</para>
</listitem>
<listitem>
<para>In the case of a multiple-row INSERT statement, the
return value of <literal>mysql_insert_id</literal> depends on the MySQL server version.</para>
<para>In MySQL 5.1.12 and later, <literal>mysql_insert_id</literal>
returns the first automatically generated AUTO_INCREMENT value
that was successfully inserted.</para>
<para>In MySQL 5.1.11 and earlier, <literal>mysql_insert_id</literal>
returns the first automatically generated AUTO_INCREMENT value,
regardless of whether insertion of that value was successful.</para>
<para>If no rows are successfully inserted, <literal>mysql_insert_id</literal> returns 0.</para>
</listitem>
<listitem>
<para>Starting in MySQL 5.1.12, if an <literal>INSERT ... SELECT</literal>
statement is executed, and no automatically generated
value is successfully inserted, <literal>mysql_insert_id</literal>
returns the ID of the last inserted row.</para>
</listitem>
<listitem>
<para>Starting in MySQL 5.1.12, if an <literal>INSERT ... SELECT</literal>
statement uses LAST_INSERT_ID(expr), <literal>mysql_insert_id</literal> returns expr.</para>
</listitem>
<listitem>
<para>INSERT statements that generate an AUTO_INCREMENT
value by inserting LAST_INSERT_ID(expr) into any column
or by updating any column to LAST_INSERT_ID(expr).</para>
</listitem>
<listitem>
<para>If the previous statement returned an error,
the value of <literal>mysql_insert_id</literal> is undefined.</para>
</listitem>
</itemizedlist>
<para>For 5.1.12 and later, the return value of
<literal>mysql_insert_id</literal> can be simplified to the following sequence:</para>
<orderedlist>
<listitem>
<para>If there is an AUTO_INCREMENT column, and an
automatically generated value was successfully inserted,
return the first such value.</para>
</listitem>
<listitem>
<para>If LAST_INSERT_ID(expr) occurred in the statement,
return expr, even if there was an AUTO_INCREMENT column
in the affected table.</para>
</listitem>
<listitem>
<para>The return value varies depending on the statement used. When called after an INSERT statement:</para>
<itemizedlist>
<listitem>
<para>If there is an AUTO_INCREMENT column in the table, and
there were some explicit values for this column that were
successfully inserted into the table, return the last
of the explicit values. </para>
</listitem>
</itemizedlist>
<para>When called after an INSERT ... ON DUPLICATE KEY UPDATE statement:</para>
<itemizedlist>
<listitem>
<para>If there is an AUTO_INCREMENT column in the
table and there were some explicit succesfully inserted
values, or some updated rows, return the last of the
inserted or updated values. </para>
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
<para><literal>mysql_insert_id</literal> returns 0 if the
previous statement does not use an AUTO_INCREMENT value.</para>
<para>If you need to save the value for later, be sure to call
<literal>mysql_insert_id</literal> immediately after the
statement that generates the value.</para>
<para>The value of <literal>mysql_insert_id</literal> is affected
only by statements issued within the current client connection.</para>
<para>It is not affected by statements issued by other clients.</para>
<para>The LAST_INSERT_ID() SQL function returns the value of the
first automatically generated value that was successfully
inserted (starting from 5.1.12) or the first automatically
generated value if any rows were successfully inserted (before 5.1.12).</para>
<para>LAST_INSERT_ID() is not reset between statements because the
value of that function is maintained in the server.</para>
<para>Another difference from <literal>mysql_insert_id</literal>
is that LAST_INSERT_ID() is not updated if you set an
AUTO_INCREMENT column to a specific nonspecial value.</para>
<para><literal>mysql_insert_id</literal> returns 0 following a
CALL statement for a stored procedure that generates an
AUTO_INCREMENT value because in this case
<literal>mysql_insert_id</literal> applies to CALL and not
the statement within the procedure.</para>
<para>Within the procedure, you can use LAST_INSERT_ID() at
the SQL level to obtain the AUTO_INCREMENT value.</para>
<para>The reason for the differences between LAST_INSERT_ID()
and <literal>mysql_insert_id</literal> is that
LAST_INSERT_ID() is made easy to use in scripts while
<literal>mysql_insert_id</literal> tries to provide
more exact information about what happens to the AUTO_INCREMENT column.</para>
</refsection>
<refsection>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>mysql</term>
<listitem>
<para>a MySQL pointer</para>
</listitem>
</varlistentry>
<varlistentry>
<term>id_pos</term>
<listitem>
<para>see the description.</para>
</listitem>
</varlistentry>
</variablelist>
</refsection>
<refsection>
<title>See Also</title>
<simplelist type="inline">
<member><link linkend="mysql_init">mysql_init</link></member>
<member><link linkend="mysql_real_connect">mysql_real_connect</link></member>
<member><link linkend="mysql_close">mysql_close</link></member>
</simplelist>
</refsection>
<refsection>
<title>Authors</title>
<simplelist type="vert">
<member>Yann COLLETTE</member>
</simplelist>
</refsection>
</refentry>
|
