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.

Large Objects

Values and ranges

NAME

trl_lob_info, trl_lob_range, trl_value_lob, trl_lob_read: a large object value, whole or by its locator, and a range of it read.

SYNOPSIS

#include <turborel/turborel.h>

#define TRL_LOB_CHUNK_BYTES 262144
#define TRL_LOB_INLINE_BYTES 65536

typedef struct trl_lob_info {
    bool character;
    bool located;
    uint64_t octets;
    uint64_t characters;
} trl_lob_info;

typedef struct trl_lob_range {
    uint64_t from;
    uint64_t count;
    bool characters;
} trl_lob_range;

trl_status trl_value_lob(const trl_value *value, trl_lob_info *out);
trl_status trl_lob_read(trl_conn *conn, const trl_value *lob, trl_lob_range range, uint8_t *out, size_t *length);

DESCRIPTION

A CLOB or BLOB value of at most SERVER.LOB_INLINE_BYTES, 64 KiB by default, comes whole in its row, value tag 20; a longer one as its locator and lengths, tag 21 [PROTOCOL Values]. trl_value_lob says which, whether it is a character large object, and its octets and, of a character one, its characters [CLIENT Large objects].

trl_lob_read reads a range: of a value whole, from the value; of one by its locator, by a Lob read, at most TRL_LOB_CHUNK_BYTES [PROTOCOL Lob 'L']. The range counts octets from 0, or, with characters, whole characters of a character large object. *length holds the octets out has room for on entry, and those read on return; a range in characters reads at most a quarter as many characters as out holds octets. Fewer than asked come only at the object's end, or a chunk's.

ERRORS

TRL_INVALID_ARGUMENT for a null pointer, a value of another kind, or out too short for one octet or character, nothing sent. TRL_FAILED with the connection's failure: SQLSTATE 0F001 of a locator no longer valid, the connection kept; SQLSTATE 08006 of the connection lost or a reply out of turn.

EXAMPLES

Large Objects reads each.

Readers

NAME

trl_lob_reader, trl_lob_reader_new, trl_lob_reader_read, trl_lob_reader_free: a large object read from its beginning to its end.

SYNOPSIS

trl_status trl_lob_reader_new(trl_conn *conn, const trl_value *lob, trl_lob_reader **out);
trl_status trl_lob_reader_read(trl_lob_reader *reader, uint8_t *out, size_t capacity, size_t *length);
void trl_lob_reader_free(trl_lob_reader *reader);

DESCRIPTION

A reader copies the value and reads it a chunk a request, so memory holds a chunk whatever its length; it uses the connection until freed, and is the caller's to free. trl_lob_reader_read reads at most capacity octets, *length 0 at the end.

ERRORS

TRL_INVALID_ARGUMENT for a null pointer or a value of another kind; TRL_NO_MEMORY. TRL_FAILED with the connection's failure, as trl_lob_read fails, or SQLSTATE 22000 of a server that sent less than the value's length.

Locators

NAME

trl_lob_free_locator, trl_lob_hold: a locator freed, or kept past its transaction.

SYNOPSIS

trl_status trl_lob_free_locator(trl_conn *conn, const trl_value *lob);
trl_status trl_lob_hold(trl_conn *conn, const trl_value *lob);

DESCRIPTION

A locator is valid until its transaction ends. trl_lob_free_locator frees it, and the value it names, by a Lob free; trl_lob_hold keeps it valid past its transaction's commit, until it is freed or a transaction is rolled back, by a Lob hold [PROTOCOL Lob 'L'].

ERRORS

TRL_INVALID_ARGUMENT for a null pointer or a value of another kind. TRL_FAILED with the connection's failure: SQLSTATE 22000 of a large object that came whole, which has no locator, nothing sent; SQLSTATE 0F001 of a locator not valid.

Writers

NAME

trl_lob_writer, trl_lob_writer_new, trl_lob_write, trl_lob_writer_finish, trl_lob_writer_free: a new large object written a piece at a time.

SYNOPSIS

trl_status trl_lob_writer_new(trl_conn *conn, bool character, trl_lob_writer **out);
trl_status trl_lob_write(trl_lob_writer *writer, const uint8_t *bytes, size_t length);
trl_status trl_lob_writer_finish(trl_lob_writer *writer, trl_params *params);
void trl_lob_writer_free(trl_lob_writer *writer);

DESCRIPTION

trl_lob_writer_new creates an empty large object on the server by a Lob create, a character one if character, its octets UTF-8. trl_lob_write sends what it is given by Lob appends of a chunk as it comes, a character large object's chunk cut where a character ends, so a write may end within a character; the server checks a character large object's octets as UTF-8 as each Append comes. trl_lob_writer_finish sends the rest and adds the object to params as its next value, by its locator, valid until its transaction ends and used once [PROTOCOL Lob 'L']. A writer uses the connection until freed; one not finished leaves its object to its transaction's end.

ERRORS

TRL_INVALID_ARGUMENT for a null pointer, or a writer finished; TRL_NO_MEMORY. TRL_FAILED with the connection's failure: SQLSTATE 22021 of a character large object whose octets an Append sent are not UTF-8, every later Append then refused; a character large object that ends within a character is refused, SQLSTATE 22021, where it is used.

EXAMPLES

Large Objects writes one.