次の方法で共有

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 呼び出しに使用するインスタンス。

Windows 2000 では、1 つのインスタンスのみがサポートされているため、このパラメーターを受け入れる API バリアントは使用できません。 この場合、この 1 つのグローバル インスタンスの使用が暗黙的に示されます。

Windows XP 以降のリリースでは、1 つのインスタンスのみがサポートされている場合に、エンジンがレガシ モード (Windows 2000 互換モード) の場合にのみ、このパラメーターを受け入れない API バリアントを呼び出すことができます。 それ以外の場合、操作は失敗し、JET_errRunningInMultiInstanceModeエラーが返されます。

hfFile

読み取るファイルのハンドル。

pv

ファイル データを受信する出力バッファー。

cb

出力バッファーの最大サイズ (バイト単位)。

Pcb

取得されたファイル データの実際の量。

戻り値

この関数は、拡張可能記憶域エンジン (ESE) API で定義されている JET_ERR データ型の戻りを容易にします。 JET エラーの詳細については、「 記憶域エンジンの拡張可能エラー 」および「 エラー処理パラメーター」を参照してください。

リターン コード

意味

JET_errSuccess

操作は正常に完了しました。

JET_errBackupAbortByServer

JetStopService 関数の呼び出しによって現在の外部バックアップが中止されたため、操作は失敗しました。 このエラーは、Windows XP 以降の Windows バージョンでのみ返されます。

JET_errClientRequestToStopJetService

JetStopService 関数の呼び出しの結果、セッションに関連付けられたインスタンス上のすべてのアクティビティが停止したため、操作を完了することはできません。

JET_errInstanceUnavailable

セッションに関連付けられているインスタンスで、そのデータの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了することはできません。 このエラーは、Windows XP 以降の Windows バージョンでのみ返されます。

JET_errInvalidParameter

指定されたパラメーターの 1 つに、予期しない値または別のパラメーターの値と組み合わせると意味のない値が含まれていました。 これは、次のいずれかが発生した場合に JetReadFileInstance 関数で発生する可能性があります。

  • 指定されたインスタンス ハンドルが無効です。 Windows XP 以降の Windows バージョン。

  • 出力バッファー サイズは、データベース ページ サイズ (JET_paramDatabasePageSize) の倍数ではありません。 Windows XP 以降の Windows バージョン。

  • 出力バッファー サイズは 3 つのデータベース ページ (JET_paramDatabasePageSize) よりも小さく、指定されたハンドルに対する JetReadFileInstance 関数の最初の呼び出しです。 Windows XP 以降の Windows バージョン。

JET_errLogReadVerifyFailure

トランザクション ログ ファイルの読み取り中に回復不可能なデータ破損が検出されたため、操作は失敗しました。 このエラーは、Windows XP 以降の Windows バージョンでのみ返されます。

JET_errNoBackup

外部バックアップが進行中でないため、操作は失敗しました。

JET_errNotInitialized

このセッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。

JET_errReadVerifyFailure

データベース ファイルまたはデータベース パッチ ファイルからデータベース ページを読み取っている間に回復不可能なデータ破損が検出されたため、操作が失敗しました。

JET_errRestoreInProgress

このセッションに関連付けられているインスタンスで復元操作が進行中のため、操作を完了できません。

JET_errRunningInMultiInstanceMode

1 つのインスタンスのみがサポートされているが、複数のインスタンスが既に存在する場合に、レガシ モード (Windows 2000 互換モード) でエンジンを使用しようとしたため、操作が失敗しました。

JET_errTermInProgress

このセッションに関連付けられているインスタンスがシャットダウンされているため、操作を完了できません。

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

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

解説

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

バックアップ パフォーマンスを最大化するには、大きな出力バッファーを使用する必要があります。 特定の状況でリソース消費とスループットの最適なトレードオフを見つけるために、実験が必要になる場合があります。 いずれの場合も、出力バッファーは 64 KB 以下にする必要があります。 JetReadFileInstance に渡すポインターは、メモリ ページ境界 (4 KB または 8 KB) に揃える必要があります。 これを行うには、 VirtualAlloc 関数を呼び出します。

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

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

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

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

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

必要条件

要件 値

クライアント

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
システム パラメーター