Función JetReadFileInstance

Se aplica a: Windows | Windows Server

Función JetReadFileInstance

La función JetReadFileInstance recupera el contenido de un archivo abierto con la función JetOpenFileInstance .

Windows XP: JetReadFileInstance se introduce en Windows XP.

    JET_ERR JET_API JetReadFileInstance(
      __in          JET_INSTANCE instance,
      __in          JET_HANDLE hfFile,
      __out         void* pv,
      __in          unsigned long cb,
      __out_opt     unsigned long* pcb
    );

Parámetros

instance

Instancia que se va a usar para una llamada API determinada.

Tenga en cuenta que para Windows 2000, la variante de API que acepta este parámetro no está disponible porque solo se admite una instancia. El uso de esta instancia global está implícito en este caso.

Para Windows XP y versiones posteriores, puedes llamar a la variante de API que no acepta este parámetro solo cuando el motor está en modo heredado (modo de compatibilidad de Windows 2000) en casos en los que solo se admite una instancia. De lo contrario, se producirá un error en la operación y se devolverá el error JET_errRunningInMultiInstanceMode.

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.

Pcb

Cantidad real de datos de archivo recuperados.

Valor devuelto

Esta función facilita el retorno de los tipos de datos de JET_ERR definidos en la API extensible storage Engine (ESE). Para obtener más información sobre los errores de JET, vea Extensible Storage Engine Errors and Error Handling Parameters.

Código de retorno	Significado
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 la función JetStopService . Este error solo lo devolverá Windows XP y versiones posteriores de Windows.
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 la función 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. Este error solo lo devolverá Windows XP y versiones posteriores de Windows.
JET_errInvalidParameter	Uno de los parámetros especificados contenía un valor inesperado o un valor que no tenía sentido cuando se combinaba con el valor de otro parámetro. Esto puede ocurrir para la función JetReadFileInstance cuando se produce cualquiera de las siguientes acciones: El identificador de instancia especificado no es válido. Windows XP y versiones posteriores de Windows. 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 de Windows. 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 la función JetReadFileInstance para el identificador especificado. Windows XP y versiones posteriores de Windows.
JET_errLogReadVerifyFailure	Error en la operación porque se detectaron daños en los datos irrecuperables al leer un archivo de registro de transacciones. Este error solo lo devolverá Windows XP y versiones posteriores de Windows.
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 esta sesión aún no se ha inicializado.
JET_errReadVerifyFailure	Error en la operación porque se detectaron daños en los datos irrecuperables 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_errRestoreInProgress	No es posible completar la operación porque hay una operación de restauración en curso en la instancia asociada a esta sesión.
JET_errRunningInMultiInstanceMode	Error en la operación porque se intentó usar el motor en modo heredado (modo de compatibilidad de Windows 2000) en un caso en el que solo se admite una instancia, pero ya existen varias instancias.
JET_errTermInProgress	No es posible completar la operación porque se está cerrando la instancia asociada a esta 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 actual. En Windows XP y versiones posteriores de Windows, 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 la función JetReadFileInstance realizada mediante un identificador que ya ha devuelto todos los datos del archivo subyacente (por ejemplo, si 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.

Debe usar un búfer de salida grande para maximizar el rendimiento de la copia de seguridad. Es posible que tenga que experimentar para encontrar el equilibrio óptimo entre el consumo de recursos y el rendimiento de una situación determinada. En cualquier caso, el búfer de salida no debe ser inferior a 64 KB. El puntero que se pasa a JetReadFileInstance debe alinearse con un límite de página de memoria (4 KB o 8 KB). Para ello, llame a la función VirtualAlloc .

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

Si ha configurado una instancia determinada de modo que la limpieza de páginas de base de datos esté habilitada (consulte el parámetro JET_paramCircularLog en Parámetros del sistema), los datos eliminados se quitarán de la base de datos como un efecto secundario de una llamada a JetReadFileInstance 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 había 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 los casos de daños en los datos normalmente se detectan por primera vez durante la copia de seguridad de streaming. Esto se debe a que 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, debido a la cantidad de datos recuperados por la copia de seguridad y la velocidad a la que se recuperan esos datos.

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, las instancias de estos datos dañados se han originado en orígenes distintos del propio motor de base de datos.

Requisitos

Requisito	Value
Remoto	Requiere Windows Vista o Windows XP.
Servidor	Requiere Windows Server 2008 o Windows Server 2003.
Encabezado	Se declara en Esent.h.
Biblioteca	Usa ESENT.lib.
Archivo DLL	Requiere ESENT.dll.

Consulte también

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFileInstance
JetStopService
Parámetros del sistema