27.7.8 C API 准备的语句数据结构

• 27 .7.8.1 C API 准备的语句类型代码

• 27 .7.8.2 C API 准备的语句类型转换

准备好的语句使用几种数据结构：

• 要获取语句处理程序，请将MYSQL连接处理程序传递给mysql_stmt_init()，该处理程序将返回指向MYSQL_STMT数据结构的指针。该结构用于该语句的进一步操作。要指定要准备的语句，请将MYSQL_STMT指针和语句字符串传递给mysql_stmt_prepare()。

• 要为准备好的语句提供 Importing 参数，请设置MYSQL_BIND结构并将其传递给mysql_stmt_bind_param()。要接收输出列的值，请设置MYSQL_BIND结构并将其传递给mysql_stmt_bind_result()。

• MYSQL_TIME结构用于在两个方向上传输时间数据。

以下讨论详细描述了准备好的语句数据类型。有关显示如何使用它们的示例，请参见第 27.7.10.10 节，“ mysql_stmt_execute()”和第 27.7.10.11 节“ mysql_stmt_fetch()”。

• MYSQL_STMT

此结构是预处理语句的处理程序。通过调用mysql_stmt_init()创建处理程序，该处理程序返回指向MYSQL_STMT的指针。该处理程序将用于该语句的所有后续操作，直到您用mysql_stmt_close()将其关闭为止，这时该处理程序将变为无效并且不应再使用。

MYSQL_STMT结构没有供应用程序使用的成员。应用程序不应尝试复制MYSQL_STMT结构。不能保证这样的副本将可用。

多个语句处理程序可以与单个连接关联。处理程序数量的限制取决于可用的系统资源。

• MYSQL_BIND

此结构用于语句 Importing(发送到服务器的数据值)和输出(从服务器返回的结果值)：

• 对于 Importing，请将MYSQL_BIND结构与mysql_stmt_bind_param()结合使用，以将参数数据值绑定到由mysql_stmt_execute()使用的缓冲区。

  • 对于输出，请使用带有_的MYSQL_BIND结构将缓冲区绑定到结果集列，以用于通过mysql_stmt_fetch()获取行。

要使用MYSQL_BIND结构，请将其内容清零以对其进行初始化，然后适当地设置其成员。例如，要声明和初始化三个MYSQL_BIND结构的数组，请使用以下代码：

MYSQL_BIND bind[3];
memset(bind, 0, sizeof(bind));

MYSQL_BIND结构包含以下供应用程序使用的成员。对于几个成员，使用方式取决于该结构是用于 Importing 还是用于输出。

• enum enum_field_types buffer_type

缓冲区的类型。该成员指示绑定到语句参数或结果集列的 C 语言变量的数据类型。对于 Importing，buffer_typetable 示包含要发送到服务器的值的变量的类型。对于输出，它指示将从服务器接收的值存储到的变量类型。有关允许的buffer_type值，请参见第 27.7.8.1 节“ C API 准备的语句类型代码”。

• void *buffer

指向用于数据传输的缓冲区的指针。这是 C 语言变量的地址。

对于 Importing，buffer是指向变量的指针，您可以在其中存储语句参数的数据值。当您调用mysql_stmt_execute()时，MySQL 使用存储在变量中的值代替语句中相应的参数标记(在语句字符串中用?指定)。

对于输出，buffer是指向要在其中返回结果集列值的变量的指针。当您调用mysql_stmt_fetch()时，MySQL 将结果集当前行中的列值存储在此变量中。呼叫返回时，您可以访问该值。

为了最大程度地减少 MySQL 在 Client 端 C 语言值和服务器 SQL 值之间执行类型转换的需要，请使用类型类似于相应 SQL 值的 C 变量：

• 对于数字数据类型，buffer应该指向正确的数字 C 类型的变量。对于整数变量(对于单字节值，它可以是char；对于较大的值，它可以是整数类型)，还应该通过设置is_unsigned成员来指示该变量是否具有unsigned属性，这将在后面介绍。

  • 对于字符(非二进制)和二进制字符串数据类型，buffer应指向字符缓冲区。

  • 对于日期和时间数据类型，buffer应该指向MYSQL_TIME结构。

有关 C 类型和 SQL 类型之间 Map 的准则以及有关类型转换的说明，请参见第 27.7.8.1 节“ C API 准备的语句类型代码”和第 27.7.8.2 节“ C API 准备的语句类型转换”。

• unsigned long buffer_length

*buffer的实际大小(以字节为单位)。这 table 示可以存储在缓冲区中的最大数据量。对于字符和二进制 C 数据，当与mysql_stmt_bind_param()一起使用以指定 Importing 值时，buffer_length值指定*buffer的长度，或者与mysql_stmt_bind_result()一起使用时buffer_length值指定可以提取到缓冲区中的最大输出数据字节数。

• unsigned long *length

指向unsigned long变量的指针，该变量指示*buffer中存储的数据的实际字节数。 length用于字符或二进制 C 数据。

对于 Importing 参数数据绑定，设置*length以指示*buffer中存储的参数值的实际长度。由mysql_stmt_execute()使用。

对于输出值绑定，当您调用mysql_stmt_fetch()时，MySQL 设置*length。返回值mysql_stmt_fetch()确定如何解释长度：

• 如果返回值为 0，则*lengthtable 示参数值的实际长度。

  • 如果返回值为MYSQL_DATA_TRUNCATED，则*lengthtable 示参数值的非截断长度。在这种情况下，*length和buffer_length的最小值 table 示该值的实际长度。

对于数字和时间数据类型，将忽略length，因为buffer_type值确定数据值的长度。

如果必须在获取返回值之前确定其长度，请参见第 27.7.10.11 节“ mysql_stmt_fetch()”以获得一些策略。

• my_bool *is_null

该成员指向一个my_bool变量，如果值是NULL则为 true，如果不是NULL则为 false。对于 Importing，将*is_null设置为 truetable 示要传递NULL值作为语句参数。

is_null是布尔标量(而不是布尔标量)的“指针”，可以灵活地指定NULL值：

• 如果您的数据值始终为NULL，则在绑定列时将MYSQL_TYPE_NULL用作buffer_type值。其他MYSQL_BIND个成员(包括is_null个)无关紧要。

  • 如果您的数据值始终为NOT NULL，请设置is_null = (my_bool*) 0，然后为要绑定的变量设置其他成员。

  • 在所有其他情况下，请适当设置其他成员，并将is_null设置为my_bool变量的地址。在两次执行之间将该变量的值适当地设置为 true 或 false，以指示相应的数据值分别是NULL或NOT NULL。

对于输出，当您获取一行时，MySQL 根据从语句返回的结果集列值是否为NULL，将is_null指向的值设置为 true 或 false。

• my_bool is_unsigned

该成员适用于数据类型可以为unsigned(char，short int，int，long long int)的 C 变量。如果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明确 table 示带符号性.)

is_unsigned仅适用于 Client 端的 C 语言变量。它在服务器端没有指示相应的 SQL 值的签名。例如，如果使用int变量为BIGINT UNSIGNED列提供值，则is_unsigned应该为 false，因为int是带符号的类型。如果使用unsigned int变量为BIGINT列提供值，则is_unsigned应该为 true，因为unsigned int是无符号类型。 MySQL 会在两个方向上在有符号和无符号值之间执行正确的转换，尽管如果截断结果会发生警告。

• my_bool *error

对于输出，将该成员设置为指向my_bool变量，以在行获取操作之后将参数的截断信息存储在该变量中。启用截断报告后，对于发生截断的参数，mysql_stmt_fetch()返回MYSQL_DATA_TRUNCATED且*error在MYSQL_BIND结构中为 true。截断 table 示丢失符号或有效数字，或者字符串太长而无法放入列中。截断报告默认情况下处于启用状态，但可以通过使用MYSQL_REPORT_DATA_TRUNCATION选项调用mysql_options()来控制。

• MYSQL_TIME

此结构用于直接与服务器之间发送和接收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结构包含下 table 中列出的成员。

Member	Description
unsigned int year	The year
unsigned int month	一年中的月份
unsigned int day	一个月中的某天
unsigned int hour	一天中的时间
unsigned int minute	时分
unsigned int second	分钟
my_bool neg	指示时间是否为负的布尔值标志
unsigned long second_part	秒的小数部分(以微秒为单位)

仅使用MYSQL_TIME结构中适用于给定类型的时间值的那些部分。 year，month和day元素用于DATE，DATETIME和TIMESTAMP值。 hour，minute和second元素用于TIME，DATETIME和TIMESTAMP值。参见第 27.7.16 节，“ C API 准备好的日期和时间值的语句处理”。