JetGetBookmark 関数

適用対象: Windows |Windows サーバー

JetGetBookmark 関数

JetGetBookmark 関数は、カーソルの現在位置にあるインデックス エントリに関連付けられているレコードのブックマークを取得します。 このブックマークを使用すると、 JetGoToBookmark を使用してそのカーソルを同じレコードに戻すことができます。

    JET_ERR JET_API JetGetBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual
    );

パラメーター

sesid

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

tableid

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

pvBookmark

ブックマークを受信する出力バッファー。

cbMax

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

pcbActual

ブックマークの実際のサイズ (バイト単位)。

このパラメーターが NULL の 場合、ブックマークの実際のサイズは返されません。

出力バッファーが小さすぎる場合でも、ブックマークの実際のサイズが返されます。 つまり、この数は出力バッファーのサイズよりも大きくなります。

戻り値

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

リターン コード

説明

JET_errSuccess

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

JET_errBufferTooSmall

操作は正常に完了しましたが、出力バッファーが小さすぎてブックマーク全体を受信できませんでした。 出力バッファーには、適切な数のブックマークが格納されています。 要求された場合は、ブックマークの実際のサイズも返されます。

JET_errClientRequestToStopJetService

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

JET_errInstanceUnavailable

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

Windows XP: この戻り値は、Windows XP で導入されます。

JET_errNoCurrentRecord

カーソルはレコード上に配置されません。 これはさまざまな理由から起こります。 たとえば、現在のインデックスの最後のレコードの後にカーソルが配置されている場合に発生します。

JET_errNotInitialized

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

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

同じセッションを複数のスレッドに同時に使用することはできません。

Windows XP: この戻り値は、Windows XP で導入されます。

JET_errTermInProgress

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

この関数が成功すると、カーソルの現在位置にあるインデックス エントリに関連付けられているレコードのブックマークが出力バッファーに返されます。 データベースの状態に対する変更は行われません。

この関数が失敗した場合、JET_errBufferTooSmallが返されない限り、出力バッファーの状態とブックマークの実際のサイズは未定義になります。 JET_errBufferTooSmallが返された場合、出力バッファーには、指定されたスペースに収まるブックマークと同じ数のブックマークが含まれており、ブックマークの実際のサイズが正確になります。 データベースの状態に対する変更は行われません。

解説

ブックマークは通常、データの不透明なチャンクとして扱う必要があります。 このデータの内部構造を悪用しようとしないでください。 ただし、次の条件はすべての ESENT ブックマークに当てはまります。

  • ブックマークは、特定のテーブル内のレコードを一意に識別します。

  • レコードのブックマークは、そのレコードの有効期間中は変更されません。

  • レコードのブックマークは、そのレコードを含むテーブルのプライマリ インデックス上のそのレコードのキーと同じです。 そのテーブルに対してプライマリ インデックスが定義されていない場合、データベース エンジンはレコードの独自のブックマークを作成します。

  • ブックマークは、memcmp 関数を使用して相互に比較して、ソース レコードのテーブルに対するプライマリ インデックスでの相対順序付けを確立できます。 そのテーブルに対してプライマリ インデックスが定義されていない場合、そのテーブルのブックマークの相対順序を使用することは意味がありません。

  • 異なるテーブルのレコードのブックマークを相互に比較することは意味がありません。

  • ブックマークは、Vista より前の長さが常にJET_cbBookmarkMost (256) バイト以下Windows。

Windows Vista: Windows Vista 以降のリリースでは、ブックマークはJET_cbBookmarkMost (256) バイトを超える場合があります。 ブックマークの最大サイズは、JET_paramKeyMost + 1 の現在の値と等しくなります。

要件

要件

Client

Vista、Windows XP、または 2000 Professional Windows Windows必要です。

[サーバー]

Windows Server 2008、Windows Server 2003、または Windows 2000 Server が必要です。

ヘッダー

Esent.h で宣言されています。

Library

ESENT.lib を使用します。

[DLL]

ESENT.dllが必要です。

参照

JET_ERR
JET_SESID
JET_TABLEID
JetGoToBookmark
JetStopService
memcmp