MySQLCAPI函数详解.docx
- 文档编号:16318952
- 上传时间:2023-07-12
- 格式:DOCX
- 页数:48
- 大小:33.94KB
MySQLCAPI函数详解.docx
《MySQLCAPI函数详解.docx》由会员分享,可在线阅读,更多相关《MySQLCAPI函数详解.docx(48页珍藏版)》请在冰点文库上搜索。
MySQLCAPI函数详解
MySQLCAPI函数详解
在下面的描述中,一个NULL参数或返回值含义是在C编程语言环境的NULL,不是一个MySQLNULL值。
返回一个值的函数一般返回一个指针或一个整数。
除非另外指定,返回一个指针的函数返回一个非NULL值表明成功,或一个NULL值表明一个错误,而返回一个整数的函数返回零表示成功,或非零表示一个错误。
注意,“非零”只有这个含义。
除非函数描述另外
说明,不要测试一个零以外的其他值:
if(result)/*正确*/
...error...
if(result<0)/*不正确*/
...error...
if(result==-1)/*不正确*/
...error...
当函数返回一个错误时,函数描述的错误小节列出错误可能的类型。
你可以调用mysql_
errno()找出发生了这些重的哪一个。
错误的字符串表示可以调用mysql_error()获得。
20.4.1mysql_affected_rows()
my_ulonglongmysql_affected_rows(MYSQL*mysql)
20.4.1.1说明
返回受到最后一个UPDATE、DELETE或INSERT查询影响(变化)的行数。
可以在针对UPDATE
、DELETE或INSERT语句的mysql_query()之后立即调用。
对于SELECT语句,mysql_affec
ted_rows()的功能于mysql_num_rows()相同。
mysql_affected_rows()目前以一个宏(macro)来实现。
20.4.1.2返回值
大于零的一个整数表示受到影响或检索出来的行数。
零表示没有匹配查序中WHERE子句的
记录或目前还没有查询被执行。
-1表示查询返回一个错误,或对于一个SELECT查询,my
sql_affected_rows()在调用mysql_store_result()之前被调用。
20.4.1.3错误
没有。
20.4.1.4范例
mysql_query(&mysql,"UPDATEproductsSETcost=cost*1.25WHEREgroup=10");
printf("%dproductsupdated",mysql_affected_rows(&mysql));
20.4.2mysql_close()
voidmysql_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.3mysql_connect()
MYSQL*mysql_connect(MYSQL*mysql,constchar*host,constchar*user,const
char*passwd)
20.4.3.1说明
该函数不推荐使用,而更好使用mysql_real_connect()。
mysql_connect()试图建立一个对运行在host的一个MySQL数据库引擎的连接。
mysql_co
nnect()必须在你能执行其他API函数之前成功地完成,除了mysql_get_client_info()。
参数的含义与mysql_connect()相应的参数相同,不同的是连接参数可以是NULL。
在这种
情况下,CAPI自动为连接结构分配内存,并且当你调用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_boolmysql_change_user(MYSQL*mysql,constchar*user,constchar*password,constchar*db)
20.4.4.1说明
改变用户并且使得由db指定数据库成为由mysql指定的连接上的缺省(当前)数据库。
在随后的查询中,这个数据库是不包括一个明确的数据库指定符的表引用的缺省值。
这个函数功能在MySQL3.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,"Failedtochangeuser.Error:
%s\n",
mysql_error(&mysql));
}
20.4.5mysql_create_db()
intmysql_create_db(MYSQL*mysql,constchar*db)
20.4.5.1说明
创建由db参数命名的数据库。
这个函数不推荐,而最好使用mysql_query()发出一条SQLCREATEDATABASE语句。
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,"Failedtocreatenewdatabase.Error:
%s\n",
mysql_error(&mysql));
}
20.4.6mysql_data_seek()
voidmysql_data_seek(MYSQL_RES*result,unsignedlonglongoffset)
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.7mysql_debug()
voidmysql_debug(char*debug)
20.4.7.1说明
用一个给定字符串做一个DBUG_PUSH。
mysql_debug()使用FredFish调试库。
为了使用这个函数,你必须编译客户库以支持调试。
见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.8mysql_drop_db()
intmysql_drop_db(MYSQL*mysql,constchar*db)
20.4.8.1说明
抛弃由db参数命名的数据库。
这个函数不推荐,而最好使用mysql_query()发出一条SQLDROPDATABASE语句。
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,"Failedtodropthedatabase:
Error:
%s\n",
mysql_error(&mysql));
20.4.9mysql_dump_debug_info()
intmysql_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.10mysql_eof()
my_boolmysql_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*FROMsome_table");
result=mysql_use_result(&mysql);
while((row=mysql_fetch_row(result)))
{
//dosomethingwithdata
}
if(!
mysql_eof(result))//mysql_fetch_row()failedduetoanerror
{
fprintf(stderr,"Error:
%s\n",mysql_error(&mysql));
}
然而,你可以用标准MySQL错误函数完成同样的效果:
mysql_query(&mysql,"SELECT*FROMsome_table");
result=mysql_use_result(&mysql);
while((row=mysql_fetch_row(result)))
{
//dosomethingwithdata
}
if(mysql_errno(&mysql))//mysql_fetch_row()failedduetoanerror
{
fprintf(stderr,"Error:
%s\n",mysql_error(&mysql));
}
20.4.11mysql_errno()
unsignedintmysql_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.12mysql_error()
char*mysql_error(MYSQL*mysql)
20.4.12.1说明
对于由mysql指定的连接,mysql_errno()返回最近调用的可能成功或失败的API函数的错误代码。
如果没有错误发生,返回空字符串("")。
这意味着下列两个测试是等价的:
if(mysql_errno(&mysql))
{
//anerroroccurred
}
if(mysql_error(&mysql)[0]!
='\0')
{
//anerroroccurred
}
客户错误消息的语言可通过重新编译MySQL客户库来改变。
目前,你能在几种不同的语言间选取错误消息。
见9.1MySQL支持什么语言?
。
20.4.12.2返回值一个描述错误的字符串。
如果没有错误发生,空字符串。
20.4.12.3错误
无。
20.4.13mysql_escape_string()
unsignedintmysql_escape_string(char*to,constchar*from,unsignedintle
ngth)
20.4.13.1说明
把在from中的字符串编码为在一条SQL语句中可以发给服务器的转义的SQL字符串,将结果放在to中,并且加上一个终止的空字节。
编码的字符是NUL(ASCII0)、‘\n’、‘\r’、‘\’、‘'’、‘"’和Control-Z(见7.1文字:
如何写字符串和数字)。
由from指向的字符串必须是length个字节长。
你必须分配to的缓冲区至少length*2+1个字节长。
(在更坏的情况,每个字符可能需要使用2个字节被编码,并且你需要为终止空字节的空间)当mysql_escape_string()返回时,to的内容将是空字符终止的字符串。
返回值是编码后的字符串的长度,不包括终止空字符。
20.4.13.2范例
charquery[1000],*end;
end=strmov(query,"INSERTINTOtest_tablevalues(");
*end++='\'';
end+=mysql_escape_string(end,"What'sthis",11);
*end++='\'';
*end++=',';
*end++='\'';
end+=mysql_escape_string(end,"binarydata:
\0\r\n",16);
*end++='\'';
*end++=')';
if(mysql_real_query(&mysql,query,(unsignedint)(end-query)))
{
fprintf(stderr,"Failedtoinsertrow,Error:
%s\n",
mysql_error(&mysql));
}
例子中所用的strmov()函数被包括在mysqlclient库中且功能类似于strcpy(),但是返回一个指向空终止的第一个参数的指针。
20.4.13.3返回值
放进to的值的长度,不包括终止空字符。
20.4.13.4错误
无。
20.4.14mysql_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("fieldname%s\n",field->name);
}
20.4.15mysql_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范例
unsignedintnum_fields;
unsignedinti;
MYSQL_FIELD*fields;
num_fields=mysql_num_fields(result);
fields=mysql_fetch_fields(result);
for(i=0;i { printf("Field%uis%s\n",i,fields[i].name); } 20.4.16mysql_fetch_field_direct() MYSQL_FIELD*mysql_fetch_field_direct(MYSQL_RES*result,unsignedintfieldn r) 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范例 unsignedintnum_fields; unsignedinti; MYSQL_FIELD*field; num_fields=mysql_num_fields(result); for(i=0;i { field=mysql_fetch_field_direct(result,i); printf("Field%uis%s\n",i,field->name); } 20.4.17mysql_fetch_lengths() unsignedlong*mysql_fetch_lengths(MYSQL_RES*result) 20.4.17.1说明 返回在结果集合内的当前行的列长度。 如果你计划拷贝字段值,这个长度信息对优化也是有用的,因为你可以避免调用strlen()。 另外,如果结果集合中包含二进制数据,你必须使用这个函数确定数据的大小,因为strlen()对包含空字符的任何字段返回不正确的结果。 空列和包含NULL的列的长度值是零。 为了看清如何区分这两种情况,见mysql_fetch_ro w()的说明。 20.4.17.2返回值 表示每列大小的无符号长整数的一个数组(不包括任何终止空字符)。 如果出现一个错误,NULL。 20.4.17.3错误 mysql_fetch_lengths()只对结果集合的当前行有效。 如果你在调用mysql_fetch_row()之前或在检索出在结果中的所有以后,它返回NULL。 20.4.17.4范例 MYSQL_ROWrow; unsignedlong*
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- MySQLCAPI 函数 详解
![提示](https://static.bingdoc.com/images/bang_tan.gif)