Alpha

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

Appendix A: Types

How each data type and value of the native protocol is given in C# ([PROTOCOL Data types] and [PROTOCOL Values] of The Native Protocol). The codec reads and writes every one of them; the types it gives are the driver's own, of the namespace Turborel.Data.Types, or .NET's where one holds a value whole (Values). A value read from a server is checked against the bounds below. A frame that is itself malformed, cut short or with bytes after its last field, fails the connection, SQLCODE -919 and SQLSTATE 08006. A value the client cannot take in a frame read whole, a units or truth octet other than 0 or 1, damaged JSON, a Complete's condition that cannot be read, or value tags 18 and 19, fails its request alone, SQLCODE -916 and SQLSTATE TB916, or of JSON past Turborel's limits -900 and 0A000; the rest of the request's replies are read past first, and the connection goes on, as turborel-client takes it ([PROTOCOL Values and fields]).

Value tags 5, 7, 10 and 12 are read as tags 1, 6, 9 and 11, as turborel-protocol's reader takes them: CHARACTER VARYING as CHARACTER, BINARY VARYING as BINARY, TIME WITH TIME ZONE as TIME, and TIMESTAMP WITH TIME ZONE as TIMESTAMP; the page lists only 1, 6, 9 and 11 as value tags.

Values

Tag Value C# Bounds
0 null null (DBNull is sent as null)
1 character string string UTF-8 on the wire; tag 5 is read as tag 1
2 exact number TurborelDecimal: Int128 units, uint scale the whole i128 range and every scale, with no loss; gives a decimal where 96 bits and a scale of 28 hold it
3 approximate number double its bits kept, NaN and -0.0 among them
4 a plug-in's value TurborelPluginValue: the type's name, the text, the bytes kept, and sent back, unchanged
6 binary string byte[] tag 7 is read as tag 6
8, 9, 11 date, time, timestamp TurborelDatetime: moment, UTC microseconds from 0001-01-01 00:00:00 (a date its midnight's, a time from midnight UTC, within a day), displacement in minutes, zoned, precision a displacement that fits an i16, -12:59 to +14:00 as the server sends it; tags 10 and 12 are read as 9 and 11
13 interval TurborelInterval: qualifier and Int128 units fields 0 YEAR to 5 SECOND; months of a year-month interval, microseconds of a day-time one
14 truth value bool 0 or 1; unknown is null
15 DECFLOAT TurborelDecFloat: Int128 coefficient, int exponent at most 34 digits, no trailing zero, an adjusted exponent of -6143 to 6144
16 array TurborelArray nested at most 16 deep
17 row TurborelRow nested at most 16 deep
20, 21 large object TurborelLargeObject: whole, its octets, or by its locator and lengths a character one's octets UTF-8
22 multiset TurborelMultiset at most 65,535 elements
23 structured value TurborelStructuredValue: its type's schema and name, its attributes nested at most 16 deep
24 reference TurborelReference, its octets
25 JSON TurborelJson: the stored form, read as an item or JSON text, made from JSON text checked whole: every node, string, offset and directory; nested at most 128 deep
26 XML TurborelXml, its serialization as CONTENT
27 UUID Guid 16 octets, in RFC 4122's order

A value of another .NET type is refused before it is sent, SQLCODE -301 and SQLSTATE 22000, the drivers' code for a value the protocol cannot carry.

Data types

Tag Type C#, of DataType
1, 5 CHARACTER, CHARACTER VARYING CharacterType: length, units, varying
2 exact numeric ExactType: precision, scale
3 approximate numeric ApproximateType: precision
4 a plug-in's type PluginType: name, at most 2 parameters
6, 7 BINARY, BINARY VARYING BinaryType: length, varying
8 to 12 DATE, TIME, TIME WITH TIME ZONE, TIMESTAMP, TIMESTAMP WITH TIME ZONE DatetimeType: moment, zoned, precision
13 INTERVAL IntervalType: qualifier
14 BOOLEAN BooleanType
15 DECFLOAT DecFloatType: precision
16 array ArrayType: maximum cardinality, 1 to 65,535, and element type
17 row RowType: its fields, one at least
18, 19 CHARACTER and BINARY LARGE OBJECT LargeObjectType: kind, length, units
22 multiset MultisetType: element type
23 structured type StructuredType: name and proper supertypes
24 reference type ReferenceType: the referenced type and its scope
25 JSON JsonType
26 XML XmlType: primary and secondary modifiers, and the schema of XMLSCHEMA
27 UUID UuidType

A distinct type comes as its source type, and a plug-in's type the driver does not have is read by its name, its values shown by their text.

In the standard API

A TurborelDataReader's GetValue gives each column as .NET's type of its data type, as the server declared it where it told it (declared-types), the type GetFieldType names; GetDataTypeName is the column's type as SQL writes it, as it was declared; GetProviderSpecificValue gives the value above as it is (RULES.md D18).

Data type GetValue
CHARACTER, CHARACTER VARYING, JSON, XML string, JSON as its text, XML as its serialization
SMALLINT, INTEGER, BIGINT, as the server declares them short, int, long
REAL, as the server declares it float
exact numeric decimal, or the TurborelDecimal where a decimal cannot hold it
approximate numeric double
BINARY, BINARY VARYING byte[]
BOOLEAN bool
UUID Guid
DATE, TIMESTAMP DateTime of its fields, DateTimeKind.Unspecified
TIMESTAMP WITH TIME ZONE DateTimeOffset
TIME TimeSpan, the time of day
INTERVAL of days to seconds TimeSpan, where it holds it; else the TurborelInterval
TIME WITH TIME ZONE TurborelDatetime
INTERVAL of years and months TurborelInterval
DECFLOAT, large objects, arrays, rows, multisets, structured types, references, a plug-in's types the driver's type above
the null value DBNull.Value

A parameter's value is sent by its .NET type (TurborelParameter).