JetSetCurrentIndex4-Funktion
Gilt für: Windows | Windows Server
JetSetCurrentIndex4-Funktion
Mit der JetSetCurrentIndex4-Funktion wird der aktuelle Index eines Cursors festgelegt. Der aktuelle Index eines Cursors definiert, welche Datensätze in einer Tabelle für diesen Cursor sichtbar sind und in welcher Reihenfolge sie angezeigt werden, indem der Satz von Indexeinträgen ausgewählt wird, die zum Verfügbar machen dieser Datensätze verwendet werden sollen.
JET_ERR JET_API JetSetCurrentIndex4(
__in JET_SESID sesid,
__in JET_TABLEID tableid,
__in_opt JET_PCSTR szIndexName,
__in_opt JET_INDEXID* pindexid,
__in JET_GRBIT grbit,
__in unsigned long itagSequence
);
Parameter
sesid
Die Sitzung, die für diesen Aufruf verwendet werden soll.
tableid
Der Cursor, der für diesen Aufruf verwendet werden soll.
szIndexName
Der Name des Indexes, der für den Cursor ausgewählt werden soll. Wenn dieser Parameter NULL oder eine leere Zeichenfolge ist, wird der gruppierte Index ausgewählt. Wenn ein primärer Index für die Tabelle definiert ist, wird dieser Index ausgewählt, da er mit dem gruppierten Index identisch ist. Wenn kein primärer Index für die Tabelle definiert ist, wird der sequenzielle Index ausgewählt. Der sequenzielle Index verfügt über keine Indexdefinition. Weitere Informationen finden Sie unter JetCreateIndex.
Wenn pindexid nicht NULL ist, wird der Indexname ignoriert, und der Index wird durch seine Index-ID ausgewählt.
pindexid
Die ID des Indexes, der für den Cursor ausgewählt werden soll.
Die Index-ID ist ein flüchtiges, nicht transparentes Handle, das verwendet werden kann, um schnell einen Index auszuwählen. Diese ID kann mit JetGetIndexInfo oder JetGetTableIndexInfo mithilfe der option JET_IdxInfoIndexId abgerufen werden.
Wenn pindexid NULL ist, wird der Index durch seinen Indexnamen ausgewählt, und die Index-ID wird ignoriert.
Wenn dieser Parameter nicht vorhanden ist, wird davon ausgegangen, dass sein Wert NULL ist.
grbit
Eine Gruppe von Bits, die die für diesen Aufruf zu verwendenden Optionen enthalten, die null oder mehr der folgenden Elemente enthalten.
Wert |
Bedeutung |
|---|---|
JET_bitMoveFirst |
Diese Option gibt an, dass der Cursor am ersten Eintrag des angegebenen Indexes positioniert werden soll. Wenn der gruppierte Index ausgewählt wird (primärer Index oder sequenzieller Index), und der aktuelle Index ein sekundärer Index ist, JET_bitMoveFirst angenommen. Wenn der aktuelle Index ausgewählt wird, wird diese Option ignoriert, und es wird keine Änderung an der Cursorposition vorgenommen. |
JET_bitNoMove |
Diese Option gibt an, dass der Cursor auf dem Indexeintrag des neuen Indexes positioniert werden soll, der dem Datensatz entspricht, der dem Indexeintrag an der aktuellen Position des Cursors im alten Index zugeordnet ist. Wenn die Definition für den neuen Index mindestens eine mehrwertige Schlüsselspalte enthält, ist der Zielindexeintrag mehrdeutig. In diesem Fall wird die angegebene itagSequence verwendet, um auszuwählen, welcher Mehrwert der wichtigsten mehrwertigen Schlüsselspalte verwendet wird, um den Cursor zu positionieren. Es ist nur erforderlich, eine einzelne itagSequence auch bei mehreren spalten mit mehreren Schlüsseln zu übergeben, da die Engine nur alle Werte für die wichtigste Spalte mit mehreren Schlüsseln erweitert. Weitere Informationen finden Sie unter JetCreateIndex. Wenn JET_bitMoveFirst angegeben wird, wird diese Option ignoriert. Wenn der aktuelle Index ausgewählt wird, wird diese Option ignoriert, und es wird keine Änderung an der Cursorposition vorgenommen. Wenn dieser Parameter nicht vorhanden ist, wird davon ausgegangen, dass sein Wert JET_bitMoveFirst. |
itagSequence
Sequenznummer des mehrwertigen Spaltenwerts, der verwendet wird, um den Cursor auf dem neuen Index zu positionieren.
Dieser Parameter wird nur in Verbindung mit JET_bitNoMove. Weitere Informationen finden Sie in der Beschreibung dieser Option.
Wenn dieser Parameter nicht vorhanden ist oder auf 0 (null) festgelegt ist, wird davon ausgegangen, dass sein Wert 1 ist.
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_errBadItagSequence |
Ein sekundärer Index wird mit der Option JET_bitNoMove ausgewählt, und es gibt keinen Wert für die erste mehrwertige Schlüsselspalte in der Definition für den neuen Index, der der angegebenen Sequenznummer entspricht. |
JET_errClientRequestToStopJetService |
Es ist nicht möglich, den Vorgang abschließen, da alle Aktivitäten auf der -Instanz, die der Sitzung zugeordnet ist, aufgrund eines Aufrufs von JetStopService beendet wurden. |
JET_errInstanceUnavailable |
Der Vorgang kann nicht abgeschlossen werden, da für die der Sitzung zugeordnete Instanz 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 xp Windows und späteren Versionen zurückgegeben. |
JET_errInvalidIndexId |
Der Inhalt der Index-ID war ungültig oder abgelaufen und muss aktualisiert werden. Dies kann für JetSetCurrentIndex4 auftreten, wenn:
|
JET_errInvalidName |
Einer der angegebenen Objektnamen war ungültig. Alle Objektnamen müssen demselben Satz von Regeln entsprechen. Nachfolgend sind diese Regeln aufgeführt:
|
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 für JetSetCurrentIndex4 passieren, wenn pindexid nicht NULL ist und pindexid- cbStruct nicht die erwartete Größe hat (Windows XP und frühere > Releases). |
JET_errNoCurrentRecord |
Ein sekundärer Index wird mit der Option JET_bitNoMove ausgewählt, und es gibt keinen Indexeintrag im neuen Index, der dem Datensatz entspricht, der dem Indexeintrag an der aktuellen Position des Cursors im alten Index zugeordnet ist. |
JET_errNotInitialized |
Der Vorgang kann nicht abgeschlossen werden, da die der Sitzung zugeordnete Instanz noch nicht initialisiert wurde. |
JET_errOutOfCursors |
Die Engine hat ihren Ressourcenpool zum Öffnen von Cursorn ausgeschöpft. Die maximale Anzahl von Cursorn, die zu einem beliebigen Zeitpunkt geöffnet werden können, wird mithilfe von JET_paramMaxCursors. Weitere Informationen finden Sie unter JetSetSystemParameter. Dies kann für JetSetCurrentIndex4 passieren, wenn ein sekundärer Index ausgewählt wurde und die Engine keinen internen Cursor öffnen kann, um diesen Index zu verwenden. |
JET_errRestoreInProgress |
Der Vorgang kann nicht abgeschlossen werden, da ein Wiederherstellungsvorgang für die -Instanz durchgeführt wird, die der Sitzung zugeordnet ist. |
JET_errSessionSharingViolation |
Dieselbe Sitzung kann nicht gleichzeitig für mehrere Threads verwendet werden. Dieser Fehler wird nur von xp Windows 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. |
Bei Erfolg wird der aktuelle Index des Cursors auf den angeforderten Index festgelegt. Indexeinträge können jetzt mit JetSeek gemäß der Indexdefinition des angeforderten Index gesucht werden. Indexeinträge können auch mitHilfe von JetMove in der von dieser Indexdefinition angegebenen Reihenfolge aufzählt werden. Die aktuelle Position des Cursors wird entweder auf den ersten Indexeintrag im Index (JET_bitMoveFirst) oder auf einen bestimmten Indexeintrag festgelegt, der mit der aktuellen Position des Cursors auf dem alten Index verknüpft ist (JET_bitNoMove). Es wird keine Änderung am Datenbankzustand vorgenommen.
Bei einem Fehler befinden sich der aktuelle Index und die aktuelle Position des Cursors in einem nicht definierten Zustand. Es wird keine Änderung am Datenbankzustand vorgenommen.
Bemerkungen
Wenn der Index-ID-Hinweis veraltet ist, schlägt die API einfach fehl. Es gibt in diesem Fall keinen Fallback auf den Textnamen des Indexes, wie man erwarten könnte. Dieser Fallback muss manuell vom Aufrufer der API durchgeführt werden.
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 |
Deklariert in Esent.h. |
Bibliothek |
Verwenden Sie ESENT.lib. |
DLL |
Erfordert ESENT.dll. |
Unicode |
Wird als JetSetCurrentIndex4W (Unicode) und JetSetCurrentIndex4A (ANSI) implementiert. |
Weitere Informationen
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_INDEXID
JetCreateIndex
JetGetCurrentIndex
JetGetIndexInfo
JetGetTableIndexInfo
JetMove
JetSeek
JetSetSystemParameter