setRange( )

Topic group Related topics

Constrains the rowset to those rows whose key field values falls within a range.

Syntax

<oRef>.setRange(<key exp>)

or

<oRef>.setRange(<startKey exp> | null, <endKey exp> | null )

<oRef>

The rowset you want to constrain.

<key exp>

Shows only those rows whose key value matches <key exp>.

<startKey exp>

Shows those rows whose key value is equal to or greater than <startKey exp>.

<endKey exp>

Shows those rows whose key value is less than or equal to <endKey exp>.

There are four ways to use setRange( ):

1. Exact match: setRange(<key exp>)

• Range from start to end: setRange(<startKey exp>, <endKey exp>)

• Range from starting value: setRange(<startKey exp>, null)

• Range up to ending value: setRange(null, <endKey exp>)

Property of

Rowset

Description

setRange( ) is similar to a filter; setRange( ) uses the rowset’s current index (represented by its indexName property) and shows only those rows whose key value matches a single value or falls within a range of values. This is referred to as a key constraint. Because it uses an index, a key constraint is instantaneous, while a filter condition must be evaluated for each row. Use clearRange( ) to remove the constraint.

The key range values must match the key expression of the index. For example, if the index key is UPPER(Name), specify uppercase letters in the range expressions. For character expressions, the key match is always a partial string match (starting at the beginning of the expression); therefore, an exact match with <key exp> could match multiple key values if the <key exp> is shorter than the key expression.

When you use both setRange( ) and a filter (and canGetRow) for the same rowset, you get those rows that are within the index range and that also meet the filter condition(s).

Rowsets that use masterRowset for master-detail linkage internally apply setRange( ) in the detail rowset. If you use setRange( ) in the detail rowset, it overrides the master-detail key constraint. Navigation in the master rowset would reapply the master-detail constraint.