MySQL 8.0 C API 开发者指南  / 第 5 章 C API 基本接口  /  5.2 C API 基本数据结构

5.2 C API 基本数据结构

本节介绍 C API 数据结构,而不是用于准备语句、异步接口或复制流接口的数据结构。有关这些的信息,请参阅 第 6.2 节“C API 准备语句数据结构”第 7.2 节“C API 异步接口数据结构”第 10.2 节“C API 二进制日志数据结构”

  • MYSQL

    此结构表示一个数据库连接的处理程序。它用于几乎所有的 MySQL 函数。不要试图复制MYSQL结构。不保证此类副本可用。

  • MYSQL_RES

    此结构表示返回行 ( SELECT, SHOW, DESCRIBE, EXPLAIN) 的查询结果。从查询返回的信息在本节的其余部分称为结果集

  • MYSQL_ROW

    这是一行数据的类型安全表示。它目前被实现为一个计数字节字符串的数组。(如果字段值可能包含二进制数据,则不能将它们视为以空字符结尾的字符串,因为此类值可能在内部包含空字节。)通过调用 mysql_fetch_row().

  • MYSQL_FIELD

    此结构包含元数据:有关字段的信息,例如字段的名称、类型和大小。本节稍后将更详细地描述其成员。您可以通过 重复MYSQL_FIELD调用来获取每个字段的结构。mysql_fetch_field()字段值不是该结构的一部分;它们包含在一个MYSQL_ROW结构中。

  • MYSQL_FIELD_OFFSET

    这是 MySQL 字段列表中偏移量的类型安全表示。(由 mysql_field_seek(). 使用)偏移量是一行中的字段编号,从零开始。

  • my_ulonglong

    用于 64 位无符号整数的类型。该 my_ulonglong类型在 MySQL 8.0.18 之前使用。从 MySQL 8.0.18 开始,改用 uint64_tC 类型。

  • my_bool

    布尔类型,用于值为真(非零)或假(零)。该my_bool类型在 MySQL 8.0 之前使用。从 MySQL 8.0 开始,改用boolintC 类型。

    笔记

    my_bool到 的变化bool意味着 mysql.h头文件需要 C++ 或 C99 编译器才能编译。

MYSQL_FIELD结构包含以下列表中描述的成员。这些定义主要适用于结果集的列,例如由 SELECT语句生成的列。 MYSQL_FIELD结构还用于为使用准备好的语句 执行的存储过程 提供元数据OUT和返回的参数。对于此类参数,某些结构成员的含义与列值的含义不同。 INOUTCALL

小费

要以交互方式查看MYSQL_FIELD结果集的成员值,请使用该选项调用mysql 命令 --column-type-info并执行一些示例查询。

  • char * name

    字段的名称,以 null 结尾的字符串。如果该字段被赋予了一个带AS子句的别名,则该字段的值name就是该别名。对于过程参数,参数名称。

  • char * org_name

    字段的名称,以 null 结尾的字符串。别名将被忽略。对于表达式,该值为空字符串。对于过程参数,参数名称。

  • char * table

    包含此字段的表的名称(如果它不是计算字段)。对于计算字段,该 table值为空字符串。如果列是从视图中选择的,则table命名该视图。如果表或视图被赋予了一个带有 AS子句的别名,则 的值 table就是别名。对于 a UNION,该值为空字符串。对于过程参数,过程名称。

  • char * org_table

    表的名称,以 null 结尾的字符串。别名将被忽略。如果列是从视图中选择的,则 org_table命名该视图。如果列是从派生表中选择的,则org_table 命名基表。如果派生表包装视图, org_table仍会命名基表。如果列是表达式,org_table则为空字符串。对于 a UNION,该值为空字符串。对于过程参数,该值是过程名称。

  • char * db

    该字段来自的数据库的名称,以 null 结尾的字符串。如果该字段是计算字段, db则为空字符串。对于 a UNION,该值为空字符串。对于过程参数,包含过程的数据库的名称。

  • char * catalog

    目录名称。该值始终为 "def".

  • char * def

    此字段的默认值,以 null 结尾的字符串。仅当您使用 mysql_list_fields().

  • unsigned long length

    字段的宽度。这对应于显示长度,以字节为单位。

    服务器length在生成结果集之前确定该值,因此这是能够保存结果列中最大可能值的数据类型所需的最小长度,而无需事先知道查询将生成的实际值结果集。

    对于字符串列,该length值因连接字符集而异。例如,如果字符集是latin1,单字节字符集,则查询length值为SELECT 'abc'3。如果字符集是 utf8mb4,字符最多占 4 个字节的多字节字符集,则length 值为 12。

  • unsigned long max_length

    结果集字段的最大宽度(结果集中实际行的最长字段值的字节长度)。如果您使用 mysql_store_result()or mysql_list_fields(),这将包含该字段的最大长度。如果使用 mysql_use_result(),则此变量的值为零。

    的值max_length是结果集中值的字符串表示形式的长度。例如,如果您检索一 FLOAT列并且 最宽值为-12.345max_length则为 7(的长度 '-12.345')。

    如果您使用的是准备好的语句, max_length默认情况下不会设置,因为对于二进制协议,值的长度取决于结果集中值的类型。(请参阅 第 6.2 节,“C API 准备语句数据结构”。)如果您仍然需要这些max_length值,请启用该STMT_ATTR_UPDATE_MAX_LENGTH 选项, mysql_stmt_attr_set()并且将在您调用时设置长度 mysql_stmt_store_result()。(参见第 6.4.3 节,“mysql_stmt_attr_set()”第 6.4.28 节,“mysql_stmt_store_result()”。)

  • unsigned int name_length

    的长度name

  • unsigned int org_name_length

    的长度org_name

  • unsigned int table_length

    的长度table

  • unsigned int org_table_length

    的长度org_table

  • unsigned int db_length

    的长度db

  • unsigned int catalog_length

    的长度catalog

  • unsigned int def_length

    的长度def

  • unsigned int flags

    描述字段的位标志。该 flags值可能具有下表中所示的零个或多个位集。

    标志值 标志说明
    NOT_NULL_FLAG 字段不能NULL
    PRI_KEY_FLAG 字段是主键的一部分
    UNIQUE_KEY_FLAG 字段是唯一键的一部分
    MULTIPLE_KEY_FLAG 字段是非唯一键的一部分
    UNSIGNED_FLAG 字段具有UNSIGNED属性
    ZEROFILL_FLAG 字段具有ZEROFILL属性
    BINARY_FLAG 字段具有BINARY属性
    AUTO_INCREMENT_FLAG 字段具有AUTO_INCREMENT属性
    ENUM_FLAG 字段是一个ENUM
    SET_FLAG 字段是一个SET
    BLOB_FLAG 字段是一个BLOBTEXT(已弃用)
    TIMESTAMP_FLAG 字段是TIMESTAMP(已弃用)
    NUM_FLAG 字段是数字;请参阅下表的附加说明
    NO_DEFAULT_VALUE_FLAG 字段没有默认值;请参阅下表的附加说明

    其中一些标志指示数据类型信息,并被 稍后描述 的成员中的值取代或结合使用:MYSQL_TYPE_xxxfield->type

    • 要检查BLOBor TIMESTAMP值,请检查是否typeMYSQL_TYPE_BLOBor MYSQL_TYPE_TIMESTAMP。( 不需要BLOB_FLAGTIMESTAMP_FLAG标志。)

    • ENUM值以 SET字符串形式返回。对于这些,检查type 值是否MYSQL_TYPE_STRINGENUM_FLAGor SET_FLAG标志是否设置在 flags值中。

    NUM_FLAG表示列是数字的。这包括类型为 MYSQL_TYPE_DECIMAL, MYSQL_TYPE_NEWDECIMAL, MYSQL_TYPE_TINY, MYSQL_TYPE_SHORT, MYSQL_TYPE_LONG, MYSQL_TYPE_FLOAT, MYSQL_TYPE_DOUBLE, MYSQL_TYPE_NULL, MYSQL_TYPE_LONGLONG, MYSQL_TYPE_INT24和 的列MYSQL_TYPE_YEAR

    NO_DEFAULT_VALUE_FLAG指示列DEFAULT在其定义中没有子句。这不适用于NULL 列(因为此类列的默认值为 NULL)或 AUTO_INCREMENT列(具有隐含的默认值)。

    以下示例说明了该 flags值的典型用法:

    if (field->flags & NOT_NULL_FLAG)
        printf("Field cannot be null\n");

    您可以使用下表中显示的便捷宏来确定值的布尔状态 flags

    标记状态 描述
    IS_NOT_NULL(flags) 如果此字段定义为,则为真NOT NULL
    IS_PRI_KEY(flags) 如果此字段是主键,则为真
    IS_BLOB(flags) 如果此字段是BLOBor 则为真TEXT(已弃用; field->type改为测试)
  • unsigned int decimals

    数字字段的小数位数,以及时间字段的小数秒精度。

  • unsigned int charsetnr

    指示字段的字符集/归类对的 ID 号。

    通常,结果集中的字符值会转换为 character_set_results系统变量指示的字符集。在这种情况下,charsetnr 对应于该变量指示的字符集。可以通过设置为来抑制字符集 character_set_results转换 NULL。在这种情况下, charsetnr对应于原始表列或表达式的字符集。另请参阅 连接字符集和排序规则

    字符串数据类型区分二进制数据和非二进制数据,检查charsetnr 值是否为63。如果是,则字符集为 binary,表示二进制数据而不是非二进制数据。这使您能够区分 BINARYfrom CHARVARBINARYfrom VARCHAR以及 BLOB类型与 TEXT类型。

    charsetnr值与报表列或 表列 Id中 显示的值相同。您可以使用这些信息源来查看哪些字符集和排序规则特定值指示: SHOW COLLATIONIDINFORMATION_SCHEMA COLLATIONScharsetnr

    mysql> SHOW COLLATION WHERE Id = 63;
    +-----------+---------+----+---------+----------+---------+
    | Collation | Charset | Id | Default | Compiled | Sortlen |
    +-----------+---------+----+---------+----------+---------+
    | binary    | binary  | 63 | Yes     | Yes      |       1 |
    +-----------+---------+----+---------+----------+---------+
    
    mysql> SELECT COLLATION_NAME, CHARACTER_SET_NAME
           FROM INFORMATION_SCHEMA.COLLATIONS WHERE ID = 33;
    +-----------------+--------------------+
    | COLLATION_NAME  | CHARACTER_SET_NAME |
    +-----------------+--------------------+
    | utf8_general_ci | utf8               |
    +-----------------+--------------------+
  • enum enum_field_types type

    字段的类型。该type值可以是MYSQL_TYPE_下表中显示的符号之一。

    类型值 类型 描述
    MYSQL_TYPE_TINY TINYINT场地
    MYSQL_TYPE_SHORT SMALLINT场地
    MYSQL_TYPE_LONG INTEGER场地
    MYSQL_TYPE_INT24 MEDIUMINT场地
    MYSQL_TYPE_LONGLONG BIGINT场地
    MYSQL_TYPE_DECIMAL DECIMALNUMERIC字段
    MYSQL_TYPE_NEWDECIMAL 精密数学DECIMALNUMERIC
    MYSQL_TYPE_FLOAT FLOAT场地
    MYSQL_TYPE_DOUBLE DOUBLEREAL字段
    MYSQL_TYPE_BIT BIT场地
    MYSQL_TYPE_TIMESTAMP TIMESTAMP场地
    MYSQL_TYPE_DATE DATE场地
    MYSQL_TYPE_TIME TIME场地
    MYSQL_TYPE_DATETIME DATETIME场地
    MYSQL_TYPE_YEAR YEAR场地
    MYSQL_TYPE_STRING CHARBINARY字段
    MYSQL_TYPE_VAR_STRING VARCHARVARBINARY字段
    MYSQL_TYPE_BLOB BLOBTEXT字段(用于 max_length确定最大长度)
    MYSQL_TYPE_SET SET场地
    MYSQL_TYPE_ENUM ENUM场地
    MYSQL_TYPE_GEOMETRY 空间场
    MYSQL_TYPE_NULL NULL-类型字段

    MYSQL_TYPE_TIME2MYSQL_TYPE_DATETIME2) MYSQL_TYPE_TIMESTAMP2类型代码仅在服务器端使用。客户看到 MYSQL_TYPE_TIMEMYSQL_TYPE_DATETIMEMYSQL_TYPE_TIMESTAMP代码。

    您可以使用IS_NUM()宏来测试字段是否具有数字类型。type将值传递 给IS_NUM() ,如果字段是数字,它的计算结果为 TRUE:

    if (IS_NUM(field->type))
        printf("Field is numeric\n");

    ENUM值以 SET字符串形式返回。对于这些,检查type 值是否MYSQL_TYPE_STRINGENUM_FLAGorSET_FLAG 标志是否设置在flags值中。