C API函数描写叙述(S-W)

int mysql_set_character_set(MYSQL *mysql, char *csname)

描写叙述

该函数用于为当前连接设置默认的字符集。

字符串csname指定了1个有效的字符集名称。连接校对成为字符集的默认校对。该函数的工作方式与SET NAMES语句相似，但它还能设置mysql->charset的值。从而影响了由mysql_real_escape_string()设置的字符集。

该函数是在MySQL 5.0.7中添加的。

返回值

0表示成功，非0值表示出现错误。

演示样例：

MYSQL mysql;

?

mysql_init(&mysql);

if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))

{

??? fprintf(stderr, "Failed to connect to database: Error: %s\n",

????????? mysql_error(&mysql));

}

?

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

{

??? printf("New client character set: %s\n", mysql_character_set_name(&mysql));

}

int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)

描写叙述

同意或禁止连接的选项。选项能够取下述值之中的一个：

返回值

0表示成功。非0值表示出现错误。

错误

·????????CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序运行了命令。

·????????CR_SERVER_GONE_ERROR

MySQLserver不可用。

·????????CR_SERVER_LOST

在查询过程中。与server的连接丢失。

·????????ER_UNKNOWN_COM_ERROR

server不支持mysql_set_server_option()（当server版本号低于4.1.1时）。或server不支持试图设置的选项。

int mysql_shutdown(MYSQL *mysql, enum enum_shutdown_level shutdown_level)

描写叙述

请求数据库server关闭。已连接的用户必须具有SHUTDOWN权限。MySQL 5.1server仅支持1种关闭类型。shutdown_level必须等效于SHUTDOWN_DEFAULT。设计规划了额外的关闭级别，以便能够选择所需的级别。

对于用旧版本号libmysqlclient头文件编译并调用mysql_shutdown()的动态链接可运行程序，须要与旧版的libmysqlclient动态库一起使用。

在5.5节。“MySQLserver关机进程”中，介绍了关机进程。

返回值

0表示成功，非0值表示出现错误。

错误

·????????CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序运行了命令。

·????????CR_SERVER_GONE_ERROR

MySQLserver不可用。

·????????CR_SERVER_LOST

在查询过程中。与server的连接丢失。

·????????CR_UNKNOWN_ERROR

出现未知错误。

const char *mysql_sqlstate(MYSQL *mysql)

描写叙述

返回由Null终结的字符串，该字符串包括关于上次错误的SQLSTATE错误代码。错误代码包括5个字符。‘00000‘表示无错误。

其值由ANSI SQL和ODBC指定。

关于可能取值的列表，请參见附录B：错误代码和消息。

注意。并不是全部的MySQL错误均会被映射到SQLSTATE错误代码。值‘HY000‘（一般错误）用于未映射的错误。

返回值

包括SQLSTATE错误码的、由Null终结的字符串。

另请參见：

请參见25.2.3.14节，“mysql_errno()”。请參见25.2.3.15节，“mysql_error()”。

请參见25.2.7.26节。“mysql_stmt_sqlstate()”。

int mysql_ssl_set(MYSQL *mysql, const char *key, const char *cert, const char *ca, const char *capath, const char *cipher)

描写叙述

使用mysql_ssl_set()。可採用SSL建立安全连接。

必须在mysql_real_connect()之前调用它。

除非在client库中同意了OpenSSL支持，否则mysql_ssl_set()不作不论什么事。

Mysql是从mysql_init()返回的连接处理程序。其它參数的指定例如以下：

·????????key是key文件的路径名。

·????????cert是证书文件的路径名。

·????????ca是证书授权文件的路径名。

·????????capath是指向文件夹的路径名。该文件夹中包括以pem格式给出的受信任SSL CA证书。

·????????cipher是同意password的列表，用于SSL加密。

对于不论什么未使用的SSL參数，可为其给定NULL。

返回值

该函数总返回0。假设SSL设置不对。当你尝试连接时，mysql_real_connect()将返回错误。

char *mysql_stat(MYSQL *mysql)

描写叙述

返回包括特定信息的字符串。该信息与mysqladmin status命令提供的信息相似。

包括以秒为单位的正常运行时间，以及运行线程的数目，问题数。再载入次数，以及打开的表数目。

返回值

描写叙述server状态的字符集。

假设出现错误，返回NULL。

错误

·????????CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序运行了命令。

·????????CR_SERVER_GONE_ERROR

MySQLserver不可用。

·????????CR_SERVER_LOST

在查询过程中，与server的连接丢失。

·????????CR_UNKNOWN_ERROR

出现未知错误。

MYSQL_RES *mysql_store_result(MYSQL *mysql)

描写叙述

对于成功检索了数据的每一个查询（SELECT、SHOW、DESCRIBE、EXPLAIN、CHECK TABLE等），必须调用mysql_store_result()或mysql_use_result()。

对于其它查询。不须要调用mysql_store_result()或mysql_use_result()。可是假设在不论什么情况下均调用了mysql_store_result()，它也不会导致不论什么伤害或性能减少。通过检查mysql_store_result()是否返回0，可检測查询是否没有结果集（以后会很多其它）。

假设希望了解查询是否应返回结果集。可使用mysql_field_count()进行检查。请參见25.2.3.22节，“mysql_field_count()”。

mysql_store_result()将查询的全部结果读取到client。分配1个MYSQL_RES结构，并将结果置于该结构中。

假设查询未返回结果集，mysql_store_result()将返回Null指针（比如。假设查询是INSERT语句）。

假设读取结果集失败，mysql_store_result()还会返回Null指针。通过检查mysql_error()是否返回非空字符串，mysql_errno()是否返回非0值。或mysql_field_count()是否返回0，能够检查是否出现了错误。

假设未返回行，将返回空的结果集。（空结果集设置不同于作为返回值的空指针）。

一旦调用了mysql_store_result()并获得了不是Null指针的结果。可调用mysql_num_rows()来找出结果集中的行数。

能够调用mysql_fetch_row()来获取结果集中的行，或调用mysql_row_seek()和mysql_row_tell()来获取或设置结果集中的当前行位置。

一旦完毕了对结果集的操作。必须调用mysql_free_result()。

请參见25.2.13.1节，“为什么在mysql_query()返回成功后，mysql_store_result()有时会返回NULL”.

返回值

具有多个结果的MYSQL_RES结果集合。

假设出现错误，返回NULL。

错误

假设成功。mysql_store_result()将复位mysql_error()和mysql_errno()。

·????????CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序运行了命令。

·????????CR_OUT_OF_MEMORY

内存溢出。

·????????CR_SERVER_GONE_ERROR

MySQLserver不可用。

·????????CR_SERVER_LOST

在查询过程中，与server的连接丢失。

·????????CR_UNKNOWN_ERROR

出现未知错误。

unsigned long mysql_thread_id(MYSQL *mysql)

描写叙述

返回当前连接的线程ID。

该值可用作mysql_kill()的參量以杀死线程。

假设连接丢失，并使用mysql_ping()进行了再连接。线程ID将改变。这意味着你不应获取线程ID并保存它供以后使用。应在须要时获取它。

返回值

当前连接的线程ID。

错误

无。

MYSQL_RES *mysql_use_result(MYSQL *mysql)

描写叙述

对于成功检索数据的每一个查询（SELECT、SHOW、DESCRIBE、EXPLAIN）。必须调用mysql_store_result()或mysql_use_result()。

mysql_use_result()将初始化结果集检索，但并不像mysql_store_result()那样将结果集实际读取到client。它必须通过对mysql_fetch_row()的调用，对每一行分别进行检索。

这将直接从server读取结果，而不会将其保存在暂时表或本地缓冲区内，与mysql_store_result()相比，速度更快并且使用的内存也更少。client仅为当前行和通信缓冲区分配内存，分配的内存可添加到max_allowed_packet字节。

还有一方面，假设你正在client一側为各行进行大量的处理操作，或者将输出发送到了用户可能会键入“^S”（停止滚动）的屏幕，就不应使用mysql_use_result()。

这会绑定server，并阻止其它线程更新不论什么表（数据从这类表获得）。

使用mysql_use_result()时。必须运行mysql_fetch_row()，直至返回NULL值，否则，未获取的行将作为下一个检索的一部分返回。C API给出命令不同步错误。假设忘记了运行该操作，将不能运行该命令。

不应与从mysql_use_result()返回的结果一起使用mysql_data_seek()、mysql_row_seek()、mysql_row_tell()、mysql_num_rows()或mysql_affected_rows()，也不应发出其它查询，直至mysql_use_result()完毕为止。（可是，提取了全部行后，mysql_num_rows()将准确返回提取的行数）。

一旦完毕了对结果集的操作，必须调用mysql_free_result()。

使用libmysqld嵌入式server时。因为在调用mysql_free_result()之前，内存使用将随着每一个检索的行添加，内存效益将基本丧失。

返回值

MYSQL_RES结果结构。假设出现错误，返回NULL。

错误

假设成功，mysql_use_result()将复位mysql_error()和mysql_errno()。

·????????CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序运行了命令。

·????????CR_OUT_OF_MEMORY

内存溢出。

·????????CR_SERVER_GONE_ERROR

MySQLserver不可用。

·????????CR_SERVER_LOST

在查询过程中，与server的连接丢失。

·????????CR_UNKNOWN_ERROR

出现未知错误。