Make a new connection through driver drivername. Parameters can be passed by optional key strings and val values. If given an existing connection, the returned conn is a new, cloned connection to the original data source if possible.

db = osdbi("sqlite3")
⇒ osdbi SQLite3 in-memory database <0>, status closed
db = osdbi("SQLite3", "filename", "tst.sqlite3")
⇒ osdbi SQLite3 connection to tst.sqlite3 <24849672>, status closed

Loadable Function: errcode = osdbi_set_option (conn, key, val, ...)

Loadable Function: errcode = osdbi_set_option (conn, optstruct)

Set options on connection conn. The returned errcode is zero on success. Other values are driver-dependent.

db = osdbi ("sqlite3");
osdbi_set_option (db, "filename", "tst.sqlite3");
osdbi_set_option (db, struct ("flags", 8));

Loadable Function: errcode = osdbi_open (conn): Opens the connection. A zero errcode signals success; other values are driver-dependent.

Loadable Function: osdbi_close (conn): Closes the connection.

Loadable Function: osdbi_is_open (conn): Returns true if the connection is open.

Loadable Function: osdbi_is_readonly (conn): Returns true if the connection is read-only.

Loadable Function: osdbi_is_ok (conn): Returns true if the connection is in a good (non-error) state. The exact meaning is driver-dependent, but it is reasonable to assume that a non-"ok" connection should be closed. It may be possible to generate an "ok" connection by cloning the non-"ok" connection.

Loadable Function: osdbi_driver_name (conn): Returns the driver name.

Loadable Function: osdbi_current_description (conn): Returns a string containing a driver-dependent description of the connection intended for end-user consumption.

Loadable Function: osdbi_current_status (conn): Returns a string containing a driver-dependent description of the connection intended for end-user consumption.

Loadable Function: errcode = osdbi_insert (conn, tablename, data)

Loadable Function: outdata = osdbi_insert (conn, tablename, data[, outfields])

Loadable Function: outdata = osdbi_insert (conn, tablename, data[, outname, ...])

Insert scalar structure data into table tablename on connection conn. The fieldnames are used as column names. Each field should contain an array or cell array of values. If a field is scalar, it is replicated to match any array fields. An empty field is treated as a null. All array fields must be of the same length. The returned errcode will be zero on success. Data is inserted in a single transaction, so either all the data is inserted or none is.

The optional structure outfields or list of strings outname specify fields to return from the recently inserted data. These can be used to retrieve autoincrement id fields or other generated key data.

On success the return value will depend on the number of requested columns and their types. Multiple columns will be returned in a structure. A single column will be returned as either a Cell column or, if possible, downcasted to a numerical column which may in turn be narrowed to a scalar.

On error, the return value will be a scalar error code which may be indistinguishable from actual data. However, an error is signaled through the common Octave mechanism. A try block or an eval is recommended to detect errors.

osdbi_do (zz, "create table aa (a, b);");
indata = struct ("a", int32([1,2,3,4]), "b", 5:8);
osdbi_insert (zz, "aa", indata)
⇒ 0
indata = struct ("a", {{"foo", "quux"}}, "b", {{"bar", "baz"}});
osdbi_insert (zz, "aa", indata, "a")
⇒ {
  a =
  {
    [1,1] = foo
    [2,1] = quux
  }
}

See also: osdbi_expand.

Loadable Function: outdata = osdbi_do (conn, sql[, params...])

Loadable Function: outdata = osdbi_do (conn, sql[, cell_of_params])

An arbitrary superfunction. Parameters are bound by position. Results are narrowed when possible.

# Assume table tbl has two columns, a and b, and eight entries.
osdbi_do (conn, "select count(*) on tbl;")
⇒ 8
osdbi_do (conn, "select * on tbl limit 1;")
⇒ ans =
{
  a =  22
  b =  bar
}
[x, y] = osdbi_do (conn, "select * on tbl limit 1;")
⇒ x =  22
y =  bar

See also: osdbi_insert,osdbi_expand.

Loadable Function: data = osdbi_expand (conn, table, indata[, outfields])

Loadable Function: data = osdbi_expand (conn, table, indata[, outname1, ...])

Expands the structure array indata with data from table table through. DB connection conn. Each structure array entry provides a pattern of values to match to values in table. The fieldnames are used as column names. The result is the distinct union of all the matching rows. Empty fields are wildcards.

Output fields can be limited either by the fieldnames of outfields or by string names. The result is a structure on success and either a scalar error code or an empty matrix on failure.

Currently NULLs are translated to Octave's NA.

q2 = struct ("a", {{-100, "foo"}});
osdbi_expand (zz, "aa", q2)
⇒{
  a = {
    [1,1] = -100
    [2,1] = foo
  }
  b = {
    [1,1] = NA
    [2,1] = bar
  }
}

See also: osdbi_insert.

Loadable Function: osdbi_toggle_tracing (): Turn on tracing. The exact effects depend on the driver.

Loadable Function: osdbi_is_tracing (): Returns true if tracing. The exact effects of tracing depend on the driver.

Loadable Function: osdbi_sqlite3_make ()

Internal connection creator. Call via osdbi.

osdbi("sqlite3");

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Function Index

Jump to:	O

	Index Entry	Section

O
	`osdbi`	2. Interface Functions
	`osdbi`	2. Interface Functions
	`osdbi_close`	2. Interface Functions
	`osdbi_current_description`	2. Interface Functions
	`osdbi_current_status`	2. Interface Functions
	`osdbi_do`	2. Interface Functions
	`osdbi_do`	2. Interface Functions
	`osdbi_driver_name`	2. Interface Functions
	`osdbi_expand`	2. Interface Functions
	`osdbi_expand`	2. Interface Functions
	`osdbi_insert`	2. Interface Functions
	`osdbi_insert`	2. Interface Functions
	`osdbi_insert`	2. Interface Functions
	`osdbi_is_ok`	2. Interface Functions
	`osdbi_is_open`	2. Interface Functions
	`osdbi_is_readonly`	2. Interface Functions
	`osdbi_is_tracing`	2. Interface Functions
	`osdbi_open`	2. Interface Functions
	`osdbi_set_option`	2. Interface Functions
	`osdbi_set_option`	2. Interface Functions
	`osdbi_sqlite3_make`	2. Interface Functions
	`osdbi_toggle_tracing`	2. Interface Functions

Jump to:	O

[Top]

[Contents]

[Index]

[ ? ]

1. Introduction
2. Interface Functions
Function Index

[Top]

[Contents]

[Index]

[ ? ]

About This Document

This document was generated by Jason Riedy on March, 12 2008 using texi2html 1.78.

The buttons in the navigation panels have the following meaning:

Button	Name	Go to	From 1.2.3 go to
[ < ]	Back	Previous section in reading order	1.2.2
[ > ]	Forward	Next section in reading order	1.2.4
[ << ]	FastBack	Beginning of this chapter or previous chapter	1
[ Up ]	Up	Up section	1.2
[ >> ]	FastForward	Next chapter	2
[Top]	Top	Cover (top) of document
[Contents]	Contents	Table of contents
[Index]	Index	Index
[ ? ]	About	About (help)

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

1. Section One
- 1.1 Subsection One-One
  - ...
- 1.2 Subsection One-Two
  - 1.2.1 Subsubsection One-Two-One
  - 1.2.2 Subsubsection One-Two-Two
  - 1.2.3 Subsubsection One-Two-Three <== Current Position
  - 1.2.4 Subsubsection One-Two-Four
- 1.3 Subsection One-Three
  - ...
- 1.4 Subsection One-Four

This document was generated by Jason Riedy on March, 12 2008 using texi2html 1.78.

1. Introduction
2. Interface Functions		Interface functions.
Function Index

osdbi, A Simple Database Interface for Octave

1. Introduction

2. Interface Functions

Function Index

Table of Contents

About This Document