Module

The output is wrapped in a module "ort". In this manual, the leading "ort::" to submodules, structures, and so on is omitted for brevity. For example, the ort::Ortdb type is written as simply Ortdb.

An application context is initialised with the following Ortdb associated functions:

new(dbname: &str) -> Ortdb

Creates an application-wide database instance at dbname, an existing sqlite3 database usually created with ort-sql(1). The number of password hashing rounds defaults to 12.

new_with_args(dbname: &str, args: Ortargs) -> Ortdb

Like new(), but accepting args consisting of configuration parameters. If provided, it must define the bcrypt_cost property with a valid number of password hashing rounds.

The Ortdb type has the following method:

connect() -> Result<Ortctx>

Connect to the database. This should be invoked for each request. In applications not having a request, this corresponds to a single operator sequence. If roles are enabled, the connection will begin in the "default" role.

Each sequence of database interaction begins with the connect() method from the application-wide Ortdb instance.

Any insert statements are output as follows. Let "foo" be the name of the exemplar structure in this and subsequent prototypes. Its full module path is ort::objs::Foo, written here as simply Foo. Returns an error Result on database error.

db_foo_insert(ARGS) -> Result<i64>

Insert a row and return its identifier or -1 on constraint violation. This accepts all native fields ARGS as parameters excluding rowid, which is automatically set by the database. If any fields are specified as null, they may be passed as None options.

Query statements count, iterate, list, search are output as follows. These return an error Result on database error.

db_foo_count() -> Result<i64>

Like db_foo_count_xxxx() but returning a count of all rows.

db_foo_count_xxxx(ARGS) -> Result<i64>

Like db_foo_get_xxxx(), but returning a count of responses.

db_foo_count_by_xxxx_op1_yy_zz_op2(ARGS) -> Result<i64>

Like db_foo_get_by_xxxx_op1_yy_zz_op2(), but returning a count of responses.

db_foo_get_xxxx(ARGS) -> Result<Option<Foo>>

The search statement named "xxxx". The function accepts variables for all binary-operator fields to check (i.e., all except for those checking for null).

db_foo_get_by_xxxx_op1_yy_zz_op2(ARGS) -> Result<Option<Foo>>

Like db_foo_get_xxxx(), but for (possibly-nested) structures. In the given example, "xxxx" is a field in the given structure with operation "op1" and "yy_zz" means a field "zz" in the nested structure "yy" with operation "op2".

db_foo_iterate(ARGS, cb) -> Result<()>

Like db_foo_iterate_xxxx() but iterating over all rows.

db_foo_iterate_xxxx(ARGS, cb) -> Result<()>

Like db_foo_get_xxxx(), but invoking a function callback per row. The cb callback accepts a single parameter of type Foo and does not have a return value.

void db_foo_iterate_by_xxxx_op1_yy_zz_op2(ARGS, cb) -> Result<()>

Like db_foo_get_by_xxxx_op1_yy_zz_op2(), but invoking a function callback for each retrieved result.

db_foo_list() -> Result<Vec<Foo>>

Like db_foo_list_xxxx() but allocating and filling a queue of all rows.

db_foo_list_xxxx(ARGS) -> Result<Vec<Foo>>

Like db_foo_get_xxxx(), but producing an array of responses.

db_foo_list_by_xxxx_op1_yy_zz_op2(ARGS) -> Result<Vec<Foo>>

Like db_foo_get_by_xxxx_op1_yy_zz_op2(), but producing a queue of responses.

Any update statements in the configuration are output as the following methods on Ortctx. These return an error Result on database error.

db_foo_update_xxxx(ARGS) -> Result<bool>

Run the named update function "xxxx". The update functions are specified with update statements. The parameters passed to this function are first the fields to modify, then the fields that constrain which rows are updated. Update fields are only specified for operations for binary-operator constraints, i.e., those not checking for null status. Returns true on success, false on constraint failure.

db_foo_update_xx_mod_by_yy_op(ARGS) -> Result<bool>

Like db_foo_update_xxxx(), but using an un-named update statement modifying "xx" with modifier "mod" constrained by "yy" with operation "op". Either or both modifiers and constraints may be empty. If modifiers are empty, all fields are modified by setting. If constraints are empty, they and the preceding "by" are omitted.

Any delete statements in the configuration are output as the following methods on Ortctx. These return an error Result on database error.

db_foo_delete_xxxx(ARGS) -> Result<()>

Run the named delete function "xxxx". The ARGS passed to this function are the fields that constrain which rows are deleted. Parameters are only specified for operations for binary-operator constraints, i.e., those not checking for null status.

db_foo_delete_by_yy_op(ARGS) -> Result<()>

Like db_foo_delete_xxxx(), but using an un-named delete statement constrained by "yy" with operation "op".

Errors

All database functions will return a rusqlite::Error in its Result on error. This may be examined for how to respond in the manner documented in its crate.

Data structures

Any enumerations or bitfields (enum, bitf) in the configuration are output in the ort::data submodule and named as themselves. Enumerations have explicit discriminator values set to the item value. Bitfields also have explicit discriminator, but assigned the bit index (from one).

Each struct is output as a structure in the ort::data module and named as itself, such as ort::data::Foo. All items of the structure are mapped to fields with the following types:

Since bitfields are combinations of bits in their respective enumerations, they are represented by i64 and not the enumeration type.

If a field is marked as null, it will be wrapped in an Option, such as Option<String>.

Objects returned by query methods are output as structures in the ort::objs module and named as in the configuration. Letting "foo" be an exemplar structure name, ort::objs::Foo, the object consists of the following.

data: Foo

The data itself.

export() -> String

Export as a JSON string in a surrounding object. Export rules are governed by the role in which the object was created.

The exported object is readable by applications using the ort-javascript(1) tool.