MySQL 8.0 C API 开发者指南  / 第 6 章 C API 预处理语句接口  /  6.2 C API 准备语句数据结构

6.2 C API 准备语句数据结构

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

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

  • 要为准备好的语句提供输入参数,请设置 MYSQL_BIND结构并将它们传递给 mysql_stmt_bind_param(). 要接收输出列值,请设置 MYSQL_BIND结构并将它们传递给 mysql_stmt_bind_result().

    MYSQL_BIND结构也与 一起使用 mysql_bind_param(),它可以定义适用于发送到服务器的下一个查询的属性。

  • MYSQL_TIME结构用于双向传输时间数据。

下面的讨论详细描述了准备好的语句数据类型。有关显示如何使用它们的示例,请参阅 第 6.4.10 节,“mysql_stmt_execute()”第 6.4.11 节,“mysql_stmt_fetch()”

  • MYSQL_STMT

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

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

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

  • MYSQL_BIND

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

    • 对于输入,使用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单字节值,也可以是较大值的整数类型),还应该 通过设置成员 来指明该变量是否具有该unsigned属性 ,后面会介绍。is_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的长度,或者与一起使用时可以提取到缓冲区中的最大输出数据字节数 。 *buffermysql_stmt_bind_param()mysql_stmt_bind_result()

    • unsigned long *length

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

      对于输入参数数据绑定,设置 *length为表示存储在参数值中的实际长度 *buffer。这是由 mysql_stmt_execute().

      对于输出值绑定,MySQL *length在您调用时 设置mysql_stmt_fetch()。返回值决定了 mysql_stmt_fetch()如何解释长度:

      • 如果返回值为0,*length 表示参数值的实际长度。

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

      length对于数字和时间数据类型将被忽略,因为该 buffer_type值决定了数据值的长度。

      如果您必须在获取返回值之前确定返回值的长度,请参阅 第 6.4.11 节,“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_nullbool变量的地址。在执行之间适当地将该变量的值设置为 true 或 false 以分别指示相应的数据值是NULL还是 NOT NULL

      对于输出,当你fetch一行时,MySQL会is_null根据语句返回的结果集列值是否是,将by指向的值设置为true或false NULL

    • bool is_unsigned

      该成员适用于数据类型可以是unsigned ( char, short int, int, long long int) 的 C 变量。is_unsigned如果指向的变量buffer是 ,则设置为 true unsigned,否则设置为 false。例如,如果将signed char 变量绑定到buffer,请指定类型代码MYSQL_TYPE_TINY并设置 is_unsigned为 false。如果您 unsigned char改为绑定 an,则类型代码相同但is_unsigned应该为真。(对于char,没有定义它是有符号的还是无符号的,所以最好使用signed charunsigned 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截断表示符号或有效数字丢失,或者字符串太长而无法放入列中。默认情况下启用截断报告,但可以通过 mysql_options()使用 MYSQL_REPORT_DATA_TRUNCATION选项调用来控制。

  • MYSQL_TIME

    此结构用于 直接向服务器发送和接收DATETIMEDATETIME和 数据。TIMESTAMPbuffer成员设置为指向MYSQL_TIME结构,并将结构的buffer_type成员 设置MYSQL_BIND为时间类型之一 ( 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、和 值 。、 和 元素用于 、和 值 。请参阅 第 3.6.4 节,“日期和时间值的准备语句处理”monthdayDATEDATETIMETIMESTAMPhourminutesecondTIMEDATETIMETIMESTAMP