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.

The C API

NAME

libturborel's standard interface: a C API of handles, statuses and results, and the three calls that make its shortest path, trl_connect_uri, trl_query_params and trl_result_text.

SYNOPSIS

#include <turborel/turborel.h>

trl_status trl_connect_uri(const char *uri, trl_conn **out);
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);
size_t trl_result_row_count(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);
const char *trl_result_text(trl_result *result, size_t row, size_t column);
void trl_result_free(trl_result *result);
const trl_failure *trl_conn_failure(const trl_conn *conn);
void trl_conn_free(trl_conn *conn);

DESCRIPTION

The C API is the whole of turborel/turborel.h. A program holds opaque handles: a connection, trl_conn; a result, trl_result; a prepared statement, trl_statement; and the rest that the pages of the low-level client describe. Each call answers with a trl_status: TRL_OK; TRL_FAILED, the failure kept by the handle and read by its _failure function; TRL_NO_MEMORY; or TRL_INVALID_ARGUMENT for an argument the call cannot take. Each function's comment in the header says who owns what it gives. A handle the program is given is freed by its _free function, and a borrowed pointer is valid while its handle is (RULES.md D10). A failure gives its SQLCODE, SQLSTATE, message and diagnostics, as Errors describes.

The calls a program makes most, by what each does:

To Call
Connect by a URI trl_connect_uri
Connect by settings given one by one trl_options_set, then trl_settings_resolve and trl_settings_connect (Settings)
Read why a call failed trl_conn_failure, trl_failure_sqlstate, trl_failure_message
End a connection trl_conn_terminate, then trl_conn_free
Run a statement trl_query
Run a statement with parameters given as text trl_query_params
Run a statement once with parameters given as typed values trl_query_values (Values)
Prepare a statement and execute it trl_prepare, trl_execute (Statements and Cursors)
Count a result's rows and columns, and name its columns trl_result_row_count, trl_result_column_count, trl_result_column_name
Read a value trl_result_text, or trl_result_value for the typed value (Values)
Tell the null value trl_result_text giving null, or trl_value_is_null
Count the rows a statement changed trl_conn_rows_affected
Free a result trl_result_free
Cancel a statement running trl_cancel (Connections)
Read and write large objects the large object calls (Large Objects)
PQputCopyData, PQgetCopyData the copy calls (Copy, Import and Export)
PQsetNoticeProcessor trl_conn_set_notice_handler
pipeline mode the pipeline calls (Pipelines)

trl_connect_uri connects as a turborel:// URI says. The URI is laid with the rest of a connection's settings, the environment's and the service file's among them, as trl_settings_from_uri lays it, and the connection is made by trl_settings_connect. Settings gives the URI's form. The connection is the caller's to free even when the call fails: it then holds the failure, of a URI that cannot be read as well as of a server that cannot be reached.

trl_query_params runs one statement with its ? parameters given as text, each 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 then destroyed. With no parameter it runs the statement by Query, as trl_query does. A failure is the connection's, as trl_query's is; the result is made only on TRL_OK.

trl_result_text gives a value's text, as trl_value_to_text writes it, by its row and column, both from 0. The text is made once and kept by the result, so it is valid until the result is freed. It is null for the null value, for a row or column past the last, and when memory cannot be had.

ERRORS

Each call fails as the calls it is made of fail. trl_connect_uri fails as trl_settings_from_uri and trl_settings_connect do: 08001 for a URI or a setting that cannot be read; 08006 for a server that cannot be reached, or of several servers 08001 naming each; 28000 for a user the server refuses. trl_query_params fails as trl_prepare and trl_execute do, with the server's SQLSTATE for a statement it refuses. Each returns TRL_INVALID_ARGUMENT for a null handle, statement or out, or for parameters counted but not given.

EXAMPLES

A program connects by a URI, makes a table, adds its rows with their values given as text, and reads them back:

#include <turborel/turborel.h>

#include <stdio.h>

int main(void) {
    trl_conn *conn = NULL;
    if (trl_connect_uri("turborel://ann@127.0.0.1:17438/?tls_mode=disable", &conn) != TRL_OK) {
        printf("%s %s\n", trl_failure_sqlstate(trl_conn_failure(conn)), trl_failure_message(trl_conn_failure(conn)));
        trl_conn_free(conn);
        return 1;
    }
    trl_result *result = NULL;
    trl_query(conn, "CREATE TABLE CREW (ID INTEGER, NAME VARCHAR(20))", &result);
    trl_result_free(result);
    static const char *const crew[][2] = {{"1", "Ann"}, {"2", "Bob"}, {"3", NULL}};
    for (size_t i = 0; i < 3; ++i) {
        trl_query_params(conn, "INSERT INTO CREW VALUES (?, ?)", 2, crew[i], &result);
        trl_result_free(result);
    }

    const char *const most[] = {"2"};
    if (trl_query_params(conn, "SELECT ID, NAME FROM CREW WHERE ID >= ? ORDER BY ID", 1, most, &result) == TRL_OK) {
        printf("%s %s\n", trl_result_column_name(result, 0), trl_result_column_name(result, 1));
        for (size_t row = 0; row < trl_result_row_count(result); ++row) {
            const char *name = trl_result_text(result, row, 1);
            printf("%s %s\n", trl_result_text(result, row, 0), name != NULL ? name : "(null)");
        }
    }
    trl_result_free(result);

    if (trl_query_params(conn, "SELECT ID FROM CREW WHERE ID = ?", 1, (const char *const[]){"x"}, &result) != TRL_OK) {
        printf("%s %s\n", trl_failure_sqlstate(trl_conn_failure(conn)), trl_failure_message(trl_conn_failure(conn)));
    }
    trl_result_free(result);
    trl_conn_terminate(conn);
    trl_conn_free(conn);
    return 0;
}
ID NAME
2 Bob
3 (null)
22018 'x' is not a <signed numeric literal>

A URI that names no server that answers fails, and the connection holds why:

#include <turborel/turborel.h>

#include <stdio.h>

int main(void) {
    trl_conn *conn = NULL;
    if (trl_connect_uri("turborel://ann@127.0.0.1:1/?tls_mode=disable&connect_timeout=2", &conn) != TRL_OK) {
        printf("%s\n", trl_failure_sqlstate(trl_conn_failure(conn)));
    }
    trl_conn_free(conn);
    return 0;
}
08006

STANDARD

The standard API is the driver's own (RULES.md D2). Beneath it are [CLIENT Connecting], [CLIENT Connecting by settings], [CLIENT The connection URI], [CLIENT Running statements] and [CLIENT Prepared statements]. It fulfils rows S-API-1 to S-API-8 of CONFORMANCE.md.

SEE ALSO

The ODBC Driver, Connections, Statements and Cursors, Values, Settings, Errors, Running Queries.