25.2.3.66. mysql_store_result()
MYSQL_RES *mysql_store_result(MYSQL *mysql)
描述
对于成功检索了数据的每个查询(SELECT 、SHOW 、DESCRIBE 、EXPLAIN 、CHECK TABLE 等 ),必须调用mysql_store_result() 或mysql_use_result() 。
对于其他查询,不需要调用mysql_store_result() 或mysql_use_result() ,但是如果在任何情况下均调用了mysql_store_result() , 它也不会导致任何伤害或性能降低。通过检查mysql_store_result() 是否返回0 ,可检测查询是否没有结果集 (以后会更多)。
如果希望了解查询是否应返回结果集,可使用mysql_field_count() 进行检查。请参见25.2.3.22节,“mysql_field_count()” 。
mysql_store_result() 将查询的全部结果读取到客户端, 分配1 个MYSQL_RES 结构, 并将结果置于该结构中。
如果查询未返回结果集,mysql_store_result() 将返回Null 指针(例如,如果查询是INSERT 语句 )。
如果读取结果集失败,mysql_store_result() 还会返回Null 指针。通过检查mysql_error() 是否返回非空字符串,mysql_errno() 是否返回非0 值,或mysql_field_count() 是否返回0 ,可以检查是否出现了错误。
如果未返回行,将返回空的结果集。(空结果集设置不同于作为返回值的空指针)。
一旦调用了mysql_store_result() 并获得了不是Null 指针的结果, 可调用mysql_num_rows() 来找出结果集中的行数。
可以调用mysql_fetch_row() 来获取结果集中的行,或调用mysql_row_seek() 和mysql_row_tell() 来获取或设置结果集中的当前行位置。
一旦完成了对结果集的操作,必须调用mysql_free_result() 。
请参见25.2.13.1节,“为什么在mysql_query()返回成功后,mysql_store_result()有时会返回NULL” .
返回值
具有多个结果的MYSQL_RES 结果集合。如果出现错误,返回NULL 。
错误
如果成功,mysql_store_result() 将 复位mysql_error() 和mysql_errno() 。
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_OUT_OF_MEMORY
内存溢出。
· CR_SERVER_GONE_ERROR
MySQL 服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
25.2.3.68. mysql_use_result()
MYSQL_RES *mysql_use_result(MYSQL *mysql)
描述
对于成功检索数据的每个查询(SELECT 、SHOW 、DESCRIBE 、EXPLAIN ),必须调用mysql_store_result() 或mysql_use_result() 。
mysql_use_result() 将初始化结果集检索,但并不像mysql_store_result() 那样将结果集实际读取到客户端。 它必须通过对mysql_fetch_row() 的调用,对每一行分别进行检索。 这将直接从服务器读取结果,而不会将其保存在临时表或本地缓冲区内,与mysql_store_result() 相比,速度更快而且使用的内存也更少。客户端仅为当前行和通信缓冲区分配内存, 分配的内存可增加到max_allowed_packet 字节。
另一方面,如果你正在客户端一侧为各行进行大量的处理操作,或者将输出发送到了用户可能会键入“^S ”(停止滚动)的屏幕,就不应使用mysql_use_result() 。这会绑定服务器,并阻止其他线程更新任何表(数据从这类表获得)。
使用mysql_use_result() 时,必须执行mysql_fetch_row() ,直至返回NULL 值,否则,未获取的行将作为下一个检索的一部分返回。 C API 给出命令不同步错误,如果忘记了执行该操作,将不能运行该命令。
不应与从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() 。
使用libmysqld 嵌入式服务器时,由于在调用mysql_free_result() 之前,内存使用将随着每个检索的行增加,内存 效益将基本丧失。
返回值
MYSQL_RES 结果结构。如果出现错误,返回NULL 。
错误
如果成功,mysql_use_result() 将复位mysql_error() 和mysql_errno() 。
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_OUT_OF_MEMORY
内存溢出。
· CR_SERVER_GONE_ERROR
MySQL 服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
http://dev.mysql.com/doc/refman/5.1/zh/apis.html#mysql-affected-rows