Wintertree Software Inc.

Sentry Spelling Checker Engine - Support

Home Site index Contact us Catalog Shopping Cart Products Support Search

You are here: Home > Support > Sentry Spelling Checker Engine > Most or all words reported as misspellings (Windows SDK)

Most or all words reported as misspellings

Product: Sentry Spelling Checker Engine Windows SDK

Problem: When checking text, the Sentry engine reports all or most words as misspellings.


This problem is almost always the result of a configuration error on the run-time system. Sentry DLL attempts to open the dictionary files indicated by the MainLexPath and MainLexFiles properties. If the properties are not defined, are not set in the place the Sentry DLL expects to find them, or are set incorrectly, the dictionaries will not be opened. Because the dictionary cannot be opened, its contents cannot be loaded into memory, and any words contained within the dictionary file will be reported as misspelled.

Note: If your application calls SSCE_OpenLex directly, and does not set MainLexPath and MainLexFiles, please see Most or all words reported as misspelled (Core API). That document describes conditions which cause SSCE_OpenLex to fail.

The main American English dictionaries are shipped as two files: ssceam.tlx and ssceam2.clx (substitute "br" for "am" in the file name for British English, and "ca" for "am" for Canadian English). The first file contains about 1,000 of the most commonly used words. The second file contains about 100,000 of the most commonly used words. Words in the first file are also present in the second file.

If the Sentry engine accepts words such as "the" or "of" but doesn't accept less common words such as "engine" or "improvement", the most likely cause is failure to open the ssceam2.clx file. If Sentry rejects all words including very common words such as "the" and "of", the most likely cause is failure to open any dictionary files.

MainLexPath and MainLexFiles

The first step in diagnosing a problem like this is to make sure you have set the MainLexPath and MainLexFiles properties on the run-time system. When you install the Sentry Windows SDK on your development system, the setup program included with the product automatically creates MainLexPath and MainLexFiles properties. When you run one of the examples included with the Sentry Windows SDK, or test the Sentry engine during integration with your application, the Sentry DLL reads these properties and successfully opens its dictionary files, so everything works fine. However, when you install your application on another system (the run-time system), MainLexPath and MainLexFiles must also be defined on that system, or the Sentry DLL will not know which dictionary files to open and will therefore not open any, causing all words to be reported as misspelled. A very common support question is, "When I run my application on my development system, the spelling checker works great. But when I run my application on a customer's system, every word is reported as misspelled." The reason is often that MainLexPath and MainLexFiles were not set up on the run-time system. If you haven't set them up, or aren't even sure what we mean by MainLexPath and MainLexFiles, read the topic titled "How to install the Sentry run-time software with your applications" in the "Using the Sentry Windows SDK" chapter of the Sentry programmer's guide. If you're still having problems after you have set up MainLexPath and MainLexFiles on the run-time system, keep reading. The important thing to note here is that MainLexPath and MainLexFiles must be set up correctly on the run-time system, and it is your responsibility to do so.

Before it checks spelling the first time after being loaded by an application, the Sentry DLL initializes itself, meaning it opens dictionaries and sets options. It determines which dictionaries to open and which options to set by examining properties. Properties are settings in the system registry or INI file. By default, the Sentry DLL looks for its properties in the system registry. The Sentry DLL will look for its properties in a INI file only if your application calls SSCE_SetIniFile. By default, when the Sentry DLL looks for its properties in the system registry, it looks for them under HKEY_CURRENT_USER\Software\Wintertree\SSCE. Your application can tell the Sentry DLL to look for its properties in a different registry tree by calling SSCE_SetRegTreeName. It's important to note that calling SSCE_SetIniFile simply tells the Sentry DLL to use an INI file when it needs to read properties, and calling SSCE_SetRegTreeName simply tells the DLL which registry tree to look under when it needs to read properties. Neither function causes the Sentry DLL to read or re-read properties. The important implication of this is that you must call SSCE_SetIniFile or SSCE_SetRegTreeName before you check spelling or do anything else that might cause the Sentry DLL to initialize itself. Otherwise, the Sentry DLL will look in the default tree in the registry for its properties. It might find nothing there, in which case it will open no dictionaries and therefore report all words as misspelled, or it might find residual information set up by some other application there, which may or may not be correct. To be safe, it's a good idea to call SSCE_SetRegTreeName or SSCE_SetIniFile early in your application, such as when it first starts (again, you need to call these functions only if you want the Sentry DLL to read its properties from somewhere other than HKEY_CURRENT_USER\Software\Wintertree\SSCE in the registry, which is the default). The only function in the Sentry API which should be called before these two functions is SSCE_SetKey.

You can configure the MainLexFiles and MainLexPath properties in either of two ways:

If your application sets up MainLexPath and MainLexFiles at installation time, potential causes of error include creating the values in the wrong registry tree or misspelling the property names. The Sentry DLL looks in the registry under HKEY_CURRENT_USER\Software\Wintertree\SSCE by default. If your setup program creates values under a different tree, your application must call SSCE_SetRegTreeName and pass the name of that tree. If the registry tree into which your setup program created values does not match the tree passed to SSCE_SetRegTreeName, the properties will not be read, no dictionaries will be opened, and all words will be reported as misspelled. Similarly, if your application uses an INI file to hold Sentry properties, the location and name of the INI file installed by your setup program must match the path name passed to SSCE_SetIniFile, or the Sentry DLL will be unable to open the INI file. The names of the MainLexPath and MainLexFiles properties must be spelled correctly in the INI file, and must be located under the [SSCE User] section (the section name must also be spelled and formed correctly). Also, if your application calls SSCE_SetIniFile, it should pass a full, absolute path to the INI file (i.e., the path should start with "x:\" or "\\").

If your application sets up MainLexPath and MainLexFiles at run time, the Sentry DLL will record the settings in system registry or INI file (depending on whether SSCE_SetIniFile had been called previously). If the settings are recorded in the system registry, they will be written under the default tree (HKEY_CURRENT_USER\Software\Wintertree\SSCE) or under the tree indicated by the value passed to SSCE_SetRegTreeName, if that function was called. Note that your application usually needs to call SSCE_SetMainLexPath and SSCE_SetMainLexFiles just once, the first time it runs. After that, the Sentry DLL will be able to read the last values from the registry or INI file.

Here is a summary of where and when the Sentry DLL reads and writes its properties:

Dictionary files

Assuming the MainLexPath and MainLexFiles properties have been set, and the Sentry DLL is able to find and read them, the next step is to open the dictionary files. MainLexPath indicates the path to the default folder which contains the dictionary files. MainLexFiles contains a comma-separated list of dictionary files. If the dictionary file names in MainLexFiles themselves contain no paths (which is normally the case), the Sentry DLL prefixes the value of MainLexPath onto each dictionary file name like this:

<MainLexPath> + "\" + <file name from MainLexFiles>

If MainLexPath contains "c:\Program Files\myapp\dicts", and MainLexFiles contains "ssceam.tlx,ssceam2.clx", the Sentry DLL would attempt to open the following dictionary files:

c:\Program Files\myapp\dicts\ssceam.tlx
c:\Program Files\myapp\dicts\ssceam2.clx

If a file listed in MainLexFiles contains a full path, then that path will be used in place of MainLexPath. If MainLexFiles contains "ssceam.tlx,ssceam2.clx,c:\Program Files\Common Files\spelling\medical.clx", then the Sentry DLL would attempt to open the following dictionary files:

c:\Program Files\myapp\dicts\ssceam.tlx
c:\Program Files\myapp\dicts\ssceam2.clx
c:\Program Files\Common Files\spelling\medical.clx

When the Sentry DLL opens a dictionary, it asks Windows to open the file. If Windows is unable to open the file, the Sentry DLL will not be able to open the dictionary, and any words contained by the dictionary will be reported as misspelled. Typical reasons Windows will be unable to open the dictionary file include:

An important point to consider is that the Sentry DLL passes the dictionary file names to Windows verbatim for opening. If Windows returns an error code, the Sentry DLL stops attempting to open the dictionary file. It doesn't search for the dictionary file in other folders, try different spellings of the dictionary file name, or magically blast through the file system's permissions to open the file at all costs. The Sentry DLL merely tries to open the files configured in MainLexPath and MainLexFiles, and if it can't open one or more of them, words contained within the unopenable files will be reported as misspelled. It's worth mentioning that failure to open a main dictionary file does not result in error messages displayed to the user. This is both a blessing and a curse: The user is not confronted with confusing messages about dictionary files, but it can be more difficult for you to detect that a problem has occurred and diagnose the cause of that problem.

Another, though less common, cause of dictionary open failure is file corruption. ssceam2.clx (and all dictionary files with a .clx extension) are binary files. If these files are transferred from one system to another using "ASCII" or "Text Mode" file transfer, they will be corrupted. If the dictionaries were once openable but the Sentry DLL suddenly started returning errors on attempts to open them, and no other changes took place on the run-time system, it's possible that the dictionary files became corrupted through file system corruption or some other cause. Replacing the files should solve the problem.

A problem related to corruption is attempting to open a dictionary file which is in a format inappropriate for your version of the Sentry engine. This usually happens only with compressed dictionary files (which have a .clx extension). The "2" in the dictionary file name (e.g., ssceam2.clx) indicates the internal format version of the dictionary file. A "2" format version is compatible with the Sentry engine version 5.1 and later. If you are using, for example, version 5.15 of the Sentry engine, the .clx files you use should have names like sscexx2.clx. When you purchase supplemental dictionaries from Wintertree Software, dictionary files in both the current "2" format version and the older "1" format version will be included. For example, Wintertree Software's French dictionary product includes files sscefr1.clx and sscefr2.clx. You must use the file appropriate to your version of the Sentry engine. If you attempt to use sscefr1.clx with a Sentry engine version 5.1 or later, the file will not be opened. Similarly, if you attempt to use sscefr2.clx with Sentry engine version 4.22 or earlier, the file will not be opened.

If the dictionary files open successfully but many words are still reported as misspelled, a potential cause is assigning a relative path name to MainLexPath. Under some circumstances, the Sentry engine will re-open a compressed (.clx) lexicon file while checking spelling or looking up suggestions to load parts of the dictionary not cached in memory. To re-open the file, it uses the path name formed by prefixing the MainLexPath value onto the dictionary file name. If MainLexPath is relative, and the calling application's current directory has changed, the attempt to re-open the file may fail. As a result, the needed parts of the dictionary are not loaded into memory, and the words contained within those parts are reported as misspelled. The path assigned to MainLexPath should therefore always be absolute (i.e., should start from the file system's root directory).

Here are some things you can try to diagnose the cause and solve dictionary problems:

Home Site index Contact us Catalog Shopping Cart Products Support Search

Copyright © 2015 Wintertree Software Inc.