# gizlang:odbc

Thin ODBC driver boundary. SQL semantics and planning belong to the data layer. Exact text/binary cells, bounded forward cursors, explicit transactions, no retries.

```gizlang
import * as Odbc from "gizlang:odbc";
```

## Types

### `OdbcError`

```gizlang
type OdbcError = { sqlstate: string; code: i64; message: string; }
```

An ODBC failure: its SQLSTATE, native code and message.

- `sqlstate`: `string`
- `code`: `i64`
- `message`: `string`

### `Column`

```gizlang
type Column = { name: string; sqlType: i64; precision: i64; scale: i64; nullable: bool; }
```

A result column of an ODBC statement: its name, SQL type, precision, scale and whether it may be NULL.

- `name`: `string`
- `sqlType`: `i64`
- `precision`: `i64`
- `scale`: `i64`
- `nullable`: `bool`

### `Parameter`

```gizlang
type Parameter = { sqlType: i64; precision: i64; scale: i64; binary: bool; value: Option<bytes>; }
```

A parameter of an ODBC statement: its SQL type, precision, scale, whether it is binary, and its value (none for NULL).

- `sqlType`: `i64`
- `precision`: `i64`
- `scale`: `i64`
- `binary`: `bool`
- `value`: `_gizlang_sdk_core.Option<bytes>`

### `Cell`

```gizlang
type Cell = | { kind: "null"; } | { kind: "text"; value: string; } | { kind: "binary"; value: bytes; }
```

One cell of an ODBC result: NULL, text or binary.

- `null`
- `text`
- `binary`

### `Page`

```gizlang
type Page = { rows: Vec<Vec<Cell>>; done: bool; }
```

A page of ODBC result rows, and whether it is the last.

- `rows`: `Vec<Vec<gizlang_odbc.Cell>>`
- `done`: `bool`

### `Capabilities`

```gizlang
type Capabilities = { write: bool; transaction: bool; cancel: bool; }
```

What an ODBC data source supports: writes, transactions and cancelling a statement.

- `write`: `bool`
- `transaction`: `bool`
- `cancel`: `bool`

### `Connection`

```gizlang
type Connection
```

A connection to an ODBC data source.

Opaque: create and use it through this module's functions.

### `Cursor`

```gizlang
type Cursor
```

An open result of an ODBC statement, read page by page.

- `connection`: `gizlang_odbc.Connection`
- `columns`: `Vec<gizlang_odbc.Column>`
- `cellBytes`: `i64`

## Functions

### `open`

```gizlang
function open(sys: System, connectionString: string): Connection throws OdbcError
```

Driver-specific connection strings remain at this explicit external boundary.

Effects: fail, read, write, io.

## Methods

### `Connection.prepare`

```gizlang
function Connection.prepare(self: Connection, sql: string, params: Vec<Parameter>, cellBytes: i64): Cursor throws OdbcError
```

SQL prepared once with its parameter types PARAMS; each result cell is read into at most CELLBYTES bytes.

Effects: fail, read, write, io.

### `Connection.capabilities`

```gizlang
function Connection.capabilities(self: Connection): Capabilities throws OdbcError
```

Driver-reported facts, not abilities inferred from the connection's spelling.

Effects: fail, read, io.

### `Cursor.poll`

```gizlang
function Cursor.poll(self: Cursor, rows: i64, bytes: i64): Page throws OdbcError
```

Admission precedes SQLFetch; this page never retains more than rowBytes * rows.

Effects: fail, read, write, io.

### `Cursor.affected`

```gizlang
function Cursor.affected(self: Cursor): i64 throws OdbcError
```

The number of rows that the statement changed (SQLRowCount).

Effects: fail, read, io.

### `Cursor.cancel`

```gizlang
function Cursor.cancel(self: Cursor): bool throws OdbcError
```

Asks the driver to stop the statement that runs (SQLCancel).

Effects: fail, read, io.

### `Cursor.close`

```gizlang
function Cursor.close(self: Cursor): bool
```

Frees the statement. It does nothing after the first call.

Effects: fail, read, write, io.

### `Connection.begin`

```gizlang
function Connection.begin(self: Connection): bool throws OdbcError
```

Starts a transaction: autocommit is off until `end`.

Effects: fail, read, write, io.

### `Connection.end`

```gizlang
function Connection.end(self: Connection, commit: bool): bool throws OdbcError
```

Ends the transaction: it commits when COMMIT, else rolls back; autocommit is on again.

Effects: fail, read, write, io.

### `Connection.close`

```gizlang
function Connection.close(self: Connection): bool
```

Disconnects and frees the connection. It does nothing after the first call.

Effects: fail, read, write, io.