ホーム › Storage.Jet › JetGetLogInfoInstance2A

JetGetLogInfoInstance2A

関数

ログ情報構造体付きでバックアップ対象ログ一覧を取得する(ANSI版)。

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

シグネチャ

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

INT JetGetLogInfoInstance2A(
    JET_INSTANCE instance,
    CHAR* szzLogs,   // optional
    DWORD cbMax,
    DWORD* pcbActual,   // optional
    JET_LOGINFO_A* pLogInfo   // optional
);

パラメーター

名前	型	方向	説明
instance	JET_INSTANCE	in	情報取得対象のインスタンスを識別するJET_INSTANCEハンドル。
szzLogs	CHAR*	outoptional	バックアップ対象のログファイル一覧を受け取る出力ANSI文字列バッファポインタ。NUL区切りの多重文字列となる。
cbMax	DWORD	in	szzLogsバッファのサイズをバイト単位で指定する値。
pcbActual	DWORD*	outoptional	実際に必要/書き込まれたバイト数を受け取る出力ポインタ。
pLogInfo	JET_LOGINFO_A*	inoutoptional	ログ世代の範囲などの追加情報を受け取るJET_LOGINFO_A構造体ポインタ。NULL可。

戻り値の型: INT

公式ドキュメント

JetGetLogInfoInstance2 関数は、JetBeginExternalBackup によって開始されたバックアップの実行中に、バックアップファイルセットに含めるべきデータベースパッチファイルおよびトランザクションログファイルの名前をインスタンスに問い合わせるために使用します。これらのファイルは、その後 JetOpenFile を使用して開き、JetReadFile を使用して読み取ることができます。

戻り値

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

戻り値コード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errBackupAbortByServer	JetStopBackup の呼び出しによって現在の外部バックアップが中止されたため、操作は失敗しました。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errClientRequestToStopJetService	JetStopService の呼び出しによって、セッションに関連付けられているインスタンス上のすべての処理が停止したため、操作を完了できません。
JET_errInstanceUnavailable	セッションに関連付けられているインスタンスで、データの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errInvalidBackupSequence	呼び出しの順序が正しくないため、バックアップ操作は失敗しました。対象のインスタンスに対して JetOpenFile で作成された未解放のファイルハンドルが存在する場合、JetGetLogInfo はこのエラーを返します。
JET_errInvalidParameter	指定されたパラメーターのいずれかに予期しない値が含まれていたか、別のパラメーターの値と組み合わせたときに意味をなさない値が含まれていました。JetGetLogInfo では、指定されたインスタンスハンドルが無効な場合にこの状況が発生することがあります (Windows XP 以降のリリース)。
JET_errNoBackup	外部バックアップが実行されていないため、操作は失敗しました。
JET_errNotInitialized	セッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errRestoreInProgress	セッションに関連付けられているインスタンスで復元操作が実行中であるため、操作を完了できません。
JET_errRunningInMultiInstanceMode	実際には複数のインスタンスが既に存在しているにもかかわらず、インスタンスを 1 つだけサポートするレガシーモード (Windows 2000 互換モード) でエンジンを使用しようとしたため、操作は失敗しました。
JET_errTermInProgress	セッションに関連付けられているインスタンスがシャットダウン処理中であるため、操作を完了できません。

成功した場合、バックアップファイルセットに含めるべきデータベースパッチファイルおよびトランザクションログファイルのセットに関する要求された情報が、指定された出力バッファーに格納されます。また、バックアップのステートマシンは、データベースファイルのバックアップが以後許可されない状態まで進みます。これ以降は、データベースパッチファイルとトランザクションログファイルのみをバックアップのために開くことができます。

失敗した場合、出力バッファーの状態は未定義です。この失敗により、そのインスタンスに対するバックアップ処理全体が取り消されます。

解説

この API は、バックアップファイルセットに含めるべきファイルの一覧全体を格納するには出力バッファーが小さすぎる場合でも、エラーや警告を返さない点に注意してください。アプリケーションは、この一覧の実際のサイズを受け取るためのバッファーを常に指定し、その情報を使用して一覧が切り捨てられたかどうかを判断する必要があります。

要件

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

各言語での呼び出し定義

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

INT JetGetLogInfoInstance2A(
    JET_INSTANCE instance,
    CHAR* szzLogs,   // optional
    DWORD cbMax,
    DWORD* pcbActual,   // optional
    JET_LOGINFO_A* pLogInfo   // optional
);

[DllImport("ESENT.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int JetGetLogInfoInstance2A(
    UIntPtr instance,   // JET_INSTANCE
    IntPtr szzLogs,   // CHAR* optional, out
    uint cbMax,   // DWORD
    IntPtr pcbActual,   // DWORD* optional, out
    IntPtr pLogInfo   // JET_LOGINFO_A* optional, in/out
);

<DllImport("ESENT.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function JetGetLogInfoInstance2A(
    instance As UIntPtr,   ' JET_INSTANCE
    szzLogs As IntPtr,   ' CHAR* optional, out
    cbMax As UInteger,   ' DWORD
    pcbActual As IntPtr,   ' DWORD* optional, out
    pLogInfo As IntPtr   ' JET_LOGINFO_A* optional, in/out
) As Integer
End Function

' instance : JET_INSTANCE
' szzLogs : CHAR* optional, out
' cbMax : DWORD
' pcbActual : DWORD* optional, out
' pLogInfo : JET_LOGINFO_A* optional, in/out
Declare PtrSafe Function JetGetLogInfoInstance2A Lib "esent" ( _
    ByVal instance As LongPtr, _
    ByVal szzLogs As LongPtr, _
    ByVal cbMax As Long, _
    ByVal pcbActual As LongPtr, _
    ByVal pLogInfo As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

JetGetLogInfoInstance2A = ctypes.windll.esent.JetGetLogInfoInstance2A
JetGetLogInfoInstance2A.restype = ctypes.c_int
JetGetLogInfoInstance2A.argtypes = [
    ctypes.c_size_t,  # instance : JET_INSTANCE
    ctypes.POINTER(ctypes.c_byte),  # szzLogs : CHAR* optional, out
    wintypes.DWORD,  # cbMax : DWORD
    ctypes.POINTER(wintypes.DWORD),  # pcbActual : DWORD* optional, out
    ctypes.c_void_p,  # pLogInfo : JET_LOGINFO_A* optional, in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetGetLogInfoInstance2A = Fiddle::Function.new(
  lib['JetGetLogInfoInstance2A'],
  [
    Fiddle::TYPE_UINTPTR_T,  # instance : JET_INSTANCE
    Fiddle::TYPE_VOIDP,  # szzLogs : CHAR* optional, out
    -Fiddle::TYPE_INT,  # cbMax : DWORD
    Fiddle::TYPE_VOIDP,  # pcbActual : DWORD* optional, out
    Fiddle::TYPE_VOIDP,  # pLogInfo : JET_LOGINFO_A* optional, in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "esent")]
extern "system" {
    fn JetGetLogInfoInstance2A(
        instance: usize,  // JET_INSTANCE
        szzLogs: *mut i8,  // CHAR* optional, out
        cbMax: u32,  // DWORD
        pcbActual: *mut u32,  // DWORD* optional, out
        pLogInfo: *mut JET_LOGINFO_A  // JET_LOGINFO_A* optional, in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ESENT.dll", CharSet = CharSet.Ansi)]
public static extern int JetGetLogInfoInstance2A(UIntPtr instance, IntPtr szzLogs, uint cbMax, IntPtr pcbActual, IntPtr pLogInfo);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetGetLogInfoInstance2A' -Namespace Win32 -PassThru
# $api::JetGetLogInfoInstance2A(instance, szzLogs, cbMax, pcbActual, pLogInfo)

#uselib "ESENT.dll"
#func global JetGetLogInfoInstance2A "JetGetLogInfoInstance2A" sptr, sptr, sptr, sptr, sptr
; JetGetLogInfoInstance2A instance, varptr(szzLogs), cbMax, varptr(pcbActual), varptr(pLogInfo)   ; 戻り値は stat
; instance : JET_INSTANCE -> "sptr"
; szzLogs : CHAR* optional, out -> "sptr"
; cbMax : DWORD -> "sptr"
; pcbActual : DWORD* optional, out -> "sptr"
; pLogInfo : JET_LOGINFO_A* optional, in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ESENT.dll"
#cfunc global JetGetLogInfoInstance2A "JetGetLogInfoInstance2A" sptr, var, int, var, var
; res = JetGetLogInfoInstance2A(instance, szzLogs, cbMax, pcbActual, pLogInfo)
; instance : JET_INSTANCE -> "sptr"
; szzLogs : CHAR* optional, out -> "var"
; cbMax : DWORD -> "int"
; pcbActual : DWORD* optional, out -> "var"
; pLogInfo : JET_LOGINFO_A* optional, in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ESENT.dll"
#cfunc global JetGetLogInfoInstance2A "JetGetLogInfoInstance2A" sptr, sptr, int, sptr, sptr
; res = JetGetLogInfoInstance2A(instance, varptr(szzLogs), cbMax, varptr(pcbActual), varptr(pLogInfo))
; instance : JET_INSTANCE -> "sptr"
; szzLogs : CHAR* optional, out -> "sptr"
; cbMax : DWORD -> "int"
; pcbActual : DWORD* optional, out -> "sptr"
; pLogInfo : JET_LOGINFO_A* optional, in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。