WriteLogRestartArea function (clfsw32.h)

Appends a new client restart area to a log, and optionally advances the base log sequence number (LSN) of the log.

After it is successfully written to a disk, the last LSN of the log is changed to the LSN of the appended restart record. Typically, WriteLogRestartArea is used by applications that regularly save a known good state, and the restart area contains the LSNs for existing log record chains.

Syntax

CLFSUSER_API BOOL WriteLogRestartArea(
  [in, out]           PVOID        pvMarshal,
  [in]                PVOID        pvRestartBuffer,
  [in]                ULONG        cbRestartBuffer,
  [in, optional]      PCLFS_LSN    plsnBase,
  [in]                ULONG        fFlags,
  [out, optional]     PULONG       pcbWritten,
  [out, optional]     PCLFS_LSN    plsnNext,
  [in, out, optional] LPOVERLAPPED pOverlapped
);

Parameters

[in, out] pvMarshal

A pointer to the marshaling context that is allocated by using the CreateLogMarshallingArea function.

[in] pvRestartBuffer

A pointer to a buffer that contains restart data.

[in] cbRestartBuffer

The size of pvRestartBuffer, in bytes.

[in, optional] plsnBase

A pointer to a CLFS_LSN structure that specifies the new base LSN of the log after successfully writing the restart area.

This value cannot be outside the range of the active log. It must be at least the value of the current base LSN, and not greater than the LSN that was returned in the lastLSN parameter from the latest call to ReserveAndAppendLog. If you omit this optional parameter, the base LSN does not change.

[in] fFlags

The flags that specify the behavior of this function.

One or more of the following values can be combined.

[out, optional] pcbWritten

A pointer to a variable that receives the number of bytes that are written when an operation completes.

[out, optional] plsnNext

A pointer to a CLFS_LSN structure that specifies the LSN of the restart area that is written.

[in, out, optional] pOverlapped

A pointer to an OVERLAPPED structure.

This parameter can be NULL if an asynchronous operation is not used.

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

The WriteLogRestartArea causes both a flush of all current buffered log records and a flush of the log metadata.

If a client calls WriteLogRestartArea on a log that is created to support asynchronous operations (for example, if the fFlagsAndAttributes parameter of CreateLogFile is set to FILE_FLAG_OVERLAPPED when the log is created), the client must supply a pointer to a valid OVERLAPPED structure in the pOverlapped parameter of WriteLogRestartArea.

Then, if WriteLogRestartArea fails with an error of ERROR_IO_PENDING, a pointer to a valid read context is placed in the variable that is pointed to by the ppvReadContext parameter.

To complete the call, the client should synchronize its execution with deferred completion of the overlapped I/O operation by using GetOverlappedResult or one of the synchronization Wait Functions. For more information, see Synchronization and Overlapped Input and Output.

Requirements

See also

CLFS_LSN

Common Log File System Functions

OVERLAPPED