JetRetrieveColumn

関数

現在のレコードから指定した列の値を取得する。

DLLESENT.dll呼出規約winapi

シグネチャ

// ESENT.dll
#include <windows.h>

INT JetRetrieveColumn(
    JET_SESID sesid,
    JET_TABLEID tableid,
    DWORD columnid,
    void* pvData,   // optional
    DWORD cbData,
    DWORD* pcbActual,   // optional
    DWORD grbit,
    JET_RETINFO* pretinfo   // optional
);

パラメーター

名前	型	方向	説明
sesid	JET_SESID	in	列の取得を行うセッションのJET_SESIDハンドル。
tableid	JET_TABLEID	in	値を取得する対象レコードを持つテーブルのカーソルハンドル。
columnid	DWORD	in	取得対象の列を識別する列ID。
pvData	void*	outoptional	取得した列データを受け取る出力バッファポインタ。NULLで必要サイズのみ照会可能である。
cbData	DWORD	in	pvDataバッファのサイズをバイト単位で指定する値。
pcbActual	DWORD*	outoptional	列の実データ長を受け取る出力ポインタ。バッファ不足の判定に用いる。NULL可。
grbit	DWORD	in	取得動作を制御するビットフラグ。JET_bitRetrieveCopy等で取得元やオフセットを指定する。
pretinfo	JET_RETINFO*	inoutoptional	多値列のタグ番号やオフセットを指定するJET_RETINFO構造体ポインタ。NULL可。

戻り値の型: INT

公式ドキュメント

JetRetrieveColumn 関数は、現在のレコードから 1 つの列値を取得します。ここでのレコードとは、カーソルの現在位置にあるインデックスエントリーに関連付けられたレコードです。また、この関数はカーソルのコピーバッファー内で作成中のレコードから列を取得することもできます。さらに、現在のレコードを参照するインデックスエントリーから列データを取得することもできます。実際の列値の取得に加えて、JetRetrieveColumn は列データ自体を取得する前に列のサイズを取得する目的にも使用でき、アプリケーション側のバッファーを適切なサイズにすることができます。

戻り値

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

戻りコード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errBadColumnId	指定された列 ID が、列 ID として有効な範囲を超えています。
JET_errBadItagSequence	無効な複数値列のシーケンス番号の値が pretinfo->itagSequence に渡されました。複数値列の値シーケンス番号として有効な値は 1 以上です。この関数では 0 (ゼロ) は無効な値です。
JET_errClientRequestToStopJetService	JetStopService の呼び出しによって、セッションに関連付けられたインスタンス上のすべての処理が停止しているため、操作を完了できません。
JET_errColumnNotFound	指定された columnid で示される列がテーブルに存在しません。
JET_errIndexTuplesCannotRetrieveFromIndex	部分文字列としてインデックスが作成された列は、通常、各インデックスエントリーには列のごく一部しか含まれないため、インデックスから取得できません。
JET_errInstanceUnavailable	セッションに関連付けられたインスタンスで、データの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errInvalidBufferSize	場合によっては、列の取得に指定するバッファーは、列値の一部でも返すために十分なサイズである必要があります。たとえば、エスクロー更新可能な列は、呼び出し元セッションのトランザクションコンテキストと一貫性を保つように調整され、この調整には呼び出し元が提供するバッファーが必要です。バッファー領域が不足している場合は JET_errInvalidBufferSize が返され、列データはまったく返されません。
JET_errInvalidParameter	指定されたパラメーターの 1 つ以上が正しくありません。これは retinfo.cbStruct が JET_RETINFO のサイズより小さい場合に発生することがあります。
JET_errInvalidgrbit	指定されたオプションが不明であるか、既知のビット設定の不正な組み合わせです。
JET_errNoCurrentRecord	カーソルがレコード上に位置していません。これはさまざまな理由で発生します。たとえば、カーソルが現在のインデックスの最後のレコードよりも後ろに位置している場合に発生します。
JET_errNotInitialized	セッションに関連付けられたインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errRestoreInProgress	セッションに関連付けられたインスタンスで復元操作が進行中であるため、操作を完了できません。
JET_errSessionSharingViolation	同一のセッションを同時に複数のスレッドで使用することはできません。 Windows XP: このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errTermInProgress	セッションに関連付けられたインスタンスがシャットダウン中であるため、操作を完了できません。
JET_wrnBufferTruncated	指定されたバッファーが列のサイズより小さいため、列値全体を取得できませんでした。
JET_wrnColumnNull	取得された列値が NULL です。

成功した場合、指定された列の列値が指定されたバッファーにコピーされます。列値の一部のみがコピーされた場合は、警告 JET_wrnBufferTruncated が返されます。pcbActual が指定されている場合は、列値の実際のサイズが返されます。NULL 値は長さが 0 (ゼロ) であるため、返されるサイズも 0 (ゼロ) になることに注意してください。取得した列が複数値列であり、pretinfo が指定され、オプションとして JET_bitReturnTag が設定されている場合は、列値のシーケンス番号が pretinfo->itagSequence に返されます。

失敗した場合、カーソルの位置は変更されず、指定されたバッファーにはデータはコピーされません。

解説

複数値列ではない列で、サイズが固定または既知のデータを取得する場合、この呼び出しは 1 回だけ使用します。ただし、列データのサイズが不明な場合、通常はこの呼び出しを 2 回使用します。1 回目はデータのサイズを判別して必要な記憶域を割り当てるために呼び出します。次に、同じ呼び出しをもう一度行って列データを取得します。列が複数値列であるために値の実際の個数が不明な場合は、通常この呼び出しを 3 回使用します。最初に値の個数を取得し、その後、記憶域の割り当てと実際のデータの取得のためにさらに 2 回呼び出します。

複数値列のすべての値を取得するには、pretinfo->itagSequence の値を 1 から開始し、呼び出しのたびに増やしながらこの関数を繰り返し呼び出します。関数から JET_wrnColumnNull が返された時点で、最後の列値まで取得したことが分かります。ただし、複数値列の値シーケンスに明示的な NULL 値が設定されている場合、それらの値はスキップされるため、この方法は使用できません。明示的に NULL に設定されたものを含め、複数値列のすべての値を取得したい場合は、JetRetrieveColumn ではなく JetRetrieveColumns を使用する必要があります。なお、この関数は itagSequence に 0 (ゼロ) を指定しても、複数値列の値の個数を返しません。itagSequence に 0 (ゼロ) を渡したときに列値の個数を返すのは JetRetrieveColumns のみです。

この関数がトランザクションレベル 0 (ゼロ) で呼び出された場合、つまり呼び出し元のセッション自体がトランザクション内にない場合は、関数内でトランザクションが開始され、終了されます。これは、long 値がデータベースページをまたぐ場合でも一貫した結果を返すためです。トランザクションは関数呼び出しの間で解放されるため、セッションがトランザクション内にない状態でこの関数を連続して呼び出すと、最初の呼び出しの後に更新されたデータが返される場合があることに注意してください。

JET_bitRetrieveIgnoreDefault オプションが設定されていない限り、列に別の値が明示的に設定されていない場合は、列の既定値が取得されます。

挿入前にコピーバッファーから自動インクリメント列の値を取得することは、正規化されたデータを複数のテーブルに挿入する際に、連結のためレコードを一意に識別する一般的な手段です。自動インクリメント値は挿入操作の開始時に割り当てられ、更新が完了するまでの間はいつでもコピーバッファーから取得できます。

columnid に 0 (ゼロ) を設定して、タグ付き列、複数値列、およびスパース列のすべてを取得する場合、列は columnid の小さい順から大きい順に取得されます。列値を取得するたびに、同じ順序で列値が返されます。この順序は決定的です。

要件

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

各言語での呼び出し定義

// ESENT.dll
#include <windows.h>

INT JetRetrieveColumn(
    JET_SESID sesid,
    JET_TABLEID tableid,
    DWORD columnid,
    void* pvData,   // optional
    DWORD cbData,
    DWORD* pcbActual,   // optional
    DWORD grbit,
    JET_RETINFO* pretinfo   // optional
);

[DllImport("ESENT.dll", ExactSpelling = true)]
static extern int JetRetrieveColumn(
    UIntPtr sesid,   // JET_SESID
    UIntPtr tableid,   // JET_TABLEID
    uint columnid,   // DWORD
    IntPtr pvData,   // void* optional, out
    uint cbData,   // DWORD
    IntPtr pcbActual,   // DWORD* optional, out
    uint grbit,   // DWORD
    IntPtr pretinfo   // JET_RETINFO* optional, in/out
);

<DllImport("ESENT.dll", ExactSpelling:=True)>
Public Shared Function JetRetrieveColumn(
    sesid As UIntPtr,   ' JET_SESID
    tableid As UIntPtr,   ' JET_TABLEID
    columnid As UInteger,   ' DWORD
    pvData As IntPtr,   ' void* optional, out
    cbData As UInteger,   ' DWORD
    pcbActual As IntPtr,   ' DWORD* optional, out
    grbit As UInteger,   ' DWORD
    pretinfo As IntPtr   ' JET_RETINFO* optional, in/out
) As Integer
End Function

' sesid : JET_SESID
' tableid : JET_TABLEID
' columnid : DWORD
' pvData : void* optional, out
' cbData : DWORD
' pcbActual : DWORD* optional, out
' grbit : DWORD
' pretinfo : JET_RETINFO* optional, in/out
Declare PtrSafe Function JetRetrieveColumn Lib "esent" ( _
    ByVal sesid As LongPtr, _
    ByVal tableid As LongPtr, _
    ByVal columnid As Long, _
    ByVal pvData As LongPtr, _
    ByVal cbData As Long, _
    ByVal pcbActual As LongPtr, _
    ByVal grbit As Long, _
    ByVal pretinfo As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

JetRetrieveColumn = ctypes.windll.esent.JetRetrieveColumn
JetRetrieveColumn.restype = ctypes.c_int
JetRetrieveColumn.argtypes = [
    ctypes.c_size_t,  # sesid : JET_SESID
    ctypes.c_size_t,  # tableid : JET_TABLEID
    wintypes.DWORD,  # columnid : DWORD
    ctypes.POINTER(None),  # pvData : void* optional, out
    wintypes.DWORD,  # cbData : DWORD
    ctypes.POINTER(wintypes.DWORD),  # pcbActual : DWORD* optional, out
    wintypes.DWORD,  # grbit : DWORD
    ctypes.c_void_p,  # pretinfo : JET_RETINFO* optional, in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetRetrieveColumn = Fiddle::Function.new(
  lib['JetRetrieveColumn'],
  [
    Fiddle::TYPE_UINTPTR_T,  # sesid : JET_SESID
    Fiddle::TYPE_UINTPTR_T,  # tableid : JET_TABLEID
    -Fiddle::TYPE_INT,  # columnid : DWORD
    Fiddle::TYPE_VOIDP,  # pvData : void* optional, out
    -Fiddle::TYPE_INT,  # cbData : DWORD
    Fiddle::TYPE_VOIDP,  # pcbActual : DWORD* optional, out
    -Fiddle::TYPE_INT,  # grbit : DWORD
    Fiddle::TYPE_VOIDP,  # pretinfo : JET_RETINFO* optional, in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "esent")]
extern "system" {
    fn JetRetrieveColumn(
        sesid: usize,  // JET_SESID
        tableid: usize,  // JET_TABLEID
        columnid: u32,  // DWORD
        pvData: *mut (),  // void* optional, out
        cbData: u32,  // DWORD
        pcbActual: *mut u32,  // DWORD* optional, out
        grbit: u32,  // DWORD
        pretinfo: *mut JET_RETINFO  // JET_RETINFO* optional, in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ESENT.dll")]
public static extern int JetRetrieveColumn(UIntPtr sesid, UIntPtr tableid, uint columnid, IntPtr pvData, uint cbData, IntPtr pcbActual, uint grbit, IntPtr pretinfo);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetRetrieveColumn' -Namespace Win32 -PassThru
# $api::JetRetrieveColumn(sesid, tableid, columnid, pvData, cbData, pcbActual, grbit, pretinfo)

#uselib "ESENT.dll"
#func global JetRetrieveColumn "JetRetrieveColumn" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; JetRetrieveColumn sesid, tableid, columnid, pvData, cbData, varptr(pcbActual), grbit, varptr(pretinfo)   ; 戻り値は stat
; sesid : JET_SESID -> "sptr"
; tableid : JET_TABLEID -> "sptr"
; columnid : DWORD -> "sptr"
; pvData : void* optional, out -> "sptr"
; cbData : DWORD -> "sptr"
; pcbActual : DWORD* optional, out -> "sptr"
; grbit : DWORD -> "sptr"
; pretinfo : JET_RETINFO* optional, in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ESENT.dll"
#cfunc global JetRetrieveColumn "JetRetrieveColumn" sptr, sptr, int, sptr, int, var, int, var
; res = JetRetrieveColumn(sesid, tableid, columnid, pvData, cbData, pcbActual, grbit, pretinfo)
; sesid : JET_SESID -> "sptr"
; tableid : JET_TABLEID -> "sptr"
; columnid : DWORD -> "int"
; pvData : void* optional, out -> "sptr"
; cbData : DWORD -> "int"
; pcbActual : DWORD* optional, out -> "var"
; grbit : DWORD -> "int"
; pretinfo : JET_RETINFO* optional, in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ESENT.dll"
#cfunc global JetRetrieveColumn "JetRetrieveColumn" sptr, sptr, int, sptr, int, sptr, int, sptr
; res = JetRetrieveColumn(sesid, tableid, columnid, pvData, cbData, varptr(pcbActual), grbit, varptr(pretinfo))
; sesid : JET_SESID -> "sptr"
; tableid : JET_TABLEID -> "sptr"
; columnid : DWORD -> "int"
; pvData : void* optional, out -> "sptr"
; cbData : DWORD -> "int"
; pcbActual : DWORD* optional, out -> "sptr"
; grbit : DWORD -> "int"
; pretinfo : JET_RETINFO* optional, in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。