Alpha

These pages are built from turborel-c’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Statements and Cursors

This page describes how the driver gives turborel-client's statements: running a statement and its rows, a batch at a time or all at once; preparing and executing; cursors and numbered cursors; describe and deallocate; several statements in one request; what a completion tells; notices and conditions; and the session's control, autocommit, reset, change-user and query attributes. The User's Guide's Running Queries, Prepared Statements, Transactions and Errors and Diagnostics show them at work.

Results

NAME

trl_query, trl_query_params, trl_query_values, trl_query_batches, trl_result_has_rows, trl_result_column_count, trl_result_column_name, trl_result_column_not_null, trl_result_column_type, trl_result_column_type_name, trl_result_column_type_written, trl_result_row_count, trl_result_value, trl_result_text, trl_result_more, trl_result_sqlcode, trl_result_sqlstate, trl_result_free: a statement run, and what it gave.

SYNOPSIS

#include <turborel/turborel.h>

typedef void (*trl_batch_handler)(void *context, const trl_result *batch);

trl_status trl_query(trl_conn *conn, const char *sql, trl_result **out);
trl_status trl_query_params(trl_conn *conn, const char *sql, size_t count, const char *const *values,
                            trl_result **out);
trl_status trl_query_values(trl_conn *conn, const char *sql, const trl_params *params, trl_result **out);
trl_status trl_query_batches(trl_conn *conn, const char *sql, trl_batch_handler handler, void *context,
                             trl_result **out);
bool trl_result_has_rows(const trl_result *result);
size_t trl_result_column_count(const trl_result *result);
const char *trl_result_column_name(const trl_result *result, size_t column);
bool trl_result_column_not_null(const trl_result *result, size_t column);
const trl_data_type *trl_result_column_type(const trl_result *result, size_t column);
const char *trl_result_column_type_name(const trl_result *result, size_t column);
const char *trl_result_column_type_written(const trl_result *result, size_t column);
size_t trl_result_row_count(const trl_result *result);
const trl_value *trl_result_value(const trl_result *result, size_t row, size_t column);
const char *trl_result_text(trl_result *result, size_t row, size_t column);
bool trl_result_more(const trl_result *result);
int32_t trl_result_sqlcode(const trl_result *result);
const char *trl_result_sqlstate(const trl_result *result);
void trl_result_free(trl_result *result);

DESCRIPTION

trl_query sends Query, its ends set under autocommit, and reads the replies to the statement's end: a query's Description, its Rows and its Complete, or another statement's Complete [PROTOCOL Query 'Q']. The result holds the columns, every row, and the completion's SQLCODE and SQLSTATE, a query of no rows SQLCODE 100 and SQLSTATE 02000. It is the caller's, and lasts until trl_result_free, its values with it, whatever the connection does after.

trl_query_params runs a statement with its ? parameters given as text: each value a null-ended UTF-8 string, or a null pointer for the null value. The statement is prepared, executed with each value as a character string, which the server assigns to the parameter's type, and destroyed; its result is as trl_query's, and what the connection tells of the last completion, the rows it changed, the identity values it generated, its warning and its conditions, is the statement's own, not its destruction's. With no parameter it is trl_query.

trl_query_values runs a statement once with its ? parameters given as typed values, a list trl_params_new makes (Values), as trl_query_params runs one with text: prepared, executed with the list as trl_execute sends it, and destroyed, its result and the completion the connection tells as trl_query_params's. Each value is assigned to its parameter's type as it is, so octets that are not UTF-8, a JSON value's numbers and kinds, arrays, rows and multisets arrive as they were added, where text would be cast. The list is the caller's still, to run again or free. With a null or empty list it is trl_query.

trl_query_batches gives each Rows reply to handler as it comes, a batch whose rows and values last only until the handler returns, the columns the query's; its result has the columns and the completion, and no rows [CLIENT Running statements].

trl_result_has_rows says whether the statement was a query. trl_result_column_name gives a column's name, or null of one the query did not name; trl_result_column_not_null whether the server described it NOT NULL. trl_result_column_type gives a column's type, by which its values are read. With declared-types granted, which a connection asks for, the server tells the type each column was declared with [PROTOCOL Declared types]: trl_result_column_type_name gives its name as the Information Schema's DATA_TYPE gives it, as INTEGER, FLOAT or USER-DEFINED, null where the server did not tell it; trl_result_column_type_written gives the type as SQL writes it, as declared where told, as INTEGER or ANN.MONEY, else as the type's tag and sizes say, as trl_type_to_text writes it, so INTEGER is NUMERIC(10,0) [CLIENT Prepared statements]. Rows and columns are counted from 0; a place past the last gives null. trl_result_text gives a value's text, as trl_value_to_text writes it, made once and kept by the result until it is freed; null of the null value, of a place past the last, or if memory cannot be had. trl_result_more says whether a cursor's batch left rows to fetch.

ERRORS

TRL_INVALID_ARGUMENT for a null pointer, or parameters counted but not given, nothing sent. TRL_FAILED, *out null, with the connection's failure: the statement's Error, of trl_query_params and trl_query_values its preparing's or its execution's, the connection kept unless it is of class 08; or the driver's own, SQLSTATE 08006 of a connection lost, a reply out of turn ("the server sent no result", "the server broke off its rows") or a malformed one.

EXAMPLES

Running Queries runs each.

Prepared statements

NAME

trl_prepare, trl_statement_parameter_count, trl_statement_parameter_type, trl_statement_column_count, trl_statement_column_name, trl_statement_column_type, trl_statement_column_type_name, trl_statement_column_type_written, trl_statement_column_not_null, trl_execute, trl_describe, trl_deallocate, trl_statement_free: a statement prepared once and run many times.

SYNOPSIS

trl_status trl_prepare(trl_conn *conn, const char *sql, trl_statement **out);
size_t trl_statement_parameter_count(const trl_statement *statement);
const trl_data_type *trl_statement_parameter_type(const trl_statement *statement, size_t parameter);
size_t trl_statement_column_count(const trl_statement *statement);
const char *trl_statement_column_name(const trl_statement *statement, size_t column);
const trl_data_type *trl_statement_column_type(const trl_statement *statement, size_t column);
const char *trl_statement_column_type_name(const trl_statement *statement, size_t column);
const char *trl_statement_column_type_written(const trl_statement *statement, size_t column);
bool trl_statement_column_not_null(const trl_statement *statement, size_t column);
trl_status trl_execute(trl_conn *conn, const trl_statement *statement, const trl_params *params,
                       trl_result **out);
trl_status trl_describe(trl_conn *conn, const trl_statement *statement, trl_statement **out);
trl_status trl_deallocate(trl_conn *conn, const trl_statement *statement);
void trl_statement_free(trl_statement *statement);

DESCRIPTION

trl_prepare sends Prepare under a number of the connection's own, each statement prepared taking the next, so no statement of the session is replaced, nor one whose cursor is open; Prepared gives its parameters, a statement's inputs alone, and its columns [PROTOCOL Prepare 'P'] [PROTOCOL Prepared 'P']. A CALL's columns are one for each ? of an OUT or INOUT parameter, in the procedure's parameter order, named and typed as each; an INOUT ? is both a parameter and a column. trl_statement_column_type_name and trl_statement_column_type_written give a column's declared type, and trl_statement_column_not_null whether it is NOT NULL, as their trl_result_ likes do.

trl_execute sends Execute, cursor 0, with params, null for none, its ends set under autocommit, and reads its replies as trl_query does, every row kept: a query's Rows with no Description, its columns those Prepared gave; a CALL's one row of its OUT and INOUT parameters' values; another statement's Complete [PROTOCOL Execute 'E']. A statement is valid across transactions, until it is deallocated or the session reset.

trl_describe sends Describe of the statement, answered by Prepared, and gives a new statement of the same number [PROTOCOL Describe 'Y']; it needs describe. trl_deallocate sends Deallocate [PROTOCOL Deallocate 'D']. trl_statement_free frees the handle alone, sending nothing.

ERRORS

As trl_query's; and "the server sent no Prepared". SQLSTATE 26000 of a statement deallocated or unknown to the server, 24000 of one whose cursor is open deallocated. trl_describe without describe gives SQLSTATE 08006, sending nothing, the connection kept.

EXAMPLES

Prepared Statements runs each.

Cursors

NAME

trl_cursor, trl_cursor_open, trl_cursor_fetch, trl_cursor_close, trl_describe_cursor: a query's rows read in parts.

SYNOPSIS

typedef struct trl_cursor {
    const trl_statement *statement;
    uint32_t number;
} trl_cursor;

trl_status trl_cursor_open(trl_conn *conn, trl_cursor cursor, const trl_params *params, uint32_t rows,
                           trl_result **out);
trl_status trl_cursor_fetch(trl_conn *conn, trl_cursor cursor, uint32_t rows, trl_result **out);
trl_status trl_cursor_close(trl_conn *conn, trl_cursor cursor);
trl_status trl_describe_cursor(trl_conn *conn, trl_cursor cursor, trl_result **out);

DESCRIPTION

A cursor is a prepared statement and a number, 0 unless the server granted cursors, with which a statement has several open at once. trl_cursor_open sends Execute of at most rows rows, tail 3 naming the cursor if it is not 0; its batch's trl_result_more says whether Suspended left the cursor open with more, else Complete closed it [PROTOCOL Execute 'E']. trl_cursor_fetch sends Fetch of the next batch [PROTOCOL Fetch 'F'], and trl_cursor_close sends Close [PROTOCOL Close 'C']. trl_describe_cursor sends Describe of an open cursor, answered by Description, and gives a result of its columns and no rows [PROTOCOL Describe 'Y'].

A cursor left open keeps its transaction. Under autocommit with fetch-ends, Execute and Fetch end the transaction as the cursor ends: the fetch of the last row commits, a failure rolls back, and Close commits [CLIENT What the server tells].

ERRORS

As trl_execute's. SQLSTATE 24000 of a cursor opened that is open, or fetched or closed that is not. A cursor numbered other than 0 without cursors, or a cursor described without describe, gives SQLSTATE 08006, sending nothing, the connection kept.

EXAMPLES

Prepared Statements and Transactions run each.

Several statements

NAME

trl_query_many, trl_ran_count, trl_ran_result, trl_ran_failure, trl_ran_free: several statements as one request.

SYNOPSIS

trl_status trl_query_many(trl_conn *conn, const char *sql, trl_ran **out);
size_t trl_ran_count(const trl_ran *ran);
const trl_result *trl_ran_result(const trl_ran *ran, size_t index);
const trl_failure *trl_ran_failure(const trl_ran *ran);
void trl_ran_free(trl_ran *ran);

DESCRIPTION

trl_query_many sends Query with tail 2, multi: the statements run one by one, ends applying to each, each Complete but the last marked by tail 5, and the first failure's Error ends the replies [PROTOCOL Query 'Q']. It gives each outcome before the failure, in order, and the failure, or null if every statement succeeded [CLIENT Controlling the session].

ERRORS

TRL_FAILED without multi-statement, sending nothing, SQLSTATE 08006, the connection kept; and as trl_query's of a connection lost. A statement's failure is not the call's: trl_ran_failure gives it.

EXAMPLES

Running Queries runs it.

What a completion tells

NAME

trl_conn_autocommit, trl_conn_set_autocommit, trl_conn_in_transaction, trl_conn_warning, trl_conn_rows_affected, trl_conn_generated_count, trl_conn_generated_at, trl_conn_server_time, trl_conn_commit_position, trl_conn_condition_count, trl_conn_condition_at, trl_conn_clear_conditions: the session's transaction, and what the last statement's completion told.

SYNOPSIS

typedef struct trl_timing {
    uint64_t total;
    uint64_t queued;
    uint64_t locks;
} trl_timing;

trl_status trl_conn_set_autocommit(trl_conn *conn, bool on);
bool trl_conn_autocommit(const trl_conn *conn);
bool trl_conn_in_transaction(const trl_conn *conn);
const char *trl_conn_warning(const trl_conn *conn);
bool trl_conn_rows_affected(const trl_conn *conn, uint64_t *rows);
size_t trl_conn_generated_count(const trl_conn *conn);
const char *trl_conn_generated_at(const trl_conn *conn, size_t index);
bool trl_conn_server_time(const trl_conn *conn, trl_timing *timing);
bool trl_conn_commit_position(const trl_conn *conn, uint64_t *position);
size_t trl_conn_condition_count(const trl_conn *conn);
const trl_failure *trl_conn_condition_at(const trl_conn *conn, size_t index);
void trl_conn_clear_conditions(trl_conn *conn);

DESCRIPTION

Under autocommit each statement is sent with ends, committed as it succeeds and rolled back as it fails [CLIENT Running statements]. trl_conn_in_transaction gives whether the session's transaction is active, as the last reply that told it said.

Each Complete replaces what the last told [PROTOCOL Complete 'K']. With row-counts, tag 6 is the rows a statement changed, or a query's rows in all, and tag 18 the server's time in microseconds, in all, queued and waiting for locks; with generated-values, tag 16 is each identity value an INSERT generated, as SQL writes it, in the order of its rows; with conditions, tag 17 is each condition the statement raised; trl_conn_clear_conditions drops them, as turborel-client's take_conditions takes them, so a program that tells them after each statement tells each once. trl_conn_commit_position gives tag 4, the log position of the last commit, with commit-position, kept until a later commit tells another. trl_conn_warning gives the completion's SQLSTATE if it is of class 01, else null. Each function that gives a bool gives whether it was told.

ERRORS

trl_conn_set_autocommit gives TRL_INVALID_ARGUMENT of a null connection; the rest give 0, false or null of one, and trl_conn_clear_conditions does nothing.

EXAMPLES

Running Queries and Transactions run each.

Notices

NAME

trl_notice_handler, trl_conn_set_notice_handler, trl_conn_notice_count, trl_conn_notice_at, trl_conn_clear_notices: the notices the server sends.

SYNOPSIS

typedef void (*trl_notice_handler)(void *context, const trl_failure *notice);

trl_status trl_conn_set_notice_handler(trl_conn *conn, trl_notice_handler handler, void *context);
size_t trl_conn_notice_count(const trl_conn *conn);
const trl_failure *trl_conn_notice_at(const trl_conn *conn, size_t index);
void trl_conn_clear_notices(trl_conn *conn);

DESCRIPTION

A Notice is given to the handler as it is read, within the call that read it, the failure valid until the handler returns; with no handler, the last 64 are kept, the oldest dropped first, until cleared [CLIENT What the server tells]. A statement's conditions come as Notices where conditions was not granted, and a failing statement's always; the server's own notices, as 01T01 of a transaction Reset or ChangeUser rolled back, always [PROTOCOL Errors and notices]. A null handler keeps notices again.

ERRORS

TRL_INVALID_ARGUMENT of a null connection.

EXAMPLES

Errors and Diagnostics runs each.

The session's control

NAME

trl_conn_reset, trl_conn_change_user, trl_conn_set_query_attributes: a session renewed, made another user's, or its statements given attributes.

SYNOPSIS

trl_status trl_conn_reset(trl_conn *conn);
trl_status trl_conn_change_user(trl_conn *conn, const char *user, trl_mechanism *mechanism);
trl_status trl_conn_set_query_attributes(trl_conn *conn, const char *const *names, const char *const *values,
                                         size_t count);

DESCRIPTION

trl_conn_reset sends Reset: the transaction rolled back, told by a Notice 01T01 if one was active; the prepared statements, cursors, a copy, temporary tables and settings gone, a Status of each setting told; the authentication and the cancel key kept; then a Complete saying no transaction is active [PROTOCOL Reset 'W']. It needs reset.

trl_conn_change_user sends ChangeUser with the mechanism's first bytes, then answers each Challenge as a login does. Accepted, the session is renewed as by Reset, under a new cancel key, and Ready tells the new authorization; refused, the connection fails [PROTOCOL ChangeUser 'U']. It needs change-user. The mechanism serves one exchange at a time, as at login.

trl_conn_set_query_attributes sets the attributes every later Query and Execute carries in tail 1, with query-attributes, until it is called again; a count of 0 clears them, needing nothing granted [CLIENT Controlling the session]. Names and values are copied.

ERRORS

TRL_INVALID_ARGUMENT of a null pointer. TRL_FAILED with SQLSTATE 08006, sending nothing, the connection kept, without the capability, or of attributes past their bounds: more than 32, a name empty or longer than 64 bytes, a value longer than 1024, or either not UTF-8 [PROTOCOL The tail]. ChangeUser refused fails with the server's Error, of class 28, and loses the connection.

EXAMPLES

Transactions runs each.

STANDARD

[CLIENT Running statements], [CLIENT Prepared statements], [CLIENT What the server tells], [CLIENT Controlling the session], and the sections of [PROTOCOL Conversations] each section names.

SEE ALSO

Values, Errors, Connections