int mysql_stmt_store_result(MYSQL_STMT *stmt)
描述
对于成功生成结果集的所有语句(SELECT、SHOW、DESCRIBE、EXPLAIN),而且仅当你打算对客户端的全部结果集进行缓冲处理时,必须调用mysql_stmt_store_result(),以便后续的mysql_stmt_fetch()调用能返回缓冲数据。
对于其他语句,没有必要调用mysql_stmt_store_result(),但如果调用了它,也不会造成任何伤害或导致任何性能问题。通过检查mysql_stmt_result_metadata()是否返回NULL,可检测语句是否生成了结果集。更多信息,请参见25.2.7.22节,“mysql_stmt_result_metadata()”。
注释:默认情况下,对于mysql_stmt_store_result()中的所有列,MySQL不计算MYSQL_FIELD->max_length,这是因为,计算它会显著降低mysql_stmt_store_result()的性能,而且大多数应用程序不需要max_length。如果打算更新max_length,可通过调用mysql_stmt_attr_set(MYSQL_STMT,
STMT_ATTR_UPDATE_MAX_LENGTH,
&flag)启用它。请参见25.2.7.3节,“mysql_stmt_attr_set()”。
返回值
如果成功完成了对结果的缓冲处理,返回0。如果出现错误,返回非0值。
错误
?
CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
?
CR_OUT_OF_MEMORY
内存溢出。
?
CR_SERVER_GONE_ERROR
MySQL服务器不可用。
?
CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
?
CR_UNKNOWN_ERROR
出现未知错误。
const char *mysql_stmt_error(MYSQL_STMT *stmt)
描述
对于由stmt指定的语句,mysql_stmt_error()返回由Null终结的字符串,该字符串包含最近调用的语句API函数的错误消息,该函数或成功或失败。如果未出现错误,返回空字符串("")。这意味着下述两个测试是等效的:
if (mysql_stmt_errno(stmt))
{
// an error occurred
}
if (mysql_stmt_error(stmt)[0])
{
// an error occurred
}
通过重新编译MySQL客户端库,可更改客户端错误消息的语言。目前,能够选择数种语言之一显示错误消息。
返回值
描述了错误的字符串。如果未出现错误,返回空字符串。
错误
无。
unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)
描述
对于由stmt指定的语句,mysql_stmt_errno()将返回最近调用的语句API函数的错误代码,该函数或成功或失败。“0”返回值表示未出现错误。在MySQL
errmsg.h头文件中列出了客户端错误消息编号。在mysqld_error.h中,列出了服务器错误消息。此外,在附录B:错误代码和消息中,也列出了错误消息。
返回值
错误代码值。如果未出现错误,返回0。
错误
无。
void mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong
offset)
描述
查找语句结果集中的任意行。偏移量为行编号,应位于从0到mysql_stmt_num_rows(stmt)-1的范围内。
该函数要求语句结果集结构包含上次执行查询的全部结果,这样,mysql_stmt_data_seek()就能与mysql_stmt_store_result()一起使用。
返回值
无。
错误
无。
my_bool mysql_stmt_close(MYSQL_STMT *)
描述
关闭预处理语句。此外,mysql_stmt_close()还会取消由“stmt”指向的语句句柄分配。
如果当前语句已挂起或未读取结果,该函数将取消它们,以便能执行下一个查询,
返回值
如果成功释放了语句,返回0。如果出现错误,返回非0值。
错误
?
CR_SERVER_GONE_ERROR
MySQL服务器不可用。
?
CR_UNKNOWN_ERROR
出现未知错误。
my_bool mysql_stmt_bind_result(MYSQL_STMT *stmt,
MYSQL_BIND *bind)
描述
mysql_stmt_bind_result()用于将结果集中的列与数据缓冲和长度缓冲关联(绑定)起来。当调用mysql_stmt_fetch()以获取数据时,MySQL客户端/服务器协议会将绑定列的数据置于指定的缓冲区内。
调用mysql_stmt_fetch()之前,必须将所有列绑定到缓冲。“bind”是MYSQL_BIND结构某一数组的地址。按照客户端库的预期,对于结果集中的每一列,数组应包含相应的元素。如果未将列绑定到MYSQL_BIND结构,mysql_stmt_fetch()将简单地忽略数据获取操作。缓冲区应足够大,足以容纳数据值,这是因为协议不返回成块的数据值。
可以在任何时候绑定或再绑定列,即使已部分检索了结果集后也同样。新的绑定将在下一次调用mysql_stmt_fetch()时起作用。假定某一应用程序绑定了结果集中的列,并调用了mysql_stmt_fetch()。客户端/服务器协议将返回绑定缓冲区中的数据。接下来,假定应用程序将多个列绑定到不同的缓冲。该协议不会将数据置于新绑定的缓冲区,直至下次调用mysql_stmt_fetch()为止。
要想绑定列,应用程序将调用mysql_stmt_bind_result(),并传递类型、地址、以及长度缓冲的地址。在25.2.5节,“C
API预处理语句的数据类型”中,介绍了应设置的各MYSQL_BIND元素的成员。
返回值
如果绑定成功,返回0。如果出现错误,返回非0值。
错误
?
CR_UNSUPPORTED_PARAM_TYPE
不支持该转换。或许buffer_type值是非法的,或不是所支持的类型之一。
?
CR_OUT_OF_MEMORY
内存溢出。
?
CR_UNKNOWN_ERROR
出现未知错误。
my_bool mysql_stmt_bind_param(MYSQL_STMT *stmt, MYSQL_BIND
*bind)
描述
mysql_stmt_bind_param()用于为SQL语句中的参数标记符绑定数据,以传递给mysql_stmt_prepare()。它使用MYSQL_BIND结构来提供数据。“bind”是MYSQL_BIND结构的某一数组的地址。按照客户端库的预期,对于查询中出现的每个“?”参数标记符,数组中均包含1个元素。
假定你准备了下述语句:
INSERT INTO mytbl VALUES(?,?,?)
绑定参数时,MYSQL_BIND结构的数组包含3个元素,并能声明如下:
MYSQL_BIND bind[3];
在25.2.5节,“C
API预处理语句的数据类型”中,介绍了应设置的每个MYSQL_BIND元素的成员。
返回值
如果绑定成功,返回0。如果出现错误,返回非0值。
错误
?
CR_INVALID_BUFFER_USE
指明“bind”(绑定)是否将提供程序块中的长数据,以及缓冲类型是否为非字符串或二进制类型。
?
CR_UNSUPPORTED_PARAM_TYPE
不支持该转换。或许buffer_type值是非法的,或不是所支持的类型之一。
?
CR_OUT_OF_MEMORY
内存溢出。
?
CR_UNKNOWN_ERROR
出现未知错误。
int mysql_stmt_attr_set(MYSQL_STMT *stmt, enum
enum_stmt_attr_type option, const void *arg)
描述
可用于影响预处理语句的行为。可多次调用该函数来设置多个选项。
“option”参量是希望设置的选项,“arg”参量是选项的值。如果“option”是整数,那么“arg”应指向整数的值。
可能的选项值:
选项
参量类型
功能
STMT_ATTR_UPDATE_MAX_LENGTH
my_bool *
如果设为1:更新mysql_stmt_store_result()中的元数据MYSQL_FIELD->max_length。
STMT_ATTR_CURSOR_TYPE
unsigned long *
调用mysql_stmt_execute()时,语句将打开的光标类型。*arg可以是CURSOR_TYPE_NO_CURSOR(默认值)或CURSOR_TYPE_READ_ONLY。
STMT_ATTR_PREFETCH_ROWS
unsigned long *
使用光标时,一次从服务器获取的行数。*arg的范围从1到unsigned
long的最大值。默认值为1。
如果与CURSOR_TYPE_READ_ONLY一起使用了STMT_ATTR_CURSOR_TYPE选项,当调用了mysql_stmt_execute()时,将为语句打开光标。如果存在由前一个mysql_stmt_execute()调用打开的光标,在打开新的光标前,将关闭该光标。此外,为再执行而准备语句之前,mysql_stmt_reset()还将关闭任何打开的光标。mysql_stmt_free_result()将关闭任何打开的光标。
如果为预处理语句打开了光标,没必要调用mysql_stmt_store_result(),这是因为,该函数会导致在客户端一侧对结果集进行缓冲处理。
在MySQL
5.0.2中增加了STMT_ATTR_CURSOR_TYPE选项。在MySQL
5.0.6中,增加了STMT_ATTR_PREFETCH_ROWS选项。
返回值
如果OK,返回0。如果选项未知,返回非0值。
错误
无。
示例:
在下述示例中,为预处理语句打开了1个光标,并将每次获取的行数设为5:
MYSQL_STMT *stmt;
int rc;
unsigned long type;
unsigned long prefetch_rows = 5;
stmt = mysql_stmt_init(mysql);
type = (unsigned long) CURSOR_TYPE_READ_ONLY;
rc = mysql_stmt_attr_set(stmt, STMT_ATTR_CURSOR_TYPE, (void*) &type);
rc = mysql_stmt_attr_set(stmt, STMT_ATTR_PREFETCH_ROWS,
(void*) &prefetch_rows);
int mysql_stmt_attr_get(MYSQL_STMT *stmt, enum enum_stmt_attr_type option, void *arg)
描述
可用于获得语句属性的当前值。
“option”参量是希望获取的选项,“arg”应指向包含选项值的变量。如果“option”是整数,那么“arg”应指向整数的值。
关于选项和选项类型的清单,请参见25.2.7.3节,“mysql_stmt_attr_set()”。
返回值
如果OK,返回0。如果选项未知,返回非0值。
错误
无。
my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)
描述
返回上次执行语句更改、删除或插入的总行数。对于UPDATE、DELETE或INSERT语句,可在mysql_stmt_execute()之后立刻调用它们。对于SELECT语句,mysql_stmt_affected_rows()的工作方式类似于mysql_num_rows()。
返回值
大于0的整数指明了受影响或检索的行数。对于UPDATE语句,“0”表明未更新任何记录,在查询中没有与WHERE子句匹配的行,或尚未执行任何查询。“-1”表明返回了错误,或对SELECT查询,在调用mysql_stmt_store_result()之前调用了mysql_stmt_affected_rows()。由于mysql_stmt_affected_rows()返回无符号值,可通过比较返回值和“(my_ulonglong)-1”(或等效的“(my_ulonglong)~0”),检查“-1”。
关于返回值的额外信息,请参见25.2.3.1节,“mysql_affected_rows()”。
错误
无。