JetBeginSessionW

関数

ESEデータベースへのセッションを開始する。

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

シグネチャ

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

INT JetBeginSessionW(
    JET_INSTANCE instance,
    JET_SESID* psesid,
    WORD* szUserName,   // optional
    WORD* szPassword   // optional
);

パラメーター

名前	型	方向	説明
instance	JET_INSTANCE	in	セッションを開始する対象のインスタンスハンドル。
psesid	JET_SESID*	out	生成されたセッションIDを受け取るJET_SESIDポインタ。
szUserName	WORD*	inoptional	認証に用いるユーザー名を指すワイド文字列(WORD*)。未使用のためNULL可。
szPassword	WORD*	inoptional	認証に用いるパスワードを指すワイド文字列(WORD*)。未使用のためNULL可。

戻り値の型: INT

公式ドキュメント

JetBeginSession 関数はセッションを開始し、ESE のセッションハンドル (JET_SESID) を初期化して返します。セッションはデータベースへのすべてのアクセスを制御し、トランザクションのスコープを制御するために使用されます。セッションを使用して、トランザクションの開始、コミット、中止を行えます。また、セッションはデータベースのアタッチ、作成、オープンにも使用されます。セッションは、すべての DDL 操作および DML 操作のコンテキストとして使用されます。データベースへの同時実行性と並列アクセスを高めるために、複数のセッションを開始できます。

戻り値

この関数は、この API で定義されている任意の JET_ERR を返す可能性があります。Jet のエラーの詳細については、Extensible Storage Engine Errors および Error Handling Parameters を参照してください。

戻り値のコード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errClientRequestToStopJetService	JetStopService の呼び出しによって、セッションに関連付けられたインスタンス上のすべての動作が停止しているため、操作を完了できません。
JET_errInstanceUnavailable	セッションに関連付けられたインスタンスで、データの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errInvalidParameter	指定されたパラメーターのいずれかに予期しない値が含まれていたか、別のパラメーターの値と組み合わせたときに意味をなさない値が含まれていました。
JET_errNotInitialized	セッションに関連付けられたインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errOutOfMemory	メモリを割り当てられなかったため、操作は失敗しました。
JET_errOutOfSessions	エンジンがクライアントに開始を許可するセッション数には制限があります。この値は、JetSetSystemParameter に JET_paramMaxSessions 定数を指定して変更できます。既定のセッション数は 16 です。JET_paramMaxSessions の詳細については、System Parameters を参照してください。
JET_errRestoreInProgress	セッションに関連付けられたインスタンスで復元操作が進行中であるため、操作を完了できません。
JET_errTermInProgress	セッションに関連付けられたインスタンスがシャットダウン中であるため、操作を完了できません。

成功した場合、セッションハンドルは初期化され、データベース操作に使用できます。

失敗した場合は、利用可能なセッションが存在しないか、新しいセッションを初期化できなかったことを示します。

解説

複数のスレッドにまたがってセッションを使用する場合は、十分に注意する必要があります。セッションは、JetBeginTransaction、JetCommitTransaction、または JetRollback の実行時にどのスレッドで使用されたかを記録しており、トランザクションが開いた状態で複数のスレッドから使用されるとエラーを発生させます。JetResetSessionContext および JetSetSessionContext を使用すると、この動作を変更できます。セッションは依然としてシリアル化されたコンテキストであるため、1 つのセッションで複数のデータベース操作を同時に実行することはできず、順次実行のみが可能です。ただし、複数のセッションを使用すれば、データベースへの同時アクセスを実現できます。セッションコンテキストの設定とリセットを行うことで、トランザクション内でスレッドをまたいでセッションを使用できます。

セッションハンドルは JetEndSession で閉じる必要があります。

要件

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

各言語での呼び出し定義

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

INT JetBeginSessionW(
    JET_INSTANCE instance,
    JET_SESID* psesid,
    WORD* szUserName,   // optional
    WORD* szPassword   // optional
);

[DllImport("ESENT.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int JetBeginSessionW(
    UIntPtr instance,   // JET_INSTANCE
    out UIntPtr psesid,   // JET_SESID* out
    IntPtr szUserName,   // WORD* optional
    IntPtr szPassword   // WORD* optional
);

<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetBeginSessionW(
    instance As UIntPtr,   ' JET_INSTANCE
    <Out> ByRef psesid As UIntPtr,   ' JET_SESID* out
    szUserName As IntPtr,   ' WORD* optional
    szPassword As IntPtr   ' WORD* optional
) As Integer
End Function

' instance : JET_INSTANCE
' psesid : JET_SESID* out
' szUserName : WORD* optional
' szPassword : WORD* optional
Declare PtrSafe Function JetBeginSessionW Lib "esent" ( _
    ByVal instance As LongPtr, _
    ByRef psesid As LongPtr, _
    ByVal szUserName As LongPtr, _
    ByVal szPassword As LongPtr) 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

JetBeginSessionW = ctypes.windll.esent.JetBeginSessionW
JetBeginSessionW.restype = ctypes.c_int
JetBeginSessionW.argtypes = [
    ctypes.c_size_t,  # instance : JET_INSTANCE
    ctypes.c_void_p,  # psesid : JET_SESID* out
    ctypes.POINTER(ctypes.c_ushort),  # szUserName : WORD* optional
    ctypes.POINTER(ctypes.c_ushort),  # szPassword : WORD* optional
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetBeginSessionW = Fiddle::Function.new(
  lib['JetBeginSessionW'],
  [
    Fiddle::TYPE_UINTPTR_T,  # instance : JET_INSTANCE
    Fiddle::TYPE_VOIDP,  # psesid : JET_SESID* out
    Fiddle::TYPE_VOIDP,  # szUserName : WORD* optional
    Fiddle::TYPE_VOIDP,  # szPassword : WORD* optional
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "esent")]
extern "system" {
    fn JetBeginSessionW(
        instance: usize,  // JET_INSTANCE
        psesid: *mut usize,  // JET_SESID* out
        szUserName: *mut u16,  // WORD* optional
        szPassword: *mut u16  // WORD* optional
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ESENT.dll", CharSet = CharSet.Unicode)]
public static extern int JetBeginSessionW(UIntPtr instance, out UIntPtr psesid, IntPtr szUserName, IntPtr szPassword);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetBeginSessionW' -Namespace Win32 -PassThru
# $api::JetBeginSessionW(instance, psesid, szUserName, szPassword)

#uselib "ESENT.dll"
#func global JetBeginSessionW "JetBeginSessionW" wptr, wptr, wptr, wptr
; JetBeginSessionW instance, varptr(psesid), varptr(szUserName), varptr(szPassword)   ; 戻り値は stat
; instance : JET_INSTANCE -> "wptr"
; psesid : JET_SESID* out -> "wptr"
; szUserName : WORD* optional -> "wptr"
; szPassword : WORD* optional -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ESENT.dll"
#cfunc global JetBeginSessionW "JetBeginSessionW" sptr, var, var, var
; res = JetBeginSessionW(instance, psesid, szUserName, szPassword)
; instance : JET_INSTANCE -> "sptr"
; psesid : JET_SESID* out -> "var"
; szUserName : WORD* optional -> "var"
; szPassword : WORD* optional -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ESENT.dll"
#cfunc global JetBeginSessionW "JetBeginSessionW" sptr, sptr, sptr, sptr
; res = JetBeginSessionW(instance, varptr(psesid), varptr(szUserName), varptr(szPassword))
; instance : JET_INSTANCE -> "sptr"
; psesid : JET_SESID* out -> "sptr"
; szUserName : WORD* optional -> "sptr"
; szPassword : WORD* optional -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。