JetCreateInstance2A

関数

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

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

シグネチャ

// ESENT.dll  (ANSI / -A)
#include <windows.h>

INT JetCreateInstance2A(
    JET_INSTANCE* pinstance,
    CHAR* szInstanceName,   // optional
    CHAR* szDisplayName,   // optional
    DWORD grbit
);

パラメーター

名前	型	方向	説明
pinstance	JET_INSTANCE*	out	生成されたインスタンスハンドルを受け取るJET_INSTANCEポインタ。
szInstanceName	CHAR*	inoptional	インスタンスを識別する一意の名前を指すANSI文字列。NULL可。
szDisplayName	CHAR*	inoptional	パフォーマンスモニタ等に表示する名前を指すANSI文字列。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  (ANSI / -A)
#include <windows.h>

INT JetCreateInstance2A(
    JET_INSTANCE* pinstance,
    CHAR* szInstanceName,   // optional
    CHAR* szDisplayName,   // optional
    DWORD grbit
);

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

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

' pinstance : JET_INSTANCE* out
' szInstanceName : CHAR* optional
' szDisplayName : CHAR* optional
' grbit : DWORD
Declare PtrSafe Function JetCreateInstance2A Lib "esent" ( _
    ByRef pinstance As LongPtr, _
    ByVal szInstanceName As LongPtr, _
    ByVal szDisplayName As LongPtr, _
    ByVal grbit As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

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

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetCreateInstance2A = Fiddle::Function.new(
  lib['JetCreateInstance2A'],
  [
    Fiddle::TYPE_VOIDP,  # pinstance : JET_INSTANCE* out
    Fiddle::TYPE_VOIDP,  # szInstanceName : CHAR* optional
    Fiddle::TYPE_VOIDP,  # szDisplayName : CHAR* optional
    -Fiddle::TYPE_INT,  # grbit : DWORD
  ],
  Fiddle::TYPE_INT)

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

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

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

出力引数:

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