JetCreateDatabaseW

関数

新しいESEデータベースファイルを作成する。

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

シグネチャ

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

INT JetCreateDatabaseW(
    JET_SESID sesid,
    WORD* szFilename,
    WORD* szConnect,   // optional
    DWORD* pdbid,
    DWORD grbit
);

パラメーター

名前	型	方向	説明
sesid	JET_SESID	in	操作に使用するセッションID。
szFilename	WORD*	in	作成するデータベースファイルのパスを指すワイド文字列(WORD*)。
szConnect	WORD*	inoptional	予約済みの接続文字列を指すワイド文字列(WORD*)。NULL可。
pdbid	DWORD*	out	生成されたデータベースID(dbid)を受け取るDWORDポインタ。
grbit	DWORD	in	作成動作を制御するJET_bitDbCreate系フラグ。上書き可否などを指定する。

戻り値の型: INT

公式ドキュメント

JetCreateDatabase 関数は、ESE データベースエンジンで使用するデータベースファイルを作成してアタッチします。cpgDatabaseSizeMax に 0 を指定して JetCreateDatabase2 を呼び出すことは、szConnect に NULL を指定して JetCreateDatabase を呼び出すことと同じです。現在、1 インスタンスあたり最大 7 個のデータベースを作成できます。

戻り値

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

リターンコード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errDatabaseDuplicate	szFilename で指定された名前のデータベースが既に存在します。このエラーが返された場合、データベースはアタッチされません。
JET_errDatabaseInUse	排他アクセスが要求されたものの許可されなかった場合、または別のセッションが既にデータベースを排他的に開いている場合に返されることがあります。
JET_errDatabaseInvalidPages	cpgDatabaseSizeMax が、データベースで許可される最大ページ数より大きい場合に返されます。現在の最大値は 2147483646 (0x7ffffffe) です。
JET_errDatabaseInvalidPath	szFilename に無効なパスが指定されました。szFilename は NULL 以外である必要があります。既定では、szFilename は存在するディレクトリを指している必要があります。JET_paramCreatePathIfNotExist が設定されている場合は、パスが作成されます (JetSetSystemParameter を参照してください)。
JET_errDatabaseLocked	別のセッションが既に (JET_bitDbExclusive を使用して) データベースを排他的に開いていることを示します。
JET_errDatabaseNotFound	データベースが事前にアタッチされていません (JetAttachDatabase を参照してください)。
JET_errDatabaseSharingViolation	データベースファイルは、既に別のセッションによってアタッチされています。
JET_errInTransaction	トランザクション中にデータベースを作成しようとしました。
JET_errInvalidDatabase	有効なデータベースファイルではないファイルを開こうとしました。
JET_errOneDatabasePerSession	JET_paramOneDatabasePerSession が設定されている状態で、複数のデータベースを開こうとしました。Database Parameters を参照してください。
JET_errOutOfMemory	メモリを割り当てられなかったため、操作は失敗しました。
JET_errTooManyAttachedDatabases	1 つのインスタンスにアタッチできるデータベースの数には上限があります。現在の上限は、1 インスタンスあたり 7 個のデータベースです。
JET_wrnDatabaseAttached	データベースファイルが既にこのセッションによってアタッチされていることを示す、致命的でない警告です。
JET_wrnFileOpenReadOnly	JET_wrnFileOpenReadOnly は、ファイルが読み取り専用でアタッチされたが、JetCreateDatabase が JET_bitDbReadOnly を渡さなかったことを示します。データベースは引き続き読み取り専用アクセスで開かれます。

解説

szFilename で指定されたデータベースが存在し、かつ JET_bitDbOverwriteExisting が渡されていない場合、API 呼び出しは失敗します。JET_bitDbOverwriteExisting が渡された場合は、まず古いデータベースファイルが削除されます。

API がデータベースファイルを作成した後で別のエラーが発生した場合、API はクリーンアップを行い、そのファイルを削除します。

JetCreateDatabase は暗黙的にデータベースを開きます。その後に JetOpenDatabase を呼び出す必要は必ずしもありません。

要件

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

各言語での呼び出し定義

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

INT JetCreateDatabaseW(
    JET_SESID sesid,
    WORD* szFilename,
    WORD* szConnect,   // optional
    DWORD* pdbid,
    DWORD grbit
);

[DllImport("ESENT.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int JetCreateDatabaseW(
    UIntPtr sesid,   // JET_SESID
    ref ushort szFilename,   // WORD*
    IntPtr szConnect,   // WORD* optional
    out uint pdbid,   // DWORD* out
    uint grbit   // DWORD
);

<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetCreateDatabaseW(
    sesid As UIntPtr,   ' JET_SESID
    ByRef szFilename As UShort,   ' WORD*
    szConnect As IntPtr,   ' WORD* optional
    <Out> ByRef pdbid As UInteger,   ' DWORD* out
    grbit As UInteger   ' DWORD
) As Integer
End Function

' sesid : JET_SESID
' szFilename : WORD*
' szConnect : WORD* optional
' pdbid : DWORD* out
' grbit : DWORD
Declare PtrSafe Function JetCreateDatabaseW Lib "esent" ( _
    ByVal sesid As LongPtr, _
    ByRef szFilename As Integer, _
    ByVal szConnect As LongPtr, _
    ByRef pdbid As Long, _
    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

JetCreateDatabaseW = ctypes.windll.esent.JetCreateDatabaseW
JetCreateDatabaseW.restype = ctypes.c_int
JetCreateDatabaseW.argtypes = [
    ctypes.c_size_t,  # sesid : JET_SESID
    ctypes.POINTER(ctypes.c_ushort),  # szFilename : WORD*
    ctypes.POINTER(ctypes.c_ushort),  # szConnect : WORD* optional
    ctypes.POINTER(wintypes.DWORD),  # pdbid : DWORD* out
    wintypes.DWORD,  # grbit : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetCreateDatabaseW = Fiddle::Function.new(
  lib['JetCreateDatabaseW'],
  [
    Fiddle::TYPE_UINTPTR_T,  # sesid : JET_SESID
    Fiddle::TYPE_VOIDP,  # szFilename : WORD*
    Fiddle::TYPE_VOIDP,  # szConnect : WORD* optional
    Fiddle::TYPE_VOIDP,  # pdbid : DWORD* out
    -Fiddle::TYPE_INT,  # grbit : DWORD
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "esent")]
extern "system" {
    fn JetCreateDatabaseW(
        sesid: usize,  // JET_SESID
        szFilename: *mut u16,  // WORD*
        szConnect: *mut u16,  // WORD* optional
        pdbid: *mut u32,  // DWORD* out
        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 JetCreateDatabaseW(UIntPtr sesid, ref ushort szFilename, IntPtr szConnect, out uint pdbid, uint grbit);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetCreateDatabaseW' -Namespace Win32 -PassThru
# $api::JetCreateDatabaseW(sesid, szFilename, szConnect, pdbid, grbit)

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

出力引数:

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