JetExternalRestoreW

関数

ログ世代を指定して外部バックアップから復元する(Unicode版)。

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

シグネチャ

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

INT JetExternalRestoreW(
    WORD* szCheckpointFilePath,
    WORD* szLogPath,
    JET_RSTMAP_W* rgrstmap,   // optional
    INT crstfilemap,
    WORD* szBackupLogPath,
    INT genLow,
    INT genHigh,
    JET_PFNSTATUS pfn
);

パラメーター

名前	型	方向	説明
szCheckpointFilePath	WORD*	in	復元時に使用するチェックポイントファイルのパスを指す終端付きUnicode文字列ポインタ。
szLogPath	WORD*	in	復元に使用するログファイルが格納されたディレクトリのパスを指す終端付きUnicode文字列ポインタ。
rgrstmap	JET_RSTMAP_W*	inoptional	バックアップ元と復元先のデータベースパス対応を保持するJET_RSTMAP_W配列のポインタ。
crstfilemap	INT	in	rgrstmap配列の要素数を指定する値。
szBackupLogPath	WORD*	in	バックアップ時のログが格納されたディレクトリのパスを指す終端付きUnicode文字列ポインタ。
genLow	INT	in	復元に適用するログ世代の下限番号を指定する値。
genHigh	INT	in	復元に適用するログ世代の上限番号を指定する値。
pfn	JET_PFNSTATUS	in	進捗通知を受け取るステータスコールバック関数(JET_PFNSTATUS)。NULL可。

戻り値の型: INT

公式ドキュメント

JetExternalRestore 関数は、外部バックアップ API で取得した外部バックアップを復元し、復元処理中に再生するログファイル番号の範囲を指定します。これはハードリカバリーと呼ばれ、JetInit 関数が実行するソフトリカバリーに似ていますが、異なるものです。

戻り値

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

戻りコード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errOutOfMemory	操作を完了するのに十分なメモリを割り当てられなかったため、操作は失敗しました。
JET_errInvalidParameter	指定されたパラメーターのいずれかに予期しない値が含まれていたか、別のパラメーターの値と組み合わせたときに意味をなさない値が含まれていました。これは JetExternalRestore などにおいて、szTargetCheckpointPath と szTargetInstanceLogPath が「両方とも指定されている」または「両方とも指定されていない」のいずれでもない場合に発生することがあります。つまり、これらは一致している必要があり、両方を指定するか、両方を指定しないかのどちらかでなければなりません。
JET_errDatabaseCorrupted	データベースが破損しているか、認識できないファイルであることを示します。
JET_errFileNotFound	要求されたファイルが指定されたパスに見つからず、開くことができなかったため、操作は失敗しました。
JET_errInvalidPath	指定されたパスが見つからなかったため、操作は失敗しました。
JET_errRestoreOfNonBackupDatabase	復元時に指定されたデータベースファイルが、外部バックアップでバックアップされたデータベースではない場合に、このエラーが返されます。
JET_errStartingRestoreLogTooHigh	szBackupLogPath にあるログファイルのいずれかが、genLow または pLogInfo.ulGenLow で指定された値よりも小さいログ世代を持つ場合に、このエラーが返されます。
JET_errEndingRestoreLogTooLow	szBackupLogPath にあるログファイルのいずれかが、genHigh または pLogInfo.ulGenHigh で指定された値よりも大きいログ世代を持つ場合に、このエラーが返されます。
JET_errBadRestoreTargetInstance	指定された szTargetInstanceLogPath が、初期化済みのインスタンスに属していません。このエラーは Windows XP 以降でのみ返されます。
JET_errRunningInOneInstanceMode	データベースエンジンは、単一インスタンスモードでは外部復元やハードリカバリーを実行できません。このエラーは Windows XP 以降でのみ返されます。

成功した場合、rgrstmap に含まれるすべてのデータベースは完全に回復され、クリーンな状態 (整合性のとれた状態) になります。この時点で、データベースを既存のインスタンスに再マウントできます。

失敗した場合、エンジンはデータベースを回復できなかったことになります。データベースは無効な状態にあり、ハードリカバリーを再試行するには、データベース全体を再度復元する必要があります。通常、このような状況の原因は、ディスクやログの破損、その他の形でのログの管理ミス、あるいはログセットが連続していないことです。

解説

「ハード」リカバリーの仕組みを理解するには、リカバリーに 3 つのフェーズがあり、2 番目のフェーズが 2 つの部分に分かれる場合があることを理解する必要があります。フェーズ I では、バックアップされたデータベースを整合性のとれた状態にするために必要なログを再生します (増分ログの初期セットを使用することもできます)。フェーズ II では、利用可能な追加のロールフォワードログが消費され、データベースが整合性のとれた状態になります。追加のロールフォワードログの再生もここで行われます。フェーズ III はリカバリーの undo (取り消し) フェーズです。

フェーズ I: データベースを整合性のとれた状態にするために復元しなければならないログセット (またはログファイルの初期セット) の再生が行われます。基本的には、復元対象のデータベースにとって省略できないログファイルのセットの再生です。この範囲のログに欠落があると、復元は失敗します。これらのログは、szBackupLogPath パラメーターで指定したディレクトリに配置してください。

フェーズ II: 必要に応じて、増分バックアップや差分バックアップ、およびアクティブなインスタンスのログファイルから取得したロールフォワードログファイルのセットが存在する場合があります。増分バックアップや差分バックアップのログファイルの場合、それらのログファイルは szBackupLogPath または szTargetInstanceLogPath パラメーターで指定したディレクトリのいずれかに配置できます。推奨されるのは前者のディレクトリです。ロールフォワードフェーズ (フェーズ II) で使用するログは、フェーズ I で再生したものと同じログ系列に属し、フェーズ I のログから隙間なく連続してログ番号が増加している必要があります。アクティブなインスタンスが現在使用しているログファイルに完全に追いつくところまでデータベースを再生するには、szTargetInstanceLogPath および szTargetInstanceCheckpointPath パラメーターを指定する必要があります。これは、他のデータベースがそのログセットにアタッチされている状態でも実行できます。

フェーズ III: リカバリーの最終フェーズでは、コミットされていないトランザクションがロールバックされます。これには、新しいログファイルの生成とチェックポイントファイルの更新が必要です。このフェーズは「undo (取り消し)」と呼ばれることがあります。このフェーズで使用するチェックポイントファイルのパスは、フェーズ III のログの場所に対応するパスです。つまり、フェーズ III で szLogPath を使用する場合は szCheckpointFilePath が使用され、リカバリーのフェーズ III で szTargetInstanceLogPath を使用する場合は szTargetInstanceCheckpointPath が使用されます。

パスがどのように機能するかを理解するには、次のフローチャートを参照してください。

ESE_Documentation_ese1

要件

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

各言語での呼び出し定義

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

INT JetExternalRestoreW(
    WORD* szCheckpointFilePath,
    WORD* szLogPath,
    JET_RSTMAP_W* rgrstmap,   // optional
    INT crstfilemap,
    WORD* szBackupLogPath,
    INT genLow,
    INT genHigh,
    JET_PFNSTATUS pfn
);

[DllImport("ESENT.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int JetExternalRestoreW(
    ref ushort szCheckpointFilePath,   // WORD*
    ref ushort szLogPath,   // WORD*
    IntPtr rgrstmap,   // JET_RSTMAP_W* optional
    int crstfilemap,   // INT
    ref ushort szBackupLogPath,   // WORD*
    int genLow,   // INT
    int genHigh,   // INT
    IntPtr pfn   // JET_PFNSTATUS
);

<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetExternalRestoreW(
    ByRef szCheckpointFilePath As UShort,   ' WORD*
    ByRef szLogPath As UShort,   ' WORD*
    rgrstmap As IntPtr,   ' JET_RSTMAP_W* optional
    crstfilemap As Integer,   ' INT
    ByRef szBackupLogPath As UShort,   ' WORD*
    genLow As Integer,   ' INT
    genHigh As Integer,   ' INT
    pfn As IntPtr   ' JET_PFNSTATUS
) As Integer
End Function

' szCheckpointFilePath : WORD*
' szLogPath : WORD*
' rgrstmap : JET_RSTMAP_W* optional
' crstfilemap : INT
' szBackupLogPath : WORD*
' genLow : INT
' genHigh : INT
' pfn : JET_PFNSTATUS
Declare PtrSafe Function JetExternalRestoreW Lib "esent" ( _
    ByRef szCheckpointFilePath As Integer, _
    ByRef szLogPath As Integer, _
    ByVal rgrstmap As LongPtr, _
    ByVal crstfilemap As Long, _
    ByRef szBackupLogPath As Integer, _
    ByVal genLow As Long, _
    ByVal genHigh As Long, _
    ByVal pfn As LongPtr) 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

JetExternalRestoreW = ctypes.windll.esent.JetExternalRestoreW
JetExternalRestoreW.restype = ctypes.c_int
JetExternalRestoreW.argtypes = [
    ctypes.POINTER(ctypes.c_ushort),  # szCheckpointFilePath : WORD*
    ctypes.POINTER(ctypes.c_ushort),  # szLogPath : WORD*
    ctypes.c_void_p,  # rgrstmap : JET_RSTMAP_W* optional
    ctypes.c_int,  # crstfilemap : INT
    ctypes.POINTER(ctypes.c_ushort),  # szBackupLogPath : WORD*
    ctypes.c_int,  # genLow : INT
    ctypes.c_int,  # genHigh : INT
    ctypes.c_void_p,  # pfn : JET_PFNSTATUS
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetExternalRestoreW = Fiddle::Function.new(
  lib['JetExternalRestoreW'],
  [
    Fiddle::TYPE_VOIDP,  # szCheckpointFilePath : WORD*
    Fiddle::TYPE_VOIDP,  # szLogPath : WORD*
    Fiddle::TYPE_VOIDP,  # rgrstmap : JET_RSTMAP_W* optional
    Fiddle::TYPE_INT,  # crstfilemap : INT
    Fiddle::TYPE_VOIDP,  # szBackupLogPath : WORD*
    Fiddle::TYPE_INT,  # genLow : INT
    Fiddle::TYPE_INT,  # genHigh : INT
    Fiddle::TYPE_VOIDP,  # pfn : JET_PFNSTATUS
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "esent")]
extern "system" {
    fn JetExternalRestoreW(
        szCheckpointFilePath: *mut u16,  // WORD*
        szLogPath: *mut u16,  // WORD*
        rgrstmap: *mut JET_RSTMAP_W,  // JET_RSTMAP_W* optional
        crstfilemap: i32,  // INT
        szBackupLogPath: *mut u16,  // WORD*
        genLow: i32,  // INT
        genHigh: i32,  // INT
        pfn: *const core::ffi::c_void  // JET_PFNSTATUS
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ESENT.dll", CharSet = CharSet.Unicode)]
public static extern int JetExternalRestoreW(ref ushort szCheckpointFilePath, ref ushort szLogPath, IntPtr rgrstmap, int crstfilemap, ref ushort szBackupLogPath, int genLow, int genHigh, IntPtr pfn);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetExternalRestoreW' -Namespace Win32 -PassThru
# $api::JetExternalRestoreW(szCheckpointFilePath, szLogPath, rgrstmap, crstfilemap, szBackupLogPath, genLow, genHigh, pfn)

#uselib "ESENT.dll"
#func global JetExternalRestoreW "JetExternalRestoreW" wptr, wptr, wptr, wptr, wptr, wptr, wptr, wptr
; JetExternalRestoreW varptr(szCheckpointFilePath), varptr(szLogPath), varptr(rgrstmap), crstfilemap, varptr(szBackupLogPath), genLow, genHigh, pfn   ; 戻り値は stat
; szCheckpointFilePath : WORD* -> "wptr"
; szLogPath : WORD* -> "wptr"
; rgrstmap : JET_RSTMAP_W* optional -> "wptr"
; crstfilemap : INT -> "wptr"
; szBackupLogPath : WORD* -> "wptr"
; genLow : INT -> "wptr"
; genHigh : INT -> "wptr"
; pfn : JET_PFNSTATUS -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ESENT.dll"
#cfunc global JetExternalRestoreW "JetExternalRestoreW" var, var, var, int, var, int, int, sptr
; res = JetExternalRestoreW(szCheckpointFilePath, szLogPath, rgrstmap, crstfilemap, szBackupLogPath, genLow, genHigh, pfn)
; szCheckpointFilePath : WORD* -> "var"
; szLogPath : WORD* -> "var"
; rgrstmap : JET_RSTMAP_W* optional -> "var"
; crstfilemap : INT -> "int"
; szBackupLogPath : WORD* -> "var"
; genLow : INT -> "int"
; genHigh : INT -> "int"
; pfn : JET_PFNSTATUS -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ESENT.dll"
#cfunc global JetExternalRestoreW "JetExternalRestoreW" sptr, sptr, sptr, int, sptr, int, int, sptr
; res = JetExternalRestoreW(varptr(szCheckpointFilePath), varptr(szLogPath), varptr(rgrstmap), crstfilemap, varptr(szBackupLogPath), genLow, genHigh, pfn)
; szCheckpointFilePath : WORD* -> "sptr"
; szLogPath : WORD* -> "sptr"
; rgrstmap : JET_RSTMAP_W* optional -> "sptr"
; crstfilemap : INT -> "int"
; szBackupLogPath : WORD* -> "sptr"
; genLow : INT -> "int"
; genHigh : INT -> "int"
; pfn : JET_PFNSTATUS -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。