sqlite.h


Poner un punto de control a una base de datos

int sqlite3_wal_checkpoint_v2(
  sqlite3 *db,                    /* Manipulador de base de datos */
  const char *zDb,                /* Nombre de la base de datos asociada (o NULL) */
  int eMode,                      /* valor SQLITE_CHECKPOINT_* */
  int *pnLog,                     /* OUT: Tamaño del diario WAL en marcos */
  int *pnCkpt                     /* OUT: Número total de marcos en el punto de control */
);

Ejecuta una operación de punto de control en el WAL de base de datos zDb asociada con el manipulador de base de datos db. La operación específica se determina por el valor del parámetro eMode.

SQLITE_CHECKPOINT_PASSIVE
El punto de control de tantos marcos como sea posible sin esperar a que los lectores o escritores de la base de datos terminen. Sincronizar el archivo db si todos los marcos en el diario son un punto de control. Este modo es el mismo que llamar a sqlite3_wal_checkpoint(). La retrollamada de manipulación de ocupado nunca es invocada.
SQLITE_CHECKPOINT_FULL
Este modo bloqua (llama a la retrollamada de manipulación de ocupado) hasa que no haya escritores en la base de datos y a que todos los lectores estén leyendo desde la imagen más reciente de la base de datos. Entonces establece el punto de control para todos los marcos en el fichero de diario y sincroniza el fichero de base de datos. Esta llamada bloquea a los escritores de la base de datos mientras se ejecuta, pero no a los lectores.
SQLITE_CHECKPOINT_RESTART
Este modo funciona igual que SQLITE_CHECKPOINT_FULL, excepto que despuñes de establecer el punto de control en el fichero de diario bloquea (llama a la retrollamada de manipulación de ocupado) hasta que todos los lectores estén leyendo sólo desde el fichero de base de datos. Esto asegura que el siguiente cliente que escriba en el fichero de base de datos reinicia el fichero de diario desde el principio. Esta llamada bloquea la base de datos a los escritores mientras se ejecuta, pero no a los lectores.

Si pnLog no es NULL, entonce *pnLog se establece al número total de marcos en el fichero de diario antes de regresar. Si pnCkpt no es NULL, entonces *pnCkpt se establece al número total de marcos en el punto de control (incluyendo cualquier que hubiese en un punto de control cuando esta función fue llamada). *pnLog y *pnCkpt pueden estar poblados aunque sqlite3_wal_checkpoint_v2() retorne algo que no sea SQLITE_OK. Si no hay valores disponibles debido a un error, ambos son establecidos a -1 antes de retornar esto al proceso que llama.

Todas las llamadas obtienen un bloqueo "punto de control" exclusivo en el fichero de base de datos. Si cualquier otro proceso está ejecutando una operación de punto de control al mismo tiempo, el bloqueo no puede ser obtenido y se retorna SQLITE_BUSY. Incluso si hay un manipulador de ocupado configurado, no se le puede invocar en este caso.

Los modos SQLITE_CHECKPOINT_FULL y RESTART también obtienen un bloqueo exclusivo "writer" sobre el fichero de base de datos. Si el bloqueo de escritura no puede ser obtenido inmediatamente, y está configurado un manipulador de ocupado, es invocado y el bloque de escritura reintentado hasta que el manipulador de ocupado retorne con 0 o el bloqueo sea obtenido con éxito. El manipulador de ocupado también es invocado mientras se espera a los lectores de la base de datos como se describe arriba. Si el manipulador de ocupado devuelve 0 antes de que el bloqueo de escritura sea obtenido o mientras se espera a los lectores de la base de datos, la operación de punto de control se procesa desde ese punto de la misma forma que con SQLITE_CHECKPOINT_PASSIVE - poniendo puntos de control en tantos marcos como sea posible sin bloquear ninguna más. En ese caso se retorna SQLITE_BUSY.

Si el parámetro zDb es NULL o apunta a una cadena de longitud cero, la operación especificada se intenta en todas las bases de datos WAL. En ese caso los valores escritos en los parámetros de salida *pnLog y *pnCkpt son indefinidos. Si se encuentra un error SQLITE_BUSY cuando se procesa una o más de las bases de datos WAL adjuntas, la operación se sigue intentando en las bases de datos adjuntas y se devuelve SQLITE_BUSY. Si se produce cualquiero otro error mientras se procesa la base de datos adjunta, el proceso se abandona y se devuelve un código de error inmediatamente. Si no se produce un error(SQLITE_BUSY u otro) mientras se procesan las bases de datos adjuntas, se devuelve SQLITE_OK.

Si la base de datos zDb es el nombre de una base de datos adjunta que no está en modo WAL, se devuelve SQLITE_OK y tanto *pnLog como *pnCkpt se establecen a -1. Si zDb no es NULL (o una cadena de longitud nula) y no es el nombre de ninguna base de datos adjunta, se devuelve SQLITE_ERROR.