HFilterStartsWith (Function)

Defines and enables a "Start with" filter on a data file, a view or a query. The "Starts with" filter is used to select all the records that start with a specific set of characters.

After its execution, the most common cases are as follows:

the filter cannot be created: HFilterStartsWith returns an empty string (""). HError returns the error identifier.
the filter is created: HFilterStartsWith returns the optimized search key that will be used to browse the data file, view or query.

Versions 15 and later

This function is now available for the Android applications.

New in version 15

This function is now available for the Android applications.

Versions 17 and later

This function is now available for the iPhone/iPad applications.

New in version 17

This function is now available for the iPhone/iPad applications.

Versions 18 and later

This function is now available in Android Widget mode.

This function is now available in Windows Store apps mode.

New in version 18

This function is now available in Android Widget mode.

This function is now available in Windows Store apps mode.

This function is now available in Android Widget mode.

This function is now available in Windows Store apps mode.

Versions 21 and later

This function is now available in Universal Windows 10 App mode.

New in version 21

This function is now available in Universal Windows 10 App mode.

Note: From version 19, HFSQL is the new name of HyperFileSQL.

Example

MyKey is string
// Selects all the customers living in a city whose name starts with "Mon"
MyKey = HFilterStartsWith(Customer, City, "Mon")
HReadFirst(Customer, MyKey)
WHILE NOT HOut()
Trace(Customer.CustomerName, Customer.City)
HReadNext(Customer, MyKey)
END
...
// Cancels the filter
HDeactivateFilter(Customer)

Syntax

<Result> = HFilterStartsWith(<File Name>, <Name of Key Item>, <Value of Filter for 1st Key Component> [, <Value of Filter for 2nd Key Component>) [, ...]])

<Result>: Character string

Search item. Corresponds to:
the search key of data file if the filter is enabled
an empty string if the filter cannot be implemented

<File Name>: Character string (with or without quotes)

Name of HFSQL data file, view or query used.

<Name of Key Item>: Character string (with or without quotes)

Name of key item onto which the filter will be applied. This item can be a simple key (string) or a composite key. Caution: this parameter must only contain letters, underlined characters or digits. Otherwise, the name must be enclosed in quotes.

<Value of Filter for Component 1 of Key>: Type of first component of search key

Value sought for the first component (the 2nd respectively) of composite key.
The type of this parameter must correspond to the type of key item component on which the filter is defined.

<Value of Filter for Component 2 of Key>: Type of second component of search key

Value sought for the second component (the 3rd respectively) of composite key.
The type of this parameter must correspond to the type of key item component on which the filter is defined.

Remarks

Automatic management of composite keys

HFilterStartsWith automatically manages the filters on the simple keys and on the composite keys.

Example 1: Using HFilterStartsWith with a simple key:

Res = HFilterStartsWith(Customer, Name, "A")
// Select all the customers whose name starts with A

Example 2: Using HFilterStartsWith with a key made of two items:

// Example where LastNameFirstname is a key made of: LastName + FirstName
// Select all customers whose last name is SMITH
// and whose first name starts with a C
Res = HFilterStartsWith(Customer, LastNameFirstName, "SMITH", "C")

This code line is equivalent to:

HFilter(Customer, LastNameFirstName, ...
HBuildKeyValue(Customer, LastNameFirstName, "SMITH", "C") + hMinVal, ...
HBuildKeyValue(Customer, LastNameFirstName, "SMITH", "C") + hMaxVal)

Example 3: Using HFilterStartsWith with a key made of three items:

// Example with CUSTINV a key made of: CustomerNumber+Date+Time
// All the invoices of a customer (sorted by date)
Res = HFilterStartsWith(Invoice, CUSTINV, Customer.CustNum)

This code line is equivalent to:

HFilter(Invoice, CustInv, ...
HBuildKeyValue(Invoice, CustInv, Customer.CustNum) + hMinVal, ...
HBuildKeyValue(Invoice, CustInv, Customer.CustNum) + hMaxVal)

Example 4: Using HFilterStartsWith with a key made of three items:

// Example with CUSTINV a key made of: CustomerNumber+Date+Time
// All the invoices of a customer for today (sorted by date)
Res = HFilterStartsWith(Invoice, CustInv, Customer.CustNum, Today())

This code line is equivalent to:

HFilter(Invoice, CustInv, ...
HBuildKeyValue(Invoice, CustInv, Customer.CustNum, Today()) + hMinVal, ...
HBuildKeyValue(Invoice, CustInv, Customer.CustNum, Today()) + hMaxVal)

Filter and filtered browse:

After the call to HFilterStartsWith, the data file must necessarily be browsed on the item returned by HFilterStartsWith. The filter will be ignored if another item is used to browse the data file.

When a filter is defined and enabled on a data file (view or query), all records read correspond to the filter. If no other record corresponds to the filter during the browse:

HOut returns True
the current record corresponds to the last record read with the filter.

For example:

On a filtered data file, after the function:	the current record is:

HReadFirst	the first file record corresponding to the filter.
HReadLast	the last file record corresponding to the filter.
HReadNext (or HForward)	the next record (or the next Nth record) corresponding to the filter.
HReadPrevious (or HBackward)	the previous record (or the previous Nth record) corresponding to the filter.

Enabling/Disabling a filter

HDeactivateFilter is used to disable a filter.
HActivateFilter is used to re-enable a filter.
The filter is deleted when the data file (query or view) is closed (HClose for example).
A single filter can exist at a given time on a data file (query or view). If HFilterStartsWith is used several times, only the last filter will be taken into account: the previous filters will be deleted. Similarly, if several filters are used (HFilter* functions), only the last filter will be taken into account.

Data files not in HFSQL format

The filter can be created from any item (key or non-key item).
The filter is automatically enabled when HFilterStartsWith is run.
The modifications performed by HFilterStartsWith and HDeactivateFilter are taken into account when using HReadFirst/HFirst, HReadLast/HLast or HReadSeekFirst/HReadSeekLast.

Component : wd240hf.dll