PASSTHRU statement

The PASSTHRU statement evaluates an expression and executes the resulting character string as a database statement.

SYNTAX
Notes:
  1. The lower half of the main syntax diagram (the second of the two ways of coding the Expression to be passed to PASSTHRU) describes syntax retained for backward compatability.

Usage

The main use of the PASSTHRU statement is to issue administrative commands to databases (to, for example, create a table).
Note: Do not use PASSTHRU to call stored procedures, instead use the CALL statement. This is because PASSTHRU imposes limitations (you cannot use output parameters, for example).

The first expression is evaluated and the resulting character string is passed to the database pointed to by DatabaseReference (in the TO clause) for execution. If the TO clause is not specified, the database pointed to by the node's data source attribute is used.

Use question marks (?) in the database string to denote parameters. The parameter values are supplied by the VALUES clause.

If the VALUES clause is specified, its expressions are evaluated and passed to the database as parameters; (that is, their values are substituted for the question marks in the database statement).

If there is only one VALUE expression, the result may or may not be a list. If it is a list, the list's scalar values are substituted for the question marks, sequentially. If it is not a list, the single scalar value is substituted for the (single) question mark in the database statement. If there is more than one VALUE expression, none of the expressions should evaluate to a list. Their scalar values are substituted for the question marks, sequentially.

Because the database statement is constructed by the user program, there is no absolute need to use parameter markers (that is, the question marks) or the VALUES clause, because the whole of the database statement could be supplied, as a literal string, by the program. However, use parameter markers whenever possible, because this reduces the number of different statements that need to be prepared and stored in the database and the broker.

Database reference

A database reference is a special case of the field references used to refer to message trees. It consists of the word "Database" followed by a data source name (that is, the name of a database instance).

You can specify the data source name directly or by an expression enclosed in braces ({...}). A directly-specified data source name is subject to name substitution. That is, if the name used has been declared to be a known name, the value of the declared name is used rather than the name itself (see DECLARE statement).

Handling errors

It is possible for errors to occur during PASSTHRU operations. For example, the database may not be operational or the statement may be invalid. In these cases, an exception is thrown (unless the node has its throw exception on database error property set to FALSE). These exceptions set appropriate SQL code, state, native error, and error text values and can be dealt with by error handlers (see the DECLARE HANDLER statement).

For further information about handling database errors, see Capturing database state.

Examples

The following example creates the "Customers" table in schema "Shop" in database DSN1:
PASSTHRU 'CREATE TABLE Shop.Customers (
  CustomerNumber INTEGER,
  FirstName      VARCHAR(256),
  LastName       VARCHAR(256),
  Street         VARCHAR(256),
  City           VARCHAR(256),
  Country        VARCHAR(256)
)' TO Database.DSN1;
If, as in the last example, the ESQL statement is specified as a string literal, you must put single quotes around it. If, however, it is specified as a variable, omit the quotes. For example:
SET myVar = 'SELECT * FROM user1.stocktable';
SET OutputRoot.XML.Data[] = PASSTHRU(myVar);
The following example "drops" (that is, deletes) the "Customers" table in schema "Shop" in database DSN1:
PASSTHRU 'DROP TABLE Shop.Customers' TO Database.DSN1;