Controlling Predicate Error Handling

To be used as a filtering predicate in a search a predicate expression must evaluate to a Boolean value (true or false). For a query predicate the requirements are much more lenient, the predicate value need only be convertible to a Double. This includes Boolean values (by far the most common case) where true equals 1.0 and false equals 0.0, but can be any other value except for the array values.

If a predicate expression which does not produce a Boolean value is passed to the lkt_dbsearch command as a filtering predicate in the search options, or a query predicate is given which cannot be converted to a Double value, the DevKit responds with a PREDTYPE error.

For example, the predicate expression below is not a valid expression for use as a filtering predicate in a search:

predicate = lpar_create_predicate2(
              PRED_OP_TODATE,
              lpar_create_str(LPAR_STR_PREDFIELD,"Creation Date"));

This predicate expression never produces a Boolean result, so it is an error.

For a given record, even well-formed predicates might fail to produce any value at all depending on the record's contents. Consider the following predicate expression where the field Clicks is an integer field:

predicate = lpar_create_predicate3(
              lpar_create_str(LPAR_STR_PREDFIELD,"Clicks"),
              PRED_OP_GREATERTHAN,
              lpar_create_str(LPAR_INT_PREDVALUE,50));

This expression has the potential to evaluate to a Boolean value, so it is not rejected by lkt_dbsearch, but to evaluate correctly there must be an integer value in the field Clicks. If a record was loaded with the value 123 in this field, it evaluates to true, if it was loaded with 21 it evaluates to false, but if it was loaded with the value "orange" it does not evaluate to anything as the field value is invalid. Likewise if the field contains no value at all it has a special value "empty" and a valid comparison cannot be made.

By default, if a predicate expression fails to evaluate for a given record, that record is rejected from the search. In other words, the predicate expression selects only those records which evaluate to true, and the search is performed on only those records.

In some cases for a filtering predicate it might be desirable to include records which fail evaluation in the search. In this case, the search parameters LPAR_BOOL_FAILBADPRED and LPAR_BOOL_FAILEMPTYPRED can be used. Setting LPAR_BOOL_FAILBADPRED to false causes all evaluations which encounter an invalid value to be considered true. That is any records that contain fields that are tested by the predicate with invalid values are returned.

Setting LPAR_BOOL_FAILEMPTYPRED to false causes empty field values to be treated as valid. Predicate evaluation continues and depending on the results of the evaluation the record might or might not be included. Text fields are simply used as is (a zero length string or text block), numeric fields are given a value of zero, and date or date-time field have a special empty value. Empty dates compare less than all valid dates, greater than all invalid dates and equal to all empty dates.

Note that LPAR_BOOL_FAILBADPRED controls the behavior of predicates that fail for any reason. Thus if LPAR_BOOL_FAILEMPTYPRED is false and LPAR_BOOL_FAILBADPRED is true (the default), then any record where the predicate encounters an empty field value is returned.

For a query predicate, a predicate that fails to evaluate is assigned a score of 0.0 by default (in Learn queries the default value is -1.0 which has special meaning to the TIBCO Patterns Learn Model). This can be changed using the LPAR_DBL_INVALID_DATA_SCORE or LPAR_DBL_EMPTY_DATA_SCORE search parameters. Queries that encounter an empty field value is assigned the score given by the LPAR_DBL_EMPTY_DATA_SCORE parameter.

Predicates that fail evaluation for any other reason is assigned the score given by the LPAR_DBL_INVALID_DATA_SCORE parameter. In both cases the value must be in the range: 0.0 - 1.0 inclusive or the special value -1.0. The -1.0 special value indicates the record should be rejected from further consideration regardless of the overall record score (in Learn queries the -1.0 score does not cause the record to be rejected, instead it is an indicator that this data was not available).