QUERY-PREPARE( ) method

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.

The following are 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)).

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

See also

OPEN QUERY statement