分类： Mysql/postgreSQL
2008-05-12 15:12:28
int mysql_query(MYSQL *mysql, const char *query)
描述
执行由“Null终结的字符串”查询指向的SQL查询。正常情况下，字符串必须包含1条SQL语句，而且不应为语句添加终结分号（‘;’）或“\g”。如果允许多语句执行，字符串可包含多条由分号隔开的语句。请参见25.2.9节，“多查询执行的C API处理”。
mysql_query()不能用于包含二进制数据的查询，应使用mysql_real_query()取而代之（二进制数据可能包含字符‘\0’，mysql_query()会将该字符解释为查询字符串结束）。
如果希望了解查询是否应返回结果集，可使用mysql_field_count()进行检查。请参见25.2.3.22节，“mysql_field_count()”。
返回值
如果查询成功，返回0。如果出现错误，返回非0值。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag)
描述
mysql_real_connect()尝试与运行在主机上的MySQL数据库引擎建立连接。在你能够执行需要有效MySQL连接句柄结构的任何其他API函数之前，mysql_real_connect()必须成功完成。
参数的指定方式如下：
· 第1个参数应是已有MYSQL结构的地址。调用mysql_real_connect()之前，必须调用mysql_init()来初始化MYSQL结构。通过mysql_options()调用，可更改多种连接选项。请参见25.2.3.48节，“mysql_options()”。
· “host”的值必须是主机名或IP地址。如果“host”是NULL或字符串"localhost"，连接将被视为与本地主机的连接。如果操作系统支持套接字（Unix）或命名管道（Windows），将使用它们而不是TCP/IP连接到服务器。
· “user”参数包含用户的MySQL登录ID。如果“user”是NULL或空字符串""，用户将被视为当前用户。在UNIX环境下，它是当前的登录名。在Windows ODBC下，必须明确指定当前用户名。请参见26.1.9.2节，“在Windows上配置MyODBC DSN”。
· “passwd”参数包含用户的密码。如果“passwd”是NULL，仅会对该用户的（拥有1个空密码字段的）用户表中的条目进行匹配检查。这样，数据库管理员就能按特定的方式设置MySQL权限系统，根据用户是否拥有指定的密码，用户将获得不同的权限。
注释：调用mysql_real_connect()之前，不要尝试加密密码，密码加密将由客户端API自动处理。
· “db”是数据库名称。如果db为NULL，连接会将默认的数据库设为该值。
· 如果“port”不是0，其值将用作TCP/IP连接的端口号。注意，“host”参数决定了连接的类型。
· 如果unix_socket不是NULL，该字符串描述了应使用的套接字或命名管道。注意，“host”参数决定了连接的类型。
· client_flag的值通常为0，但是，也能将其设置为下述标志的组合，以允许特定功能：
|
标志名称 |
标志描述 |
|
CLIENT_COMPRESS |
使用压缩协议。 |
|
CLIENT_FOUND_ROWS |
返回发现的行数（匹配的），而不是受影响的行数。 |
|
CLIENT_IGNORE_SPACE |
允许在函数名后使用空格。使所有的函数名成为保留字。 |
|
CLIENT_INTERACTIVE |
关闭连接之前，允许interactive_timeout（取代了wait_timeout）秒的不活动时间。客户端的会话wait_timeout变量被设为会话interactive_timeout变量的值。 |
|
CLIENT_LOCAL_FILES |
允许LOAD DATA LOCAL处理功能。 |
|
CLIENT_MULTI_STATEMENTS |
通知服务器，客户端可能在单个字符串内发送多条语句（由‘;’隔开）。如果未设置该标志，将禁止多语句执行。 |
|
CLIENT_MULTI_RESULTS |
通知服务器，客户端能够处理来自多语句执行或存储程序的多个结果集。如果设置了CLIENT_MULTI_STATEMENTS，将自动设置它。 |
|
CLIENT_NO_SCHEMA |
禁止db_name.tbl_name.col_name语法。它用于ODBC。如果使用了该语法，它会使分析程序生成错误，在捕获某些ODBC程序中的缺陷时，它很有用。 |
|
CLIENT_ODBC |
客户端是ODBC客户端。它将mysqld变得更为ODBC友好。 |
|
CLIENT_SSL |
使用SSL（加密协议）。该选项不应由应用程序设置，它是在客户端库内部设置的。 |
对于某些参数，能够从选项文件获得取值，而不是取得mysql_real_connect()调用中的确切值。为此，在调用mysql_real_connect()之前，应与MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP选项一起调用mysql_options()。随后，在mysql_real_connect()调用中，为准备从选项文件读取值的每个参数指定“无值”值：
· 对于host，指定NULL值或空字符串("")。
· 对于user，指定NULL值或空字符串。
· 对于passwd，指定NULL值。（对于密码，mysql_real_connect()调用中的空字符串的值不能被选项文件中的字符串覆盖，这是因为，空字符串明确指明MySQL账户必须有空密码）。
· 对于db，指定NULL值或空字符串
· 对于port，指定“0”值。
· 对于unix_socket，指定NULL值。
对于某一参数，如果在选项文件中未发现值，将使用它的默认值，如本节前面介绍的那样。
返回值
如果连接成功，返回MYSQL*连接句柄。如果连接失败，返回NULL。对于成功的连接，返回值与第1个参数的值相同。
错误
· CR_CONN_HOST_ERROR
无法连接到MySQL服务器。
· CR_CONNECTION_ERROR
无法连接到本地MySQL服务器。
· CR_IPSOCK_ERROR
无法创建IP套接字。
· CR_OUT_OF_MEMORY
内存溢出。
· CR_SOCKET_CREATE_ERROR
无法创建Unix套接字。
· CR_UNKNOWN_HOST
无法找到主机名的IP地址。
· CR_VERSION_ERROR
协议不匹配，起因于：试图连接到具有特定客户端库（该客户端库使用了不同的协议版本）的服务器。如果使用很早的客户端库来建立与较新的服务器（未使用“--old-protocol”选项开始的）的连接，就会出现该情况。
· CR_NAMEDPIPEOPEN_ERROR
无法在Windows平台下创建命名管道。
· CR_NAMEDPIPEWAIT_ERROR
在Windows平台下等待命名管道失败。
· CR_NAMEDPIPESETSTATE_ERROR
在Windows平台下获取管道处理程序失败。
· CR_SERVER_LOST
如果connect_timeout > 0，而且在连接服务器时所用时间长于connect_timeout秒，或在执行init-command时服务器消失。
示例：
MYSQL mysql; mysql_init(&mysql);mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");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));}
通过使用mysql_options()，MySQL库将读取my.cnf文件的[client]和[your_prog_name]部分，以确保程序工作，即使某人以某种非标准的方式设置MySQL也同样。
注意，一旦建立了连接，mysql_real_connect()将设置再连接标志（MYSQL结构的组成部份）的值，在低于5.0.3版的API中，将其设为“1”，在较新的版本中，将其设为“0”。对于该标志，值“1”表示，如果因连接丢失而无法执行语句，放弃前，将尝试再次连接到服务器。从MySQL 5.0.13开始，可以对mysql_options()使用MYSQL_OPT_RECONNECT选项，对再连接行为进行控制。
unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length)
注意，mysql必须是有效的开放式连接。之所以需要它是因为，转义功能取决于服务器使用的字符集。
描述
该函数用于创建可在SQL语句中使用的合法SQL字符串。请参见9.1.1节，“字符串”。
按照连接的当前字符集，将“from”中的字符串编码为转义SQL字符串。将结果置于“to”中，并添加1个终结用NULL字节。编码的字符为NUL (ASCII 0)、‘\n’、‘\r’、‘\’、‘'’、‘"’、以及Control-Z（请参见9.1节，“文字值”）。（严格地讲，MySQL仅需要反斜杠和引号字符，用于引用转义查询中的字符串。该函数能引用其他字符，从而使得它们在日志文件中具有更好的可读性）。
“from”指向的字符串必须是长度字节“long”。必须为“to”缓冲区分配至少length*2+1字节。在最坏的情况下，每个字符或许需要使用2个字节进行编码，而且还需要终结Null字节。当mysql_real_escape_string()返回时，“to”的内容是由Null终结的字符串。返回值是编码字符串的长度，不包括终结用Null字符。
如果需要更改连接的字符集，应使用mysql_set_character_set()函数，而不是执行SET NAMES (或SET CHARACTER SET)语句。mysql_set_character_set()的工作方式类似于SET NAMES，但它还能影响mysql_real_escape_string()所使用的字符集，而SET NAMES则不能。
示例：
char query[1000],*end; end = strmov(query,"INSERT INTO test_table values(");*end++ = '\'';end += mysql_real_escape_string(&mysql, end,"What's this",11);*end++ = '\'';*end++ = ',';*end++ = '\'';end += mysql_real_escape_string(&mysql, end,"binary data: \0\r\n",16);*end++ = '\'';*end++ = ')'; if (mysql_real_query(&mysql,query,(unsigned int) (end - query))){ fprintf(stderr, "Failed to insert row, Error: %s\n", mysql_error(&mysql));}
该示例中使用的strmov()函数包含在mysqlclient库中，工作方式与strcpy()类似，但会返回指向第1个参数终结用Null的指针。
返回值
置于“to”中的值的长度，不包括终结用Null字符。
错误
无。
int mysql_real_query(MYSQL *mysql, const char *query, unsigned long length)
描述
执行由“query”指向的SQL查询，它应是字符串长度字节“long”。正常情况下，字符串必须包含1条SQL语句，而且不应为语句添加终结分号（‘;’）或“\g”。如果允许多语句执行，字符串可包含由分号隔开的多条语句。请参见25.2.9节，“多查询执行的C API处理”。
对于包含二进制数据的查询，必须使用mysql_real_query()而不是mysql_query()，这是因为，二进制数据可能会包含‘\0’字符。此外，mysql_real_query()比mysql_query()快，这是因为它不会在查询字符串上调用strlen()。
如果希望知道查询是否应返回结果集，可使用mysql_field_count()进行检查25.2.3.22节，“mysql_field_count()”。
返回值
如果查询成功，返回0。如果出现错误，返回非0值。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
int mysql_refresh(MYSQL *mysql, unsigned int options)
描述
该函数用于刷新表或高速缓冲，或复位复制服务器信息。连接的用户必须具有RELOAD权限。
“options”参量是一种位掩码，由下述值的任意组合构成。能够以“Or”（或）方式将多个值组合在一起，用一次调用执行多项操作。
· REFRESH_GRANT
刷新授权表，与FLUSH PRIVILEGES类似。
· REFRESH_LOG
刷新日志，与FLUSH LOGS类似。
· REFRESH_TABLES
刷新表高速缓冲，与FLUSH TABLES类似。
· REFRESH_HOSTS
刷新主机高速缓冲，与FLUSH HOSTS类似。
· REFRESH_STATUS
复位状态变量，与FLUSH STATUS类似。
· REFRESH_THREADS
刷新线程高速缓冲。
· REFRESH_SLAVE
在从复制服务器上，复位主服务器信息，并重新启动从服务器，与RESET SLAVE类似。
· REFRESH_MASTER
在主复制服务器上，删除二进制日志索引中列出的二进制日志文件，并截短索引文件，与RESET MASTER类似。
返回值
0表示成功，非0值表示出现错误。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
int mysql_reload(MYSQL *mysql)
描述
请求MySQL服务器重新加载授权表。连接的用户必须具有RELOAD权限。
该函数已过时。最好使用mysql_query()来发出SQL FLUSH PRIVILEGES语句。
返回值
0表示成功，非0值表示出现错误。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
my_bool mysql_rollback(MYSQL *mysql)
描述
回滚当前事务。
该函数的动作取决于completion_type系统变量的值。尤其是，如果completion_type的值为“2”，终结事务后，服务器将执行释放操作，并关闭客户端连接。客户端程序应调用mysql_close()，从客户端一侧关闭连接。
返回值
如果成功，返回0，如果出现错误，返回非0值。
错误
无。
MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)
描述
将行光标置于查询结果集中的任意行。“offset”值是行偏移量，它应是从mysql_row_tell()或mysql_row_seek()返回的值。该值不是行编号，如果你打算按编号查找结果集中的行，请使用mysql_data_seek()。
该函数要求在结果集的结构中包含查询的全部结果，因此，mysql_row_seek()仅应与mysql_store_result()一起使用，而不是与mysql_use_result()。
返回值
行光标的前一个值。该值可传递给对mysql_row_seek()的后续调用。
错误
无。
MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)
描述
对于上一个mysql_fetch_row()，返回行光标的当前位置。该值可用作mysql_row_seek()的参量。
仅应在mysql_store_result()之后，而不是mysql_use_result()之后使用mysql_row_tell()。
返回值
行光标的当前偏移量。
错误
无。
int mysql_select_db(MYSQL *mysql, const char *db)
描述
使由db指定的数据库成为由mysql指定的连接上的默认数据库（当前数据库）。在后续查询中，该数据库将是未包含明确数据库区分符的表引用的默认数据库。
除非已连接的用户具有使用数据库的权限，否则mysql_select_db()将失败。
返回值
0表示成功，非0值表示出现错误。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
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)
描述
允许或禁止连接的选项。选项可以取下述值之一：
|
MYSQL_OPTION_MULTI_STATEMENTS_ON |
允许多语句支持。 |
|
MYSQL_OPTION_MULTI_STATEMENTS_OFF |
禁止多语句支持。 |
返回值
0表示成功，非0值表示出现错误。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· ER_UNKNOWN_COM_ERROR
服务器不支持mysql_set_server_option()（当服务器版本低于4.1.1时），或服务器不支持试图设置的选项。
int mysql_shutdown(MYSQL *mysql, enum enum_shutdown_level shutdown_level)
描述
请求数据库服务器关闭。已连接的用户必须具有SHUTDOWN权限。MySQL 5.1服务器仅支持1种关闭类型，shutdown_level必须等效于SHUTDOWN_DEFAULT。设计规划了额外的关闭级别，以便能够选择所需的级别。对于用旧版本libmysqlclient头文件编译并调用mysql_shutdown()的动态链接可执行程序，需要与旧版的libmysqlclient动态库一起使用。
在5.5节，“MySQL服务器关机进程”中，介绍了关机进程。
返回值
0表示成功，非0值表示出现错误。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· 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()之前调用它。
除非在客户端库中允许了OpenSSL支持，否则mysql_ssl_set()不作任何事。
Mysql是从mysql_init()返回的连接处理程序。其他参数的指定如下：
· key是key文件的路径名。
· cert是证书文件的路径名。
· ca是证书授权文件的路径名。
· capath是指向目录的路径名，该目录中包含以pem格式给出的受信任SSL CA证书。
· cipher是允许密码的列表，用于SSL加密。
对于任何未使用的SSL参数，可为其给定NULL。
返回值
该函数总返回0。如果SSL设置不正确，当你尝试连接时，mysql_real_connect()将返回错误。
char *mysql_stat(MYSQL *mysql)
描述
返回包含特定信息的字符串，该信息与mysqladmin status命令提供的信息类似。包括以秒为单位的正常运行时间，以及运行线程的数目，问题数，再加载次数，以及打开的表数目。
返回值
描述服务器状态的字符集。如果出现错误，返回NULL。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· 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()将查询的全部结果读取到客户端，分配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
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· 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()那样将结果集实际读取到客户端。它必须通过对mysql_fetch_row()的调用，对每一行分别进行检索。这将直接从服务器读取结果，而不会将其保存在临时表或本地缓冲区内，与mysql_store_result()相比，速度更快而且使用的内存也更少。客户端仅为当前行和通信缓冲区分配内存，分配的内存可增加到max_allowed_packet字节。
另一方面，如果你正在客户端一侧为各行进行大量的处理操作，或者将输出发送到了用户可能会键入“^S”（停止滚动）的屏幕，就不应使用mysql_use_result()。这会绑定服务器，并阻止其他线程更新任何表（数据从这类表获得）。
使用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嵌入式服务器时，由于在调用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
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
错误
返回执行前一个SQL语句期间生成的告警数目。
返回值
告警计数。
错误
无。
MySQL客户端／服务器协议提供了预处理语句。该功能采用了由mysql_stmt_init()初始化函数返回的MYSQL_STMT语句处理程序数据结构。对于多次执行的语句，预处理执行是一种有效的方式。首先对语句进行解析，为执行作好准备。接下来，在以后使用初始化函数返回的语句句柄执行一次或多次。
对于多次执行的语句，预处理执行比直接执行快，主要原因在于，仅对查询执行一次解析操作。在直接执行的情况下，每次执行语句时，均将进行查询。此外，由于每次执行预处理语句时仅需发送参数的数据，从而减少了网络通信量。
预处理语句的另一个优点是，它采用了二进制协议，从而使得客户端和服务器之间的数据传输更有效率。
下述语句可用作预处理语句：CREATE TABLE、DELETE、DO、INSERT、REPLACE、SELECT、SET、UPDATE、以及大多数SHOW语句。在MySQL 5.1中，不支持其他语句。
预处理语句主要使用MYSQL_STMT和MYSQL_BIND数据结构。第3种结构MYSQL_TIME用于传输暂时性数据。
· MYSQL_STMT
该结构表示预处理语句。通过调用mysql_stmt_init()创建语句，返回语句句柄，即指向MYSQL_STMT的指针。该句柄用户所有后续的与语句有关的函数，直至使用mysql_stmt_close()关闭了它为止。
MYSQL_STMT结构没有供应用程序使用的参数。此外，不应尝试复制MYSQL_STMT结构。不保证这类复制物会有用。
多个语句句柄能够与单个连接关联起来。对句柄数目的限制取决于系统资源。
· MYSQL_BIND
该结构用于语句输入（发送给服务器的数据值）和输出（从服务器返回的结果值）。对于输入，它与mysql_stmt_bind_param()一起使用，用于将参数数据值绑定到缓冲区上，以供mysql_stmt_execute()使用。对于输出，它与mysql_stmt_bind_result()一起使用，用于绑定结果缓冲区，以便用于with mysql_stmt_fetch()以获取行。
MYSQL_BIND结构包含下述供应用程序使用的成员。每个成员用于输入和输出，但在某些时候，也能用于不同的目的，具体情况取决于数据传输的方向。
o enum enum_field_types buffer_type
缓冲的类型。在本节后面列出了允许的buffer_type值。对于输入，buffer_type指明了与语句参数捆绑的值类型。对于输出，它指明了你希望从结果缓冲收到的值类型。
o void *buffer
对于输入，这是指向存储语句参数数据值的缓冲的指针。对于输出，它是指向返回结果集列值的缓冲的指针。对于数值列类型，缓冲应指向恰当的C类型变量（如果将该变量与具有UNSIGNED属性的列关联起来，变量unsigned C类型。通过使用is_unsigned成员，指明变量是signed或unsigned类型，详情请参见本节后面的介绍）。对于日期和时间列类型，缓冲应指向MYSQL_TIME结构。对于字符和二进制字符串列类型，缓冲应指向字符缓冲区。
o unsigned long buffer_length
*buffer的实际大小，单位为字节。它指明了可保存在缓冲区内的最大数据。对于字符和二进制C数据，buffer_length值指定了与mysql_stmt_bind_param()一起使用时的*buffer长度，或与mysql_stmt_bind_result()一起使用时能够提取到缓冲区内的最大数据。
o unsigned long *length
指向unsigned long变量的指针，该变量指明了存储在*buffer中数据的实际字节数。“length”用于字符或二进制C数据。对于输入参数数据绑定，“length”指向unsigned long变量，该变量指明了存储在*buffer中参数值的长度，供mysql_stmt_execute()使用。对于输出值绑定，mysql_stmt_fetch()会将返回的列值保存到“length”指向的变量中。
对于数值和临时数据类型，“length”将被忽略，原因在于，数据值的长度是由buffer_type值决定的。
o my_bool *is_null
该成员指向my_bool变量，如果值为NULL，该变量为“真”，如果值为非Null，该变量为“假”。对于输入，将*is_null设置为“真”，指明以语句参数的形式传递NULL值。对于输出，如果从语句返回的结果集列值为NULL，当获取了行后，该值将被设为“真”。
“is_null”是指向布尔类型的指针，而不是布尔标量，以便能以下述方式使用它：
§ 如果数据值总是NULL，使用MYSQL_TYPE_NULL绑定列。
§ 如果数据值总是NOT NULL，设置is_null = (my_bool*) 0。
§ 在所有其他情况下，应将is_null设置为my_bool变量的地址，并在各次执行之间恰当地更改变量的值，以指明数据值是NULL或NOT NULL。
o my_bool is_unsigned
该成员用于整数类型。（对应于MYSQL_TYPE_TINY、MYSQL_TYPE_SHORT、MYSQL_TYPE_LONG、以及MYSQL_TYPE_LONGLONG类型的代码）。对于无符号类型，应将“is_unsigned”设置为“真”，对于带符号类型，应将其设置为“假”。
o my_bool error
对于输出，该成员用于通报数据截短错误。必须通过调用带有MYSQL_REPORT_DATA_TRUNCATION选项的mysql_options()，启用截短通报功能。允许该功能后，mysql_stmt_fetch()返回MYSQL_DATA_TRUNCATED，而且对于出现截短情况的参数，在MYSQL_BIND结构中，错误标志为“真”。截短指明丢失了符号或有效位数，或字符串过长以至于无法容纳在1列中。
要想使用MYSQL_BIND结构，应将其内容置为0以便初始化它，然后对其进行设置，恰当地描述它。例如，要想声明并初始化三个MYSQL_BIND结构的数组，可使用下述代码：
MYSQL_BIND bind[3];memset(bind, 0, sizeof(bind));
· MYSQL_TIME
该结构用于将DATE、TIME、DATETIME和TIMESTAMP数据直接发送到服务器，或从服务器直接接收这类数据。将MYSQL_BIND结构的buffer_type成员设置为临时值之一，并将buffer成员设置为指向MYSQL_TIME结构，即可实现该点。
MYSQL_TIME结构包含下述成员：
o unsigned int year
年份
o unsigned int month
月份
o unsigned int day
天
o unsigned int hour
小时
o unsigned int minute
分钟
o unsigned int second
秒
o my_bool neg
布尔标志，用于指明时间是否为负数。
o unsigned long second_part
秒的分数部分。该成员目前不使用。
仅使用施加在给定临时类型值上的MYSQL_TIME结构的部分：用于DATE、DATETIME和TIMESTAMP的年、月、日部分。用于TIME、DATETIME和TIMESTAMP值的小时、分钟、秒部分。请参见25.2.10节，“日期和时间值的C API处理”。
在下面的表格中，给出了可在MYSQL_BIND结构的buffer_type成员中指定的允许值。在该表中，还给出了与每个buffer_type值最接近的对应SQL类型，对于数值和临时类型，给出了对应的C类型。
|
buffer_type值 |
SQL类型 |
C类型 |
|
MYSQL_TYPE_TINY |
TINYINT |
char |
|
MYSQL_TYPE_SHORT |
SMALLINT |
short int |
|
MYSQL_TYPE_LONG |
INT |
int |
|
MYSQL_TYPE_LONGLONG |
BIGINT |
long long int |
|
MYSQL_TYPE_FLOAT |
FLOAT |
float |
|
MYSQL_TYPE_DOUBLE |
DOUBLE |
double |
|
MYSQL_TYPE_TIME |
TIME |
MYSQL_TIME |
|
MYSQL_TYPE_DATE |
DATE |
MYSQL_TIME |
|
MYSQL_TYPE_DATETIME |
DATETIME |
MYSQL_TIME |
|
MYSQL_TYPE_TIMESTAMP |
TIMESTAMP |
MYSQL_TIME |
|
MYSQL_TYPE_STRING |
CHAR |
|
|
MYSQL_TYPE_VAR_STRING |
VARCHAR |
|
|
MYSQL_TYPE_TINY_BLOB |
TINYBLOB/TINYTEXT |
|
|
MYSQL_TYPE_BLOB |
BLOB/TEXT |
|
|
MYSQL_TYPE_MEDIUM_BLOB |
MEDIUMBLOB/MEDIUMTEXT |
|
|
MYSQL_TYPE_LONG_BLOB |
LONGBLOB/LONGTEXT |
|
隐式类型转换可沿两个方向执行。
在此归纳了预处理语句处理功能可使用的函数，并在后面的章节中详细介绍了它。请参见25.2.7节，“C API预处理语句函数描述”。
|
函数 |
描述 |
|
mysql_stmt_affected_rows() |
返回由预处理语句UPDATE、DELETE或INSERT变更、删除或插入的行数目。 |
|
mysql_stmt_attr_get() |
获取预处理语句属性的值。 |
|
mysql_stmt_attr_set() |
设置预处理语句的属性。 |
|
mysql_stmt_bind_param() |
将应用程序数据缓冲与预处理SQL语句中的参数标记符关联起来。 |
|
mysql_stmt_bind_result() |
将应用程序数据缓冲与结果集中的列关联起来。 |
|
mysql_stmt_close() |
释放预处理语句使用的内存。 |
|
mysql_stmt_data_seek() |
寻找语句结果集中的任意行编号。 |
|
mysql_stmt_errno() |
返回上次语句执行的错误编号。 |
|
mysql_stmt_error() |
返回上次语句执行的错误消息。 |
|
mysql_stmt_execute() |
执行预处理语句。 |
|
mysql_stmt_fetch() |
从结果集获取数据的下一行，并返回所有绑定列的数据。 |
|
mysql_stmt_fetch_column() |
获取结果集当前行中某列的数据。 |
|
mysql_stmt_field_count() |
对于最近的语句，返回结果行的数目。 |
|
mysql_stmt_free_result() |
释放分配给语句句柄的资源。 |
|
mysql_stmt_init() |
为MYSQL_STMT结构分配内存并初始化它。 |
|
mysql_stmt_insert_id() |
对于预处理语句的AUTO_INCREMENT列，返回生成的ID。 |
|
mysql_stmt_num_rows() |
从语句缓冲结果集返回总行数。 |
|
mysql_stmt_param_count() |
返回预处理SQL语句中的参数数目。 |
|
mysql_stmt_param_metadata() |
返回结果集的参数元数据。 |
|
mysql_stmt_prepare() |
为执行操作准备SQL字符串。 |
|
mysql_stmt_reset() |
复位服务器中的语句缓冲区。 |
|
mysql_stmt_result_metadata() |
以结果集形式返回预处理语句元数据。 |
|
mysql_stmt_row_seek() |
使用从mysql_stmt_row_tell()返回的值，查找语句结果集中的行偏移。 |
|
mysql_stmt_row_tell() |
返回语句行光标位置。 |
|
mysql_stmt_send_long_data() |
将程序块中的长数据发送到服务器。 |
|
mysql_stmt_sqlstate() |
返回关于上次语句执行的SQLSTATE错误代码。 |
|
mysql_stmt_store_result() |
将完整的结果集检索到客户端。 |
调用mysql_stmt_init()以创建语句句柄，然后调用mysql_stmt_prepare准备语句，调用mysql_stmt_bind_param()提供参数数据，并调用mysql_stmt_execute()执行语句。通过更改mysql_stmt_bind_param()提供的相应缓冲区中的参数值，可重复执行mysql_stmt_execute()。
如果语句是SELECT或任何其他能生成结果集的语句，mysql_stmt_prepare()也会通过mysql_stmt_result_metadata()以MYSQL_RES结果集的形式返回结果集元数据信息。
你可以使用mysql_stmt_bind_result()提供结果缓冲，以便mysql_stmt_fetch()能自动将数据返回给这些缓冲。这是一种按行获取方式。
此外，你也能使用mysql_stmt_send_long_data()将程序块中的文本或二进制数据发送到服务器。请参见25.2.7.25节，“mysql_stmt_send_long_data()”。
完成语句执行后，必须使用mysql_stmt_close()关闭语句句柄，以便与之相关的所有资源均能被释放。
如果通过调用mysql_stmt_result_metadata()获得了SELECT语句的结果集元数据，也应使用mysql_free_result()释放元数据。
执行步骤
要想准备和执行语句，应用程序必须采取下述步骤：
1. 用msyql_stmt_init()创建预处理语句句柄。要想在服务器上准备预处理语句，可调用mysql_stmt_prepare()，并为其传递包含SQL语句的字符串。
2. 如果语句生成了结果集，调用mysql_stmt_result_metadata()以获得结果集元数据。虽然与包含查询返回列的结果集不同，该元数据本身也采用了结果集的形式。元数据结果集指明了结果中包含多少列，并包含每一列的信息。
3. 使用mysql_stmt_bind_param()设置任何参数的值。必须设置所有参数。否则，语句执行将返回错误，或生成无法预料的结果。
4. 调用mysql_stmt_execute()执行语句。
5. 如果语句生成了结果集，捆绑数据缓冲，通过调用mysql_stmt_bind_result()，检索行值。
6. 通过重复调用mysql_stmt_fetch()，按行将数据提取到缓冲区，直至未发现更多行为止。
7. 通过更改参数值并再次执行语句，重复步骤3到步骤6。
调用mysql_stmt_prepare()时，MySQL客户端／服务器协议将执行下述动作：
· 服务器解析语句，并通过赋值语句ID将OK状态发回客户端。此外，如果它是面向结果集的语句，还将发送总的参数数目，列计数和元数据。在此调用过程中，服务器将检查语句的所有语法和语义。
· 客户端采用该语句ID用于进一步操作，以便服务器能从其语句池中识别语句。
调用mysql_stmt_execute()时，MySQL客户端／服务器协议将执行下述动作：
· 客户端使用语句句柄，并将参数数据发送到服务器。
· 服务器使用由客户端提供的ID来识别语句，用新提供的数据替换参数标记符，并执行语句。如果语句生成了结果集，服务器将数据发回客户端。否则，服务器会将发送OK状态，以及总的变更、删除和插入行数。
调用mysql_stmt_fetch()时，MySQL客户端／服务器协议将执行下述动作：
· 客户端按行从信息包读取数据，并通过执行必要的转换操作将其放入应用程序数据缓冲中。如果应用程序的缓冲类型与服务器返回的字段类型相同，转换十分简明。
如果出现了错误，可分别使用mysql_stmt_errno()、mysql_stmt_error()和mysql_stmt_sqlstate()获取语句错误代码、错误消息和SQLSTATE值。
预处理语句日志功能
对于与mysql_stmt_prepare()和mysql_stmt_execute() C API函数一起执行的预处理语句，服务器会将“准备”和“执行”行写入一般查询日志，以便你能了解语句是在何时准备和执行的。
假定按下述方式准备和执行了语句：
1. 调用mysql_stmt_prepare()以准备语句字符串"SELECT ?"。
2. 调用mysql_stmt_bind_param()将值“3”绑定到预处理语句中的参数。
3. 调用mysql_stmt_execute()，执行预处理语句。
上述调用的结果是，服务器将下述行写入一般查询日志：
Prepare [1] SELECT ?Execute [1] SELECT 3
日志中的每个“准备”和“执行”行均具有[n]语句ID标识，这样，你就能跟踪已记录的预处理语句。N是正整数。对于客户端，如果同时有多个活动的预处理语句，n可能会大于1。替换了“?”参数的数据值后，每个“执行”行将显示一条预处理语句。
版本说明：在MySQL 4.1.10之前，显示的“准备”行无[n]标识。在MySQL 4.1.10之前，不显示“执行”行。
为了准备和执行查询，请使用下述部分详细介绍的函数。
注意，与MYSQL_STMT结构一起使用的所有函数均以前缀mysql_stmt_开始。
要想创建MYSQL_STMT句柄，请使用mysql_stmt_init()函数。
my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)
描述
返回上次执行语句更改、删除或插入的总行数。对于UPDATE、DELETE或INSERT语句，可在mysql_stmt_execute()之后立刻调用它们。对于SELECT语句，mysql_stmt_affected_rows()的工作方式类似于mysql_num_rows()。
返回值
大于0的整数指明了受影响或检索的行数。对于UPDATE语句，“0”表明未更新任何记录，在查询中没有与WHERE子句匹配的行，或尚未执行任何查询。“-1”表明返回了错误，或对SELECT查询，在调用mysql_stmt_store_result()之前调用了mysql_stmt_affected_rows()。由于mysql_stmt_affected_rows()返回无符号值，可通过比较返回值和“(my_ulonglong)-1”（或等效的“(my_ulonglong)~0”），检查“-1”。
关于返回值的额外信息，请参见25.2.3.1节，“mysql_affected_rows()”。
错误
无。
示例：
关于mysql_stmt_affected_rows()的用法，请参阅25.2.7.10节，“mysql_stmt_execute()”中给出的示例。
int mysql_stmt_attr_get(MYSQL_STMT *stmt, enum enum_stmt_attr_type option, void *arg)
描述
可用于获得语句属性的当前值。
“option”参量是希望获取的选项，“arg”应指向包含选项值的变量。如果“option”是整数，那么“arg”应指向整数的值。
关于选项和选项类型的清单，请参见25.2.7.3节，“mysql_stmt_attr_set()”。
返回值
如果OK，返回0。如果选项未知，返回非0值。
错误
无。
int mysql_stmt_attr_set(MYSQL_STMT *stmt, enum enum_stmt_attr_type option, const void *arg)
描述
可用于影响预处理语句的行为。可多次调用该函数来设置多个选项。
“option”参量是希望设置的选项，“arg”参量是选项的值。如果“option”是整数，那么“arg”应指向整数的值。
可能的选项值：
|
选项 |
参量类型 |
功能 |
|
STMT_ATTR_UPDATE_MAX_LENGTH |
my_bool * |
如果设为1：更新mysql_stmt_store_result()中的元数据MYSQL_FIELD->max_length。 |
|
STMT_ATTR_CURSOR_TYPE |
unsigned long * |
调用mysql_stmt_execute()时，语句将打开的光标类型。*arg可以是CURSOR_TYPE_NO_CURSOR（默认值）或CURSOR_TYPE_READ_ONLY。 |
|
STMT_ATTR_PREFETCH_ROWS |
unsigned long * |
使用光标时，一次从服务器获取的行数。*arg的范围从1到unsigned long的最大值。默认值为1。 |
如果与CURSOR_TYPE_READ_ONLY一起使用了STMT_ATTR_CURSOR_TYPE选项，当调用了mysql_stmt_execute()时，将为语句打开光标。如果存在由前一个mysql_stmt_execute()调用打开的光标，在打开新的光标前，将关闭该光标。此外，为再执行而准备语句之前，mysql_stmt_reset()还将关闭任何打开的光标。mysql_stmt_free_result()将关闭任何打开的光标。
如果为预处理语句打开了光标，没必要调用mysql_stmt_store_result()，这是因为，该函数会导致在客户端一侧对结果集进行缓冲处理。
在MySQL 5.0.2中增加了STMT_ATTR_CURSOR_TYPE选项。在MySQL 5.0.6中，增加了STMT_ATTR_PREFETCH_ROWS选项。
返回值
如果OK，返回0。如果选项未知，返回非0值。
错误
无。
示例：
在下述示例中，为预处理语句打开了1个光标，并将每次获取的行数设为5：
MYSQL_STMT *stmt;int rc;unsigned long type;unsigned long prefetch_rows = 5; stmt = mysql_stmt_init(mysql);type = (unsigned long) CURSOR_TYPE_READ_ONLY;rc = mysql_stmt_attr_set(stmt, STMT_ATTR_CURSOR_TYPE, (void*) &type);/* ... check return value ... */rc = mysql_stmt_attr_set(stmt, STMT_ATTR_PREFETCH_ROWS, (void*) &prefetch_rows);/* ... check return value ... */my_bool mysql_stmt_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)
描述
mysql_stmt_bind_param()用于为SQL语句中的参数标记符绑定数据，以传递给mysql_stmt_prepare()。它使用MYSQL_BIND结构来提供数据。“bind”是MYSQL_BIND结构的某一数组的地址。按照客户端库的预期，对于查询中出现的每个“?”参数标记符，数组中均包含1个元素。
假定你准备了下述语句：
INSERT INTO mytbl VALUES(?,?,?)
绑定参数时，MYSQL_BIND结构的数组包含3个元素，并能声明如下：
MYSQL_BIND bind[3];
在25.2.5节，“C API预处理语句的数据类型”中，介绍了应设置的每个MYSQL_BIND元素的成员。
返回值
如果绑定成功，返回0。如果出现错误，返回非0值。
错误
· CR_INVALID_BUFFER_USE
指明“bind”（绑定）是否将提供程序块中的长数据，以及缓冲类型是否为非字符串或二进制类型。
· CR_UNSUPPORTED_PARAM_TYPE
不支持该转换。或许buffer_type值是非法的，或不是所支持的类型之一。
· CR_OUT_OF_MEMORY
内存溢出。
· CR_UNKNOWN_ERROR
出现未知错误。
示例：
关于mysql_stmt_bind_param()的用法，请参见25.2.7.10节，“mysql_stmt_execute()”给出的示例。
my_bool mysql_stmt_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)
描述
mysql_stmt_bind_result()用于将结果集中的列与数据缓冲和长度缓冲关联（绑定）起来。当调用mysql_stmt_fetch()以获取数据时，MySQL客户端／服务器协议会将绑定列的数据置于指定的缓冲区内。
调用mysql_stmt_fetch()之前，必须将所有列绑定到缓冲。“bind”是MYSQL_BIND结构某一数组的地址。按照客户端库的预期，对于结果集中的每一列，数组应包含相应的元素。如果未将列绑定到MYSQL_BIND结构，mysql_stmt_fetch()将简单地忽略数据获取操作。缓冲区应足够大，足以容纳数据值，这是因为协议不返回成块的数据值。
可以在任何时候绑定或再绑定列，即使已部分检索了结果集后也同样。新的绑定将在下一次调用mysql_stmt_fetch()时起作用。假定某一应用程序绑定了结果集中的列，并调用了mysql_stmt_fetch()。客户端／服务器协议将返回绑定缓冲区中的数据。接下来，假定应用程序将多个列绑定到不同的缓冲。该协议不会将数据置于新绑定的缓冲区，直至下次调用mysql_stmt_fetch()为止。
要想绑定列，应用程序将调用mysql_stmt_bind_result()，并传递类型、地址、以及长度缓冲的地址。在25.2.5节，“C API预处理语句的数据类型”中，介绍了应设置的各MYSQL_BIND元素的成员。
返回值
如果绑定成功，返回0。如果出现错误，返回非0值。
错误
· CR_UNSUPPORTED_PARAM_TYPE
不支持该转换。或许buffer_type值是非法的，或不是所支持的类型之一。
· CR_OUT_OF_MEMORY
内存溢出。
· CR_UNKNOWN_ERROR
出现未知错误。
示例：
关于mysql_stmt_bind_result()的用法，请参见25.2.7.11节，“mysql_stmt_fetch()”中给出的示例。