JetExternalRestoreA

関数

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

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

シグネチャ

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

INT JetExternalRestoreA(
    CHAR* szCheckpointFilePath,
    CHAR* szLogPath,
    JET_RSTMAP_A* rgrstmap,   // optional
    INT crstfilemap,
    CHAR* szBackupLogPath,
    INT genLow,
    INT genHigh,
    JET_PFNSTATUS pfn
);

パラメーター

名前	型	方向	説明
szCheckpointFilePath	CHAR*	in	復元時に使用するチェックポイントファイルのパスを指す終端付きANSI文字列ポインタ。
szLogPath	CHAR*	in	復元に使用するログファイルが格納されたディレクトリのパスを指す終端付きANSI文字列ポインタ。
rgrstmap	JET_RSTMAP_A*	inoptional	バックアップ元と復元先のデータベースパス対応を保持するJET_RSTMAP_A配列のポインタ。
crstfilemap	INT	in	rgrstmap配列の要素数を指定する値。
szBackupLogPath	CHAR*	in	バックアップ時のログが格納されたディレクトリのパスを指す終端付きANSI文字列ポインタ。
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  (ANSI / -A)
#include <windows.h>

INT JetExternalRestoreA(
    CHAR* szCheckpointFilePath,
    CHAR* szLogPath,
    JET_RSTMAP_A* rgrstmap,   // optional
    INT crstfilemap,
    CHAR* szBackupLogPath,
    INT genLow,
    INT genHigh,
    JET_PFNSTATUS pfn
);

[DllImport("ESENT.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int JetExternalRestoreA(
    IntPtr szCheckpointFilePath,   // CHAR*
    IntPtr szLogPath,   // CHAR*
    IntPtr rgrstmap,   // JET_RSTMAP_A* optional
    int crstfilemap,   // INT
    IntPtr szBackupLogPath,   // CHAR*
    int genLow,   // INT
    int genHigh,   // INT
    IntPtr pfn   // JET_PFNSTATUS
);

<DllImport("ESENT.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function JetExternalRestoreA(
    szCheckpointFilePath As IntPtr,   ' CHAR*
    szLogPath As IntPtr,   ' CHAR*
    rgrstmap As IntPtr,   ' JET_RSTMAP_A* optional
    crstfilemap As Integer,   ' INT
    szBackupLogPath As IntPtr,   ' CHAR*
    genLow As Integer,   ' INT
    genHigh As Integer,   ' INT
    pfn As IntPtr   ' JET_PFNSTATUS
) As Integer
End Function

' szCheckpointFilePath : CHAR*
' szLogPath : CHAR*
' rgrstmap : JET_RSTMAP_A* optional
' crstfilemap : INT
' szBackupLogPath : CHAR*
' genLow : INT
' genHigh : INT
' pfn : JET_PFNSTATUS
Declare PtrSafe Function JetExternalRestoreA Lib "esent" ( _
    ByVal szCheckpointFilePath As LongPtr, _
    ByVal szLogPath As LongPtr, _
    ByVal rgrstmap As LongPtr, _
    ByVal crstfilemap As Long, _
    ByVal szBackupLogPath As LongPtr, _
    ByVal genLow As Long, _
    ByVal genHigh As Long, _
    ByVal pfn As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

JetExternalRestoreA = ctypes.windll.esent.JetExternalRestoreA
JetExternalRestoreA.restype = ctypes.c_int
JetExternalRestoreA.argtypes = [
    ctypes.POINTER(ctypes.c_byte),  # szCheckpointFilePath : CHAR*
    ctypes.POINTER(ctypes.c_byte),  # szLogPath : CHAR*
    ctypes.c_void_p,  # rgrstmap : JET_RSTMAP_A* optional
    ctypes.c_int,  # crstfilemap : INT
    ctypes.POINTER(ctypes.c_byte),  # szBackupLogPath : CHAR*
    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')
JetExternalRestoreA = Fiddle::Function.new(
  lib['JetExternalRestoreA'],
  [
    Fiddle::TYPE_VOIDP,  # szCheckpointFilePath : CHAR*
    Fiddle::TYPE_VOIDP,  # szLogPath : CHAR*
    Fiddle::TYPE_VOIDP,  # rgrstmap : JET_RSTMAP_A* optional
    Fiddle::TYPE_INT,  # crstfilemap : INT
    Fiddle::TYPE_VOIDP,  # szBackupLogPath : CHAR*
    Fiddle::TYPE_INT,  # genLow : INT
    Fiddle::TYPE_INT,  # genHigh : INT
    Fiddle::TYPE_VOIDP,  # pfn : JET_PFNSTATUS
  ],
  Fiddle::TYPE_INT)

#[link(name = "esent")]
extern "system" {
    fn JetExternalRestoreA(
        szCheckpointFilePath: *mut i8,  // CHAR*
        szLogPath: *mut i8,  // CHAR*
        rgrstmap: *mut JET_RSTMAP_A,  // JET_RSTMAP_A* optional
        crstfilemap: i32,  // INT
        szBackupLogPath: *mut i8,  // CHAR*
        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.Ansi)]
public static extern int JetExternalRestoreA(IntPtr szCheckpointFilePath, IntPtr szLogPath, IntPtr rgrstmap, int crstfilemap, IntPtr szBackupLogPath, int genLow, int genHigh, IntPtr pfn);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetExternalRestoreA' -Namespace Win32 -PassThru
# $api::JetExternalRestoreA(szCheckpointFilePath, szLogPath, rgrstmap, crstfilemap, szBackupLogPath, genLow, genHigh, pfn)

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

出力引数:

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