Win32 API 日本語リファレンス
ホーム › Storage.Jet › JetRestore2W

JetRestore2W

関数
復元先を指定してバックアップから復元する(Unicode版)。
DLLESENT.dll文字セットUnicode (-W)呼出規約winapi

シグネチャ

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

INT JetRestore2W(
    WORD* sz,
    WORD* szDest,   // optional
    JET_PFNSTATUS pfn   // optional
);

パラメーター

名前型方向説明
szWORD*in復元元バックアップが格納されたディレクトリのパスを指す終端付きUnicode文字列ポインタ。
szDestWORD*inoptional復元先ディレクトリのパスを指す終端付きUnicode文字列ポインタ。NULLで元の場所に復元する。
pfnJET_PFNSTATUSinoptional進捗通知を受け取るステータスコールバック関数(JET_PFNSTATUS)。NULL可。

戻り値の型: INT

公式ドキュメント

JetRestore2 は、接続されているすべてのデータベースを含む、インスタンスのストリーミングバックアップを復元し、回復します。この関数は主に、データベースのインスタンスを 1 つしか使用できない Windows 2000 以前のデータベースエンジンとの下位互換性のために用意されています。この場合、復元されるのはアクティブなインスタンスです。

戻り値

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

戻り値コード

説明

JET_errSuccess

操作は正常に完了しました。

JET_errAlreadyInitialized

このインスタンスのエンジンが既に初期化されているため、操作は失敗しました。

JET_errInvalidLogSequence

バックアップセットのログファイルのセットと、現在のログパスにあるログファイルのセットが一致しません。

JET_errInvalidParameter

指定されたパラメーターのいずれかに予期しない値が含まれているか、他のパラメーターの値と組み合わせたときに意味をなさない値が含まれていました。Windows XP 以降のリリースでは、エンジンがマルチインスタンスモードで動作しており、pinstance が無効なインスタンスを参照している場合に、JetRestoreInstance がこのエラーを返します。

JET_errInvalidPath

指定されたパスの一部 (バックアップパス、復元先パス、インスタンスのログパスまたはシステムパス) が無効であるため、操作は失敗しました。

JET_errPageSizeMismatch

エンジンに設定されているデータベースページサイズ (JetSetSystemParameter で JET_paramDatabasePageSize に設定した値) が、トランザクションログファイル、またはそのトランザクションログファイルに関連付けられたデータベースの作成に使用されたデータベースページサイズと一致しないため、操作は失敗しました。

JET_errRunningInMultiInstanceMode

パラメーターがシングルインスタンスモード (Windows 2000 互換モード) を示しているにもかかわらず、エンジンが既にマルチインスタンスモードになっているため、操作は失敗しました。

成功した場合、バックアップセットのデータベースファイルが元の場所に復元され、データベースがトランザクション上一貫したクリーンな状態になるように回復処理が実行されます。回復処理では、バックアップセットのログファイルと、ログパスにログファイルが存在する場合はそれらのログファイルが再実行されます。この回復処理により、チェックポイントファイル、トランザクションログファイル、およびそれらのトランザクションログファイルが参照するすべてのデータベースが変更されます。

失敗した場合、インスタンスは初期化されていない状態のままとなります。ただし、復元の初期化とデータベースの回復を試みる過程で、トランザクションログファイルおよびそれらのトランザクションログファイルが参照するデータベースの状態は変更されている可能性があります。

解説

回復処理では、バックアップ時にインスタンスに接続されていたデータベースが再構築され、その変更がデータベースファイルに書き戻されます。その結果、データベースはトランザクション上一貫した状態になります。可能であれば、バックアップの取得後からトランザクションログ内で見つかった最新の変更までの変更もデータベースに保存されます。これは、バックアップの取得後に生成されたトランザクションログがトランザクションログディレクトリに残っている場合に可能です。なお、インスタンスで循環ログが有効になっている場合は、生成されたトランザクションログが再利用されるため、回復処理で保存できるのはバックアップ時点までに行われた変更となります。いずれの場合も、データベースに対して再実行するトランザクションログファイルの数が多いと、この処理にはかなりの時間がかかることがあります。

JetRestore 系の関数は、対象のインスタンスに対して JetInit を呼び出す前に呼び出す必要があります。

回復処理では多数のデータベースページとトランザクションログが使用されるため、これらの関数からは非常に多くの種類のエラーが返される可能性があります。そのようなエラーには、Jet_errOutOfMemory のような一時的なリソース割り当ての失敗から、JET_errReadVerifyFailure、JET_errLogFileCorrupt、JET_errBadPageLink のような物理的な破損を表すものまであります。これらのエラーはほとんどの場合ハードウェアの問題が原因であり、回避することはできません。ファイルの管理不備は、多くの場合 JET_errMissingLogFile、JET_errAttachedDatabaseMismatch、JET_errDatabaseSharingViolation、JET_errInvalidLogSequence として現れます。これらのエラーはアプリケーション側で防止できます。アプリケーションは、これらのファイルの保管場所が、ユーザーや他のアプリケーションなどの外部から操作されないように注意して保護する必要があります。インスタンスを完全に破棄する場合は、そのインスタンスに関連付けられたすべてのファイルを削除する必要があります。これには、チェックポイントファイル、トランザクションログファイル、およびインスタンスに接続されているすべてのデータベースファイルが含まれます。

回復処理の各段階では、トランザクションログの再実行の進行状況や復元の最終結果など、イベントログのエントリが生成されます。

要件

要件 値

クライアント

Windows Vista、Windows XP、または Windows 2000 Professional が必要です。

サーバー

Windows Server 2008、Windows Server 2003、または Windows 2000 Server が必要です。

ヘッダー

Esent.h で宣言されています。

ライブラリ

ESENT.lib を使用します。

DLL

ESENT.dll が必要です。

Unicode

JetRestore2W (Unicode) および JetRestore2A (ANSI) として実装されています。

関連項目

JET_ERR
JET_GRBIT
JET_INSTANCE
JetBackup
JetBackupInstance
JetCreateInstance
JetInit
JetRestore
JetRestoreInstance
JetSetSystemParameter

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp)

各言語での呼び出し定義

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

INT JetRestore2W(
    WORD* sz,
    WORD* szDest,   // optional
    JET_PFNSTATUS pfn   // optional
);
[DllImport("ESENT.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int JetRestore2W(
    ref ushort sz,   // WORD*
    IntPtr szDest,   // WORD* optional
    IntPtr pfn   // JET_PFNSTATUS optional
);
<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetRestore2W(
    ByRef sz As UShort,   ' WORD*
    szDest As IntPtr,   ' WORD* optional
    pfn As IntPtr   ' JET_PFNSTATUS optional
) As Integer
End Function
' sz : WORD*
' szDest : WORD* optional
' pfn : JET_PFNSTATUS optional
Declare PtrSafe Function JetRestore2W Lib "esent" ( _
    ByRef sz As Integer, _
    ByVal szDest As LongPtr, _
    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

JetRestore2W = ctypes.windll.esent.JetRestore2W
JetRestore2W.restype = ctypes.c_int
JetRestore2W.argtypes = [
    ctypes.POINTER(ctypes.c_ushort),  # sz : WORD*
    ctypes.POINTER(ctypes.c_ushort),  # szDest : WORD* optional
    ctypes.c_void_p,  # pfn : JET_PFNSTATUS optional
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetRestore2W = Fiddle::Function.new(
  lib['JetRestore2W'],
  [
    Fiddle::TYPE_VOIDP,  # sz : WORD*
    Fiddle::TYPE_VOIDP,  # szDest : WORD* optional
    Fiddle::TYPE_VOIDP,  # pfn : JET_PFNSTATUS optional
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"
#[link(name = "esent")]
extern "system" {
    fn JetRestore2W(
        sz: *mut u16,  // WORD*
        szDest: *mut u16,  // WORD* optional
        pfn: *const core::ffi::c_void  // JET_PFNSTATUS optional
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("ESENT.dll", CharSet = CharSet.Unicode)]
public static extern int JetRestore2W(ref ushort sz, IntPtr szDest, IntPtr pfn);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetRestore2W' -Namespace Win32 -PassThru
# $api::JetRestore2W(sz, szDest, pfn)
#uselib "ESENT.dll"
#func global JetRestore2W "JetRestore2W" wptr, wptr, wptr
; JetRestore2W varptr(sz), varptr(szDest), pfn   ; 戻り値は stat
; sz : WORD* -> "wptr"
; szDest : WORD* optional -> "wptr"
; pfn : JET_PFNSTATUS optional -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
出力引数:
#uselib "ESENT.dll"
#cfunc global JetRestore2W "JetRestore2W" var, var, sptr
; res = JetRestore2W(sz, szDest, pfn)
; sz : WORD* -> "var"
; szDest : WORD* optional -> "var"
; pfn : JET_PFNSTATUS optional -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
出力引数:
; INT JetRestore2W(WORD* sz, WORD* szDest, JET_PFNSTATUS pfn)
#uselib "ESENT.dll"
#cfunc global JetRestore2W "JetRestore2W" var, var, intptr
; res = JetRestore2W(sz, szDest, pfn)
; sz : WORD* -> "var"
; szDest : WORD* optional -> "var"
; pfn : JET_PFNSTATUS optional -> "intptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	esent = windows.NewLazySystemDLL("ESENT.dll")
	procJetRestore2W = esent.NewProc("JetRestore2W")
)

// sz (WORD*), szDest (WORD* optional), pfn (JET_PFNSTATUS optional)
r1, _, err := procJetRestore2W.Call(
	uintptr(sz),
	uintptr(szDest),
	uintptr(pfn),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // INT
function JetRestore2W(
  sz: Pointer;   // WORD*
  szDest: Pointer;   // WORD* optional
  pfn: Pointer   // JET_PFNSTATUS optional
): Integer; stdcall;
  external 'ESENT.dll' name 'JetRestore2W';
result := DllCall("ESENT\JetRestore2W"
    , "Ptr", sz   ; WORD*
    , "Ptr", szDest   ; WORD* optional
    , "Ptr", pfn   ; JET_PFNSTATUS optional
    , "Int")   ; return: INT
●JetRestore2W(sz, szDest, pfn) = DLL("ESENT.dll", "int JetRestore2W(void*, void*, void*)")
# 呼び出し: JetRestore2W(sz, szDest, pfn)
# sz : WORD* -> "void*"
# szDest : WORD* optional -> "void*"
# pfn : JET_PFNSTATUS optional -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
# ※-W(Unicode)関数。なでしこ1はANSIのため -A 版の利用を推奨。
const std = @import("std");

extern "esent" fn JetRestore2W(
    sz: [*c]u16, // WORD*
    szDest: [*c]u16, // WORD* optional
    pfn: ?*anyopaque // JET_PFNSTATUS optional
) callconv(std.os.windows.WINAPI) i32;
// Unicode(-W): UTF-16LE のヌル終端バッファ([*c]const u16)を渡す。
proc JetRestore2W(
    sz: ptr uint16,  # WORD*
    szDest: ptr uint16,  # WORD* optional
    pfn: pointer  # JET_PFNSTATUS optional
): int32 {.importc: "JetRestore2W", stdcall, dynlib: "ESENT.dll".}
# Unicode(-W): WideCString は newWideCString("...") で生成。
pragma(lib, "esent");
extern(Windows)
int JetRestore2W(
    ushort* sz,   // WORD*
    ushort* szDest,   // WORD* optional
    void* pfn   // JET_PFNSTATUS optional
);
ccall((:JetRestore2W, "ESENT.dll"), stdcall, Int32,
      (Ptr{UInt16}, Ptr{UInt16}, Ptr{Cvoid}),
      sz, szDest, pfn)
# sz : WORD* -> Ptr{UInt16}
# szDest : WORD* optional -> Ptr{UInt16}
# pfn : JET_PFNSTATUS optional -> Ptr{Cvoid}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
# Unicode(-W): Cwstring には transcode(UInt16, "...") 等で UTF-16 を渡す。
local ffi = require("ffi")
ffi.cdef[[
int32_t JetRestore2W(
    uint16_t* sz,
    uint16_t* szDest,
    void* pfn);
]]
local esent = ffi.load("esent")
-- esent.JetRestore2W(sz, szDest, pfn)
-- sz : WORD*
-- szDest : WORD* optional
-- pfn : JET_PFNSTATUS optional
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
-- Unicode(-W): uint16_t* には UTF-16LE のバッファ(ffi.new("uint16_t[?]", ...))を渡す。
const koffi = require('koffi');
const lib = koffi.load('ESENT.dll');
const JetRestore2W = lib.func('__stdcall', 'JetRestore2W', 'int32_t', ['uint16_t *', 'uint16_t *', 'void *']);
// JetRestore2W(sz, szDest, pfn)
// sz : WORD* -> 'uint16_t *'
// szDest : WORD* optional -> 'uint16_t *'
// pfn : JET_PFNSTATUS optional -> 'void *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
// コールバック(関数ポインタ)は koffi.proto/koffi.register で型を定義して渡す(素の void* では JS 関数を渡せない)。
const lib = Deno.dlopen("ESENT.dll", {
  JetRestore2W: { parameters: ["pointer", "pointer", "pointer"], result: "i32" },
});
// lib.symbols.JetRestore2W(sz, szDest, pfn)
// sz : WORD* -> "pointer"
// szDest : WORD* optional -> "pointer"
// pfn : JET_PFNSTATUS optional -> "pointer"
// 文字列は "buffer"。Unicode(-W) は new TextEncoder() ではなく UTF-16LE のバイト列(末尾に \x00\x00)を Uint8Array で渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t JetRestore2W(
    uint16_t* sz,
    uint16_t* szDest,
    void* pfn);
C, "ESENT.dll");
// $ffi->JetRestore2W(sz, szDest, pfn);
// sz : WORD*
// szDest : WORD* optional
// pfn : JET_PFNSTATUS optional
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Esent extends StdCallLibrary {
    Esent INSTANCE = Native.load("esent", Esent.class, W32APIOptions.UNICODE_OPTIONS);
    int JetRestore2W(
        ShortByReference sz,   // WORD*
        ShortByReference szDest,   // WORD* optional
        Callback pfn   // JET_PFNSTATUS optional
    );
}
// Unicode(-W): WString(入力)/char[](出力)で UTF-16 をマーシャリング。
@[Link("esent")]
lib LibESENT
  fun JetRestore2W = JetRestore2W(
    sz : UInt16*,   # WORD*
    szDest : UInt16*,   # WORD* optional
    pfn : Void*   # JET_PFNSTATUS optional
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef JetRestore2WNative = Int32 Function(Pointer<Uint16>, Pointer<Uint16>, Pointer<Void>);
typedef JetRestore2WDart = int Function(Pointer<Uint16>, Pointer<Uint16>, Pointer<Void>);
final JetRestore2W = DynamicLibrary.open('ESENT.dll')
    .lookupFunction<JetRestore2WNative, JetRestore2WDart>('JetRestore2W');
// sz : WORD* -> Pointer<Uint16>
// szDest : WORD* optional -> Pointer<Uint16>
// pfn : JET_PFNSTATUS optional -> Pointer<Void>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function JetRestore2W(
  sz: Pointer;   // WORD*
  szDest: Pointer;   // WORD* optional
  pfn: Pointer   // JET_PFNSTATUS optional
): Integer; stdcall;
  external 'ESENT.dll' name 'JetRestore2W';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "JetRestore2W"
  c_JetRestore2W :: Ptr Word16 -> Ptr Word16 -> Ptr () -> IO Int32
-- sz : WORD* -> Ptr Word16
-- szDest : WORD* optional -> Ptr Word16
-- pfn : JET_PFNSTATUS optional -> Ptr ()
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let jetrestore2w =
  foreign "JetRestore2W"
    ((ptr uint16_t) @-> (ptr uint16_t) @-> (ptr void) @-> returning int32_t)
(* sz : WORD* -> (ptr uint16_t) *)
(* szDest : WORD* optional -> (ptr uint16_t) *)
(* pfn : JET_PFNSTATUS optional -> (ptr void) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library esent (t "ESENT.dll"))
(cffi:use-foreign-library esent)

(cffi:defcfun ("JetRestore2W" jet-restore2-w :convention :stdcall) :int32
  (sz :pointer)   ; WORD*
  (sz-dest :pointer)   ; WORD* optional
  (pfn :pointer))   ; JET_PFNSTATUS optional
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $JetRestore2W = Win32::API::More->new('ESENT',
    'int JetRestore2W(LPVOID sz, LPVOID szDest, LPVOID pfn)');
# my $ret = $JetRestore2W->Call($sz, $szDest, $pfn);
# sz : WORD* -> LPVOID
# szDest : WORD* optional -> LPVOID
# pfn : JET_PFNSTATUS optional -> LPVOID
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。
# コールバック(関数ポインタ)は Perl sub を直接渡せません。Win32::API::Callback を使用してください。
# Unicode(-W): LPCWSTR/LPWSTR は Win32::API が UTF-16 変換を行う。

関連項目

文字セット違い
類似 API
使用する型