DB(7) DB(7)
NAME
DB - database support
SYNOPSIS
include "security.m"; # need Auth for algorithm names
include "db.m";
db := load DB DB->PATH;
DB_Handle: adt {
SQLOpen: fn(oldh: self ref DB_Handle): (int, ref DB_Handle);
SQLClose: fn(dbh: self ref DB_Handle): int;
SQL: fn(handle: self ref DB_Handle, command: string):
(int, string);
columns: fn(handle: self ref DB_Handle): int;
nextRow: fn(handle: self ref DB_Handle): int;
read: fn(handle: self ref DB_Handle, column: int):
(int, array of byte);
write: fn(handle: self ref DB_Handle, param: int,
fld: array of byte): int
columnTitle: fn(handle: self ref DB_Handle,
column: int): string;
errmsg: fn(handle: self ref DB_Handle): string;
datafd: ref Sys->FD;
sqlconn: int;
sqlstream: int;
lock: chan of int;
};
connect: fn(addr, alg: string): (ref Sys->FD, string);
dbopen: fn(fd: ref Sys->FD, username, password, dbname: string):
(ref DB_Handle, list of string);
open: fn(addr, username, password, dbname: string):
(ref DB_Handle, list of string);
DESCRIPTION
DB allows Limbo programs to connect to data base management
systems that support an ODBC interface.
Dbsrv(7) must be running (usually in a hosted emu(1)) to
service database requests.
If security features will be used in conjunction with DB,
the Auth module definitions (see security-auth(2)) from
security.m must be included.
If authentication is in use, DB will use the certificate in
the file
/usr/user/keyring/net!machine
Page 1 Plan 9 (printed 12/30/24)
DB(7) DB(7)
if that file exists. Otherwise, db will attempt to find a
certificate in the file
/usr/user/keyring/default.
Connect establishes a connection to the dbsrv at addr. Addr
has the form machine!service. Machine is a symbolic or
numeric network address, and service is a service or port on
that machine. Dbsrv starts a corresponding infdb process.
After some negotiation, infdb will take the appropriate
authentication, digesting, and decryption actions, based on
the alg requested by the client. If successful, connect
will return a file descriptor required by dbopen.
Dbopen initiates a session with a database dbname, passing
username and password down the fd returned by connect.
Dbopen returns a reference to an instance of DB_Handle and
an error string, which is nil on success. On error, the
reference is nil, but the string contains a diagnostic.
Dbopen implicitly opens an initial SQL stream via SQLOpen.
Open returns the result of a connect followed (if success-
ful) by a dbopen.
oh.SQLOpen
Creates a new DB_Handle and opens a new SQL stream with
which requests can be associated. The new handle shares
the connection and transaction context with oh. Other
characteristics such as the current SQL command, the
result set, and cursor position are independent, which
allows the manipulation and interaction of many SQL
statements within a transaction. It returns zero on
success, non-zero on error.
h.SQLClose
Closes the SQL stream opened by SQLOpen. Closing all
SQL streams associated with a connection causes the
connection to be closed.
h.SQL(command)
Sends the SQL statement command to the database. If the
call fails, the first element of the returned tuple is
non-zero and the second is an error message.
h.columns()
Returns the number of columns in the result set of the
previous SQL select command sent to the database. A
returned value of 0 indicates there was a problem with
the previous command, or there was no previous select
command.
h.nextRow()
Page 2 Plan 9 (printed 12/30/24)
DB(7) DB(7)
Advances the current row, then returns the current row
number of the selection results. A return value of 0
indicates there are no more rows; a negative value is
returned in case of an error. The initial current row
is 0 following a select, so nextRow must be called
before any data is read.
h.read(c)
Returns the data of column c of the current row. If c
is out of range, there is no current row, or some other
error occurred, the first element of the returned tuple
will be negative, and the byte array (sic) will contain
an error message. Otherwise, it will be the number of
bytes in the field requested. This could be greater
than the length of the returned array, if the DB module
could not allocate enough memory to contain the entire
field. In this case the returned array contains the
initial portion of the field.
h.write(p,data)
Write sends data for a binary field to the server, in
anticipation of a subsequent SQL `update request with
placeholders'. Data is an array of bytes containing
the data for placeholder p (counting from 1). All
binary fields should be set by write before the SQL
request is sent to the server with SQL. It returns the
number of bytes saved for the field, or -1 on failure.
h.columnTitle(n)
ColumnTitle returns the title of column n. It returns
nil if n is out of range.
h.errmsg()
Returns the error message associated with the failure
of a previous columns, nextRow, columnTitle or read.
SOURCE
/appl/lib/db.b
SEE ALSO
srv(8)
Page 3 Plan 9 (printed 12/30/24)