Funzione JetUpdate

Si applica a: Windows | Windows Server

Funzione JetUpdate

La funzione JetUpdate esegue un'operazione di aggiornamento, inclusa l'inserimento di una nuova riga in una tabella o l'aggiornamento di una riga esistente. L'eliminazione di una riga di tabella viene eseguita chiamando JetDelete.

JetUpdate è il passaggio finale per eseguire un inserimento o un aggiornamento. L'aggiornamento viene avviato chiamando JetPrepareUpdate e quindi chiamando JetSetColumn o JetSetColumns una o più volte per impostare lo stato del record. Infine, JetUpdate viene chiamato per completare l'operazione di aggiornamento. Gli indici vengono aggiornati solo da JetUpdate o JetUpdate2 e non durante JetSetColumn o JetSetColumns.

    JET_ERR JET_API JetUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbBookmark,
      __out_opt     unsigned long* pcbActual
    );

Parametri

sesid

Sessione da usare per questa chiamata.

tableid

Cursore da usare per questa chiamata.

pvBookmark

Puntatore a un segnalibro restituito per una riga inserita.

cbBookmark

Dimensioni del buffer a cui fa riferimento pvBookmark.

pcbActual

Dimensione restituita del segnalibro per la riga inserita restituita in pvBookmark.

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_errBufferTooSmall	Il buffer specificato per il segnalibro di record non è abbastanza grande per archiviare il segnalibro del record.
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_errColumnIllegalNull	Uguale a JET_errNullInvalid.
JET_errDiskFull	L'operazione di aggiornamento richiede la crescita del file di database o l'allocazione del file di log, ma l'unità disco in cui risiede il file di database o la serie di log è completa. In alternativa, il file di database si trova in un volume formattato FAT32 e il file di database è già 4GBytes, il limite per file per FAT32.
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_errInvalidParameter	Il parametro di prep specificato nella funzione JetPrepareUpdate non è un flag valido.
JET_errKeyDuplicate	Una chiave di indice per questo record è un duplicato di un'altra chiave di indice per un altro record già nella tabella e l'indice non consente duplicati.
JET_errKeyTruncated	Il record inserito o aggiornato ha uno o più indici per i quali la chiave generata ha superato le dimensioni massime consentite. Di conseguenza, l'operazione non è riuscita a impedire il troncamento della chiave.
JET_errMultiValuedIndexViolation	Il record inserito o aggiornato ha una colonna multivalore indicizzata con due o più valori identici all'interno delle dimensioni massime della chiave di lunghezza impostate per l'indice. Di conseguenza, il record ha due voci identiche nell'indice che non è valido.
JET_errNotInitialized	Non è possibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.
JET_errNullInvalid	Una o più colonne nel record da inserire o nello stato aggiornato di un record sostituito è NULL che viola il vincolo definito per tali colonne.
JET_errNullKeyDisallowed	Uno o più indici non sono definiti per consentire una chiave NULL e lo stato inserito o aggiornato di un record sostituito viola questo vincolo definito.
JET_errRecordPrimaryChanged	Un'operazione di sostituzione dei record ha aggiornato la chiave primaria. Aggiornamenti alle colonne chiave primaria devono essere eseguite tramite l'eliminazione del record esistente e l'inserimento di un nuovo record con i dati desiderati.
JET_errRestoreInProgress	Non è possibile completare l'operazione perché un'operazione di ripristino è in corso 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_errTransReadOnly	Non è possibile tentare un aggiornamento quando all'interno dell'ambito di una transazione di sola lettura. Una transazione di sola lettura è una transazione avviata usando una chiamata a JetBeginTransaction2 con JET_bitTransactionReadOnly. Windows XP: Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errUpdateNotPrepared	JetPrepareUpdate è stato chiamato con JET_prepCancel, ma il cursore non era nello stato preparato.
JET_errVersionStoreOutOfMemory	L'operazione non è riuscita perché la memoria non è sufficiente per conservare informazioni transazionali sull'aggiornamento.
JET_errWriteConflict	Un'altra sessione ha precedentemente bloccato il record per l'aggiornamento. L'aggiornamento tentato da questa sessione avrà esito negativo.

In caso di esito positivo, l'operazione di aggiornamento aperta sul cursore viene completata. Se per la tabella viene definita una colonna di incremento automatico, questo valore viene impostato per i record inseriti. Se per la tabella viene definita una colonna di versione, il relativo valore viene inizializzato per i record appena inseriti o incrementato ogni volta che viene sostituito un record. Tutti gli indici, inclusi gli indici cluster e non cluster, vengono aggiornati.

In caso di errore, non vengono apportate modifiche di qualsiasi tipo al database. Prima di inserire e prima di sostituire le funzioni di callback potrebbe essere stato chiamato, ma dopo l'inserimento e dopo la sostituzione dei callback non sarà stato chiamato, poiché quest'ultimo non può causare un errore di aggiornamento. Il buffer di copia del cursore viene lasciato nello stato preparato, in modo che l'opportunità esista per correggere in modo incrementale i problemi che hanno causato errori e riprovare l'operazione di aggiornamento.

Commenti

Le funzioni di callback possono essere registrate per essere chiamate prima o dopo l'inserimento e prima o dopo l'aggiornamento.

Le limitazioni delle dimensioni dei record vengono applicate da JetSetColumn e non in generale da JetUpdate.

È importante comprendere l'impatto dell'esecuzione di un numero elevato di operazioni di aggiornamento all'interno di una singola transazione. Ogni aggiornamento al database deve essere monitorato dal motore di database nell'archivio delle versioni. L'archivio delle versioni contiene un record live di tutte le diverse versioni di ogni record o voce di indice nel database che può essere visualizzato da tutte le transazioni attive. Queste versioni vengono usate per supportare il controllo di concorrenza a più versioni in uso dal motore di database per supportare le transazioni usando l'isolamento dello snapshot. Dopo che il motore di database ha esaurito le risorse usate per archiviare queste versioni, non può più accettare ulteriori modifiche fino a quando alcune transazioni non hanno concluso per consentire il recupero di queste risorse. Quando il motore si trova in questo stato, tutti gli aggiornamenti avranno esito negativo con JET_errVersionStoreOutOfMemory. Le risorse disponibili per il motore di database per archiviare queste versioni possono essere controllate usando JetSetSystemParameter con JET_paramMaxVerPages e JET_paramGlobalMinVerPages.

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
JetDelete
JetPrepareUpdate
JetRegisterCallback
JetRetrieveColumn
JetRetrieveColumns
JetSetColumn
JetSetColumns
JetSetSystemParameter
Parametri di sistema