Win32 API 日本語リファレンス
ホーム › Storage.Jet › JetAttachDatabaseA

JetAttachDatabaseA

関数
既存のESEデータベースファイルをインスタンスにアタッチする(ANSI版)。
DLLESENT.dll文字セットANSI (-A)呼出規約winapi

シグネチャ

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

INT JetAttachDatabaseA(
    JET_SESID sesid,
    CHAR* szFilename,
    DWORD grbit
);

パラメーター

名前型方向説明
sesidJET_SESIDin操作に使用するセッションID。
szFilenameCHAR*inアタッチする既存データベースファイルのパスを指すANSI文字列。
grbitDWORDinアタッチ動作を制御するJET_bitDbReadOnly等のフラグ。

戻り値の型: INT

公式ドキュメント

JetAttachDatabase 関数は、データベースインスタンスで使用するためにデータベースファイルをアタッチします。データベースを使用するには、その後 JetOpenDatabase で開く必要があります。

戻り値

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

戻りコード

説明

JET_errSuccess

操作は正常に完了しました。

JET_errBackupInProgress

バックアップ中にデータベースをアタッチすることはできません。

JET_errDatabaseFileReadOnly

szFilename で指定されたデータベースファイルは書き込み可能である必要があります。読み取り専用属性が設定されておらず、実行中のプロセスがそのファイルに書き込むための十分な特権を持っている必要があります。

JET_errDatabaseInUse

データベースファイルは既に別のプロセスによって開かれています。

JET_errDatabaseInvalidPath

szFilename に無効なパスが指定されました。szFilename は NULL 以外で、有効なパスを指している必要があります。

JET_errDatabaseSharingViolation

データベースファイルは既に別のセッションによってアタッチされています。

JET_errFileAccessDenied

データベースエンジンがデータベースファイルを開けません。そのファイルが別のプロセスで使用中であるか、呼び出し元がファイルを開くための十分な特権を持っていない可能性があります。

JET_errFileNotFound

szFilename に指定されたファイルが存在しません。

JET_errPrimaryIndexCorrupted

主インデックスにエラーがあります。これは物理的な破損(ディスクやメモリの破損など)による場合があります。また、より古いオペレーティングシステムで最後に変更されたデータベースをアタッチし、主インデックスが Unicode データを含む列に対して作成されている場合にも返されることがあります。Unicode データに対するインデックスの詳細については、解説を参照してください。

JET_errSecondaryIndexCorrupted

セカンダリインデックスにエラーがあります。これは物理的な破損(ディスクやメモリの破損など)による場合があります。また、より古いオペレーティングシステムで最後に変更されたデータベースをアタッチし、セカンダリインデックスが Unicode データを含む列に対して作成されている場合にも返されることがあります。Unicode データに対するインデックスの詳細については、解説を参照してください。セカンダリインデックスは、オフラインユーティリティで次のコマンドを使用してデータベースをデフラグすると完全に再構築されます: esentutl -d。

JET_errTooManyAttachedDatabases

1 つのインスタンスにアタッチできるデータベースの数には上限があります。現在の上限は 1 インスタンスあたり 7 個のデータベースです。

JET_wrnDatabaseAttached

データベースファイルが既にこのセッションによってアタッチされていることを示す、致命的ではない警告です。

解説

JetAttachDatabase の呼び出しは、JetAttachDatabase2 を呼び出し、cpgDatabaseSizeMax パラメーターに 0(制限なしを意味します)を渡すことと同等です。

書き込み可能なデータベースをアタッチすると(つまり grbit パラメーターに JET_bitDbReadOnly を指定しなかった場合)、オペレーティングシステムのレベルでファイルが排他的に開かれます。他のプロセスはそのファイルを開くことができません。読み取り専用モードで開けば、複数のプロセスが単一のデータベースをアタッチすることも可能です。

データベースファイルのデタッチには JetDetachDatabase または JetDetachDatabase2 を使用します。

インデックスチェックのパラメーター

Windows のバージョンによって Unicode テキストの正規化方法が異なります。そのため、あるバージョンの Windows で構築されたインデックスが、別のバージョンでは動作しないことがあります。

Windows Server 2003 より前では、オペレーティングシステムのバージョンが変わると(Service Pack のインストールを含む)、Unicode データに対するすべてのインデックスが破損している可能性のある状態になりました。

Windows Server 2003 以降で作成されたインデックスには、構築に使用された Unicode 正規化のバージョンが記録されます。それより古いインデックスにはバージョン情報が含まれていません。Unicode 正規化の変更のほとんどは新しい文字の追加であり、以前は未定義だったコードポイントが定義され、正規化の結果が変わります。したがって、Unicode 列にバイナリデータを格納している場合、新しいコードポイントが定義されるにつれて正規化の結果が変わります。

Windows Server 2003 以降、ESE データベースエンジンは未定義のコードポイントを含む Unicode インデックスエントリを追跡します。これらは、定義済みの Unicode 文字の集合が変化したときにインデックスを修復するために使用できます。

これらのパラメーターは、異なるビルドのオペレーティングシステムで最後に使用されたデータベースに ESE データベースエンジンがアタッチする際の動作を制御します。オペレーティングシステムのバージョンはデータベースヘッダーに記録されています。

JET_paramEnableIndexChecking が TRUE に設定されていて、データベースに破損している可能性のあるインデックスが含まれている場合:

JET_paramEnableIndexChecking が FALSE に設定されている場合:

Windows Server 2003 以降: JET_paramEnableIndexChecking がリセットされていない場合、内部の修正テーブルを使用してインデックスエントリが修正されます。これによってすべてのインデックスの破損が修復されるとは限りませんが、アプリケーションからは透過的に行われます。

データベースが読み取り専用としてアタッチされている場合、インデックスを修復または削除することはできません。この場合、API は代わりに JET_errSecondaryIndexCorrupted や JET_errPrimaryIndexCorrupted などのエラーを返します。

要件

要件 値

クライアント

Windows Vista、Windows XP、または Windows 2000 Professional が必要です。

サーバー

Windows Server 2008、Windows Server 2003、または Windows 2000 Server が必要です。

ヘッダー

Esent.h で宣言されています。

ライブラリ

ESENT.lib を使用します。

DLL

ESENT.dll が必要です。

Unicode

JetAddColumnW (Unicode) および JetAddColumnA (ANSI) として実装されています。

関連項目

Extensible Storage Engine Files
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetAttachDatabase2
JetCreateDatabase
JetDetachDatabase
JetDetachDatabase2
JetOpenDatabase
JetSetSystemParameter

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp)

各言語での呼び出し定義

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

INT JetAttachDatabaseA(
    JET_SESID sesid,
    CHAR* szFilename,
    DWORD grbit
);
[DllImport("ESENT.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int JetAttachDatabaseA(
    UIntPtr sesid,   // JET_SESID
    IntPtr szFilename,   // CHAR*
    uint grbit   // DWORD
);
<DllImport("ESENT.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function JetAttachDatabaseA(
    sesid As UIntPtr,   ' JET_SESID
    szFilename As IntPtr,   ' CHAR*
    grbit As UInteger   ' DWORD
) As Integer
End Function
' sesid : JET_SESID
' szFilename : CHAR*
' grbit : DWORD
Declare PtrSafe Function JetAttachDatabaseA Lib "esent" ( _
    ByVal sesid As LongPtr, _
    ByVal szFilename 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

JetAttachDatabaseA = ctypes.windll.esent.JetAttachDatabaseA
JetAttachDatabaseA.restype = ctypes.c_int
JetAttachDatabaseA.argtypes = [
    ctypes.c_size_t,  # sesid : JET_SESID
    ctypes.POINTER(ctypes.c_byte),  # szFilename : CHAR*
    wintypes.DWORD,  # grbit : DWORD
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetAttachDatabaseA = Fiddle::Function.new(
  lib['JetAttachDatabaseA'],
  [
    Fiddle::TYPE_UINTPTR_T,  # sesid : JET_SESID
    Fiddle::TYPE_VOIDP,  # szFilename : CHAR*
    -Fiddle::TYPE_INT,  # grbit : DWORD
  ],
  Fiddle::TYPE_INT)
#[link(name = "esent")]
extern "system" {
    fn JetAttachDatabaseA(
        sesid: usize,  // JET_SESID
        szFilename: *mut i8,  // CHAR*
        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 JetAttachDatabaseA(UIntPtr sesid, IntPtr szFilename, uint grbit);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetAttachDatabaseA' -Namespace Win32 -PassThru
# $api::JetAttachDatabaseA(sesid, szFilename, grbit)
#uselib "ESENT.dll"
#func global JetAttachDatabaseA "JetAttachDatabaseA" sptr, sptr, sptr
; JetAttachDatabaseA sesid, varptr(szFilename), grbit   ; 戻り値は stat
; sesid : JET_SESID -> "sptr"
; szFilename : CHAR* -> "sptr"
; grbit : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
出力引数:
#uselib "ESENT.dll"
#cfunc global JetAttachDatabaseA "JetAttachDatabaseA" sptr, var, int
; res = JetAttachDatabaseA(sesid, szFilename, grbit)
; sesid : JET_SESID -> "sptr"
; szFilename : CHAR* -> "var"
; grbit : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
出力引数:
; INT JetAttachDatabaseA(JET_SESID sesid, CHAR* szFilename, DWORD grbit)
#uselib "ESENT.dll"
#cfunc global JetAttachDatabaseA "JetAttachDatabaseA" intptr, var, int
; res = JetAttachDatabaseA(sesid, szFilename, grbit)
; sesid : JET_SESID -> "intptr"
; szFilename : CHAR* -> "var"
; grbit : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	esent = windows.NewLazySystemDLL("ESENT.dll")
	procJetAttachDatabaseA = esent.NewProc("JetAttachDatabaseA")
)

// sesid (JET_SESID), szFilename (CHAR*), grbit (DWORD)
r1, _, err := procJetAttachDatabaseA.Call(
	uintptr(sesid),
	uintptr(szFilename),
	uintptr(grbit),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // INT
function JetAttachDatabaseA(
  sesid: NativeUInt;   // JET_SESID
  szFilename: Pointer;   // CHAR*
  grbit: DWORD   // DWORD
): Integer; stdcall;
  external 'ESENT.dll' name 'JetAttachDatabaseA';
result := DllCall("ESENT\JetAttachDatabaseA"
    , "UPtr", sesid   ; JET_SESID
    , "Ptr", szFilename   ; CHAR*
    , "UInt", grbit   ; DWORD
    , "Int")   ; return: INT
●JetAttachDatabaseA(sesid, szFilename, grbit) = DLL("ESENT.dll", "int JetAttachDatabaseA(int, void*, dword)")
# 呼び出し: JetAttachDatabaseA(sesid, szFilename, grbit)
# sesid : JET_SESID -> "int"
# szFilename : CHAR* -> "void*"
# grbit : DWORD -> "dword"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "esent" fn JetAttachDatabaseA(
    sesid: usize, // JET_SESID
    szFilename: [*c]i8, // CHAR*
    grbit: u32 // DWORD
) callconv(std.os.windows.WINAPI) i32;
proc JetAttachDatabaseA(
    sesid: uint,  # JET_SESID
    szFilename: ptr int8,  # CHAR*
    grbit: uint32  # DWORD
): int32 {.importc: "JetAttachDatabaseA", stdcall, dynlib: "ESENT.dll".}
pragma(lib, "esent");
extern(Windows)
int JetAttachDatabaseA(
    size_t sesid,   // JET_SESID
    byte* szFilename,   // CHAR*
    uint grbit   // DWORD
);
ccall((:JetAttachDatabaseA, "ESENT.dll"), stdcall, Int32,
      (Csize_t, Ptr{Int8}, UInt32),
      sesid, szFilename, grbit)
# sesid : JET_SESID -> Csize_t
# szFilename : CHAR* -> Ptr{Int8}
# grbit : DWORD -> UInt32
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
int32_t JetAttachDatabaseA(
    uintptr_t sesid,
    int8_t* szFilename,
    uint32_t grbit);
]]
local esent = ffi.load("esent")
-- esent.JetAttachDatabaseA(sesid, szFilename, grbit)
-- sesid : JET_SESID
-- szFilename : CHAR*
-- grbit : DWORD
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('ESENT.dll');
const JetAttachDatabaseA = lib.func('__stdcall', 'JetAttachDatabaseA', 'int32_t', ['uintptr_t', 'int8_t *', 'uint32_t']);
// JetAttachDatabaseA(sesid, szFilename, grbit)
// sesid : JET_SESID -> 'uintptr_t'
// szFilename : CHAR* -> 'int8_t *'
// grbit : DWORD -> 'uint32_t'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("ESENT.dll", {
  JetAttachDatabaseA: { parameters: ["usize", "pointer", "u32"], result: "i32" },
});
// lib.symbols.JetAttachDatabaseA(sesid, szFilename, grbit)
// sesid : JET_SESID -> "usize"
// szFilename : CHAR* -> "pointer"
// grbit : DWORD -> "u32"
// 文字列は "buffer"。ANSI(-A) は new TextEncoder() で UTF-8/ANSI バイト列(末尾に \x00)を渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t JetAttachDatabaseA(
    size_t sesid,
    int8_t* szFilename,
    uint32_t grbit);
C, "ESENT.dll");
// $ffi->JetAttachDatabaseA(sesid, szFilename, grbit);
// sesid : JET_SESID
// szFilename : CHAR*
// grbit : DWORD
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Esent extends StdCallLibrary {
    Esent INSTANCE = Native.load("esent", Esent.class, W32APIOptions.ASCII_OPTIONS);
    int JetAttachDatabaseA(
        long sesid,   // JET_SESID
        byte[] szFilename,   // CHAR*
        int grbit   // DWORD
    );
}
@[Link("esent")]
lib LibESENT
  fun JetAttachDatabaseA = JetAttachDatabaseA(
    sesid : LibC::SizeT,   # JET_SESID
    szFilename : Int8*,   # CHAR*
    grbit : UInt32   # DWORD
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef JetAttachDatabaseANative = Int32 Function(UintPtr, Pointer<Int8>, Uint32);
typedef JetAttachDatabaseADart = int Function(int, Pointer<Int8>, int);
final JetAttachDatabaseA = DynamicLibrary.open('ESENT.dll')
    .lookupFunction<JetAttachDatabaseANative, JetAttachDatabaseADart>('JetAttachDatabaseA');
// sesid : JET_SESID -> UintPtr
// szFilename : CHAR* -> Pointer<Int8>
// grbit : DWORD -> Uint32
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function JetAttachDatabaseA(
  sesid: NativeUInt;   // JET_SESID
  szFilename: Pointer;   // CHAR*
  grbit: DWORD   // DWORD
): Integer; stdcall;
  external 'ESENT.dll' name 'JetAttachDatabaseA';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "JetAttachDatabaseA"
  c_JetAttachDatabaseA :: CUIntPtr -> Ptr Int8 -> Word32 -> IO Int32
-- sesid : JET_SESID -> CUIntPtr
-- szFilename : CHAR* -> Ptr Int8
-- grbit : DWORD -> Word32
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let jetattachdatabasea =
  foreign "JetAttachDatabaseA"
    (size_t @-> (ptr int8_t) @-> uint32_t @-> returning int32_t)
(* sesid : JET_SESID -> size_t *)
(* szFilename : CHAR* -> (ptr int8_t) *)
(* grbit : DWORD -> uint32_t *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library esent (t "ESENT.dll"))
(cffi:use-foreign-library esent)

(cffi:defcfun ("JetAttachDatabaseA" jet-attach-database-a :convention :stdcall) :int32
  (sesid :uint64)   ; JET_SESID
  (sz-filename :pointer)   ; CHAR*
  (grbit :uint32))   ; DWORD
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $JetAttachDatabaseA = Win32::API::More->new('ESENT',
    'int JetAttachDatabaseA(WPARAM sesid, LPVOID szFilename, DWORD grbit)');
# my $ret = $JetAttachDatabaseA->Call($sesid, $szFilename, $grbit);
# sesid : JET_SESID -> WPARAM
# szFilename : CHAR* -> LPVOID
# grbit : DWORD -> DWORD
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

文字セット違い
類似 API