mysql c api详解(二)...
时间：2010-08-18 来源：jsufcz
转自 http://hi.baidu.com/developer%5Fhyh/blog/item/af55a1526642ff561138c223.html
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 范例
unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *field;
num_fields = mysql_num_fields(result);
for(i = 0; i < num_fields; i++)
{
field = mysql_fetch_field_direct(result, i);
printf("Field %u is %s\n", i, field->name);
}
20.4.17 mysql_fetch_lengths()
unsigned long *mysql_fetch_lengths(MYSQL_RES *result)
20.4.17.1 说明
返回在结果集合内的当前行的列长度。如果你计划拷贝字段值，这个长度信息对优化也是有用的，因为你可以避免调用strlen()。另外，如果结果集合中包含二进制数据，你必须使用这个函数确定数据的大小，因为strlen()对包含空字符的任何字段返回不正确的结果。
空列和包含NULL的列的长度值是零。为了看清如何区分这两种情况，见mysql_fetch_row()的说明。
20.4.17.2 返回值
表示每列大小的无符号长整数的一个数组(不包括任何终止空字符)。如果出现一个错误，NULL。
20.4.17.3 错误
mysql_fetch_lengths()只对结果集合的当前行有效。如果你在调用mysql_fetch_row()之前或在检索出在结果中的所有以后，它返回NULL。
20.4.17.4 范例
MYSQL_ROW row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;
row = mysql_fetch_row(result);
if (row)
{
num_fields = mysql_num_fields(result);
lengths = mysql_fetch_lengths(result);
for(i = 0; i < num_fields; i++)
{
printf("Column %u is %lu bytes in length.\n", i, lengths[i]);
}
}
20.4.18 mysql_fetch_row()
MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)
20.4.18.1 说明
检索一个结果集合的下一行。当在mysql_store_result()之后使用时，如果没有更多的行可见所时，mysql_fetch_row()返回NULL。当在mysql_use_result()之后使用时，当没有更多的行可检索时或如果出现一个错误，mysql_fetch_row()返回NULL。
在行中值的数量由mysql_num_fields(result)给出。如果row保存了从一个对用mysql_fetch_row()调用返回的值，指向该值的指针作为row[0]到row[mysql_num_fields(result)-1]来存取。在行中的NULL值由NULL指针指出。
在行中字段值的长度可以通过调用mysql_fetch_lengths()获得。空字段和包含NULL的字段长度都是 0；你可以通过检查该值的指针区分他们。如果指针是NULL，字段是NULL；否则字段是空的。
20.4.18.2 返回值
下一行的一个MYSQL_ROW结构。如果没有更多的行可检索或如果出现一个错误，NULL。
20.4.18.3 错误
CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。20.4.18.4 范例
MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;
num_fields = mysql_num_fields(result);
while ((row = mysql_fetch_row(result)))
{
unsigned long *lengths;
lengths = mysql_fetch_lengths(result);
for(i = 0; i < num_fields; i++)
{
printf("[%.*s] ", (int) lengths[i], row[i] ? row[i] : "NULL");
}
printf("\n");
}
20.4.19 mysql_field_count()
unsigned int mysql_field_count(MYSQL *mysql)
如果你正在使用一个比3.22.24早MySQL版本，你应该使用unsigned int mysql_num_fields(MYSQL *mysql)。
20.4.19.1 说明
返回在连接上的最近查询的列的数量。
这个函数一般用在mysql_store_result()返回NULL时（这样你没有结果设置指针)。在这种情况中，你能调用mysql_field_count()确定mysql_store_result()是否应该产生了一个非空的结果。这允许一个客户程序执行正确的操作，而不必知道查询是否是一条SELECT（或类SELECT)语句。下面显示的例子说明这怎样可以做到。
见20.4.51 为什么在mysql_query()返回成功后，mysql_store_result()有时返回NULL?。
20.4.19.2 返回值
在结果集合中表示字段数量字的一个无符号整数。
20.4.19.3 错误
无。
20.4.19.4 范例
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_field_count(&mysql) == 0)
{
// query does not return data
// (it was not a SELECT)
num_rows = mysql_affected_rows(&mysql);
}
else // mysql_store_result() should have returned data
{
fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}
}
}
另一个选择是用mysql_errno(&mysql)代替mysql_field_count(&mysql)调用。在这种情况中，你直接检查来自mysql_store_result()的一个错误而非从mysql_field_count()值来推断语句是否是一个SELECT。
20.4.20 mysql_field_seek()
MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)
20.4.20.1 说明
将字段光标设置到给定的偏移量。下一次调用mysql_fetch_field()将检索与该偏移量关联的列的字段定义。
为了定位于行的起始，传递一个值为0的offset值。
20.4.20.2 返回值
字段光标的先前的值。
20.4.20.3 错误
无。
20.4.21mysql_field_tell()
MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)
20.4.21.1 说明
返回用于最后一个mysql_fetch_field()的字段光标的位置。这个值可用作mysql_field_seek()的一个参数。
20.4.21.2 返回值
字段光标的当前偏移量。
20.4.21.3 错误
无。
20.4.22 mysql_free_result()
void mysql_free_result(MYSQL_RES *result)
20.4.22.1 说明
释放由mysql_store_result()、mysql_use_result()、mysql_list_dbs()等为一个结果集合分配的内存。当你用完了一个结果集合时，你必须调用mysql_free_result()来释放它使用的内存。
20.4.22.2 返回值
无。
20.4.22.3 错误
无。
20.4.23 mysql_get_client_info()
char *mysql_get_client_info(void)
20.4.23.1 说明
返回代表客户库的版本的字符串。
20.4.23.2 返回值
代表MySQL客户库版本的一个字符串。
20.4.23.3 错误
无。
20.4.24 mysql_get_host_info()
char *mysql_get_host_info(MYSQL *mysql)
20.4.24.1 说明
返回描述正在使用的连接类型的字符串，包括服务其主机名。
20.4.24.2 返回值
表示服务器主机名者和连接类型的字符串。
20.4.24.3 错误
无。
20.4.25 mysql_get_proto_info()
unsigned int mysql_get_proto_info(MYSQL *mysql)
20.4.25.1 说明
返回当前连接使用的协议版本。
20.4.25.2 返回值
表示被当前连接使用的协议版本的一个无符号整数。
20.4.25.3 错误
无。
20.4.26 mysql_get_server_info()
char *mysql_get_server_info(MYSQL *mysql)
20.4.26.1 说明
返回表示服务器版本号的字符串。
20.4.26.2 返回值
表示服务器版本号的一个字符串。
20.4.26.3 错误
无。
20.4.27 mysql_info()
char *mysql_info(MYSQL *mysql)
20.4.27.1 说明
检索一个字符串，它提供有关最近执行的查询的信息，但是对下面列出的语句。对其他语句，mysql_info()返回NULL。字符串的格式随查询类型而变化，如下所述。数字仅仅是说明性的；字符串将包含对查询适当的值。
INSERT INTO ... SELECT ... 字符串格式： Records: 100 Duplicates: 0 Warnings: 0 INSERT INTO ... VALUES (...),(...),(...)... 字符串格式： Records: 3 Duplicates: 0 Warnings: 0 LOAD DATA INFILE ... 字符串格式： Records: 1 Deleted: 0 Skipped: 0 Warnings: 0 ALTER TABLE 字符串绳格式： Records: 3 Duplicates: 0 Warnings: 0 UPDATE 字符串格式： Rows matched: 40 Changed: 40 Warnings: 0注意，只有多个值在语句中指定，mysql_info()对INSERT ... VALUES语句才返回非NULL值。
20.4.27.2 返回值
表示最近执行的查询的附加信息的一个字符串。如果得不到查询的任何信息，NULL。
20.4.27.3 错误
无。
20.4.28 mysql_init()
MYSQL *mysql_init(MYSQL *mysql)
20.4.28.1 说明
分配或初始化适合mysql_real_connect()的一个MYSQL对象。如果mysql是一个NULL指针，函数分配、初始化并且返回一个新对象。否则对象被初始化并且返回对象的地址。如果mysql_init()分配一个新对象，它将在调用mysql_close()关闭连接时被释放。
20.4.28.2 返回值
一个被初始化的MYSQL*句柄。如果没有足够的内存来分配一个新对象，NULL。
20.4.28.3 错误
在内存不够的情况下，返回NULL。
20.4.29 mysql_insert_id()
my_ulonglong mysql_insert_id(MYSQL *mysql)
20.4.29.1 说明
返回由先前的查询为一个AUTO_INCREMENT列生成的ID。在你执行一个INSERT查询向一个包含AUTO_INCREMENT字段的表中插入后，使用这个函数。
注意，如果先前的查询不产生一个AUTO_INCREMENT值，mysql_insert_id()返回0。如果你需要在以后保存该值，必须在查询生成了该值后马上调用mysql_insert_id()。
也要注意，SQL的LAST_INSERT_ID()函数总是包含最近生成的AUTO_INCREMENT值，并且在查询之间不被重置，因为该函数的值在服务器端维护。
20.4.29.2 返回值
有先前的查询更新的AUTO_INCREMENT字段的值。如果在连接上没有先前的询问或如果查询没更新AUTO_INCREMENT值，返回零。
20.4.29.3 错误
无
相关阅读 更多 +
