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 エラーの詳細については、「 拡張ストレージ エンジン エラー と エラー処理パラメーター」を参照してください。

成功すると、ファイルからのデータの次のチャンクが出力バッファーに読み込まれます。 取得された実際のバイト数も返されます。 次の読み取りが行われるファイル オフセットは、この量だけ進められます。

失敗した場合、出力バッファーの状態は未定義です。 このエラーにより、インスタンスのバックアップ プロセス全体が取り消されます。 Windows XP 以降のリリースでは、データベース ファイルの読み取り中にエラーが発生した場合、バックアップは取り消されません。 ただし、そのデータベース ファイルのバックアップは引き続き取り消され、対応するハンドルは自動的に閉じられます。

解説

基になるファイル内のすべてのデータを既に返しているハンドルを使用した JetReadFile の呼び出し (以前の呼び出しで出力バッファーのサイズより少ないバイト数が返された場合など) は常に成功しますが、0 バイトのデータが返されます。

バックアップ パフォーマンスを最大化するには、大きな出力バッファーを使用する必要があります。 特定の状況でリソース消費とスループットの間の適切なトレードオフを見つけるために、いくつかの実験が必要になる場合があります。 いずれの場合も、出力バッファーは 64 KB 以下にする必要があります。

同じファイル ハンドルを使用した JetReadFile への複数の同時呼び出しはサポートされていません。 つまり、同じファイルに対して読み取りを同時に行うために複数のバッファーをキューに登録して、高いシーケンシャル スループットを実現することはできません。 代わりに、1 つの大きなバッファーを使用する必要があります。

データベース ページスクラブが有効になるようにインスタンスが構成されている場合 (「システム パラメーター」の「JET_paramZeroDatabaseDuringBackup」を参照)、データベース ファイルに対する JetReadFile の呼び出しの副作用として、削除されたデータがデータベースから削除されます。

バックアップとデータの破損がどのように相互作用するかを理解することは非常に重要です。 データベース エンジンがバックアップ中にデータの破損を検出した場合、影響を受けるデータベースまたはインスタンス全体のバックアップが失敗します。 これは、データ損失から保護することを目的とした意識的な設計上の決定です。 データの破損が存在する場合、データベース エンジンでバックアップの成功が許可された場合は、古い、中断されていないバックアップが結果として破棄される可能性があります。 このバックアップを復元し、そのデータベースに対するすべてのトランザクション ログ ファイルを再生することで、ライブ インスタンスのデータ破損を修正できるため、これは残念なことです。 このゼロ データ損失シナリオでは、循環ログが有効になっていないことを前提とします (「システム パラメーター」の「JET_paramCircularLog」を参照してください)。

また、データの破損が存在する場合、ストリーミング バックアップが最初に検出される可能性が最も高い場所であることを理解することも重要です。 これは、ストリーミング バックアップが、データベース ファイルのすべての単一ページを定期的にスキャンする唯一のプロセスであるためです。 また、断続的なデータ破損エラーによって明らかにされるハードウェア障害の早期兆候を検出する最初のプロセスは、ストリーミング バックアップになる可能性があります。 これは、バックアップによって取得されるデータの量と、それが取得される速度が原因です。

データの破損は、ブロック チェックサムを使用してデータベース エンジンによって検出されます。 これらのチェックサムは、データベース ページの書き込みの直前に設定され、読み取られたデータベース ページで検証されます。 このスキームにより、データベース エンジンは、ある時点でデータが破損したと判断できますが、データベース エンジンがその破損の原因を特定することはできません。 これまで、このような破損の主な原因は、データベース エンジン自体以外のソースから発生していることが判明しました。

必要条件

参照

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFile
JetStopService
システム パラメーター