CAPI function description (G-N)

25.2.3.26.mysql _ get_character_set_info () voidmysql_get_character_set_info (MYSQL * mysql, MY_CHARSET_INFO * cs) describes the functions that provide information about the Default Client character set. You can use the mysql_set_character_set () function to change the default character set. This function is added in MySQL5.0.10

25.2.3.26. mysql_get_character_set_info () void mysql_get_character_set_info (MYSQL * mysql, MY_CHARSET_INFO * cs) describes the Default Client Character Set provided by this function. You can use the mysql_set_character_set () function to change the default character set. This function is added in MySQL 5.0.10.

25.2.3.26. mysql_get_character_set_info ()

Void mysql_get_character_set_info (MYSQL * mysql, MY_CHARSET_INFO * cs)

Description

This function provides information about the Default Client character set. You can use the mysql_set_character_set () function to change the default character set.

This function is added in MySQL 5.0.10.

Example:

if (!mysql_set_character_set(&mysql, "utf8"))

{

    MY_CHARSET_INFO cs;

    mysql_get_character_set_info(&mysql, &cs);

    printf("character set information:\n");

    printf("character set name: %s\n", cs.name);

    printf("collation name: %s\n", cs.csname);

    printf("comment: %s\n", cs.comment);

    printf("directory: %s\n", cs.dir);

    printf("multi byte character min. length: %d\n", cs.mbminlen);

    printf("multi byte character max. length: %d\n", cs.mbmaxlen);

}

25.2.3.27. mysql_get_client_info ()

Char * mysql_get_client_info (void)

Description

Returns the string representing the client database version.

Return Value

String Of the MySQL client version.

Error

None.

25.2.3.28. mysql_get_client_version ()

Unsigned long mysql_get_client_version (void)

Description

Returns the integer that represents the client database version. The value is in the format of XYYZZ. X indicates the main version number, YY indicates the release level, and ZZ indicates the version number within the release level. For example, the value 40102 indicates that the client database version is 4.1.2.

Return Value

The integer of the MySQL client version.

Error

None.

25.2.3.29. mysql_get_host_info ()

Char * mysql_get_host_info (MYSQL * mysql)

Description

Returns a string describing the connection type used, including the server host name.

Return Value

A string that represents the server host name and connection type.

Error

None.

25.2.3.30. mysql_get_proto_info ()

Unsigned int mysql_get_proto_info (MYSQL * mysql)

Description

Returns the Protocol version used by the current connection.

Return Value

Indicates the unsigned integer of the Protocol version used for the current connection.

Error

None.

25.2.3.31. mysql_get_server_info ()

Char * mysql_get_server_info (MYSQL * mysql)

Description

Returns a string representing the server version number.

Return Value

A string representing the server version number.

Error

None.

25.2.3.32. mysql_get_server_version ()

Unsigned long mysql_get_server_version (MYSQL * mysql)

Description

Returns the server version number in integer format.

Return Value

The value of the MySQL server version, in the following format:

major_version*10000 + minor_version *100 + sub_version

For example, for 5.0.12, 500012 is returned.

In client programs, this function is useful to quickly determine whether certain version-related server functions exist.

Error

None.

25.2.3.33. mysql_hex_string ()

Unsigned long mysql_hex_string (char * to, const char * from, unsigned long length)

Description

This function is used to create valid SQL strings available in SQL statements. See section 9.1.1, "string ".

The string is formally encoded in hexadecimal format. Each character is encoded in two hexadecimal numbers. The result is placed in it and an ending Null byte is added.

The string "from" must be a long byte ". A buffer must be allocated for "to". The buffer length must be at least 2 + 1 bytes long. When mysql_hex_string () is returned, the content of "to" is a string terminated by Null. The return value is the length of the encoded string, excluding the Null character used for termination.

Use 0xValueOr x'Value'Format: place the returned value in an SQL statement. However, the returned values do not include 0x or x '...'. The caller must provide the desired format.

Example:

char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");

end = strmov(end,"0x");

end += mysql_hex_string(end,"What's this",11);

end = strmov(end,",0x");

end += mysql_hex_string(end,"binary data: \0\r\n",16);

*end++ = ')';

if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))

{

   fprintf(stderr, "Failed to insert row, Error: %s\n",

           mysql_error(&mysql));

}

The strmov () function used in the example is included in the mysqlclient library. It works in a way similar to strcpy (), but returns a pointer pointing to the 1st parameter to terminate Null.

Return Value

Length of the value placed in "to", excluding the Null character used to terminate.

Error

None.

25.2.3.34. mysql_info ()

Char * mysql_info (MYSQL * mysql)

Description

Returns a string that provides information about the latest query executed, but is only valid for the statements listed here. For other statements, mysql_info () returns NULL. The string format depends on the query type, as described in this section. The value is descriptive only, and the string contains the value suitable for the query.

· Insert into... SELECT...

String format: Record, 100; copy, 0; warning, 0

· Insert into... VALUES (...),(...),(...)...

String format: Record, 3; copy, 0; warning, 0

· Load data infile...

String format: Record, 1; delete, 0; Skip, 0; warning, 0

· ALTER TABLE

String format: Record, 3; copy, 0; warning, 0

· UPDATE

String format: Match row, 40; change, 40; warning, 0

Note that mysql_info () is INSERT... VALUES returns a non-NULL value, INSERT... VALUES is only used for statements in the form of multiple rows (that is, only when multiple value lists are specified ).

Return Value

String, which indicates the additional information of the latest query. If no information is available for this query, NULL is returned.

Error

None.

25.2.3.35. mysql_init ()

MYSQL * mysql_init (MYSQL * mysql)

Description

Allocate or initialize MYSQL objects that are compatible with mysql_real_connect. If mysql is a NULL pointer, this function will allocate, initialize, and return a new object. Otherwise, the object is initialized and the address of the object is returned. If mysql_init () is assigned a new object, when mysql_close () is called to close the connection. This object will be released.

Return Value

Initialized MYSQL * handle. If there is not enough memory to allocate new objects, NULL is returned.

Error

If the memory is insufficient, NULL is returned.

25.2.3.36. mysql_insert_id ()

My_ulonglong mysql_insert_id (MYSQL * mysql)

Description

Returns the value generated by the previous INSERT or UPDATE statement for the AUTO_INCREMENT column. This function is used after an INSERT statement is executed in a table containing the AUTO_INCREMENT field.

To be more accurate, mysql_insert_id () will be updated under the following conditions ():

· Save the value to the INSERT statement in the AUTO_INCREMENT column. Whether the value is automatically generated by storing the special value NULL or 0 in the column or the exact non-special value, it is true.

· In the case of multiple INSERT statements, mysql_insert_id () returns 1st automatically generated AUTO_INCREMENT values. If such values are not generated, insert the last exact value in the AUTO_INCREMENT column.

· By adding LAST_INSERT_ID (Expr) INSERT the statement into any column to generate the AUTO_INCREMENT value.

· Update any column to LAST_INSERT_ID (Expr) To generate the INSERT statement for the AUTO_INCREMENT value.

· The value of mysql_insert_id () is not affected by statements that return result sets, such as SELECT.

· If the preceding statement returns an error, the value of mysql_insert_id () will be uncertain.

Note: If the previous statement does not use AUTO_INCREMENT, mysql_insert_id () returns 0. To save the value, you must call mysql_insert_id () immediately after generating the value statement ().

The value of mysql_insert_id () is only affected by the statements sent in the current client connection. It is not affected by statements issued by other clients.

See section 12.9.3 "information functions ".

In addition, you should also note that the value of the SQL LAST_INSERT_ID () function always includes the recently generated AUTO_INCREMENT value and will not be reset between statements, the reason is that the function value is maintained on the server. The other difference is that if the AUTO_INCREMENT column is set to specify non-special values, LAST_INSERT_ID () is not updated ().

LAST_INSERT_ID () is different from mysql_insert_id () Because LAST_INSERT_ID () is easy to use in scripts, while mysql_insert_id () then, it tries to provide more accurate information about the situation in the AUTO_INCREMENT column.

Return Value

This is described in the previous discussion.

Error

None.

25.2.3.37. mysql_kill ()

Int mysql_kill (MYSQL * mysql, unsigned long pid)

Description

The request server kills the thread specified by the pid.

Return Value

0 indicates success, and a non-0 value indicates an error.

Error

· CR_COMMANDS_OUT_OF_SYNC

The command is executed in an inappropriate order.

· CR_SERVER_GONE_ERROR

The MySQL server is unavailable.

· CR_SERVER_LOST

The connection to the server is lost during the Query Process.

· CR_UNKNOWN_ERROR

An unknown error occurs.

25.2.3.38. mysql_library_end ()

Void mysql_library_end (void)

Description

It is a synonym for the mysql_server_end () function.

For specific usage, see section 25.2.2, "c api function overview ".

25.2.3.39. mysql_library_init ()

Int mysql_library_init (int argc, char ** argv, char ** groups)

Description

This is a synonym for the mysql_server_init () function.

For specific usage, see section 25.2.2, "c api function overview ".

25.2.3.40. mysql_list_dbs ()

MYSQL_RES * mysql_list_dbs (MYSQL * mysql, const char * wild)

Description

Returns a result set composed of database names on the server. The server matches a simple regular expression specified by the wildcard parameter. The wildcard parameter can contain the wildcard "%" or "_" or a NULL pointer to match all databases. The method for calling mysql_list_dbs () is similar to executing the SHOW database [LIKE wild] query.

You must use mysql_free_result () to release the result set.

Return Value

Returns the MYSQL_RES result set. If an error occurs, NULL is returned.

Error

· CR_COMMANDS_OUT_OF_SYNC

The command is executed in an inappropriate order.

· CR_OUT_OF_MEMORY

Memory overflow.

· CR_SERVER_GONE_ERROR

The MySQL server is unavailable.

· CR_SERVER_LOST

The connection to the server is lost during the Query Process.

· CR_UNKNOWN_ERROR

An unknown error occurs.

25.2.3.41. mysql_list_fields ()

MYSQL_RES * mysql_list_fields (MYSQL * mysql, const char * table, const char * wild)

Description

Returns a result set composed of field names in a given table. The given table matches the simple regular expression specified by the wildcard parameter. The wildcard parameter can contain the wildcard "%" or "_" or a NULL pointer to match all fields. Calling mysql_list_fields () is similar to executing the show columns from query.Tbl_name[LIKEWild].

Note: We recommend that you use SHOW COLUMNS FROMTbl_nameInstead of mysql_list_fields ().

You must use mysql_free_result () to release the result set.

Return Value

If yes, the MYSQL_RES result set is returned. If an error occurs, NULL is returned.

Error

· CR_COMMANDS_OUT_OF_SYNC

The command is executed in an inappropriate order.

· CR_SERVER_GONE_ERROR

The MySQL server is unavailable.

· CR_SERVER_LOST

The connection to the server is lost during the Query Process.

· CR_UNKNOWN_ERROR

An unknown error occurs.

25.2.3.42. mysql_list_processes ()

MYSQL_RES * mysql_list_processes (MYSQL * mysql)

Description

Returns the result set that describes the current server thread. This type of information correspondsMysqladmin processlistOr show processlist queries give the same information.

You must use mysql_free_result () to release the result set.

Return Value

If yes, the MYSQL_RES result set is returned. If an error occurs, NULL is returned.

Error

· CR_COMMANDS_OUT_OF_SYNC

The command is executed in an inappropriate order.

· CR_SERVER_GONE_ERROR

The MySQL server is unavailable.

· CR_SERVER_LOST

The connection to the server is lost during the Query Process.

· CR_UNKNOWN_ERROR

An unknown error occurs.

25.2.3.43. mysql_list_tables ()

MYSQL_RES * mysql_list_tables (MYSQL * mysql, const char * wild)

Description

Returns the result set composed of the table names in the current database. The current database matches the simple regular expression specified by the wildcard parameter. The wildcard parameter can contain the wildcard "%" or "_" or a NULL pointer to match all tables. The method for calling mysql_list_tables () is similar to HOW tables [LIKEWild].

You must use mysql_free_result () to release the result set.

Return Value

If yes, the MYSQL_RES result set is returned. If an error occurs, NULL is returned.

Error

· CR_COMMANDS_OUT_OF_SYNC

The command is executed in an inappropriate order.

· CR_SERVER_GONE_ERROR

The MySQL server is unavailable.

· CR_SERVER_LOST

The connection to the server is lost during the Query Process.

· CR_UNKNOWN_ERROR

An unknown error occurs.

25.2.3.44. mysql_more_results ()

My_bool mysql_more_results (MYSQL * mysql)

Description

If the current query has multiple results, "true" is returned, and the application must call mysql_next_result () to obtain the results.

Return Value

If multiple results exist, "true" (1) is returned. If no results exist, "false" (0) is returned ).

In most cases, you can call mysql_next_result () to test whether multiple results exist. If multiple results exist, initialize the search.

See section 25.2.9, "c api processing for multi-query execution ". See section 25.2.3.45, "mysql_next_result ()".

Error

None.

25.2.3.45. mysql_next_result ()

Int mysql_next_result (MYSQL * mysql)

Description

If multiple query results exist, mysql_next_result () reads the next query result and returns the status to the application.

If the preceding query returns a result set, you must call mysql_free_result () for it ().

After mysql_next_result () is called, the connection status is the same as when you have called mysql_real_query () or mysql_query () for the next query. This means you can call mysql_store_result (), mysql_warning_count (), mysql_affected_rows (), and so on.

If mysql_next_result () returns an error, no other statements are executed and no more results are obtained,

See section 25.2.9, "c api processing for multi-query execution ".

Return Value

Return Value	Description
0	Successful with multiple results.
-1	Successful but no results are returned.
> 0	Error

Error

· CR_COMMANDS_OUT_OF_SYNC

The command is executed in an inappropriate order. For example, mysql_use_result () is not called for the previous result set ().

· CR_SERVER_GONE_ERROR

The MySQL server is unavailable.

· CR_SERVER_LOST

The connection to the server is lost during the Query Process.

· CR_UNKNOWN_ERROR

An unknown error occurs.

25.2.3.46. mysql_num_fields ()

Unsigned int mysql_num_fields (MYSQL_RES * result)

To replace the MYSQL * parameter, use the unsigned integer mysql_field_count (MYSQL * mysql ).

Description

The number of rows in the returned result set.

Note: You can obtain the number of rows from the pointer to the result set or the pointer to the connection handle. If mysql_store_result () or mysql_use_result () returns NULL, the connection handle should be used (so there is no result set pointer ). In this case, you can use mysql_field_count () to determine whether non-empty results are generated by mysql_store_result. In this way, the client program can take appropriate actions without knowing whether the query is a SELECT statement (or similar to a SELECT statement ). The following example describes how to perform this operation.

See section 25.2.13.1, "Why does mysql_store_result () sometimes return NULL after mysql_query () returns success?”。

Return Value

The unsigned integer that represents the number of rows in the result set.

Error

None.

Example:

MYSQL_RES *result;

unsigned int num_fields;

unsigned int num_rows;

if (mysql_query(&mysql,query_string))

{

    // error

}

else // query succeeded, process any data returned by it

{

    result = mysql_store_result(&mysql);

    if (result)  // there are rows

    {

        num_fields = mysql_num_fields(result);

        // retrieve rows, then call mysql_free_result(result)

    }

    else  // mysql_store_result() returned nothing; should it have?

    {

        if (mysql_errno(&mysql))

        {

           fprintf(stderr, "Error: %s\n", mysql_error(&mysql));

        }

        else if (mysql_field_count(&mysql) == 0)

        {

            // query does not return data

            // (it was not a SELECT)

            num_rows = mysql_affected_rows(&mysql);

        }

    }

}

Another option is to replace mysql_errno (& mysql) call by checking "mysql_field_count (& mysql) is = 0" if you know that your query should return a result set. Use it only when an error occurs.

25.2.3.47. mysql_num_rows ()

My_ulonglong mysql_num_rows (MYSQL_RES * result)

Description

The number of rows in the returned result set.

The use of mysql_num_rows () depends on whether mysql_store_result () or mysql_use_result () is used to return the result set. If mysql_store_result () is used, you can call mysql_num_rows () immediately (). If mysql_use_result () and mysql_num_rows () are used, the correct value is not returned until all rows in the result set are retrieved.

Return Value

The number of rows in the result set.

Error

None.