JetMakeKey-Funktion
Gilt für: Windows | Windows Server
JetMakeKey-Funktion
Die JetMakeKey-Funktion erstellt Suchschlüssel, die dann verwendet werden können, um einen Satz von Einträgen in einem Index mit einigen einfachen Suchkriterien für ihre Schlüsselspaltenwerte zu finden. Ein Suchschlüssel ist auch eine der systeminternen Eigenschaften eines Cursors und wird von den JetSeek- und JetSetIndexRange-Vorgängen verwendet, um Indexeinträge zu finden, die diesen Suchkriterien im aktuellen Index dieses Cursors entsprechen. Ein vollständiger Suchschlüssel wird in einer Reihe von JetMakeKey-Aufrufen erstellt, wobei jeder Aufruf verwendet wird, um den Spaltenwert für die nächste Schlüsselspalte des aktuellen Indexes eines Cursors zu laden. Es ist auch möglich, einen zuvor erstellten Suchschlüssel zu laden, der mit jetRetrikeyaus dem Cursor abgerufen wurde.
JET_ERR JET_API JetMakeKey(
__in JET_SESID sesid,
__in JET_TABLEID tableid,
__in_opt const void* pvData,
__in unsigned long cbData,
__in JET_GRBIT grbit
);
Parameter
sesid
Die Sitzung, die für diesen Aufruf verwendet werden soll.
tableid
Der Cursor, der für diesen Aufruf verwendet werden soll.
pvData
Der Eingabepuffer, der die Spaltendaten für die aktuelle Schlüsselspalte des aktuellen Indexes des Cursors enthält, für den der Suchschlüssel erstellt wird.
Der Datentyp der Spaltendaten im Eingabepuffer muss genau mit dem Datentyp und anderen Eigenschaften der Spaltendefinition der aktuellen Schlüsselspalte übereinstimmen. Es wird keine Typkoercion für die Spaltendaten ausgeführt.
Wenn JET_bitNormalizedKey im grbit-Parameter angegeben ist, muss der Eingabepuffer einen zuvor erstellten Suchschlüssel enthalten. Solche Schlüssel werden mithilfe eines Aufrufs von JetRetrikey erhalten.
cbData
Die Größe der im Eingabepuffer bereitgestellten Spaltendaten in Bytes.
Wenn JET_bitNormalizedKey im grbit-Parameter angegeben wird, ist dies die Größe des Suchschlüssels, der im Eingabepuffer bereitgestellt wird.
Wenn die Größe der Spaltendaten null ist, wird der Inhalt des Eingabepuffers ignoriert. Wenn JET_bitKeyDataZeroLength im grbit-Parameter angegeben ist und die aktuelle Schlüsselspalte des aktuellen Indexes des Cursors eine Spalte variabler Länge ist, wird davon ausgegangen, dass die Eingabespaltendaten einen Wert der Länge 0 (null) haben. Andernfalls wird davon ausgegangen, dass die Eingabespaltendaten ein NULL-Wert sind.
grbit
Eine Gruppe von Bits, die null oder mehr der folgenden Optionen an geben.
Wert |
Bedeutung |
|---|---|
JET_bitFullColumnEndLimit |
Der Suchschlüssel sollte so erstellt werden, dass alle Schlüsselspalten, die nach der aktuellen Schlüsselspalte stehen, als Platzhalter betrachtet werden. Dies bedeutet, dass der konstruierte Suchschlüssel verwendet werden kann, um Indexeinträge mit den folgenden Angaben zu suchen:
Diese Option sollte beim Erstellen von Platzhalter-Suchschlüsseln verwendet werden, die zum Suchen von Indexeinträgen verwendet werden, die dem Ende eines Indexes am nächsten sind. Das Ende des Indexes ist der Indexeintrag, der beim Wechsel zum letzten Datensatz in diesem Index gefunden wird. Das Ende des Indexes ist nicht dasselbe wie das obere Ende des Index, das sich je nach Sortierreihenfolge der Schlüsselspalten im Index ändern kann. Diese Option ist nur für xp Windows und spätere Versionen verfügbar. |
JETbitFullColumnStartLimit |
Der Suchschlüssel sollte so erstellt werden, dass alle Schlüsselspalten nach der aktuellen Schlüsselspalte als Platzhalter betrachtet werden. Dies bedeutet, dass der konstruierte Suchschlüssel verwendet werden kann, um Indexeinträge mit den folgenden Angaben zu suchen:
Diese Option sollte beim Erstellen von Platzhalter-Suchschlüsseln verwendet werden, die zum Suchen von Indexeinträgen verwendet werden sollen, die am nächsten am Anfang eines Indexes sind. Der Anfang des Index ist der Indexeintrag, der beim Verschieben zum ersten Datensatz in diesem Index gefunden wird. Der Anfang des Indexes ist nicht mit dem unteren Ende des Indexes identisch, der sich je nach Sortierreihenfolge der Schlüsselspalten im Index ändern kann. Diese Option ist nur für xp Windows und spätere Versionen verfügbar. |
JET_bitKeyDataZeroLength |
Wenn die Größe des Eingabepuffers 0 (null) ist und die aktuelle Schlüsselspalte eine Spalte variabler Länge ist, gibt diese Option an, dass der Eingabepuffer einen Wert der Länge 0 (null) enthält. Andernfalls würde eine Eingabepuffergröße von 0 (null) einen NULL-Wert angeben. |
JET_bitNewKey |
Es sollte ein neuer Suchschlüssel erstellt werden. Alle zuvor vorhandenen Suchschlüssel werden verworfen. |
JET_bitNormalizedKey |
Wenn diese Option angegeben wird, werden alle anderen Optionen ignoriert, alle zuvor vorhandenen Suchschlüssel werden verworfen, und der Inhalt des Eingabepuffers wird als neuer Suchschlüssel geladen. |
JET_bitPartialColumnEndLimit |
Der Suchschlüssel sollte so erstellt werden, dass die aktuelle Schlüsselspalte als Präfix-Platzhalter betrachtet wird und dass alle Schlüsselspalten, die nach der aktuellen Schlüsselspalte stammen, als Platzhalter betrachtet werden sollten. Dies bedeutet, dass der konstruierte Suchschlüssel verwendet werden kann, um Indexeinträge mit den folgenden Angaben zu suchen:
Diese Option sollte beim Erstellen von Platzhalter-Suchschlüsseln verwendet werden, die zum Suchen von Indexeinträgen verwendet werden, die dem Ende eines Indexes am nächsten sind. Das Ende des Indexes ist der Indexeintrag, der beim Wechsel zum letzten Datensatz in diesem Index gefunden wird. Das Ende des Indexes ist nicht dasselbe wie das obere Ende des Index, das sich je nach Sortierreihenfolge der Schlüsselspalten im Index ändern kann. Diese Option kann nicht verwendet werden, wenn die aktuelle Schlüsselspalte keine Textspalte oder variable binäre Spalte ist. Der Vorgang kann nicht durchgeführt werden JET_errInvalidgrbit wenn dies versucht wird. Diese Option ist nur für xp Windows und spätere Versionen verfügbar. |
JET_bitPartialColumnStartLimit |
Diese Option gibt an, dass der Suchschlüssel so konstruiert werden soll, dass die aktuelle Schlüsselspalte als Präfix-Platzhalter betrachtet wird und dass alle Schlüsselspalten, die nach der aktuellen Schlüsselspalte kommen, als Platzhalter betrachtet werden sollen. Dies bedeutet, dass der konstruierte Suchschlüssel verwendet werden kann, um Indexeinträge mit den folgenden Angaben zu suchen:
Diese Option sollte beim Erstellen von Platzhalter-Suchschlüsseln verwendet werden, die zum Suchen von Indexeinträgen verwendet werden sollen, die am nächsten am Anfang eines Indexes sind. Der Anfang des Index ist der Indexeintrag, der beim Verschieben zum ersten Datensatz in diesem Index gefunden wird. Der Anfang des Indexes ist nicht mit dem unteren Ende des Indexes identisch, der sich je nach Sortierreihenfolge der Schlüsselspalten im Index ändern kann. Diese Option kann nicht verwendet werden, wenn die aktuelle Schlüsselspalte keine Textspalte oder variable binäre Spalte ist. Der Vorgang kann nicht durchgeführt werden JET_errInvalidgrbit wenn dies versucht wird. Diese Option ist nur für xp Windows und spätere Versionen verfügbar. |
JET_bitStrLimit |
Diese Option gibt an, dass der Suchschlüssel so erstellt werden soll, dass alle Schlüsselspalten, die nach der aktuellen Schlüsselspalte kommen, als Platzhalter betrachtet werden sollen. Dies bedeutet, dass der konstruierte Suchschlüssel verwendet werden kann, um Indexeinträge mit den folgenden Angaben zu suchen:
Diese Option sollte beim Erstellen von Platzhalter-Suchschlüsseln verwendet werden, die zum Suchen von Indexeinträgen verwendet werden, die dem Ende eines Indexes am nächsten sind. Das Ende des Indexes ist der Indexeintrag, der beim Wechsel zum letzten Datensatz in diesem Index gefunden wird. Das Ende des Indexes ist nicht dasselbe wie das obere Ende des Index, das sich je nach Sortierreihenfolge der Schlüsselspalten im Index ändern kann. Wenn diese Option in Kombination mit JET_bitSubStrLimit und die aktuelle Schlüsselspalte eine Textspalte ist, wird diese Option ignoriert. Dieses Verhalten soll ermöglichen, dass der Typ der aktuellen Schlüsselspalte beim Erstellen des Suchschlüssels abgeleitet wird. Wenn Sie einen ähnlichen Suchschlüssel für den Anfang eines Indexes erstellen möchten, sollte ein ähnlicher Aufruf von JetMakeKey für die letzte Schlüsselspalte vorgenommen werden, die kein Platzhalter ist, aber keine Platzhalteroptionen angegeben ist. Der Suchschlüssel befindet sich dann in einem geeigneten Zustand, der für eine solche Suche verwendet werden kann. Dies entspricht der Verwendung von JET_bitFullColumnStartLimit, mit der Ausnahme, dass der Suchschlüssel nicht wie nach der Verwendung einer Platzhalteroption sauber beendet wird. Diese Option ist für XP und Windows veraltet, um diese umkämte Semantik zu adressiert. JET_bitFullColumnStartLimit und JET_bitFullColumnEndLimit sollten stattdessen nach Möglichkeit verwendet werden. |
JET_bitSubStrLimit |
Diese Option gibt an, dass der Suchschlüssel so konstruiert werden soll, dass die aktuelle Schlüsselspalte als Präfix-Platzhalter betrachtet wird und dass alle Schlüsselspalten, die nach der aktuellen Schlüsselspalte kommen, als Platzhalter betrachtet werden sollen. Dies bedeutet, dass der konstruierte Suchschlüssel verwendet werden kann, um Indexeinträge mit den folgenden Angaben zu suchen:
Diese Option sollte beim Erstellen von Platzhalter-Suchschlüsseln verwendet werden, die zum Suchen von Indexeinträgen verwendet werden, die dem Ende eines Indexes am nächsten sind. Das Ende des Indexes ist der Indexeintrag, der beim Verschieben zum letzten Datensatz in diesem Index gefunden wird. Das Ende des Indexes ist nicht dasselbe wie das obere Ende des Indexes, das sich je nach Sortierreihenfolge der Schlüsselspalten im Index ändern kann. Wenn diese Option in Kombination mit JET_bitStrLimit angegeben wird und die aktuelle Schlüsselspalte eine Textspalte ist, hat diese Option Vorrang. Diese Option wird ignoriert, wenn die aktuelle Schlüsselspalte keine Textspalte ist. Dieses Verhalten soll es ermöglichen, dass der Typ der aktuellen Schlüsselspalte beim Erstellen des Suchschlüssels abgeleitet wird. Wenn Sie einen ähnlichen Suchschlüssel für den Anfang eines Indexes erstellen möchten, sollte ein ähnlicher Aufruf von JetMakeKey für die Schlüsselspalte erfolgen, die als Präfix-Platzhalter verwendet werden soll, wobei jedoch keine Platzhalteroptionen angegeben sind. Der Suchschlüssel befindet sich dann in einem geeigneten Zustand, der für eine solche Suche verwendet werden soll. Dies entspricht der Verwendung von JET_bitPartialColumnStartLimit, mit dem Unterschied, dass der Suchschlüssel nicht wie nach der Verwendung einer Platzhalteroption sauber abgeschlossen ist. Diese Option ist für Windows XP und höhere Versionen veraltet, um diese umständliche Semantik zu beheben. stattdessen sollten nach Möglichkeit JET_bitPartialColumnStartLimit und JET_bitPartialColumnEndLimit verwendet werden. |
Rückgabewert
Diese Funktion gibt den JET_ERR Datentyp mit einem der folgenden Rückgabecodes zurück. Weitere Informationen zu den möglichen ESE-Fehlern finden Sie unter Extensible Storage Engine Errors and Error Handling Parameters.
Rückgabecode |
Beschreibung |
|---|---|
JET_errSuccess |
Der Vorgang wurde erfolgreich abgeschlossen. |
JET_errClientRequestToStopJetService |
Es ist nicht möglich, den Vorgang abzuschließen, da alle Aktivitäten auf der Instanz, die der Sitzung zugeordnet ist, als Ergebnis eines Aufrufs von JetStopServiceaufgetreten sind. |
JET_errIndexTuplesKeyTooSmall |
Die bereitgestellten Spaltendaten waren zu klein, um einen gültigen Schlüssel für den aktuellen Index zu erstellen, da dieser Index ein Tupelindex ist und die minimale Tupelgröße größer als die bereitgestellten Spaltendaten war. Weitere Informationen zu Tupelindizes finden Sie unter JetCreateIndex. Dieser Fehler wird nur von Windows XP und späteren Versionen zurückgegeben. |
JET_errInstanceUnavailable |
Es ist nicht möglich, den Vorgang abzuschließen, da für die instanz, die der Sitzung zugeordnet ist, ein schwerwiegender Fehler aufgetreten ist, der erfordert, dass der Zugriff auf alle Daten widerrufen wird, um die Integrität dieser Daten zu schützen. Dieser Fehler wird nur von Windows XP und späteren Versionen zurückgegeben. |
JET_errInvalidBufferSize |
Die bereitgestellten Spaltendaten stimmten nicht mit der größe überein, die für die Spaltendefinition erforderlich ist. Dies kann passieren, wenn der Datentyp der Spalte intrinsisch eine bestimmte Größe hat. Dies kann auch der Fall sein, wenn der Datentyp der Spalte nicht systemintrinsisch eine bestimmte Größe hat, die Definition der Spalte sie jedoch als eine feste Länge deklariert. Eine Ausnahme besteht darin, dass dieser Fehler nicht auftritt, wenn für eine Textspalte mit fester Länge zu wenig Daten bereitgestellt werden, da fehlende Daten automatisch mit Leerzeichen aufgefüllt werden. Eine zweite Ausnahme besteht darin, dass dieser Fehler nicht auftritt, wenn für eine binäre Spalte mit fester Länge zu wenig Daten bereitgestellt werden, da fehlende Daten automatisch mit Nullen aufgefüllt werden. |
JET_errInvalidgrbit |
Eine der angeforderten Optionen war ungültig, wurde auf unzulässige Weise verwendet oder nicht implementiert. Dies kann für JetMakeKey passieren, wenn:
|
JET_errInvalidParameter |
Einer der bereitgestellten Parameter enthielt einen unerwarteten Wert oder einen Wert, der in Kombination mit dem Wert eines anderen Parameters nicht sinnvoll war. Dies kann bei JetMakeKey passieren, wenn JET_bitNormalizedKey angegeben wurde und der im Eingabepuffer angegebene Wert zu groß war, um ein gültiger Suchschlüssel zu sein. |
JET_errKeyIsMade |
Die für JetMakeKey bereitgestellten Spaltendaten wurden abgelehnt, da die Spaltendaten bereits für alle Schlüsselspalten im aktuellen Index bereitgestellt wurden. Dies kann auf drei Arten geschehen. Die erste Möglichkeit ist, wenn Spaltendaten für jede Schlüsselspalte im aktuellen Index bereitgestellt werden. Die zweite Möglichkeit ist, wenn Spaltendaten für mindestens eine Schlüsselspalte bereitgestellt wurden und eine Platzhalteroption für den letzten Aufruf ausgewählt wurde. Die dritte Möglichkeit besteht darin, dass ein zuvor konstruierter Suchschlüssel mithilfe JET_bitNormalizedKey bereitgestellt wurde, der alle Schlüsselspalten abdeckt. |
JET_errKeyNotMade |
Es gibt keinen aktuellen Suchschlüssel für den Cursor. Dies geschieht für JetMakeKey, wenn JET_bitNewKey nicht angegeben ist und kein Suchschlüssel für diesen Cursor mit einem vorherigen Aufruf von JetMakeKeyerstellt wurde. Der Suchschlüssel wird durch einen vorherigen Aufruf einer beliebigen Navigations-API auf dem Cursor außer JetMovegelöscht. |
JET_errNoCurrentIndex |
Es gibt keinen aktuellen Index für den Cursor. Dies geschieht für JetMakeKey, wenn sich der Cursor im gruppierten Index einer Tabelle befindet, kein primärer Index definiert wurde und JET_bitNormalizedKey nicht angegeben wurde. Es ist nicht möglich, einen Suchschlüssel zu erstellen, wenn sich der Cursor in einem Index befindet, der keine Schlüsselspalten aufweist, es sei denn, es wird ein zuvor konstruierter Suchschlüssel bereitgestellt. |
JET_errNotInitialized |
Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete Instanz noch nicht initialisiert wurde. |
JET_errRestoreInProgress |
Es ist nicht möglich, den Vorgang abzuschließen, da ein Wiederherstellungsvorgang für die Instanz ausgeführt wird, die der Sitzung zugeordnet ist. |
JET_errSessionSharingViolation |
Dieselbe Sitzung kann nicht für mehrere Threads gleichzeitig verwendet werden. Dieser Fehler wird nur von Windows XP und späteren Versionen zurückgegeben. |
JET_errTermInProgress |
Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete Instanz heruntergefahren wird. |
Wenn bei Erfolg JET_bitNormalizedKey und JET_bitNewKey nicht angegeben wurden, wurde der Suchschlüssel anhand der Suchkriterien für eine weitere Schlüsselspalte im aktuellen Index erstellt. Wenn JET_bitNormalizedKey nicht angegeben wurde und JET_bitNewKey angegeben wurde, wurde jeder zuvor vorhandene Suchschlüssel verworfen, und ein neuer Suchschlüssel wurde anhand der Suchkriterien für die erste Schlüsselspalte im aktuellen Index erstellt. Wenn JET_bitNormalizedKey angegeben wurde, wurde jeder zuvor vorhandene Suchschlüssel verworfen und ein neuer aus dem Eingabepuffer geladen. In jedem Fall erfolgt keine Änderung des Datenbankzustands.
Wenn bei einem Fehler JET_bitNormalizedKey oder JET_bitNewKey angegeben wurde, ist der Status des Suchschlüssels nicht definiert. Wenn weder JET_bitNormalizedKey noch JET_bitNewKey angegeben wurden, wird der Zustand des Suchschlüssels nicht geändert. In jedem Fall erfolgt keine Änderung des Datenbankzustands.
Bemerkungen
Schlüssel sollten als nicht transparente Datenblöcke behandelt werden. Es sollte nicht versucht werden, die interne Struktur dieser Daten auszunutzen. Folgendes ist jedoch über alle ESENT-Schlüssel bekannt:
Schlüssel können miteinander verglichen werden, indem sie memcmp verwenden, um ihre relative Reihenfolge im ursprünglichen Index über der Tabelle der Quellindexeinträge herzustellen.
Es ist bedeutungslos, Schlüssel von Indexeinträgen aus verschiedenen Indizes miteinander zu vergleichen.
Ein Schlüssel ist vor Windows Vista immer kleiner oder gleich JET_cbKeyMost (255) Bytes. Bei Windows Vista und höheren Versionen können die Schlüssel größer sein. Die maximale Größe eines Schlüssels entspricht dem aktuellen Wert von JET_paramKeyMost.
Suchschlüssel können ein Byte länger sein, wenn eine Platzhalteroption verwendet wurde. In diesem Fall beträgt der Suchschlüssel bis zu JET_cbLimitKeyMost (256) Bytes für Releases vor Windows Vista und JET_paramKeyMost + 1 Bytes für Windows Vista und höhere Versionen.
Diese maximale Schlüsselgröße hat eine sehr wichtige Bedeutung. Wenn ein Indexeintrag mit Spaltenwerten vorhanden ist, die groß genug sind, um die Generierung eines Schlüssels für diesen Index zu bewirken, der andernfalls größer als diese maximale Größe wäre, wird dieser Schlüssel automatisch bei dieser maximalen Größe abgeschnitten. Dies hat zwei Auswirkungen:
Bei Einträgen in einem eindeutigen Index werden Einträge, die andernfalls eindeutig sind, als Duplikate deklariert.
Bei Einträgen in allen Indizes führt das Abschneiden von Schlüsseln dazu, dass Indexeinträge, die andernfalls nicht den Suchkriterien eines bestimmten Suchschlüssels entsprechen, als Übereinstimmungen deklariert werden.
Anwendungen müssen diese Kürzung antizipieren und sie entweder vermeiden oder ihre Auswirkungen kompensieren. In Windows Vista wurde ein neues Indexflag JET_bitIndexDisallowTruncation hinzugefügt, um Anwendungen das Verhindern von Schlüsselkürzungen zu erleichtern. Weitere Informationen zu dieser Indizierungsoption finden Sie in der JET_INDEXCREATE-Struktur.
Anforderungen
| Anforderung | Wert |
|---|---|
Client |
Erfordert Windows Vista, Windows XP oder Windows 2000 Professional. |
Server |
Erfordert Windows Server 2008, Windows Server 2003 oder Windows 2000 Server. |
Header |
Wird in Esent.h deklariert. |
Bibliothek |
Verwenden Sie ESENT.lib. |
DLL |
Erfordert ESENT.dll. |
Weitere Informationen
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateIndex
JetRetrikey
JetSeek
JetSetIndexRange