Funzione JetRetrieveColumns

Si applica a: Windows | server Windows

Funzione JetRetrieveColumns

La funzione JetRetrieveColumns recupera più valori di colonna dal record corrente in una singola operazione. Una matrice di strutture JET_RETRIEVECOLUMN viene usata per descrivere il set di valori di colonna da recuperare e per descrivere i buffer di output per ogni valore di colonna da recuperare.

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

Parametri

sesid

Sessione da utilizzare per questa chiamata.

tableid

Cursore da utilizzare per questa chiamata.

pretrievecolumn

Puntatore a una matrice di una o più strutture JET_RETRIEVECOLUMN . Ogni struttura include descrizioni del valore della colonna da recuperare e della posizione in cui archiviare i dati restituiti.

cretrievecolumn

Numero di strutture JET_RETRIEVECOLUMN nella matrice specificata da pretrievecolumn.

Valore restituito

Questa funzione restituisce il tipo di dati JET_ERR con uno dei codici restituiti seguenti. Per altre informazioni sui possibili errori ESE, vedere Extensible Archiviazione Engine Errors and Error Handling Parameters.For more information about the possible ESE errors errors, see Extensible Archiviazione Engine Errors and Error Handling Parameters.

Codice restituito	Descrizione
JET_errSuccess	Operazione riuscita.
JET_errBadItagSequence	Un valore di numero di sequenza di colonna multivalore non valido è stato passato in pretinfo-itagSequence>. I valori validi per i numeri di sequenza dei valori di colonna multivalore sono 1 o superiori. Il valore 0 (zero) è valido per questa funzione, ma non è valido per JetRetrieveColumn.
JET_errBadColumnId	L'ID di colonna specificato non rientra nei limiti legali di un ID di colonna.
JET_errClientRequestToStopJetService	Non è possibile completare l'operazione perché tutte le attività nell'istanza associata alla sessione sono cessate a seguito di una chiamata a JetStopService.
JET_errColumnNotFound	La colonna descritta dall'id colonna specificato non esiste nella tabella.
JET_errIndexTuplesCannotRetrieveFromIndex	Le colonne indicizzate come sottostringhe non possono essere recuperate dall'indice, perché solo una piccola parte della colonna è in genere presente in ogni voce di indice.
JET_errInvalidBufferSize	In alcuni casi, il buffer specificato per la colonna di recupero deve essere sufficientemente ridimensionato per restituire qualsiasi quantità del valore della colonna. Ad esempio, le colonne aggiornabili di deposito vengono modificate in modo da essere coerenti per il contesto transazionale della sessione chiamante e questa regolazione richiede il buffer fornito dal chiamante. Se viene fornito spazio buffer insufficiente, viene restituito JET_errInvalidBufferSize e non vengono restituiti dati di colonna.
JET_errInvalidgrbit	Le opzioni fornite sono sconosciute o una combinazione non valida di impostazioni di bit note.
JET_errInvalidParameter	Uno o più parametri specificati non sono corretti. Ciò può verificarsi se retinfo.cbStruct è minore della dimensione di JET_RETINFO.
JET_errInstanceUnavailable	Non è possibile completare l'operazione perché l'istanza associata alla sessione ha rilevato un errore irreversibile che richiede la revoca dell'accesso a tutti i dati per proteggere l'integrità dei dati. Windows XP: questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errNoCurrentRecord	Il cursore non è posizionato su un record. I motivi possono essere diversi. Ad esempio, ciò si verifica se il cursore è attualmente posizionato dopo l'ultimo record nell'indice corrente.
JET_errNotInitialized	Non è possibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.
JET_errRestoreInProgress	Non è possibile completare l'operazione perché è in corso un'operazione di ripristino nell'istanza associata alla sessione.
JET_errSessionSharingViolation	La stessa sessione non può essere usata contemporaneamente per più thread. Windows XP: questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errTermInProgress	Non è possibile completare l'operazione perché l'istanza associata alla sessione viene arrestata.
JET_wrnBufferTruncated	Impossibile recuperare l'intero valore della colonna perché il buffer specificato è inferiore alle dimensioni della colonna.

In caso di esito positivo, le dimensioni dei dati e delle colonne vengono restituite nei buffer forniti descritti nella matrice di strutture JET_RETRIEVECOLUMN . Se un itagSequence è stato impostato su 0 (zero) per indicare che il numero di istanze di un campo multivalore è stato desiderato anziché dati di colonna, il numero di istanze di una colonna multivalore viene restituito nel campo itagSequence stesso. Ogni struttura JET_RETRIEVECOLUMN contiene un campo di errore che contiene avvisi per la colonna recuperata. Se la colonna è stata impostata su NULL, il codice di errore verrà impostato su JET_wrnColumnNull.

In caso di errore, la posizione del cursore rimane invariata e non vengono copiati dati nel buffer specificato.

Commenti

JetRetrieveColumns supporta una funzionalità non supportata da JetRetrieveColumn . Si tratta della possibilità di recuperare il numero di istanze di una colonna multivalore. Lo scopo di questa funzionalità è consentire a un'applicazione di recuperare tutti i valori di una colonna. Questa operazione può essere eseguita determinando innanzitutto il numero di valori di una colonna. Successivamente, è possibile determinare le lunghezze chiamando JetRetrieveColumns con una struttura JET_RETRIEVECOLUMN allocata per ogni valore per determinare la lunghezza dei dati della colonna. A tale scopo, è possibile passare puntatori NULLpvData con cbMax pari a 0 (zero) e recuperare la lunghezza della colonna in cbActual. La terza e l'ultima chiamata possono essere effettuate con la memoria allocata per i dati del valore della colonna.

Se una colonna recuperata viene troncata a causa di un buffer di lunghezza insufficiente, l'API restituirà JET_wrnBufferTruncated. Tuttavia, altri errori, JET_wrnColumnNull vengono restituiti solo nel campo di errore in JET_RETRIEVECOLUMN. Il motivo è che le applicazioni spesso vogliono assicurarsi che tutti i dati siano stati recuperati e che venga restituito questo errore da JetRetrieveColumns facilita questa comprensione.

Requisiti

Requisito	Valore
Client	Richiede Windows Vista, Windows XP o Windows 2000 Professional.
Server	Richiede Windows Server 2008, Windows Server 2003 o Windows 2000 Server.
Intestazione	Dichiarato in Esent.h.
Libreria	Usare ESENT.lib.
DLL	Richiede ESENT.dll.

Vedere anche

JET_ERR
JET_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns