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
);
매개 변수
instance
특정 API 호출에 사용할 instance.
Windows 2000의 경우 instance 하나만 지원되므로 이 매개 변수를 허용하는 API 변형을 사용할 수 없습니다. 이 하나의 전역 instance 사용하는 것은 이 경우에 암시됩니다.
Windows XP 이상 릴리스의 경우 엔진이 레거시 모드(Windows 2000 호환 모드)에 있을 때만 이 매개 변수를 허용하지 않는 API 변형을 호출할 수 있습니다(instance 하나만 지원되는 경우). 그렇지 않으면 작업이 실패하고 JET_errRunningInMultiInstanceMode 오류가 반환됩니다.
hfFile
읽을 파일의 핸들입니다.
태양광 발전
파일 데이터를 받을 출력 버퍼입니다.
Cb
출력 버퍼의 최대 크기(바이트)입니다.
Pcb
검색된 파일 데이터의 실제 양입니다.
반환 값
이 함수는 ESE(Extensible Storage Engine) API에 정의된 모든 JET_ERR 데이터 형식의 반환을 용이하게 합니다. JET 오류에 대한 자세한 내용은 확장 가능한 스토리지 엔진 오류 및 오류 처리 매개 변수를 참조하세요.
반환 코드 |
의미 |
|---|---|
JET_errSuccess |
작업이 성공적으로 완료되었습니다. |
JET_errBackupAbortByServer |
현재 외부 백업이 JetStopService 함수 호출로 중단되어 작업이 실패했습니다. 이 오류는 Windows XP 이상 Windows 버전에서만 반환됩니다. |
JET_errClientRequestToStopJetService |
JetStopService 함수 호출로 인해 세션과 연결된 instance 모든 작업이 중단되었으므로 작업을 완료할 수 없습니다. |
JET_errInstanceUnavailable |
세션과 연결된 instance 해당 데이터의 무결성을 보호하기 위해 모든 데이터에 대한 액세스를 해지해야 하는 심각한 오류가 발생하여 작업을 완료할 수 없습니다. 이 오류는 Windows XP 이상 Windows 버전에서만 반환됩니다. |
JET_errInvalidParameter |
지정된 매개 변수 중 하나에 예기치 않은 값 또는 다른 매개 변수의 값과 결합할 때 의미가 없는 값이 포함되어 있습니다. 이 문제는 다음 중 어느 것이라도 발생할 때 JetReadFileInstance 함수에 대해 발생할 수 있습니다.
|
JET_errLogReadVerifyFailure |
트랜잭션 로그 파일을 읽는 동안 복구할 수 없는 데이터 손상이 감지되어 작업이 실패했습니다. 이 오류는 Windows XP 이상 Windows 버전에서만 반환됩니다. |
JET_errNoBackup |
외부 백업이 진행 중이 아니므로 작업이 실패했습니다. |
JET_errNotInitialized |
이 세션과 연결된 instance 아직 초기화되지 않았기 때문에 작업을 완료할 수 없습니다. |
JET_errReadVerifyFailure |
데이터베이스 파일 또는 데이터베이스 패치 파일에서 데이터베이스 페이지를 읽는 동안 복구할 수 없는 데이터 손상이 감지되어 작업이 실패했습니다. |
JET_errRestoreInProgress |
이 세션과 연결된 instance 복원 작업이 진행 중이므로 작업을 완료할 수 없습니다. |
JET_errRunningInMultiInstanceMode |
하나의 instance 지원되지만 여러 인스턴스가 이미 있는 경우 레거시 모드(Windows 2000 호환 모드)에서 엔진을 사용하려고 했기 때문에 작업이 실패했습니다. |
JET_errTermInProgress |
이 세션과 연결된 instance 종료 중이므로 작업을 완료할 수 없습니다. |
성공하면 파일의 다음 데이터 청크가 출력 버퍼로 읽혀질 것입니다. 검색된 실제 바이트 수도 반환됩니다. 다음 읽기가 수행되는 파일 오프셋은 이 양만큼 고급입니다.
실패 시 출력 버퍼의 상태가 정의되지 않습니다. 이 오류로 인해 현재 instance 대한 전체 백업 프로세스가 취소됩니다. Windows XP 이상 Windows 버전에서는 데이터베이스 파일을 읽는 동안 오류가 발생한 경우 백업이 취소되지 않습니다. 그러나 해당 데이터베이스 파일의 백업은 여전히 취소되고 해당 핸들은 자동으로 닫힙니다.
설명
기본 파일의 모든 데이터를 이미 반환한 핸들(예: 이전 호출이 출력 버퍼 크기보다 더 적은 바이트를 반환한 경우)을 사용하여 만든 JetReadFileInstance 함수에 대한 모든 호출은 항상 성공하지만 0바이트의 데이터를 반환합니다.
백업 성능을 최대화하려면 큰 출력 버퍼를 사용해야 합니다. 특정 상황에서 리소스 사용량과 처리량 간의 최적 절충을 찾기 위해 실험해야 할 수 있습니다. 어쨌든 출력 버퍼는 64KB보다 작지 않아야 합니다. JetReadFileInstance에 전달하는 포인터는 메모리 페이지 경계(4KB 또는 8KB)에 맞춰야 합니다. VirtualAlloc 함수를 호출하여 이 작업을 수행할 수 있습니다.
동일한 파일 핸들을 사용하여 만든 JetReadFileInstance 에 대한 여러 동시 호출은 지원되지 않습니다. 즉, 높은 순차적 처리량을 달성하기 위해 동일한 파일에 대해 동시 읽기를 위해 여러 버퍼를 큐에 대기할 수 없습니다. 대신 단일 큰 버퍼를 사용해야 합니다.
데이터베이스 페이지 스크러빙이 사용하도록 설정되도록 특정 instance 구성한 경우(시스템 매개 변수의 JET_paramCircularLog 매개 변수 참조) 삭제된 데이터는 데이터베이스 파일에 대한 JetReadFileInstance 호출의 부작용으로 데이터베이스에서 제거됩니다.
백업 및 데이터 손상이 상호 작용하는 방식을 이해하는 것이 매우 중요합니다. 데이터베이스 엔진이 백업 중에 데이터 손상을 감지하면 영향을 받는 데이터베이스 또는 전체 instance 백업에 실패합니다. 이는 데이터 손실로부터 보호하기 위한 의식적인 디자인 결정입니다. 데이터베이스 엔진에서 데이터 손상이 발생한 백업이 성공하도록 허용한 경우 이전의 손상되지 않은 백업은 결과적으로 삭제될 수 있습니다. 그러면 해당 백업을 복원하고 해당 데이터베이스에 대해 모든 트랜잭션 로그 파일을 재생하여 라이브 instance 데이터 손상을 해결할 수 있기 때문에 이는 불행한 일입니다. 이 제로 데이터 손실 시나리오는 순환 로깅이 사용되지 않는다고 가정합니다(시스템 매개 변수의 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
시스템 매개 변수
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기