ホーム › Storage.Jet › JetSetCurrentIndex4W

JetSetCurrentIndex4W

関数

インデックスIDを用いて現在のインデックスを設定する(Unicode版)。

DLLESENT.dll文字セットUnicode (-W)呼出規約winapi

シグネチャ

// ESENT.dll  (Unicode / -W)
#include <windows.h>

INT JetSetCurrentIndex4W(
    JET_SESID sesid,
    JET_TABLEID tableid,
    WORD* szIndexName,   // optional
    JET_INDEXID* pindexid,   // optional
    DWORD grbit,
    DWORD itagSequence
);

パラメーター

名前	型	方向	説明
sesid	JET_SESID	in	現在インデックス設定を行うセッションのJET_SESIDハンドル。
tableid	JET_TABLEID	in	対象テーブルのカーソルハンドル。
szIndexName	WORD*	inoptional	有効化するインデックス名を指す終端付きUnicode文字列ポインタ。pindexid使用時はNULL可。
pindexid	JET_INDEXID*	inoptional	高速指定用のインデックスIDを格納したJET_INDEXID構造体ポインタ。名前検索を回避できる。NULL可。
grbit	DWORD	in	移動動作を制御するビットフラグ。カーソル位置決め方法を指定する。
itagSequence	DWORD	in	多値インデックスで位置決めに用いるタグシーケンス番号。1始まりで指定する。

戻り値の型: INT

公式ドキュメント

JetSetCurrentIndex4 関数は、カーソルの現在のインデックスを設定するために使用します。カーソルの現在のインデックスは、レコードを公開するために使用するインデックスエントリのセットを選択することによって、テーブル内のどのレコードがそのカーソルから参照できるか、およびそれらがどのような順序で現れるかを定義します。

戻り値

この関数は JET_ERR データ型を返し、その値は次のいずれかの戻りコードです。発生し得る ESE エラーの詳細については、「Extensible Storage Engine Errors」および「Error Handling Parameters」を参照してください。

戻りコード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errBadItagSequence	JET_bitNoMove オプションを指定してセカンダリインデックスが選択されていますが、新しいインデックスの定義における最初の複数値キー列に、指定されたシーケンス番号に対応する値がありません。
JET_errClientRequestToStopJetService	JetStopService の呼び出しの結果、そのセッションに関連付けられたインスタンス上のすべての処理が停止しているため、操作を完了できません。
JET_errInstanceUnavailable	そのセッションに関連付けられたインスタンスで、データの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errInvalidIndexId	インデックス ID の内容が無効であるか、有効期限が切れているため、更新する必要があります。JetSetCurrentIndex4 では、次の場合にこのエラーが発生することがあります。 pindexid->cbStruct が想定されたサイズではない (Windows Server 2003 以降のリリース)。インデックス ID を取得してからエンジンがシャットダウンされた。そのインデックス ID に対応するインデックスを含むテーブルを参照しているカーソルがすべて閉じられ、エンジンがそのインデックスの定義をスキーマキャッシュから破棄した。インデックス ID が、誤ったテーブルで開かれたカーソルと共に使用されている。インデックスが削除されたか、まだそのセッションから参照できない。
JET_errInvalidName	指定されたオブジェクト名のいずれかが無効でした。すべてのオブジェクト名は同じ規則に従う必要があります。規則は次のとおりです。オブジェクト名は ASCII 文字で構成されている必要があります。オブジェクト名は 1 文字以上の長さである必要があります。オブジェクト名の長さは JET_cbNameMost (64) 文字を超えることはできません。オブジェクト名を空白で開始することはできません。オブジェクト名に ASCII 制御文字 (0x00 から 0x1F) を含めることはできません。オブジェクト名に感嘆符 (!)、ピリオド (.)、左角かっこ ([)、右角かっこ (]) の各文字を含めることはできません。検証後は、文字列のうち最初の空白 (存在する場合) までの部分のみがオブジェクト名として使用されます。これは実質的に、オブジェクト名に空白も含められないことを意味します。
JET_errInvalidParameter	指定されたパラメーターのいずれかに予期しない値が含まれていたか、別のパラメーターの値と組み合わせたときに意味をなさない値が含まれていました。JetSetCurrentIndex4 では、pindexid が NULL ではなく、かつ pindexid->cbStruct が想定されたサイズではない場合にこのエラーが発生することがあります (Windows XP 以前のリリース)。
JET_errNoCurrentRecord	JET_bitNoMove オプションを指定してセカンダリインデックスが選択されていますが、古いインデックス上のカーソルの現在位置にあるインデックスエントリに関連付けられたレコードに対応するインデックスエントリが、新しいインデックスにありません。
JET_errNotInitialized	そのセッションに関連付けられたインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errOutOfCursors	エンジンが、カーソルを開くために使用するリソースのプールを使い果たしました。同時に開くことができるカーソルの最大数は JET_paramMaxCursors を使用して制御します。詳細については JetSetSystemParameter を参照してください。JetSetCurrentIndex4 では、セカンダリインデックスが選択されていて、エンジンがそのインデックスを使用するための内部カーソルを開けない場合にこのエラーが発生することがあります。
JET_errRestoreInProgress	そのセッションに関連付けられたインスタンスで復元操作が進行中のため、操作を完了できません。
JET_errSessionSharingViolation	同じセッションを同時に複数のスレッドで使用することはできません。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errTermInProgress	そのセッションに関連付けられたインスタンスがシャットダウン中のため、操作を完了できません。

成功した場合、カーソルの現在のインデックスは要求されたインデックスに設定されます。以後、要求されたインデックスのインデックス定義に従って、JetSeek を使用してインデックスエントリを検索できます。また、そのインデックス定義で指定された順序で、JetMove を使用してインデックスエントリを列挙することもできます。カーソルの現在位置は、そのインデックスの最初のインデックスエントリ (JET_bitMoveFirst)、または古いインデックス上のカーソルの現在位置に関連する特定のインデックスエントリ (JET_bitNoMove) のいずれかに設定されます。データベースの状態は変更されません。

失敗した場合、カーソルの現在のインデックスおよび現在位置は未定義の状態になります。データベースの状態は変更されません。

解説

インデックス ID のヒントが古くなっている場合、この API は単純に失敗します。予想されるかもしれませんが、この場合にインデックスのテキスト名へフォールバックする処理は行われません。このフォールバックは API の呼び出し元が手動で行う必要があります。

要件

要件	値
クライアント	Windows Vista、Windows XP、または Windows 2000 Professional が必要です。
サーバー	Windows Server 2008、Windows Server 2003、または Windows 2000 Server が必要です。
ヘッダー	Esent.h で宣言されています。
ライブラリ	ESENT.lib を使用します。
DLL	ESENT.dll が必要です。
Unicode	JetSetCurrentIndex4W (Unicode) および JetSetCurrentIndex4A (ANSI) として実装されています。

各言語での呼び出し定義

// ESENT.dll  (Unicode / -W)
#include <windows.h>

INT JetSetCurrentIndex4W(
    JET_SESID sesid,
    JET_TABLEID tableid,
    WORD* szIndexName,   // optional
    JET_INDEXID* pindexid,   // optional
    DWORD grbit,
    DWORD itagSequence
);

[DllImport("ESENT.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int JetSetCurrentIndex4W(
    UIntPtr sesid,   // JET_SESID
    UIntPtr tableid,   // JET_TABLEID
    IntPtr szIndexName,   // WORD* optional
    IntPtr pindexid,   // JET_INDEXID* optional
    uint grbit,   // DWORD
    uint itagSequence   // DWORD
);

<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetSetCurrentIndex4W(
    sesid As UIntPtr,   ' JET_SESID
    tableid As UIntPtr,   ' JET_TABLEID
    szIndexName As IntPtr,   ' WORD* optional
    pindexid As IntPtr,   ' JET_INDEXID* optional
    grbit As UInteger,   ' DWORD
    itagSequence As UInteger   ' DWORD
) As Integer
End Function

' sesid : JET_SESID
' tableid : JET_TABLEID
' szIndexName : WORD* optional
' pindexid : JET_INDEXID* optional
' grbit : DWORD
' itagSequence : DWORD
Declare PtrSafe Function JetSetCurrentIndex4W Lib "esent" ( _
    ByVal sesid As LongPtr, _
    ByVal tableid As LongPtr, _
    ByVal szIndexName As LongPtr, _
    ByVal pindexid As LongPtr, _
    ByVal grbit As Long, _
    ByVal itagSequence As Long) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

JetSetCurrentIndex4W = ctypes.windll.esent.JetSetCurrentIndex4W
JetSetCurrentIndex4W.restype = ctypes.c_int
JetSetCurrentIndex4W.argtypes = [
    ctypes.c_size_t,  # sesid : JET_SESID
    ctypes.c_size_t,  # tableid : JET_TABLEID
    ctypes.POINTER(ctypes.c_ushort),  # szIndexName : WORD* optional
    ctypes.c_void_p,  # pindexid : JET_INDEXID* optional
    wintypes.DWORD,  # grbit : DWORD
    wintypes.DWORD,  # itagSequence : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetSetCurrentIndex4W = Fiddle::Function.new(
  lib['JetSetCurrentIndex4W'],
  [
    Fiddle::TYPE_UINTPTR_T,  # sesid : JET_SESID
    Fiddle::TYPE_UINTPTR_T,  # tableid : JET_TABLEID
    Fiddle::TYPE_VOIDP,  # szIndexName : WORD* optional
    Fiddle::TYPE_VOIDP,  # pindexid : JET_INDEXID* optional
    -Fiddle::TYPE_INT,  # grbit : DWORD
    -Fiddle::TYPE_INT,  # itagSequence : DWORD
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "esent")]
extern "system" {
    fn JetSetCurrentIndex4W(
        sesid: usize,  // JET_SESID
        tableid: usize,  // JET_TABLEID
        szIndexName: *mut u16,  // WORD* optional
        pindexid: *mut JET_INDEXID,  // JET_INDEXID* optional
        grbit: u32,  // DWORD
        itagSequence: u32  // DWORD
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ESENT.dll", CharSet = CharSet.Unicode)]
public static extern int JetSetCurrentIndex4W(UIntPtr sesid, UIntPtr tableid, IntPtr szIndexName, IntPtr pindexid, uint grbit, uint itagSequence);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetSetCurrentIndex4W' -Namespace Win32 -PassThru
# $api::JetSetCurrentIndex4W(sesid, tableid, szIndexName, pindexid, grbit, itagSequence)

#uselib "ESENT.dll"
#func global JetSetCurrentIndex4W "JetSetCurrentIndex4W" wptr, wptr, wptr, wptr, wptr, wptr
; JetSetCurrentIndex4W sesid, tableid, varptr(szIndexName), varptr(pindexid), grbit, itagSequence   ; 戻り値は stat
; sesid : JET_SESID -> "wptr"
; tableid : JET_TABLEID -> "wptr"
; szIndexName : WORD* optional -> "wptr"
; pindexid : JET_INDEXID* optional -> "wptr"
; grbit : DWORD -> "wptr"
; itagSequence : DWORD -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ESENT.dll"
#cfunc global JetSetCurrentIndex4W "JetSetCurrentIndex4W" sptr, sptr, var, var, int, int
; res = JetSetCurrentIndex4W(sesid, tableid, szIndexName, pindexid, grbit, itagSequence)
; sesid : JET_SESID -> "sptr"
; tableid : JET_TABLEID -> "sptr"
; szIndexName : WORD* optional -> "var"
; pindexid : JET_INDEXID* optional -> "var"
; grbit : DWORD -> "int"
; itagSequence : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ESENT.dll"
#cfunc global JetSetCurrentIndex4W "JetSetCurrentIndex4W" sptr, sptr, sptr, sptr, int, int
; res = JetSetCurrentIndex4W(sesid, tableid, varptr(szIndexName), varptr(pindexid), grbit, itagSequence)
; sesid : JET_SESID -> "sptr"
; tableid : JET_TABLEID -> "sptr"
; szIndexName : WORD* optional -> "sptr"
; pindexid : JET_INDEXID* optional -> "sptr"
; grbit : DWORD -> "int"
; itagSequence : DWORD -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。