ReserveAndAppendLog function (clfsw32.h)

  • Article

Reserves space for log buffers, or appends a log record to the log, or does both. The function is atomic.

Syntax

CLFSUSER_API BOOL ReserveAndAppendLog(
  [in]                PVOID             pvMarshal,
  [in, optional]      PCLFS_WRITE_ENTRY rgWriteEntries,
  [in]                ULONG             cWriteEntries,
  [in, optional]      PCLFS_LSN         plsnUndoNext,
  [in, optional]      PCLFS_LSN         plsnPrevious,
  [in]                ULONG             cReserveRecords,
  [in, out, optional] LONGLONG []       rgcbReservation,
  [in]                ULONG             fFlags,
  [out, optional]     PCLFS_LSN         plsn,
  [in, out, optional] LPOVERLAPPED      pOverlapped
);

Parameters

[in] pvMarshal

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

[in, optional] rgWriteEntries

A pointer to an array of CLFS_WRITE_ENTRY buffers to be marshaled into one record.

This parameter is ignored if the cWriteEntries parameter is zero.

[in] cWriteEntries

The number of write entries in the rgWriteEntries array.

If this value is nonzero, you must specify a buffer in the rgWriteEntries parameter.

[in, optional] plsnUndoNext

A pointer to a CLFS_LSN structure that specifies the log sequence number (LSN) of the next record in the undo-chain.

[in, optional] plsnPrevious

A pointer to a CLFS_LSN structure that specifies the LSN of the previous record in the previous-chain.

[in] cReserveRecords

The number of record sizes in the rgcbReservation array.

[in, out, optional] rgcbReservation

A pointer to an array of reservation sizes for each record that the cReserveRecords parameter specifies.

This parameter is ignored if the cReserveRecords parameter is zero. If a reservation size is negative, a reservation of that size is released.

The actual space that is reserved for each record, including required overhead, is returned in the individual array elements on successful completion. These values can be passed to the FreeReservedLog function to adjust space that is reserved in the marshaling area.

[in] fFlags

The flags that specify the behavior of this function.

One or more of the following values can be combined.

Value Meaning
CLFS_FLAG_FORCE_APPEND
 Assigns a physical location for all appended records in a log that have not been previously assigned a physical location.

All these records are made available for reading from other marshaling contexts.
CLFS_FLAG_FORCE_FLUSH
 Assigns a physical location for all appended records in a log that have not been previously assigned a physical location.

All these records are made available for reading from other marshaling contexts. Then, the records are flushed to disk.
CLFS_FLAG_NO_FLAGS
 Assigns no flags.
CLFS_FLAG_USE_RESERVATION
 Appends the current record by using the space that is reserved in the marshaling area.

[out, optional] plsn

A pointer to a CLFS_LSN structure that receives the LSN of the appended record.

[in, out, optional] pOverlapped

A pointer to an OVERLAPPED structure.

This parameter can be NULL if 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 the GetLastError function.

The following list identifies the possible error codes:

Remarks

The LSN that is returned by the ReserveAndAppendLog function is not necessarily the next LSN that is used. The LSN that is returned is an estimate of the next LSN, and it varies based on which flags are specified by the fFlags parameter. The LSN that is returned can be used when moving the base tail. This LSN is invalidated by the next call to this function.

If the ReserveAndAppendLog function returns ERROR_LOG_FILE_FULL, there is no more space in the log. This can be resolved in one of the following ways:

  • Free any unneeded reservations.
  • Advance the base LSN or the log archive tail, or both, to recycle containers.
  • Add containers to the log.
The CLFS Management API also provides a way to handle scenarios involving full logs.

If the ReserveAndAppendLog function is called with a valid pOverlapped structure and the log handle is created with the overlapped option, then if a call to this function fails with an error code 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 log record copy, the client should first synchronize its execution with deferred completion of the overlapped I/O operation by using the GetOverlappedResult function, or one of the synchronization Wait Functions. For more information, see Synchronization and Overlapped Input and Output.

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

See also

CLFS_LSN

CLFS_WRITE_ENTRY

Common Log File System Functions

OVERLAPPED