JetCreateInstance2W

関数

表示名とオプションを指定してESEインスタンスを作成する。

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

シグネチャ

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

INT JetCreateInstance2W(
    JET_INSTANCE* pinstance,
    WORD* szInstanceName,   // optional
    WORD* szDisplayName,   // optional
    DWORD grbit
);

パラメーター

名前	型	方向	説明
pinstance	JET_INSTANCE*	out	生成されたインスタンスハンドルを受け取るJET_INSTANCEポインタ。
szInstanceName	WORD*	inoptional	インスタンスを識別する一意の名前を指すワイド文字列(WORD*)。NULL可。
szDisplayName	WORD*	inoptional	パフォーマンスモニタ等に表示する名前を指すワイド文字列(WORD*)。NULL可。
grbit	DWORD	in	予約済みのオプションフラグ。通常は0を指定する。

戻り値の型: INT

公式ドキュメント

JetCreateInstance2 関数は、表示名を指定して、単一のプロセス内で使用するデータベースエンジンの新しいインスタンスを割り当てるために使用します。

戻り値

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

リターンコード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errInstanceNameInUse	指定されたインスタンス名は、このプロセスで既に使用されています。
JET_errInvalidParameter	指定されたパラメーターのいずれかに予期しない値が含まれていたか、他のパラメーターの値と組み合わせたときに意味を成さない値が含まれていました。これは、JetCreateInstance において pinstance が NULL の場合に発生することがあります。
JET_errRunningInOneInstanceMode	データベースエンジンがシングルインスタンスモード (Windows 2000 互換モード) で動作しているときには使用できない操作であるため、操作は失敗しました。
JET_errTooManyInstances	インスタンスの最大数に達したため、新しいインスタンスを作成できませんでした。サポートされるインスタンスの最大数は、JetSetSystemParameter で JET_paramMaxInstances を使用して構成します。

成功した場合は、新しいインスタンスが割り当てられ、その識別子が返されます。この時点では、インスタンスのすべてのシステムパラメーターはグローバルな既定のシステムパラメーターの値になっています。インスタンスを割り当てた後は、後でそのインスタンスを終了または解放する必要があります。

失敗した場合は、失敗の原因を表すエラーが返され、インスタンスは割り当てられません。

解説

インスタンスは、JetSetSystemParameter 以外から使用する前に、JetInit の呼び出しによって初期化する必要があります。

インスタンスは、JetInit で初期化されていない場合でも、JetTerm 関数の呼び出しによって破棄されます。同時に作成できるインスタンスの最大数は JET_paramMaxInstances によって制御され、この値は JetSetSystemParameter の呼び出しで構成できます。インスタンスは、データベースエンジンにおける回復可能性の単位です。インスタンスは、一連のデータベースファイル内のデータの整合性を保護するために使用されるすべてのファイルのライフサイクルを制御します。これらのファイルには、チェックポイントファイルとトランザクションログファイルが含まれます。

関数が成功すると、この呼び出しの副作用として、データベースエンジンは自動的にマルチインスタンスモードに変更されます。プロセス内で 1 つのインスタンスのみを許可したい場合は、JetInit を使用して Windows 2000 互換モードでデータベースエンジンを開始してください。

szDisplayName パラメーターが指定されている場合、この値はイベントログなどの場所や、バックアップアプリケーションなどの他の呼び出し元に対して (JetGetInstanceInfo や JetOSSnapshotFreeze などの関数を通じて) インスタンスを識別するために使用されます。表示名が指定されていない場合は、代わりに一意の szInstanceName パラメーターが使用されます (指定されている場合)。いずれも指定されていない場合は空の文字列が返されます。エンジンに実行モードが設定されていなかった場合、この呼び出しの後にマルチインスタンスモードに設定されます。

複数の Jet インスタンスを実行する可能性があるプロセスの一般的な起動シーケンスは、次のとおりです。

JetCreateInstance2 を呼び出して、インスタンスを割り当てて名前を付けます。
そのインスタンスに対して JetSetSystemParameter を複数回呼び出し、さまざまなシステムパラメーターを設定します。一部のシステムパラメーター (JET_paramSystemPath や JET_paramLogFilePath など) はインスタンスごとに一意である必要があるため、多くの場合、これらはそれぞれ設定する必要があります。
JetInit または JetInit2 を使用してインスタンスを開始します。インスタンスを終了または解放するには、JetTerm または JetTerm2 を使用します。

開始する最初のインスタンスである場合は、基本的なシステムの初期化と構成を行うために、この呼び出しの中で追加の手順がいくつか実行されます。これらの手順の一部では、JET_errOutOfMemory をはじめとする特定のエラーが発生する可能性があります (詳細については戻り値に関する説明を参照してください)。

要件

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

各言語での呼び出し定義

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

INT JetCreateInstance2W(
    JET_INSTANCE* pinstance,
    WORD* szInstanceName,   // optional
    WORD* szDisplayName,   // optional
    DWORD grbit
);

[DllImport("ESENT.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int JetCreateInstance2W(
    out UIntPtr pinstance,   // JET_INSTANCE* out
    IntPtr szInstanceName,   // WORD* optional
    IntPtr szDisplayName,   // WORD* optional
    uint grbit   // DWORD
);

<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetCreateInstance2W(
    <Out> ByRef pinstance As UIntPtr,   ' JET_INSTANCE* out
    szInstanceName As IntPtr,   ' WORD* optional
    szDisplayName As IntPtr,   ' WORD* optional
    grbit As UInteger   ' DWORD
) As Integer
End Function

' pinstance : JET_INSTANCE* out
' szInstanceName : WORD* optional
' szDisplayName : WORD* optional
' grbit : DWORD
Declare PtrSafe Function JetCreateInstance2W Lib "esent" ( _
    ByRef pinstance As LongPtr, _
    ByVal szInstanceName As LongPtr, _
    ByVal szDisplayName As LongPtr, _
    ByVal grbit 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

JetCreateInstance2W = ctypes.windll.esent.JetCreateInstance2W
JetCreateInstance2W.restype = ctypes.c_int
JetCreateInstance2W.argtypes = [
    ctypes.c_void_p,  # pinstance : JET_INSTANCE* out
    ctypes.POINTER(ctypes.c_ushort),  # szInstanceName : WORD* optional
    ctypes.POINTER(ctypes.c_ushort),  # szDisplayName : WORD* optional
    wintypes.DWORD,  # grbit : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetCreateInstance2W = Fiddle::Function.new(
  lib['JetCreateInstance2W'],
  [
    Fiddle::TYPE_VOIDP,  # pinstance : JET_INSTANCE* out
    Fiddle::TYPE_VOIDP,  # szInstanceName : WORD* optional
    Fiddle::TYPE_VOIDP,  # szDisplayName : WORD* optional
    -Fiddle::TYPE_INT,  # grbit : DWORD
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "esent")]
extern "system" {
    fn JetCreateInstance2W(
        pinstance: *mut usize,  // JET_INSTANCE* out
        szInstanceName: *mut u16,  // WORD* optional
        szDisplayName: *mut u16,  // WORD* optional
        grbit: u32  // DWORD
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ESENT.dll", CharSet = CharSet.Unicode)]
public static extern int JetCreateInstance2W(out UIntPtr pinstance, IntPtr szInstanceName, IntPtr szDisplayName, uint grbit);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetCreateInstance2W' -Namespace Win32 -PassThru
# $api::JetCreateInstance2W(pinstance, szInstanceName, szDisplayName, grbit)

#uselib "ESENT.dll"
#func global JetCreateInstance2W "JetCreateInstance2W" wptr, wptr, wptr, wptr
; JetCreateInstance2W varptr(pinstance), varptr(szInstanceName), varptr(szDisplayName), grbit   ; 戻り値は stat
; pinstance : JET_INSTANCE* out -> "wptr"
; szInstanceName : WORD* optional -> "wptr"
; szDisplayName : WORD* optional -> "wptr"
; grbit : DWORD -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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