NLS collating sequences differ from the USASCII collating, and the differences must be considered when
performing generic key searches. Refer to the Native Language Support Reference Manual (32414-90001)
for more information.
The description of a generic key search in a KSAM file with a native language attribute is presented from
an application point of view.
Keys matching a certain generic key may not be in consecutive order in the key file because the keys are
sorted according to a native language collating sequence. The key sequence in Figure F-3 “Generic Key Searches” illustrates this
with a French KSAM file; keylength is 4, the generic key length is 2. The partial key "aa" appears in
nonconsecutive keys (with a result of 0 in the last column of the figure). Records containing partial keys (such
as "AA" or "Aa"0 are intermixed according to the French collating sequence. These keys have a result of 1
listed.
If a generic key search is performed in a KSAM file with a language attribute other than NATIVE-3000,
the application program must determine whether the retrieved record matches the generic key and, even if
it does not, whether subsequence records might still match it.
The codes returned by NLKEYCOMPARE are shown in Figure F-2 “Results Returned By The NLKEYCOMPARE Intrinsic”.
Refer to the Native Language Support Reference Manual (32414-90001) for a complete discussion of the
NLKEYCOMPARE intrinsic.
Figure F-2 Results Returned By The NLKEYCOMPARE Intrinsic
| RESULT | MEANING |
|---|
| 0 | The retrieved key matches the generic key exactly.
|
| 1 | The retrieved key does not match the generic key.
Uppercase/lowercase priority or accent priority is different.
|
| 2 | The retrieved key value is less than the generic key. It precedes the designated key in the collating sequence.
|
| 3 | The retrieved key is greater than the generic key.
|
The generic key search sequence is:
After FFINDBYKEY has been called with >= as relational operator(relop), the logical record pointer
points to the data records indicated by the arrow labeled "Case 2".
The subsequent FREAD call will retrieve the data record. When the partial key "AA" is compared to the
generic key "aa" they are found to be different.
This comparison is done by calling the intrinsic NLKEYCOMPARE using the generic key and the key found
in the record. The result returned by NLKEYCOMPARE tells the application whether the FREAD delivered a
record:
Before the desired range (result 2).
In the desired range with an uppercase/lowercase or accent priority difference (result 1).
With an exact match (result 0).
After the desired range (result 3).
To get all records whose key match the generic key exactly, the FREAD calls and subsequent
NLKEYCOMPARE call should continue until a result of 3 is returned.
When performing a generic key search in a KSAM file with a native language attribute other than
NATIVE-3000 use the NLKEYCOMPARE intrinsic to compare partial keys and generic keys.
Refer to the Native Language Support Reference Manual (32414-90001) for examples of generic key
searches in KSAM files with native language attributes.
Figure F-3 Generic Key Searches
Key length: 4
Language: FRENCH (only USASCII characters are used in the example).
Desired records are all records whose record key starts with "aa" (generic key = "aa", length = 2) .
|
| Pointer Position | Key Value | NLKEYCOMPARE Result ("aa" Compared to Key) |
|---|
| Case 1---> | A | 2 |
| | a | 2 |
| Case 2---> | AA | 1 |
| | Aa | 1 |
| | aA | 1 |
| | aa | 0 |
| | AAA | 1 |
| | aaa | 0 |
| | AAAA | 1 |
| | AAAa | 1 |
| | AAaa | 1 |
| | AaAa | 1 |
| | AaaA | 1 |
| | Aaaa | 1 |
| | aAAA | 1 |
| | aAAa | 1 |
| | aAaA | 1 |
| | aaAA | 0 |
| | aaaA | 0 |
| | aaaa | 0 |
| Case 3---> | Baaa | 3 |
| | baaa | 3
|
Case: 1. FREAD starting at the beginning of the file.
2. FFINDBYKEY with relational operator = or >= and subsequent FREAD calls.
3. FFINDBYKEY with relational operator > and subsequent FREAD calls.
Key Value: Key values in ascending sequence.
|
