Funzione JetSetColumn

Articolo
06/13/2023

Si applica a: Windows | Windows Server

Funzione JetSetColumn

La funzione JetSetColumn modifica un singolo valore di colonna in un record modificato da inserire o aggiornare il record corrente. Può sovrascrivere un valore esistente, aggiungere un nuovo valore a una sequenza di valori in una colonna multivalore, rimuovere un valore da una sequenza di valori in una colonna multivalore oppure aggiornare tutto o parte di un valore long, una colonna di tipo JET_coltypLongText o JET_coltypLongBinary.

    JET_ERR JET_API JetSetColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit,
      __in_opt      JET_SETINFO* psetinfo
    );

Parametri

sesid

Sessione da utilizzare per questa chiamata.

tableid

Cursore da utilizzare per questa chiamata.

columnid

JET_COLUMNID della colonna da recuperare. In alternativa, è possibile specificare un valore columnid pari a 0 (zero). Quando viene specificato columnid 0 (zero), tutte le colonne con tag sparse e multivalore vengono considerate come una singola colonna. Ciò semplifica il recupero di tutte le colonne di tipo sparse presenti in un record.

pvData

Buffer di input contenente dati da usare per il valore della colonna.

cbData

Dimensioni in byte del buffer di input.

grbit

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

Valore	Significato
JET_bitSetAppendLV	Questa opzione consente di aggiungere dati a una colonna di tipo JET_coltypLongText o JET_coltypLongBinary. Lo stesso comportamento può essere ottenuto determinando le dimensioni del valore lungo esistente e specificando ibLongValue in psetinfo. Tuttavia, è più semplice usare questo grbit perché non è necessario conoscere le dimensioni del valore di colonna esistente.
JET_bitSetOverwriteLV	Questa opzione viene usata per sostituire il valore long esistente con i dati appena forniti. Quando si usa questa opzione, è come se il valore lungo esistente sia stato impostato su 0 (zero) lunghezza prima di impostare i nuovi dati.
JET_bitSetRevertToDefaultValue	Questa opzione è applicabile solo per le colonne con tag, sparse o multivalore. Fa in modo che la colonna restituisca il valore di colonna predefinito nelle successive operazioni di recupero delle colonne. Tutti i valori di colonna esistenti vengono rimossi.
JET_bitSetSeparateLV	Questa opzione viene utilizzata per forzare un valore lungo, le colonne di tipo JET_coltypLongText o JET_coltypLongBinary, da archiviare separatamente dal resto dei dati del record. Ciò si verifica normalmente quando le dimensioni del valore lungo impediscono l'archiviazione con i dati dei record rimanenti. Tuttavia, questa opzione può essere usata per forzare l'archiviazione separata del valore long. Si noti che i valori lunghi quattro byte di dimensioni inferiori non possono essere costretti a essere separati. In questi casi, l'opzione viene ignorata.
JET_bitSetSizeLV	Questa opzione viene usata per interpretare il buffer di input come numero intero di byte da impostare come lunghezza del valore lungo descritto dall'id colonna specificato e, se specificato, il numero di sequenza in psetinfo-itagSequence>. Se le dimensioni specificate sono maggiori del valore della colonna esistente, la colonna verrà estesa con 0s. Se le dimensioni sono inferiori al valore della colonna esistente, il valore verrà troncato.
JET_bitSetUniqueMultiValues	Questa opzione viene usata per imporre che tutti i valori in una colonna multivalore siano distinti. Questa opzione confronta i dati della colonna di origine, senza trasformazioni, con altri valori di colonna esistenti e viene restituito un errore se viene trovato un duplicato. Se questa opzione viene specificata, non è possibile JET_bitSetAppendLV JET_bitSetOverwriteLV e JET_bitSetSizeLV.
JET_bitSetUniqueNormalizedMultiValues	Questa opzione viene usata per imporre che tutti i valori in una colonna multivalore siano distinti. Questa opzione confronta la trasformazione normalizzata della chiave dei dati della colonna, con altri valori di colonna esistenti trasformati in modo analogo e viene restituito un errore se viene trovato un duplicato. Se questa opzione viene specificata, non è possibile JET_bitSetAppendLV JET_bitSetOverwriteLV e JET_bitSetSizeLV.
JET_bitSetZeroLength	Questa opzione viene usata per impostare un valore su lunghezza zero. In genere, un valore di colonna è impostato su NULL passando un cbMax pari a 0 (zero). Tuttavia, per alcuni tipi, ad esempio JET_coltypText, un valore di colonna può essere 0 (zero) lunghezza anziché NULL e questa opzione viene usata per distinguere tra NULL e 0 (zero) lunghezza. Nota In generale, se la colonna è una colonna a lunghezza fissa, questo bit viene ignorato e la colonna è impostata su NULL. Tuttavia, se la colonna è una colonna con tag a lunghezza fissa, la lunghezza della colonna è impostata su 0. Quando la colonna con tag a lunghezza fissa è impostata su 0, tenta di recuperare la colonna con JetRetrieveColumn o JetRetrieveColumns avrà esito positivo, ma la lunghezza effettiva restituita nel parametro cbActual è 0.
JET_bitSetIntrinsicLV	Questa opzione viene usata per archiviare l'intero valore long nel record.
JET_bitSetCompressed	Questa opzione viene usata per tentare la compressione dei dati durante l'archiviazione dei dati. Windows 7: JET_bitSetCompressed è stato introdotto in Windows 7.
JET_bitSetUncompressed	Questa opzione non viene usata per tentare la compressione durante l'archiviazione dei dati. Windows 7: JET_bitSetUnCompressed è stato introdotto in Windows 7.

psetinfo

Puntatore a parametri di input facoltativi che possono essere impostati per questa funzione usando la struttura JET_SETINFO .

Se psetinfo viene assegnato come NULL , la funzione si comporta come se fosse stato assegnato un itagSequence pari a 1 e un valore ibLongValue pari a 0 (zero). In questo modo, il set di colonne imposta il primo valore di una colonna multivalore e imposta i dati lunghi a partire dall'offset 0 (zero).

Per questo parametro è possibile impostare le opzioni seguenti:

Valore	Significato
ibLongValue	Offset binario in un valore di colonna lungo in cui devono iniziare i dati impostati.
itagSequence	Numero di sequenza del valore di colonna multivalore desiderato da impostare. Se itagSequence è impostato su 0 (zero), il valore fornito deve essere aggiunto alla fine della sequenza di valori multivalore. Se il numero di sequenza specificato è maggiore dell'ultimo valore multivalore esistente, viene aggiunto di nuovo il valore specificato alla fine della sequenza di valori. Se il numero di sequenza corrisponde a un valore esistente, tale valore viene sostituito con il valore specificato.

Valore

Significato

ibLongValue

Offset binario in un valore di colonna lungo in cui devono iniziare i dati impostati.

itagSequence

Numero di sequenza del valore di colonna multivalore desiderato da impostare. Se itagSequence è impostato su 0 (zero), il valore fornito deve essere aggiunto alla fine della sequenza di valori multivalore. Se il numero di sequenza specificato è maggiore dell'ultimo valore multivalore esistente, viene aggiunto di nuovo il valore specificato alla fine della sequenza di valori. Se il numero di sequenza corrisponde a un valore esistente, tale valore viene sostituito con il valore specificato.

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 Errori del motore di archiviazione estendibile e parametri di gestione degli errori.

Codice restituito	Descrizione
JET_errSuccess	Operazione riuscita.
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à sull'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_errColumnNotUpdatable	È stato effettuato un tentativo non valido di aggiornare un valore long durante un'operazione di eliminazione dell'aggiornamento originale di copia di inserimento.
JET_errColumnTooBig	I dati del valore di colonna specificati nel buffer di input superano la limitazione delle dimensioni naturale per una colonna a lunghezza fissa o configurata per colonne di testo a lunghezza fissa o binarie. Questo errore viene restituito anche quando si passano più di 1024 byte di dati per una colonna lunga e si imposta il flag JET_bitSetIntrinsicLV.
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_errInvalidBufferSize	Le dimensioni dei dati del valore di colonna specificate non corrispondono a ciò che è naturale per il tipo di dati a lunghezza fissa.
JET_errInvalidColumnType	È stato effettuato un tentativo non valido di aggiornare una colonna di incremento automatico durante un'operazione di inserimento o aggiornamento o di aggiornare una colonna di versione durante un'operazione di sostituzione.
JET_errInvalidgrbit	Le opzioni fornite sono sconosciute o una combinazione non valida di impostazioni di bit note.
JET_errInvalidParameter	La proprietà psetinfo-cbStruct> specificata non è una dimensione valida per la struttura JET_SETINFO .
JET_errMultiValuedDuplicate	L'operazione imposta colonna ha tentato di creare un valore duplicato e di specificare JET_bitSetUniqueMultiValues o JET_bitSetUniqueNormalizedMultiValues.
JET_errNotInitialized	Non è possibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.
JET_errNotInTransaction	È stato effettuato un tentativo non valido di aggiornare un valore di colonna lungo quando la sessione chiamante non era in una transazione.
JET_errNullInvalid	È stato effettuato un tentativo non valido di impostare una colonna non NULL su NULL.
JET_errColumnIllegalNull	Uguale a JET_errNullInvalid.
JET_errRecordTooBig	Impossibile impostare il valore della colonna sul valore nel buffer di input perché avrebbe causato il superamento della limitazione delle dimensioni della pagina del record. Le colonne di tipo JET_coltypLongText o JET_coltypLongBinary possono essere archiviate separatamente dai dati dei record rimanenti. Tuttavia, è necessario archiviare altre colonne con il record e può causare il superamento della limitazione delle dimensioni del record. Anche le colonne lunghe richiedono 5 byte di spazio all'interno del record come collegamento e questo può causare la restituzione di JET_errRecordTooBig.
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_errUpdateNotPrepared	Il cursore non è attualmente in corso di inserimento di un nuovo record o dell'aggiornamento di un record esistente.
JET_errVersionStoreOutOfMemory	Questo errore si verifica quando le dimensioni configurate dell'archivio versioni non sono sufficienti per contenere tutti gli aggiornamenti in sospeso.
JET_wrnColumnMaxTruncated	Il valore della colonna nel buffer di input ha superato la lunghezza massima configurata per una colonna a lunghezza variabile ed è stato troncato.

In caso di esito positivo, la parte desiderata di un valore di colonna per la colonna specificata viene impostata con i dati copiati dal buffer di input. È possibile che il set di dati sia stato troncato se ha superato la lunghezza massima specificata per una colonna a lunghezza variabile.

In caso di errore, la posizione del cursore rimane invariata e nel buffer di copia non vengono aggiornati dati relativi ai valori di colonna.

Commenti

L'impostazione di valori lunghi, valori per le colonne JET_coltypLongBinary di tipo JET_coltypLongText o JET_coltypLongBinary, deve essere eseguita solo quando la sessione chiamante si trova in una transazione. Se la sessione chiamante non si trova in una transazione, è possibile eseguire il commit completo delle modifiche ai valori lunghi archiviati separatamente anche quando l'operazione di aggiornamento viene successivamente annullata. Se la sessione chiamante si trova in una transazione, è possibile eseguire il rollback completo degli effetti dell'aggiornamento annullando l'aggiornamento e eseguendo il rollback della transazione di sessione.

Gli aggiornamenti degli indici non vengono eseguiti in seguito alle operazioni JetSetColumn . Gli indici vengono invece aggiornati solo dopo aver completato tutte le modifiche alle colonne e viene chiamato JetUpdate . Ciò consente l'aggiornamento più efficiente degli indici quando gli indici comportano la modifica di più colonne.

Le dimensioni di un record sono limitate in base alle dimensioni della pagina del database. Tutti i valori lunghi nel record maggiori di cinque byte verranno archiviati separati dal record se i dati nel record superano il limite in seguito a un'operazione JetSetColumn . L'errore JET_errRecordTooBig verrà restituito solo dopo che tutti i dati di colonna record separabili sono stati archiviati separatamente dal record e il record supera ancora il limite di dimensioni del record.

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_SETINFO
JetRetrieveColumn
JetSetColumns

Condividi tramite

Funzione JetSetColumn