Dynamic Columns API
Contents
- Result codes of functions
- Type of dynamic column encoded string
- Types of data used by dynamic string routines
- Storing unpacked values
- Functions
- Creating string from unpacked value array
- Changing dynamic column packed string content
- Checking column existance
- List of not NULL columns
- Get one column value
- Get all non-NULL columns values
- Check packed dynamic column string format
- Check packed dynamic column integrity
- Get dynamic columns as JSON object
- Get dynamic column value as one of base 3 types
Result codes of functions
General rule is that if result code less then 0 it is an error.
Following codeas are defined in enum enum_dyncol_func_result
:
value | name | meaning |
---|---|---|
0 | ER_DYNCOL_OK | A procedure sucessfully finished |
0 | ER_DYNCOL_NO | (the same as ER_DYNCOL_OK but for functions which requite YES/NO responce |
1 | ER_DYNCOL_YES | YES responce and sucess (see above) |
2 | ER_DYNCOL_TRUNCATED | OK, but data was truncated |
-1 | ER_DYNCOL_FORMAT | Wrong format of the encoded string |
-2 | ER_DYNCOL_LIMIT | A limit of implimentation reached |
-3 | ER_DYNCOL_RESOURCE | Out of resourses |
-4 | ER_DYNCOL_DATA | Incorrect input data (other then encoded string) |
-5 | ER_DYNCOL_UNKNOWN_CHARSET | Unknown character set |
Type of dynamic column encoded string
We add special type for dynamic column encoded string: DYNAMIC_COLUMN
but in fact it is DYNAMIC_STRING
.
Types of data used by dynamic string routines
The types defined as a DYNAMIC_COLUMN_TYPE
(enum
enum_dynamic_column_type
).
type | meaning |
---|---|
DYN_COL_NULL | means NULL, never stored in the column (absence mean NULL) |
DYN_COL_INT | Signed Integer (long) |
DYN_COL_UINT | Unsigned integer (unsigned long) |
DYN_COL_DOUBLE | Floating point double (double |
DYN_COL_STRING | String (MYSQL_LEX_STRING and CHARSET_INFO ) |
DYN_COL_DECIMAL | MySQL Decimal (fixed point) value |
DYN_COL_DATETIME | Date and tyme |
DYN_COL_DATE | Date |
DYN_COL_TIME | Time |
DYN_COL_DYNCOL | The same as String with binary encoding but content other encoded dynamic columns row (valid only for new 10.0.1 format with names) |
Storing unpacked values
Unpacked (not encoded to the string) values of dynamic columns stored in the structure
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;
Values should be requested from different underlying unuon fieds depending
on type (value.type
)
type | field |
---|---|
DYN_COL_NULL | - |
DYN_COL_INT | value.x.long_value |
DYN_COL_UINT | value.x.ulong_value |
DYN_COL_DOUBLE | value.x.double_value |
DYN_COL_STRING | value.x.string.value and value.x.string.charset |
DYN_COL_DECIMAL | value.x.decimal.value |
DYN_COL_DATETIME | value.x.time_value |
DYN_COL_DATE | value.x.time_value |
DYN_COL_TIME | value.x.time_value |
DYN_COL_DYNCOL | value.x.string.value |
Before putting value into value.x.decimal.value
mariadb_dyncol_prepare_decimal
should be called for correct
initialization of the value and buffer where decimal will be stored.
Functions
Mostly there is 2 pairs of function, one works only with old (numeric) format other one can read old (numeric) and new (with names) format but produce string in the new format.
To check packed dynamic string format use mariadb_dyncol_has_names
function
Creating string from unpacked value array
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);
where
str | OUT | Created packed dynamic columns string will be put here |
column_count | IN | Number of columns in following arrays |
column_numbers | IN | Column numbers array (old format) |
column_keys | IN | Column names array (new format) |
values | IN | Values of the columns array |
new_string | IN | If TRUE then the str will be reinitialized (not freed) before usage |
Changing dynamic column packed string content
Following function add columns if they are not present in the string, update a column values if they was already in the string. To delete column you should update its value to 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);
str | IN/OUT | Packed dynamic columns string to modify. |
column_count | IN | Number of columns in following arrays |
column_numbers | IN | Column numbers array (old format) |
column_keys | IN | Column names array (new format) |
values | IN | Values of the columns array |
Checking column existance
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);
str | IN | Packed dynamic columns string. |
column_number | IN | Column number (old format) |
column_key | IN | Column name (new format) |
The function returns YES/NO or Error code
List of not NULL columns
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);
str | IN | Packed dynamic columns string. |
column_count | OUT | Number of columns in following arrays |
column_numbers | OUT | Column numbers array (old format). Caller should free this array. |
column_keys | OUT | Column names array (new format). Caller should free this array. |
Get one column value
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);
str | IN | Packed dynamic columns string. |
column_number | IN | Column numbers array (old format) |
column_key | IN | Column names array (new format) |
value | OUT | Value of the column |
If the column is not found NULL returned as a value of the column.
Get all non-NULL columns values
enum enum_dyncol_func_result mariadb_dyncol_unpack(DYNAMIC_COLUMN *str, uint *column_count, MYSQL_LEX_STRING **column_keys, DYNAMIC_COLUMN_VALUE **values);
str | IN | Packed dynamic columns string to unpack. |
column_count | OUT | Number of columns in following arrays |
column_keys | OUT | Column names array (should be free by caller) |
values | OUT | Values of the columns array (should be free by caller) |
Check packed dynamic column string format
my_bool mariadb_dyncol_has_names(DYNAMIC_COLUMN *str);
str | IN | Packed dynamic columns string. |
The function check only one byte of the string so it is quite efficient, but also wrong data tolerant.
Check packed dynamic column integrity
enum enum_dyncol_func_result mariadb_dyncol_check(DYNAMIC_COLUMN *str);
str | IN | Packed dynamic columns string. |
Get dynamic columns as JSON object
enum enum_dyncol_func_result mariadb_dyncol_json(DYNAMIC_COLUMN *str, DYNAMIC_STRING *json);
str | IN | Packed dynamic columns string. |
json | out | JSON representation |
Get dynamic column value as one of base 3 types
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);
str or ll or dbl | #out# | value of the column |
val | IN | Value |
to be continue