20.4.1.1 说明
返回受到最后一个UPDATE、DELETE或INSERT查询影响(变化)的行数。可以在针对UPDATE、DELETE或INSERT语句的mysql_query()之后立即调用。对于SELECT语句，mysql_affected_rows()的功能于mysql_num_rows()相同。

mysql_affected_rows()目前以一个宏(macro)来实现。

20.4.1.2 返回值
大于零的一个整数表示受到影响或检索出来的行数。零表示没有匹配查序中WHERE子句的记录或目前还没有查询被执行。-1表示查询返回一个错误，或对于一个SELECT查询，mysql_affected_rows()在调用mysql_store_result()之前被调用。

20.4.1.3 错误
没有。

20.4.1.4 范例
mysql_query(&mysql,"UPDATE products SET cost=cost*1.25 WHERE group=10");
printf("%d products updated",mysql_affected_rows(&mysql));

20.4.2 mysql_close()
void mysql_close(MYSQL *mysql)

20.4.2.1 说明
关闭一个以前打开了的连接。如果句柄由mysql_init()或mysql_connect()自动分配，mysql_close()也释放被mysql指向的连接句柄。

20.4.2.2 返回值
没有。

20.4.2.3 错误
CR_COMMANDS_OUT_OF_SYNC
命令以一个不正确的次序被执行。
CR_SERVER_GONE_ERROR
MySQL服务器关闭了。
CR_SERVER_LOST
对服务者的连接在查询期间失去。
CR_UNKNOWN_ERROR
发生一个未知的错误。

20.4.3 mysql_connect()
MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd)

20.4.3.1 说明
该函数不推荐使用，而更好使用mysql_real_connect()。

mysql_connect()试图建立一个对运行在host的一个MySQL数据库引擎的连接。mysql_connect()必须在你能执行其他API函数之前成功地完成，除了mysql_get_client_info()。

参数的含义与mysql_connect()相应的参数相同，不同的是连接参数可以是NULL。在这种情况下，C API 自动为连接结构分配内存，并且当你调用mysql_close()，释放它。这种方法的缺点是如果连接失败，你不能检索出一条错误消息。（为了从mysql_errno()或mysql_error()得到错误信息，你必须提供一个有效的MYSQL指针。）

20.4.3.2 返回值
同mysql_real_connect()。

20.4.3.3 错误
同mysql_real_connect()。

20.4.4mysql_change_user()
my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password, const char *db)

20.4.4.1 说明
改变用户并且使得由db指定数据库成为由mysql指定的连接上的缺省(当前)数据库。在随后的查询中，这个数据库是不包括一个明确的数据库指定符的表引用的缺省值。

这个函数功能在MySQL 3.23.3中引入。

除非连接的用户能被认证或如果他没有权限使用数据库，mysql_change_user()失败。在这种情况下，用户和数据库都没被改变。

如果你不想有一个缺省数据库，db参数可以被设置为NULL。

20.4.4.2 返回值
成功，零。如果发生一个错误发生，非零。

20.4.4.3 错误
与你能从mysql_real_connect()得到的相同。

CR_COMMANDS_OUT_OF_SYNC
命令以一个不正确的次序被执行。
CR_SERVER_GONE_ERROR
MySQL服务者关闭了。
CR_SERVER_LOST
对服务者的连接在查询期间失去。
CR_UNKNOWN_ERROR
发生一个未知的错误。
ER_UNKNOWN_COM_ERROR
MySQL服务器未实现这个命令(可能是一个老的服务器）
ER_ACCESS_DENIED_ERROR
用户或口令错误。
ER_BAD_DB_ERROR
数据库不存在。
ER_DBACCESS_DENIED_ERROR
用户没有数据库的存取权利。
ER_WRONG_DB_NAME
数据库名字太长。
20.4.4.4 范例
if (mysql_change_user(&mysql, "user", "password", "new_database"))
{
  fprintf(stderr, "Failed to change user.  Error: %s\n",
          mysql_error(&mysql));
}

20.4.5 mysql_create_db()
int mysql_create_db(MYSQL *mysql, const char *db)

20.4.5.1 说明
创建由db参数命名的数据库。

这个函数不推荐，而最好使用mysql_query()发出一条SQL CREATE DATABASE语句。

20.4.5.2 返回值
如果数据库成功地被创造，零。如果发生一个错误，非零。

20.4.5.3 错误
CR_COMMANDS_OUT_OF_SYNC
命令以一个不正确的次序被执行。
CR_SERVER_GONE_ERROR
MySQL服务器关闭了。
CR_SERVER_LOST
对服务者的连接在查询期间失去。
CR_UNKNOWN_ERROR
发生一个未知的错误。  
20.4.5.4 范例
if(mysql_create_db(&mysql, "my_database"))
{
  fprintf(stderr, "Failed to create new database.  Error: %s\n",
          mysql_error(&mysql));
}

20.4.6 mysql_data_seek()
void mysql_data_seek(MYSQL_RES *result, unsigned long long offset)

20.4.6.1 说明
在一个查询结果集合中定位任意行。这要求结果集合结构包含查询的全部结果，这样mysql_data_seek()可以仅需与mysql_store_result()一起使用，不是与mysql_use_result()。

偏移量应该是从0到mysql_num_rows(result)-1范围的一个值。

20.4.6.2 返回值
无。

20.4.6.3 错误
无。

20.4.7 mysql_debug()
void mysql_debug(char *debug)

20.4.7.1 说明
用一个给定字符串做一个DBUG_PUSH。mysql_debug()使用Fred Fish 调试库。为了使用这个函数，你必须编译客户库以支持调试。见G.1 调试一个MySQL服务器和节G.2 调试一个MySQL客户。

20.4.7.2 返回值
无。

20.4.7.3 错误
无。

20.4.7.4 范例
下面所示的调用使得客户库在客户机器上的“/tmp/client.trace”中产生一个跟踪文件：

mysql_debug("d:t:O,/tmp/client.trace");

20.4.8 mysql_drop_db()
int mysql_drop_db(MYSQL *mysql, const char *db)

20.4.8.1 说明
抛弃由db参数命名的数据库。

这个函数不推荐，而最好使用mysql_query()发出一条SQL DROP DATABASE语句。

20.4.8.2 返回值
如果数据库成功地被破抛弃，零。如果发生一个错误，非零。

20.4.8.3 错误
CR_COMMANDS_OUT_OF_SYNC
命令以一个不正确的次序被执行。
CR_SERVER_GONE_ERROR
MySQL服务器关闭了。
CR_SERVER_LOST
对服务者的连接在查询期间失去。
CR_UNKNOWN_ERROR
发生一个未知的错误。  
20.4.8.4 范例
if(mysql_drop_db(&mysql, "my_database"))
 fprintf(stderr, "Failed to drop the database: Error: %s\n",
         mysql_error(&mysql));

20.4.9 mysql_dump_debug_info()
int mysql_dump_debug_info(MYSQL *mysql)

20.4.9.1 说明
指示服务者将一些调试信息写入日志文件。连接的用户对此必须有precess权限才能工作。

20.4.9.2 返回值
如果命令成功，零。如果发生一个错误，非零。

20.4.9.3 错误
CR_COMMANDS_OUT_OF_SYNC
命令以一个不正确的次序被执行。
CR_SERVER_GONE_ERROR
MySQL服务者关闭了。
CR_SERVER_LOST
对服务器的连接在查询期间失去。
CR_UNKNOWN_ERROR
发生一个未知的错误。
　

20.4.10 mysql_eof()
my_bool mysql_eof(MYSQL_RES *result)

20.4.10.1 说明
这个函数不推荐，而使用mysql_errno()或mysql_error()。

mysql_eof()确定是否已经读到了一个结果集合的最后一行。

如果你从成功的mysql_store_result()调用获得一个结果集合，客户程序用一个操作收到全部集合。在这种情况下，从mysql_fetch_row()返回一个NULL总是意味着已经到达了结果集合的尾部，没必要调用mysql_eof()。

在另一方面，如果你使用mysql_use_result()初始化一个结果集合的检索，该集合的行随着你重复调用mysql_fetch_row()一个一个地从服务器获得。因为在这个过程中在连接上可能发生一个错误，从mysql_fetch_row()返回一个NULL值并不意味着集合正常到达了尾部。在这种情况下，你能使用mysql_eof()确定发生了什么。如果到达结果集合的尾部，mysql_eof()返回非零值，并且如果发生一个错误，返回零。

在时间上，mysql_eof()先于标准MySQL错误函数mysql_errno()和mysql_error()。因为这些错误函数提供相同的信息，他们的使用更好mysql_eof()，它现在不建议使用。（事实上，他们提供更多的信息，因为mysql_eof()值返回一个布尔值，而错误函数指出当发生错误时的出错原因。）

20.4.10.2 返回值
如果发生一个错误，零。如果到达结果集合的结束，非零。

20.4.10.3 错误
无。

20.4.10.4 范例
下列例子显示你必须如何使用mysql_eof()：

mysql_query(&mysql,"SELECT * FROM some_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
   // do something with data
}
if(!mysql_eof(result))  // mysql_fetch_row() failed due to an error
{
   fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}

然而，你可以用标准MySQL错误函数完成同样的效果：

mysql_query(&mysql,"SELECT * FROM some_table");
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
   // do something with data
}
if(mysql_errno(&mysql))  // mysql_fetch_row() failed due to an error
{
   fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}

20.4.11 mysql_errno()
unsigned int mysql_errno(MYSQL *mysql)

20.4.11.1 说明
对于由mysql指定的连接，mysql_errno()返回最近调用的可能成功或失败的API函数的错误代码。返回值零意味着没有错误发生。客户错误消息编号列出在MySQL“errmsg.h”头文件中。服务器错误消息编号列出在“mysqld_error.h”中。

20.4.11.2 返回值：
一个错误代码值。如果没有错误发生，零。

20.4.11.3 错误
无。

20.4.12 mysql_error()
char *mysql_error(MYSQL *mysql)

20.4.12.1 说明
对于由mysql指定的连接，mysql_errno()返回最近调用的可能成功或失败的API函数的错误代码。如果没有错误发生，返回空字符串("")。这意味着下列两个测试是等价的：

if(mysql_errno(&mysql))
{
   // an error occurred
}

if(mysql_error(&mysql)[0] != ''''\0'''')
{
   // an error occurred
}

客户错误消息的语言可通过重新编译MySQL客户库来改变。目前，你能在几种不同的语言间选取错误消息。见9.1 MySQL支持什么语言？。

20.4.12.2 返回值
一个描述错误的字符串。如果没有错误发生，空字符串。

20.4.12.3 错误
无。

20.4.13 mysql_escape_string()
unsigned int mysql_escape_string(char *to, const char *from, unsigned int length)

20.4.13.1 说明
把在from中的字符串编码为在一条SQL语句中可以发给服务器的转义的SQL字符串，将结果放在to中， 并且加上一个终止的空字节。编码的字符是NUL（ASCII 0)、‘\n’、‘\r’、‘\’、‘''''’、‘"’和Control-Z(见7.1 文字：如何写字符串和数字)。

由from指向的字符串必须是length个字节长。你必须分配to的缓冲区至少length*2+1个字节长。（在更坏的情况，每个字符可能需要使用2个字节被编码，并且你需要为终止空字节的空间) 当mysql_escape_string()返回时，to的内容将是空字符终止的字符串。返回值是编码后的字符串的长度，不包括终止空字符。

20.4.13.2 范例
char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");
*end++ = ''''\'''''''';
end += mysql_escape_string(end,"What''''s this",11);
*end++ = ''''\'''''''';
*end++ = '''','''';
*end++ = ''''\'''''''';
end += mysql_escape_string(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()，但是返回一个指向空终止的第一个参数的指针。

20.4.13.3 返回值
放进to的值的长度，不包括终止空字符。

20.4.13.4 错误
无。

20.4.14 mysql_fetch_field()
MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

20.4.14.1 说明
返回作为一个MYSQL_FIELD结构的一个结果集合的一个列的定义。重复调用这个函数在结果集合中检索所有关于列的信息。当没有剩下更多的字段时，mysql_fetch_field()返回NULL。

在每次你执行一个新的SELECT查询，mysql_fetch_field()被重置（reset)以返回有关第一列的信息。由mysql_fetch_field()返回的字段也受调用mysql_field_seek()的影响。

如果你调用mysql_query()在一张表上执行一个SELECT，但是没调用mysql_store_result()，如果你调用mysql_fetch_field()询问一个BLOB字段的长度，MySQL返回缺省BLOB长度(8K字节)。（选择8K的长度是因为MySQL不知道BLOB的最大长度。这应该在某个时候是它可配置) 一旦你已经检索了结果集合，field->max_length包含了在特定查询中对于该列最大值的长度。

20.4.14.2 返回值
当前列的MYSQL_FIELD结构。如果没有列剩下，NULL。

20.4.14.3 错误
无。

20.4.14.4 范例
MYSQL_FIELD *field;

while((field = mysql_fetch_field(result)))
{
   printf("field name %s\n", field->name);
}

20.4.15 mysql_fetch_fields()
MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

20.4.15.1 说明
返回一个结果集合的所有MYSQL_FIELD结构的数组。每个结构提供结果结合中一列的字段定义。

20.4.15.2 返回值
一个结果集合的所有MYSQL_FIELD结构的一个数组。

20.4.15.3 错误
无。

20.4.15.4 范例
unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *fields;

num_fields = mysql_num_fields(result);
fields = mysql_fetch_fields(result);
for(i = 0; i < num_fields; i++)
{
  printf("Field %u is %s\n", i, fields[i].name);
}

20.4.16 mysql_fetch_field_direct()
MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr)

20.4.16.1 说明
给定在一个结果集合中的一个列的字段编号fieldnr，返回作为MYSQL_FIELD结构的列的字段定义。你可以使用这个函数检索任意列的义。fieldnr的值应该在从0到mysql_num_fields(result)-1范围内。

20.4.16.2 返回值
指定列的MYSQL_FIELD结构。

20.4.16.3 错误
无。

20.4.16.4 范例
uns

上一页  [1] [2] [3] [4]  下一页