JetRetrieveColumns-Funktion

Artikel
06/12/2023

Gilt für: Windows | Windows Server

JetRetrieveColumns-Funktion

Die JetRetrieveColumns-Funktion ruft mehrere Spaltenwerte aus dem aktuellen Datensatz in einem einzigen Vorgang ab. Ein Array von JET_RETRIEVECOLUMN Strukturen wird verwendet, um den Satz der abzurufenden Spaltenwerte zu beschreiben und Ausgabepuffer für jeden abzurufenden Spaltenwert zu beschreiben.

    JET_ERR JET_API JetRetrieveColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_out_opt  JET_RETRIEVECOLUMN* pretrievecolumn,
      __in          unsigned long cretrievecolumn
    );

Parameter

sesid

Die Sitzung, die für diesen Aufruf verwendet werden soll.

tableid

Der Cursor, der für diesen Aufruf verwendet werden soll.

prätrievecolumn

Ein Zeiger auf ein Array mit mindestens einer JET_RETRIEVECOLUMN Strukturen. Jede Struktur enthält Beschreibungen, welcher Spaltenwert abgerufen werden soll und wo zurückgegebene Daten gespeichert werden sollen.

cretrievecolumn

Die Anzahl der JET_RETRIEVECOLUMN Strukturen im Array, die von pretrievecolumn angegeben wird.

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_errBadItagSequence	In pretinfo-itagSequence> wurde ein ungültiger Wert für mehrwertige Spaltensequenznummern übergeben. Gültige Werte für die mehrwertigen Spaltenwertsequenznummern sind 1 oder höher. Der Wert 0 (null) ist für diese Funktion gültig, für JetRetrieveColumn jedoch ungültig.
JET_errBadColumnId	Die angegebene Spalten-ID liegt außerhalb der gesetzlichen Grenzwerte einer Spalten-ID.
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_errColumnNotFound	Die von der angegebenen Columnid beschriebene Spalte ist in der Tabelle nicht vorhanden.
JET_errIndexTuplesCannotRetrieveFromIndex	Spalten, die als Teilzeichenfolgen indiziert sind, können nicht aus dem Index abgerufen werden, da in der Regel nur ein kleiner Teil der Spalte in jedem Indexeintrag vorhanden ist.
JET_errInvalidBufferSize	In einigen Fällen muss der für die Abrufspalte angegebene Puffer ausreichend groß sein, um eine beliebige Menge des Spaltenwerts zurückzugeben. Beispielsweise werden aktualisierbare Escrow-Spalten so angepasst, dass sie für den Transaktionskontext der aufrufenden Sitzung konsistent sind, und diese Anpassung erfordert den vom Aufrufer bereitgestellten Puffer. Wenn nicht genügend Pufferspeicher bereitgestellt wird, wird JET_errInvalidBufferSize zurückgegeben, und es werden keine Spaltendaten zurückgegeben.
JET_errInvalidgrbit	Die angegebenen Optionen sind unbekannt oder eine unzulässige Kombination bekannter Biteinstellungen.
JET_errInvalidParameter	Mindestens einer der angegebenen Parameter ist falsch. Dies kann passieren, wenn die retinfo.cbStruct kleiner ist als die Größe von JET_RETINFO.
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. Windows XP: Dieser Fehler wird nur von Windows XP und höheren Versionen zurückgegeben.
JET_errNoCurrentRecord	Der Cursor wird nicht auf einem Datensatz positioniert. Dafür sind viele verschiedene Gründe möglich. Dies geschieht beispielsweise, wenn der Cursor derzeit nach dem letzten Datensatz im aktuellen Index positioniert ist.
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. Windows XP: 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.
JET_wrnBufferTruncated	Der gesamte Spaltenwert konnte nicht abgerufen werden, da der angegebene Puffer kleiner als die Größe der Spalte ist.

Bei Erfolg werden Spaltendaten und Spaltengröße in bereitgestellten Puffern zurückgegeben, die im Array von JET_RETRIEVECOLUMN-Strukturen beschrieben sind. Wenn eine itagSequence auf 0 (null) festgelegt wurde, um anzugeben, dass die Anzahl der Instanzen eines mehrwertigen Felds anstelle von Spaltendaten gewünscht wurde, wird die Anzahl der Instanzen einer mehrwertigen Spalte im Feld itagSequence selbst zurückgegeben. Jede JET_RETRIEVECOLUMN Struktur verfügt über ein Fehlerfeld, das Warnungen für die abgerufene Spalte enthält. Wenn die Spalte NULL wert ist, wird der Fehlercode auf JET_wrnColumnNull festgelegt.

Bei einem Fehler bleibt die Cursorposition unverändert, und es werden keine Daten in den bereitgestellten Puffer kopiert.

Bemerkungen

JetRetrieveColumns unterstützt ein Feature, das JetRetrieveColumn nicht unterstützt. Dies ist die Möglichkeit, die Anzahl der Instanzen einer mehrwertigen Spalte abzurufen. Der Zweck dieses Features besteht darin, einer Anwendung das Abrufen aller Werte einer Spalte zu ermöglichen. Dazu kann zuerst die Anzahl der Werte einer Spalte bestimmt werden. Als Nächstes können ihre Längen bestimmt werden, indem JetRetrieveColumns erneut aufgerufen wird, wobei jedem Wert eine JET_RETRIEVECOLUMN Struktur zugewiesen ist, um die Länge der Spaltendaten zu bestimmen. Dies kann durch Übergeben von NULLpvData-Zeigern mit cbMax von 0 (Null) und Abrufen der Spaltenlänge in cbActual erfolgen. Der dritte und letzte Aufruf kann mit zugewiesenem Arbeitsspeicher für die Spaltenwertdaten erfolgen.

Wenn eine abgerufene Spalte aufgrund eines unzureichenden Längenpuffers abgeschnitten wird, gibt die API JET_wrnBufferTruncated zurück. Andere Fehler, JET_wrnColumnNull werden jedoch nur im Fehlerfeld in JET_RETRIEVECOLUMN zurückgegeben. Der Grund dafür ist, dass Anwendungen häufig sicherstellen möchten, dass alle Daten abgerufen wurden, und die Rückgabe dieses Fehlers von JetRetrieveColumns erleichtert dieses Verständnis.

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_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns

Freigeben über

JetRetrieveColumns-Funktion