SetCollation Function (String) |  |
Return and optionally change the setting that determines the internal collation routine used for string comparisons.
Namespace: XSharp.Core
Assembly: XSharp.Core (in XSharp.Core.dll) Version: 2.19
SyntaxRequest Example
View Source
If symNewSetting is not specified, SetCollation() returns the current setting.
If symNewSetting is specified, the previous setting is returned.
The current setting, either "Windows" (the default), "Clipper", "Unicode" or "Ordinal"
Parameters
- symNewSetting
- Type: String
The collation mode to use.
The available modes are #Windows (the default) and #Clipper.
Return Value
Type: StringIf symNewSetting is not specified, SetCollation() returns the current setting.
If symNewSetting is specified, the previous setting is returned.
Return Value
Type: StringThe current setting, either "Windows" (the default), "Clipper", "Unicode" or "Ordinal"
Remarks
SetCollation() sets the internal collation routine that is used for all string comparisons, except the ones done using the == operator. Note that this includes sort and index operations, as well as programmatic string comparisons using the various operators.
Note: Changing SetInternational() automatically changes SetCollation() so that the two settings are the same.
This setting allows X# to operate in different collation modes.
The #Clipper mode is provided for compatibility with CA-Clipper applications and uses a collation routine defined in the nation module (VO28NAT.DLL).
The #Windows mode uses string comparison services provided by Windows that automatically handle foreign character sets. Therefore, if an application uses the #Clipper collation mode, it will behave the same on all machines. Thus, to achieve a different collation sequence based on a language other than English, you would need a version of VO28NAT.DLL specialized to the desired language. On the other hand, if the application uses the #Windows collation mode, it will behave differently from machine to machine, depending on the language defined in the International settings of the Control Panel. In this case, all languages supported by Windows are also supported by your application, including right-to-left languages, such as Hebrew and Arabic, and double-byte languages, such as Chinese, Japanese, and Korean. Note: String functions, such as Substr() and SLen(), that operate at the byte level will not function correctly with double-byte characters. The collation sequence for the regular Latin character set is different for #Clipper and #Windows.
For #Clipper: A < B < C < ... < Z < a < b < c < ... < z For #Windows: A < a < B < b < C < c < ... < Z < z Warning! SetCollation() determines how index files and the orders within them are created and maintained.
Attempting to use different collation modes in the same order will corrupt the order.
The #Clipper mode is provided for compatibility with CA-Clipper applications and uses a collation routine defined in the nation module (VO28NAT.DLL).
The #Windows mode uses string comparison services provided by Windows that automatically handle foreign character sets. Therefore, if an application uses the #Clipper collation mode, it will behave the same on all machines. Thus, to achieve a different collation sequence based on a language other than English, you would need a version of VO28NAT.DLL specialized to the desired language. On the other hand, if the application uses the #Windows collation mode, it will behave differently from machine to machine, depending on the language defined in the International settings of the Control Panel. In this case, all languages supported by Windows are also supported by your application, including right-to-left languages, such as Hebrew and Arabic, and double-byte languages, such as Chinese, Japanese, and Korean. Note: String functions, such as Substr() and SLen(), that operate at the byte level will not function correctly with double-byte characters. The collation sequence for the regular Latin character set is different for #Clipper and #Windows.
For #Clipper: A < B < C < ... < Z < a < b < c < ... < z For #Windows: A < a < B < b < C < c < ... < Z < z Warning! SetCollation() determines how index files and the orders within them are created and maintained.
Attempting to use different collation modes in the same order will corrupt the order.
Remarks
The Core dialect always compares according to the Unicode rules.
The other dialects use the rules defined with SetCollation for string comparison. There are 4 possible values:
| Parameter | Description |
|---|---|
| Windows (the default) |
This uses the normal windows Ansi comparison mechanism that Visual Objects uses as well.
That means that the Unicode strings from .Net are converted to Ansi first and then compared with the Ansi comparison rules.
In most cases characters that are not available in the Ansi codepage are translated to a question mark '?' and are therefore all seen as equal. If you want true unicode comparison you need the Unicode value for SetCollation. |
| Clipper | This uses string comparison tables that are the same as the character comparison tables in the Visual Objects nation modules. Each character from the unicode string is converted to a character from the OEM codepage first using the DosCodePage from the runtime state. the resulting OEM characters are then looked up in the 256 character weight tables that are part of the runtime dll. You can switch to a different table by using SetNatDLL(). |
| Unicode | This uses the normal Unicode String.Compare routines for string comparisons. |
| Ordinal | This uses the normal Ordinal String.Compare routines from DotNet. This is the fastest. |
Examples
This example, based on the Start() method for the Standard Application, checks the current Windows language configuration, allowing the application to run only when set to use the French language collation:
X#
1METHOD Start() CLASS App 2 LOCAL oWindow AS Window 3 LOCAL nLen, nBufSize := 10 AS SHORTINT 4 LOCAL pszLang := Psz(Space(nBufSize)) AS PSZ 5 // Initialize StandardShellWindow 6 Enable3DControls() 7 oWindow := StandardShellWindow{SELF} 8 oWindow:Show() 9 // Retrieve language collation setting from WIN.INI 10 nLen := GetProfileString("intl", "sLanguage", ; 11 "", pszLang, nBufSize)
X#
1// Run application only if system configured to use 2// French Windows collation 3IF (Left(String(_CAST, pszLang), nLen) != "fra") 4 // Incorrect language so give error and quit. 5 TextBox{oWindow, "System Configuration", ; 6 "You must have the Language set to " + ; 7 "'French' in the International " + ; 8 "section of your Control Panel to " + ; 9 "run this application."}:Show() 10ELSE 11 // Run application 12 SELF:Exec() 13ENDIF
See Also