25.2.3.36. mysql_insert_id()
my_ulonglong mysql_insert_id(MYSQL *mysql)
Description
Returns the value generated for an
AUTO_INCREMENT column by the previous
INSERT or UPDATE
statement. Use this function after you have performed an
INSERT statement into a table that contains
an AUTO_INCREMENT field.
More precisely, mysql_insert_id() is
updated under these conditions:
INSERT statements that store a value
into an AUTO_INCREMENT column. This is
true whether the value is automatically generated by
storing the special values NULL or
0 into the column, or is an explicit
non-special value.
In the case of a multiple-row INSERT
statement, mysql_insert_id() returns
the first automatically
generated AUTO_INCREMENT value; if no
such value is generated, it returns the last
last explicit value
inserted into the AUTO_INCREMENT
column.
INSERT statements that generate an
AUTO_INCREMENT value by inserting
LAST_INSERT_ID(expr)
into any column.
INSERT statements that generate an
AUTO_INCREMENT value by updating any
column to
LAST_INSERT_ID(expr).
The value of mysql_insert_id() is not
affected by statements such as SELECT
that return a result set.
If the previous statement returned an error, the value of
mysql_insert_id() is undefined.
Note that mysql_insert_id() returns
0 if the previous statement does not use an
AUTO_INCREMENT value. If you need to save
the value for later, be sure to call
mysql_insert_id() immediately after the
statement that generates the value.
The value of mysql_insert_id() is affected
only by statements issued within the current client
connection. It is not affected by statements issued by other
clients.
See Section 12.10.3, “Information Functions”.
Also note that the value of the SQL
LAST_INSERT_ID() function always contains
the most recently generated AUTO_INCREMENT
value, and is not reset between statements because the value
of that function is maintained in the server. Another
difference is that LAST_INSERT_ID() is not
updated if you set an AUTO_INCREMENT column
to a specific non-special value.
The reason for the difference between
LAST_INSERT_ID() and
mysql_insert_id() is that
LAST_INSERT_ID() is made easy to use in
scripts while mysql_insert_id() tries to
provide a little more exact information of what happens to the
AUTO_INCREMENT column.
Return Values
Described in the preceding discussion.
Errors
None.
