|
|
Sentry Spelling Checker Engine - Support |
|
Home |
You are here: Home > Support > Sentry Spelling Checker Engine > Most or all words reported as misspellings (Windows SDK)
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.
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:
At installation time, where your application's setup program creates values in the system registry, or installs an INI file containing the correct values on the run-time system
At run time, where your application calls SSCE_SetMainLexPath and SSCE_SetMainLexFiles.
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:
By default, the Sentry DLL reads and writes its properties in the system registry, under the HKEY_CURRENT_USER\Software\Wintertree\SSCE tree.
If your application calls SSCE_SetRegTreeName, the Sentry DLL will continue to read and write its properties in the system registry, but will use the registry tree you specify.
If your application calls SSCE_SetIniFile, the Sentry DLL will stop reading and writing its properties in the system registry, and will instead read and write them from the INI file you specify.
Calling SSCE_SetRegTreeName or SSCE_SetIniFile has no effect on the current state of the Sentry DLL. The Sentry DLL won't use the registry tree or INI file you specify until it next needs to read or write properties. (It's like giving someone your new phone number. That person won't (necessarily) call you right away, but will use the number the next time they call you.)
To ensure that the Sentry DLL reads the correct properties, call SSCE_SetRegTreeName or SSCE_SetIniFile (if they are called at all) before calling any other functions in the Sentry API except SSCE_SetKey.
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:
The dictionary file name or part of the path name is misspelled. Example: ssceam2.clx is contained in directory \myapp\dicts on the run-time system. MainLexPath is set to "\myapp\dict", or MainLexFiles is set to "ssceam.tlx,ssecam2.clx" (look carefully to spot the misspellings!).
The path name assigned to MainLexPath is syntactically incorrect. Example: If MainLexPath is set to "c\:myapp\dicts", Windows will refuse to open any dictionary files (the correct form is "c:\myapp\dicts"). Another possible hard-to-spot cause is spaces at the beginning or end of the path name assigned to MainLexPath, a space after the comma separator in MainLexFiles, or a space at the end or beginning of the MainLexFiles value.
One or more of the dictionary files listed in MainLexFiles are not contained in the folder indicated by MainLexPath. For example, ssceam2.clx is contained in folder c:\myapp\dicts on the run-time system, but MainLexPath is set to "c:\myapp\dicts\am". Another possibility: MainLexPath is set correctly, but you forgot to actually copy the dictionary files to that folder, or one or more of the dictionary files were subsequently deleted for some reason.
If the file system supports permissions, the permissions assigned to the dictionary files or the folders in MainLexPath may prevent the application from opening them. The Sentry DLL is a software library used by an application. When used by your application, it essentially becomes part of your application, and has exactly the same capabilities and authority. If your application can't open a file, the Sentry DLL won't be able to, either.
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:
Set the DebugFile property (click here for instructions). The Sentry engine will record diagnostic information in the file you configure, including the names of dictionary files it tries to open and the results of those attempts. Sometimes by examining the contents of the diagnostic file you may be able to spot the problem, such as a malformed or misspelled path. If you contact Wintertree Software's Support group for help with solving dictionary related problems, the first thing they will ask is that you set the DebugFile property and send the file's contents, so you can save time by including the contents when you contact Support initially.
If you have Sentry Windows SDK version 5.15 and later, you can copy the Sentry Example Program (located in \Program Files\ssce\sdk\examples\mfc\mfcexample.exe) onto the run-time system. Click on the Configuration button to examine the MainLexPath and MainLexFiles settings. If necessary, select "INI file name" and enter the full name of your INI file, or select "Registry tree" and enter the path to the registry tree containing your Sentry settings (you can prefix the path with HKEY_LOCAL_MACHINE if the default of HKEY_CURRENT_USER is incorrect). Click the Change button if you have made any changes, and the values of MainLexPath and MainLexFiles will be displayed. If the MainLexPath and MainLexFiles fields remain empty, double-check your changes and make sure the indicated INI file or registry tree actually exist. Once you do see values in the MainLexPath and MainLexFiles fields, click the Test button. Each dictionary file will be opened, and the results of the open attempt will be displayed.
Copyright © 2015 Wintertree Software Inc.
