JetDefragment2W

関数

コールバック付きでオンライン最適化を実行する(Unicode版)。

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

シグネチャ

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

INT JetDefragment2W(
    JET_SESID sesid,
    DWORD dbid,
    WORD* szTableName,   // optional
    DWORD* pcPasses,   // optional
    DWORD* pcSeconds,   // optional
    JET_CALLBACK callback,
    DWORD grbit
);

パラメーター

名前	型	方向	説明
sesid	JET_SESID	in	オンライン最適化を行うセッションのJET_SESIDハンドル。
dbid	DWORD	in	最適化対象のデータベースを識別するデータベースID(JET_DBID)。
szTableName	WORD*	inoptional	最適化対象テーブル名を指す終端付きUnicode文字列ポインタ。NULLで全テーブル対象となる。
pcPasses	DWORD*	inoutoptional	最大パス数を入出力で受け渡すポインタ。完了時に実行済み回数が返る。NULL可。
pcSeconds	DWORD*	inoutoptional	最大秒数を入出力で受け渡すポインタ。完了時に経過秒数が返る。NULL可。
callback	JET_CALLBACK	in	最適化の完了通知を受け取るコールバック関数(JET_CALLBACK)。NULL可。
grbit	DWORD	in	最適化動作を制御するビットフラグ。バッチ開始/停止などを指定する。

戻り値の型: INT

公式ドキュメント

JetDefragment2 関数は、データベース内のデータ構成を改善するデータベースのデフラグタスクを開始および停止します。デフラグの進行状況を報告するためのコールバックパラメーターを指定できます。これは、データベース内の既存のディスク割り当てをより効率的に使用することで、データベースの増大を抑えるために行われます。また、データをより緊密に配置することでワーキングセットを削減することもできます。さらに、データ構成の改善によって一般的な操作が高速化され、アプリケーションのパフォーマンスを向上させることができます。

戻り値

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

リターンコード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errClientRequestToStopJetService	JetStopService の呼び出しの結果として、セッションに関連付けられたインスタンス上のすべての動作が停止したため、操作を完了できません。
JET_errDatabaseFileReadOnly	デフラグ対象として選択されたデータベースは読み取り専用であり、デフラグを含め、いかなる方法でも更新できません。
JET_errDistributedTransactionAlreadyPreparedToCommit	指定されたセッションはコミット準備完了状態にあり、現在のトランザクションがコミットまたはロールバックされるまで、新しい更新を開始できません。
JET_errInstanceUnavailable	セッションに関連付けられたインスタンスで、データの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errInvalidDatabaseId	指定されたデータベース ID は、インスタンス内の既知のデータベースと一致しません。
JET_errNotInitialized	セッションに関連付けられたインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errRestoreInProgress	セッションに関連付けられたインスタンスで復元操作が進行中であるため、操作を完了できません。
JET_errSessionSharingViolation	同じセッションを複数のスレッドで同時に使用することはできません。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errTermInProgress	セッションに関連付けられたインスタンスがシャットダウン中であるため、操作を完了できません。
JET_errTransReadOnly	指定されたセッションは読み取り専用の特権しか持たないため、デフラグを含め、更新を行う可能性のあるタスクを開始できません。
JET_errVersionStoreOutOfMemory	構成されたバージョンストアのサイズが、未処理のすべての更新を保持するには不十分な場合に、このエラーが発生します。
JET_wrnDefragAlreadyRunning	JET_bitDefragmentBatchStart オプションが渡されましたが、指定されたデータベースでは既にデフラグタスクがデフラグを実行しています。
JET_wrnDefragNotRunning	JET_bitDefragmentBatchStop オプションが渡されましたが、現在実行中のデフラグタスクはありません。

成功した場合は、指定されたデータに対して指定されたオプションでデフラグタスクを開始する、または既存のデフラグタスクを停止するという、要求されたアクションが実行されます。

失敗した場合は、オンラインデフラグジョブを開始または停止するという、要求されたアクションは実行されません。他の副作用は発生しません。

解説

オンラインデフラグは、パラメーター設定とこの API の両方によって制御されます。既定のシステムパラメーター値は JET_OnlineDefragAll であり、サポートされるすべてのデータ構造でデフラグが有効であることを意味します。ただし、JetSetSystemParameter を使用すると、オンラインデフラグを無効にしたり、データベースの空き領域ツリーのみ、データベースのみ、ストリーミングファイルのみ、またはこれらの任意の組み合わせに対して選択的に有効にしたりできます。オンラインデフラグのシステム設定が廃止された設定になっている場合、JetDefragment2 はその設定を JET_OnlineDefragAll として扱います。

各データベースに対して実行できるタスクは、最大で 1 つです。このタスクは、ESE をホストするプロセス内のスレッドとして実行されます。

オンラインデフラグタスクの開始に使用したセッションは、デフラグタスクの継続中も、その後のデータベース操作に使用できます。これは、デフラグタスクが独自のセッションを割り当てるためです。指定されたセッションは、タスクを開始したセッションに関連付けられたアクセス許可を確認するためにのみ使用され、デフラグ操作そのものには実際には使用されません。

要件

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

各言語での呼び出し定義

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

INT JetDefragment2W(
    JET_SESID sesid,
    DWORD dbid,
    WORD* szTableName,   // optional
    DWORD* pcPasses,   // optional
    DWORD* pcSeconds,   // optional
    JET_CALLBACK callback,
    DWORD grbit
);

[DllImport("ESENT.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int JetDefragment2W(
    UIntPtr sesid,   // JET_SESID
    uint dbid,   // DWORD
    IntPtr szTableName,   // WORD* optional
    IntPtr pcPasses,   // DWORD* optional, in/out
    IntPtr pcSeconds,   // DWORD* optional, in/out
    IntPtr callback,   // JET_CALLBACK
    uint grbit   // DWORD
);

<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetDefragment2W(
    sesid As UIntPtr,   ' JET_SESID
    dbid As UInteger,   ' DWORD
    szTableName As IntPtr,   ' WORD* optional
    pcPasses As IntPtr,   ' DWORD* optional, in/out
    pcSeconds As IntPtr,   ' DWORD* optional, in/out
    callback As IntPtr,   ' JET_CALLBACK
    grbit As UInteger   ' DWORD
) As Integer
End Function

' sesid : JET_SESID
' dbid : DWORD
' szTableName : WORD* optional
' pcPasses : DWORD* optional, in/out
' pcSeconds : DWORD* optional, in/out
' callback : JET_CALLBACK
' grbit : DWORD
Declare PtrSafe Function JetDefragment2W Lib "esent" ( _
    ByVal sesid As LongPtr, _
    ByVal dbid As Long, _
    ByVal szTableName As LongPtr, _
    ByVal pcPasses As LongPtr, _
    ByVal pcSeconds As LongPtr, _
    ByVal callback 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

JetDefragment2W = ctypes.windll.esent.JetDefragment2W
JetDefragment2W.restype = ctypes.c_int
JetDefragment2W.argtypes = [
    ctypes.c_size_t,  # sesid : JET_SESID
    wintypes.DWORD,  # dbid : DWORD
    ctypes.POINTER(ctypes.c_ushort),  # szTableName : WORD* optional
    ctypes.POINTER(wintypes.DWORD),  # pcPasses : DWORD* optional, in/out
    ctypes.POINTER(wintypes.DWORD),  # pcSeconds : DWORD* optional, in/out
    ctypes.c_void_p,  # callback : JET_CALLBACK
    wintypes.DWORD,  # grbit : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetDefragment2W = Fiddle::Function.new(
  lib['JetDefragment2W'],
  [
    Fiddle::TYPE_UINTPTR_T,  # sesid : JET_SESID
    -Fiddle::TYPE_INT,  # dbid : DWORD
    Fiddle::TYPE_VOIDP,  # szTableName : WORD* optional
    Fiddle::TYPE_VOIDP,  # pcPasses : DWORD* optional, in/out
    Fiddle::TYPE_VOIDP,  # pcSeconds : DWORD* optional, in/out
    Fiddle::TYPE_VOIDP,  # callback : JET_CALLBACK
    -Fiddle::TYPE_INT,  # grbit : DWORD
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "esent")]
extern "system" {
    fn JetDefragment2W(
        sesid: usize,  // JET_SESID
        dbid: u32,  // DWORD
        szTableName: *mut u16,  // WORD* optional
        pcPasses: *mut u32,  // DWORD* optional, in/out
        pcSeconds: *mut u32,  // DWORD* optional, in/out
        callback: *const core::ffi::c_void,  // JET_CALLBACK
        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 JetDefragment2W(UIntPtr sesid, uint dbid, IntPtr szTableName, IntPtr pcPasses, IntPtr pcSeconds, IntPtr callback, uint grbit);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetDefragment2W' -Namespace Win32 -PassThru
# $api::JetDefragment2W(sesid, dbid, szTableName, pcPasses, pcSeconds, callback, grbit)

#uselib "ESENT.dll"
#func global JetDefragment2W "JetDefragment2W" wptr, wptr, wptr, wptr, wptr, wptr, wptr
; JetDefragment2W sesid, dbid, varptr(szTableName), varptr(pcPasses), varptr(pcSeconds), callback, grbit   ; 戻り値は stat
; sesid : JET_SESID -> "wptr"
; dbid : DWORD -> "wptr"
; szTableName : WORD* optional -> "wptr"
; pcPasses : DWORD* optional, in/out -> "wptr"
; pcSeconds : DWORD* optional, in/out -> "wptr"
; callback : JET_CALLBACK -> "wptr"
; grbit : DWORD -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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