JetMakeKey-Funktion

  • Artikel

Gilt für: Windows | Windows Server

JetMakeKey-Funktion

Die JetMakeKey-Funktion erstellt Suchschlüssel, die dann verwendet werden können, um eine Reihe von Einträgen in einem Index anhand einiger einfacher Suchkriterien für ihre Schlüsselspaltenwerte zu finden. Ein Suchschlüssel ist auch eine der intrinsischen 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, bei denen jeder Aufruf verwendet wird, um den Spaltenwert für die nächste Schlüsselspalte des aktuellen Index eines Cursors zu laden. Es ist auch möglich, einen zuvor erstellten Suchschlüssel zu laden, der mithilfe von JetRetrieveKey vom 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. Für die Spaltendaten wird keinerlei Typkoerz 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 JetRetrieveKey abgerufen.

cbData

Die Größe der spaltenbasierten Daten in Bytes, die im Eingabepuffer bereitgestellt werden.

Wenn JET_bitNormalizedKey im grbit-Parameter angegeben ist, ist dies die Größe des Suchschlüssels, der im Eingabepuffer bereitgestellt wird.

Wenn die Größe der Spaltendaten 0 ist, werden die Inhalte des Eingabepuffers ignoriert. Wenn JET_bitKeyDataZeroLength im grbit-Parameter angegeben ist und die aktuelle Schlüsselspalte des aktuellen Indexes des Cursors eine Spalte mit variabler Länge ist, wird angenommen, dass die Daten der Eingabespalte ein Wert der Länge null sind. Andernfalls wird angenommen, dass die Eingabespaltendaten ein NULL-Wert sind.

grbit

Eine Gruppe von Bits, die null oder mehr der folgenden Optionen angibt.

Wert

Bedeutung

JET_bitFullColumnEndLimit

Der Suchschlüssel sollte so aufgebaut sein, dass alle Schlüsselspalten, die nach der aktuellen Schlüsselspalte kommen, als Wildcards gelten. Dies bedeutet, dass der erstellte Suchschlüssel verwendet werden kann, um Indexeinträge abzugleichen, die Folgendes aufweisen:

  • Die genauen Spaltenwerte, die für diese Schlüsselspalte und alle vorherigen Schlüsselspalten bereitgestellt wurden.

  • Alle Spaltenwerte, die für nachfolgende Schlüsselspalten erforderlich sind.

Diese Option sollte beim Erstellen von Suchschlüsseln für Die Suche nach 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 mit dem hohen Ende des Indexes identisch, was sich je nach Sortierreihenfolge der Schlüsselspalten im Index ändern kann.

Diese Option ist nur unter Windows XP und höheren Versionen verfügbar.

JETbitFullColumnStartLimit

Der Suchschlüssel sollte so erstellt werden, dass alle Schlüsselspalten, die nach der aktuellen Schlüsselspalte kommen, als Feldhalter betrachtet werden. Dies bedeutet, dass der erstellte Suchschlüssel verwendet werden kann, um Indexeinträge abzugleichen, die Folgendes aufweisen:

  • Die genauen Spaltenwerte, die für diese Schlüsselspalte und alle vorherigen Schlüsselspalten bereitgestellt wurden.

  • Alle Spaltenwerte, die für nachfolgende Schlüsselspalten erforderlich sind.

Diese Option sollte verwendet werden, wenn Sie Suchschlüssel erstellen, die zum Suchen nach Indexeinträgen verwendet werden, die dem Anfang eines Index am nächsten sind. Der Anfang des Indexes ist der Indexeintrag, der beim Wechsel zum ersten Datensatz in diesem Index gefunden wird. Der Anfang des Indexes ist nicht mit dem unteren Ende des Indexes identisch, was sich je nach Sortierreihenfolge der Schlüsselspalten im Index ändern kann.

Diese Option ist nur unter Windows XP und höheren Versionen verfügbar.

JET_bitKeyDataZeroLength

Wenn die Größe des Eingabepuffers 0 und die aktuelle Schlüsselspalte eine Spalte mit variabler Länge ist, gibt diese Option an, dass der Eingabepuffer einen Wert der Länge 0 enthält. Andernfalls würde eine Eingabepuffergröße von 0 auf einen NULL-Wert hinweisen.

JET_bitNewKey

Ein neuer Suchschlüssel sollte 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 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äfixplatzhalter betrachtet wird und alle Schlüsselspalten, die nach der aktuellen Schlüsselspalte kommen, als Feldhalter betrachtet werden sollten. Dies bedeutet, dass der erstellte Suchschlüssel verwendet werden kann, um Indexeinträge abzugleichen, die Folgendes aufweisen:

  • Die genauen Spaltenwerte, die für diese Schlüsselspalte und alle vorherigen Schlüsselspalten bereitgestellt wurden.

  • Alle Spaltenwerte, die für nachfolgende Schlüsselspalten erforderlich sind.

Diese Option sollte beim Erstellen von Suchschlüsseln für Die Suche nach 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 mit dem hohen Ende des Indexes identisch, was sich je nach Sortierreihenfolge der Schlüsselspalten im Index ändern kann.

Diese Option kann nicht verwendet werden, wenn es sich bei der aktuellen Schlüsselspalte nicht um eine Textspalte oder eine variable binärspalte handelt. Der Vorgang schlägt mit JET_errInvalidgrbit fehl, wenn dies versucht wird.

Diese Option ist nur unter Windows XP und höheren Versionen verfügbar.

JET_bitPartialColumnStartLimit

Diese Option gibt an, dass der Suchschlüssel so erstellt werden soll, dass die aktuelle Schlüsselspalte als Präfixplatzhalter betrachtet wird und dass alle Schlüsselspalten, die nach der aktuellen Schlüsselspalte kommen, als Feldhalter betrachtet werden sollten. Dies bedeutet, dass der erstellte Suchschlüssel verwendet werden kann, um Indexeinträge abzugleichen, die Folgendes aufweisen:

  • Die genauen Spaltenwerte, die für diese Schlüsselspalte und alle vorherigen Schlüsselspalten bereitgestellt wurden.

  • Alle Spaltenwerte, die für nachfolgende Schlüsselspalten erforderlich sind.

Diese Option sollte verwendet werden, wenn Sie Suchschlüssel erstellen, die zum Suchen nach Indexeinträgen verwendet werden, die dem Anfang eines Index am nächsten sind. Der Anfang des Indexes ist der Indexeintrag, der beim Wechsel zum ersten Datensatz in diesem Index gefunden wird. Der Anfang des Indexes ist nicht mit dem unteren Ende des Indexes identisch, was sich je nach Sortierreihenfolge der Schlüsselspalten im Index ändern kann.

Diese Option kann nicht verwendet werden, wenn es sich bei der aktuellen Schlüsselspalte nicht um eine Textspalte oder eine variable binärspalte handelt. Der Vorgang schlägt mit JET_errInvalidgrbit fehl, wenn dies versucht wird.

Diese Option ist nur unter Windows XP und höheren 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 Feldhalter betrachtet werden sollen. Dies bedeutet, dass der erstellte Suchschlüssel verwendet werden kann, um Indexeinträge abzugleichen, die Folgendes aufweisen:

  • Die genauen Spaltenwerte, die für diese Schlüsselspalte und alle vorherigen Schlüsselspalten bereitgestellt wurden.

  • Alle Spaltenwerte, die für nachfolgende Schlüsselspalten erforderlich sind.

Diese Option sollte beim Erstellen von Suchschlüsseln für Die Suche nach 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 mit dem hohen Ende des Indexes identisch, was sich je nach Sortierreihenfolge der Schlüsselspalten im Index ändern kann.

Wenn diese Option in Kombination mit JET_bitSubStrLimit angegeben wird und die aktuelle Schlüsselspalte eine Textspalte ist, wird diese Option ignoriert. Dieses Verhalten soll es ermöglichen, dass der Typ der aktuellen Schlüsselspalte beim Erstellen des Suchschlüssels abgeleitet werden kann.

Wenn Sie einen ähnlichen Suchschlüssel für den Beginn eines Indexes erstellen möchten, sollte ein ähnlicher Aufruf von JetMakeKey für die letzte Schlüsselspalte erfolgen, die kein Feldhalter ist, aber keine Feldhalteroptionen angegeben sind. Der Suchschlüssel befindet sich dann in einem geeigneten Zustand, der für eine solche Suche verwendet werden kann. Dies ist analog zur Verwendung JET_bitFullColumnStartLimit, mit dem Unterschied, dass der Suchschlüssel nicht sauber abgeschlossen ist, wie er nach der Verwendung einer Platzhalteroption ist.

Diese Option wurde für Windows XP und höhere Versionen veraltet, um diese unbeholfene Semantik zu beheben. stattdessen sollten nach Möglichkeit JET_bitFullColumnStartLimit und JET_bitFullColumnEndLimit verwendet werden.

JET_bitSubStrLimit

Diese Option gibt an, dass der Suchschlüssel so erstellt werden soll, dass die aktuelle Schlüsselspalte als Präfixplatzhalter betrachtet wird und dass alle Schlüsselspalten, die nach der aktuellen Schlüsselspalte kommen, als Feldhalter betrachtet werden sollten. Dies bedeutet, dass der erstellte Suchschlüssel verwendet werden kann, um Indexeinträge abzugleichen, die Folgendes aufweisen:

  • Die genauen Spaltenwerte, die für alle vorherigen Schlüsselspalten bereitgestellt wurden.

  • Die angegebenen Spaltendaten als Präfix ihres Spaltenwerts für die aktuelle Schlüsselspalte.

  • Alle Spaltenwerte für nachfolgende Schlüsselspalten.

Diese Option sollte beim Erstellen von Suchschlüsseln für Die Suche nach 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 mit dem hohen Ende des Indexes identisch, was 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 werden kann.

Wenn Sie einen ähnlichen Suchschlüssel für den Beginn eines Indexes erstellen möchten, sollte ein ähnlicher Aufruf von JetMakeKey für die Schlüsselspalte erfolgen, bei der es sich um das Präfixplatzhalter handelt, aber keine Feldhalteroptionen angegeben sind. 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_bitPartialColumnStartLimit, mit dem Unterschied, dass der Suchschlüssel nach der Verwendung einer Platzhalteroption nicht sauber abgeschlossen ist.

Diese Option wurde für Windows XP und höhere Versionen veraltet, um diese unbeholfene 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 möglichen ESE-Fehlern finden Sie unter Erweiterbare Speichermodulfehler und Fehlerbehandlungsparameter.

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 dem instance, die der Sitzung zugeordnet sind, aufgrund eines Aufrufs von JetStopService beendet wurden.

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 höheren Versionen zurückgegeben.

JET_errInstanceUnavailable

Es ist nicht möglich, den Vorgang abzuschließen, da beim instance, der 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 höheren Versionen zurückgegeben.

JET_errInvalidBufferSize

Die bereitgestellten Spaltendaten entsprachen nicht der größe, die für die Spaltendefinition erforderlich ist. Dies kann passieren, wenn der Datentyp der Spalte intrinsisch eine bestimmte Größe aufweist. Dies kann auch der Fall sein, wenn der Datentyp der Spalte nicht systemintern eine bestimmte Größe aufweist, sondern die Definition der Spalte eine feste Länge deklariert. Eine Ausnahme ist, dass dieser Fehler nicht auftritt, wenn zu wenig Daten für eine Textspalte mit fester Länge bereitgestellt werden, da fehlende Daten automatisch mit Leerzeichen versehen werden. Eine zweite Ausnahme ist, dass dieser Fehler nicht auftritt, wenn für eine Binärspalte 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, illegal verwendet oder nicht implementiert. Dies kann für JetMakeKey in folgenden Fällen auftreten:

  • JET_bitPartialColumnStartLimit oder JET_bitPartialColumnEndLimit angegeben werden, und die entsprechende Schlüsselspalte ist keine Textspalte und keine binäre Spalte mit variabler Länge. Dieser Fall tritt nur unter Windows XP und höheren Versionen auf.

  • Es wird versucht, mehrere der folgenden Optionen zusammen zu verwenden: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit und JET_bitFullColumnEndLimit. Dieser Fall tritt nur unter Windows XP und höheren Versionen auf.

  • Es wird versucht, JET_bitStrLimit oder JET_bitSubStrLimit zu verwenden, wenn eine der folgenden Optionen verwendet wird: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit und JET_bitFullColumnEndLimit. Dieser Fall tritt nur unter Windows XP und höheren Versionen auf.

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 Spaltendaten bereits für alle Schlüsselspalten im aktuellen Index bereitgestellt wurden. Dies kann auf drei Arten geschehen. Der erste Weg ist, wenn Spaltendaten für jede Schlüsselspalte im aktuellen Index bereitgestellt werden. Die zweite Möglichkeit besteht darin, wenn Spaltendaten für mindestens eine Schlüsselspalte bereitgestellt wurden und eine Platzhalteroption für den letzten Aufruf ausgewählt wurde. Der dritte Weg ist, wenn ein zuvor erstellter Suchschlüssel mithilfe von JET_bitNormalizedKey bereitgestellt wurde, der alle Schlüsselspalten abdeckt.

JET_errKeyNotMade

Es gibt keine aktuelle Suchtaste für den Cursor. Dies geschieht für JetMakeKey , wenn JET_bitNewKey nicht angegeben ist und kein Suchschlüssel für diesen Cursor mithilfe eines vorherigen Aufrufs von JetMakeKey erstellt wurde. Der Suchschlüssel wird durch einen vorherigen Aufruf einer anderen Navigations-API auf dem Cursor als JetMove gelöscht.

JET_errNoCurrentIndex

Es gibt keinen aktuellen Index für den Cursor. Dies geschieht für JetMakeKey , wenn sich der Cursor auf dem 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 auf einem Index befindet, der keine Schlüsselspalten enthält, es sei denn, ein zuvor erstellter Suchschlüssel wird angegeben.

JET_errNotInitialized

Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete instance noch nicht initialisiert wurde.

JET_errRestoreInProgress

Es ist nicht möglich, den Vorgang abzuschließen, da auf dem der Sitzung zugeordneten instance ein Wiederherstellungsvorgang ausgeführt wird.

JET_errSessionSharingViolation

Dieselbe Sitzung kann nicht für mehrere Threads gleichzeitig verwendet werden. Dieser Fehler wird nur von Windows XP und höheren Versionen zurückgegeben.

JET_errTermInProgress

Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete instance heruntergefahren wird.

Wenn bei Erfolg JET_bitNormalizedKey und JET_bitNewKey nicht angegeben wurden, wurde der Suchschlüssel durch die Suchkriterien für eine weitere Schlüsselspalte im aktuellen Index erstellt. Wenn JET_bitNormalizedKey nicht angegeben und JET_bitNewKey angegeben wurde, wurde jeder zuvor vorhandene Suchschlüssel verworfen, und ein neuer Suchschlüssel wurde durch die 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 Suchschlüssel wurde aus dem Eingabepuffer geladen. In jedem Fall wird keine Änderung des Datenbankzustands vorgenommen.

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 sich der Status des Suchschlüssels nicht ändern. In jedem Fall wird keine Änderung des Datenbankzustands vorgenommen.

Bemerkungen

Schlüssel sollten als undurchsichtige Datenblöcke behandelt werden. Es sollte nicht versucht werden, die interne Struktur dieser Daten zu nutzen. Über alle ESENT-Schlüssel ist jedoch Folgendes bekannt:

  • Schlüssel können unter Verwendung von memcmp miteinander verglichen werden, um ihre relative Reihenfolge im Ursprungsindex gegenüber der Tabelle der Quellindexeinträge festzulegen.

  • Es ist sinnlos, Schlüssel von Indexeinträgen aus verschiedenen Indizes miteinander zu vergleichen.

  • Ein Schlüssel ist immer kleiner oder gleich JET_cbKeyMost (255) Bytes länge vor Windows Vista. Unter 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 Feldhalteroption verwendet wurde. In diesem Fall beträgt der Suchschlüssel bis zu JET_cbLimitKeyMost (256) Bytes für Versionen vor Windows Vista und JET_paramKeyMost + 1 Bytes für Windows Vista und höhere Versionen.

Es gibt einen sehr wichtigen Einfluss auf diese maximale Schlüsselgröße. Wenn ein Indexeintrag über Spaltenwerte verfügt, die groß genug sind, um einen Schlüssel für diesen Index zu generieren, der andernfalls größer als diese maximale Größe wäre, wird dieser Schlüssel bei dieser maximalen Größe unbeaufsichtigt abgeschnitten. Dies hat zwei Auswirkungen:

  • Bei Einträgen in einem eindeutigen Index werden Einträge, die andernfalls eindeutig wären, als Duplikate deklariert.

  • Bei Einträgen in allen Indizes bewirkt das Abschneiden von Schlüsseln, dass Indexeinträge, die andernfalls nicht den Suchkriterien eines bestimmten Suchschlüssels entsprechen, als Übereinstimmung deklariert werden.

Anwendungen müssen diese Kürzung vorhersehen und sie entweder vermeiden oder ihre Auswirkungen kompensieren. In Windows Vista wurde ein neues Indexflag hinzugefügt, JET_bitIndexDisallowTruncation, 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.

Kopfzeile

Deklariert in Esent.h.

Bibliothek

Verwenden Sie ESENT.lib.

DLL

Erfordert ESENT.dll.

Weitere Informationen

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateIndex
JetRetrieveKey
JetSeek
JetSetIndexRange