JetSetLS 関数

適用対象: Windows |Windows Server

JetSetLS 関数

JetSetLS 関数を使用すると、アプリケーションはローカル ストレージと呼ばれるコンテキスト ハンドルをカーソルまたはそのカーソルに関連付けられたテーブルに関連付けることができます。 このコンテキスト ハンドルは、カーソルまたはテーブルに関連付けられている補助データを格納するためにアプリケーションで使用できます。 コンテキスト ハンドルを解放する必要がある場合、アプリケーションは後でランタイム コールバックを使用して通知されます。 これにより、動的に割り当てられた状態をカーソルまたはテーブルに関連付けることができます。

Windows XP:JetSetLS は Windows XP で導入されています。

    JET_ERR JET_API JetSetLS(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_LS ls,
      __in          JET_GRBIT grbit
    );

パラメーター

sesid

この呼び出しに使用するセッション。

tableid

この呼び出しに使用するカーソル。

ls

カーソルまたはテーブルに関連付けるコンテキスト ハンドル。

JET_bitLSResetを指定すると、このパラメーターの実際の値は無視され、JET_LSNilが使用されます。

grbit

この呼び出しに使用するオプションを含むビットのグループ。これには、次の 0 個以上が含まれます。

値	説明
JET_bitLSCursor	このオプションは、コンテキスト ハンドルを指定されたカーソルに関連付ける必要があることを示します。 JET_bitLSCursorもJET_bitLSTableも指定されていない場合は、JET_bitLSCursorが推定されます。 JET_bitLSTableでこのオプションを使用することは違法です。 この操作が試行されると、JET_errInvalidgrbitで操作が失敗します。
JET_bitLSReset	このオプションは、指定したコンテキスト ハンドルを無視し、選択したオブジェクトのコンテキスト ハンドルをJET_LSNilにリセットする必要があることを示します。 このアクションでは、選択したオブジェクトのコンテキスト ハンドルの以前の値をクリーンアップするためのコールバックは発生しないことに注意してください。 前のコンテキスト ハンドルの適切なクリーンアップは、 JET_bitLSResetで JetGetLS を 使用して実現できます。 詳細については、「 JetGetLS 」を参照してください。
JET_bitLSTable	このオプションは、指定されたカーソルに関連付けられたテーブルにコンテキスト ハンドルを関連付ける必要があることを示します。 このオプションをJET_bitLSCursorで使用することは違法です。 この操作が試行されると、JET_errInvalidgrbitで操作が失敗します。

戻り値

この関数は、次のいずれかのリターン コードを使用して 、JET_ERR データ型を返します。 考えられる ESE エラーの詳細については、「 拡張可能ストレージ エンジン エラー 」および「 エラー処理パラメーター」を参照してください。

リターン コード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errClientRequestToStopJetService	JetStopService の呼び出しの結果、セッションに関連付けられたインスタンス上のすべてのアクティビティが停止したため、操作を完了することはできません。
JET_errInvalidgrbit	要求されたオプションの 1 つが無効であるか、正しく使用されていないか、実装されていませんでした。 これは、JET_bitLSCursorとJET_bitLSTableの両方が指定されている場合に 、JetSetLS で 発生する可能性があります。
JET_errInstanceUnavailable	セッションに関連付けられているインスタンスで致命的なエラーが発生したため、操作を完了できません。このエラーでは、そのデータの整合性を保護するためにすべてのデータへのアクセスを取り消す必要があります。 このエラーは、Windows XP 以降のリリースでのみ返されます。
JET_errLSAlreadySet	指定されたコンテキスト ハンドルは、既にコンテキスト ハンドルが関連付けられているため、要求されたオブジェクトに関連付けられません。
JET_errLSCallbackNotSpecified	セッションに関連付けられているインスタンスに対してランタイム コールバックが構成されていないため、指定されたコンテキスト ハンドルを要求されたオブジェクトに関連付けませんでした。
JET_errNotInitialized	セッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errRestoreInProgress	セッションに関連付けられているインスタンスで復元操作が進行中であるため、操作を完了できません。
JET_errTermInProgress	セッションに関連付けられているインスタンスがシャットダウンされているため、操作を完了できません。

成功すると、指定されたコンテキスト ハンドルが要求されたオブジェクトに正常に関連付けられました。 データベースの状態は変更されません。

失敗した場合、要求されたオブジェクトの状態に対する変更は行われません。 データベースの状態は変更されません。

解説

カーソルまたはテーブルのローカル ストレージは、揮発性キャッシュとして表示する必要があります。 アプリケーションでは、最初に JetGetLS を使用してコンテキスト ハンドルを取得する必要があります。 値が設定されていない (つまりJET_LSNil) 場合、アプリケーションは新しいコンテキストを作成し、 JetSetLS を使用してキャッシュに読み込む必要があります。 アプリケーションは、JET_bitLSResetを使用して JetGetLS の呼び出しを使用してキャッシュを消去できます。 データベース エンジンがキャッシュを消去すると、ランタイム コールバックが生成され、アプリケーションでそのコンテキストをクリーンアップできるようになります。 コールバック型は、カーソルに関連付けられたコンテキスト ハンドルに対してJET_cbtypFreeCursorLSされ、テーブルに関連付けられたコンテキスト ハンドルのJET_cbtypFreeTableLSされます。 どちらの場合も、コンテキスト ハンドルは pvArg1 として渡されます。 詳細については、「 JET_CALLBACK 」を参照してください。

ローカル ストレージを使用する前に、指定されたセッションに関連付けられているインスタンスに対してランタイム コールバックを適切に構成する必要があります。 このコールバックは、 JetSetSystemParameter と JET_paramRuntimeCallbackを使用して設定できます。 詳細については、「システム パラメーター」の JetSetSystemParameter と JET_paramRuntimeCallback に関するページを参照してください。

要件

要件	値
Client	Windows Vista または Windows XP が必要です。
[サーバー]	Windows Server 2008 または Windows Server 2003 が必要です。
Header	Esent.h で宣言されています。
Library	ESENT.lib を使用します。
[DLL]	ESENT.dllが必要です。

参照

JET_CALLBACK
JET_ERR
JET_GRBIT
JET_LS
JET_SESID
JET_TABLEID
JetGetLS
JetSetSystemParameter
システム パラメーター