Alpha

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

Large Objects

NAME

LargeObject, ReadLOB, LOBReader, LOBWriter: large objects whole or by locator.

SYNOPSIS

const LOBInlineOctets = 64 * 1024
const LOBChunkOctets = 256 * 1024

type LargeObject interface{ Value } // LOB or Locator

func (c *Conn) ReadLOB(ctx context.Context, lob LargeObject, from, count uint64, characters bool) ([]byte, error)
func (c *Conn) NewLOBReader(ctx context.Context, lob LargeObject) *LOBReader
func (r *LOBReader) Read(out []byte) (int, error)

func (c *Conn) CreateLOB(ctx context.Context, kind LOBKind) (*LOBWriter, error)
func (w *LOBWriter) Write(octets []byte) (int, error)
func (w *LOBWriter) Flush() error
func (w *LOBWriter) Finish() (Locator, error)

func (c *Conn) FreeLOB(ctx context.Context, locator Locator) error
func (c *Conn) HoldLOB(ctx context.Context, locator Locator) error

DESCRIPTION

A large object of at most SERVER.LOB_INLINE_BYTES comes whole, a LOB; a longer one by its locator, a Locator with its lengths, valid until its transaction ends. ReadLOB sends a Lob read: at most count octets from octet from, counted from 0, or of a CLOB if characters, whole characters; the server gives at most a chunk, fewer only at the value's end or a chunk's. Of a LOB it reads the value itself. A LOBReader reads the value whole a chunk at a time, io.EOF at its length.

CreateLOB sends a Lob create; the LOBWriter sends what is written in appends of at most LOBChunkOctets, once that much waits, on Flush and on Finish, which gives the Locator, its lengths counted as written, a CLOB's characters counted once each though split between writes. The server checks a CLOB's octets as UTF-8 as each append comes, a character split between appends taken; the driver does not check them itself. FreeLOB and HoldLOB send a Lob free and hold.

A reader's and a writer's requests are cancelled on the server as the context they were made with is done.

ERRORS

SQLSTATE When
0F001 A locator that is not valid: freed, or its transaction ended
22021 An append of a CLOB whose octets are not UTF-8, checked as each append comes, or any append after one refused; the use of such a CLOB, or of one that ends within a character
22001 An append that makes the value longer than the longest
08006 SQLCODE -919: a reply of the wrong kind, or none

A LOBReader whose server sends less than the value's length fails with an error saying so.

EXAMPLES

The examples of Large Objects.

STANDARD

[PROTOCOL Lob 'L'] and [PROTOCOL Values] of The Native Protocol; [CLIENT Large objects] of The Client Library.

SEE ALSO

Values, Copy, Import and Export.