Funzione JetRetrieveColumn

Articolo
06/12/2023

Si applica a: Windows | Windows Server

Funzione JetRetrieveColumn

La funzione JetRetrieveColumn recupera un singolo valore di colonna dal record corrente. Il record è quello associato alla voce di indice nella posizione corrente del cursore. In alternativa, questa funzione può recuperare una colonna da un record creato nel buffer di copia del cursore. Questa funzione può anche recuperare i dati della colonna da una voce di indice che fa riferimento al record corrente. Oltre a recuperare il valore effettivo della colonna, JetRetrieveColumn può essere usato anche per recuperare le dimensioni di una colonna, prima di recuperare i dati della colonna stessa in modo che i buffer dell'applicazione possano essere ridimensionati in modo appropriato.

    JET_ERR JET_API JetRetrieveColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __out_opt     void* pvData,
      __in          unsigned long cbData,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit,
      __in_out_opt  JET_RETINFO* pretinfo
    );

Parametri

sesid

Sessione da usare per questa chiamata.

tableid

Cursore da usare per questa chiamata.

columnid

JET_COLUMNID della colonna da recuperare.

È possibile specificare un valore columnid pari a 0 (zero) che non fa riferimento a alcuna singola colonna. Quando viene specificato columnid 0 (zero), tutte le colonne con tag, sparse e multivalore vengono considerate come una singola colonna. Ciò facilita il recupero di tutte le colonne sparse presenti in un record.

pvData

Buffer di output che riceve il valore della colonna.

cbData

Dimensioni massime, in byte, del buffer di output.

pcbActual

Riceve le dimensioni effettive, in byte, del valore della colonna.

Se questo parametro è NULL, le dimensioni effettive del valore della colonna non verranno restituite.

grbit

Un gruppo di bit che contengono le opzioni da usare per questa chiamata, che includono zero o più dei seguenti elementi:

Valore	Significato
JET_bitRetrieveCopy	Questo flag causa il recupero della colonna per recuperare il valore modificato anziché il valore originale. Se il valore non è stato modificato, il valore originale viene recuperato. In questo modo, un valore che non è ancora stato inserito o aggiornato può essere recuperato durante l'operazione di inserimento o aggiornamento di un record.
JET_bitRetrieveFromIndex	Questa opzione viene usata per recuperare i valori di colonna dall'indice, se possibile, senza accedere al record. In questo modo, il caricamento non necessario dei record può essere evitato quando i dati necessari sono disponibili dalle voci di indice stesse. Nei casi in cui il valore di colonna originale non può essere recuperato dall'indice, a causa di trasformazioni irreversibili o troncamento dei dati, il record verrà accessibile e i dati recuperati come normale. Questa è un'opzione di prestazioni e deve essere specificata solo quando è probabile che il valore della colonna possa essere recuperato dall'indice. Questa opzione non deve essere specificata se l'indice corrente è l'indice cluster, poiché le voci di indice per il cluster o l'indice primario sono i record stessi. Questo bit non può essere impostato se è impostato anche JET_bitRetrieveFromPrimaryBookmark.
JET_bitRetrieveFromPrimaryBookmark	Questa opzione viene usata per recuperare i valori di colonna dal segnalibro di indice e può essere diversa dal valore di indice quando una colonna viene visualizzata sia nell'indice primario che nell'indice corrente. Questa opzione non deve essere specificata se l'indice corrente è l'indice cluster o primario. Questo bit non può essere impostato se è impostato anche JET_bitRetrieveFromIndex.
JET_bitRetrieveTag	Questa opzione viene usata per recuperare il numero di sequenza di un valore di colonna multivalore in pretinfo-itagSequence>. Il campo itagSequence è in genere un input per recuperare i valori di colonna multivalore da un record. Tuttavia, quando si recuperano valori da un indice, è anche possibile associare la voce di indice a un determinato numero di sequenza e recuperare anche questo numero di sequenza. Il recupero del numero di sequenza può essere un'operazione costosa e deve essere eseguita solo se necessario.
JET_bitRetrieveNull	Questa opzione viene usata per recuperare valori NULL di colonna multivalore. Se questa opzione non è specificata, i valori NULL di colonna multivalore verranno ignorati automaticamente.
JET_bitRetrieveIgnoreDefault	Questa opzione influisce solo sulle colonne multivalore e determina la restituzione di un valore NULL quando il numero di sequenza richiesto è 1 e non sono presenti valori impostati per la colonna nel record.
JET_bitRetrieveLongId	Questo flag è destinato solo all'uso interno e non deve essere usato nell'applicazione.
JET_bitRetrieveLongValueRefCount	Questo flag è destinato solo all'uso interno e non deve essere usato nell'applicazione.
JET_bitRetrieveTuple	Questo flag consentirà il recupero di un segmento di tupla dell'indice. Questo bit deve essere specificato con JET_bitRetrieveFromIndex.

pretinfo

Se pretinfo viene dato come NULL , la funzione si comporta come se fosse stato assegnato un itagSequence di 1 e un ibLongValue pari a 0 (zero). In questo modo, il recupero della colonna consente di recuperare il primo valore di una colonna multivalore e di recuperare dati lunghi con offset 0 (zero).

Questo parametro viene usato per fornire uno o più dei seguenti elementi:

Valore	Significato
ibLongValue	Fornisce un offset binario in un valore di colonna lungo durante il recupero di una parte di un valore di colonna.
itagSequence	Fornisce il numero di sequenza del valore di colonna multivalore desiderato. Si noti che questo campo è impostato solo se il JET_bitRetrieveTag è specificato. In caso contrario, non viene modificato.
columnidNextTagged	Restituisce l'ID colonna del valore di colonna restituito durante il recupero di tutti i tag, sparse e multivalore, le colonne usando il passaggio di columnid di 0 (zero).

Valore restituito

Questa funzione restituisce il tipo di dati JET_ERR con uno dei codici restituiti seguenti. Per altre informazioni sugli errori ESE possibili, vedere Errori del motore di archiviazione estendibili e parametri di gestione degli errori.

Codice restituito	Descrizione
JET_errSuccess	Operazione riuscita.
JET_errBadColumnId	L'ID colonna specificato è esterno ai limiti legali di un ID colonna.
JET_errBadItagSequence	Il valore del numero di sequenza di colonne multivalore non valido è stato passato in pretinfo-itagSequence>. I valori validi per i numeri di sequenza di valori di colonna multivalore sono 1 o superiori. Un valore pari a 0 (zero) non è valido per questa funzione.
JET_errClientRequestToStopJetService	Non è possibile completare l'operazione perché tutte le attività nell'istanza associata alla sessione non sono state interrotte in seguito a una chiamata a JetStopService.
JET_errColumnNotFound	La colonna descritta dall'oggetto columnid specificato non esiste nella tabella.
JET_errIndexTuplesCannotRetrieveFromIndex	Le colonne indicizzate come sottostringa non possono essere recuperate dall'indice, poiché in genere in ogni voce di indice è presente solo una piccola parte della colonna.
JET_errInstanceUnavailable	Non è possibile completare l'operazione perché l'istanza associata alla sessione ha rilevato un errore irreversibile che richiede che l'accesso a tutti i dati venga revocato per proteggere l'integrità dei dati. Questo errore verrà restituito solo da Windows XP e versioni successive.
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_errInvalidParameter	Uno o più parametri specificati non sono corretti. Ciò può verificarsi se retinfo.cbStruct è minore della dimensione di JET_RETINFO.
JET_errInvalidgrbit	Le opzioni fornite sono sconosciute o una combinazione non valida di impostazioni di bit note.
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.
JET_wrnColumnNull	Il valore della colonna recuperato è NULL.

In caso di esito positivo, il valore della colonna per la colonna specificata viene copiato nel buffer specificato. Viene copiato un valore minore di tutto il valore della colonna con l'avviso JET_wrnBufferTruncated restituito. Se è stato specificato il pcbActual , viene restituita la dimensione effettiva del valore della colonna. Si noti che i valori NULL hanno una lunghezza pari a 0 (zero) e quindi impostano le dimensioni restituite su 0 (zero). Se la colonna recuperata è una colonna multivalore e pretinfo è stata assegnata e JET_bitReturnTag è stata impostata come opzione, il numero di sequenza del valore della colonna viene restituito in pretinfo-itagSequence>.

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

Commenti

Questa chiamata viene usata una sola volta per recuperare i dati di dimensioni fisse o note per colonne non multivalore. Tuttavia, quando i dati della colonna sono di dimensioni sconosciute, questa chiamata viene in genere usata due volte. Viene chiamato prima per determinare le dimensioni dei dati in modo che possa allocare lo spazio di archiviazione necessario. Viene quindi eseguita di nuovo la stessa chiamata per recuperare i dati della colonna. Quando il numero effettivo di valori è sconosciuto, poiché una colonna è multivalore, la chiamata viene in genere usata tre volte. Prima di tutto per ottenere il numero di valori e quindi due volte più per allocare l'archiviazione e recuperare i dati effettivi.

Il recupero di tutti i valori per una colonna multivalore può essere eseguito ripetutamente chiamando questa funzione con un valore pretinfo-itagSequence> a partire da 1 e aumentando in ogni chiamata successiva. L'ultimo valore della colonna viene recuperato quando viene restituito un JET_wrnColumnNull dalla funzione . Si noti che questo metodo non può essere eseguito se la colonna multivalore ha valori NULL espliciti impostati nella sequenza di valori, perché questi valori verrebbero ignorati. Se un'applicazione desidera recuperare tutti i valori di colonna multivalore, inclusi quelli impostati in modo esplicito su NULL, è necessario usare JetRetrieveColumns anziché JetRetrieveColumn. Si noti che questa funzione non restituisce il numero di valori per una funzione multivalore quando viene assegnato un valore itagSequence pari a 0 (zero). Solo JetRetrieveColumns restituirà il numero di valori di un valore di colonna quando viene passato un valore itagSequence pari a 0 (zero).

Se questa funzione viene chiamata al livello di transazione 0 (zero), ad esempio la sessione chiamante non si trova in una transazione, una transazione viene aperta e chiusa all'interno della funzione. Questo scopo è quello di restituire risultati coerenti nel caso in cui un valore lungo si estende su pagine di database. Si noti che la transazione viene rilasciata tra le chiamate di funzione e una serie di chiamate a questa funzione quando la sessione non si trova in una transazione può restituire dati aggiornati dopo la prima chiamata a questa funzione.

Il valore di colonna predefinito verrà recuperato quando la colonna non è stata impostata in modo esplicito su un altro valore, a meno che non sia impostata l'opzione JET_bitRetrieveIgnoreDefault.

Il recupero del valore della colonna di recupero automatico dal buffer di copia prima dell'inserimento è un mezzo comune per identificare un record in modo univoco per il collegamento durante l'inserimento di dati normalizzati in più tabelle. Il valore di recupero automatico viene allocato all'inizio dell'operazione di inserimento e può essere recuperato dal buffer di copia in qualsiasi momento fino al completamento dell'aggiornamento.

Quando si recuperano tutte le colonne con tag, multivalore e sparse, impostando columnid su 0 (zero), le colonne vengono recuperate in ordine columnid dal columnid più basso al columnid più alto. Viene restituito lo stesso ordine dei valori di colonna ogni volta che vengono recuperati i valori delle colonne. L'ordine è deterministico.

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_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_RETINFO
JetSetColumn
JetRetrieveColumns

Condividi tramite

Funzione JetRetrieveColumn