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 |
指定されたパラメーターの 1 つに予期しない値が含まれていたか、別のパラメーターの値と組み合わせたときに意味のない値が含まれていました。 これは、次の場合に JetReadFile で 発生する可能性があります。
|
JET_errNoBackup |
外部バックアップが進行中でないため、操作は失敗しました。 |
JET_errNotInitialized |
セッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。 |
JET_errReadVerifyFailure |
データベース ファイルまたはデータベース パッチ ファイルからデータベース ページを読み取っている間に、回復不可能なデータの破損が検出されたため、操作に失敗しました。 |
JET_errLogReadVerifyFailure |
トランザクション ログ ファイルの読み取り中に回復不可能なデータ破損が検出されたため、操作に失敗しました。 このエラーは、Windows XP 以降のリリースでのみ返されます。 |
JET_errRestoreInProgress |
セッションに関連付けられているインスタンスで復元操作が進行中のため、操作を完了できません。 |
JET_errRunningInMultiInstanceMode |
実際には複数のインスタンスが既に存在する場合、1 つのインスタンスのみがサポートされているレガシ モード (Windows 2000 互換モード) でエンジンを使用しようとしたため、操作は失敗しました。 |
JET_errTermInProgress |
セッションに関連付けられているインスタンスがシャットダウンされているため、操作を完了できません。 |
成功すると、ファイルからのデータの次のチャンクが出力バッファーに読み込まれます。 取得された実際のバイト数も返されます。 次の読み取りが行われるファイル オフセットは、この量だけ進められます。
失敗した場合、出力バッファーの状態は未定義です。 このエラーにより、インスタンスのバックアップ プロセス全体が取り消されます。 Windows XP 以降のリリースでは、データベース ファイルの読み取り中にエラーが発生した場合、バックアップは取り消されません。 ただし、そのデータベース ファイルのバックアップは引き続き取り消され、対応するハンドルは自動的に閉じられます。
解説
基になるファイル内のすべてのデータを既に返しているハンドルを使用した JetReadFile の呼び出し (以前の呼び出しで出力バッファーのサイズより少ないバイト数が返された場合など) は常に成功しますが、0 バイトのデータが返されます。
バックアップ パフォーマンスを最大化するには、大きな出力バッファーを使用する必要があります。 特定の状況でリソース消費とスループットの間の適切なトレードオフを見つけるために、いくつかの実験が必要になる場合があります。 いずれの場合も、出力バッファーは 64 KB 以下にする必要があります。
同じファイル ハンドルを使用した JetReadFile への複数の同時呼び出しはサポートされていません。 つまり、同じファイルに対して読み取りを同時に行うために複数のバッファーをキューに登録して、高いシーケンシャル スループットを実現することはできません。 代わりに、1 つの大きなバッファーを使用する必要があります。
データベース ページスクラブが有効になるようにインスタンスが構成されている場合 (「システム パラメーター」の「JET_paramZeroDatabaseDuringBackup」を参照)、データベース ファイルに対する JetReadFile の呼び出しの副作用として、削除されたデータがデータベースから削除されます。
バックアップとデータの破損がどのように相互作用するかを理解することは非常に重要です。 データベース エンジンがバックアップ中にデータの破損を検出した場合、影響を受けるデータベースまたはインスタンス全体のバックアップが失敗します。 これは、データ損失から保護することを目的とした意識的な設計上の決定です。 データの破損が存在する場合、データベース エンジンでバックアップの成功が許可された場合は、古い、中断されていないバックアップが結果として破棄される可能性があります。 このバックアップを復元し、そのデータベースに対するすべてのトランザクション ログ ファイルを再生することで、ライブ インスタンスのデータ破損を修正できるため、これは残念なことです。 このゼロ データ損失シナリオでは、循環ログが有効になっていないことを前提とします (「システム パラメーター」の「JET_paramCircularLog」を参照してください)。
また、データの破損が存在する場合、ストリーミング バックアップが最初に検出される可能性が最も高い場所であることを理解することも重要です。 これは、ストリーミング バックアップが、データベース ファイルのすべての単一ページを定期的にスキャンする唯一のプロセスであるためです。 また、断続的なデータ破損エラーによって明らかにされるハードウェア障害の早期兆候を検出する最初のプロセスは、ストリーミング バックアップになる可能性があります。 これは、バックアップによって取得されるデータの量と、それが取得される速度が原因です。
データの破損は、ブロック チェックサムを使用してデータベース エンジンによって検出されます。 これらのチェックサムは、データベース ページの書き込みの直前に設定され、読み取られたデータベース ページで検証されます。 このスキームにより、データベース エンジンは、ある時点でデータが破損したと判断できますが、データベース エンジンがその破損の原因を特定することはできません。 これまで、このような破損の主な原因は、データベース エンジン自体以外のソースから発生していることが判明しました。
必要条件
| 要件 | 値 |
|---|---|
Client |
Windows Vista、Windows XP、または Windows 2000 Professional が必要です。 |
[サーバー] |
Windows Server 2008、Windows Server 2003、または Windows 2000 Server が必要です。 |
Header |
Esent.h で宣言されています。 |
Library |
ESENT.lib を使用します。 |
[DLL] |
ESENT.dllが必要です。 |
参照
JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFile
JetStopService
システム パラメーター