SNDDEX Control
SNDDEX.VBX Custom Control

Description

The SNDDEX custom control performs Soundex word matching comparisons. The SNDDEX.VBX custom control contains two versions of the Soundex word comparison algorithm.

These versions are:

The standard Soundex comparison algorithm where the first character in each compare word is used "as is" as the first character in the Soundex code word, the remaining characters in the word are processed by the Soundex algorithm and converted to a Soundex code..

The second version is a derivative version which allows the first character to not determine the search outcome. In this method, the first character is also converted to the equivalent Soundex code and used in the Soundex comparison. This reduces the "weight" assigned to the first character of a compare word. All remaining characters in the word are also converted to a Soundex code.

Selection of which version of Soundex comparison to use is determined by which Action property is used.

See Soundex operation for a more complete description of the Soundex algorithm.

File Name

SNDDEX.VBX

Remarks

When you create and distribute applications that use the SNDDEX control you should install the file SNDDEX.VBX in the customer's Microsoft Windows \WINDOWS\SYSTEM sub directory. All of the properties, events, and methods for this control are listed below.  Properties and events that apply only to this control, or require special consideration when used with it, are underlined. They are documented in this help file.  See the Visual Basic Language Reference or on-line Help for documentation of the remaining properties, events, and methods.

Properties

Action

SearchText

KeyText

SoundsLike

SoundexCode

CtlName

Index

Left

Top

Tag

Events

none

Methods

The SNDDEX.VBX Action property is used as a pseudo method.

See Also: Examples


Examples
Programming Examples

SNDDEX.VBX custom control code examples.

1. To use the control to search two words;

    ' To perform standard soundex search

    ' load the words to match

    SndDex1.KeyText = TXTKeyString.Text

    SndDex1.SearchText = TXTSearchString.Text

    ' do standard search

    SndDex1.Action = IDC_SNDEX_STDSEARCH	  '(20)

    ' use result

    Result% = Str$(SndDex1.SoundsLike)

    ' To perform modified soundex search

    ' load the words to match

    SndDex1.KeyText = TXTKeyString.Text

    SndDex1.SearchText = TXTSearchString.Text

    ' do modified search

    SndDex1.Action = IDC_SNDEX_INTSEARCH	  '(21)

    ' use result

    Result% = Str$(SndDex1.SoundsLike)

2. To perform a repeating search where the Key Text is held constant and the Search Text is varied ( ie as in searching through a list of words for a match ).

    ' To perform repeating standard soundex search

    ' load the words to match

    SndDex1.KeyText = TXTKeyString.Text

    SndDex1.SearchText = TXTSearchString.Text

    ' do standard search

    SndDex1.Action = IDC_SNDEX_STDSEARCH	  '(20)

    ' use result

    Result% = SndDex1.SoundsLike

    ' repeat loop starts here

    ' assumes the word list to search is an array

    For nDex =1 To Length

SndDex1.SearchText = SearchText[ nDex ]

SndDex1.Action = IDC_SNDEX_REPEATSTD  '( 30 )

'use results

Result% = SndDex1.SoundsLike

    Next nDex

    ' To perform repeating standard soundex search

    ' load the words to match

    SndDex1.KeyText = TXTKeyString.Text

    SndDex1.SearchText = TXTSearchString.Text

    ' do standard search

    SndDex1.Action = IDC_SNDEX_INTSEARCH	  '(21)

    ' use result

    Result% = SndDex1.SoundsLike

    ' repeat loop starts here

    ' assumes the word list to search is an array

    For nDex =1 To Length

SndDex1.SearchText = SearchText[ nDex ]

SndDex1.Action = IDC_SNDEX_REPEATINT  '( 31 )

'use results

Result% = SndDex1.SoundsLike

    Next nDex

3. To retreive the Soundex code value for any word

    ' To retrieve the Soundex Standard code

    ' load the word to retreive the code for in KeyText

    SndDex1.KeyText = TXTKeyString.Text

    SndDex1.Action = IDC_SNDEX_GETSTDCODE  ' ( 25 )

        ' use result,

        ' the Soundex code is returned

        ' in the control property SoundsLike

    SoundexStdCode% = SndDex1.SoundsLike

    ' To retrieve the Soundex Integer code

    ' load the word to retreive the code for in KeyText

    SndDex1.KeyText = TXTKeyString.Text

    SndDex1.Action = IDC_SNDEX_GETINTCODE  ' ( 26 )

        ' use result

        ' the Soundex code is returned

        ' in the control property SoundsLike

    SoundexIntCode% = SndDex1.SoundsLike


Typical Problems

The debugging version of SNDDEX.VBX will most likely resolve any program errors encountered when developing your application.

Keep in mind the following guidelines when implementing Soundex comparison searching in your application:

1. Soundex comparison searching is not an exact comparison search. If you want to know if two character strings exactly match then use the built in VB compare functions.

2. Long words may not give the results expected. Since the Soundex algorithm stops generating additional characters to add to the Soundex code after the first four are added, long words may not compare correctly. This is a limitation of the basic Soundex algorithm. In practice, the results obtained by a Soundex search should be presented to the user for additional scrutiny before use. Typically a list of potential matching choices would be presented upon completion of a Soundex search. The user would then make the final choice.

3. When implementing a Soundex search option in an application, the application should specifically advise the user that Soundex is being used as the basis for the search, otherwise the user may experience results that were not expected.


Action Property, SNDDEX Control

Description

Setting the SNDDEX.VBX controls action property to either IDC_SNDEX_STDSEARCH or IDC_SNDEX_INTSEARCH causes the custom control to compare the two words presented for matching Soundex codes. If the Soundex codes returned by each word is identical then SNDDEX.VBX returns the result in the property "SoundsLike".

The text used to generate the Soundex compare codes must be loaded in the respective SNDDEX control property, KeyText or SearchText prior to issuing the Action command. If either search word is a zero length string, the compare result in the "SoundsLike" property will be FALSE (property SoundsLike = 0). If the Soundex codes match then the return result in the "SoundsLike" property will be non-zero (property SoundsLike = 1).

Repeating Soundex searches start with a normal search, this fixes the KeyText value, and then repeat the search by setting the SearchText and issuing the appropiate Action command. The repeat result is returned the same as the non-repeating search.

To retrieve the appropiate Soundex code, set the word in the KeyText property and issue the appropiate action command. The Soundex code is returned as a STRING ( for both the Standard Soundex and the Integer Soundex code retieval ) in the SoundexCode property.

Usage

[form.]CALCKER.Action[ = setting %]

Settings

The Action property settings are:

Setting	        Value	Description

IDC_SNDEX_STDSEARCH 	20	Perform standard Soundex search

IDC_SNDEX_INTSEARCH 	21	Perform modified Soundex search

IDC_SNDEX_GETSTDCODE	25	Retreive the Soundex standard code

IDC_SNDEX_GETINTCODE	26	Retrieve the Soundex integer code

IDC_SNDEX_REPEATSTD	30	Repeat previous Soundex standard search.

IDC_SNDEX_REPEATINT	31	Repeat previous Soundex Integer search

Remarks

The return result of a search is available in "SoundsLike" property immediately after issuing the appropriate action command. See programming examples for more detail on use of the Action properties.

Data Type

All Action parameters are constant Integers.


KeyText
KeyText Property, SNDDEX Control

One of the two words presented for searching. For a repeat search, this property is set once and the SearchText property is varied for successive searches.

Value

Any valid VB string. Numbers, punctuation marks, and spaces are ignored by the Soundex algorithm.

See Soundex for details on individual character to Soundex code conversion.


SearchText
SearchText Property, SNDDEX Control

One of the two words presented for searching.

Value

Any valid VB string. Numbers, punctuation marks, and spaces are ignored by the Soundex algorithm.

See Soundex for details on individual character to Soundex code conversion.


SoundsLike
SoundsLike Property, SNDDEX Control

The result returned from a Soundex search or a request for a Soundex code. The returned value is placed in the SNDDEX.VBX property SoundsLike.

Value

Value returned is dependent on the action parameter sent to the control. For a nomal and repeat search where both the KeyText and the Search Text is provided the return values are as follows.:

0	Soundex code DOES NOT match

1	Soundex code DOES match

For retreiving the Soundex code, the property SoundsLike is the actual Soundex code. The Soundex code value returned is an integer.


SoundexCode
SoundexCode Property, SNDDEX Control

The result returned from a Soundex code request. The returned value is placed in the SNDDEX.VBX property SoundexCode.

Value

String value returned is dependent on the action parameter sent to the control. See the Action properties for the appropiate values.

For retreiving the Soundex code, the property SoundexCode is the actual Soundex code. The Soundex code value returned is an Alphanumeric String of four or less characters.


Soundex
Soundex Technology Brief

How it works.

Soundex searching is a word search algorithm that compares two words for a similar sound match. Soundex searching is often used to search for names in databases, although it is by no means restricted to name searching. The typical use is to find a name when the exact spelling may not be known. The Soundex code returned from the algorithm is a alphanumeric representation of the words being converted.

Soundex searching is accomplished by taking two words, generating the Soundex code for each word, and then comparing the resultant Soundex codes. SNDDEX.VBX returns only the result of this comparison, giving only a yes/no result.

In SNDDEX.VBX these two words are arbitrarily represented by the properties "KEYTEXT" and SEARCHTEXT. You may use either property for either word, but for searching long lists of words for a match, the algorithm used by SNDDEX.VBX will run slightly faster if the KEYTEXT property is the fixed one, and SEARCHTEXT is the variable one.

Soundex codes that are generated by the Soundex algorithm are four characters long, so very long words, or multiple words may not fully compute to a proper match code. For these reasons, the developer should exercise some care in structuring the word presentation to SNDDEX.VBX to maximize the search effectiveness.

Soundex Code	Letters

1	B,F,P,V

2	C,G,J,K,Q,S,X

3	D,T

4	L

5	M,N

6	R

The above table shows how letters in a word are converted into the appropriate Soundex code. Letters not shown are ignored and generate no Soundex code. When the number of Soundex code characters generated equals four, searching stops and the Soundex code is ready for comparison.

The main difference in the standard Soundex search and the modified Soundex search is the use of the first character in the word. In the standard Soundex search, the first character is used as is. Therefore words which do not begin with the same first character cannot match, In the modified version of Soundex, a Soundex code is generated for the first character in the word, so the searching is somewhat relaxed over the standard version.

Soundex is presented in detail in several books on algorithms, so if you desire more information It is suggested you look in one of these texts,