API динамических столбцов

Эта страница описывает API клиентской части для чтения и записи блобов динамических столбцов.

Обычно следует использовать функции динамических столбцов, которые выполняются внутри сервера MariaDB и позволяют получить доступ к содержимому динамических столбцов без каких-либо клиентских библиотек.

Если по какой-либо причине вам необходимо читать/записывать блоки динамических столбцов на клиенте, этот API предоставляет такую возможность.

Где получить

API является частью libmysql библиотеки клиента C. Для его использования необходимо включить этот заголовочный файл

#include <mysql/ma_dyncol.h>

и связать его с libmysql.

Структуры данных

DYNAMIC_COLUMN

DYNAMIC_COLUMN представляет собой упакованный блок динамического столбца. По сути, это строка с длиной, определенная следующим образом:

/* A generic-purpose arbitrary-length string defined in MySQL Client API */
typedef struct st_dynamic_string
{
  char *str;
  size_t length,max_length,alloc_increment;
} DYNAMIC_STRING;

...

typedef DYNAMIC_STRING DYNAMIC_COLUMN;

DYNAMIC_COLUMN_VALUE

Блок динамических столбцов хранит пары {имя, значение}. Для представления значения в доступной форме используется структура DYNAMIC_COLUMN_VALUE.

struct st_dynamic_column_value
{
  DYNAMIC_COLUMN_TYPE type;
  union
  {
    long long long_value;
    unsigned long long ulong_value;
    double double_value;
    struct {
      MYSQL_LEX_STRING value;
      CHARSET_INFO *charset;
    } string;
    struct {
      decimal_digit_t buffer[DECIMAL_BUFF_LENGTH];
      decimal_t value;
    } decimal;
    MYSQL_TIME time_value;
  } x;
};
typedef struct st_dynamic_column_value DYNAMIC_COLUMN_VALUE;

Каждое значение имеет тип, который определяется членом type.

Примечания

• Значения с типом DYN_COL_NULL никогда не встречаются в блоках динамических столбцов.
• Тип DYN_COL_DYNCOL означает, что значение является упакованным динамическим блоком. Именно так реализуются вложенные динамические столбцы.
• Перед сохранением значения в value.x.decimal.value, необходимо вызвать mariadb_dyncol_prepare_decimal() для инициализации места хранения.

enum_dyncol_func_result

enum enum_dyncol_func_result используется в качестве возвращаемого значения.

Код результата, меньший нуля, представляет собой условия ошибки.

Справочник по функциям

Функции представлены парами:

• xxx() работает со старым (до MariaDB-10.0.1) форматом блоков динамических столбцов, где столбцы идентифицируются по номерам.
• xxx_named() может работать как со старым, так и с новым форматом данных. Если она изменяет блок, она преобразует его в новый формат данных.

Следует использовать функции xxx_named(), если нет необходимости сохранять совместимость данных с версиями MariaDB до 10.0.1.

mariadb_dyncol_create_many

Создает упакованный динамический блок из массивов значений и имён.

enum enum_dyncol_func_result
mariadb_dyncol_create_many(DYNAMIC_COLUMN *str,
                           uint column_count,
                           uint *column_numbers,
                           DYNAMIC_COLUMN_VALUE *values,
                           my_bool new_string);
enum enum_dyncol_func_result
mariadb_dyncol_create_many_named(DYNAMIC_COLUMN *str,
                                 uint column_count,
                                 MYSQL_LEX_STRING *column_keys,
                                 DYNAMIC_COLUMN_VALUE *values,
                                 my_bool new_string);

где

mariadb_dyncol_update_many

Добавляет или обновляет столбцы в блоке динамических столбцов. Для удаления столбца обновите его значение до «нет значения» типа DYN_COL_NULL

enum enum_dyncol_func_result
mariadb_dyncol_update_many(DYNAMIC_COLUMN *str,
                           uint column_count,
                           uint *column_numbers,
                           DYNAMIC_COLUMN_VALUE *values);
enum enum_dyncol_func_result
mariadb_dyncol_update_many_named(DYNAMIC_COLUMN *str,
                                 uint column_count,
                                 MYSQL_LEX_STRING *column_keys,
                                 DYNAMIC_COLUMN_VALUE *values);

mariadb_dyncol_exists

Проверяет, существует ли столбец с заданным именем в блоке

enum enum_dyncol_func_result
mariadb_dyncol_exists(DYNAMIC_COLUMN *str, uint column_number);
enum enum_dyncol_func_result
mariadb_dyncol_exists_named(DYNAMIC_COLUMN *str, MYSQL_LEX_STRING *column_key);

Функция возвращает ДА/НЕТ или код ошибки

mariadb_dyncol_column_count

Получает количество столбцов в блоке динамического столбца

enum enum_dyncol_func_result
mariadb_dyncol_column_count(DYNAMIC_COLUMN *str, uint *column_count);

mariadb_dyncol_list

Список столбцов в блоке динамических столбцов.

enum enum_dyncol_func_result
mariadb_dyncol_list(DYNAMIC_COLUMN *str, uint *column_count, uint **column_numbers);
enum enum_dyncol_func_result
mariadb_dyncol_list_named(DYNAMIC_COLUMN *str, uint *column_count,
                          MYSQL_LEX_STRING **column_keys);

mariadb_dyncol_get

Получить значение одного столбца

enum enum_dyncol_func_result
mariadb_dyncol_get(DYNAMIC_COLUMN *org, uint column_number,
                   DYNAMIC_COLUMN_VALUE *value);
enum enum_dyncol_func_result
mariadb_dyncol_get_named(DYNAMIC_COLUMN *str, MYSQL_LEX_STRING *column_key,
                         DYNAMIC_COLUMN_VALUE *value);

Если столбец не найден, возвращается NULL как значение столбца.

mariadb_dyncol_unpack

Получить значения всех столбцов

enum enum_dyncol_func_result
mariadb_dyncol_unpack(DYNAMIC_COLUMN *str,
                      uint *column_count,
                      MYSQL_LEX_STRING **column_keys,
                      DYNAMIC_COLUMN_VALUE **values);

mariadb_dyncol_has_names

Проверка, использует ли блок динамических столбцов новый формат данных (формат, в котором столбцы идентифицируются по именам)

my_bool mariadb_dyncol_has_names(DYNAMIC_COLUMN *str);

mariadb_dyncol_check

Проверка, имеет ли блок динамических столбцов правильный формат данных.

enum enum_dyncol_func_result
mariadb_dyncol_check(DYNAMIC_COLUMN *str);

mariadb_dyncol_json

Получение содержимого блока динамических столбцов в формате JSON

enum enum_dyncol_func_result
mariadb_dyncol_json(DYNAMIC_COLUMN *str, DYNAMIC_STRING *json);

mariadb_dyncol_val_TYPE

Получение значения динамического столбца как одного из основных типов

enum enum_dyncol_func_result
mariadb_dyncol_val_str(DYNAMIC_STRING *str, DYNAMIC_COLUMN_VALUE *val,
                       CHARSET_INFO *cs, my_bool quote);
enum enum_dyncol_func_result
mariadb_dyncol_val_long(longlong *ll, DYNAMIC_COLUMN_VALUE *val);
enum enum_dyncol_func_result
mariadb_dyncol_val_double(double *dbl, DYNAMIC_COLUMN_VALUE *val);

mariadb_dyncol_prepare_decimal

Инициализация DYNAMIC_COLUMN_VALUE перед тем, как можно будет установить значение value.x.decimal.value

void mariadb_dyncol_prepare_decimal(DYNAMIC_COLUMN_VALUE *value);

Эта функция связывает value.x.decimal.value с value.x.decimal.buffer.

mariadb_dyncol_value_init

Инициализирует структуру DYNAMIC_COLUMN_VALUE до безопасного значения по умолчанию.

#define mariadb_dyncol_value_init(V) (V)->type= DYN_COL_NULL

mariadb_dyncol_column_cmp_named

Сравнение двух имён столбцов (в настоящее время имена столбцов сравниваются с помощью memcmp())

int mariadb_dyncol_column_cmp_named(const MYSQL_LEX_STRING *s1,
                                    const MYSQL_LEX_STRING *s2);