Funzione JetPrepareUpdate

Si applica a: Windows | Windows Server

Funzione JetPrepareUpdate

La funzione JetPrepareUpdate è la prima operazione nell'esecuzione di un aggiornamento, ai fini dell'inserimento di un nuovo record o della sostituzione di un record esistente con nuovi valori. Aggiornamenti vengono eseguite chiamando JetPrepareUpdate, quindi chiamando JetSetColumn o JetSetColumn zero o più volte e infine chiamando JetUpdate per completare l'operazione. JetPrepareUpdate e JetUpdate impostano i limiti per un'operazione di aggiornamento e sono importanti per avere solo lo stato di aggiornamento finale di un record immesso negli indici. Questo è sia più efficiente, ma anche necessario nei casi in cui i dati devono corrispondere a uno stato valido tramite più di su un'operazione di colonna impostata.

Esistono alcune opzioni diverse per l'inserimento o la sostituzione dei record e sono descritte in dettaglio di seguito.

    JET_ERR JET_API JetPrepareUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long prep
    );

Parametri

sesid

Sessione da usare per questa chiamata.

tableid

Cursore da usare per questa chiamata.

Preparazione

Le opzioni che possono essere usate per preparare un aggiornamento, che includono quanto segue.

Valore	Significato
JET_prepCancel	Questo flag causa l'annullamento dell'aggiornamento di JetPrepareUpdate per questo cursore .
JET_prepInsert	Questo flag causa la preparazione del cursore per un inserimento di un nuovo record. Tutti i dati vengono inizializzati nello stato predefinito per il record. Se la tabella ha una colonna di incremento automatico, un nuovo valore viene assegnato a questo record indipendentemente dal fatto che l'aggiornamento abbia esito positivo, ha esito negativo o viene annullato.
JET_prepInsertCopy	Questo flag causa la preparazione del cursore per un inserimento di una copia del record esistente. È necessario che sia presente un record corrente se viene usata questa opzione. Lo stato iniziale del nuovo record viene copiato dal record corrente. I valori lunghi archiviati fuori record vengono copiati virtualmente.
JET_prepInsertCopyDeleteOriginal	Questo flag causa la preparazione del cursore per un inserimento dello stesso record e l'eliminazione o il record originale. Viene usato nei casi in cui la chiave primaria è stata modificata.
JET_prepReplace	Questo flag causa la preparazione del cursore per una sostituzione del record corrente. Se la tabella ha una colonna di versione, la colonna della versione viene impostata sul valore successivo nella relativa sequenza. Se questo aggiornamento non viene completato, il valore della versione nel record non sarà interessato. Viene eseguito un blocco di aggiornamento nel record per impedire ad altre sessioni di aggiornare questo record prima che questa sessione venga completata.
JET_prepReplaceNoLock	Questo flag è simile a JET_prepReplace, ma non viene eseguito alcun blocco per impedire ad altre sessioni di aggiornare questo record. Questa sessione può invece ricevere JET_errWriteConflict quando chiama JetUpdate per completare l'aggiornamento.

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_errAlreadyPrepared	JetPrepareUpdate è stato chiamato con un flag valido per la preparazione, ma non JET_prepCancel e il cursore era già nello stato preparato.
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_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_errInvalidParameter	Il flag di prep specificato non è un flag valido.
JET_errNotInitialized	Non è possibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.
JET_errNotInTransaction	JetPrepareUpdate è stato chiamato per sostituire un record con colonne SLV. Colonne SLV. Si noti che le colonne SLV sono una funzionalità non destinata all'utilizzo generale. Questa funzionalità viene usata per supportare l'infrastruttura di Microsoft Exchange e non deve essere usata nell'applicazione.
JET_errRestoreInProgress	Non è possibile completare l'operazione perché un'operazione di ripristino è in corso nell'istanza associata alla sessione.
JET_errRollbackError	JetPrepareUpdate è stato chiamato con JET_prepCancel, ma non è stato possibile eseguire il rollback di tutte le modifiche apportate alle colonne di tipo JET_coltypLongText e/o colonne di tipo JET_coltypLongBinary.
JET_errSessionSharingViolation	Questo flag non può essere usato con la stessa sessione da più thread contemporaneamente. 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	JetPrepareUpdate è stato chiamato con JET_prepCancel, ma il cursore non era nello stato preparato.

In caso di esito positivo, il cursore viene modificato nello stato preparato per lo scopo dell'aggiornamento desiderato o nel caso di JET_prepCancel, il cursore viene ripristinato allo stato non preparato e le modifiche vengono rimosse.

In caso di errore, lo stato del cursore viene lasciato invariato. Se l'errore è stato JET_errRollbackError, lo stato del cursore viene modificato nello stato non preparato, ma non tutte le modifiche sono state ripristinate.

Commenti

L'inserimento di una copia di un record è un'ottimizzazione importante quando i record condividono i dati di tipo JET_coltypLongText e/o JET_coltypLongBinary. Questi dati vengono archiviati fuori record quando sono di grandi dimensioni ed è possibile che più record condividono la stessa rappresentazione fisica dei dati. In questo caso, i dati possono essere aggiornati da entrambi i record, ma in questo modo i dati verranno esplosi in modo che ogni record abbia la propria copia. Non è possibile modificare i dati in un record tramite una modifica da un altro record. Inoltre, non è possibile bloccare un aggiornamento di un record da un aggiornamento di un altro record. Questa è una funzionalità centrale per ESE ed è nota come Blocco a livello di record.

Operazioni di JetUpdate che non riescono a lasciare il cursore nello stato preparato dell'aggiornamento. Ciò consente di correggere alcuni errori, ad esempio un valore di colonna errato, senza dover ricreare lo stato di aggiornamento. Ciò significa che in tutti i casi in cui un cursore abbandona un aggiornamento, deve chiamare in modo esplicito JetPrepareUpdate con JET_prepCancel.

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
JetRetrieveColumn
JetSetColumn
JetUpdate