JetDefragmentA

関数

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

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

シグネチャ

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

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

パラメーター

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

戻り値の型: 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  (ANSI / -A)
#include <windows.h>

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

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

<DllImport("ESENT.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function JetDefragmentA(
    sesid As UIntPtr,   ' JET_SESID
    dbid As UInteger,   ' DWORD
    szTableName As IntPtr,   ' CHAR* 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 : CHAR* optional
' pcPasses : DWORD* optional, in/out
' pcSeconds : DWORD* optional, in/out
' grbit : DWORD
Declare PtrSafe Function JetDefragmentA 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
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

JetDefragmentA = ctypes.windll.esent.JetDefragmentA
JetDefragmentA.restype = ctypes.c_int
JetDefragmentA.argtypes = [
    ctypes.c_size_t,  # sesid : JET_SESID
    wintypes.DWORD,  # dbid : DWORD
    ctypes.POINTER(ctypes.c_byte),  # szTableName : CHAR* 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')
JetDefragmentA = Fiddle::Function.new(
  lib['JetDefragmentA'],
  [
    Fiddle::TYPE_UINTPTR_T,  # sesid : JET_SESID
    -Fiddle::TYPE_INT,  # dbid : DWORD
    Fiddle::TYPE_VOIDP,  # szTableName : CHAR* 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)

#[link(name = "esent")]
extern "system" {
    fn JetDefragmentA(
        sesid: usize,  // JET_SESID
        dbid: u32,  // DWORD
        szTableName: *mut i8,  // CHAR* 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.Ansi)]
public static extern int JetDefragmentA(UIntPtr sesid, uint dbid, IntPtr szTableName, IntPtr pcPasses, IntPtr pcSeconds, uint grbit);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetDefragmentA' -Namespace Win32 -PassThru
# $api::JetDefragmentA(sesid, dbid, szTableName, pcPasses, pcSeconds, grbit)

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

出力引数:

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