JetDefragmentW

関数

テーブルやデータベースをオンラインで最適化する(Unicode版)。

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

シグネチャ

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

INT JetDefragmentW(
    JET_SESID sesid,
    DWORD dbid,
    WORD* szTableName,   // optional
    DWORD* pcPasses,   // optional
    DWORD* pcSeconds,   // optional
    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可。
grbit	DWORD	in	最適化動作を制御するビットフラグ。バッチ開始/停止などを指定する。

戻り値の型: INT

公式ドキュメント

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

戻り値

この関数は、次のいずれかのリターンコードを含む 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 を使用すると、オンラインデフラグを無効にしたり、データベース空間ツリーのみ、データベースのみ、ストリーミングファイルのみ、またはこれらの組み合わせに対して選択的に有効にしたりできます。オンラインデフラグのシステム設定が廃止された設定になっている場合、JetDefragment はその設定を JET_OnlineDefragAll として扱います。

各データベースに対して実行できるタスクは最大 1 つです。このタスクは、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	JetDefragmentW (Unicode) および JetDefragmentA (ANSI) として実装されています。

各言語での呼び出し定義

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

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

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

<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetDefragmentW(
    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
    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
' grbit : DWORD
Declare PtrSafe Function JetDefragmentW Lib "esent" ( _
    ByVal sesid As LongPtr, _
    ByVal dbid As Long, _
    ByVal szTableName As LongPtr, _
    ByVal pcPasses As LongPtr, _
    ByVal pcSeconds 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

JetDefragmentW = ctypes.windll.esent.JetDefragmentW
JetDefragmentW.restype = ctypes.c_int
JetDefragmentW.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
    wintypes.DWORD,  # grbit : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetDefragmentW = Fiddle::Function.new(
  lib['JetDefragmentW'],
  [
    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_INT,  # grbit : DWORD
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "esent")]
extern "system" {
    fn JetDefragmentW(
        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
        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 JetDefragmentW(UIntPtr sesid, uint dbid, IntPtr szTableName, IntPtr pcPasses, IntPtr pcSeconds, uint grbit);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetDefragmentW' -Namespace Win32 -PassThru
# $api::JetDefragmentW(sesid, dbid, szTableName, pcPasses, pcSeconds, grbit)

#uselib "ESENT.dll"
#func global JetDefragmentW "JetDefragmentW" wptr, wptr, wptr, wptr, wptr, wptr
; JetDefragmentW sesid, dbid, varptr(szTableName), varptr(pcPasses), varptr(pcSeconds), 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"
; grbit : DWORD -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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