JetSetDatabaseSizeW

関数

データベースファイルのサイズをページ単位で設定する(Unicode版)。

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

シグネチャ

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

INT JetSetDatabaseSizeW(
    JET_SESID sesid,
    WORD* szDatabaseName,
    DWORD cpg,
    DWORD* pcpgReal
);

パラメーター

名前	型	方向	説明
sesid	JET_SESID	in	データベースサイズ設定を行うセッションのJET_SESIDハンドル。
szDatabaseName	WORD*	in	対象データベースファイルのパスを指す終端付きUnicode文字列ポインタ。
cpg	DWORD	in	設定する目標サイズをページ数で指定する値。
pcpgReal	DWORD*	out	実際に設定されたサイズをページ数で受け取る出力ポインタ。

戻り値の型: INT

公式ドキュメント

JetSetDatabaseSize 関数は、開かれていないデータベースファイルのサイズを設定します。

戻り値

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

戻り値コード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errDatabaseInconsistent JET_errDatabaseDirtyShutdown	JET_errDatabaseInconsistent と JET_errDatabaseDirtyShutdown は同じ数値です。サイズを変更するデータベースは、クリーンシャットダウンされた状態、つまり一貫した状態でなければなりません。一貫していないデータベースは破損しているわけではありませんが、ログファイルの再実行が必要です。
JET_errDatabaseInvalidPath	szDatabaseName は、NULL ではない空文字列であってはなりません。
JET_errDiskFull	ボリュームに、拡張操作を実行するための十分な空き領域がありません。JetSetDatabaseSize は、次を含む (ただしこれらに限定されない) さまざまなファイル関連のエラーを返すこともあります。 JET_errDiskIO JET_errFileNotFound JET_errInvalidPath JET_errFileAccessDenied JET_errOutOfFileHandles
JET_errInvalidParameter	このエラーが返される理由の 1 つは、cpg がデータベースの最小サイズを満たしていない場合です。現在のデータベースの最小サイズは 256 ページです。
JET_errOutOfMemory	システムのメモリリソースが不足しています。

解説

大量のデータを挿入する前に JetSetDatabaseSize を呼び出すと、データベースファイルは 1 回の操作で拡張されます。これにより、ファイルシステムレベルでデータベースファイルが断片化する可能性が低減され、データベースファイルを拡張する回数も減ります。データベースファイルを 1 回で拡張する方が、複数回に分けて拡張するよりも高速になる場合があります。

現在サポートされているのはファイルの拡張のみです。ファイルを縮小するには、esentutl.exe ユーティリティプログラムのデフラグ機能を使用してください。

cpg が現在のデータベースのサイズより小さい場合、この操作は無視されます。cpg がデータベースの最小サイズ (現在は 256 ページ) より小さい場合は、JET_errInvalidParameter が返されます。

開かれているデータベースのサイズを設定するには、JetGrowDatabase を参照してください。

ファイルサイズは、pcpgReal に返されるページ数と一致しない場合があります。pcpgReal にカウントされない予約済みのページが 2 ページ追加で存在します。

要件

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

各言語での呼び出し定義

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

INT JetSetDatabaseSizeW(
    JET_SESID sesid,
    WORD* szDatabaseName,
    DWORD cpg,
    DWORD* pcpgReal
);

[DllImport("ESENT.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int JetSetDatabaseSizeW(
    UIntPtr sesid,   // JET_SESID
    ref ushort szDatabaseName,   // WORD*
    uint cpg,   // DWORD
    out uint pcpgReal   // DWORD* out
);

<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetSetDatabaseSizeW(
    sesid As UIntPtr,   ' JET_SESID
    ByRef szDatabaseName As UShort,   ' WORD*
    cpg As UInteger,   ' DWORD
    <Out> ByRef pcpgReal As UInteger   ' DWORD* out
) As Integer
End Function

' sesid : JET_SESID
' szDatabaseName : WORD*
' cpg : DWORD
' pcpgReal : DWORD* out
Declare PtrSafe Function JetSetDatabaseSizeW Lib "esent" ( _
    ByVal sesid As LongPtr, _
    ByRef szDatabaseName As Integer, _
    ByVal cpg As Long, _
    ByRef pcpgReal 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

JetSetDatabaseSizeW = ctypes.windll.esent.JetSetDatabaseSizeW
JetSetDatabaseSizeW.restype = ctypes.c_int
JetSetDatabaseSizeW.argtypes = [
    ctypes.c_size_t,  # sesid : JET_SESID
    ctypes.POINTER(ctypes.c_ushort),  # szDatabaseName : WORD*
    wintypes.DWORD,  # cpg : DWORD
    ctypes.POINTER(wintypes.DWORD),  # pcpgReal : DWORD* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetSetDatabaseSizeW = Fiddle::Function.new(
  lib['JetSetDatabaseSizeW'],
  [
    Fiddle::TYPE_UINTPTR_T,  # sesid : JET_SESID
    Fiddle::TYPE_VOIDP,  # szDatabaseName : WORD*
    -Fiddle::TYPE_INT,  # cpg : DWORD
    Fiddle::TYPE_VOIDP,  # pcpgReal : DWORD* out
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "esent")]
extern "system" {
    fn JetSetDatabaseSizeW(
        sesid: usize,  // JET_SESID
        szDatabaseName: *mut u16,  // WORD*
        cpg: u32,  // DWORD
        pcpgReal: *mut u32  // DWORD* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ESENT.dll", CharSet = CharSet.Unicode)]
public static extern int JetSetDatabaseSizeW(UIntPtr sesid, ref ushort szDatabaseName, uint cpg, out uint pcpgReal);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetSetDatabaseSizeW' -Namespace Win32 -PassThru
# $api::JetSetDatabaseSizeW(sesid, szDatabaseName, cpg, pcpgReal)

#uselib "ESENT.dll"
#func global JetSetDatabaseSizeW "JetSetDatabaseSizeW" wptr, wptr, wptr, wptr
; JetSetDatabaseSizeW sesid, varptr(szDatabaseName), cpg, varptr(pcpgReal)   ; 戻り値は stat
; sesid : JET_SESID -> "wptr"
; szDatabaseName : WORD* -> "wptr"
; cpg : DWORD -> "wptr"
; pcpgReal : DWORD* out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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