JetCreateInstanceW

関数

名前付きのESEデータベースインスタンスを作成する。

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

シグネチャ

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

INT JetCreateInstanceW(
    JET_INSTANCE* pinstance,
    WORD* szInstanceName   // optional
);

パラメーター

名前	型	方向	説明
pinstance	JET_INSTANCE*	out	生成されたインスタンスハンドルを受け取るJET_INSTANCEポインタ。
szInstanceName	WORD*	inoptional	インスタンスを識別する一意の名前を指すワイド文字列(WORD*)。NULL可。

戻り値の型: INT

公式ドキュメント

JetCreateInstance 関数は、単一のプロセス内で使用するデータベースエンジンの新しいインスタンスを割り当てます。

戻り値

この関数は 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	JetCreateInstanceW (Unicode) および JetCreateInstanceA (ANSI) として実装されています。

各言語での呼び出し定義

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

INT JetCreateInstanceW(
    JET_INSTANCE* pinstance,
    WORD* szInstanceName   // optional
);

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

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

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

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

require 'fiddle'
require 'fiddle/import'

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

#[link(name = "esent")]
extern "system" {
    fn JetCreateInstanceW(
        pinstance: *mut usize,  // JET_INSTANCE* out
        szInstanceName: *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 JetCreateInstanceW(out UIntPtr pinstance, IntPtr szInstanceName);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetCreateInstanceW' -Namespace Win32 -PassThru
# $api::JetCreateInstanceW(pinstance, szInstanceName)

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

出力引数:

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