Функция JetReadFileInstance
Применимо к: Windows | Windows Server
Функция JetReadFileInstance
Функция JetReadFileInstance извлекает содержимое файла, открытого с помощью функции JetOpenFileInstance .
Windows XP: JetReadFileInstance появился в 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
);
Параметры
Экземпляр
Экземпляр, используемый для определенного вызова API.
Обратите внимание, что для Windows 2000 вариант API, который принимает этот параметр, недоступен, так как поддерживается только один экземпляр. В данном случае подразумевается использование этого глобального экземпляра.
Для Windows XP и более поздних версий можно вызвать вариант API, который не принимает этот параметр, только если подсистема находится в устаревшем режиме (режим совместимости с Windows 2000) в случаях, когда поддерживается только один экземпляр. В противном случае операция завершится сбоем и вернет ошибку JET_errRunningInMultiInstanceMode.
hfFile
Дескриптор считываемого файла.
Pv
Выходной буфер, который будет принимать данные файла.
Cb
Максимальный размер выходного буфера (в байтах).
Pcb
Фактический объем полученных данных файла.
Возвращаемое значение
Эта функция упрощает возврат любых JET_ERR типов данных, определенных в API расширяемого модуля хранения данных (ESE). Дополнительные сведения об ошибках JET см. в разделах Ошибки подсистемы расширяемого хранилища и Параметры обработки ошибок.
Код возврата |
Значение |
|---|---|
JET_errSuccess |
Операция выполнена успешно. |
JET_errBackupAbortByServer |
Операция завершилась сбоем, так как текущая внешняя резервная копия была прервана вызовом функции JetStopService . Эта ошибка будет возвращена только в Windows XP и более поздних версиях Windows. |
JET_errClientRequestToStopJetService |
Невозможно выполнить операцию, так как все действия экземпляра, связанного с сеансом, прекратились в результате вызова функции JetStopService . |
JET_errInstanceUnavailable |
Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, столкнулся с неустранимой ошибкой, требующей отмены доступа ко всем данным для защиты целостности этих данных. Эта ошибка будет возвращена только в Windows XP и более поздних версиях Windows. |
JET_errInvalidParameter |
Один из указанных параметров содержал либо непредвиденное значение, либо значение, которое не имело смысла в сочетании со значением другого параметра. Это может произойти для функции JetReadFileInstance при выполнении любого из следующих действий:
|
JET_errLogReadVerifyFailure |
Операция завершилась сбоем, так как при чтении файла журнала транзакций было обнаружено неустранимое повреждение данных. Эта ошибка будет возвращена только в Windows XP и более поздних версиях Windows. |
JET_errNoBackup |
Операция завершилась сбоем, так как внешнее резервное копирование не выполняется. |
JET_errNotInitialized |
Невозможно выполнить операцию, так как экземпляр, связанный с этим сеансом, еще не инициализирован. |
JET_errReadVerifyFailure |
Операция завершилась сбоем, так как при чтении страницы базы данных из файла базы данных или файла исправлений базы данных обнаружено неустранимое повреждение данных. |
JET_errRestoreInProgress |
Невозможно выполнить операцию, так как операция восстановления выполняется на экземпляре, связанном с этим сеансом. |
JET_errRunningInMultiInstanceMode |
Операция завершилась сбоем, так как была предпринята попытка использовать подсистему в устаревшем режиме (режим совместимости с Windows 2000) в случае, когда поддерживается только один экземпляр, но несколько экземпляров уже существуют. |
JET_errTermInProgress |
Невозможно выполнить операцию, так как экземпляр, связанный с этим сеансом, завершает работу. |
При успешном выполнении следующий блок данных из файла будет считываться в выходной буфер. Также будет возвращено фактическое количество извлеченных байтов. Смещение файла, с которым будет выполняться следующее чтение, будет расширено на этот объем.
При сбое состояние выходного буфера не определено. Сбой приведет к отмене всего процесса резервного копирования для текущего экземпляра. В Windows XP и более поздних версиях Windows резервное копирование не будет отменено, если при чтении файла базы данных произошла ошибка. Однако резервная копия этого файла базы данных по-прежнему будет отменена, а соответствующий дескриптор будет автоматически закрыт.
Комментарии
Любой вызов функции JetReadFileInstance , выполненный с помощью дескриптора, который уже вернул все данные в базовом файле (например, если предыдущий вызов возвращал меньше байтов, чем размер выходного буфера), всегда будет выполнен успешно, но возвращает ноль байтов данных.
Для максимальной производительности резервного копирования следует использовать большой выходной буфер. Возможно, вам потребуется поэкспериментировать, чтобы найти оптимальный компромисс между потреблением ресурсов и пропускной способностью для конкретной ситуации. В любом случае выходной буфер не должен быть меньше 64 КБ. Указатель, который передается в JetReadFileInstance , должен быть выровнен по границе страницы памяти (4 КБ или 8 КБ). Это можно сделать, вызвав функцию VirtualAlloc .
Несколько одновременных вызовов JetReadFileInstance , выполненных с помощью одного дескриптора файла, не поддерживаются. Это означает, что невозможно ставить несколько буферов в очередь для параллельного чтения в одном файле, чтобы обеспечить высокую последовательную пропускную способность. Вместо этого следует использовать один большой буфер.
Если вы настроили определенный экземпляр таким образом, чтобы была включена очистка страниц базы данных (см. параметр JET_paramCircularLog в разделе Системные параметры), удаленные данные будут удалены из базы данных как побочный эффект вызова JetReadFileInstance для файла базы данных.
Очень важно понимать, как взаимодействуют резервное копирование и повреждение данных. Если ядро СУБД обнаруживает повреждение данных во время резервного копирования, произойдет сбой резервного копирования затронутой базы данных или всего экземпляра. Это сознательное проектное решение, предназначенное для защиты от потери данных. Если ядро СУБД позволило успешно выполнить резервное копирование при повреждении данных, в результате может быть удалена старая, некорированная резервная копия. Это было бы неудачно, так как после этого можно было бы исправить повреждение данных в активном экземпляре, восстановив эту резервную копию и повторно создав все файлы журнала транзакций в этой базе данных. В этом сценарии с нулевой потерей данных предполагается, что циклическое ведение журнала не включено (см . JET_paramCircularLog в разделе Системные параметры).
Важно также понимать, что случаи повреждения данных обычно впервые обнаруживаются во время потокового резервного копирования. Это связано с тем, что потоковая архивация является единственным процессом, который регулярно сканирует каждую страницу файла базы данных. Кроме того, вполне вероятно, что потоковое резервное копирование будет первым процессом для обнаружения ранних признаков сбоя оборудования, что проявляется периодическими ошибками повреждения данных из-за объема данных, извлекаемых резервной копией, и скорости, с которой эти данные извлекаются.
Повреждение данных обнаруживается ядром СУБД с помощью контрольных сумм блоков. Эти контрольные суммы устанавливаются непосредственно перед записью страницы базы данных и проверяются на странице чтения базы данных. Эта схема позволяет ядру СУБД определить, что данные были повреждены в какой-то момент, но она не позволяет ядру СУБД определить источник этого повреждения. Исторически сложилось так, что экземпляры такого повреждения данных были получены из источников, отличных от самого ядра СУБД.
Требования
| Требование | Значение |
|---|---|
клиент |
Требуется Windows Vista или Windows XP. |
Сервер |
Требуется Windows Server 2008 или Windows Server 2003. |
Заголовок |
Объявляется в Esent.h. |
Библиотека |
Использует ESENT.lib. |
DLL |
Требуется ESENT.dll. |
См. также:
JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFileInstance
JetStopService
Системные параметры