PrepareLogArchive function (clfsw32.h)

Article
10/13/2021

Prepares a physical log for archival. The function takes a snapshot of the current active log, builds an ordered set of log archive descriptors for the active log extents, and returns a log archive context.

By passing this log archive context to GetNextLogArchiveExtent, a client can iterate through the set of log archive extents to archive the log. You can also specify a range of records to archive.

Syntax

CLFSUSER_API BOOL PrepareLogArchive(
  [in]            HANDLE                    hLog,
  [in, out]       PWSTR                     pszBaseLogFileName,
  [in]            ULONG                     cLen,
  [in, optional]  const PCLFS_LSN           plsnLow,
  [in, optional]  const PCLFS_LSN           plsnHigh,
  [out, optional] PULONG                    pcActualLength,
  [out]           PULONGLONG                poffBaseLogFileData,
  [out]           PULONGLONG                pcbBaseLogFileLength,
  [out]           PCLFS_LSN                 plsnBase,
  [out]           PCLFS_LSN                 plsnLast,
  [out]           PCLFS_LSN                 plsnCurrentArchiveTail,
  [out]           PCLFS_LOG_ARCHIVE_CONTEXT ppvArchiveContext
);

Parameters

[in] hLog

A handle to the log that is obtained by a successful call to CreateLogFile.

This handle can be the handle to a dedicated or multiplexed log.

[in, out] pszBaseLogFileName

A pointer to a user-allocated buffer to receive the fully qualified path of the base log.

If the buffer is not large enough, it contains a truncated file path on exit, and the function fails with an ERROR_BUFFER_OVERFLOW status code.

The length of the file path is returned in the variable pointed to by pcActualLength. The client can re-attempt a failed call with a name buffer that is large enough.

[in] cLen

The size of the pszBaseLogFileName buffer, in wide characters.

[in, optional] plsnLow

A pointer to a CLFS_LSN structure that specifies the log sequence number (LSN) of the low end of the range of the active log where the log client needs log archival information.

If this parameter is omitted, the low end of the range defaults to the LSN of the log archive tail.

[in, optional] plsnHigh

A pointer to a CLFS_LSN structure that specifies the LSN of the high end of the range of the active log where the log client needs log archival information.

If this parameter is omitted, the high end of the range defaults to the next LSN to be written to the log.

[out, optional] pcActualLength

A pointer to a variable that receives the actual length of the name of the base log path, in characters.

If this value is greater than cLen, the function returns an ERROR_BUFFER_OVERFLOW status with a truncated path that is stored in the pszBaseLogFileName buffer and all other out parameters that are not set to meaningful values.

[out] poffBaseLogFileData

A pointer to a variable that receives the offset where the metadata begins in the base log.

The contiguous extent in the base log pszBaseLogFileName represents the full contents of the log metadata—that is, from poffBaseLogFileData to pcbBaseLogFileLength.

[out] pcbBaseLogFileLength

A pointer to a variable that specifies the exact length of the base log, in bytes.

[out] plsnBase

A pointer to a CLFS_LSN structure to receive the base log sequence number (LSN) of the active log.

[out] plsnLast

A pointer to a CLFS_LSN structure to receive the highest valid LSN in the active log.

[out] plsnCurrentArchiveTail

A pointer to a CLFS_LSN structure to receive the current LSN of the archive tail of the log.

[out] ppvArchiveContext

A pointer to the variable that receives a pointer to an archive context that the system allocates.

The archive context maintains the cursor state of the archival iterator and the log handle context. The archival client is responsible for releasing the context by calling TerminateLogArchive.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. The following list identifies the possible error codes:

Remarks

You must call TerminateLogArchive to free the archive context, or memory leaks can occur.

Until you call TerminateLogArchive, containers that are being archived cannot be recycled.

You can only perform one archive operation at a time per handle that CreateLogFile returns.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 R2 [desktop apps only]
Target Platform	Windows
Header	clfsw32.h
Library	Clfsw32.lib
DLL	Clfsw32.dll