预处理语句使用多种数据结构
要获取语句句柄,将
MYSQL
连接句柄传递给mysql_stmt_init()
,它将返回指向MYSQL_STMT
数据结构的指针。此结构用于语句的后续操作。要指定要准备的语句,将MYSQL_STMT
指针和语句字符串传递给mysql_stmt_prepare()
。-
要为预处理语句提供输入参数,请设置
MYSQL_BIND
结构,并将它们传递给mysql_stmt_bind_param()
或mysql_stmt_bind_named_param()
。要接收输出列值,请设置MYSQL_BIND
结构,并将它们传递给mysql_stmt_bind_result()
。MYSQL_BIND
结构也与mysql_bind_param()
一起使用,它允许定义应用于发送到服务器的下一个查询的属性。 MYSQL_TIME
结构用于双向传输时间数据。
以下讨论详细描述了预处理语句数据类型。有关如何使用它们的示例,请参见 第 6.4.11 节,“mysql_stmt_execute()” 和 第 6.4.12 节,“mysql_stmt_fetch()”。
-
此结构是预处理语句的句柄。句柄通过调用
mysql_stmt_init()
创建,它返回指向MYSQL_STMT
的指针。该句柄用于与该语句的所有后续操作,直到您使用mysql_stmt_close()
关闭它,此时句柄变为无效,不再使用。MYSQL_STMT
结构没有供应用程序使用的成员。应用程序不应尝试复制MYSQL_STMT
结构。无法保证此类副本可用。多个语句句柄可以与单个连接相关联。句柄数量的限制取决于可用的系统资源。
-
此结构用于语句输入(发送到服务器的数据值)和输出(从服务器返回的结果值)
对于输入,使用
MYSQL_BIND
结构与mysql_bind_param()
一起定义查询的属性。(在以下讨论中,将对预处理语句的语句参数的任何提及视为也适用于查询属性。)对于输出,使用
MYSQL_BIND
结构与mysql_stmt_bind_result()
一起将缓冲区绑定到结果集列,以便用于使用mysql_stmt_fetch()
获取行。
要使用
MYSQL_BIND
结构,请将其内容归零以初始化它,然后适当地设置其成员。例如,要声明和初始化三个MYSQL_BIND
结构的数组,请使用以下代码MYSQL_BIND bind[3]; memset(bind, 0, sizeof(bind));
MYSQL_BIND
结构包含以下供应用程序使用的成员。对于多个成员,使用方式取决于结构是用于输入还是输出。-
enum enum_field_types buffer_type
缓冲区的类型。此成员指示绑定到语句参数或结果集列的 C 语言变量的数据类型。对于输入,
buffer_type
指示包含要发送到服务器的值的变量的类型。对于输出,它指示应将从服务器接收的值存储到的变量的类型。有关允许的buffer_type
值,请参见 第 6.2.1 节,“C API 预处理语句类型代码”。 -
void *buffer
指向要用于数据传输的缓冲区的指针。这是 C 语言变量的地址。
对于输入,
buffer
是指向存储语句参数数据的变量的指针。当您调用mysql_stmt_execute()
时,MySQL 将使用存储在该变量中的值来替换语句中相应的参数标记(在语句字符串中使用?
指定)。对于输出,
buffer
是指向要返回结果集列值的变量的指针。当您调用mysql_stmt_fetch()
时,MySQL 将从结果集的当前行中存储列值到该变量。在调用返回时,您可以访问该值。为了最大程度地减少 MySQL 在客户端的 C 语言值和服务器端的 SQL 值之间执行类型转换的必要性,请使用类型类似于相应的 SQL 值的 C 变量
对于数字数据类型,
buffer
应该指向具有正确的数字 C 类型的变量。对于整数变量(对于单字节值可以是char
,对于较大的值可以是整数类型),您还应该通过设置is_unsigned
成员来指示该变量是否具有unsigned
属性,该成员将在后面描述。对于字符(非二进制)和二进制字符串数据类型,
buffer
应该指向字符缓冲区。对于日期和时间数据类型,
buffer
应该指向MYSQL_TIME
结构。
有关 C 类型和 SQL 类型之间映射的指南以及有关类型转换的说明,请参见 第 6.2.1 节,“C API 预处理语句类型代码” 和 第 6.2.2 节,“C API 预处理语句类型转换”。
-
unsigned long buffer_length
*buffer
的实际大小(以字节为单位)。这指示可以存储在缓冲区中的最大数据量。对于字符和二进制 C 数据,buffer_length
值指定*buffer
的长度(与mysql_stmt_bind_param()
或mysql_stmt_bind_named_param()
一起使用以指定输入值时),或指定使用mysql_stmt_bind_result()
时可以获取到缓冲区的最大输出数据字节数。 -
unsigned long *length
指向
unsigned long
变量的指针,该变量指示存储在*buffer
中的实际数据字节数。length
用于字符或二进制 C 数据。对于输入参数数据绑定,请设置
*length
以指示存储在*buffer
中的参数值的实际长度。这由mysql_stmt_execute()
使用。对于输出值绑定,MySQL 在您调用
mysql_stmt_fetch()
时设置*length
。mysql_stmt_fetch()
的返回值决定如何解释长度如果返回值为 0,则
*length
指示参数值的实际长度。如果返回值为
MYSQL_DATA_TRUNCATED
,则*length
指示参数值的未截断长度。在这种情况下,*length
和buffer_length
的最小值指示值的实际长度。
length
对于数字和时间数据类型被忽略,因为buffer_type
值决定数据值的长度。如果您必须在获取返回值之前确定其长度,请参见 第 6.4.12 节,“mysql_stmt_fetch()”,了解一些策略。
-
bool *is_null
此成员指向一个
bool
变量,如果一个值为NULL
,则该变量为真,如果它不是NULL
,则该变量为假。对于输入,将*is_null
设置为 true 以指示您正在传递NULL
值作为语句参数。is_null
是指向布尔标量的 指针,而不是布尔标量,以提供指定NULL
值的灵活性如果您的数据值始终为
NULL
,则在绑定列时将MYSQL_TYPE_NULL
用作buffer_type
值。其他MYSQL_BIND
成员(包括is_null
)无关紧要。如果您的数据值始终为
NOT NULL
,请设置is_null = (bool*) 0
,并为要绑定的变量相应地设置其他成员。在所有其他情况下,请相应地设置其他成员,并将
is_null
设置为bool
变量的地址。在执行之间将该变量的值相应地设置为 true 或 false,以指示对应的数据值分别为NULL
或NOT NULL
。
对于输出,在您获取一行时,MySQL 会根据从语句返回的结果集列值是否为
NULL
,将is_null
指向的值设置为 true 或 false。 -
bool is_unsigned
此成员适用于数据类型可以为
unsigned
的 C 变量(char
、short int
、int
、long long int
)。如果buffer
指向的变量为unsigned
,则将is_unsigned
设置为 true,否则设置为 false。例如,如果将signed char
变量绑定到buffer
,请指定类型代码MYSQL_TYPE_TINY
并将is_unsigned
设置为 false。如果您改为绑定unsigned char
,则类型代码相同,但is_unsigned
应为 true。(对于char
,未定义它是有符号还是无符号,因此最好通过使用signed char
或unsigned char
来明确符号。)is_unsigned
仅适用于客户端的 C 语言变量。它不指示服务器端对应 SQL 值的符号。例如,如果您使用int
变量为BIGINT UNSIGNED
列提供值,则is_unsigned
应为 false,因为int
是有符号类型。如果您使用unsigned int
变量为BIGINT
列提供值,则is_unsigned
应为 true,因为unsigned int
是无符号类型。MySQL 会在两个方向上执行有符号值和无符号值之间的正确转换,尽管如果发生截断,将会发出警告。 -
bool *error
对于输出,将此成员设置为指向
bool
变量,以在行获取操作后将参数的截断信息存储在该变量中。当启用截断报告时,mysql_stmt_fetch()
返回MYSQL_DATA_TRUNCATED
,并且*error
在发生截断的参数的MYSQL_BIND
结构中为 true。截断表示符号或有效数字丢失,或者字符串过长而无法放入列中。默认情况下启用截断报告,但可以通过使用MYSQL_REPORT_DATA_TRUNCATION
选项调用mysql_options()
来控制它。
-
此结构用于直接将
DATE
、TIME
、DATETIME
和TIMESTAMP
数据发送到服务器和从服务器接收。将buffer
成员设置为指向MYSQL_TIME
结构,并将MYSQL_BIND
结构的buffer_type
成员设置为时间类型之一(MYSQL_TYPE_TIME
、MYSQL_TYPE_DATE
、MYSQL_TYPE_DATETIME
、MYSQL_TYPE_TIMESTAMP
)。MYSQL_TIME
结构包含下表中列出的成员。成员 描述 unsigned int year
年份 unsigned int month
月份 unsigned int day
日 unsigned int hour
小时 unsigned int minute
分钟 unsigned int second
秒 bool neg
指示时间是否为负的布尔标志 unsigned long second_part
以微秒为单位的秒的小数部分 仅使用适用于给定时间值类型的
MYSQL_TIME
结构的那些部分。year
、month
和day
元素用于DATE
、DATETIME
和TIMESTAMP
值。hour
、minute
和second
元素用于TIME
、DATETIME
和TIMESTAMP
值。请参阅 第 3.6.4 节,“准备好的语句处理日期和时间值”。