Dynamic Columns API

Эта страница описывает клиентскую часть API MariaDB 10.0.1 и MariaDB Connector/C 2.0 для чтения и записи блоков Динамических столбцов.

Обычно следует использовать функции динамических столбцов, которые выполняются внутри сервера 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_num() работает со старым (до MariaDB-10.0.1) форматом блоков динамических столбцов, где столбцы определялись номерами.
• xxx_named() может работать как со старым, так и с новым форматом данных. Если она изменяет блок, она преобразует его в новый формат данных.

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

mariadb_dyncol_init

1. define mariadb_dyncol_init(A) memset((A), 0, sizeof(*(A)))

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

mariadb_dyncol_free

void mariadb_dyncol_free(DYNAMIC_COLUMN *str);

где

mariadb_dyncol_create_many (num|named)

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

enum enum_dyncol_func_result
mariadb_dyncol_create_many_num(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 (num|named)

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

enum enum_dyncol_func_result
mariadb_dyncol_update_many_num(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 (num|named)

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

enum enum_dyncol_func_result
mariadb_dyncol_exists_num(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 (num|named)

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

enum enum_dyncol_func_result
mariadb_dyncol_list_num(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 (num|named)

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

enum enum_dyncol_func_result
mariadb_dyncol_get_num(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_json() выделяет память для параметра json, который необходимо явно освободить с помощью функции mariadb_dyncol_free(), чтобы предотвратить утечку памяти.

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

Сравнить два имени столбцов на равенство

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