C API Threaded Function Descriptions
------------------------------------

You need to use the following functions when you want to create a
threaded client. *Note Threaded clients::.

`my_init()'
...........

`void my_init(void)'

Description
...........

 will also
call `mysql_thread_init()' for this thread.

This is automatically called by `mysql_init()', `mysql_server_init()'
and `mysql_connect()'.

Return Values
.............

None.

`mysql_thread_init()'
.....................

`my_bool mysql_thread_init(void)'

Description
...........

This function needs to be called for each created thread to initialise
thread-specific variables.

This is automatically called by `my_init()' and `mysql_connect()'.

Return Values
.............

Zero if successful. Non-zero if an error occurred.

`mysql_thread_end()'
....................

`void mysql_thread_end(void)'

Description
...........

This function needs to be called before calling `pthread_exit()' to
free memory allocated by `mysql_thread_init()'.

Note that this function *is not invoked automatically* by the client
library.  It must be called explicitly to avoid a memory leak.

Return Values
.............

None.

`mysql_thread_safe()'
.....................

`unsigned int mysql_thread_safe(void)'

Description
...........

This function indicates whether the client is compiled as thread-safe.

Return Values
.............

1 is the client is thread-safe, 0 otherwise.


C API Embedded Server Function Descriptions
-------------------------------------------

You must use the following functions if you want to allow your
application to be linked against the embedded MySQL server library.
*Note libmysqld::.


modifying any code.

`mysql_server_init()'
.....................

`int mysql_server_init(int argc, char **argv, char **groups)'

Description
...........

  that
the server uses.  If this function is not called, the program will
crash.  If you are using the DBUG package that comes with MySQL, you
should call this after you have called `MY_INIT()'.


if there are no command-line arguments for the server.
`mysql_server_init()' makes a copy of the arguments so it's safe to
destroy `argv' or `groups' after the call.

 and
`[emedded]' groups will be active.

Example
.......

     #include 
     #include 
     
     static char *server_args[] = {
       "this_program",       /* this string is not used */
       "--datadir=.",
       "--key_buffer_size=32M"
     };
     static char *server_groups[] = {
       "embedded",
       "server",
       "this_program_SERVER",
       (char *)NULL
     };
     
     int main(void) {
       mysql_server_init(sizeof(server_args) / sizeof(char *),
                         server_args, server_groups);
     
       /* Use any MySQL API functions here */
     
       mysql_server_end();
     
       return EXIT_SUCCESS;
     }

Return Values
.............

0 if okay, 1 if an error occurred.

`mysql_server_end()'
....................

`void mysql_server_end(void)'

Description
...........

This function *must* be called once in the program after all other
MySQL functions.  It shuts down the embedded server.

Return Values
.............

None.


Common questions and problems when using the C API
--------------------------------------------------

Why Is It that After `mysql_query()' Returns Success, `mysql_store_result()' Sometimes Returns `NULL'?
......................................................................................................

It is possible for `mysql_store_result()' to return `NULL' following a
successful call to `mysql_query()'.  When this happens, it means one of
the following conditions occurred:

   * There was a `malloc()' failure (for example, if the result set was
     too large).

   * The data couldn't be read (an error occurred on the connection).

   * The query returned no data (for example, it was an `INSERT',
     `UPDATE', or `DELETE').

You can always check whether the statement should have produced a
non-empty result by calling `mysql_field_count()'.  If
`mysql_field_count()' returns zero, the result is empty and the last
query was a statement that does not return values (for example, an
`INSERT' or a `DELETE').  If `mysql_field_count()' returns a non-zero
value, the statement should have produced a non-empty result.  See the
description of the `mysql_field_count()' function for an example.

You can test for an error by calling `mysql_error()' or `mysql_errno()'.

What Results Can I Get From a Query?
....................................

In addition to the result set returned by a query, you can also get the
following information:

    the
     table is re-created empty, which is much faster! In this case,
     `mysql_affected_rows()' returns zero for the number of records
     affected.

   * `mysql_num_rows()' returns the number of rows in a result set.
     With `mysql_store_result()', `mysql_num_rows()' may be called as
     soon as `mysql_store_result()' returns.  With `mysql_use_result()',
     `mysql_num_rows()' may be called only after you have fetched all
     the rows with `mysql_fetch_row()'.

   * `mysql_insert_id()' returns the ID generated by the last query
     that inserted a row into a table with an `AUTO_INCREMENT' index.
     *Note `mysql_insert_id()': mysql_insert_id.

   * Some queries (`LOAD DATA INFILE ...', `INSERT INTO ... SELECT
     ...', `UPDATE') return additional information.  The result is
     returned by `mysql_info()'.  See the description for `mysql_info()'
     for the format of the string that it returns.  `mysql_info()'
     returns a `NULL' pointer if there is no additional information.

How Can I Get the Unique ID for the Last Inserted Row?
......................................................

If you insert a record in a table containing a column that has the
`AUTO_INCREMENT' attribute, you can get the most recently generated ID
by calling the `mysql_insert_id()' function.

You can also retrieve the ID by using the `LAST_INSERT_ID()' function in
a query string that you pass to `mysql_query()'.

You can check if an `AUTO_INCREMENT' index is used by executing the
following code. This also checks if the query was an `INSERT' with an
`AUTO_INCREMENT' index:

     if (mysql_error(&mysql)[0] == 0 &&
         mysql_num_fields(result) == 0 &&
         mysql_insert_id(&mysql) != 0)
     {
         used_id = mysql_insert_id(&mysql);
     }

The most recently generated ID is maintained in the server on a
per-connection basis.  It will not be changed by another client. It
will not even be changed if you update another `AUTO_INCREMENT' column
with a non-magic value (that is, a value that is not `NULL' and not
`0').

If you want to use the ID that was generated for one table and insert
it into a second table, you can use SQL statements like this:

     INSERT INTO foo (auto,text)
         VALUES(NULL,'text');              # generate ID by inserting NULL
     INSERT INTO foo2 (id,text)
         VALUES(LAST_INSERT_ID(),'text');  # use ID in second table

Problems Linking with the C API
...............................

When linking with the C API, the following errors may occur on some
systems:

     gcc -g -o client test.o -L/usr/local/lib/mysql -lmysqlclient -lsocket -lnsl
     
     Undefined        first referenced
      symbol          in file
     floor            /usr/local/lib/mysql/libmysqlclient.a(password.o)
     ld: fatal: Symbol referencing errors. No output written to client

If this happens on your system, you must include the math library by
adding `-lm' to the end of the compile/link line.


Building Client Programs
------------------------

If you compile MySQL clients that you've written yourself or that you
obtain from a third-party, they must be linked using the `-lmysqlclient
-lz' option on the link command.  You may also need to specify a `-L'
option to tell the linker where to find the library.  For example, if
the library is installed in `/usr/local/mysql/lib', use
`-L/usr/local/mysql/lib -lmysqlclient -lz' on the link command.

For clients that use MySQL header files, you may need to specify a `-I'
option when you compile them (for example,
`-I/usr/local/mysql/include'), so the compiler can find the header
files.

To make the above simpler on Unix we have provided the `mysql_config'
script for you. *Note `mysql_config': mysql_config.

You can use this to compile a MySQL client by as follows:

     CFG=/usr/local/mysql/bin/mysql_config
     sh -c "gcc -o progname `$CFG --cflags` progname.c `$CFG --libs`"

The `sh -c' is need to get the shell to not threat the output from
`mysql_config' as one word.

[Назад] [Содержание] [Вперед]