JetCreateDatabaseA

関数

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

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

シグネチャ

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

INT JetCreateDatabaseA(
    JET_SESID sesid,
    CHAR* szFilename,
    CHAR* szConnect,   // optional
    DWORD* pdbid,
    DWORD grbit
);

パラメーター

名前	型	方向	説明
sesid	JET_SESID	in	操作に使用するセッションID。
szFilename	CHAR*	in	作成するデータベースファイルのパスを指すANSI文字列。
szConnect	CHAR*	inoptional	予約済みの接続文字列を指すANSI文字列。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 つのインスタンスにアタッチできるデータベースの数には限りがあります。現在の上限はインスタンスあたり 7 個です。
JET_wrnDatabaseAttached	データベースファイルがこのセッションによって既にアタッチされていることを示す、致命的ではない警告です。
JET_wrnFileOpenReadOnly	JET_wrnFileOpenReadOnly は、JetCreateDatabase が JET_bitDbReadOnly を渡していないにもかかわらず、ファイルが読み取り専用でアタッチされたことを示します。データベースは読み取り専用アクセスで開かれたままになります。

解説

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

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  (ANSI / -A)
#include <windows.h>

INT JetCreateDatabaseA(
    JET_SESID sesid,
    CHAR* szFilename,
    CHAR* szConnect,   // optional
    DWORD* pdbid,
    DWORD grbit
);

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

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

' sesid : JET_SESID
' szFilename : CHAR*
' szConnect : CHAR* optional
' pdbid : DWORD* out
' grbit : DWORD
Declare PtrSafe Function JetCreateDatabaseA Lib "esent" ( _
    ByVal sesid As LongPtr, _
    ByVal szFilename As LongPtr, _
    ByVal szConnect As LongPtr, _
    ByRef pdbid As Long, _
    ByVal grbit As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

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

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetCreateDatabaseA = Fiddle::Function.new(
  lib['JetCreateDatabaseA'],
  [
    Fiddle::TYPE_UINTPTR_T,  # sesid : JET_SESID
    Fiddle::TYPE_VOIDP,  # szFilename : CHAR*
    Fiddle::TYPE_VOIDP,  # szConnect : CHAR* optional
    Fiddle::TYPE_VOIDP,  # pdbid : DWORD* out
    -Fiddle::TYPE_INT,  # grbit : DWORD
  ],
  Fiddle::TYPE_INT)

#[link(name = "esent")]
extern "system" {
    fn JetCreateDatabaseA(
        sesid: usize,  // JET_SESID
        szFilename: *mut i8,  // CHAR*
        szConnect: *mut i8,  // CHAR* 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.Ansi)]
public static extern int JetCreateDatabaseA(UIntPtr sesid, IntPtr szFilename, IntPtr szConnect, out uint pdbid, uint grbit);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetCreateDatabaseA' -Namespace Win32 -PassThru
# $api::JetCreateDatabaseA(sesid, szFilename, szConnect, pdbid, grbit)

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

出力引数:

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