Funzione JetEnumerateColumns

Si applica a: Windows | Windows Server

Funzione JetEnumerateColumns

La funzione JetEnumerateColumns recupera in modo efficiente un set di colonne e i relativi valori dal record corrente di un cursore o dal buffer di copia di tale cursore. Le colonne e i valori recuperati possono essere limitati da un elenco di ID colonna, numeri itagSequence e altre caratteristiche. Questa API di recupero della colonna è univoca in quanto restituisce informazioni nella memoria allocata dinamicamente ottenuta usando un callback compatibile con realloc fornito dall'utente. Questa nuova flessibilità consente il recupero efficiente dei dati di colonna con caratteristiche specifiche (ad esempio dimensioni e molteplicità) sconosciute al chiamante. Ciò elimina la necessità di usare le modalità di individuazione di JetRetrieveColumn per determinare queste caratteristiche per configurare una chiamata finale a JetRetrieveColumn che recupera correttamente i dati desiderati.

Windows XP: JetEnumerateColumns viene introdotto in Windows XP.

    JET_ERR JET_API JetEnumerateColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long cEnumColumnId,
      __in_opt      JET_ENUMCOLUMNID* rgEnumColumnId,
      __out         unsigned long* pcEnumColumn,
      __out         JET_ENUMCOLUMN** prgEnumColumn,
      __in          JET_PFNREALLOC pfnRealloc,
      __in          void* pvReallocContext,
      __in          unsigned long cbDataMost,
      __in          JET_GRBIT grbit
    );

Parametri

sesid

Sessione da usare per questa chiamata.

tableid

Cursore da usare per questa chiamata.

cEnumColumnId

Matrice di ID di colonna, ognuno con una matrice facoltativa di numeri itagSequence da enumerare.

Se cEnumColumnId è 0 (zero), rgEnumColumnId viene ignorato e tutti i valori di colonna vengono enumerati e restituiti al chiamante. Se un elemento della matrice ID colonna fa riferimento a un ID colonna pari a 0 (zero), l'enumerazione di tale colonna viene ignorata e verrà generato uno slot corrispondente nell'output con stato di colonna di JET_wrnColumnSkipped.

Se ctagSequence è 0 (zero) per un determinato elemento della matrice ID colonna, rgtagSequence viene ignorato e tutti i valori di colonna per tale ID colonna vengono enumerati e restituiti al chiamante. Se un elemento di una matrice di numeri itagSequence fa riferimento a un numero itagSequence di 0 (zero), l'enumerazione di tale numero di itagSequence viene ignorata e verrà generato uno slot corrispondente nell'output con uno stato del valore di colonna di JET_wrnColumnSkipped.

rgEnumColumnId

Vedere cEnumColumnId.

pcEnumColumn

Restituisce la matrice enumerata di colonne e i relativi valori in memoria allocati tramite il callback compatibile con itagSequence specificato.

Se viene richiesta una matrice di ID di colonna nell'input, l'ordine e le dimensioni della matrice di output rifletteranno l'ordine e le dimensioni della matrice di input. Analogamente, se viene richiesta una matrice di numeri itagSequence per un ID di colonna specifico sull'input, l'ordine e le dimensioni della matrice di output dei valori di colonna per tale colonna riflettono l'ordine e le dimensioni della matrice di input.

I parametri di output sono impostati su 0 (zero) e NULL su qualsiasi errore tranne JET_errBadColumnId e JET_errColumnNotFound. Quando vengono restituiti questi errori, i dati di output sono validi e completi per tutti gli ID di colonna interessati. Il codice di stato per ogni ID di colonna interessato è impostato su uno di questi errori in modo che il chiamante possa determinare quali ID di colonna sono stati danneggiati e potenzialmente intraprendere azioni correttive.

prgEnumColumn

Vedere pcEnumColumn.

pfnRealloc

Identifica un callback compatibile con realloc e un puntatore di contesto facoltativo usato per allocare memoria per la matrice di output di colonne e i relativi valori.

pvReallocContext

Vedere pfnRealloc.

cbDataMost

Imposta un limite sulla quantità di dati da restituire da una colonna binaria lunga o di testo lungo.

Questo parametro può essere usato per impedire l'enumerazione di un valore di colonna estremamente grande. In genere, tale enumerazione potrebbe non riuscire la chiamata API con JET_errOutOfMemory. Se un valore di colonna di grandi dimensioni viene troncato in modo tale, lo stato del valore della colonna sarà JET_wrnColumnTruncated.

grbit

Un gruppo di bit che specificano zero o più delle opzioni seguenti.

Valore	Significato
JET_bitEnumerateCompressOutput	Durante l'enumerazione dei valori di colonna, tutte le colonne per cui si recuperano tutti i valori e che hanno un solo valore di colonna non NULL può essere restituito in un formato compresso. Lo stato di tali colonne verrà impostato su JET_wrnColumnSingleValue e le dimensioni del valore della colonna e la memoria contenente il valore della colonna verrà restituita direttamente nella struttura JET_ENUMCOLUMN . Non è garantito che tutte le colonne idonee vengano compresse in questo modo. Per altre informazioni , vedere JET_ENUMCOLUMN .
JET_bitEnumerateCopy	Questa opzione indica che i valori di colonna modificati del record devono essere enumerati anziché i valori di colonna originali. Se non è stato modificato un valore di colonna, il valore della colonna originale viene enumerato. In questo modo, un valore di colonna che non è ancora stato inserito o aggiornato può essere enumerato durante l'inserimento o l'aggiornamento di un record. Questa opzione è identica a JET_bitRetrieveCopy quando viene usata con JetRetrieveColumn o JetRetrieveColumns.
JET_bitEnumerateIgnoreDefault	Se una colonna specificata non è presente nel record, non verrà restituito alcun valore di colonna. In genere, il valore predefinito per la colonna, se presente, verrà restituito in questo caso. È garantito che se la colonna è impostata su un valore diverso dal valore predefinito, verrà restituito un valore diverso, ovvero se una colonna con un valore predefinito è impostata in modo esplicito su NULL , verrà restituito un valore NULL come valore per tale colonna. Si noti che, anche se questa opzione è richiesta, è comunque possibile visualizzare un valore di colonna che si verifica come uguale al valore predefinito. Non viene eseguito alcun sforzo per rimuovere i valori di colonna corrispondenti ai valori predefiniti. È importante notare che questa opzione influisce sull'output di JetEnumerateColumns quando usato con JET_bitEnumeratePresenceOnly o JET_bitEnumerateTaggedOnly.
JET_bitEnumerateIgnoreUserDefinedDefault	Se una colonna specificata non è presente nel record e ha un valore predefinito definito dall'utente, non verrà restituito alcun valore di colonna. Questa opzione impedisce il callback che calcola il valore predefinito definito dall'utente per la colonna da chiamare durante l'enumerazione dei valori per tale colonna. Windows Server 2003 e versioni precedenti: Per le versioni precedenti e Windows Server 2003, l'operazione avrà esito negativo con JET_errCallbackFailed. Windows Server 2003 SP1: Questo valore possibile è disponibile solo per i sistemi operativi Windows Server 2003 SP1 e versioni successive. Se questo valore possibile viene specificato e la tabella contiene una colonna con un valore predefinito definito dall'utente, l'operazione avrà esito negativo con JET_errCallbackFailed.
JET_bitEnumeratePresenceOnly	Se esiste un valore non NULL per la colonna o il valore di colonna richiesto, i dati associati non vengono restituiti. Lo stato associato per tale colonna o valore di colonna verrà invece impostato su JET_wrnColumnPresent. Se il valore di colonna o colonna è NULL , JET_wrnColumnNull verrà restituito come di consueto.
JET_bitEnumerateTaggedOnly	Quando si enumera tutti i valori di colonna nel record , ad esempio quando cEnumColumnId è zero, verranno restituiti solo i valori di colonna contrassegnati. Questa opzione non è consentita durante l'enumerazione di una matrice specifica di ID colonna.
JET_bitEnumerateInRecordOnly	Windows 7: JET_bitEnumerateInRecordOnly viene introdotto in Windows 7.

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. Questo errore verrà restituito da JetEnumerateColumns se sono stati richiesti id di colonna specifici, uno di questi ID di colonna non è valido e il primo ID colonna non valido non è riuscito con questo errore per il relativo codice di stato della colonna.
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'ID colonna specificato non esiste nella tabella. Questo errore verrà restituito da JetEnumerateColumns se sono stati richiesti ID di colonna specifici, uno di questi ID di colonna non è valido e il primo ID colonna non valido non è riuscito con questo errore per il relativo codice di stato 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. Windows XP: Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errInvalidgrbit	Una delle opzioni richieste non è valida o non è stata implementata. Questo errore verrà restituito da JetEnumerateColumns quando: JET_bitEnumerateLocal specificato. Viene specificato un grbit non valido.
JET_errInvalidParameter	Uno dei parametri forniti conteneva un valore imprevisto o conteneva un valore che non ha senso se combinato con il valore di un altro parametro. Questo errore verrà restituito da JetEnumerateColumns quando: pcEnumColumn è NULL. prgEnumColumn è NULL. pfnRealloc è NULL.
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_errRecordDeleted	Il cursore è posizionato su un record eliminato. I motivi possono essere diversi. Il motivo più comune è che la sessione non si trova in una transazione, che il cursore è stato posizionato su un record, che è stato eliminato e quindi il cursore ha tentato di fare riferimento a tale record.
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.

In caso di esito positivo, i dati richiesti verranno restituiti nei buffer di output. È responsabilità del chiamante liberare qualsiasi memoria allocata da questo callback e restituita nei buffer di output. Tale memoria deve essere liberata tramite il callback compatibile con realloc fornito. Non verrà apportata alcuna modifica allo stato del database.

In caso di errore, nessuno dei dati richiesti verrà restituito. Qualsiasi memoria allocata durante la chiamata verrà liberata automaticamente usando il callback compatibile con realloc fornito. Non verrà apportata alcuna modifica allo stato del database.

Commenti

Se si enumera tutti i valori di colonna nel record e non è stato specificato JET_bitEnumerateIgnoreDefaults, non è possibile presupporre che non venga mai visualizzato un valore di colonna o colonna con un codice di stato di JET_wrnColumnNull. È possibile visualizzare questo codice di stato se una colonna ha un valore predefinito ed è stata impostata in modo esplicito su NULL o se la colonna è una colonna non di tipo sparse , ad esempio una colonna fissa o variabile.

Il parametro cbDataMost non si applica a tutti i valori di colonna. Questo parametro tronca solo i valori di colonna binaria lunghi e lunghi che sono così grandi che sono stati archiviati separatamente dal record.

Se JetEnumerateColumns restituisce dati nei parametri di output, il chiamante è responsabile della liberazione della memoria nella matrice e di qualsiasi memoria definita dai puntatori incorporati in tale matrice.

Requisiti

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

Vedere anche

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_ENUMCOLUMNID
JET_ENUMCOLUMN
JET_ENUMCOLUMNVALUE
JET_PFNREALLOC
realloc
JetRetrieveColumn
JetRetrieveColumns