Funzione JetEscrowUpdate

Articolo
06/13/2023

Si applica a: Windows | Windows Server

Funzione JetEscrowUpdate

La funzione JetEscrowUpdate esegue un'operazione di addizione atomica su una colonna. Questa funzione consente a più sessioni di aggiornare contemporaneamente lo stesso record senza conflitti.

    JET_ERR JET_API JetEscrowUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in          void* pv,
      __in          unsigned long cbMax,
      __out_opt     void* pvOld,
      __in          unsigned long cbOldMax,
      __out_opt     unsigned long* pcbOldActual,
      __in          JET_GRBIT grbit
    );

Parametri

sesid

Sessione da utilizzare per questa chiamata.

tableid

Cursore da utilizzare per questa chiamata.

columnid

Columnid della colonna da aggiornare.

Puntatore a un buffer contenente l'addend per la colonna.

cbMax

Dimensione del buffer contenente l'addend.

pvOld

Buffer di output che riceverà il valore corrente della colonna archiviato nel database (il controllo delle versioni viene ignorato).

cbOldMax

Dimensione massima del buffer di output che riceverà il valore corrente della colonna. Attualmente è supportato solo JET_coltypLong, pertanto il buffer deve avere una lunghezza di 4 byte o 0 byte. Se pvOld è NULL, cbOldMax deve essere 0.

pcbOldActual

Riceve la quantità effettiva di dati sui valori non elaborati ricevuti nel buffer di output.

grbit

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

Valore	Significato
JET_bitEscrowNoRollback	Anche se la sessione che esegue l'aggiornamento del deposito ha il rollback della transazione, questo aggiornamento non verrà annullato. Si noti che poiché i record di log potrebbero non essere scaricati su disco, è possibile che gli aggiornamenti recenti del deposito eseguiti con questo flag vadano persi in caso di arresto anomalo.

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_errAlreadyPrepared	Il cursore ha un aggiornamento preparato con JetPrepareUpdate.
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_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. Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errInvalidBufferSize	È stata passata una dimensione del buffer non valida. Attualmente è supportato solo JET_coltypLong, pertanto il buffer deve essere di 4 byte.
JET_errInvalidOperation	È stata specificata una colonna non valida. La colonna deve essere creata con JET_bitColumnEscrowUpdate specificato. Solo le colonne fisse di JET_coltypLong possono essere specificate come aggiornabili.
JET_errNoCurrentRecord	Il cursore deve trovarsi in un record per aggiornare una colonna.
JET_errNotInTransaction	Gli aggiornamenti del deposito possono essere eseguiti solo da sessioni in una transazione.
JET_errNotInitialized	Non è possibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.
JET_errPermissionDenied	Il cursore non può essere di sola lettura e aggiornare un 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 da più thread. 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	La sessione deve disporre delle autorizzazioni di scrittura per aggiornare un record.
JET_errWriteConflict	Errore restituito quando viene richiesto un aggiornamento in conflitto.

Commenti

In genere, se due sessioni tentano di aggiornare un record contemporaneamente, la seconda sessione riceverà un errore JET_errWriteConflict a meno che le sessioni non siano completamente serializzate. Per serializzare due sessioni che aggiornano lo stesso record, la seconda sessione deve avviare la transazione dopo che la prima transazione esegue il commit della transazione. Per altre informazioni, vedere JetBeginTransaction .

È possibile aggiornare più colonne nello stesso record. Gli aggiornamenti non influiscono l'uno sull'altro.

Solo le operazioni JetEscrowUpdate sono compatibili tra loro. Se due sessioni diverse tentano di preparare gli aggiornamenti o eliminare lo stesso record, verrà generato un conflitto di scrittura.

		Sessione B JetEscrowUpdate	JetPrepareUpdate	JetDelete
	JetEscrowUpdate	JET_errSuccess	JET_errWriteConflict	JET_errWriteConflict
	JetUpdate	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict
Sessione A	JetDelete	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict

Le operazioni di deposito vengono con controllo delle versioni e vengono annullate usando JetRollback (a meno che non sia stato specificato JET_bitEscrowNoRollback). JetEscrowUpdate restituisce il valore non elaborato della colonna archiviata nel database, perché un'applicazione può voler eseguire un'azione speciale quando viene raggiunto un valore sentinel. JetRetrieveColumn restituisce la visualizzazione con versione corretta della colonna, ignorando gli aggiornamenti apportati dalle sessioni simultanee.

Dato due sessioni che operano sulla stessa colonna dello stesso record, è possibile vedere come funziona questa operazione. Si supponga che la colonna inizi con un valore pari a 0.

sessione	Operazione	Valore archiviato	Valore restituito
A	JetBeginTransation
A	JetBeginTransation		0
A	JetEscrowUpdate (4)	4	0
A	JetRetrieveColumn		4
B	JetBeginTransaction
B	JetRetrieveColumn		0
B	JetEscrowUpdate (3)	7	4
B	JetRetrieveColumn		3
A	JetEscrowUpdate (2)	9	7
A	JetEscrowUpdate (-7)	2	9
B	JetRetrieveColumn		3
A	JetRetrieveColumn		-1
B	JetRollback	-1
A	JetRetrieveColumn		-1

La sostituzione di un record nella stessa transazione che esegue gli aggiornamenti di escrow a un record non è consigliabile. In particolare, se un aggiornamento in un record viene preparato con un JET_TABLEID e viene usato un JET_TABLEID diverso per completare l'aggiornamento del record, l'aggiornamento dell'escrow verrà perso quando viene chiamato JetUpdate . Ciò accade anche se la colonna di escrow non è stata impostata durante l'aggiornamento.

Quando una colonna aggiornabile escrow ha un valore pari a zero, è possibile attivare un comportamento speciale. Questo comportamento si verifica solo se un'operazione JetEscrowUpdate causa che la colonna abbia un valore pari a zero. L'azione non si verifica immediatamente, ma si verifica qualche volta dopo la transazione che ha causato che la colonna ha avuto un valore pari a zero commit. La colonna deve comunque avere un valore pari a zero, ovvero se non sono state modificate altre sessioni. Se la colonna è stata creata con JET_bitColumnDeleteOnZero, il record contenente la colonna verrà eliminato. Se la colonna è stata creata con JET_bitColumnFinalize, verrà rilasciato un callback. Un arresto anomalo può causare che queste azioni non si verifichino, ma la manutenzione online (usando la funzione JetDefragment ) ridistribuirà correttamente le azioni.

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_GRBIT
JET_SESID
JET_TABLEID
JetBeginTransaction
JetDefragment
JetPrepareUpdate
JetRetrieveColumn
JetRollback
JetStopService
JetUpdate

Condividi tramite

Funzione JetEscrowUpdate