HFilterStartsWith (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

This content has been translated automatically. Click here to view the French version.

Help / WLanguage / Managing databases / HFSQL / HFSQL functions

Automatic management of composite keys
Filter and filtered iteration:
Enabling/Disabling a filter
Non-HFSQL data files

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

HFilterStartsWith (Function)

In french: HFiltreCommencePar

Not available with this kind of connection

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: the function HFilterStartsWith FUNCTION function returns an empty string (""). HError returns the error identifier.
the filter is created: the HFilterStartsWith function returns the optimal route key to be used to route the data file, view or query.

Example

MaClé is string
// Sélectionne tous les clients habitant la ville commençant par "Mon"
MaClé = HFilterStartsWith(Client, Ville, "Mon")
HReadFirst(Client, MaClé)
WHILE NOT HOut()
	Trace(Client.NomClient, Client.Ville) 
	HReadNext(Client, MaClé)
END
...
// Annule le filtre
HDeactivateFilter(Client)

Syntax

<Result> = HFilterStartsWith(<Data file> , <Key item> , <Filter for key component 1> [, <Filter for key component 2> [... [, <Filter for key component N>]]])

<Result>: Character string

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

<Data file>: Character string

Name of the HFSQL data file, view or query used.

<Key item>: Character string

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

<Filter for key component 1>: Type of the first component of the 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.

<Filter for key component 2>: Type of the second component of the search key

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

<Filter for key component N>: Type of the N component of the search key

Value sought for component N 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(Client, Nom, "A")
// Sélection de tous les clients dont le nom commence par A

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

// Exemple avec NomPrénom une clé composée de : Nom + Prénom
// Sélection de tous les clients dont le nom est DUPONT 
// et le prénom commence par C
Res = HFilterStartsWith(Client, NomPrénom, "DUPONT", "C")

This line of code is equivalent to:

HFilter(Client, NomPrénom, ...
	HBuildKeyValue(Client, NomPrénom, "DUPONT", "C") + hMinVal, ...
	HBuildKeyValue(Client, NomPrénom, "DUPONT", "C") + hMaxVal)

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

// Exemple avec FACTCLI une clé composée de : NuméroClient+Date+Heure
// Toutes les factures d'un client (triées par date)
Res = HFilterStartsWith(Facture, FACTCLI, Client.NumCli)

This line of code is equivalent to:

HFilter(Facture, FactCli, ...
	HBuildKeyValue(Facture, FactCli, Client.NumCli) + hMinVal, ...
	HBuildKeyValue(Facture, FactCli, Client.NumCli) + hMaxVal)

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

// Exemple avec FACTCLI une clé composée de : NuméroClient+Date+Heure
// Toutes les factures du jour d'un client (triées par date)
Res = HFilterStartsWith(Facture, FactCli, Client.NumCli, Today())

This line of code is equivalent to:

HFilter(Facture, FactCli, ...
	HBuildKeyValue(Facture, FactCli, Client.NumCli, Today()) + hMinVal, ...
	HBuildKeyValue(Facture, FactCli, Client.NumCli, Today()) + hMaxVal)

Filter and filtered iteration:

After the call to HFilterStartsWith, the iteration must be performed on the item returned by HFilterStartsWith. The filter will be ignored if another item is used to loop through 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 there are no more records matching the filter during browsing:

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 the HFilterStartsWith is used several times, only the last filter will be taken into account: the previous filter(s) will be deleted. Similarly, if several filters are used (HFilter* functions), only the last filter will be taken into account.

Non-HFSQL data files

The filter can be created from any item (key or non-key item).
The filter is automatically enabled when HFilterStartsWith is executed.
The changes made with HFilterStartsWith and HDeactivateFilter are only taken into account when the following functions are used HReadFirst/HFirst, HReadLast/HLast or HReadSeekFirst/HReadSeekLast.

Component: wd300hf.dll