Funzione JetCompact

Si applica a: Windows | Windows Server

Funzione JetCompact

La funzione JetCompact crea una copia di un database esistente. La copia viene compattata in uno stato ottimale per l'utilizzo. I dati nei dati copiati verranno compressi in base alle misure scelte per gli indici in corrispondenza della creazione dell'indice. In questo modo, i dati compattati possono essere archiviati il più densamente possibile. In alternativa, i dati compattati possono riservare spazio per i successivi inserimenti di indici o di crescita dei record.

    JET_ERR JET_API JetCompact(
      __in          JET_SESID sesid,
      __in          JET_PCSTR szDatabaseSrc,
      __in          JET_PCSTR szDatabaseDest,
      __in          JET_PFNSTATUS pfnStatus,
      __in_opt      JET_CONVERT* pconvert,
      __in          JET_GRBIT grbit
    );

Parametri

sesid

Sessione da utilizzare per questa chiamata.

szDatabaseSrc

Database di origine che verrà compattato.

szDatabaseDest

Nome da utilizzare per il database compattato.

pfnStatus

Funzione di callback che può essere chiamata periodicamente tramite l'operazione compatta del database per segnalare lo stato di avanzamento.

pconvert

Puntatore utilizzato per designare una DLL ESE alternativa che può essere usata per leggere il database di origine e per fornire parametri facoltativi per un'operazione JetCompact che converte un database da un formato precedente a un formato di versione successiva. Questa funzionalità non è più disponibile in Windows Server 2003.

grbit

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

Valore	Significato
JET_bitCompactRepair	Usato quando il database di origine è noto come danneggiato. Consente un intero set di nuovi comportamenti destinati a recuperare il maggior numero possibile di dati dal database di origine. JetCompact con questo set di opzioni può restituire JET_errSuccess ma non copiare tutti i dati creati nel database di origine. I dati presenti in parti danneggiate del database di origine verranno ignorati.
JET_bitCompactStats	Fa in modo che JetCompact dump delle statistiche nel database di origine in un file denominato DFRGINFO.TXT. Le statistiche includono il nome di ogni tabella nel database di origine, il numero di righe in ogni tabella, le dimensioni totali in byte di tutte le righe di ogni tabella, le dimensioni totali in byte di tutte le colonne di tipo JET_coltypLongText o JET_coltypLongBinary che erano sufficienti per essere archiviate separate dal record, il numero di pagine foglia dell'indice cluster, e il numero di pagine foglia con valore lungo. Inoltre, le statistiche di riepilogo, incluse le dimensioni del database di origine, il database di destinazione, il tempo necessario per la compattazione del database, lo spazio temporaneo del database vengono tutti scaricati.

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_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_errFeatureNotAvailable	È stato fornito un puntatore pconvert non NULL, ma la versione di ESE in uso non supporta la funzionalità di conversione. Questa funzionalità è stata rimossa nella versione di Windows Server 2003 di ESE.
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_errInTransaction	La sessione chiamante si trova all'interno di una transazione. JetCompact deve essere chiamato da una sessione all'esterno di qualsiasi transazione.
JET_errNotInitialized	Non è possibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.
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. 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, il database di origine viene copiato nel database di destinazione. Il database di destinazione è in uno stato ottimale, ad esempio tutti gli indici di tabella si trovano nello spazio su disco logico adiacente. Ogni pagina di indice viene riempita in base alla quantità configurata quando gli indici sono stati originariamente creati nel database di origine. Tutte le impostazioni di dati e metadati vengono copiate con la massima fedeltà, a meno che non sia stata specificata l'opzione di ripristino. Se è stata specificata l'opzione di ripristino, è possibile che alcuni dati del database di origine non siano stati copiati.

In caso di errore, il database di destinazione può esistere ma non è una copia completa del database di origine.

Commenti

La compattazione di un database viene usata anche per aggiornare un database da un formato di versione precedente a una versione più moderna. Un parametro facoltativo è pconvert, che contiene una struttura che può contenere una descrizione per una DLL di versione precedente da usare per la lettura del formato del database di origine. Questa funzionalità non è più disponibile in Windows Server 2003. Successivamente a Windows Server 2003, le nuove versioni di ESE sono sempre in grado di leggere le versioni precedenti del formato del database e quindi questa funzionalità non è necessaria.

La densità desiderata dei dati dopo un'operazione compatta viene specificata quando vengono create tabelle e indici. La densità deve essere compresa tra il 20% e il 100%. Se un database viene letto e non aggiornato, le applicazioni imposteranno la densità sul 100% per ridurre il numero di operazioni di I/O durante l'elaborazione delle query. Tuttavia, se i dati vengono aggiornati frequentemente con operazioni che aumentano le dimensioni dei dati archiviati insieme al record o i nuovi dati vengono spesso inseriti, l'applicazione sceglierà una densità inferiore in modo che gli aggiornamenti trovino più spesso le risorse necessarie disponibili. L'operazione di compattazione del database determina la disposizione ideale del database in base al riempimento scelto dall'applicazione.

La compattazione del database è un'operazione off-line. Non può essere eseguita mentre il database è in uso. Di conseguenza, viene in genere eseguita come parte di un processo di compilazione di sviluppo di un'applicazione che fornisce un set di dati come parte di se stesso.

La compattazione del database offline tocca ogni bit di dati in un database e può essere usata come mezzo per controllare la coerenza di un database. Se un database è sospetto, può essere compattato. Se non viene rilevato alcun errore dalla compattazione, sarà noto che il database è in uno stato valido per ESE.

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.
Unicode	Implementato come JetCompactW (Unicode) e JetCompactA (ANSI).

Vedere anche

JET_COLTYP
JET_ERR
JET_SESID
JetDefragment
JetStopService