Compartir a través de

Función JetReadFile

  • Artículo

Se aplica a: Windows | Windows Server

Función JetReadFile

La función JetReadFile recupera el contenido de un archivo abierto con JetOpenFile.

    JET_ERR JET_API JetReadFile(
      __in          JET_HANDLE hfFile,
      __out         void* pv,
      __in          unsigned long cb,
      __out_opt     unsigned long* pcbActual
    );

Parámetros

hfFile

Identificador del archivo que se va a leer.

pv

Búfer de salida que recibirá los datos del archivo.

cb

Tamaño máximo en bytes del búfer de salida.

pcbActual

Recibe la cantidad real de datos de archivo recuperados.

Valor devuelto

Esta función devuelve el tipo de datos JET_ERR con uno de los siguientes códigos de retorno. Para obtener más información sobre los posibles errores de ESE, vea Extensible Storage Engine Errors and Error Handling Parameters.

Código devuelto

Descripción

JET_errSuccess

La operación se ha completado correctamente.

JET_errBackupAbortByServer

Error en la operación porque la copia de seguridad externa actual se ha anulado mediante una llamada a JetStopService. Windows XP solo devolverá este error y versiones posteriores.

JET_errClientRequestToStopJetService

No es posible completar la operación porque toda la actividad de la instancia asociada a la sesión ha dejado de funcionar como resultado de una llamada a JetStopService.

JET_errInstanceUnavailable

No es posible completar la operación porque la instancia asociada a la sesión ha encontrado un error irrecuperable que requiere que se revoque el acceso a todos los datos para proteger la integridad de esos datos. Windows XP solo devolverá este error y versiones posteriores.

JET_errInvalidParameter

Uno de los parámetros proporcionados contenía un valor inesperado o contenía un valor que no tenía sentido cuando se combinaba con el valor de otro parámetro. Esto puede ocurrir para JetReadFile cuando:

  • El identificador de instancia especificado no es válido. Windows XP y versiones posteriores.

  • El tamaño del búfer de salida no es un múltiplo del tamaño de página de la base de datos (JET_paramDatabasePageSize). Windows XP y versiones posteriores.

  • El tamaño del búfer de salida es menor que tres páginas de base de datos (JET_paramDatabasePageSize) y esta es la primera llamada a JetReadFile para el identificador especificado. Windows XP y versiones posteriores.

JET_errNoBackup

Error en la operación porque no hay ninguna copia de seguridad externa en curso.

JET_errNotInitialized

No es posible completar la operación porque la instancia asociada a la sesión aún no se ha inicializado.

JET_errReadVerifyFailure

Error en la operación porque se detectaron daños en los datos no recuperables al leer una página de base de datos desde un archivo de base de datos o un archivo de revisión de base de datos.

JET_errLogReadVerifyFailure

Error en la operación porque se detectaron daños en los datos no recuperables al leer un archivo de registro de transacciones. Windows XP solo devolverá este error y versiones posteriores.

JET_errRestoreInProgress

No es posible completar la operación porque hay una operación de restauración en curso en la instancia asociada a la sesión.

JET_errRunningInMultiInstanceMode

Error en la operación porque se intentó usar el motor en modo heredado (modo de compatibilidad de Windows 2000), donde solo se admite una instancia cuando ya existen varias instancias.

JET_errTermInProgress

No es posible completar la operación porque se está cerrando la instancia asociada a la sesión.

Si se ejecuta correctamente, el siguiente fragmento de datos del archivo se leerá en el búfer de salida. También se devolverá el número real de bytes recuperados. El desplazamiento del archivo en el que se producirá la siguiente lectura será avanzado por esta cantidad.

En caso de error, el estado del búfer de salida no está definido. El error provocará la cancelación de todo el proceso de copia de seguridad de la instancia. En Windows XP y versiones posteriores, la copia de seguridad no se cancelará si se produjo un error al leer un archivo de base de datos. Sin embargo, la copia de seguridad de ese archivo de base de datos se seguirá cancelando y el identificador correspondiente se cerrará automáticamente.

Comentarios

Cualquier llamada a JetReadFile mediante un identificador que ya haya devuelto todos los datos del archivo subyacente (por ejemplo, una llamada anterior devolvió menos bytes que el tamaño del búfer de salida) siempre se realizará correctamente, pero devolverá cero bytes de datos.

Se debe usar un búfer de salida grande para maximizar el rendimiento de la copia de seguridad. Es posible que se requiera cierta experimentación para encontrar el equilibrio adecuado entre el consumo de recursos y el rendimiento de una situación determinada. El búfer de salida no debe ser inferior a 64 KB en ningún caso.

No se admiten varias llamadas simultáneas a JetReadFile con el mismo identificador de archivo. Esto significa que no es posible poner en cola varios búferes para leer simultáneamente en el mismo archivo para lograr un alto rendimiento secuencial. En su lugar, se debe usar un único búfer grande.

Si la instancia está configurada de modo que la limpieza de páginas de base de datos esté habilitada (consulte JET_paramZeroDatabaseDuringBackup en Parámetros del sistema), los datos eliminados se quitarán de la base de datos como efecto secundario de una llamada a JetReadFile en el archivo de base de datos.

Es muy importante comprender cómo interactúan las copias de seguridad y los datos dañados. Si el motor de base de datos detecta daños en los datos durante una copia de seguridad, se producirá un error en la copia de seguridad de la base de datos afectada o de toda la instancia. Se trata de una decisión de diseño consciente destinada a protegerse contra la pérdida de datos. Si el motor de base de datos permitía que una copia de seguridad se realizara correctamente cuando hubiera daños en los datos, es posible que una copia de seguridad anterior y sin corregir se pueda descartar como resultado. Esto sería lamentable porque sería posible corregir los daños en los datos en la instancia activa restaurando esa copia de seguridad y reproduciendo todos los archivos de registro de transacciones en esa base de datos. En este escenario de pérdida de datos cero se supone que el registro circular no está habilitado (consulte JET_paramCircularLog en Parámetros del sistema).

También es importante comprender que, cuando los datos dañados están presentes, la copia de seguridad de streaming será el lugar más probable en el que se detectará por primera vez. Este es el caso porque la copia de seguridad de streaming es el único proceso que examina periódicamente cada página del archivo de base de datos. También es probable que la copia de seguridad de streaming sea el primer proceso para detectar los primeros signos de error de hardware, como se manifiesta por errores intermitentes de daños en los datos. Esto se debe a la cantidad de datos recuperados por la copia de seguridad, así como a la velocidad a la que se recupera.

El motor de base de datos detecta daños en los datos mediante el uso de sumas de comprobación de bloqueo. Estas sumas de comprobación se establecen justo antes de escribir una página de base de datos y se comprueban en una página de base de datos leída. Este esquema permite al motor de base de datos determinar que los datos se han dañado en algún momento, pero no permite que el motor de base de datos determine el origen de ese daño. Históricamente, se ha encontrado que la causa predominante de tales daños procede de orígenes distintos del propio motor de base de datos.

Requisitos

Requisito Value

Cliente

Requiere Windows Vista, Windows XP o Windows 2000 Professional.

Servidor

Requiere Windows Server 2008, Windows Server 2003 o Windows 2000 Server.

Encabezado

Declarado en Esent.h.

Library

Use ESENT.lib.

Archivo DLL

Requiere ESENT.dll.

Consulte también

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFile
JetStopService
Parámetros del sistema