const char *mysql_stmt_sqlstate(MYSQL_STMT *stmt)
描述
对于由stmt指定的语句,mysql_stmt_sqlstate()返回由Null终结的字符串,该字符串包含针对最近调用预处理语句API函数的SQLSTATE错误代码,该函数或成功或失败。错误代码由5个字符构成。"00000"表示“无错误”。这些值由ANSI SQL和ODBC指定。关于可能值的列表,请参见附录B:错误代码和消息。
注意,并非所有的MySQL错误均会被映射到SQLSTATE代码。值"HY000"(一般错误)用于未映射的错误。
返回值
包含SQLSTATE错误代码、由Null终结的字符串。
my_bool mysql_stmt_send_long_data(MYSQL_STMT *stmt, unsigned int parameter_number, const char *data, unsigned long length)
描述
允许应用程序分段地(分块)将参数数据发送到服务器。可以多次调用该函数,以便发送关于某一列的字符或二进制数据的不同部分,列必须是TEXT或BLOB数据类型之一。
“parameter_number”指明了与数据关联的参数。参数从0开始编号。“data”是指向包含将要发送的数据的缓冲区的指针,“length”指明了缓冲区内的字节数。
注释:自上一个mysql_stmt_execute()或mysql_stmt_reset()后,对于与mysql_stmt_send_long_data()一起使用的所有参数,下一个mysql_stmt_execute()调用将忽略绑定缓冲。
如果希望复位/忽略已发送的数据,可使用mysql_stmt_reset()。请参见25.2.7.21节,“mysql_stmt_reset()”。
返回值
如果成功地将数据发送到服务器,返回0。如果出现错误,返回非0值。
错误
? CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
? CR_SERVER_GONE_ERROR
MySQL服务器不可用。
? CR_OUT_OF_MEMORY
内存溢出。
? CR_UNKNOWN_ERROR
出现未知错误。
示例:
在下面的示例中,介绍了以信息块形式为TEXT列发送数据的方法。它会将数据值“MySQL,最流行的开放源码数据库”插入到text_column列中。假定mysql变量具有有效的连接句柄。
#define INSERT_QUERY "INSERT INTO test_long_data(text_column) VALUES(?)"
MYSQL_BIND bind[1];
long length;
smtt = mysql_stmt_init(mysql);
if (!stmt)
{
fprintf(stderr, " mysql_stmt_init(), out of memory\\n");
exit(0);
}
if (mysql_stmt_prepare(stmt, INSERT_QUERY, strlen(INSERT_QUERY)))
{
fprintf(stderr, "\\n mysql_stmt_prepare(), INSERT failed");
fprintf(stderr, "\\n %s", mysql_stmt_error(stmt));
exit(0);
}
memset(bind, 0, sizeof(bind));
bind[0].buffer_type= MYSQL_TYPE_STRING;
bind[0].length= &length;
bind[0].is_null= 0;
if (mysql_stmt_bind_param(stmt, bind))
{
fprintf(stderr, "\\n param bind failed");
fprintf(stderr, "\\n %s", mysql_stmt_error(stmt));
exit(0);
}
if (!mysql_stmt_send_long_data(stmt,0,"MySQL",5))
{
fprintf(stderr, "\\n send_long_data failed");
fprintf(stderr, "\\n %s", mysql_stmt_error(stmt));
exit(0);
}
if (mysql_stmt_send_long_data(stmt,0," - The most popular Open Source database",40))
{
fprintf(stderr, "\\n send_long_data failed");
fprintf(stderr, "\\n %s", mysql_stmt_error(stmt));
exit(0);
}
if (mysql_stmt_execute(stmt))
{
fprintf(stderr, "\\n mysql_stmt_execute failed");
fprintf(stderr, "\\n %s", mysql_stmt_error(stmt));
exit(0);
}
MYSQL_ROW_OFFSET mysql_stmt_row_tell(MYSQL_STMT *stmt)
描述
返回针对前一个mysql_stmt_fetch()的行光标的当前位置。该值可用作mysql_stmt_row_seek()的参量。
仅应在mysql_stmt_store_result()之后使用mysql_stmt_row_tell()。
返回值
行光标的当前偏移量。
错误
无。
MYSQL_ROW_OFFSET mysql_stmt_row_seek(MYSQL_STMT *stmt, MYSQL_ROW_OFFSET offset)
描述
将行光标设置到语句结果集中的任意行。“offset”值是行偏移的值,行偏移应是从mysql_stmt_row_tell()或mysql_stmt_row_seek()返回的值。该值不是行编号,如果打算按编号查找结果集中的行,可使用mysql_stmt_data_seek()取而代之。
该函数要求结果集结构包含查询的全部结果,以便mysql_stmt_row_seek()能够仅与mysql_stmt_store_result()一起使用。
返回值
行光标的前一个值。可以将该值换递给后续的mysql_stmt_row_seek()调用。
错误
无。
MYSQL_RES *mysql_stmt_result_metadata(MYSQL_STMT *stmt)
描述
如果传递给mysql_stmt_prepare()的语句能够成生结果集,mysql_stmt_result_metadata()将以指针的形式返回结果集元数据,该指针指向MYSQL_RES结构,可用于处理元信息,如总的字段数以及单独的字段信息。该结果集指针可作为参量传递给任何基于字段且用于处理结果集元数据的API函数,如:
? mysql_num_fields()
? mysql_fetch_field()
? mysql_fetch_field_direct()
? mysql_fetch_fields()
? mysql_field_count()
? mysql_field_seek()
? mysql_field_tell()
? mysql_free_result()
完成操作后,应释放结果集结构,可通过将其传递给mysql_free_result()完成。它与释放通过mysql_store_result()调用获得的结果集的方法类似。
mysql_stmt_result_metadata()返回的结果集仅包含元数据。不含任何行结果。与mysql_stmt_fetch()一起使用语句句柄,可获取行。
返回值
MYSQL_RES结果结构。如果不存在关于预处理查询的任何元信息,返回NULL。
错误
? CR_OUT_OF_MEMORY
内存溢出。
? CR_UNKNOWN_ERROR
出现未知错误。
示例:
关于mysql_stmt_result_metadata()的用法,请参见25.2.7.11节,“mysql_stmt_fetch()”中给出的示例。
my_bool mysql_stmt_reset(MYSQL_STMT *stmt)
描述
在客户端和服务器上,将预处理语句复位为完成准备后的状态。主要用于复位用mysql_stmt_send_long_data()发出的数据。对于语句,任何已打开的光标将被关闭。
要想重新准备用于另一查询的语句,可使用mysql_stmt_prepare()。
返回值
如果语句成功复位,返回0。如果出现错误,返回非0值。
错误
? CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
? CR_SERVER_GONE_ERROR
MySQL服务器不可用。
? CR_SERVER_LOST
查询过程中,与服务器的连接丢失。
? CR_UNKNOWN_ERROR
出现未知错误。
int mysql_stmt_prepare(MYSQL_STMT *stmt, const char *query, unsigned long length)
描述
给定mysql_stmt_init()返回的语句句柄,准备字符串查询指向的SQL语句,并返回状态值。字符串长度应由“length”参量给出。字符串必须包含1条SQL语句。不应为语句添加终结用分号(‘;’)或\\g。
通过将问号字符“?”嵌入到SQL字符串的恰当位置,应用程序可包含SQL语句中的一个或多个参数标记符。
标记符仅在SQL语句中的特定位置时才是合法的。例如,它可以在INSERT语句的VALUES()列表中(为行指定列值),或与WHERE子句中某列的比较部分(用以指定比较值)。但是,对于ID(例如表名或列名),不允许使用它们,不允许指定二进制操作符(如等于号“=”)的操作数。后一个限制是有必要的,原因在于,无法确定参数类型。一般而言,参数仅在DML(数据操作语言)语句中才是合法的,在DDL(数据定义语言)语句中不合法。
执行语句之前,必须使用mysql_stmt_bind_param(),将参数标记符与应用程序变量绑定在一起。
返回值
如果成功处理了语句,返回0。如果出现错误,返回非0值。
错误
? CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
? CR_OUT_OF_MEMORY
内存溢出。
? CR_SERVER_GONE_ERROR
MySQL服务器不可用。
? CR_SERVER_LOST
查询过程中,与服务器的连接丢失。
? CR_UNKNOWN_ERROR
出现未知错误。
如果准备操作失败(即mysql_stmt_prepare()返回非0值),可通过调用mysql_stmt_error()获取错误消息。
示例:
关于mysql_stmt_prepare()的用法,请参见25.2.7.10节,“mysql_stmt_execute()”中给出的示例。
MYSQL_RES *mysql_stmt_param_metadata(MYSQL_STMT *stmt)
该函数目前不做任何事。
描述
返回值
错误
unsigned long mysql_stmt_param_count(MYSQL_STMT *stmt)
描述
返回预处理语句中参数标记符的数目。
返回值
表示语句中参数数目的无符号长整数。
错误
无。
my_ulonglong mysql_stmt_num_rows(MYSQL_STMT *stmt)
描述
返回结果集中的行数。
mysql_stmt_num_rows()的用法取决于是否使用了mysql_stmt_store_result()来对语句句柄中的全部结果集进行了缓冲处理。
如果使用了mysql_stmt_store_result(),可立刻调用mysql_stmt_num_rows()。
返回值
结果集中的行数。
错误
无。
my_ulonglong mysql_stmt_insert_id(MYSQL_STMT *stmt)
描述
返回预处理INSERT或UPDATE语句为AUTO_INCREMENT列生成的值。在包含AUTO_INCREMENT字段的表上执行了预处理INSERT语句后,使用该函数。
更多信息,请参见25.2.3.36节,“mysql_insert_id()”。
返回值
为在执行预处理语句期间自动生成或明确设置的AUTO_INCREMENT列返回值,或由LAST_INSERT_ID(expr)函数生成的值。如果语句未设置AUTO_INCREMENT值,返回值不确定。
错误
无。
MYSQL_STMT *mysql_stmt_init(MYSQL *mysql)
描述
创建MYSQL_STMT句柄。对于该句柄,应使用mysql_stmt_close(MYSQL_STMT *)释放。
返回值
成功时,返回指向MYSQL_STMT结构的指针。如果内存溢出,返回NULL。
错误
? CR_OUT_OF_MEMORY
内存溢出。
my_bool mysql_stmt_free_result(MYSQL_STMT *stmt)
描述
释放与执行预处理语句生成的结果集有关的内存。对于该语句,如果存在打开的光标,mysql_stmt_free_result()将关闭它。
返回值
如果成功释放了结果集,返回0。如果出现错误,返回非0值。
错误
unsigned int mysql_stmt_field_count(MYSQL_STMT *stmt)
描述
为语句处理程序返回关于最近语句的行数。对于诸如INSERT或DELETE等不生成结果集的语句,该值为0。
通过调用mysql_stmt_prepare()准备好了语句后,可调用mysql_stmt_field_count()。
返回值
表示结果集中行数的无符号整数。
错误
无。
int mysql_stmt_fetch_column(MYSQL_STMT *stmt, MYSQL_BIND *bind, unsigned int column, unsigned long offset)
描述
从当前结果集行获取1列。“bind”提供了应将数据置于其中的缓冲。其设置方法应与设置mysql_stmt_bind_result()的相同。“column”指明了将获取哪个列。第1列编号为0。“offset”是数据值内的偏移量,将从该处开始检索数据。可将其用于获取碎片形式的数据值。值开始部分的偏移量为0。
返回值
如果成功获取了值,返回0。如果出现错误,返回非0值。
错误
? CR_INVALID_PARAMETER_NO
Invalid column number.
? CR_NO_DATA
已抵达结果集的末尾。
--转自