PrepareLogArchive function

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


BOOL WINAPI PrepareLogArchive(
  _In_            HANDLE                    hLog,
  _Inout_         PWSTR                     pszBaseLogFileName,
  _In_            ULONG                     cLen,
  _In_opt_  const PCLFS_LSN                 plsnLow,
  _In_opt_  const PCLFS_LSN                 plsnHigh,
  _Out_opt_       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

hLog [in]

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.

pszBaseLogFileName [in, out]

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.

cLen [in]

The size of the pszBaseLogFileName buffer, in wide characters.

plsnLow [in, optional]

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.

plsnHigh [in, optional]

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.

pcActualLength [out, optional]

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.

poffBaseLogFileData [out]

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.

pcbBaseLogFileLength [out]

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

plsnBase [out]

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

plsnLast [out]

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

plsnCurrentArchiveTail [out]

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

ppvArchiveContext [out]

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:

ERROR_ACCESS_DENIED
ERROR_BUFFER_OVERFLOW
ERROR_INVALID_PARAMETER
ERROR_INVALID_OPERATION
ERROR_LOG_ARCHIVE_IN_PROGRESS
ERROR_LOG_EPHEMERAL
ERROR_NO_SYSTEM_MEMORY
ERROR_OUT_OF_MEMORY

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

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 R2 [desktop apps only]

Header

Clfsw32.h

Library

Clfsw32.lib

DLL

Clfsw32.dll

See also

CLFS_LSN
Common Log File System Functions
GetNextLogArchiveExtent
ReadLogArchiveMetadata
TerminateLogArchive

 

 

Show: