MySQL学习总结(适用版本:MySQL 3.23.7alpla)1. MySQL API21.1. MySQL C API21.2. C API数据类型31.3. C API函数概述61.4. C API函数描述91.4.1. mysql_affected_rows( )101.4.2. mysql_close()111.4.3. mysql_connect()111.4.4. mysql_cha nge_user()121.4.5. mysql_create_db()131.4.6. mysql_data_seek()141 .4.7. mysql_debug()151.4.8. mysql_drop_db()151.4.9. mysql_dump_de bug_info()161.4.10. mysql_eof()171.4.11. mysql_errno()181.4.12. m ysql_error()191.4.13. mysql_escape_string()201.4.14. mysql_fetch_ field()211.4.15. mysql_fetch_fields()221.4.16. mysql_fetch_field_ direct()231.4.17. mysql_fetch_lengths()231.4.18. mysql_fetch_row( )241.4.19. mysql_field_count()261.4.20. mysql_field_seek()271.4.2 1. mysql_field_tell()281.4.22. mysql_free_result()281.4.23. mysql _get_client_info()291.4.24. mysql_get_host_info()291.4.25. mysql_ get_proto_info()301.4.26. mysql_get_server_info()301.4.27. mysql_ info()301.4.28. mysql_init()311.4.29. mysql_insert_id()321.4.30. mysql_kill()321.4.31. mysql_list_dbs()331.4.32. mysql_list_fields ()341.4.33. mysql_list_processes()351.4.34. mysql_list_tables()35 1.4.35. mysql_num_fields()361.4.36. mysql_num_rows()381.4.37. mys ql_options()381.4.38. mysql_ping()401.4.39. mysql_query()411.4.40 . mysql_real_connect()411.4.41. mysql_real_query()431.4.42. mysql _reload()441.4.43. mysql_row_seek()451.4.44. mysql_row_tell()451. 4.45. mysql_select_db()461.4.46. mysql_shutdown()471.4.47. mysql_ stat()471.4.48. mysql_store_result()481.4.49. mysql_thread_id()49 1.4.50. mysql_use_result()501.4.51. 为什么在mysql_query()返回成功后,mysql_ store_result()有时返回NULL?511.4.52. 我能从查询中得到什么结果?511.4.53. 我怎样能得到最后插 入的行的唯一ID?52 MySQL API MySQL C APIC API代码是随MySQL分发的,它被包含在mysqlclie nt库且允许C程序存取一个数据库。在 MySQL源代码分发中的很多客户是用C编写的。如果你正在寻找演示怎样使用C API的例子,看 一下这些客户程序。大多数其他客户 API(除了Java的所有)都使用mysqlclient库与MySQL服务器通信。这意味着,例如 ,你能利用很多被其他客户程序使用的同一环境变量,因为他们从库中引用。对这些变量的一张表,见12.1 不同的MySQL程序的概述。 客户有一个最大通讯缓冲区大小。初始分配的缓冲区大小(16K字节) 自动地增加到最大尺寸(缺省的最大值是24M)。因为缓冲区大小只是 按保证需求而被增加,简单地增加缺省的最大限制并不造成更多被消耗。该尺寸检查主要是一个对错误的查询和通讯包的检查。通讯缓冲区必须足够 大以便一个单独的SQL语句(对客户-服务器传输)和一行返回的数据(对服务器-客户传输)。每个线程的通讯缓冲区被动态扩大到最大限制来 处理任何查询或行。例如,如果你包含大到16M数据的BLOB值,你必须有一个至少16M通讯缓冲区限制(在服务器和客户两端)。客户的缺 省最大值是24M,但是在服务器端的缺省最大值是1M。你可以在服务器启动时通过改变max_allowed_packet参数的值来改变 它。见10.2.3 调节服务器参数。MySQL服务器在每个查询后缩小每个通讯缓冲区到net_buffer_length个字节。对客 户,与一个连接相关的缓冲区的大小没被减少,直到连接被关闭,在此时客户内存被回收。 如果你用线程的编程,你应该用--with-thr ead-safe-client编译MySQL C API,这将使C API线程对每个连接更安全。你可以让2个线程共享相同的连接,只 要如果你做下列事情: 两个线程不能同时在同一个连接上发送查询到MySQL。特别是你必须保证在一个mysql_query()和mys ql_store_result()之间没有其他线程正在使用同一个连接。 许多线程能存取用mysql_store_result()检 索出来的不同结果集合。 如果你使用mysql_use_result,你必须保证没有其他线程在同一个连接上正在询问任何东西,直到结果 集合被关闭。 C API数据类型MYSQL 这个结构表示对一个数据库连接的句柄,它被用于几乎所有的MySQL函数。 MYSQL_ RES 这个结构代表返回行的一个查询的(SELECT, SHOW, DESCRIBE, EXPLAIN)的结果。从查询返回的信息在 本章下文称为结果集合。 MYSQL_ROW 这是一个行数据的类型安全(type-safe)的表示。当前它实现为一个计数字节的字符串 数组。(如果字段值可能包含二进制数据,你不能将这些视为空终止串,因为这样的值可以在内部包含空字节) 行通过调用mysql_fetc h_row()获得。 MYSQL_FIELD 这个结构包含字段信息,例如字段名、类型和大小。其成员在下面更详细地描述。你可以通过重 复调用mysql_fetch_field()对每一列获得MYSQL_FIELD结构。字段值不是这个结构的部分;他们被包含在一个MY SQL_ROW结构中。 MYSQL_FIELD_OFFSET 这是一个相对一个MySQL字段表的偏移量的类型安全的表示。(由mys ql_field_seek()使用。) 偏移量是在一行以内的字段编号,从0开始。 my_ulonglong 该类型用于行编号和my sql_affected_rows()、mysql_num_rows()和mysql_insert_id()。这种类型提供0到1. 84e19的一个范围。在一些系统上,试图打印类型my_ulonglong的值将不工作。为了打印出这样的值,将它变换到unsigne d long并且使用一个%lu打印格式。例如:printf (Number of rows: %lu\n", (unsigned long) mysql_num_rows(result));MYSQL_FIELD结构包含列在下面的成员: char name 字段名,是一个空结尾的字符串。 char table 包含该字段的表的名字,如果它不是可计算的字段。对可计算的字段,tabl e值是一个空字符串。 char def 这字段的缺省值,是一个空结尾的字符串。只要你使用,只有你使用mysql_list_fi elds()才可设置它。 enum enum_field_types type 字段类型。type值可以是下列之一: 类型值 类型 含义FIELD_TYPE_TINY TINYINT字段FIELD_TYPE_SHORT SMALLINT字段FIELD_TYPE_ LONG INTEGER字段FIELD_TYPE_INT24 MEDIUMINT字段FIELD_TYPE_LONGLONG BIG INT字段FIELD_TYPE_DECIMAL DECIMAL或NUMERIC字段FIELD_TYPE_FLOAT FLOAT字段 FIELD_TYPE_DOUBLE DOUBLE或REAL字段FIELD_TYPE_TIMESTAMP TIMESTAMP字段FI ELD_TYPE_DATE DATE字段FIELD_TYPE_TIME TIME字段FIELD_TYPE_DATETIME DAT ETIME字段FIELD_TYPE_YEAR YEAR字段FIELD_TYPE_STRING 字符串(CHAR或VARCHAR)字 段FIELD_TYPE_BLOB BLOB或TEXT字段(使用max_length决定最大长度)FIELD_TYPE_SET SE T字段FIELD_TYPE_ENUM ENUM字段FIELD_TYPE_NULL NULL- 类型字段FIELD_TYPE_CHA R 不推荐;使用FIELD_TYPE_TINY代替你可以使用IS_NUM()宏来测试字段是否有一种数字类型。将type值传给IS_ NUM()并且如果字段是数字的,它将计算为TRUE:if (IS_NUM(field->type)) printf("Field is numeric\n");unsigned int length 字段宽度,在表定义中指定。 unsigned int max _length 对结果集合的字段的最大宽度(对实际在结果集合中的行的最长字段值的长度)。如果你使用mysql_store_resu lt()或mysql_list_fields(),这包含字段最大长度。如果你使用mysql_use_result(),这个变量的值 是零。 unsigned int flags 字段的不同位标志。flags值可以是零个或多个下列位设置: 标志值 标志含义NOT_ NULL_FLAG 字段不能是NULL PRI_KEY_FLAG 字段是一个主键的一部分UNIQUE_KEY_FLAG 字段是一个 唯一键的一部分MULTIPLE_KEY_FLAG 字段是一个非唯一键的一部分。 UNSIGNED_FLAG 字段有UNSIGNED 属性ZEROFILL_FLAG 字段有ZEROFILL属性BINARY_FLAG 字段有BINARY属性AUTO_INCREMEN T_FLAG 字段有AUTO_INCREMENT属性ENUM_FLAG 字段是一个ENUM(不推荐)BLOB_FLAG 字段是一个 BLOB或TEXT(不推荐)TIMESTAMP_FLAG 字段是一个TIMESTAMP(不推荐)BLOB_FLAG、ENUM_FL AG和TIMESTAMP_FLAG标志的使用是不推荐的,因为他们指出字段的类型而非它的类型属性。对FIELD_TYPE_BLOB、 FIELD_TYPE_ENUM或FIELD_TYPE_TIMESTAMP,最好是测试field->type。下面例子演示了一个典型 的flags值用法:if (field->flags & NOT_NULL_FLAG) printf("Field can''t b e null\n");你可以使用下列方便的宏决来确定flags值的布尔状态:IS_NOT_NULL(flags) 真,如果该字段被 定义为NOT NULL IS_PRI_KEY(flags) 真,如果该字段是一个主键IS_BLOB(flags) 真,如果该字段是 一个BLOB或TEXT(不推荐;相反测试field->type)unsigned int decimals 对数字字段的小数位数。 C API函数概述在 C API 中可用的函数列在下面,并且在下一节更详细地描述。见20.4 C API函数描述。mysql_ affected_rows() 返回被最新的UPDATE, DELETE或INSERT查询影响的行数。mysql_close() 关闭一个服务器连接。 mysql_connect() 连接一个MySQL服务器。该函数不推荐;使用mysql_real_conne ct()代替。 mysql_change_user() 改变在一个打开的连接上的用户和数据库。 mysql_create_db() 创建一个数据库。该函数不推荐;而使用SQL命令CREATE DATABASE。mysql_data_seek()在一个查询结果集 合中搜寻一任意行。mysql_debug()用给定字符串做一个DBUG_PUSH。 mysql_drop_db()抛弃一个数据库。 该函数不推荐;而使用SQL命令DROP DATABASE。 mysql_dump_debug_info()让服务器将调试信息写入日 志文件。 mysql_eof()确定是否已经读到一个结果集合的最后一行。这功能被反对; mysql_errno()或mysql_e rror()可以相反被使用。 mysql_errno()返回最近被调用的MySQL函数的出错编号。 mysql_error()返回 最近被调用的MySQL函数的出错消息。mysql_escape_string() 用在SQL语句中的字符串的转义特殊字符。 mys ql_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_in fo()返回服务器版本号。 mysql_info() 返回关于最近执行得查询的信息。 mysql_init()获得或初始化一个MY SQL结构。 mysql_insert_id()返回有前一个查询为一个AUTO_INCREMENT列生成的ID。 mysql_ki ll()杀死一个给定的线程。 mysql_list_dbs()返回匹配一个简单的正则表达式的数据库名。 mysql_list_fi elds()返回匹配一个简单的正则表达式的列名。 mysql_list_processes()返回当前服务器线程的一张表。 mys ql_list_tables()返回匹配一个简单的正则表达式的表名。 mysql_num_fields()返回一个结果集合重的列的 数量。 mysql_num_rows()返回一个结果集合中的行的数量。 mysql_options()设置对mysql_conne ct()的连接选项。 mysql_ping()检查对服务器的连接是否正在工作,必要时重新连接。 mysql_query()执行指定 为一个空结尾的字符串的SQL查询。 mysql_real_connect()连接一个MySQL服务器。 mysql_real_qu ery()执行指定为带计数的字符串的SQL查询。 mysql_reload()告诉服务器重装授权表。 mysql_row_seek ()搜索在结果集合中的行,使用从mysql_row_tell()返回的值。 mysql_row_tell()返回行光标位置。 my sql_select_db()连接一个数据库。 mysql_shutdown()关掉数据库服务器。 mysql_stat()返回作 为字符串的服务器状态。 mysql_store_result()检索一个完整的结果集合给客户。 mysql_thread_id() 返回当前线程的ID。 mysql_use_result()初始化一个一行一行地结果集合的检索。 为了连接服务器,调用mysql_i nit()以初始化一个连接处理器,然后用该处理器调用mysql_real_connect()(还有其他信息例如主机名、用户名和口令 )。当你用该连接完成工作后,调用mysql_close()终止它。当一个连接活跃时,客户可以用mysql_query()或mysq l_real_query()将SQL查询发送到服务器。两者的差别是mysql_query()期望查询作为一个空结尾的字符串来指定而 mysql_real_query()期望一个计数的字符串。如果字符串包含二进制数据(它可以包括空字节),你必须使用mysql_re al_query()。对与每个非--SELECT查询(例如,INSERT、UPDATE、DELETE等),你可以调用mysql_a ffected_rows()知道有多少行受到影响(改变)。对于SELECT查询,你作为一个结果集合来检索选择的行。(注意一些语句是 类SELECT的,他们返回行。这些包括SHOW、DESCRIBE和EXPLAIN。他们应该象SELECT语句相同的方式来对待。)对 客户,有两种方法处理结果集合。一种方法是通过调用mysql_store_result()立刻检索全部结果。该函数从服务器获得查询返 回的所有行,并将他们存储在客户端。第二种方法是对客户通过调用mysql_use_result()初始化一个一行一行地结果集合的检索 。该函数初始化检索,但是实际上不从服务器获得任何行。在两种情况中,你通过mysql_fetch_row()存取行。用mysql_s tore_result()、mysql_fetch_row()储存取已经从服务器被取出的行。用mysql_use_result() 、mysql_fetch_row()实际上从服务器检索行。调用mysql_fetch_lengths()可获得关于每行中数据值尺寸 的信息。在你用完一个结果集合以后,调用mysql_free_result()释放由它使用的内存。两种检索机制是互补的。客户程序应该 选择最适合他们的要求的途径。在实践中,客户通常更愿意使用mysql_store_result()。mysql_store_resu lt()的一个优点是既然行均被客户取到,你不仅能顺序存取行,你也能mysql_data_seek()或mysql_row_seek ()在结果集合中前后移动以改变在结果集合中的当前行位置。你也能通过调用mysql_num_rows()知道有多少行。另一方面,my sql_store_result()的内存需求对较大结果集合可能很高,并且你最可能遇到out-of-memory情况。mysql_ use_result()的一个优点是客户为结果集合需要较少的内存,因为它一次只是维持一行(并且因为有较少的分配开销,mysql_u se_result()能更快些)。缺点是你必须尽快处理每一行以避免困住服务器,你不必再结果集合中随意存取行(你只能顺序存取行),而 且你不知道在结果集合中有多少行,直到你检索全部结果。还有,你必须检索出所有行,即使你在检索中途确定你已找到了想寻找的信息。 API 使得客户正确应答查询成为可能(仅检索必要的行),不用知道查询是否是一个SELECT。你可以通过在mysql_query()(或my sql_real_query())之后调用mysql_store_result()做到。如果结果集合调用成功并且查询是一个SELE CT,你能读取行。如果结果集合调用,调用mysql_field_count()确定结果是否是实际期望的。如果mysql_field _count()返回0,查询没有返回数据(表明它是一个INSERT、UPDATE、DELETE等),所以不期望返回行。如果mysq l_field_count()是非零,查询应该有返回行,但是没有。这表明查询是一个失败的SELECT。见mysql_field_c ount()如何能做到的例子的描述。mysql_store_result()和mysql_use_result()都允许你获得有关 组成结果集合的字段的信息(字段数量、他们的名字和类型等等)。你可以通过重复调用mysql_fetch_field()在行中顺序存取 字段信息,或调用mysql_fetch_field_direct()存取行中的字段编号。当前字段光标位置可以通过调用mysql_f ield_seek()改变,设置字段光标影响到后续mysql_fetch_field()调用。你也能通过调用mysql_fetch _fields()马上获得字段信息。对于检测和报告错误,MySQL借助于mysql_errno()和mysql_error()函数 提供错误信息的存取。他们返回最近调用的可能成功或失败的函数的错误代码或错误消息,允许你确定何时发生一个错误和什么错误。 C AP I函数描述在下面的描述中,一个NULL参数或返回值含义是在C编程语言环境的NULL,不是一个MySQL NULL值。返回一个值的函 数一般返回一个指针或一个整数。除非另外指定,返回一个指针的函数返回一个非 NULL值表明成功,或一个NULL值表明一个错误,而返回 一个整数的函数返回零表示成功,或非零表示一个错误。注意,“非零”只有这个含义。除非函数描述另外说明,不要测试一个零以外的其他值:i f (result) / 正确 / ... error ...if (result < 0 ) / 不正确 / ... error ...if (result == -1) / 不正确 / ... error ...当函数返回一个错误时,函数描述的错误小节列出错误可能的类型。你可以调用mys ql_errno()找出发生了这些重的哪一个。错误的字符串表示可以调用mysql_error()获得。 mysql_affecte d_rows()my_ulonglong mysql_affected_rows(MYSQL mysql) 说明返回受到最后一 个UPDATE、DELETE或INSERT查询影响(变化)的行数。可以在针对UPDATE、DELETE或INSERT语句的mysq l_query()之后立即调用。对于SELECT语句,mysql_affected_rows()的功能于mysql_num_row s()相同。mysql_affected_rows()目前以一个宏(macro)来实现。 返回值大于零的一个整数表示受到影响或检索 出来的行数。零表示没有匹配查序中WHERE子句的记录或目前还没有查询被执行。-1表示查询返回一个错误,或对于一个SELECT查询, mysql_affected_rows()在调用mysql_store_result()之前被调用。 错误没有。 范例mysql _query(&mysql,"UPDATE products SET cost=cost1.25 WHERE group=10" );printf("%d products updated",mysql_affected_rows(&mysql)); mys ql_close()void mysql_close(MYSQL mysql) 说明关闭一个以前打开了的连接。如果句柄由mys ql_init()或mysql_connect()自动分配,mysql_close()也释放被mysql指向的连接句柄。 返回值没 有。 错误CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确的次序被执行。 CR_SERVER_GONE_ERRO R MySQL服务器关闭了。 CR_SERVER_LOST 对服务者的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生 一个未知的错误。 mysql_connect()MYSQL mysql_connect(MYSQL mysql, const char host, const char user, const char passwd) 说明该函数不推荐使用,而更 好使用mysql_real_connect()。 mysql_connect()试图建立一个对运行在host的一个MySQL数据库 引擎的连接。mysql_connect()必须在你能执行其他API函数之前成功地完成,除了mysql_get_client_inf o()。参数的含义与mysql_connect()相应的参数相同,不同的是连接参数可以是NULL。在这种情况下,C API 自动为 连接结构分配内存,并且当你调用mysql_close(),释放它。这种方法的缺点是如果连接失败,你不能检索出一条错误消息。(为了从 mysql_errno()或mysql_error()得到错误信息,你必须提供一个有效的MYSQL指针。) 返回值同mysql_r eal_connect()。 错误同mysql_real_connect()。mysql_change_user()my_boo l mysql_change_user(MYSQL mysql, const char user, const char p assword, const char db) 说明改变用户并且使得由db指定数据库成为由mysql指定的连接上的缺省(当前) 数据库。在随后的查询中,这个数据库是不包括一个明确的数据库指定符的表引用的缺省值。这个函数功能在MySQL 3.23.3中引入。除 非连接的用户能被认证或如果他没有权限使用数据库,mysql_change_user()失败。在这种情况下,用户和数据库都没被改变。 如果你不想有一个缺省数据库,db参数可以被设置为NULL。 返回值成功,零。如果发生一个错误发生,非零。 错误与你能从mysq l_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 数据库名字太长。 范例if (mysql_change_user(&mysql, "user", "password", "new_databa se")){ fprintf(stderr, "Failed to change user. Error: %s\n", mys ql_error(&mysql));} mysql_create_db()int mysql_create_db(MYSQL mysql, const char db) 说明创建由db参数命名的数据库。 这个函数不推荐,而最好使用mysql_query ()发出一条SQL CREATE DATABASE语句。 返回值如果数据库成功地被创造,零。如果发生一个错误,非零。 错误CR _COMMANDS_OUT_OF_SYNC 命令以一个不正确的次序被执行。 CR_SERVER_GONE_ERROR MySQL服 务器关闭了。 CR_SERVER_LOST 对服务者的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 ? 范例if(mysql_create_db(&mysql, "my_database")){ fprintf(stderr, "Failed to create new database. Error: %s\n", mysql_error(&mysql ));} mysql_data_seek()void mysql_data_seek(MYSQL_RES result, un signed long long offset) 说明在一个查询结果集合中定位任意行。这要求结果集合结构包含查询的全部结果,这样 mysql_data_seek()可以仅需与mysql_store_result()一起使用,不是与mysql_use_resul t()。偏移量应该是从0到mysql_num_rows(result)-1范围的一个值。 返回值无。 错误无。 mysql_d ebug()void mysql_debug(char debug) 说明用一个给定字符串做一个DBUG_PUSH。mysql _debug()使用Fred Fish 调试库。为了使用这个函数,你必须编译客户库以支持调试。见G.1 调试一个MySQL服务器和 节G.2 调试一个MySQL客户。 返回值无。 错误无。 范例下面所示的调用使得客户库在客户机器上的“/tmp/client .trace”中产生一个跟踪文件: mysql_debug("d:t:O,/tmp/client.trace"); mysql_ drop_db()int mysql_drop_db(MYSQL mysql, const char db) 说明抛弃由db 参数命名的数据库。 这个函数不推荐,而最好使用mysql_query()发出一条SQL DROP DATABASE语句。 返回值 如果数据库成功地被破抛弃,零。如果发生一个错误,非零。 错误CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确的次 序被执行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 对服务者的连接在查询 期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。? 范例if(mysql_drop_db(&mysql, "m y_database")) fprintf(stderr, "Failed to drop the database: Error : %s\n", mysql_error(&mysql)); mysql_dump_debug_info()int mysql_ dump_debug_info(MYSQL mysql) 说明指示服务者将一些调试信息写入日志文件。连接的用户对此必须有pre cess权限才能工作。 返回值如果命令成功,零。如果发生一个错误,非零。 错误CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务者关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 mysql_eof()my_bool mysql_eof(MYSQL_RES result) 说明这个函数不推荐,而使用mysql_errno()或mysql_er ror()。 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()返回非零值,并且如果发生一个错误,返回零。在时间上,mys ql_eof()先于标准MySQL错误函数mysql_errno()和mysql_error()。因为这些错误函数提供相同的信息, 他们的使用更好mysql_eof(),它现在不建议使用。(事实上,他们提供更多的信息,因为mysql_eof()值返回一个布尔值, 而错误函数指出当发生错误时的出错原因。) 返回值如果发生一个错误,零。如果到达结果集合的结束,非零。 错误无。 范例下列例子显 示你必须如何使用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)) // m ysql_fetch_row() failed due to an error{ fprintf(stderr, "Error: %s\n", mysql_error(&mysql));}然而,你可以用标准MySQL错误函数完成同样的效果: mysql_que ry(&mysql,"SELECT FROM some_table");result = mysql_use_result(& mysql);while((row = mysql_fetch_row(result))){ // do something wi th data}if(mysql_errno(&mysql)) // mysql_fetch_row() failed due to an error{ fprintf(stderr, "Error: %s\n", mysql_error(&mysql)); } mysql_errno()unsigned int mysql_errno(MYSQL mysql) 说明对于由mysq l指定的连接,mysql_errno()返回最近调用的可能成功或失败的API函数的错误代码。返回值零意味着没有错误发生。客户错误消 息编号列出在MySQL“errmsg.h”头文件中。服务器错误消息编号列出在“mysqld_error.h”中。 返回值:一个错 误代码值。如果没有错误发生,零。 错误无。 mysql_error()char mysql_error(MYSQL mys ql) 说明对于由mysql指定的连接,mysql_errno()返回最近调用的可能成功或失败的API函数的错误代码。如果没有错 误发生,返回空字符串("")。这意味着下列两个测试是等价的:if(mysql_errno(&mysql)){ // an erro r occurred}if(mysql_error(&mysql)[0] != ''\0''){ // an error occurr ed}客户错误消息的语言可通过重新编译MySQL客户库来改变。目前,你能在几种不同的语言间选取错误消息。见9.1 MySQL支持什 么语言?。 返回值一个描述错误的字符串。如果没有错误发生,空字符串。 错误无。 mysql_escape_string()u nsigned int mysql_escape_string(char to, const char from, unsig ned int length) 说明把在from中的字符串编码为在一条SQL语句中可以发给服务器的转义的SQL字符串,将结果放在 to中, 并且加上一个终止的空字节。编码的字符是NUL(ASCII 0)、‘\n’、‘\r’、‘\’、‘''’、‘"’和Contro l-Z(见7.1 文字:如何写字符串和数字)。由from指向的字符串必须是length个字节长。你必须分配to的缓冲区至少leng th2+1个字节长。(在更坏的情况,每个字符可能需要使用2个字节被编码,并且你需要为终止空字节的空间) 当mysql_escap e_string()返回时,to的内容将是空字符终止的字符串。返回值是编码后的字符串的长度,不包括终止空字符。 范例char q uery[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_st ring(end,"binary data: \0\r\n",16);end++ = ''\'''';end++ = '')'';if (mysql_real_query(&mysql,query,(unsigned int) (end - query))){ fp rintf(stderr, "Failed to insert row, Error: %s\n", mysql_error(&m ysql));}例子中所用的strmov()函数被包括在mysqlclient库中且功能类似于strcpy(),但是返回一个指向空 终止的第一个参数的指针。 返回值放进to的值的长度,不包括终止空字符。 错误无。 mysql_fetch_field()MYSQ L_FIELD mysql_fetch_field(MYSQL_RES result) 说明返回作为一个MYSQL_FIEL D结构的一个结果集合的一个列的定义。重复调用这个函数在结果集合中检索所有关于列的信息。当没有剩下更多的字段时,mysql_fetc h_field()返回NULL。在每次你执行一个新的SELECT查询,mysql_fetch_field()被重置(reset)以 返回有关第一列的信息。由mysql_fetch_field()返回的字段也受调用mysql_field_seek()的影响。如果你 调用mysql_query()在一张表上执行一个SELECT,但是没调用mysql_store_result(),如果你调用mys ql_fetch_field()询问一个BLOB字段的长度,MySQL返回缺省BLOB长度(8K字节)。(选择8K的长度是因为My SQL不知道BLOB的最大长度。这应该在某个时候是它可配置) 一旦你已经检索了结果集合,field->max_length包含了在 特定查询中对于该列最大值的长度。 返回值当前列的MYSQL_FIELD结构。如果没有列剩下,NULL。 错误无。 范例MYSQL_ FIELD field;while((field = mysql_fetch_field(result))){ printf(" field name %s\n", field->name);} mysql_fetch_fields()MYSQL_FIELD mysql_fetch_fields(MYSQL_RES result) 说明返回一个结果集合的所有MYSQL_FIELD 结构的数组。每个结构提供结果结合中一列的字段定义。 返回值一个结果集合的所有MYSQL_FIELD结构的一个数组。 错误无。 范例unsigned int num_fields;unsigned int i;MYSQL_FIELD fields;num_ fields = mysql_num_fields(result);fields = mysql_fetch_fields(res ult);for(i = 0; i < num_fields; i++){ printf("Field %u is %s\n", i, fields[i].name);} mysql_fetch_field_direct()MYSQL_FIELD mysql _fetch_field_direct(MYSQL_RES result, unsigned int fieldnr) 说明给 定在一个结果集合中的一个列的字段编号fieldnr,返回作为MYSQL_FIELD结构的列的字段定义。你可以使用这个函数检索任意列 的义。fieldnr的值应该在从0到mysql_num_fields(result)-1范围内。 返回值指定列的MYSQL_FIE LD结构。 错误无。 范例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);} mysql_fetch_lengths()unsi gned long mysql_fetch_lengths(MYSQL_RES result) 说明返回在结果集合内的当前行 的列长度。如果你计划拷贝字段值,这个长度信息对优化也是有用的,因为你可以避免调用strlen()。另外,如果结果集合中包含二进制数 据,你必须使用这个函数确定数据的大小,因为strlen()对包含空字符的任何字段返回不正确的结果。 空列和包含NULL的列的长度值 是零。为了看清如何区分这两种情况,见mysql_fetch_row()的说明。 返回值表示每列大小的无符号长整数的一个数组(不包括 任何终止空字符)。如果出现一个错误,NULL。 错误mysql_fetch_lengths()只对结果集合的当前行有效。如果你在 调用mysql_fetch_row()之前或在检索出在结果中的所有以后,它返回NULL。 范例MYSQL_ROW row;unsi gned long lengths;unsigned int num_fields;unsigned int i;row = m ysql_fetch_row(result);if (row){ num_fields = mysql_num_fields(re sult); lengths = mysql_fetch_lengths(result); for(i = 0; i < num_ fields; i++) { printf("Column %u is %lu bytes in length.\n", i, l engths[i]); }} mysql_fetch_row()MYSQL_ROW mysql_fetch_row(MYSQL_ RES result) 说明检索一个结果集合的下一行。当在mysql_store_result()之后使用时,如果没有更多的行 可见所时,mysql_fetch_row()返回NULL。当在mysql_use_result()之后使用时,当没有更多的行可检索 时或如果出现一个错误,mysql_fetch_row()返回NULL。在行中值的数量由mysql_num_fields(resul t)给出。如果row保存了从一个对用mysql_fetch_row()调用返回的值,指向该值的指针作为row[0]到row[mys ql_num_fields(result)-1]来存取。在行中的NULL值由NULL指针指出。在行中字段值的长度可以通过调用mys ql_fetch_lengths()获得。空字段和包含NULL的字段长度都是 0;你可以通过检查该值的指针区分他们。如果指针是NU LL,字段是NULL;否则字段是空的。 返回值下一行的一个MYSQL_ROW结构。如果没有更多的行可检索或如果出现一个错误,NUL L。 错误CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 范例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) lengt hs[i], row[i] ? row[i] : "NULL"); } printf("\n");} mysql_field_c ount()unsigned int mysql_field_count(MYSQL mysql) 如果你正在使用一个比3.22 .24早MySQL版本,你应该使用unsigned int mysql_num_fields(MYSQL mysql)。 说明 返回在连接上的最近查询的列的数量。 这个函数一般用在mysql_store_result()返回NULL时(这样你没有结果设置指针 )。在这种情况中,你能调用mysql_field_count()确定mysql_store_result()是否应该产生了一个非空 的结果。这允许一个客户程序执行正确的操作,而不必知道查询是否是一条SELECT(或类SELECT)语句。下面显示的例子说明这怎样可 以做到。 见 为什么在mysql_query()返回成功后,mysql_store_result()有时返回NULL?。 返回值在 结果集合中表示字段数量字的一个无符号整数。 错误无。 范例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 b y it{ result = mysql_store_result(&mysql); if (result) // there are rows { num_fields = mysql_num_fields(result); // retrieve row s, then call mysql_free_result(result) } else // mysql_store_res ult() returned nothing; should it have? { if(mysql_field_count(&m ysql) == 0) { // query does not return data // (it was not a SELE CT) 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_f ield_count(&mysql)调用。在这种情况中,你直接检查来自mysql_store_result()的一个错误而非从my sql_field_count()值来推断语句是否是一个SELECT。 mysql_field_seek()MYSQL_FIELD _OFFSET mysql_field_seek(MYSQL_RES result, MYSQL_FIELD_OFFSET of fset) 说明将字段光标设置到给定的偏移量。下一次调用mysql_fetch_field()将检索与该偏移量关联的列的字段定义 。 为了定位于行的起始,传递一个值为0的offset值。 返回值字段光标的先前的值。 错误无。 mysql_field_tel l()MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES result) 说明返回用于 最后一个mysql_fetch_field()的字段光标的位置。这个值可用作mysql_field_seek()的一个参数。 返 回值字段光标的当前偏移量。 错误无。 mysql_free_result()void mysql_free_result(MY SQL_RES result) 说明释放由mysql_store_result()、mysql_use_result()、my sql_list_dbs()等为一个结果集合分配的内存。当你用完了一个结果集合时,你必须调用mysql_free_result() 来释放它使用的内存。返回值无。 错误无。 mysql_get_client_info()char mysql_get_cli ent_info(void) 说明返回代表客户库的版本的字符串。 返回值代表MySQL客户库版本的一个字符串。 错误无。 m ysql_get_host_info()char mysql_get_host_info(MYSQL mysql) 说明返回描 述正在使用的连接类型的字符串,包括服务其主机名。 返回值表示服务器主机名者和连接类型的字符串。 错误无。 mysql_get _proto_info()unsigned int mysql_get_proto_info(MYSQL mysql) 说明返 回当前连接使用的协议版本。 返回值表示被当前连接使用的协议版本的一个无符号整数。 错误无。 mysql_get_server _info()char mysql_get_server_info(MYSQL mysql) 说明返回表示服务器版本号的字符 串。 返回值表示服务器版本号的一个字符串。 错误无。 mysql_info()char mysql_info(MYSQL mysql) 说明检索一个字符串,它提供有关最近执行的查询的信息,但是对下面列出的语句。对其他语句,mysql_info()返 回NULL。字符串的格式随查询类型而变化,如下所述。数字仅仅是说明性的;字符串将包含对查询适当的值。 INSERT INTO .. . SELECT ... 字符串格式: Records: 100 Duplicates: 0 Warnings: 0 INSERT INTO ... VALUES (...),(...),(...)... 字符串格式: Records: 3 Duplicate s: 0 Warnings: 0 LOAD DATA INFILE ... 字符串格式: Records: 1 Deleted: 0 Skipped: 0 Warnings: 0 ALTER TABLE 字符串绳格式: Records: 3 Duplicate s: 0 Warnings: 0 UPDATE 字符串格式: Rows matched: 40 Changed: 40 Warni ngs: 0 注意,只有多个值在语句中指定,mysql_info()对INSERT ... VALUES语句才返回非NULL值。 返回值表示最近执行的查询的附加信息的一个字符串。如果得不到查询的任何信息,NULL。 错误无。 mysql_init()MYS QL mysql_init(MYSQL mysql) 说明分配或初始化适合mysql_real_connect()的一个MY SQL对象。如果mysql是一个NULL指针,函数分配、初始化并且返回一个新对象。否则对象被初始化并且返回对象的地址。如果mysq l_init()分配一个新对象,它将在调用mysql_close()关闭连接时被释放。 返回值一个被初始化的MYSQL句柄。如果 没有足够的内存来分配一个新对象,NULL。 错误在内存不够的情况下,返回NULL。 mysql_insert_id()my_ulo nglong mysql_insert_id(MYSQL mysql) 说明返回由先前的查询为一个AUTO_INCREMENT 列生成的ID。在你执行一个INSERT查询向一个包含AUTO_INCREMENT字段的表中插入后,使用这个函数。注意,如果先前的查 询不产生一个AUTO_INCREMENT值,mysql_insert_id()返回0。如果你需要在以后保存该值,必须在查询生成了该 值后马上调用mysql_insert_id()。也要注意,SQL的LAST_INSERT_ID()函数总是包含最近生成的AUTO_ INCREMENT值,并且在查询之间不被重置,因为该函数的值在服务器端维护。 返回值有先前的查询更新的AUTO_INCREMEN T字段的值。如果在连接上没有先前的询问或如果查询没更新AUTO_INCREMENT值,返回零。 错误无。 mysql_kill( )int mysql_kill(MYSQL mysql, unsigned long pid) 说明要求服务器杀死由pid指定 的线程。 返回值成功,零。如果出现一个错误,非零。 错误CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确的次序 被执行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 对服务器的连接在查询期 间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 mysql_list_dbs()MYSQL_RES mys ql_list_dbs(MYSQL mysql, const char wild) 说明返回一个结果集合,它用在服务器上的匹 配wild参数指定的简单正则表达式的数据库名组成。wild可以包含通配符字符“%”或“_”,或可以是匹配所有的数据库的一个NULL 指针。调用mysql_list_dbs()类似于执行查询SHOW databases [LIKE wild]。你必须用mysql_ free_result()释放结果集合。 返回值成功,一个MYSQL_RES结果集合。如果出现一个错误,NULL。 错误CR_C OMMANDS_OUT_OF_SYNC 命令以一个不正确的次序被执行。 CR_OUT_OF_MEMORY 内存溢出。 CR_SER VER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNK NOWN_ERROR 发生一个未知的错误。 mysql_list_fields()MYSQL_RES mysql_list_ fields(MYSQL mysql, const char table, const char wild) 说明返回一个 结果集合,它用在给定表中的匹配wild参数指定的简单正则表达式的列名组成。wild可以包含通配符字符“%”或“_”,或可以是匹配所 有列的一个NULL指针。调用mysql_list_fields()类似于执行查询SHOW COLUMNS FROM tbl_nam e [LIKE wild]。注意,建议你使用SHOW COLUMNS FROM tbl_name而不是mysql_list_fie lds()。你必须用mysql_free_result()释放结果集合。 返回值成功,一个MYSQL_RES的结果集合。如果出线一 个错误,NULL。 错误CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确的次序被执行。 CR_SERVER_GON E_ERROR MySQL服务者关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ER ROR 发生一个未知的错误。 mysql_list_processes()MYSQL_RES mysql_list_proce sses(MYSQL mysql) 说明返回一个描述当前服务器线程的结果集合。这是与mysqladmin processlis t或SHOW PROCESSLIST查询报告的相同信息。你必须用mysql_free_result()释放结果集合。 返回值成功, 一个MYSQL_RES结果集合。如果发生一个错误,NULL。 错误CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确 的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务者关闭了。 CR_SERVER_LOST 对服务器的连接在 查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 mysql_list_tables()MYSQL_RES mysql_list_tables(MYSQL mysql, const char wild) 说明返回一个结果集合,它 用在当前数据库中的匹配wild参数指定的简单正则表达式的表名组成。wild可以包含通配符字符“%”或“_”,或可以是匹配所有表的一 个NULL指针。调用mysql_list_tables()类似于执行询问SHOW tables [LIKE wild]。你必须用m ysql_free_result()释放结果集合。 返回值成功,一个MYSQL_RES结果集合。如果出现一个错误,NULL。 错误 CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确的次序被执行。 CR_SERVER_GONE_ERROR MySQ L服务器关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错 误。 mysql_num_fields()unsigned int mysql_num_fields(MYSQL_RES re sult) 或unsigned int mysql_num_fields(MYSQL mysql) 第二中形式在MySQL 3. 22.24或更新版本上不能工作。为了传递一个MYSQL 参数,你必须使用unsigned int mysql_field_cou nt(MYSQL mysql)。 说明在结果集合中返回列的数量。 注意,你也可以通过一个指向一个结果集合或一个连接句柄的指针获 得列的数量。如果mysql_store_result()或mysql_user_result()返回NULL,你将使用连接句柄(而 这样你没有结果集合指针)。在这种情况下,你可以调用mysql_field_count()确定mysql_store_result( )是否应该产生非空的结果。这允许客户程序采取成正确的行动,不必知道查询是否是一个SELECT(或类SELECT)语句。下面被显示出 的例子说明这怎么可以被做。 见 为什么在mysql_query()返回成功后,mysql_store_result()有时返回NU LL?。 返回值表示一个结果集合中字段数量的一个无符号整数。 错误无。 范例MYSQL_RES result;unsign ed int num_fields;unsigned int num_rows;if (mysql_query(&mysql,qu ery_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); // re trieve rows, then call mysql_free_result(result) } else // mysql _store_result() returned nothing; should it have? { if (mysql_err no(&mysql)){ fprintf(stderr, "Error: %s\n", mysql_error(&mysql)); } else if (mysql_field_count(&mysql) == 0) { // query does not re turn data // (it was not a SELECT) num_rows = mysql_affected_rows (&mysql); } }}另一个选择(如果你知道你查询应该返回了一个结果结合)是用mysql_field_count(&mysq l) = 0的一个检查来代替mysql_errno(&mysql)。这只会发生在出错了的情形。 mysql_num_rows()m y_ulonglong mysql_num_rows(MYSQL_RES result) 说明在结果集合中返回行的数量。 my sql_num_rows()的使用取决于你是否使用mysql_store_result()或mysql_use_result()返 回一个结果集合。如果你使用mysql_store_result(),mysql_num_rows()可以马上被调用。如果你使用my sql_use_result(),mysql_num_rows()将不会返回正确的值,直到在结果集合中的所有行均被检索了。 返回 值在结果集合中行的数量。 错误无。 mysql_options()int mysql_options(MYSQL mysql , enum mysql_option option, const char arg) 说明能用于设置额外连接选项并且影响一个 连接的行为。这个函数可以被多次调用来设置多个选项。 mysql_options()应该在mysql_init()之后和mysql_ connect()或mysql_real_connect()之前调用。option参数是你想要设置的选项;arg参数是选项的值。如 果选项是一个整数,那么arg应该指向整数值。可能的选项值:选项 参数类型 功能 MYSQL_OPT_CONNECT_TIMEOUT unsigned int 以秒计的连接超时。 MYSQL_OPT_COMPRESS 不使用使用压缩的客户机/服务器协议。 M YSQL_OPT_NAMED_PIPE 不使用使用命名管道连接一个在NT上的MySQL服务器。 MYSQL_INIT_COMMAN D char 当连接MySQL服务器时执行的命令。当重新连接时,将自动重新执行。 MYSQL_READ_DEFAULT_FIL E char 从命名的选项文件而不是从“my.cnf”读取选项。MYSQL_READ_DEFAULT_GROUP char 从“my.cnf”或用MYSQL_READ_DEFAULT_FILE指定的文件中的命名组中读取选项。注意,如果你使用MYSQL_ READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP,总是读取client。在选项文件中指定的组可 能包含下列选项:compress 使用压缩的客户机/服务器协议。 database 如果在连接命令中没有指定数据库,使用这个数据库 。debug 调试选项host 缺省主机名init-command 在连接MySQL服务器时,执行的命令。当重新连接时,将自动重新 执行。 password 缺省口令pipe 使用命名管道连接一个在NT上的MySQL服务器。 port 缺省端口号return-f ound-rows 告诉mysql_info()返回找到的行,而不是在使用UPDATE时,返回更新的行。 socket 缺省套接字 号timeout 以秒计的连接超时。 user 缺省用户对于选项文件的更多信息,见4.15.4 选项文件。 返回值成功,零。如果你 使用了未知的选项,非零。 范例MYSQL mysql;mysql_init(&mysql);mysql_options(&mysq l,MYSQL_OPT_COMPRESS,0);mysql_options(&mysql,MYSQL_READ_DEFAULT_G ROUP,"odbc");if (!mysql_real_connect(&mysql,"host","user","passwd ","database",0,NULL,0)){ fprintf(stderr, "Failed to connect to da tabase: Error: %s\n", mysql_error(&mysql));}上例请求客户使用压缩的客户机/服务器协议并 且从my.cnf文件的odbc小节读取额外的选项。 mysql_ping()int mysql_ping(MYSQL mysql ) 说明检查到服务器的连接是否正在工作。如果它关闭了,自动尝试一个再连接。这个函数可被已经空闲很长时间的客户使用,来检查服务器是 否关闭了连接并且如有必要重新连接。 返回值如果服务器活着,零。如果出现一个错误,非零。 错误CR_COMMANDS_OUT_OF _SYNC 命令以一个不适当的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_UNKNOW N_ERROR 发生一个未知的错误。 mysql_query()int mysql_query(MYSQL mysql, c onst char query) 说明执行指向空终止的字符串query的SQL查询,查询必须由一个单个的SQL语句组成。你不应 该在语句后加上一个终止的分号(“;”)或\g。mysql_query()不能被用于包含二进制数据的查询;相反你应该使用mysql_ real_query()。(二进制数据可能包含“\0”字符,而mysql_query()将解释为查询字符串的结束。) 返回值如果查 询成功,零。如果出现一个错误,非零。 错误CR_COMMANDS_OUT_OF_SYNC 命令以一个不适当的次序被执行。 CR_S ERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 到服务器的连接在查询期间失去。 CR_U NKNOWN_ERROR 发生一个未知的错误。 mysql_real_connect()MYSQL mysql_real_c onnect(MYSQL mysql, const char host, const char user, const ch ar passwd, const char db, unsigned int port, const char unix_s ocket, unsigned int client_flag) 说明mysql_real_connect()试图建立到运行ho st的一个MySQL数据库引擎的一个连接。 mysql_real_connect()在你可以执行任何其他API函数之前必须成功地完 成,除了mysql_get_client_info()。参数指定如下: 第一个参数应该是一个现存MYSQL结构的地址。在调用mys ql_real_connect()之前,你必须调用mysql_init()初始化MYSQL结构。见下面的例子。 host值可以是一 个主机名或一个IP地址。如果host是NULL或字符串"localhost",假定是到本地主机的一个连接。如果OS支持套接字(Un ix)或命名管道(Win32),使用他们而不是TCP/IP与服务器连接。 user参数包含用户的MySQL登录ID。如果user是 NULL,假定是当前用户。在Unix下,它是当前登录名。在Windows ODBC下,必须明确地指定当前用户名字。见16.4 怎样 填写ODBC管理程序中各种域。 passwd参数为user包含口令。如果passwd是NULL,只有在user表中对于有一个空白口 令字段的用户的条目将被检查一个匹配。这允许数据库主管设置MySQL权限,使用户获得不同的口令,取决于他们是否已经指定一个口令。注意 :不要试图在调用mysql_real_connect()前加密口令;口令加密自动被客户API处理。 db是数据库名。如果db不是N ULL,连接将缺省数据库设置为这个值。 如果port不是0,值对于TCP/IP连接将用作端口号。注意host参数决定连接的类型。 如果unix_socket不是NULL,字符串指定套接字或应该被使用的命名管道。注意host参数决定连接的类型。 client_f lag值通常是0,但是在很特殊的情况下可以被设置为下列标志的组合: 标志名字 意味着的标志 CLIENT_FOUND_ROWS 返 回找到的(匹配的)行数,不是受到影响的行数。CLIENT_NO_SCHEMA 不允许db_name.tbl_name.col_na me语法。这是为了ODBC;如果你使用该语法,导致语法分析器产生一个错误,它是为在一些ODBC程序捕捉错误是有用的。 CLIENT _COMPRESS 使用压缩协议。CLIENT_ODBC 客户是一个ODBC客户。这使mysqld变得对ODBC更友好。 返回值 如果连接成功,一个 MYSQL连接句柄。如果连接失败,NULL。对一个成功的连接,返回值与第一个参数值相同,除非你传递NULL给 该参数。 错误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_ERRO R; 不能在 Win32 上创建一个命名管道。 CR_NAMEDPIPEWAIT_ERROR; 不能在 Win32 上等待一个命名 管道。 CR_NAMEDPIPESETSTATE_ERROR; 不能在 Win32 上得到一个管道处理器。 范例MYSQL my sql;mysql_init(&mysql);if (!mysql_real_connect(&mysql,"host","use r","passwd","database",0,NULL,0)){ fprintf(stderr, "Failed to con nect to database: Error: %s\n", mysql_error(&mysql));} mysql_real _query()int mysql_real_query(MYSQL mysql, const char query, uns igned int length) 说明执行由query指向的SQL查询,它应该是一个length个字节的字符串。查询必须由一个 单个的SQL语句组成。你不应该在语句后增加一个终止的分号(“;”)或\g。对于包含二进制数据的查询,你必须使用mysql_real _query()而不是mysql_query(),因为二进制代码数据可能包含“\0”字符,而且,mysql_real_query( )比mysql_query()更快,因为它对查询字符串调用strlen()。 返回值如果查询成功,零。如果发生一个错误,非零。 错 误CR_COMMANDS_OUT_OF_SYNC 命令以一个不适当的次序被执行。 CR_SERVER_GONE_ERROR MyS QL服务器关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的 错误。 mysql_reload()int mysql_reload(MYSQL mysql) 说明要求MySQL服务器再 次装载授权表。连接的用户必须拥有reload权限。 不推荐这个函数。最好使用mysql_query()发出一条SQL FLUSH PRIVILEGES语句。 返回值成功,零。如果发生一个错误,非零。 错误 CR_COMMANDS_OUT_OF_SYNC 命令以 一个不适当的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 对服务 器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 mysql_row_seek()MYSQL_ ROW_OFFSET mysql_row_seek(MYSQL_RES result, MYSQL_ROW_OFFSET off set) 说明设置行光标为在结果集合中的任意行。这要求结果集合结构包含查询的全部结果,这样mysql_row_seek()只能与 mysql_store_result()一起使用,而不与mysql_use_result()。偏移量应该是调用mysql_row_ tell()或mysql_row_seek()返回的值。这个值不是简单地一个行号;如果你想要在结果集合内用行号来寻找行,使用mys ql_data_seek()。 返回值行光标先前的值。该值可以被传递给随后的mysql_row_seek()调用。 错误无。 m ysql_row_tell()MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES result) 说明返回为了mysql_fetch_row()的行光标的当前位置。这个值可以作为一个参数用于mysql_row_seek()。 你应该仅在mysql_store_result()后使用mysql_row_tell(),而不是在mysql_use_resul t()后。 返回值行光标当前的偏移量。 错误无。 mysql_select_db()int mysql_select_db( MYSQL mysql, const char db) 说明使得由db指定的数据库成为 在由mysql指定的连接上的缺省(当 前)数据库。在随后的查询中,这个数据库对于不包括一个显式的数据库指定符的表的引用是缺省数据库。除非连接的用户能被认证允许使用数据库 ,否则mysql_select_db()失败。 返回值成功,零。如果发生一个错误,非零。 错误CR_COMMANDS_OUT_O F_SYNC 命令以一个不适当的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVE R_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 mysql_shutdo wn()int mysql_shutdown(MYSQL mysql) 说明让数据库服务器关闭。连接的用户必须有shutdow n权限。 返回值成功,零。如果出现一个错误,非零 错误CR_COMMANDS_OUT_OF_SYNC 命令以一个不适当的次序被执 行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失 去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 mysql_stat()char mysql_stat(MYS QL mysql) 说明返回包含类似于由mysqladmin status命令提供的信息的一个字符串。它包括正常运行的秒数和正 在运行线程、问题、再次装载和打开的表的数目。 返回值描述服务器状态的一个字符串。如果出现一个错误,NULL。 错误CR_COMM ANDS_OUT_OF_SYNC 命令以一个不适当的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了 。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 mys ql_store_result()MYSQL_RES mysql_store_result(MYSQL mysql) 说明对 于成功地检索数据的每个询问(SELECT、SHOW、DESCRIBE、EXPLAIN),你必须调用mysql_store_resu lt()或mysql_use_result()。mysql_store_result()读取一个到客户的查询的全部结果,分配一个M YSQL_RES结构,并且把结果放进这个结构中。 如果没有行返回,返回一个空集合集合。(空结果集合不同于一个NULL返回值。)一旦 你调用了mysql_store_result(),你可以调用mysql_num_rows()找出结果集合中有多少行。你能调用mys ql_fetch_row()从结果集合中取出行,或mysql_row_seek()和mysql_row_tell()结果集合中获得 或设置当前的行位置。 一旦你用完结果集合,你必须调用mysql_free_result()。见 为什么mysql_query()返 回成功后,mysql_store_result()有时返回NULL?。 返回值一个保存结果的MYSQL_RES结构。如果出现一个错 误,NULL。 错误CR_COMMANDS_OUT_OF_SYNC 命令以一个不适当的次序被执行。 CR_OUT_OF_MEMOR Y 内存溢出。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 对服务器的连接在 查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 mysql_thread_id()unsigned lo ng mysql_thread_id(MYSQL mysql) 说明返回当前连接的线程ID。这个值可用作mysql_kill( )的一个参数以杀死线程。如果失去连接并且你用mysql_ping()重新连接,线程ID将改变。这意味着你不应该为以后使用获得线程I D并且存储它,当你需要它时,你应该获得它。 返回值当前连接的线程 ID 。 错误无。 mysql_use_result()MY SQL_RES mysql_use_result(MYSQL mysql) 说明对于成功地检索数据的每个查询(SELECT、 SHOW、DESCRIBE、EXPLAIN),你必须调用mysql_store_result()或mysql_use_result ()。mysql_use_result()初始化一个结果集合的检索,但不真正将结果集合读入客户,就象mysql_store_res ult()那样。相反,必须通过调用mysql_fetch_row()单独检索出每一行,这直接从服务器读出结果而不在一个临时表或本地缓冲区中存储它,它比mysql_store_result()更快一点并且使用较少的内存。客户将只为当前行和一个可能最大max_allowed_packet字节的通信缓冲区分配内存。在另一方面,如果你在客户端对每一行正在做很多的处理,或如果输出被送到屏幕,用户可以打一个^S(停止滚动),你不应该使用mysql_use_result()。这将阻塞服务器并且阻止另外的线程从数据被取出的任何表中更新数据。 当使用mysql_use_result()时,你必须执行mysql_fetch_row()直到返回一个NULL值,否则未取出的行将作为下一个查询的结果集合一部分被返回。如果你忘记做这个,C API将给出错误Commands out of sync; You can''t run this command now!你不能在一个从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()。 返回值一个MYSQL_RES结果结构。 如果发生一个错误发生,NULL。 错误CR_COMMANDS_OUT_OF_SYNC 命令以一个不适当的次序被执行。 CR_OUT_OF_MEMORY 内存溢出。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 为什么在mysql_query()返回成功后,mysql_store_result()有时返回NULL?有可能在一个对mysql_query()成功的调用后,mysql_store_result()返回NULL。当这发生时,它意味着出现了下列条件之一: 有一个malloc()失败(例如,如果结果集合太大)。 数据不能被读取(发生在连接上的一个错误)。 查询没有返回数据(例如,它是一个INSERT、UPDATE或DELETE)。 你总是可以通过调用mysql_field_count()检查语句是否应该产生非空的结果。如果mysql_field_count()返回零,结果是空的并且最后一个查询是不回值的一条语句(例如,一条INSERT或DELETE)。如果mysql_field_count()返回非零值,语句应该产生非空的结果。见对mysql_field_count()描述的一个例子。 你可以调用mysql_error()或mysql_errno()测试一个错误。 我能从查询中得到什么结果?除了由查询返回的结果集合外,你也能得到下列信息: 当执行一条INSERT、UPDATE或DELETE时,mysql_affected_rows()返回受到最后一个查询影响的行数。一个例外是如果使用一条没有WHERE子句的DELETE,表被截断,它更快!在这种情况下,mysql_affected_rows()对于影响的记录数量返回零。 mysql_num_rows()返回结果集合中的行数。用mysql_store_result(),一旦mysql_store_result()返回,就可以调用mysql_num_rows()。用mysql_use_result(),只有在你已经用mysql_fetch_row()取出了所有行后,才能调用mysql_num_rows()。 mysql_insert_id()返回由将一行插入一个具有AUTO_INCREMENT索引的表中的最后查询生成的ID。见 mysql_insert_id()。 某些查询(LOAD DATA INFILE ...、INSERT INTO ... SELECT ...、UPDATE)返回附加的信息。结果由返mysql_info()返回。对其返回字符串的格式,见mysql_info()的描述。如果没有附加的信息,mysql_info()返回一个NULL指针。 我怎样能得到最后插入的行的唯一ID?如果你往包含一个具有AUTO_INCREMENT属性的列的一张表中插入一个记录,你能通过mysql_insert_id()函数获得最近生成的ID。你也可以通过在你传递给mysql_query()的一个查询字符串中使用LAST_INSERT_ID()函数检索出ID。你可以执行下列代码检查是否使用一个AUTO_INCREMENT索引。这也检查查询是否是有一个AUTO_INCREMENT索引的一条INSERT:if (mysql_error(&mysql)[0] == 0 && mysql_num_fields(result) == 0 && mysql_insert_id(&mysql) != 0){ used_id = mysql_insert_id(&mysql);}最近产生的ID是在一个按连接的基础上在服务器上进行维护,它将不被其他客户改变。如果你更新另外一个有非奇特(non-magic)值(即一个既不是NULL也不是0的值)的AUTO_INCREMENT列,它甚至将不被改变。如果你想要使用为一张表生成的ID并且把它插入到第2张表,你可以使用象这样的SQL语句:INSERT INTO foo (auto,text) VALUES(NULL,''text''); # generate ID by inserting NULLINSERT INTO foo2 (id,text) VALUES(LAST_INSERT_ID(),''text''); # use ID in second table |
|