SQL Table Data Management

Data Structures
struct	M_sql_tabledata_t

Typedefs
typedef struct M_sql_tabledata_field	M_sql_tabledata_field_t
typedef struct M_sql_tabledata_txn	M_sql_tabledata_txn_t
typedef M_bool(*	M_sql_tabledata_filtertransform_cb) (M_sql_tabledata_txn_t *txn, const char *field_name, M_sql_tabledata_field_t *field, char *error, size_t error_len)
typedef M_sql_error_t(*	M_sql_tabledata_validate_cb) (M_sql_trans_t *sqltrans, M_sql_tabledata_txn_t *txn, const char *field_name, char *error, size_t error_len)
typedef M_bool(*	M_sql_tabledata_fetch_cb) (M_sql_tabledata_field_t *out, const char *field_name, M_bool is_add, void *thunk)
typedef M_sql_error_t(*	M_sql_tabledata_notify_cb) (M_sql_trans_t *sqltrans, M_sql_tabledata_txn_t *txn, char *error, size_t error_len)

Enumerations
enum	M_sql_tabledata_flags_t {   M_SQL_TABLEDATA_FLAG_NONE = 0 ,   M_SQL_TABLEDATA_FLAG_VIRTUAL = 1 << 0 ,   M_SQL_TABLEDATA_FLAG_EDITABLE = 1 << 1 ,   M_SQL_TABLEDATA_FLAG_NOTNULL = 1 << 2 ,   M_SQL_TABLEDATA_FLAG_ID = 1 << 3 ,   M_SQL_TABLEDATA_FLAG_ID_GENERATE = 1 << 4 ,   M_SQL_TABLEDATA_FLAG_ID_REQUIRED = 1 << 5 ,   M_SQL_TABLEDATA_FLAG_TIMESTAMP = 1 << 6 ,   M_SQL_TABLEDATA_FLAG_ALLOW_NONPRINT_SEP = 1 << 7 }
enum	M_sql_tabledata_txn_field_select_t {   M_SQL_TABLEDATA_TXN_FIELD_MERGED = 1 ,   M_SQL_TABLEDATA_TXN_FIELD_MERGED_NODUPLICATE = 2 ,   M_SQL_TABLEDATA_TXN_FIELD_PRIOR = 3 ,   M_SQL_TABLEDATA_TXN_FIELD_CURRENT_READONLY = 4 ,   M_SQL_TABLEDATA_TXN_FIELD_CURRENT = 5 }

Functions
M_bool	M_sql_tabledata_filter_int2dec_cb (M_sql_tabledata_txn_t *txn, const char *field_name, M_sql_tabledata_field_t *field, char *error, size_t error_len)
M_bool	M_sql_tabledata_filter_int5dec_cb (M_sql_tabledata_txn_t *txn, const char *field_name, M_sql_tabledata_field_t *field, char *error, size_t error_len)
M_bool	M_sql_tabledata_filter_alnum_cb (M_sql_tabledata_txn_t *txn, const char *field_name, M_sql_tabledata_field_t *field, char *error, size_t error_len)
M_bool	M_sql_tabledata_filter_alnumsp_cb (M_sql_tabledata_txn_t *txn, const char *field_name, M_sql_tabledata_field_t *field, char *error, size_t error_len)
M_bool	M_sql_tabledata_filter_alpha_cb (M_sql_tabledata_txn_t *txn, const char *field_name, M_sql_tabledata_field_t *field, char *error, size_t error_len)
M_bool	M_sql_tabledata_filter_graph_cb (M_sql_tabledata_txn_t *txn, const char *field_name, M_sql_tabledata_field_t *field, char *error, size_t error_len)
M_sql_tabledata_field_t *	M_sql_tabledata_field_create_ext (void)
void	M_sql_tabledata_field_destroy_ext (M_sql_tabledata_field_t *field)
void	M_sql_tabledata_field_set_bool (M_sql_tabledata_field_t *field, M_bool val)
void	M_sql_tabledata_field_set_int16 (M_sql_tabledata_field_t *field, M_int16 val)
void	M_sql_tabledata_field_set_int32 (M_sql_tabledata_field_t *field, M_int32 val)
void	M_sql_tabledata_field_set_int64 (M_sql_tabledata_field_t *field, M_int64 val)
void	M_sql_tabledata_field_set_text_own (M_sql_tabledata_field_t *field, char *val)
void	M_sql_tabledata_field_set_text_dup (M_sql_tabledata_field_t *field, const char *val)
void	M_sql_tabledata_field_set_text_const (M_sql_tabledata_field_t *field, const char *val)
void	M_sql_tabledata_field_set_binary_own (M_sql_tabledata_field_t *field, unsigned char *val, size_t len)
void	M_sql_tabledata_field_set_binary_dup (M_sql_tabledata_field_t *field, const unsigned char *val, size_t len)
void	M_sql_tabledata_field_set_binary_const (M_sql_tabledata_field_t *field, const unsigned char *val, size_t len)
void	M_sql_tabledata_field_set_null (M_sql_tabledata_field_t *field)
M_bool	M_sql_tabledata_field_get_bool (M_sql_tabledata_field_t *field, M_bool *val)
M_bool	M_sql_tabledata_field_get_int16 (M_sql_tabledata_field_t *field, M_int16 *val)
M_bool	M_sql_tabledata_field_get_int32 (M_sql_tabledata_field_t *field, M_int32 *val)
M_bool	M_sql_tabledata_field_get_int64 (M_sql_tabledata_field_t *field, M_int64 *val)
M_bool	M_sql_tabledata_field_get_text (M_sql_tabledata_field_t *field, const char **val)
M_bool	M_sql_tabledata_field_get_binary (M_sql_tabledata_field_t *field, const unsigned char **val, size_t *len)
M_bool	M_sql_tabledata_field_is_null (const M_sql_tabledata_field_t *field)
M_bool	M_sql_tabledata_field_is_alloc (const M_sql_tabledata_field_t *field)
M_sql_data_type_t	M_sql_tabledata_field_type (const M_sql_tabledata_field_t *field)
void *	M_sql_tabledata_txn_get_thunk (M_sql_tabledata_txn_t *txn)
const char *	M_sql_tabledata_txn_get_tablename (M_sql_tabledata_txn_t *txn)
M_int64	M_sql_tabledata_txn_get_generated_id (M_sql_tabledata_txn_t *txn)
M_bool	M_sql_tabledata_txn_is_add (M_sql_tabledata_txn_t *txn)
M_sql_tabledata_field_t *	M_sql_tabledata_txn_field_get (M_sql_tabledata_txn_t *txn, const char *field_name, M_sql_tabledata_txn_field_select_t fselect)
M_bool	M_sql_tabledata_txn_field_changed (M_sql_tabledata_txn_t *txn, const char *field_name)
M_bool	M_sql_tabledata_txn_field_changed_ci (M_sql_tabledata_txn_t *txn, const char *field_name)
const M_sql_tabledata_t *	M_sql_tabledata_txn_fetch_fielddef (M_sql_tabledata_txn_t *txn, const char *field_name)
M_sql_error_t	M_sql_tabledata_add (M_sql_connpool_t *pool, const char *table_name, const M_sql_tabledata_t *fields, size_t num_fields, M_sql_tabledata_fetch_cb fetch_cb, M_sql_tabledata_notify_cb notify_cb, void *thunk, M_int64 *generated_id, char *error, size_t error_len)
M_sql_error_t	M_sql_tabledata_trans_add (M_sql_trans_t *sqltrans, const char *table_name, const M_sql_tabledata_t *fields, size_t num_fields, M_sql_tabledata_fetch_cb fetch_cb, M_sql_tabledata_notify_cb notify_cb, void *thunk, M_int64 *generated_id, char *error, size_t error_len)
M_sql_error_t	M_sql_tabledata_edit (M_sql_connpool_t *pool, const char *table_name, const M_sql_tabledata_t *fields, size_t num_fields, M_sql_tabledata_fetch_cb fetch_cb, M_sql_tabledata_notify_cb notify_cb, void *thunk, char *error, size_t error_len)
M_sql_error_t	M_sql_tabledata_trans_edit (M_sql_trans_t *sqltrans, const char *table_name, const M_sql_tabledata_t *fields, size_t num_fields, M_sql_tabledata_fetch_cb fetch_cb, M_sql_tabledata_notify_cb notify_cb, void *thunk, char *error, size_t error_len)
M_sql_error_t	M_sql_tabledata_upsert (M_sql_connpool_t *pool, const char *table_name, const M_sql_tabledata_t *fields, size_t num_fields, M_sql_tabledata_fetch_cb fetch_cb, M_sql_tabledata_notify_cb notify_cb, void *thunk, char *error, size_t error_len)
M_sql_error_t	M_sql_tabledata_trans_upsert (M_sql_trans_t *sqltrans, const char *table_name, const M_sql_tabledata_t *fields, size_t num_fields, M_sql_tabledata_fetch_cb fetch_cb, M_sql_tabledata_notify_cb notify_cb, void *thunk, char *error, size_t error_len)
M_sql_tabledata_t *	M_sql_tabledata_append_virtual_list (const M_sql_tabledata_t *fields, size_t *num_fields, const char *table_column, const M_list_str_t *field_names, size_t max_len, M_sql_tabledata_flags_t flags)
M_bool	M_sql_tabledata_to_table (M_sql_table_t *table, const M_sql_tabledata_t *fields, size_t num_fields)

Detailed Description

SQL Table Data Management

---

Data Structure Documentation

M_sql_tabledata_t

struct M_sql_tabledata_t

Structure to be used to define the various fields and columns stored in a table

Data Fields
const char *	table_column	Database column name
const char *	field_name	Field name to fetch in order to retrieve column data. For virtual columns, this field name is also used as the tag name. If NULL or blank, means field not used. Reserved for external modification.
size_t	max_column_len	Maximum text or binary length of column allowed. For M_SQL_TABLEDATA_FLAG_ID_GENERATE fields, it is the desired number of digits to generate
M_sql_data_type_t	type	Column data type
M_sql_tabledata_flags_t	flags	Flags controlling behavior
M_sql_tabledata_filtertransform_cb	filter_cb	Callback to filter or transform input data. Called only on new user-specified params.
M_sql_tabledata_validate_cb	validate_cb	Callback for in-depth validation of input data that may require external SQL queries.

Typedef Documentation

M_sql_tabledata_field_t

typedef struct M_sql_tabledata_field M_sql_tabledata_field_t

Opaque structure holding field data. Use corresponding setters/getters to manipulate.

M_sql_tabledata_txn_t

typedef struct M_sql_tabledata_txn M_sql_tabledata_txn_t

Opaque Data structure holding add/edit request transaction data. Use the M_sql_tabledata_txn_*() functions to access/modify

M_sql_tabledata_filtertransform_cb

typedef M_bool(* M_sql_tabledata_filtertransform_cb) (M_sql_tabledata_txn_t *txn, const char *field_name, M_sql_tabledata_field_t *field, char *error, size_t error_len)

A callback to perform basic filtering and transformation of a user-input field to how it needs to be stored within the database. This can also reject the data and return an error if it does not meet the requirements.

This callback is called only when new user data is provided. It will not be called if a field isn't passed in. For instance, on an edit operation, this callback will NOT be called if the user did not supply the field as the only data we have is the data from the database which is already sanitized. This also goes for an add operation, if not provided by the user, this callback is NOT called.

Parameters

[in]	txn	Transaction data. May be used to retrieve other useful information that may be needed for proper validation.
[in]	field_name	Name of field
[in,out]	field	Current data in field. This should be modified in-place if needed to be transformed.
[out]	error	Buffer to hold error message
[in]	error_len	Length of error buffer

Returns

M_TRUE on success, M_FALSE on failure (set error buffer!)

M_sql_tabledata_validate_cb

typedef M_sql_error_t(* M_sql_tabledata_validate_cb) (M_sql_trans_t *sqltrans, M_sql_tabledata_txn_t *txn, const char *field_name, char *error, size_t error_len)

A callback to perform intensive validation of the data field, which may require performing additional SQL queries.

This callback is always called for the field, regardless of if it has changed. This includes on add even if a field isn't specified as it may be required to validate if maybe the field really should have been provided. Recommended to call M_sql_tabledata_txn_field_changed() if only need to perform operations when the field has changed.

The field data is not provided and must be fetched via M_sql_tabledata_txn_field_get() as it is not known which variant of the data may be needed.

The field data may be manipulated or transformed by this callback if desired.

Parameters

[in]	sqltrans	SQL transaction to use for any external queries needed.
[in]	txn	Transaction data. May be used to retrieve other useful information that may be needed for proper validation.
[in]	field_name	Name of field
[out]	error	Buffer to hold error message
[in]	error_len	Length of error buffer

Returns

M_SQL_ERROR_SUCCESS or M_SQL_ERROR_USER_SUCCESS if validationsucceeded, other error otherwise (possibly retryable).

M_sql_tabledata_fetch_cb

typedef M_bool(* M_sql_tabledata_fetch_cb) (M_sql_tabledata_field_t *out, const char *field_name, M_bool is_add, void *thunk)

Callback for fetching a table field.

Parameters

[out]	out	Pointer to M_sql_tabledata_field_t to be filled in. MUST allow NULL as it may be called during a 'test' operation.
[in]	field_name	Field name being fetched
[in]	is_add	M_TRUE if this is called during an add operation, M_FALSE otherwise.
[in]	thunk	Thunk parameter for custom state tracking passed to parent function.

Returns

M_FALSE if field was not found, M_TRUE otherwise

M_sql_tabledata_notify_cb

typedef M_sql_error_t(* M_sql_tabledata_notify_cb) (M_sql_trans_t *sqltrans, M_sql_tabledata_txn_t *txn, char *error, size_t error_len)

Callback that is called at completion of an add/edit. Both the prior and new field data are available for the entire table. It may be necessary to do cross-table modifications based on a change, so this facilitates that ability. If making linked changes, you must use the passed in sqltrans parameter to ensure it is treated as a single atomic operation. On edit, this registered callback will be called on any successful condition, including no changed fields.

Parameters

[in]	sqltrans	SQL Transaction for chaining atomic actions
[in]	txn	Tabledata transaction pointer to grab field data
[in,out]	error	Buffer to hold error if any
[in]	error_len	Size of error buffer

Returns

one of the M_sql_error_t codes. Use M_SQL_ERROR_USER_SUCCESS if nothing changed, and M_SQL_ERROR_SUCCESS if this callback caused a change. Otherwise one of the error codes.

Enumeration Type Documentation

M_sql_tabledata_flags_t

enum M_sql_tabledata_flags_t

Flags for processing table data fields / columns

Enumerator
M_SQL_TABLEDATA_FLAG_NONE	No Flags
M_SQL_TABLEDATA_FLAG_VIRTUAL	Field is a virtual column, multiple serialized virtual columns can be stored in a single 'real' database column under 'table_column'. Any data type except binary may be used.
M_SQL_TABLEDATA_FLAG_EDITABLE	Field is allowed to be edited, not add-only
M_SQL_TABLEDATA_FLAG_NOTNULL	Field must be specified and is not allowed to be NULL
M_SQL_TABLEDATA_FLAG_ID	Field is an ID column (meaning it is used for lookups). Can be assigned on add, but cannot be used with M_SQL_TABLEDATA_FLAG_EDITABLE or M_SQL_TABLEDATA_FLAG_VIRTUAL.
M_SQL_TABLEDATA_FLAG_ID_GENERATE	Auto-generate the ID on the user's behalf. Must be an ID field. Only one allowed per field definition list.
M_SQL_TABLEDATA_FLAG_ID_REQUIRED	On edits, this ID must be specified. On some DBs, you may not have any required IDs as there may be multiple lookup indexes
M_SQL_TABLEDATA_FLAG_TIMESTAMP	Field is an auto-generated unix timestamp. Must be INT64. Cannot be specified with ID. Field fetcher will never be called. If M_SQL_TABLEDATA_FLAG_EDITABLE is specified, will update on edit
M_SQL_TABLEDATA_FLAG_ALLOW_NONPRINT_SEP	Allow non-printable characters designated as separators (e.g. 0x1C, 0x1D, 0x1E)

M_sql_tabledata_txn_field_select_t

enum M_sql_tabledata_txn_field_select_t

When fetching a field from a transaction, the manner in which to fetch

Enumerator
M_SQL_TABLEDATA_TXN_FIELD_MERGED	Grab the current specified value of the field, if not found, grab the prior value. On add, equivalent to M_SQL_TABLEDATA_TXN_FIELD_CURRENT.
M_SQL_TABLEDATA_TXN_FIELD_MERGED_NODUPLICATE	Grab the current specified value of the field, if not found, grab the prior value and duplicate it as the current value for editing.
M_SQL_TABLEDATA_TXN_FIELD_PRIOR	Grab the prior value of the field. On add, this is always NULL.
M_SQL_TABLEDATA_TXN_FIELD_CURRENT_READONLY	Grab the current specified value of the field. May not exist on edit if value is unchanged.
M_SQL_TABLEDATA_TXN_FIELD_CURRENT	Grab the current specified value of the field. If not found, create a new NULL field and return it for modification (field_name specified must be valid)

Function Documentation

M_sql_tabledata_filter_int2dec_cb()

M_bool M_sql_tabledata_filter_int2dec_cb	(	M_sql_tabledata_txn_t *	txn,
		const char *	field_name,
		M_sql_tabledata_field_t *	field,
		char *	error,
		size_t	error_len
	)

Implementation of M_sql_tabledata_filtertransform_cb to validate and transform a decimal value with 2 places to an integer with 2 implied decimal places

M_sql_tabledata_filter_int5dec_cb()

M_bool M_sql_tabledata_filter_int5dec_cb	(	M_sql_tabledata_txn_t *	txn,
		const char *	field_name,
		M_sql_tabledata_field_t *	field,
		char *	error,
		size_t	error_len
	)

Implementation of M_sql_tabledata_filtertransform_cb to validate and transform a decimal value with 5 places to an integer with 5 implied decimal places

M_sql_tabledata_filter_alnum_cb()

M_bool M_sql_tabledata_filter_alnum_cb	(	M_sql_tabledata_txn_t *	txn,
		const char *	field_name,
		M_sql_tabledata_field_t *	field,
		char *	error,
		size_t	error_len
	)

Implementation of M_sql_tabledata_filtertransform_cb to validate a string is alpha numeric

M_sql_tabledata_filter_alnumsp_cb()

M_bool M_sql_tabledata_filter_alnumsp_cb	(	M_sql_tabledata_txn_t *	txn,
		const char *	field_name,
		M_sql_tabledata_field_t *	field,
		char *	error,
		size_t	error_len
	)

Implementation of M_sql_tabledata_filtertransform_cb to validate a string is alpha numeric with possible spaces

M_sql_tabledata_filter_alpha_cb()

M_bool M_sql_tabledata_filter_alpha_cb	(	M_sql_tabledata_txn_t *	txn,
		const char *	field_name,
		M_sql_tabledata_field_t *	field,
		char *	error,
		size_t	error_len
	)

Implementation of M_sql_tabledata_filtertransform_cb to validate a string is alpha only

M_sql_tabledata_filter_graph_cb()

M_bool M_sql_tabledata_filter_graph_cb	(	M_sql_tabledata_txn_t *	txn,
		const char *	field_name,
		M_sql_tabledata_field_t *	field,
		char *	error,
		size_t	error_len
	)

Implementation of M_sql_tabledata_filtertransform_cb to validate a string is graph only

M_sql_tabledata_field_create_ext()

M_sql_tabledata_field_t * M_sql_tabledata_field_create_ext

(

void

)

FOR EXTERNAL USE ONLY. Create a new M_sql_tabledata_field_t

This is only for use outside of M_sql_tabledata_* functions.

Returns

new allocated tabledata field

M_sql_tabledata_field_destroy_ext()

void M_sql_tabledata_field_destroy_ext

(

M_sql_tabledata_field_t *

field

)

FOR EXTERNAL USE ONLY. Destroys a M_sql_tabledata_field_t explicitly allocated by M_sql_tabledata_field_create_ext()

This is only for use outside of M_sql_tabledata_* functions. NEVER call this on a handle provided by M_sql_tabledata_fetch_cb or retrieved by M_sql_tabledata_txn_field_get()

Parameters

[in]

field

Field to be destroyed

M_sql_tabledata_field_set_bool()

void M_sql_tabledata_field_set_bool	(	M_sql_tabledata_field_t *	field,
		M_bool	val
	)

Set the field pointer to a boolean value. Will override existing value and deallocate any prior memory consumed if necessary

Parameters

[in,out]	field	Field to set
[in]	val	Value to set. May be NULL if just error ch

M_sql_tabledata_field_set_int16()

void M_sql_tabledata_field_set_int16	(	M_sql_tabledata_field_t *	field,
		M_int16	val
	)

Set the field pointer to a 16bit integer Will override existing value and deallocate any prior memory consumed if necessary

Parameters

[in,out]	field	Field to set
[in]	val	Value to set

M_sql_tabledata_field_set_int32()

void M_sql_tabledata_field_set_int32	(	M_sql_tabledata_field_t *	field,
		M_int32	val
	)

Set the field pointer to a 32bit integer Will override existing value and deallocate any prior memory consumed if necessary

Parameters

[in,out]	field	Field to set
[in]	val	Value to set

M_sql_tabledata_field_set_int64()

void M_sql_tabledata_field_set_int64	(	M_sql_tabledata_field_t *	field,
		M_int64	val
	)

Set the field pointer to a 64bit integer. Will override existing value and deallocate any prior memory consumed if necessary

Parameters

[in,out]	field	Field to set
[in]	val	Value to set

M_sql_tabledata_field_set_text_own()

void M_sql_tabledata_field_set_text_own	(	M_sql_tabledata_field_t *	field,
		char *	val
	)

Set the field pointer to a text value and will take ownership of pointer passed (will be freed automatically). Will override existing value and deallocate any prior memory consumed if necessary

Parameters

[in,out]	field	Field to set
[in]	val	Value to set

M_sql_tabledata_field_set_text_dup()

void M_sql_tabledata_field_set_text_dup	(	M_sql_tabledata_field_t *	field,
		const char *	val
	)

Set the field pointer to a text value and will duplicate the pointer passed. Will override existing value and deallocate any prior memory consumed if necessary

Parameters

[in,out]	field	Field to set
[in]	val	Value to set

M_sql_tabledata_field_set_text_const()

void M_sql_tabledata_field_set_text_const	(	M_sql_tabledata_field_t *	field,
		const char *	val
	)

Set the field pointer to a text value and will treat the pointer as const, it must be valid until field is deallocated. Will override existing value and deallocate any prior memory consumed if necessary

Parameters

[in,out]	field	Field to set
[in]	val	Value to set

M_sql_tabledata_field_set_binary_own()

void M_sql_tabledata_field_set_binary_own	(	M_sql_tabledata_field_t *	field,
		unsigned char *	val,
		size_t	len
	)

Set the field pointer to a binary value and will duplicate the pointer passed. Will override existing value and deallocate any prior memory consumed if necessary

Parameters

[in,out]	field	Field to set
[in]	val	Value to set
[in]	len	Length of value

M_sql_tabledata_field_set_binary_dup()

void M_sql_tabledata_field_set_binary_dup	(	M_sql_tabledata_field_t *	field,
		const unsigned char *	val,
		size_t	len
	)

Set the field pointer to a binary value and will duplicate the pointer passed. Will override existing value and deallocate any prior memory consumed if necessary

Parameters

[in,out]	field	Field to set
[in]	val	Value to set
[in]	len	Length of value

M_sql_tabledata_field_set_binary_const()

void M_sql_tabledata_field_set_binary_const	(	M_sql_tabledata_field_t *	field,
		const unsigned char *	val,
		size_t	len
	)

Set the field pointer to a binary value and will treat the pointer as const, it must be valid until field is deallocated. Will override existing value and deallocate any prior memory consumed if necessary

Parameters

[in,out]	field	Field to set
[in]	val	Value to set
[in]	len	Length of value

M_sql_tabledata_field_set_null()

void M_sql_tabledata_field_set_null

(

M_sql_tabledata_field_t *

field

)

Set the field to NULL. Will override existing value and deallocate any prior memory consumed if necessary

Parameters

[in,out]

field

Field to set

M_sql_tabledata_field_get_bool()

M_bool M_sql_tabledata_field_get_bool	(	M_sql_tabledata_field_t *	field,
		M_bool *	val
	)

Retrieve field data as a boolean. If type conversion is necessary, it will be performed such that integer values are treated as true if non-zero and false if zero. Text values must have a valid boolean string and evaluate as appropriate or return failure. Any other conversion will return failure.

Once a field is fetched successfully as a bool, it is internally converted to a bool.

Parameters

[in,out]	field	Field to retrieve data from
[out]	val	Boolean output value. May be NULL if just error checking.

Returns

M_FALSE if conversion was not possible, M_TRUE if successful.

M_sql_tabledata_field_get_int16()

M_bool M_sql_tabledata_field_get_int16	(	M_sql_tabledata_field_t *	field,
		M_int16 *	val
	)

Retrieve field data as a 16bit integer. If type conversion is necessary, it will be performed such that integer values are truncated if possible, and boolean values are set to 1 or 0. Text values will be passed through a string conversion if numeric. Any other conversion will return failure.

Once a field is fetched successfully as an int32, it is internally converted to an int32.

Parameters

[in,out]	field	Field to retrieve data from
[out]	val	Int32 output value. May be NULL if just error checking.

Returns

M_FALSE if conversion was not possible, M_TRUE if successful.

M_sql_tabledata_field_get_int32()

M_bool M_sql_tabledata_field_get_int32	(	M_sql_tabledata_field_t *	field,
		M_int32 *	val
	)

Retrieve field data as a 32bit integer. If type conversion is necessary, it will be performed such that integer values are truncated if possible, and boolean values are set to 1 or 0. Text values will be passed through a string conversion if numeric. Any other conversion will return failure.

Once a field is fetched successfully as an int32, it is internally converted to an int32.

Parameters

[in,out]	field	Field to retrieve data from
[out]	val	Int32 output value. May be NULL if just error checking.

Returns

M_FALSE if conversion was not possible, M_TRUE if successful.

M_sql_tabledata_field_get_int64()

M_bool M_sql_tabledata_field_get_int64	(	M_sql_tabledata_field_t *	field,
		M_int64 *	val
	)

Retrieve field data as a 64bit integer. If type conversion is necessary, it will be performed such that integer values are expanded, and boolean values are set to 1 or 0. Text values will be passed through a string conversion if numeric. Any other conversion will return failure.

Once a field is fetched successfully as an int64, it is internally converted to an int64

Parameters

[in,out]	field	Field to retrieve data from
[out]	val	Int64 output value. May be NULL if just error checking.

Returns

M_FALSE if conversion was not possible, M_TRUE if successful.

M_sql_tabledata_field_get_text()

M_bool M_sql_tabledata_field_get_text	(	M_sql_tabledata_field_t *	field,
		const char **	val
	)

Retrieve field data as text. If type conversion is necessary, it will be performed such that integer values are converted to base10 strings, and boolean values are converted into "yes" and "no". ny other conversion will return failure.

Once a field is fetched successfully as text, it is internally converted to text

Parameters

[in,out]	field	Field to retrieve data from
[out]	val	Pointer to text value that is valid until another conversion occurs or is freed or out of scope. May return NULL if value is NULL. Input may be NULL if just error checking.

Returns

M_FALSE if conversion was not possible, M_TRUE if successful.

M_sql_tabledata_field_get_binary()

M_bool M_sql_tabledata_field_get_binary	(	M_sql_tabledata_field_t *	field,
		const unsigned char **	val,
		size_t *	len
	)

Retrieve field data as binary.

Binary fields are not eligible for conversion.

Parameters

[in,out]	field	Field to retrieve data from
[out]	val	Pointer to binary value until freed or out of scope. May return NULL if value is NULL. Input may be NULL if just error checking.
[out]	len	Length of value. May be NULL if just error checking, unless val is non-NULL.

Returns

M_FALSE if conversion was not possible, M_TRUE if successful.

M_sql_tabledata_field_is_null()

M_bool M_sql_tabledata_field_is_null

(

const M_sql_tabledata_field_t *

field

)

Determine if field is NULL or not.

Parameters

[in]

field

Field to determine if value is NULL.

Returns

M_TRUE if NULL, M_FALSE otherwise.

M_sql_tabledata_field_is_alloc()

M_bool M_sql_tabledata_field_is_alloc

(

const M_sql_tabledata_field_t *

field

)

Determine if field is duplicated (non-const), meaning data will not survive once mutated or field is destroyed.

Parameters

[in]

field

Field to determine if is duplicated.

Returns

M_TRUE if duplicated, M_FALSE if const.

M_sql_tabledata_field_type()

M_sql_data_type_t M_sql_tabledata_field_type

(

const M_sql_tabledata_field_t *

field

)

Determine current field type. May change if setter or another getter is called.

Parameters

[in]

field

Field to retrieve type of.

Returns

field type.

M_sql_tabledata_txn_get_thunk()

void * M_sql_tabledata_txn_get_thunk

(

M_sql_tabledata_txn_t *

txn

)

Retrieve thunk parameter passed into transaction

Parameters

[in]

txn

Transaction provided to callback.

Returns

thunk parameter or NULL if none

M_sql_tabledata_txn_get_tablename()

const char * M_sql_tabledata_txn_get_tablename

(

M_sql_tabledata_txn_t *

txn

)

Retrieve table name parameter passed into transaction

Parameters

[in]

txn

Transaction provided to callback.

Returns

table name, or NULL on error

M_sql_tabledata_txn_get_generated_id()

M_int64 M_sql_tabledata_txn_get_generated_id

(

M_sql_tabledata_txn_t *

txn

)

Retrieve generated id during add operation

Parameters

[in]

txn

Transaction provided to callback.

Returns

generated id or 0 on error

M_sql_tabledata_txn_is_add()

M_bool M_sql_tabledata_txn_is_add

(

M_sql_tabledata_txn_t *

txn

)

Retrieve if transaction is add (vs edit)

Parameters

[in]

txn

Transaction provided to callback.

Returns

M_TRUE if is add, M_FALSE if is_edit (or misuse)

M_sql_tabledata_txn_field_get()

M_sql_tabledata_field_t * M_sql_tabledata_txn_field_get	(	M_sql_tabledata_txn_t *	txn,
		const char *	field_name,
		M_sql_tabledata_txn_field_select_t	fselect
	)

Retrieve the field data associated with the field name in the current transaction.

Parameters

[in]	txn	Transaction provided to callback.
[in]	field_name	Name of field
[in]	fselect	Manner in which to select the field

Returns

M_sql_tabledata_field_t on success, NULL on failure (not found, or invalid field name)

M_sql_tabledata_txn_field_changed()

M_bool M_sql_tabledata_txn_field_changed	(	M_sql_tabledata_txn_t *	txn,
		const char *	field_name
	)

Retrieve if the field has changed. Text fields are evaluated case sensitive.

Parameters

[in]	txn	Transaction provided to callback.
[in]	field_name	Name of field

Returns

M_TRUE if the field is found and on an add, or has changed on an edit, M_FALSE otherwise

M_sql_tabledata_txn_field_changed_ci()

M_bool M_sql_tabledata_txn_field_changed_ci	(	M_sql_tabledata_txn_t *	txn,
		const char *	field_name
	)

Retrieve if the field has changed. Text fields are evaluated case insensitively.

Parameters

[in]	txn	Transaction provided to callback.
[in]	field_name	Name of field

Returns

M_TRUE if the field is found and on an add, or has changed on an edit, M_FALSE otherwise

M_sql_tabledata_txn_fetch_fielddef()

const M_sql_tabledata_t * M_sql_tabledata_txn_fetch_fielddef	(	M_sql_tabledata_txn_t *	txn,
		const char *	field_name
	)

Retrieve the field definition for a field name from the current transaction.

Parameters

[in]	txn	Transaction provided to callback.
[in]	field_name	Name of field

Returns

pointer to field definition, or NULL if not found

M_sql_tabledata_add()

M_sql_error_t M_sql_tabledata_add	(	M_sql_connpool_t *	pool,
		const char *	table_name,
		const M_sql_tabledata_t *	fields,
		size_t	num_fields,
		M_sql_tabledata_fetch_cb	fetch_cb,
		M_sql_tabledata_notify_cb	notify_cb,
		void *	thunk,
		M_int64 *	generated_id,
		char *	error,
		size_t	error_len
	)

Add a row to a table based on the table definition. If there are key conflicts, it will retry up to 10 times if an auto-generated ID column exists.

Use M_sql_tabledata_trans_add() if inside of a transaction.

Parameters

[in]	pool	Required if sqltrans not passed. The handle to the SQL pool in use.
[in]	table_name	Name of the table
[in]	fields	List of fields (columns) in the table.
[in]	num_fields	Number of fields in the list
[in]	fetch_cb	Callback to be called to fetch each field/column.
[in]	notify_cb	Optional. Callback to be called to be notified on successful completion.
[in]	thunk	Thunk parameter for custom state tracking, will be passed to fetch_cb.
[out]	generated_id	If a column had specified M_SQL_TABLEDATA_FLAG_ID_GENERATE, then this will return that id
[in,out]	error	Buffer to hold error if any
[in]	error_len	Size of error buffer

Returns

one of the M_sql_error_t codes. Will return M_SQL_ERROR_USER_FAILURE on invalid usage of this function

M_sql_tabledata_trans_add()

M_sql_error_t M_sql_tabledata_trans_add	(	M_sql_trans_t *	sqltrans,
		const char *	table_name,
		const M_sql_tabledata_t *	fields,
		size_t	num_fields,
		M_sql_tabledata_fetch_cb	fetch_cb,
		M_sql_tabledata_notify_cb	notify_cb,
		void *	thunk,
		M_int64 *	generated_id,
		char *	error,
		size_t	error_len
	)

Add a row to a table based on the table definition. If there are key conflicts, it will retry up to 10 times if an auto-generated ID column exists.

Use M_sql_tabledata_add() if not already in a transaction.

Parameters

[in]	sqltrans	Required if pool not passed. If run within a transaction, this must be passed.
[in]	table_name	Name of the table
[in]	fields	List of fields (columns) in the table.
[in]	num_fields	Number of fields in the list
[in]	fetch_cb	Callback to be called to fetch each field/column.
[in]	notify_cb	Optional. Callback to be called to be notified on successful completion.
[in]	thunk	Thunk parameter for custom state tracking, will be passed to fetch_cb.
[out]	generated_id	If a column had specified M_SQL_TABLEDATA_FLAG_ID_GENERATE, then this will return that id
[in,out]	error	Buffer to hold error if any
[in]	error_len	Size of error buffer

Returns

one of the M_sql_error_t codes. Will return M_SQL_ERROR_USER_FAILURE on invalid usage of this function

M_sql_tabledata_edit()

M_sql_error_t M_sql_tabledata_edit	(	M_sql_connpool_t *	pool,
		const char *	table_name,
		const M_sql_tabledata_t *	fields,
		size_t	num_fields,
		M_sql_tabledata_fetch_cb	fetch_cb,
		M_sql_tabledata_notify_cb	notify_cb,
		void *	thunk,
		char *	error,
		size_t	error_len
	)

Edit an existing row in a table based on the field definitions. Not all fields need to be available on edit, only fields that are able to be fetched will be modified. It is valid to fetch a NULL value to explicitly set a column to NULL. The ID(s) specified must match exactly one row or a failure will be emitted.

Use M_sql_tabledata_trans_edit() if already in a transaction.

Parameters

[in]	pool	Required if sqltrans not passed. The handle to the SQL pool in use.
[in]	table_name	Name of the table
[in]	fields	List of fields (columns) in the table.
[in]	num_fields	Number of fields in the list
[in]	fetch_cb	Callback to be called to fetch each field/column.
[in]	notify_cb	Optional. Callback to be called to be notified on successful completion. (Even if no data changed)
[in]	thunk	Thunk parameter for custom state tracking, will be passed to fetch_cb.
[in,out]	error	Buffer to hold error if any
[in]	error_len	Size of error buffer

Returns

one of the M_sql_error_t codes. Will return M_SQL_ERROR_USER_FAILURE on invalid usage of this function. Will return M_SQL_ERROR_USER_SUCCESS when no updates were performed (passed in data matches on file data). M_SQL_ERROR_SUCCESS means a single row was changed.

M_sql_tabledata_trans_edit()

M_sql_error_t M_sql_tabledata_trans_edit	(	M_sql_trans_t *	sqltrans,
		const char *	table_name,
		const M_sql_tabledata_t *	fields,
		size_t	num_fields,
		M_sql_tabledata_fetch_cb	fetch_cb,
		M_sql_tabledata_notify_cb	notify_cb,
		void *	thunk,
		char *	error,
		size_t	error_len
	)

Edit an existing row in a table based on the field definitions. Not all fields need to be available on edit, only fields that are able to be fetched will be modified. It is valid to fetch a NULL value to explicitly set a column to NULL. The ID(s) specified must match exactly one row or a failure will be emitted.

Use M_sql_tabledata_edit() if not already in a transaction.

Parameters

[in]	sqltrans	Required if pool not passed. If run within a transaction, this must be passed.
[in]	table_name	Name of the table
[in]	fields	List of fields (columns) in the table.
[in]	num_fields	Number of fields in the list
[in]	fetch_cb	Callback to be called to fetch each field/column.
[in]	notify_cb	Optional. Callback to be called to be notified on successful completion. (Even if no data changed)
[in]	thunk	Thunk parameter for custom state tracking, will be passed to fetch_cb.
[in,out]	error	Buffer to hold error if any
[in]	error_len	Size of error buffer

Returns

one of the M_sql_error_t codes. Will return M_SQL_ERROR_USER_FAILURE on invalid usage of this function. Will return M_SQL_ERROR_USER_SUCCESS when no updates were performed (passed in data matches on file data). M_SQL_ERROR_SUCCESS means a single row was changed.

M_sql_tabledata_upsert()

M_sql_error_t M_sql_tabledata_upsert	(	M_sql_connpool_t *	pool,
		const char *	table_name,
		const M_sql_tabledata_t *	fields,
		size_t	num_fields,
		M_sql_tabledata_fetch_cb	fetch_cb,
		M_sql_tabledata_notify_cb	notify_cb,
		void *	thunk,
		char *	error,
		size_t	error_len
	)

Edit an existing row, or if not found, insert in a table based on the field definitions. All fields should be sent. It is valid to fetch a NULL value to explicitly set a column to NULL. The ID(s) specified must match exactly one row or a failure will be emitted.

Use M_sql_tabledata_trans_upsert() if already in a transaction.

Parameters

[in]	pool	Required if sqltrans not passed. The handle to the SQL pool in use.
[in]	table_name	Name of the table
[in]	fields	List of fields (columns) in the table.
[in]	num_fields	Number of fields in the list
[in]	fetch_cb	Callback to be called to fetch each field/column.
[in]	notify_cb	Optional. Callback to be called to be notified on successful completion. (Only if data changed)
[in]	thunk	Thunk parameter for custom state tracking, will be passed to fetch_cb.
[in,out]	error	Buffer to hold error if any
[in]	error_len	Size of error buffer

Returns

one of the M_sql_error_t codes. Will return M_SQL_ERROR_USER_FAILURE on invalid usage of this function. Will return M_SQL_ERROR_USER_SUCCESS when no updates were performed (passed in data matches on file data). M_SQL_ERROR_SUCCESS means a single row was changed.

M_sql_tabledata_trans_upsert()

M_sql_error_t M_sql_tabledata_trans_upsert	(	M_sql_trans_t *	sqltrans,
		const char *	table_name,
		const M_sql_tabledata_t *	fields,
		size_t	num_fields,
		M_sql_tabledata_fetch_cb	fetch_cb,
		M_sql_tabledata_notify_cb	notify_cb,
		void *	thunk,
		char *	error,
		size_t	error_len
	)

Edit an existing row, or if not found, insert in a table based on the field definitions. All fields should be sent. It is valid to fetch a NULL value to explicitly set a column to NULL. The ID(s) specified must match exactly one row or a failure will be emitted.

Use M_sql_tabledata_upsert() if not already in a transaction.

Parameters

[in]	sqltrans	Required if pool not passed. If run within a transaction, this must be passed.
[in]	table_name	Name of the table
[in]	fields	List of fields (columns) in the table.
[in]	num_fields	Number of fields in the list
[in]	fetch_cb	Callback to be called to fetch each field/column.
[in]	notify_cb	Optional. Callback to be called to be notified on successful completion. (Only if data changed)
[in]	thunk	Thunk parameter for custom state tracking, will be passed to fetch_cb.
[in,out]	error	Buffer to hold error if any
[in]	error_len	Size of error buffer

Returns

one of the M_sql_error_t codes. Will return M_SQL_ERROR_USER_FAILURE on invalid usage of this function. Will return M_SQL_ERROR_USER_SUCCESS when no updates were performed (passed in data matches on file data). M_SQL_ERROR_SUCCESS means a single row was changed.

M_sql_tabledata_append_virtual_list()

M_sql_tabledata_t * M_sql_tabledata_append_virtual_list	(	const M_sql_tabledata_t *	fields,
		size_t *	num_fields,
		const char *	table_column,
		const M_list_str_t *	field_names,
		size_t	max_len,
		M_sql_tabledata_flags_t	flags
	)

Convenience function to expand a list of tabledata fields base on an M_list_str_t list of virtual column names tied to a single table column that share the same attributes. All virtual columns are always stored as text.

IMPORTANT: The passed in "table_column" and "field_names" MUST persist until the tabledata structure is no longer needed as they are used as const values internally.

Parameters

[in]	fields	Field list to expand. Original input is NOT modified.
[in,out]	num_fields	On input, the size of the fields table passed in. On return, the new size.
[in]	table_column	Name of real table column virtual columns are tied to. NOTE: Pointer must persist until returned table is no longer needed.
[in]	field_names	List of virtual column names used to expand table. NOTE: Pointer must persist until returned table is no longer needed.
[in]	max_len	Maximum field value length for each field name.
[in]	flags	Shared field flags. M_SQL_TABLEDATA_FLAG_VIRTUAL is automatically added if not specified.

Returns

Allocated tabledata structure. Must be M_free()'d when no longer needed.

M_sql_tabledata_to_table()

M_bool M_sql_tabledata_to_table	(	M_sql_table_t *	table,
		const M_sql_tabledata_t *	fields,
		size_t	num_fields
	)

Convenience function to try to auto-generate the table columns for table creation based on the same tabledata used to add/edit.

NOTE: This does NOT create the primary key or index, it is expected to be handled externally.

Parameters

[in,out]	table	Initialized table to be populated with column data
[in]	fields	Field list to generate columns from
[in]	num_fields	Number of fields in the field list

Returns

M_TRUE on success, M_FALSE on error