NLKEYCOMPARE
MPE documents | |
 Complete PDF | |
| Table of Contents | |
| Index | |
| Edition 7 E0701 ♥ | |
| Edition 7 E0300 | |
| Edition 6 E0195 |
Syntax
CA I16V CA I16V
NLKEYCOMPARE (generickey, length1, key, length2,
I16 I16V U16A U16A
result, langnum, error, collseq);
Parameters
- generickey
character array (required)
Passes the generic key to be compared to the keys contained in the record read by FREAD.
- length1
16-bit signed integer by value (required)
Contains the length, in bytes, of generickey, which must be less than length2.
- key
character array (required)
Passes an entire key to which you want to compare generickey.
- length2
16-bit signed integer by value (required)
Contains the length in bytes of key, which must be greater than length1.
- result
16-bit signed integer by reference (required)
Returns the result of the compare:
Value Meaning 0 The retrieved key matches the generic key exactly for a length of length. 1 The retrieved key does not match the generic key; it is different only because of priority (for example, uppercase versus lowercase characters or accent). The FREAD key is still in range; records can follow whichever key matches the generic key exactly. 2 The retrieved key is less than the generic key (its collating order precedes the key specified). It does not match generickey. This means the FREAD call found a record that precedes the range requested. Records that match generickey can follow. 3 The retrieved key is greater than the generic key (it collates after the specified key). This means that the FREAD call found a record whose key follows the specified range. No records matching generickey follow. - langnum
16-bit signed integer by value (required)
Contains the language ID number, specifying the collating sequence to be used for the compare.
- error
16-bit unsigned integer array (required)
Returns two elements: the first element is the error number; the second element is reserved and always returns 0. The possible error number values are:
Value Meaning 0 Successful 1 *NLS not installed 2 *Specified language not configured 3 Invalid collating table entry 4 Invalid length parameter 5 *NLS internal error 6 *NLS internal error 7 Value of length1 not less than length2 * Does not apply to calls with a langnum equal to 0 (NATIVE3000/XL).
- collseq
16-bit unsigned integer array (optional)
Passes the collating sequence table as returned by NLINFO item 11. If this parameter is present, langnum is ignored, and this routine is much more efficient.
Operation Notes
Use NLKEYCOMPARE when reading a KSAM file in key sequential order in combination with FREAD, and after a FFINDBYKEY call. The NLKEYCOMPARE intrinsic lets a program determine whether a generic key search found an exact match (that is, the generic key is exactly equal to the beginning of the key), or whether the keys are different only because of priority (for example, uppercase versus lowercase or accent). It also lets the program determine whether an exactly matching key could be farther along the key sequence.
Related Information
| Intrinsics | NLCOLLATE, NLCOLLATE2, NLFINDSTR, NLJUDGE, NLREPCHAR, NLSCANMOVE, NLSUBSTR, NLSWITCHBUF, NLTRANSLATE |
| Manuals | Native Language Programmer's Guide |
|
NLJUDGE |
NLMATCH |