JetCompactA

関数

データベースを圧縮して再構築する(ANSI版)。

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

シグネチャ

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

INT JetCompactA(
    JET_SESID sesid,
    CHAR* szDatabaseSrc,
    CHAR* szDatabaseDest,
    JET_PFNSTATUS pfnStatus,
    JET_CONVERT_A* pconvert,   // optional
    DWORD grbit
);

パラメーター

名前	型	方向	説明
sesid	JET_SESID	in	圧縮を行うセッションのJET_SESIDハンドル。
szDatabaseSrc	CHAR*	in	圧縮元データベースファイルのパスを指す終端付きANSI文字列ポインタ。
szDatabaseDest	CHAR*	in	圧縮先(出力)データベースファイルのパスを指す終端付きANSI文字列ポインタ。
pfnStatus	JET_PFNSTATUS	in	進捗通知を受け取るステータスコールバック関数(JET_PFNSTATUS)。NULL可。
pconvert	JET_CONVERT_A*	inoptional	予約済みの変換オプション構造体ポインタ(JET_CONVERT_A)。NULLを指定する。
grbit	DWORD	in	圧縮動作を制御するビットフラグ。JET_bitCompactStats等を指定する。

戻り値の型: INT

公式ドキュメント

JetCompact 関数は、既存のデータベースのコピーを作成します。コピーは、使用に最適な状態に圧縮されます。コピーされたデータは、インデックス作成時に選択された指標に従って詰め込まれます。これにより、圧縮されたデータを可能な限り高密度に格納できます。あるいは、圧縮されたデータに、その後のレコードの増加やインデックスの挿入に備えた領域を予約することもできます。

戻り値

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

戻り値コード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errClientRequestToStopJetService	JetStopService の呼び出しによってセッションに関連付けられたインスタンス上のすべての動作が停止しているため、操作を完了できません。
JET_errFeatureNotAvailable	NULL 以外の pconvert ポインターが指定されましたが、使用している ESE のバージョンは convert 機能をサポートしていません。この機能は Windows Server 2003 版の ESE で削除されました。
JET_errInstanceUnavailable	セッションに関連付けられたインスタンスで、データの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errInTransaction	呼び出し元のセッションがトランザクション内にあります。JetCompact は、いかなるトランザクションにも属していないセッションから呼び出す必要があります。
JET_errNotInitialized	セッションに関連付けられたインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errRestoreInProgress	セッションに関連付けられたインスタンスで復元操作が進行中であるため、操作を完了できません。
JET_errSessionSharingViolation	同一のセッションを、同時に複数のスレッドで使用することはできません。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errTermInProgress	セッションに関連付けられたインスタンスがシャットダウン中であるため、操作を完了できません。

成功した場合、コピー元のデータベースがコピー先のデータベースに複製されます。コピー先のデータベースは最適な状態にあり、たとえばテーブルのインデックスはすべて論理ディスク上の隣接した領域に配置されます。各インデックスページは、コピー元のデータベースでインデックスが最初に作成されたときに構成された量までパディングされます。repair オプションが指定されていない限り、すべてのデータとメタデータの設定が完全な忠実度でコピーされます。repair オプションが指定された場合は、コピー元のデータベースの一部のデータがコピーされていない可能性があります。

失敗した場合、コピー先のデータベースは存在することがありますが、コピー元のデータベースの完全なコピーではありません。

解説

データベースの圧縮は、以前のバージョンの形式のデータベースをより新しいバージョンにアップグレードするためにも使用されます。省略可能なパラメーターとして pconvert があり、これにはコピー元のデータベース形式を読み取るために使用する以前のバージョンの DLL の記述を保持できる構造体が含まれます。この機能は Windows Server 2003 で廃止されました。Windows Server 2003 以降、新しいバージョンの ESE は常に以前のバージョンのデータベース形式を読み取ることができるため、この機能は不要になりました。

圧縮操作後に望まれるデータの密度は、テーブルおよびインデックスの作成時に指定します。密度は 20% から 100% の範囲でなければなりません。データベースが主に読み取られるだけで更新されない場合、アプリケーションは密度を 100% に設定し、クエリ処理中の I/O 操作の回数を削減します。一方、レコードとともに格納されるデータのサイズを増加させる操作によって頻繁に更新される場合や、新しいデータが頻繁に挿入される場合、アプリケーションはより低い密度を選択し、更新時に必要なリソースをより多くの場合に利用できるようにします。データベースを圧縮する操作により、データベースはアプリケーションが選択した充填率に従って理想的に配置されます。

データベースの圧縮はオフライン操作です。データベースの使用中に実行することはできません。そのため、通常は、データセットを自身の一部として提供するアプリケーションを開発する際のビルド処理の一環として行われます。

オフラインでのデータベース圧縮はデータベース内のすべてのデータに触れるため、データベースの整合性を確認する手段として使用できます。データベースに疑いがある場合は、圧縮を実行できます。圧縮でエラーが検出されなければ、そのデータベースが ESE にとって有効な状態にあることが分かります。

要件

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

各言語での呼び出し定義

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

INT JetCompactA(
    JET_SESID sesid,
    CHAR* szDatabaseSrc,
    CHAR* szDatabaseDest,
    JET_PFNSTATUS pfnStatus,
    JET_CONVERT_A* pconvert,   // optional
    DWORD grbit
);

[DllImport("ESENT.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int JetCompactA(
    UIntPtr sesid,   // JET_SESID
    IntPtr szDatabaseSrc,   // CHAR*
    IntPtr szDatabaseDest,   // CHAR*
    IntPtr pfnStatus,   // JET_PFNSTATUS
    IntPtr pconvert,   // JET_CONVERT_A* optional
    uint grbit   // DWORD
);

<DllImport("ESENT.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function JetCompactA(
    sesid As UIntPtr,   ' JET_SESID
    szDatabaseSrc As IntPtr,   ' CHAR*
    szDatabaseDest As IntPtr,   ' CHAR*
    pfnStatus As IntPtr,   ' JET_PFNSTATUS
    pconvert As IntPtr,   ' JET_CONVERT_A* optional
    grbit As UInteger   ' DWORD
) As Integer
End Function

' sesid : JET_SESID
' szDatabaseSrc : CHAR*
' szDatabaseDest : CHAR*
' pfnStatus : JET_PFNSTATUS
' pconvert : JET_CONVERT_A* optional
' grbit : DWORD
Declare PtrSafe Function JetCompactA Lib "esent" ( _
    ByVal sesid As LongPtr, _
    ByVal szDatabaseSrc As LongPtr, _
    ByVal szDatabaseDest As LongPtr, _
    ByVal pfnStatus As LongPtr, _
    ByVal pconvert 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

JetCompactA = ctypes.windll.esent.JetCompactA
JetCompactA.restype = ctypes.c_int
JetCompactA.argtypes = [
    ctypes.c_size_t,  # sesid : JET_SESID
    ctypes.POINTER(ctypes.c_byte),  # szDatabaseSrc : CHAR*
    ctypes.POINTER(ctypes.c_byte),  # szDatabaseDest : CHAR*
    ctypes.c_void_p,  # pfnStatus : JET_PFNSTATUS
    ctypes.c_void_p,  # pconvert : JET_CONVERT_A* optional
    wintypes.DWORD,  # grbit : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetCompactA = Fiddle::Function.new(
  lib['JetCompactA'],
  [
    Fiddle::TYPE_UINTPTR_T,  # sesid : JET_SESID
    Fiddle::TYPE_VOIDP,  # szDatabaseSrc : CHAR*
    Fiddle::TYPE_VOIDP,  # szDatabaseDest : CHAR*
    Fiddle::TYPE_VOIDP,  # pfnStatus : JET_PFNSTATUS
    Fiddle::TYPE_VOIDP,  # pconvert : JET_CONVERT_A* optional
    -Fiddle::TYPE_INT,  # grbit : DWORD
  ],
  Fiddle::TYPE_INT)

#[link(name = "esent")]
extern "system" {
    fn JetCompactA(
        sesid: usize,  // JET_SESID
        szDatabaseSrc: *mut i8,  // CHAR*
        szDatabaseDest: *mut i8,  // CHAR*
        pfnStatus: *const core::ffi::c_void,  // JET_PFNSTATUS
        pconvert: *mut JET_CONVERT_A,  // JET_CONVERT_A* 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 JetCompactA(UIntPtr sesid, IntPtr szDatabaseSrc, IntPtr szDatabaseDest, IntPtr pfnStatus, IntPtr pconvert, uint grbit);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetCompactA' -Namespace Win32 -PassThru
# $api::JetCompactA(sesid, szDatabaseSrc, szDatabaseDest, pfnStatus, pconvert, grbit)

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

出力引数:

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