MYSQL
这个结构表示对一个数据库连接的句柄,它被用于几乎所有的MySQL函数。
MYSQL_RES
这个结构代表返回行的一个查询的(SELECT, SHOW, DESCRIBE, EXPLAIN)的结果。从查询返回的信息在本章下文称为结果集合。
MYSQL_ROW
这是一个行数据的类型安全(type-safe)的表示。当前它实现为一个计数字节的字符串数组。(如果字段值可能包含二进制数据,你不能将这些视为空终止串,因为这样的值可以在内部包含空字节) 行通过调用mysql_fetch_row()获得。
MYSQL_FIELD
这个结构包含字段信息,例如字段名、类型和大小。其成员在下面更详细地描述。你可以通过重复调用mysql_fetch_field()对每一列获得MYSQL_FIELD结构。字段值不是这个结构的部分;他们被包含在一个MYSQL_ROW结构中。
MYSQL_FIELD_OFFSET
这是一个相对一个MySQL字段表的偏移量的类型安全的表示。(由mysql_field_seek()使用。) 偏移量是在一行以内的字段编号,从0开始。
my_ulonglong
该类型用于行编号和mysql_affected_rows()、mysql_num_rows()和mysql_insert_id()。这种类型提供0到1.84e19的一个范围。在一些系统上,试图打印类型my_ulonglong的值将不工作。为了打印出这样的值,将它变换到unsigned long并且使用一个%lu打印格式。例如:
printf (Number of rows: %lu/n", (unsigned long) mysql_num_rows(result));
MYSQL_FIELD结构包含列在下面的成员:
char * name
字段名,是一个空结尾的字符串。
char * table
包含该字段的表的名字,如果它不是可计算的字段。对可计算的字段,table值是一个空字符串。
char * def
这字段的缺省值,是一个空结尾的字符串。只要你使用,只有你使用mysql_list_fields()才可设置它。
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
BIGINT字段
FIELD_TYPE_DECIMAL
DECIMAL或NUMERIC字段
FIELD_TYPE_FLOAT
FLOAT字段
FIELD_TYPE_DOUBLE
DOUBLE或REAL字段
FIELD_TYPE_TIMESTAMP
TIMESTAMP字段
FIELD_TYPE_DATE
DATE字段
FIELD_TYPE_TIME
TIME字段
FIELD_TYPE_DATETIME
DATETIME字段
FIELD_TYPE_YEAR
YEAR字段
FIELD_TYPE_STRING
字符串(CHAR或VARCHAR)字段
FIELD_TYPE_BLOB
BLOB或TEXT字段(使用max_length决定最大长度)
FIELD_TYPE_SET
SET字段
FIELD_TYPE_ENUM
ENUM字段
FIELD_TYPE_NULL
NULL- 类型字段
FIELD_TYPE_CHAR
不推荐;使用FIELD_TYPE_TINY代替
IS_NUM()宏来测试字段是否有一种数字类型。将type值传给IS_NUM()并且如果字段是数字的,它将计算为TRUE:
(IS_NUM(field->type))
printf("Field is numeric/n");
unsigned int length
字段宽度,在表定义中指定。
unsigned int max_length
对结果集合的字段的最大宽度(对实际在结果集合中的行的最长字段值的长度)。如果你使用mysql_store_result()或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_INCREMENT_FLAG
字段有AUTO_INCREMENT属性
ENUM_FLAG
字段是一个ENUM(不推荐)
BLOB_FLAG
字段是一个BLOB或TEXT(不推荐)
TIMESTAMP_FLAG
字段是一个TIMESTAMP(不推荐)
BLOB_FLAG、ENUM_FLAG和TIMESTAMP_FLAG标志的使用是不推荐的,因为他们指出字段的类型而非它的类型属性。对FIELD_TYPE_BLOB、FIELD_TYPE_ENUM或FIELD_TYPE_TIMESTAMP,最好是测试field->type。下面例子演示了一个典型的flags值用法:
if (field->flags & NOT_NULL_FLAG)
printf("Field can't be null/n");
你可以使用下列方便的宏决来确定flags值的布尔状态:
IS_NOT_NULL(flags)
真,如果该字段被定义为NOT NULL
IS_PRI_KEY(flags)
真,如果该字段是一个主键
IS_BLOB(flags)
真,如果该字段是一个BLOB或TEXT(不推荐;相反测试field->type)
unsigned int decimals
对数字字段的小数位数。
mysql_affected_rows()
返回被最新的UPDATE, DELETE或INSERT查询影响的行数。
mysql_close()
关闭一个服务器连接。
mysql_connect()
连接一个MySQL服务器。该函数不推荐;使用mysql_real_connect()代替。
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_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_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()函数提供错误信息的存取。他们返回最近调用的可能成功或失败的函数的错误代码或错误消息,允许你确定何时发生一个错误和什么错误。