JetCompactW

関数

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

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

シグネチャ

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

INT JetCompactW(
    JET_SESID sesid,
    WORD* szDatabaseSrc,
    WORD* szDatabaseDest,
    JET_PFNSTATUS pfnStatus,
    JET_CONVERT_W* pconvert,   // optional
    DWORD grbit
);

パラメーター

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

戻り値の型: INT

公式ドキュメント

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

戻り値

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

戻りコード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errClientRequestToStopJetService	JetStopService の呼び出しによって、そのセッションに関連付けられたインスタンス上のすべてのアクティビティが停止しているため、操作を完了できません。
JET_errFeatureNotAvailable	NULL 以外の pconvert ポインターが指定されましたが、使用している ESE のバージョンは変換機能をサポートしていません。この機能は、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% の間である必要があります。データベースが主に読み取られ、更新されない場合、アプリケーションはクエリ処理中の I/O 操作の数を減らすために密度を 100% に設定します。一方、レコードと共に格納されるデータのサイズが増える操作でデータが頻繁に更新される場合や、新しいデータが頻繁に挿入される場合は、更新時に必要なリソースをより多くの場合に確保できるよう、アプリケーションはより低い密度を選択します。データベースの圧縮操作により、データベースはアプリケーションが選択した充填率に従って理想的に配置されます。

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

オフラインのデータベース圧縮はデータベース内のすべてのデータに触れるため、データベースの整合性を確認する手段として使用できます。データベースに問題がある疑いがある場合は、圧縮を実行できます。圧縮によってエラーが検出されなければ、そのデータベースが 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  (Unicode / -W)
#include <windows.h>

INT JetCompactW(
    JET_SESID sesid,
    WORD* szDatabaseSrc,
    WORD* szDatabaseDest,
    JET_PFNSTATUS pfnStatus,
    JET_CONVERT_W* pconvert,   // optional
    DWORD grbit
);

[DllImport("ESENT.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int JetCompactW(
    UIntPtr sesid,   // JET_SESID
    ref ushort szDatabaseSrc,   // WORD*
    ref ushort szDatabaseDest,   // WORD*
    IntPtr pfnStatus,   // JET_PFNSTATUS
    IntPtr pconvert,   // JET_CONVERT_W* optional
    uint grbit   // DWORD
);

<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetCompactW(
    sesid As UIntPtr,   ' JET_SESID
    ByRef szDatabaseSrc As UShort,   ' WORD*
    ByRef szDatabaseDest As UShort,   ' WORD*
    pfnStatus As IntPtr,   ' JET_PFNSTATUS
    pconvert As IntPtr,   ' JET_CONVERT_W* optional
    grbit As UInteger   ' DWORD
) As Integer
End Function

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

JetCompactW = ctypes.windll.esent.JetCompactW
JetCompactW.restype = ctypes.c_int
JetCompactW.argtypes = [
    ctypes.c_size_t,  # sesid : JET_SESID
    ctypes.POINTER(ctypes.c_ushort),  # szDatabaseSrc : WORD*
    ctypes.POINTER(ctypes.c_ushort),  # szDatabaseDest : WORD*
    ctypes.c_void_p,  # pfnStatus : JET_PFNSTATUS
    ctypes.c_void_p,  # pconvert : JET_CONVERT_W* optional
    wintypes.DWORD,  # grbit : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetCompactW = Fiddle::Function.new(
  lib['JetCompactW'],
  [
    Fiddle::TYPE_UINTPTR_T,  # sesid : JET_SESID
    Fiddle::TYPE_VOIDP,  # szDatabaseSrc : WORD*
    Fiddle::TYPE_VOIDP,  # szDatabaseDest : WORD*
    Fiddle::TYPE_VOIDP,  # pfnStatus : JET_PFNSTATUS
    Fiddle::TYPE_VOIDP,  # pconvert : JET_CONVERT_W* optional
    -Fiddle::TYPE_INT,  # grbit : DWORD
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

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

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

出力引数:

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