Compiles a predicate (query condition).

Return type: LOGICAL

Applies to: Query object handle

Syntax

QUERY-PREPARE ( predicate-expression )
predicate-expression
A CHARACTER expression that evaluates to an OPEN QUERY ... FOR EACH statement without the OPEN QUERY .... You can also use a field phrase.

The QUERY-PREPARE method corresponds to the OPEN QUERY statement's compilation phase. To open the query object, use the QUERY-OPEN method.

If the QUERY-PREPARE method encounters an error, it returns FALSE and generates an error message, but does not raise ERROR. If you use the QUERY-PREPARE method in a statement that uses the NO-ERROR option and an error occurs, the QUERY-PREPARE method returns FALSE and diverts the error to the ERROR-STATUS system handle. In either instance, ERROR-STATUS:ERROR returns FALSE. You can get information on the error through the GET-MESSAGE method of the ERROR-STATUS system handle, as usual.

Examples

hQuery:QUERY-PREPARE("FOR EACH Customer WHERE Customer.CustNum < 9").
 
hQuery:QUERY-PREPARE(my-predicate).
 
hQuery:QUERY-PREPARE("FOR EACH Customer WHERE Customer.CustNum > " +
  STRING(my-integer)).

Notes

  • The QUERY-PREPARE method is compatible with indexed reposition of queries with joins. In predicate-expression, just include the INDEXED-REPOSITION option. For more information on the INDEXED-REPOSITION option, see the reference entry for the OPEN QUERY statement.
  • Unless explicitly specified otherwise in the predicate-expression, the default record lock type for the QUERY-PREPARE method is NO-LOCK.
  • Like the FOR statement, the QUERY-PREPARE method predicate-expression supports the BREAK and BY options for sorting and accumulating data by break groups.
    hQuery:QUERY-PREPARE("FOR EACH Customer WHERE Customer.CustNum > 50 
  BREAK BY Customer.SalesRep BY Customer.Country").
    To test whether a break group has changed, you can use the FIRST-OF( ) method and LAST-OF( ) method of the query object handle.
  • The QUOTER function can be used to wrap character values with internal quotes, as in this example:
    hQuery:QUERY-PREPARE("FOR EACH Customer WHERE Customer.Name = " +
  QUOTER(my-name)).
  • The NAME attribute of the Temp-table object handle is writeable for dynamic and AVM-generated temp-tables. You might need to update a predicate-expression that references a renamed temp-table with new strings using the new table name.
  • The DYNAMIC-FUNCTION function can be used inside the predicate-expression, as in this example:
    hquery:QUERY-PREPARE("FOR EACH tt WHERE ~
   DYNAMIC-FUNCTION( 'GetLogical', " + cExpression + ") = TRUE").
  • If the predicate-expression contains special characters, QUERY-PREPARE may fail with an error, "Could not tokenize PREPARE string…". For example, the left curly brace ({) is a special character used in source code as an argument reference, an include file reference, or a preprocessor name reference, and has special meaning to the compiler. To avoid the error, special characters in the predicate-expression must be escaped with a tilde (~). During QUERY-PREPARE, the string is compiled twice, once when the r-code is written and once at runtime. Therefore, it may be necessary to escape special characters multiple times.
  • The QUERY-PREPARE() method cannot be used together with other assignments in a single ASSIGN statement.

See also

OPEN QUERY statement