Element: database.query { }

Type

procedure

Description

A function to send a series of commands to a database interface. <command_block> is a block of language commands, any of which starting with * are processed as database commands. Such commands are not sent to the database interface immediately but are buffered up and sent at the end of the block as a single "query". This behavior is different to that of database.session where every command command is sent immediately. With the database.query procedure, network traffic is kept to a minimum.

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).

Any non-database commands within the block are executed normally as they are encountered. Therefore, because database commands are all executed together at the end of the block, it is advisable to restrict the commands in a block to database commands only. To avoid execution anomalies during block execution (where non-database commands are executed immediately but database command execution is delayed until the end-of the block) the system numeric identifier limit_query_sub_commands may be set. When limit_query_sub_commands is set, any attempt to use non-database commands within a block will invoke an error. This then prevents unintentional execution anomalies from occurring.

Any jump out of the command block, e.g. by a break, return, goto, or exit command will abort the block without executing the database commands.

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.

The code of the procedure cannot be redefined.

Parameters

<database>.query () {
    <command_block>
}

The procedure may be called in one of two ways:

# Assume mydb is the database identifier.
mydb.query(mydb) { ... } 

or

mydb.query { ... }

Examples

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

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

See Also