Element: database.transaction { }

Type

procedure

Description

A function to conduct a dialogue with a database interface. <command_block> is a block of language commands, any of which starting with * are sent to the database interface. Any errors detected during execution of the command block (language errors or database errors reported by the database interface) will abort the command block.

In database commands which require identifier values, language identifiers may be specified by preceding them with a : character, e.g.

string s = 'test'
*select * from my_table where name = :s

Such language variables may be array expressions. They must not contain any embedded white space. The only permitted identifier types are numeric, string, time and point. An attempt to output other variables will produce an error. Colons within quoted strings are treated literally and are not assumed to prefix a language variable. Numeric values will be expanded without trailing zeros, string variables will be enclosed within quotes, time variables will be output using the current date_mode format, point variables will be output in the form (x,y,z).

The default behavior for when an error is detected during execution of the command block (language errors or database errors reported by the database interface) is to abort the command block, skipping over any commands remaining in the block. This default behavior can be changed permanently by setting the value of the system numeric session_abort_on_error (set to true at program start), or just for the duration of this procedure by passing a numeric "abort-on-error" parameter.

Whenever the database interface detects an error, the attribute database.dberr (which is initialized to zero at the beginning of the block) is set to a non-zero value.

This procedure does the same as a dbtrans command, which should be consulted for more details of database commands.

The block is executed as database transaction with the result that a "rollback" is performed in the event of any database errors which occur during execution of the block. If no database errors were incurred during the block, a database "commit" is performed. A database error is an error incurred by a *command sent to the database. Errors in non-database commands will not trigger a rollback.

The code of the procedure cannot be redefined.

Parameters

database.transaction () {
    <command_block>
}

The procedure may be called in one of two ways:

# Assume mydb is the database identifier.
mydb.transaction(mydb,1) { ... }

or

mydb.transaction(1) { ... }

Examples

Open a database interface to an ODBC database. Within a database transaction select and fetch some data.

database mydb,-prop=odbc,-name='myodbc'
string names[]
mydb.transaction(1) {
  * select * from mytable
  * multifetch into names
}
if (mydb.dberr) !Error during fetch
mydb.close

See Also