JetSetDatabaseSizeA

関数

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

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

シグネチャ

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

INT JetSetDatabaseSizeA(
    JET_SESID sesid,
    CHAR* szDatabaseName,
    DWORD cpg,
    DWORD* pcpgReal
);

パラメーター

名前	型	方向	説明
sesid	JET_SESID	in	データベースサイズ設定を行うセッションのJET_SESIDハンドル。
szDatabaseName	CHAR*	in	対象データベースファイルのパスを指す終端付きANSI文字列ポインタ。
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 は同じ数値です。サイズを調整するデータベースは、整合状態 (consistent state) と呼ばれるクリーンシャットダウンの状態でなければなりません。整合していないデータベースは破損しているわけではありませんが、ログファイルの再生が必要です。
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  (ANSI / -A)
#include <windows.h>

INT JetSetDatabaseSizeA(
    JET_SESID sesid,
    CHAR* szDatabaseName,
    DWORD cpg,
    DWORD* pcpgReal
);

[DllImport("ESENT.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int JetSetDatabaseSizeA(
    UIntPtr sesid,   // JET_SESID
    IntPtr szDatabaseName,   // CHAR*
    uint cpg,   // DWORD
    out uint pcpgReal   // DWORD* out
);

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

' sesid : JET_SESID
' szDatabaseName : CHAR*
' cpg : DWORD
' pcpgReal : DWORD* out
Declare PtrSafe Function JetSetDatabaseSizeA Lib "esent" ( _
    ByVal sesid As LongPtr, _
    ByVal szDatabaseName As LongPtr, _
    ByVal cpg As Long, _
    ByRef pcpgReal As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

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

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetSetDatabaseSizeA = Fiddle::Function.new(
  lib['JetSetDatabaseSizeA'],
  [
    Fiddle::TYPE_UINTPTR_T,  # sesid : JET_SESID
    Fiddle::TYPE_VOIDP,  # szDatabaseName : CHAR*
    -Fiddle::TYPE_INT,  # cpg : DWORD
    Fiddle::TYPE_VOIDP,  # pcpgReal : DWORD* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "esent")]
extern "system" {
    fn JetSetDatabaseSizeA(
        sesid: usize,  // JET_SESID
        szDatabaseName: *mut i8,  // CHAR*
        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.Ansi)]
public static extern int JetSetDatabaseSizeA(UIntPtr sesid, IntPtr szDatabaseName, uint cpg, out uint pcpgReal);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetSetDatabaseSizeA' -Namespace Win32 -PassThru
# $api::JetSetDatabaseSizeA(sesid, szDatabaseName, cpg, pcpgReal)

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

出力引数:

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