ホーム › Storage.Jet › JetGetTruncateLogInfoInstanceW

JetGetTruncateLogInfoInstanceW

関数

切り捨て可能なログファイル一覧を取得する(Unicode版)。

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

シグネチャ

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

INT JetGetTruncateLogInfoInstanceW(
    JET_INSTANCE instance,
    WORD* wszzLogs,   // optional
    DWORD cbMax,
    DWORD* pcbActual   // optional
);

パラメーター

名前	型	方向	説明
instance	JET_INSTANCE	in	情報取得対象のインスタンスを識別するJET_INSTANCEハンドル。
wszzLogs	WORD*	outoptional	切り詰め可能なログファイル一覧を受け取る出力Unicode文字列バッファポインタ。NUL区切りの多重文字列となる。
cbMax	DWORD	in	wszzLogsバッファのサイズをバイト単位で指定する値。
pcbActual	DWORD*	outoptional	実際に必要/書き込まれたバイト数を受け取る出力ポインタ。

戻り値の型: INT

公式ドキュメント

JetGetTruncateLogInfoInstance 関数は、JetBeginExternalBackup によって開始されたバックアップ中に、バックアップが正常に完了した後で安全に削除できるトランザクションログファイルの名前をインスタンスに問い合わせるために使用します。

戻り値

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

戻り値コード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errInvalidParameter	指定されたパラメーターのいずれかに想定外の値が含まれていたか、複数のパラメーター値の組み合わせが想定外の結果になりました。 Windows XP 以降: JetGetTruncateLogInfoInstance では、指定されたインスタンスハンドルが無効な場合にこれが発生することがあります。
JET_errNotInitialized	セッションに関連付けられたインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errClientRequestToStopJetService	JetStopService の呼び出しによって、セッションに関連付けられたインスタンス上のすべての動作が停止したため、操作を完了できません。
JET_errInstanceUnavailable	セッションに関連付けられたインスタンスで、データの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。 Windows XP: この戻り値は Windows XP で導入されました。
JET_errBackupAbortByServer	JetStopBackup の呼び出しによって現在の外部バックアップが中止されたため、操作は失敗しました。 Windows XP: この戻り値は Windows XP で導入されました。
JET_errInvalidBackupSequence	順序どおりに呼び出されなかったため、バックアップ操作は失敗しました。
JET_errNoBackup	外部バックアップが実行されていないため、操作は失敗しました。
JET_errRestoreInProgress	セッションに関連付けられたインスタンスで復元操作が進行中のため、操作を完了できません。
JET_errTermInProgress	セッションに関連付けられたインスタンスがシャットダウン中のため、操作を完了できません。
JetGetTruncateLogInfoInstance	そのインスタンスに対して JetOpenFile を使用して作成されたファイルハンドルが、まだ解放されずに残っています。

この関数が成功すると、バックアップが正常に完了した後で安全に削除できるトランザクションログファイルのセットに関する要求された情報が、指定された出力バッファーに格納されます。バックアップの状態遷移が進み、データベースファイルのバックアップは以降許可されなくなります。この時点以降は、データベースのパッチファイルとトランザクションログファイルのみをバックアップ用に開くことができます。

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

解説

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

要件

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

各言語での呼び出し定義

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

INT JetGetTruncateLogInfoInstanceW(
    JET_INSTANCE instance,
    WORD* wszzLogs,   // optional
    DWORD cbMax,
    DWORD* pcbActual   // optional
);

[DllImport("ESENT.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int JetGetTruncateLogInfoInstanceW(
    UIntPtr instance,   // JET_INSTANCE
    IntPtr wszzLogs,   // WORD* optional, out
    uint cbMax,   // DWORD
    IntPtr pcbActual   // DWORD* optional, out
);

<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetGetTruncateLogInfoInstanceW(
    instance As UIntPtr,   ' JET_INSTANCE
    wszzLogs As IntPtr,   ' WORD* optional, out
    cbMax As UInteger,   ' DWORD
    pcbActual As IntPtr   ' DWORD* optional, out
) As Integer
End Function

' instance : JET_INSTANCE
' wszzLogs : WORD* optional, out
' cbMax : DWORD
' pcbActual : DWORD* optional, out
Declare PtrSafe Function JetGetTruncateLogInfoInstanceW Lib "esent" ( _
    ByVal instance As LongPtr, _
    ByVal wszzLogs As LongPtr, _
    ByVal cbMax As Long, _
    ByVal pcbActual 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

JetGetTruncateLogInfoInstanceW = ctypes.windll.esent.JetGetTruncateLogInfoInstanceW
JetGetTruncateLogInfoInstanceW.restype = ctypes.c_int
JetGetTruncateLogInfoInstanceW.argtypes = [
    ctypes.c_size_t,  # instance : JET_INSTANCE
    ctypes.POINTER(ctypes.c_ushort),  # wszzLogs : WORD* optional, out
    wintypes.DWORD,  # cbMax : DWORD
    ctypes.POINTER(wintypes.DWORD),  # pcbActual : DWORD* optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetGetTruncateLogInfoInstanceW = Fiddle::Function.new(
  lib['JetGetTruncateLogInfoInstanceW'],
  [
    Fiddle::TYPE_UINTPTR_T,  # instance : JET_INSTANCE
    Fiddle::TYPE_VOIDP,  # wszzLogs : WORD* optional, out
    -Fiddle::TYPE_INT,  # cbMax : DWORD
    Fiddle::TYPE_VOIDP,  # pcbActual : DWORD* optional, out
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

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

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

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

出力引数:

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