Result Set

Functions
int	kdbc_next (kdbc_result *rs)
	Advance to the next row.
int	kdbc_col_count (kdbc_result *rs)
	Get the number of columns in the result set.
const char *	kdbc_col_name (kdbc_result *rs, int col)
	Get a column name by index.
const char *	kdbc_col_label (kdbc_result *rs, int col)
	Get a column label (alias) by index.
int	kdbc_is_null (kdbc_result *rs, int col)
	Check if a column value is NULL.
int64_t	kdbc_get_long (kdbc_result *rs, int col)
	Get a column value as a 64-bit integer.
double	kdbc_get_double (kdbc_result *rs, int col)
	Get a column value as a double.
const char *	kdbc_get_string (kdbc_result *rs, int col)
	Get a column value as a UTF-8 string.
const void *	kdbc_get_blob (kdbc_result *rs, int col, size_t *out_len)
	Get a column value as a binary blob.
int	kdbc_get_timestamp (kdbc_result *rs, int col, int *year, int *month, int *day, int *hour, int *minute, int *second, int *usec)
	Get a column value as a timestamp (date + time).
int	kdbc_get_date (kdbc_result *rs, int col, int *year, int *month, int *day)
	Get a column value as a date (no time component).
int	kdbc_get_time (kdbc_result *rs, int col, int *hour, int *minute, int *second, int *usec)
	Get a column value as a time (no date component).
void	kdbc_result_close (kdbc_result *rs)
	Close a result set and free resources.

Detailed Description

Navigate rows and retrieve column values from query results.

All column indices are 1-indexed. String and blob pointers are valid until the next kdbc_next() call or kdbc_result_close().

kdbc_result *rs = kdbc_execute_query(conn, "SELECT id, name FROM users");
while (kdbc_next(rs) == 1) {
    int64_t id = kdbc_get_long(rs, 1);
    const char *name = kdbc_get_string(rs, 2);
    if (!kdbc_is_null(rs, 2))
        printf("%lld: %s\n", (long long)id, name);
}
kdbc_result_close(rs);

Function Documentation

kdbc_next()

int kdbc_next

(

kdbc_result *

rs

)

Advance to the next row.

Parameters

rs	A result set.

Returns

1 if a row is available, 0 if no more rows, KDBC_ERROR on failure.

kdbc_col_count()

int kdbc_col_count

(

kdbc_result *

rs

)

Get the number of columns in the result set.

Parameters

rs	A result set.

Returns

Column count.

kdbc_col_name()

const char * kdbc_col_name	(	kdbc_result *	rs,
		int	col )

Get a column name by index.

Parameters

rs	A result set.
col	Column index (1-indexed).

Returns

Column name, or NULL if index is invalid.

kdbc_col_label()

const char * kdbc_col_label	(	kdbc_result *	rs,
		int	col )

Get a column label (alias) by index.

Falls back to the column name if no alias was specified in the query.

Parameters

rs	A result set.
col	Column index (1-indexed).

Returns

Column label, or NULL if index is invalid.

kdbc_is_null()

int kdbc_is_null	(	kdbc_result *	rs,
		int	col )

Check if a column value is NULL.

Call this after a kdbc_get_* function to distinguish NULL from zero or empty string.

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).

Returns

1 if the value is NULL, 0 otherwise.

kdbc_get_long()

int64_t kdbc_get_long	(	kdbc_result *	rs,
		int	col )

Get a column value as a 64-bit integer.

For type mismatches, reasonable conversions are attempted. Check kdbc_is_null() to distinguish NULL from 0.

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).

Returns

The integer value (0 if NULL or conversion failed).

kdbc_get_double()

double kdbc_get_double	(	kdbc_result *	rs,
		int	col )

Get a column value as a double.

Check kdbc_is_null() to distinguish NULL from 0.0.

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).

Returns

The double value (0.0 if NULL or conversion failed).

kdbc_get_string()

const char * kdbc_get_string	(	kdbc_result *	rs,
		int	col )

Get a column value as a UTF-8 string.

The returned pointer is valid until the next kdbc_next() call or kdbc_result_close().

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).

Returns

The string value, or NULL if the column is NULL.

kdbc_get_blob()

const void * kdbc_get_blob	(	kdbc_result *	rs,
		int	col,
		size_t *	out_len )

Get a column value as a binary blob.

The returned pointer is valid until the next kdbc_next() call or kdbc_result_close().

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).
out_len	Output: blob size in bytes.

Returns

Pointer to the blob data, or NULL if the column is NULL.

kdbc_get_timestamp()

int kdbc_get_timestamp	(	kdbc_result *	rs,
		int	col,
		int *	year,
		int *	month,
		int *	day,
		int *	hour,
		int *	minute,
		int *	second,
		int *	usec )

Get a column value as a timestamp (date + time).

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).
year	Output: year.
month	Output: month (1–12).
day	Output: day (1–31).
hour	Output: hour (0–23).
minute	Output: minute (0–59).
second	Output: second (0–59).
usec	Output: microseconds (0–999999).

Returns

KDBC_OK on success, KDBC_ERROR if NULL or conversion failed.

kdbc_get_date()

int kdbc_get_date	(	kdbc_result *	rs,
		int	col,
		int *	year,
		int *	month,
		int *	day )

Get a column value as a date (no time component).

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).
year	Output: year.
month	Output: month (1–12).
day	Output: day (1–31).

Returns

KDBC_OK on success, KDBC_ERROR if NULL or conversion failed.

kdbc_get_time()

int kdbc_get_time	(	kdbc_result *	rs,
		int	col,
		int *	hour,
		int *	minute,
		int *	second,
		int *	usec )

Get a column value as a time (no date component).

Parameters

rs	A result set (positioned on a row).
col	Column index (1-indexed).
hour	Output: hour (0–23).
minute	Output: minute (0–59).
second	Output: second (0–59).
usec	Output: microseconds (0–999999).

Returns

KDBC_OK on success, KDBC_ERROR if NULL or conversion failed.

kdbc_result_close()

void kdbc_result_close

(

kdbc_result *

rs

)

Close a result set and free resources.

Safe to call with NULL (no-op).

Parameters

rs	The result set to close, or NULL.