Поделиться через

Функция JetReadFile

  • Статья

Применимо к: Windows | Windows Server

Функция JetReadFile

Функция JetReadFile извлекает содержимое файла, открытого с помощью JetOpenFile.

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

Параметры

hfFile

Дескриптор считываемого файла.

Pv

Выходной буфер, который будет получать данные файла.

Cb

Максимальный размер выходного буфера в байтах.

pcbActual

Получает фактический объем полученных данных о файлах.

Возвращаемое значение

Эта функция возвращает тип данных JET_ERR с одним из следующих кодов возврата. Дополнительные сведения о возможных ошибках ESE см. в разделах Ошибки подсистемы расширяемого хранилища и Параметры обработки ошибок.

Код возврата

Описание

JET_errSuccess

Операция выполнена успешно.

JET_errBackupAbortByServer

Операция завершилась сбоем, так как текущая внешняя резервная копия была прервана вызовом JetStopService. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.

JET_errClientRequestToStopJetService

Невозможно выполнить операцию, так как все действия экземпляра, связанного с сеансом, прекратились в результате вызова JetStopService.

JET_errInstanceUnavailable

Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, столкнулся с неустранимой ошибкой, требующей отмены доступа ко всем данным для защиты целостности этих данных. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.

JET_errInvalidParameter

Один из предоставленных параметров содержал непредвиденное значение или значение, которое не имело смысла в сочетании со значением другого параметра. Это может произойти для JetReadFile , если:

  • Указанный дескриптор экземпляра недопустим. Windows XP и более поздние выпуски.

  • Размер выходного буфера не кратен размеру страницы базы данных (JET_paramDatabasePageSize). Windows XP и более поздние выпуски.

  • Размер выходного буфера меньше трех страниц базы данных (JET_paramDatabasePageSize), и это первый вызов JetReadFile для указанного дескриптора. Windows XP и более поздние выпуски.

JET_errNoBackup

Операция завершилась сбоем, так как внешнее резервное копирование не выполняется.

JET_errNotInitialized

Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, еще не инициализирован.

JET_errReadVerifyFailure

Операция завершилась сбоем, так как при чтении страницы базы данных из файла базы данных или файла исправлений базы данных обнаружено повреждение невосстановимых данных.

JET_errLogReadVerifyFailure

Операция завершилась сбоем, так как при чтении файла журнала транзакций было обнаружено повреждение невосстановимых данных. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.

JET_errRestoreInProgress

Невозможно выполнить операцию, так как операция восстановления выполняется в экземпляре, связанном с сеансом.

JET_errRunningInMultiInstanceMode

Операция завершилась сбоем, так как была предпринята попытка использовать подсистему в устаревшем режиме (режим совместимости с Windows 2000), где поддерживается только один экземпляр, если на самом деле уже существует несколько экземпляров.

JET_errTermInProgress

Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, завершает работу.

При успешном выполнении следующий фрагмент данных из файла будет считываться в выходной буфер. Также будет возвращено фактическое количество извлеченных байтов. Смещение файла, при котором будет выполняться следующее чтение, будет расширено на этот объем.

При сбое состояние выходного буфера не определено. Сбой приведет к отмене всего процесса резервного копирования экземпляра. В Windows XP и более поздних выпусках резервное копирование не будет отменено, если произошла ошибка при чтении файла базы данных. Однако резервная копия этого файла базы данных по-прежнему будет отменена, а соответствующий дескриптор будет автоматически закрыт.

Комментарии

Любой вызов JetReadFile с помощью дескриптора, который уже вернул все данные в базовом файле (например, предыдущий вызов вернул меньше байтов, чем размер выходного буфера), всегда будет успешным, но возвращает ноль байт данных.

Для максимальной производительности резервного копирования следует использовать большой выходной буфер. Для поиска правильного компромисса между потреблением ресурсов и пропускной способностью для конкретной ситуации может потребоваться некоторое экспериментирование. Размер выходного буфера в любом случае не должен превышать 64 КБ.

Несколько одновременных вызовов JetReadFile с использованием одного дескриптора файла не поддерживаются. Это означает, что невозможно ставить в очередь несколько буферов для чтения одновременно с тем же файлом, чтобы обеспечить высокую последовательную пропускную способность. Вместо этого следует использовать один большой буфер.

Если экземпляр настроен таким образом, что включена очистка страниц базы данных (см. JET_paramZeroDatabaseDuringBackup в системных параметрах), удаленные данные будут удалены из базы данных в качестве побочного эффекта вызова JetReadFile к файлу базы данных.

Очень важно понимать, как взаимодействуют резервные копии и повреждение данных. Если ядро СУБД обнаруживает повреждение данных во время резервного копирования, это приведет к сбою резервного копирования затронутой базы данных или всего экземпляра. Это сознательное проектное решение, предназначенное для защиты от потери данных. Если ядро СУБД позволило успешно выполнить резервное копирование при повреждении данных, то в результате этого может быть удалена более старая, некорруцированная резервная копия. Это было бы неудачно, так как можно было бы исправить повреждение данных в динамическом экземпляре, восстановив эту резервную копию и повторно создав все файлы журнала транзакций в этой базе данных. Этот сценарий нулевой потери данных предполагает, что циклическое ведение журнала не включено (см . JET_paramCircularLog в системных параметрах).

Также важно понимать, что при наличии повреждения данных потоковая архивация будет наиболее вероятным местом, где она будет обнаружена. Это связано с тем, что потоковая архивация является единственным процессом, который регулярно сканирует каждую страницу файла базы данных. Кроме того, вероятно, что потоковое резервное копирование будет первым процессом для обнаружения ранних признаков сбоя оборудования, что проявляется периодическими ошибками повреждения данных. Это связано с объемом данных, извлекаемых резервным копированием, а также скоростью, с которой они извлекаются.

Повреждение данных обнаруживается ядром СУБД с помощью контрольных сумм блоков. Эти контрольные суммы устанавливаются непосредственно перед записью страницы базы данных и проверяются на чтение страницы базы данных. Эта схема позволяет ядру СУБД определить, что данные были повреждены в какой-то момент, но не позволяет ядру СУБД определить источник этого повреждения. Исторически сложилось так, что основной причиной такого повреждения были источники, отличные от самого ядра СУБД.

Требования

Требование Значение

Клиент

Требуется Windows Vista, Windows XP или Windows 2000 Профессиональная.

Сервер

Требуется Windows Server 2008, Windows Server 2003 или Windows 2000 Server.

Верхняя часть

Объявлено в Esent.h.

Библиотека

Используйте ESENT.lib.

DLL

Требуется ESENT.dll.

См. также:

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFile
JetStopService
Системные параметры