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.

Appendix A: Types

This appendix maps every data type and value tag of the native protocol, 1 to 27, to the C type the driver gives and takes, with the bounds of each, such as the exact number's units and scale, a timestamp's displacement and an interval's qualifier.

The driver reads and writes every type and value below, with the bounds given; a reply that breaks one fails the connection, SQLCODE -919, SQLSTATE 08006. Values gives the functions that read each value, and those that make each parameter.

Data types

Tag Type What it carries
1 CHARACTER length uint32_t; units 0 characters or 1 octets
2 exact numeric precision and scale, uint32_t
3 approximate numeric precision uint32_t
4 a plug-in's type its name, UTF-8; at most 2 parameters, uint32_t
5 CHARACTER VARYING as CHARACTER
6, 7 BINARY, BINARY VARYING length uint32_t
8 to 12 DATE, TIME, TIME WITH TIME ZONE, TIMESTAMP, TIMESTAMP WITH TIME ZONE precision uint32_t
13 INTERVAL start and end fields, 0 YEAR, 1 MONTH, 2 DAY, 3 HOUR, 4 MINUTE, 5 SECOND; leading and fractional precision
14 BOOLEAN nothing
15 DECFLOAT precision uint32_t
16 array maximum cardinality, 1 to 65535; element type
17 row one or more fields, each a name and a type
18, 19 CLOB, BLOB length uint64_t; units
22 multiset element type
23 structured type its schema and name; its proper supertypes
24 reference type the referenced type's names; its scope, if scoped
25 JSON nothing
26 XML primary modifier DOCUMENT, CONTENT or SEQUENCE; secondary UNTYPED, ANY or XMLSCHEMA, and of XMLSCHEMA the schema's names, its namespace and element if named; SEQUENCE is untyped
27 UUID nothing

Arrays, rows and multisets nest at most 16 deep, as turborel's types do.

Values

Tag Value C type Bounds
0 null none
1 character string UTF-8 bytes and their length UTF-8
2 exact number trl_decimal units the whole of trl_int128; scale the whole of uint32_t
3 approximate number double, its 64 bits kept every bit kept: NaN, -0.0 and the infinities too
4 a plug-in's value its type's name, its text, its bytes kept and sent back unchanged
6 binary string bytes and their length
8, 9, 11 date, time, timestamp trl_datetime: zoned bool, precision uint8_t, displacement in minutes int16_t, instant in UTC microseconds int64_t a displacement of 16 bits
5, 7, 10, 12 the types' own tags read as 1, 6, 9 and 11, as turborel-protocol's reader takes them: a character string, a binary string, a time and a timestamp, a zone told inside; the driver sends only 1, 6, 9 and 11
13 interval trl_interval: its qualifier, then units trl_int128: months of a year-month interval, microseconds of a day-time one fields 0 to 5
14 truth value bool 0 or 1; unknown is null
15 DECFLOAT trl_decfloat: coefficient trl_int128, exponent int32_t canonical: at most 34 digits, no trailing zero, zero of exponent 0, adjusted exponent -6143 to 6144
16, 17 array, row a list of values nested at most 16 deep
20 large object whole kind, character or binary; its octets a character one's UTF-8
18, 19 a large object's stored form, which no server sends refused: the statement fails, SQLCODE -916, SQLSTATE TB916, the connection kept (RULES.md D8)
21 large object by locator kind; locator uint32_t; octets and characters uint64_t
22 multiset a list of values at most 65535 elements
23 structured value its type's schema and name; its attributes
24 reference bytes
25 JSON the stored form of turborel's RULES.md D89, written as JSON text and made from it checked whole; nested at most 128 deep
26 XML its serialization as CONTENT, UTF-8
27 UUID 16 octets exactly 16

A JSON value's text is written as turborel writes it: no white space, members in the order written, an exact number's digits, a DECFLOAT plain, an approximate number as its shortest numeral with an exponent. A datetime within a JSON value, or an approximate number that is not finite, has no JSON text: SQLSTATE 22032. A JSON text made into a value takes a number without an exponent as exact, one of more digits than an exact number holds as a DECFLOAT, and one with an exponent as approximate; a number none of them holds exactly is SQLSTATE 22003.