SQL Statement Results

Functions
size_t	M_sql_stmt_result_affected_rows (M_sql_stmt_t *stmt)
size_t	M_sql_stmt_result_num_rows (M_sql_stmt_t *stmt)
size_t	M_sql_stmt_result_total_rows (M_sql_stmt_t *stmt)
size_t	M_sql_stmt_result_num_cols (M_sql_stmt_t *stmt)
const char *	M_sql_stmt_result_col_name (M_sql_stmt_t *stmt, size_t col)
M_sql_data_type_t	M_sql_stmt_result_col_type (M_sql_stmt_t *stmt, size_t col, size_t *type_size)
M_sql_data_type_t	M_sql_stmt_result_col_type_byname (M_sql_stmt_t *stmt, const char *col, size_t *type_size)
M_bool	M_sql_stmt_result_col_idx (M_sql_stmt_t *stmt, const char *col, size_t *idx)
M_sql_error_t	M_sql_stmt_result_isnull (M_sql_stmt_t *stmt, size_t row, size_t col, M_bool *is_null)
M_sql_error_t	M_sql_stmt_result_text (M_sql_stmt_t *stmt, size_t row, size_t col, const char **text)
M_sql_error_t	M_sql_stmt_result_bool (M_sql_stmt_t *stmt, size_t row, size_t col, M_bool *val)
M_sql_error_t	M_sql_stmt_result_int16 (M_sql_stmt_t *stmt, size_t row, size_t col, M_int16 *val)
M_sql_error_t	M_sql_stmt_result_int32 (M_sql_stmt_t *stmt, size_t row, size_t col, M_int32 *val)
M_sql_error_t	M_sql_stmt_result_int64 (M_sql_stmt_t *stmt, size_t row, size_t col, M_int64 *val)
M_sql_error_t	M_sql_stmt_result_binary (M_sql_stmt_t *stmt, size_t row, size_t col, const M_uint8 **bin, size_t *bin_size)
M_bool	M_sql_stmt_result_isnull_direct (M_sql_stmt_t *stmt, size_t row, size_t col)
const char *	M_sql_stmt_result_text_direct (M_sql_stmt_t *stmt, size_t row, size_t col)
M_bool	M_sql_stmt_result_bool_direct (M_sql_stmt_t *stmt, size_t row, size_t col)
M_int16	M_sql_stmt_result_int16_direct (M_sql_stmt_t *stmt, size_t row, size_t col)
M_int32	M_sql_stmt_result_int32_direct (M_sql_stmt_t *stmt, size_t row, size_t col)
M_int64	M_sql_stmt_result_int64_direct (M_sql_stmt_t *stmt, size_t row, size_t col)
const M_uint8 *	M_sql_stmt_result_binary_direct (M_sql_stmt_t *stmt, size_t row, size_t col, size_t *bin_size)
M_sql_error_t	M_sql_stmt_result_isnull_byname (M_sql_stmt_t *stmt, size_t row, const char *col, M_bool *is_null)
M_sql_error_t	M_sql_stmt_result_text_byname (M_sql_stmt_t *stmt, size_t row, const char *col, const char **text)
M_sql_error_t	M_sql_stmt_result_bool_byname (M_sql_stmt_t *stmt, size_t row, const char *col, M_bool *val)
M_sql_error_t	M_sql_stmt_result_int16_byname (M_sql_stmt_t *stmt, size_t row, const char *col, M_int16 *val)
M_sql_error_t	M_sql_stmt_result_int32_byname (M_sql_stmt_t *stmt, size_t row, const char *col, M_int32 *val)
M_sql_error_t	M_sql_stmt_result_int64_byname (M_sql_stmt_t *stmt, size_t row, const char *col, M_int64 *val)
M_sql_error_t	M_sql_stmt_result_binary_byname (M_sql_stmt_t *stmt, size_t row, const char *col, const M_uint8 **bin, size_t *bin_size)
M_bool	M_sql_stmt_result_isnull_byname_direct (M_sql_stmt_t *stmt, size_t row, const char *col)
const char *	M_sql_stmt_result_text_byname_direct (M_sql_stmt_t *stmt, size_t row, const char *col)
M_bool	M_sql_stmt_result_bool_byname_direct (M_sql_stmt_t *stmt, size_t row, const char *col)
M_int16	M_sql_stmt_result_int16_byname_direct (M_sql_stmt_t *stmt, size_t row, const char *col)
M_int32	M_sql_stmt_result_int32_byname_direct (M_sql_stmt_t *stmt, size_t row, const char *col)
M_int64	M_sql_stmt_result_int64_byname_direct (M_sql_stmt_t *stmt, size_t row, const char *col)
const M_uint8 *	M_sql_stmt_result_binary_byname_direct (M_sql_stmt_t *stmt, size_t row, const char *col, size_t *bin_size)

Detailed Description

SQL Statement Result Processing

Function Documentation

M_sql_stmt_result_affected_rows()

size_t M_sql_stmt_result_affected_rows

(

M_sql_stmt_t *

stmt

)

Retrieve the number of rows affected by the executed statement.

Does not apply to SELECT statements, used often on UPDATE and DELETE statements to reflect how many rows were affected.

NOTE: On update, if updating a row in the database, and the passed in fields being updated are the same as the database already contains, depending on the backend database driver, that row may or may not be included.
Developers should not rely on this behavior.

Parameters

[in]

stmt

Initialized M_sql_stmt_t object.

Returns

affected rows.

M_sql_stmt_result_num_rows()

size_t M_sql_stmt_result_num_rows

(

M_sql_stmt_t *

stmt

)

Retrieve the number of cached rows in statement handle.

There may be additional rows yet to be fetched if not retrieving all rows at once. This function will return only the number of cached rows client-side, each time M_sql_stmt_fetch() is called, previous cached rows are cleared. This result is NOT cumulative.

Parameters

[in]

stmt

Initialized M_sql_stmt_t object.

Returns

row count

M_sql_stmt_result_total_rows()

size_t M_sql_stmt_result_total_rows

(

M_sql_stmt_t *

stmt

)

Retrieve the number of total rows that have been fetched so far.

This number may be greater than or equal to M_sql_stmt_result_num_rows() as each call to M_sql_stmt_fetch() will clear the current cached rows (and count), but this value will continue to increment.

Parameters

[in]

stmt

Initialized M_sql_stmt_t object.

Returns

total row count fetched so far.

M_sql_stmt_result_num_cols()

size_t M_sql_stmt_result_num_cols

(

M_sql_stmt_t *

stmt

)

Retrieve the number of columns returned from the server in response to a query.

Parameters

[in]

stmt

Initialized M_sql_stmt_t object.

Returns

column count.

M_sql_stmt_result_col_name()

const char * M_sql_stmt_result_col_name	(	M_sql_stmt_t *	stmt,
		size_t	col
	)

Retrieve the name of a returned column.

Parameters

[in]	stmt	Initialized and executed M_sql_stmt_t object.
[in]	col	Index of column.

Returns

column name or NULL on failure.

M_sql_stmt_result_col_type()

M_sql_data_type_t M_sql_stmt_result_col_type	(	M_sql_stmt_t *	stmt,
		size_t	col,
		size_t *	type_size
	)

Retrieve the data type of the returned column.

Parameters

[in]	stmt	Initialized and executed M_sql_stmt_t object.
[in]	col	Index of column.
[out]	type_size	Optional, pass NULL if not desired. For TEXT and BINARY types, the column definition may indicate a possible size (or maximum size). If the value is 0, it means the column width is bounded by the maximums of the SQL server.

Returns

Column type for referenced column.

M_sql_stmt_result_col_type_byname()

M_sql_data_type_t M_sql_stmt_result_col_type_byname	(	M_sql_stmt_t *	stmt,
		const char *	col,
		size_t *	type_size
	)

Retrieve the data type of the returned column.

Parameters

[in]	stmt	Initialized and executed M_sql_stmt_t object.
[in]	col	Name of column.
[out]	type_size	Optional, pass NULL if not desired. For TEXT and BINARY types, the column definition may indicate a possible size (or maximum size). If the value is 0, it means the column width is bounded by the maximums of the SQL server.

Returns

Column type for referenced column or M_SQL_DATA_TYPE_UNKNOWN if column not found.

M_sql_stmt_result_col_idx()

M_bool M_sql_stmt_result_col_idx	(	M_sql_stmt_t *	stmt,
		const char *	col,
		size_t *	idx
	)

Retrieve the column index by name

Parameters

[in]	stmt	Initialized and executed M_sql_stmt_t object.
[in]	col	Column name, case insensitive.
[out]	idx	Index of column.

Returns

M_TRUE on success, M_FALSE if column not found.

M_sql_stmt_result_isnull()

M_sql_error_t M_sql_stmt_result_isnull	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col,
		M_bool *	is_null
	)

Retrieve if a cell is NULL.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve
[out]	is_null	Return whether column is NULL or not.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_text()

M_sql_error_t M_sql_stmt_result_text	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col,
		const char **	text
	)

Retrieve a textual cell from the resultset.

All cell types may be retrieved in their textual form.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve
[out]	text	Output constant pointer to cell data. May be NULL if a NULL column.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_bool()

M_sql_error_t M_sql_stmt_result_bool	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col,
		M_bool *	val
	)

Retrieve a bool value from the resultset.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve
[out]	val	Output boolean value.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_int16()

M_sql_error_t M_sql_stmt_result_int16	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col,
		M_int16 *	val
	)

Retrieve a signed 16bit Integer cell from the resultset.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve
[out]	val	Output integer data. If NULL, outputs 0.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_int32()

M_sql_error_t M_sql_stmt_result_int32	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col,
		M_int32 *	val
	)

Retrieve a signed 32bit Integer cell from the resultset.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve
[out]	val	Output integer data. If NULL, outputs 0.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_int64()

M_sql_error_t M_sql_stmt_result_int64	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col,
		M_int64 *	val
	)

Retrieve a signed 64bit Integer cell from the resultset.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve
[out]	val	Output integer data. If NULL, outputs 0.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_binary()

M_sql_error_t M_sql_stmt_result_binary	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col,
		const M_uint8 **	bin,
		size_t *	bin_size
	)

Retrieve a binary cell from the resultset.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve
[out]	bin	Output constant pointer to cell data. May be NULL if a NULL column.
[out]	bin_size	Size of binary data returned.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_isnull_direct()

M_bool M_sql_stmt_result_isnull_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col
	)

Retrieve if a cell is NULL, directly, ignoring errors.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve

Returns

M_TRUE on usage failure, or if NULL cell, otherwise M_FALSE

M_sql_stmt_result_text_direct()

const char * M_sql_stmt_result_text_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col
	)

Retrieve a textual cell from the resultset, directly, ignoring errors.

All cell types may be retrieved in their textual form.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve

Returns

String result on success, or NUL on failure.

M_sql_stmt_result_bool_direct()

M_bool M_sql_stmt_result_bool_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col
	)

Retrieve a bool value from the resultset, directly, ignoring errors.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve

Returns

Return M_TRUE if data is a boolean value resulting in truth, or M_FALSE for all other cases

M_sql_stmt_result_int16_direct()

M_int16 M_sql_stmt_result_int16_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col
	)

Retrieve a signed 16bit Integer cell from the resultset, directly, ignoring errors.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve

Returns

Return integer value represented in cell, or possibly 0 on error

M_sql_stmt_result_int32_direct()

M_int32 M_sql_stmt_result_int32_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col
	)

Retrieve a signed 32bit Integer cell from the resultset, directly, ignoring errors.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve

Returns

Return integer value represented in cell, or possibly 0 on error

M_sql_stmt_result_int64_direct()

M_int64 M_sql_stmt_result_int64_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col
	)

Retrieve a signed 64bit Integer cell from the resultset, directly, ignoring errors.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve

Returns

Return integer value represented in cell, or possibly 0 on error

M_sql_stmt_result_binary_direct()

const M_uint8 * M_sql_stmt_result_binary_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		size_t	col,
		size_t *	bin_size
	)

Retrieve a binary cell from the resultset, directly, ignoring errors.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve
[out]	bin_size	Size of binary data returned.

Returns

NULL on error (not right data type), or error

M_sql_stmt_result_isnull_byname()

M_sql_error_t M_sql_stmt_result_isnull_byname	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col,
		M_bool *	is_null
	)

Retrieve if a cell is NULL (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column nameto retrieve
[out]	is_null	Return whether column is NULL or not.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_text_byname()

M_sql_error_t M_sql_stmt_result_text_byname	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col,
		const char **	text
	)

Retrieve a textual cell from the resultset (by column name).

All cell types may be retrieved in their textual form.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve
[out]	text	Output constant pointer to cell data. May be NULL if a NULL column.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_bool_byname()

M_sql_error_t M_sql_stmt_result_bool_byname	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col,
		M_bool *	val
	)

Retrieve a bool value from the resultset (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve
[out]	val	Output boolean value.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_int16_byname()

M_sql_error_t M_sql_stmt_result_int16_byname	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col,
		M_int16 *	val
	)

Retrieve a signed 16bit Integer cell from the resultset (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve
[out]	val	Output integer data.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_int32_byname()

M_sql_error_t M_sql_stmt_result_int32_byname	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col,
		M_int32 *	val
	)

Retrieve a signed 32bit Integer cell from the resultset (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve
[out]	val	Output integer data.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_int64_byname()

M_sql_error_t M_sql_stmt_result_int64_byname	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col,
		M_int64 *	val
	)

Retrieve a signed 64bit Integer cell from the resultset (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve
[out]	val	Output integer data.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_binary_byname()

M_sql_error_t M_sql_stmt_result_binary_byname	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col,
		const M_uint8 **	bin,
		size_t *	bin_size
	)

Retrieve a binary cell from the resultset (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column index to retrieve
[out]	bin	Output constant pointer to cell data. May be NULL if a NULL column.
[out]	bin_size	Size of binary data returned, maximum is 64k.

Returns

M_SQL_ERROR_SUCCESS on success, or one of M_sql_error_t errors on failure.

M_sql_stmt_result_isnull_byname_direct()

M_bool M_sql_stmt_result_isnull_byname_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col
	)

Retrieve if a cell is NULL, directly, ignoring errors (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve

Returns

M_TRUE on usage failure, or if NULL cell, otherwise M_FALSE

M_sql_stmt_result_text_byname_direct()

const char * M_sql_stmt_result_text_byname_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col
	)

Retrieve a textual cell from the resultset, directly, ignoring errors (by column name).

All cell types may be retrieved in their textual form.

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve

Returns

String result on success, or NUL on failure.

M_sql_stmt_result_bool_byname_direct()

M_bool M_sql_stmt_result_bool_byname_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col
	)

Retrieve a bool value from the resultset, directly, ignoring errors (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve

Returns

Return M_TRUE if data is a boolean value resulting in truth, or M_FALSE for all other cases

M_sql_stmt_result_int16_byname_direct()

M_int16 M_sql_stmt_result_int16_byname_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col
	)

Retrieve a signed 16bit Integer cell from the resultset, directly, ignoring errors (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve

Returns

Return integer value represented in cell, or possibly 0 on error

M_sql_stmt_result_int32_byname_direct()

M_int32 M_sql_stmt_result_int32_byname_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col
	)

Retrieve a signed 32bit Integer cell from the resultset, directly, ignoring errors (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve

Returns

Return integer value represented in cell, or possibly 0 on error

M_sql_stmt_result_int64_byname_direct()

M_int64 M_sql_stmt_result_int64_byname_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col
	)

Retrieve a signed 64bit Integer cell from the resultset, directly, ignoring errors (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve

Returns

Return integer value represented in cell, or possibly 0 on error

M_sql_stmt_result_binary_byname_direct()

const M_uint8 * M_sql_stmt_result_binary_byname_direct	(	M_sql_stmt_t *	stmt,
		size_t	row,
		const char *	col,
		size_t *	bin_size
	)

Retrieve a binary cell from the resultset, directly, ignoring errors (by column name).

Parameters

[in]	stmt	Initialized M_sql_stmt_t object.
[in]	row	Row index to retrieve
[in]	col	Column name to retrieve
[out]	bin_size	Size of binary data returned.

Returns

NULL on error (not right data type), or error