MYSQLC API函数概述.docx
- 文档编号:13348463
- 上传时间:2023-06-13
- 格式:DOCX
- 页数:59
- 大小:39.72KB
MYSQLC API函数概述.docx
《MYSQLC API函数概述.docx》由会员分享,可在线阅读,更多相关《MYSQLC API函数概述.docx(59页珍藏版)》请在冰点文库上搜索。
MYSQLCAPI函数概述
MYSQL-CAPI函数概述
在CAPI中可用的函数列在下面,并且在下一节更详细地描述。
见20.4CAPI函数描述。
mysql_affected_rows()返回被最新的UPDATE,DELETE或INSERT查询影响的行数。
mysql_close()关闭一个服务器连接。
mysql_connect()连接一个MySQL服务器。
该函数不推荐;使用mysql_real_connect()代替。
mysql_change_user()改变在一个打开的连接上的用户和数据库。
mysql_create_db()创建一个数据库。
该函数不推荐;而使用SQL命令CREATEDATABASE。
mysql_data_seek()在一个查询结果集合中搜寻一任意行。
mysql_debug()用给定字符串做一个DBUG_PUSH。
mysql_drop_db()抛弃一个数据库。
该函数不推荐;而使用SQL命令DROPDATABASE。
mysql_dump_debug_info()让服务器将调试信息写入日志文件。
mysql_eof()确定是否已经读到一个结果集合的最后一行。
这功能被反对;mysql_errno()或mysql_error()可以相反被使用。
mysql_errno()返回最近被调用的MySQL函数的出错编号。
mysql_error()返回最近被调用的MySQL函数的出错消息。
mysql_escape_string()用在SQL语句中的字符串的转义特殊字符。
mysql_fetch_field()返回下一个表字段的类型。
mysql_fetch_field_direct()返回一个表字段的类型,给出一个字段编号。
mysql_fetch_fields()返回一个所有字段结构的数组。
mysql_fetch_lengths()返回当前行中所有列的长度。
mysql_fetch_row()从结果集合中取得下一行。
mysql_field_seek()把列光标放在一个指定的列上。
mysql_field_count()返回最近查询的结果列的数量。
mysql_field_tell()返回用于最后一个mysql_fetch_field()的字段光标的位置。
mysql_free_result()释放一个结果集合使用的内存。
mysql_get_client_info()返回客户版本信息。
mysql_get_host_info()返回一个描述连接的字符串。
mysql_get_proto_info()返回连接使用的协议版本。
mysql_get_server_info()返回服务器版本号。
mysql_info()返回关于最近执行得查询的信息。
mysql_init()获得或初始化一个MYSQL结构。
mysql_insert_id()返回有前一个查询为一个AUTO_INCREMENT列生成的ID。
mysql_kill()杀死一个给定的线程。
mysql_list_dbs()返回匹配一个简单的正则表达式的数据库名。
mysql_list_fields()返回匹配一个简单的正则表达式的列名。
mysql_list_processes()返回当前服务器线程的一张表。
mysql_list_tables()返回匹配一个简单的正则表达式的表名。
mysql_num_fields()返回一个结果集合重的列的数量。
mysql_num_rows()返回一个结果集合中的行的数量。
mysql_options()设置对mysql_connect()的连接选项。
mysql_ping()检查对服务器的连接是否正在工作,必要时重新连接。
mysql_query()执行指定为一个空结尾的字符串的SQL查询。
mysql_real_connect()连接一个MySQL服务器。
mysql_real_query()执行指定为带计数的字符串的SQL查询。
mysql_reload()告诉服务器重装授权表。
mysql_row_seek()搜索在结果集合中的行,使用从mysql_row_tell()返回的值。
mysql_row_tell()返回行光标位置。
mysql_select_db()连接一个数据库。
mysql_shutdown()关掉数据库服务器。
mysql_stat()返回作为字符串的服务器状态。
mysql_store_result()检索一个完整的结果集合给客户。
mysql_thread_id()返回当前线程的ID。
mysql_use_result()初始化一个一行一行地结果集合的检索。
为了连接服务器,调用mysql_init()以初始化一个连接处理器,然后用该处理器调用mysql_real_connect()(还有其他信息例如主机名、用户名和口令)。
当你用该连接完成工作后,调用mysql_close()终止它。
当一个连接活跃时,客户可以用mysql_query()或mysql_real_query()将SQL查询发送到服务器。
两者的差别是mysql_query()期望查询作为一个空结尾的字符串来指定而mysql_real_query()期望一个计数的字符串。
如果字符串包含二进制数据(它可以包括空字节),你必须使用mysql_real_query()。
对与每个非--SELECT查询(例如,INSERT、UPDATE、DELETE等),你可以调用mysql_affected_rows()知道有多少行受到影响(改变)。
对于SELECT查询,你作为一个结果集合来检索选择的行。
(注意一些语句是类SELECT的,他们返回行。
这些包括SHOW、DESCRIBE和EXPLAIN。
他们应该象SELECT语句相同的方式来对待。
)
对客户,有两种方法处理结果集合。
一种方法是通过调用mysql_store_result()立刻检索全部结果。
该函数从服务器获得查询返回的所有行,并将他们存储在客户端。
第二种方法是对客户通过调用mysql_use_result()初始化一个一行一行地结果集合的检索。
该函数初始化检索,但是实际上不从服务器获得任何行。
在两种情况中,你通过mysql_fetch_row()存取行。
用mysql_store_result()、mysql_fetch_row()储存取已经从服务器被取出的行。
用mysql_use_result()、mysql_fetch_row()实际上从服务器检索行。
调用mysql_fetch_lengths()可获得关于每行中数据值尺寸的信息。
在你用完一个结果集合以后,调用mysql_free_result()释放由它使用的内存。
两种检索机制是互补的。
客户程序应该选择最适合他们的要求的途径。
在实践中,客户通常更愿意使用mysql_store_result()。
mysql_store_result()的一个优点是既然行均被客户取到,你不仅能顺序存取行,你也能mysql_data_seek()或mysql_row_seek()在结果集合中前后移动以改变在结果集合中的当前行位置。
你也能通过调用mysql_num_rows()知道有多少行。
另一方面,mysql_store_result()的内存需求对较大结果集合可能很高,并且你最可能遇到out-of-memory情况。
mysql_use_result()的一个优点是客户为结果集合需要较少的内存,因为它一次只是维持一行(并且因为有较少的分配开销,mysql_use_result()能更快些)。
缺点是你必须尽快处理每一行以避免困住服务器,你不必再结果集合中随意存取行(你只能顺序存取行),而且你不知道在结果集合中有多少行,直到你检索全部结果。
还有,你必须检索出所有行,即使你在检索中途确定你已找到了想寻找的信息。
API使得客户正确应答查询成为可能(仅检索必要的行),不用知道查询是否是一个SELECT。
你可以通过在mysql_query()(或mysql_real_query())之后调用mysql_store_result()做到。
如果结果集合调用成功并且查询是一个SELECT,你能读取行。
如果结果集合调用,调用mysql_field_count()确定结果是否是实际期望的。
如果mysql_field_count()返回0,查询没有返回数据(表明它是一个INSERT、UPDATE、DELETE等),所以不期望返回行。
如果mysql_field_count()是非零,查询应该有返回行,但是没有。
这表明查询是一个失败的SELECT。
见mysql_field_count()如何能做到的例子的描述。
mysql_store_result()和mysql_use_result()都允许你获得有关组成结果集合的字段的信息(字段数量、他们的名字和类型等等)。
你可以通过重复调用mysql_fetch_field()在行中顺序存取字段信息,或调用mysql_fetch_field_direct()存取行中的字段编号。
当前字段光标位置可以通过调用mysql_field_seek()改变,设置字段光标影响到后续mysql_fetch_field()调用。
你也能通过调用mysql_fetch_fields()马上获得字段信息。
对于检测和报告错误,MySQL借助于mysql_errno()和mysql_error()函数提供错误信息的存取。
他们返回最近调用的可能成功或失败的函数的错误代码或错误消息,允许你确定何时发生一个错误和什么错误。
20.4CAPI函数描述
在下面的描述中,一个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_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,"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,constchar*passwd)
20.4.3.1说明
该函数不推荐使用,而更好使用mysql_real_connect()。
mysql_connect()试图建立一个对运行在host的一个MySQL数据库引擎的连接。
mysql_connect()必须在你能执行其他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));
}
然而,
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- MYSQL API函数概述 API 函数 概述