ホーム › Storage.Jet › JetOSSnapshotFreezeA

JetOSSnapshotFreezeA

関数

スナップショット作成のためESEインスタンスの書き込みを凍結する(ANSI版)。

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

シグネチャ

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

INT JetOSSnapshotFreezeA(
    JET_OSSNAPID snapId,
    DWORD* pcInstanceInfo,
    JET_INSTANCE_INFO_A** paInstanceInfo,
    DWORD grbit
);

パラメーター

名前	型	方向	説明
snapId	JET_OSSNAPID	in	対象のスナップショットセッション識別子。
pcInstanceInfo	DWORD*	out	返されるインスタンス情報配列の要素数を受け取る出力ポインタ。
paInstanceInfo	JET_INSTANCE_INFO_A**	out	凍結された各インスタンスの情報配列を受け取る出力ポインタ(ANSI)。
grbit	DWORD	in	予約済み。通常は0を指定するフラグ引数。

戻り値の型: INT

公式ドキュメント

JetOSSnapshotFreeze 関数はスナップショットを開始します。スナップショットの実行中は、エンジンによるディスクへの書き込み動作は一切行われません。

戻り値

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

戻り値コード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errInvalidParameter	出力パラメーターに指定されたポインターが NULL であるか、スナップショットセッションが無効であるか、または grbit パラメーターが無効です。
JET_errOSSnapshotInvalidSequence	スナップショットセッションが、フリーズを開始するのに適切な状態にありません (たとえば、このセッションで以前にフリーズが失敗している場合など)。
JET_errOSSnapshotNotAllowed	エンジンがスナップショットを実行できる状態にありません。1 つ以上のストリーミングバックアップが既に実行中であるか、1 つ以上のインスタンスが回復処理中または終了処理中です。
JET_errOSSnapshotInvalidSnapId	スナップショットセッションの識別子が無効です。
JET_errOutOfMemory	メモリ不足のため、関数が失敗しました。
JET_errOutOfThreads	フリーズを実行する新しいスレッドの開始に失敗したため、関数が失敗しました。

この関数が成功した場合、フリーズされたインスタンスに属するデータベースファイルおよびログファイルに対して、書き込み I/O は一切発行されません。また、インスタンス情報が適切に設定されるため、後で、返されたインスタンス情報配列へのポインターを指定して JetFreeBuffer を呼び出し、解放する必要があります。

この関数が失敗した場合、エンジンは通常どおり実行を続け、I/O も通常どおり発生します。フリーズが失敗した場合に JetOSSnapshotThaw を呼び出す必要はありません。また、インスタンス情報は設定されないため、このリソースを解放する必要もありません。

解説

フリーズ期間中は、アタッチされているデータベースやトランザクションログに対して書き込み I/O は発行されません。ただし、一時データベースやストリーミングファイルに対しては書き込み I/O が発行される場合があります。

フリーズ中のデータベースおよびログファイルの状態 (ボリュームスナップショットイメージ内でそれらのファイルが取る状態) は、後でそれらのファイルを復元した場合に通常の回復処理が可能となるような状態になります。

フリーズ期間中は書き込み操作が行われないため、エンジンに対する通常の API 呼び出しがその間停止することがあります。クライアントアプリケーションは、フリーズが発生した場合に API 呼び出しが通常より長い時間を要する可能性に対応できる必要があります。

上記のような影響が生じ得るため、内部タイムアウトが設けられており、解凍 (thaw) または中止 (abort) を行う API が呼び出されなかった場合でも、タイムアウト後にスナップショットセッションはフリーズフェーズを終了します。タイムアウトの値は、JET_paramOSSnapshotTimeout システムパラメーターを使用して変更できます。なお、一般的なフリーズ間隔は 10 秒程度で、既定のタイムアウトは 60 秒前後です。

要件

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

各言語での呼び出し定義

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

INT JetOSSnapshotFreezeA(
    JET_OSSNAPID snapId,
    DWORD* pcInstanceInfo,
    JET_INSTANCE_INFO_A** paInstanceInfo,
    DWORD grbit
);

[DllImport("ESENT.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int JetOSSnapshotFreezeA(
    UIntPtr snapId,   // JET_OSSNAPID
    out uint pcInstanceInfo,   // DWORD* out
    IntPtr paInstanceInfo,   // JET_INSTANCE_INFO_A** out
    uint grbit   // DWORD
);

<DllImport("ESENT.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function JetOSSnapshotFreezeA(
    snapId As UIntPtr,   ' JET_OSSNAPID
    <Out> ByRef pcInstanceInfo As UInteger,   ' DWORD* out
    paInstanceInfo As IntPtr,   ' JET_INSTANCE_INFO_A** out
    grbit As UInteger   ' DWORD
) As Integer
End Function

' snapId : JET_OSSNAPID
' pcInstanceInfo : DWORD* out
' paInstanceInfo : JET_INSTANCE_INFO_A** out
' grbit : DWORD
Declare PtrSafe Function JetOSSnapshotFreezeA Lib "esent" ( _
    ByVal snapId As LongPtr, _
    ByRef pcInstanceInfo As Long, _
    ByVal paInstanceInfo 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

JetOSSnapshotFreezeA = ctypes.windll.esent.JetOSSnapshotFreezeA
JetOSSnapshotFreezeA.restype = ctypes.c_int
JetOSSnapshotFreezeA.argtypes = [
    ctypes.c_size_t,  # snapId : JET_OSSNAPID
    ctypes.POINTER(wintypes.DWORD),  # pcInstanceInfo : DWORD* out
    ctypes.c_void_p,  # paInstanceInfo : JET_INSTANCE_INFO_A** out
    wintypes.DWORD,  # grbit : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetOSSnapshotFreezeA = Fiddle::Function.new(
  lib['JetOSSnapshotFreezeA'],
  [
    Fiddle::TYPE_UINTPTR_T,  # snapId : JET_OSSNAPID
    Fiddle::TYPE_VOIDP,  # pcInstanceInfo : DWORD* out
    Fiddle::TYPE_VOIDP,  # paInstanceInfo : JET_INSTANCE_INFO_A** out
    -Fiddle::TYPE_INT,  # grbit : DWORD
  ],
  Fiddle::TYPE_INT)

#[link(name = "esent")]
extern "system" {
    fn JetOSSnapshotFreezeA(
        snapId: usize,  // JET_OSSNAPID
        pcInstanceInfo: *mut u32,  // DWORD* out
        paInstanceInfo: *mut *mut JET_INSTANCE_INFO_A,  // JET_INSTANCE_INFO_A** 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 JetOSSnapshotFreezeA(UIntPtr snapId, out uint pcInstanceInfo, IntPtr paInstanceInfo, uint grbit);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetOSSnapshotFreezeA' -Namespace Win32 -PassThru
# $api::JetOSSnapshotFreezeA(snapId, pcInstanceInfo, paInstanceInfo, grbit)

#uselib "ESENT.dll"
#func global JetOSSnapshotFreezeA "JetOSSnapshotFreezeA" sptr, sptr, sptr, sptr
; JetOSSnapshotFreezeA snapId, varptr(pcInstanceInfo), varptr(paInstanceInfo), grbit   ; 戻り値は stat
; snapId : JET_OSSNAPID -> "sptr"
; pcInstanceInfo : DWORD* out -> "sptr"
; paInstanceInfo : JET_INSTANCE_INFO_A** out -> "sptr"
; grbit : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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