Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Writing Data Records to a CLFS Stream

There are two types of records in a Common Log File System (CLFS) stream: data records and restart records. This topic explains how to write data records to a stream. For information about how to write restart records, see Writing Restart Records to a CLFS Stream.

Before you can write data records to a CLFS stream, you must create a marshalling area by calling ClfsCreateMarshallingArea. Then you can append records to the marshalling area (which is in volatile memory), and CLFS will periodically flush the records to stable storage.

There are several variations on writing data records to a stream. For example, you can reserve space ahead of time and then write several records, or you can write records without reserving space. You can request that records you write to the marshalling area be immediately queued to stable storage, or you can let CLFS queue the records according to its policy.

For all variations on writing data records, complete the following steps.

  1. Create an array of one or more CLFS_WRITE_ENTRY structures. Each write entry structure points to a buffer that you have filled with record data.

  2. Call ClfsReserveAndAppendLog or ClfsReserveAndAppendLogAligned.

The tables in the following subsections show how to set the parameters of ClfsReserveAndAppendLog for several variations on writing a record to a stream.

Writing a single data buffer to a stream

Suppose you have a single data buffer that you want to write to a marshalling area. You are willing to let the record be flushed to stable storage according to CLFS policy, and you do not want the record to be part of any chain of records. The following table shows how to set the parameters when you call ClfsReserveAndAppendLog.

Parameter name Value

pvMarshalContext

A pointer to a marshalling area.

rgWriteEntries

A pointer to a CLFS_WRITE_ENTRY structure.

cWriteEntries

1

plsnUndoNext

CLFS_LSN_INVALID

plsnPrevious

CLFS_LSN_INVALID

cReserveRecords

0

rgcbReservation

NULL

fFlags

0

plsn

A pointer to a CLFS_LSN structure. (This is an output parameter that receives the LSN of the record that is written.)

 

Reserving space for a set of CLFS log records

You can use ClfsReserveAndAppendLog to reserve space in a marshalling area for a set of log records without actually writing any of the records. The following table shows how to set the parameters to reserve record space.

Parameter name Value

pvMarshalContext

A pointer to a marshalling area.

rgWriteEntries

NULL

cWriteEntries

0

plsnUndoNext

CLFS_LSN_INVALID

plsnPrevious

CLFS_LSN_INVALID

cReserveRecords

The number of elements in the array pointed to by rgcbReservation.

rgcbReservation

A pointer to an array of LONGLONG-typed variables. Each element in the array is the size, in bytes, of a record for which space will be reserved. Note that this is this size of the data portion of the record; you do not have to include the size of headers or padding.

fFlags

0

plsn

NULL

 

Note   Another way to reserve space in a marshalling area is to call ClfsAlignReservedLog followed by ClfsAllocReservedLog.

Writing a record to reserved space

Suppose you have already reserved space for three records whose sizes, in bytes, are 100, 200, and 300. The marshalling area has a reserved-record count of 3 and enough reserved space to hold the 600 bytes of record data, the record headers, and any padding required for alignment.

Now suppose you want to write one of those records into the reserved space in the marshalling area. The available reserved space will be reduced, and the reserved-record count will be decremented from 3 to 2. The following table shows how to set the parameters when you call ClfsReserveAndAppendLog.

Parameter name Value

pvMarshalContext

A pointer to a marshalling area.

rgWriteEntries

A pointer to an array of CLFS_WRITE_ENTRY structures.

cWriteEntries

The number of elements in the array pointed to by rgWriteEntries.

plsnUndoNext

CLFS_LSN_INVALID or the LSN of the previous record in the undo chain. For more information about the undo chain, see CLFS Log Sequence Numbers.

plsnPrevious

CLFS_LSN_INVALID or the LSN of the previous log record in the previous-LSN chain. For more information about the previous-LSN chain, see CLFS Log Sequence Numbers.

cReserveRecords

0

rgcbReservation

NULL

fFlags

CLFS_FLAG_USE_RESERVATION

plsn

A pointer to a CLFS_LSN structure. (This is an output parameter that receives the LSN of the record that is written.)

 

Writing records with aligned entries

Suppose you want to write a record that has three write entries. The write entries vary in size between 300 and 500 bytes, but you require that each write entry begins on a 512-byte boundary. The following table shows how to set the parameters of the ClfsReserveAndAppendLogAligned function.

Parameter name Value

pvMarshalContext

A pointer to a marshalling area.

rgWriteEntries

A pointer to an array of three CLFS_WRITE_ENTRY structures.

cWriteEntries

3

cbEntryAlignment

512

plsnUndoNext

CLFS_LSN_INVALID or the LSN of the previous record in the undo chain. For more information about the undo chain, see CLFS Log Sequence Numbers.

plsnPrevious

CLFS_LSN_INVALID or the LSN of the previous log record in the previous-LSN chain. For more information about the previous-LSN chain, see CLFS Log Sequence Numbers.

cReserveRecords

0

rgcbReservation

NULL

fFlags

Zero or some combination of flags that specify flush and reservation preferences.

plsn

A pointer to a CLFS_LSN structure. (This is an output parameter that receives the LSN of the record that is written.)

 

The preceding tables show only a few of the many variations on reserving record space and writing records to CLFS streams. As you think of other variations, keep the following point in mind: The actions performed by ClfsReserveAndAppendLog (or ClfsReserveAndAppendLogAligned) are atomic. For example, you can make a single call to ClfsReserveAndAppendLog that will reserve space for a record and write the record to the stream. The pair of actions (reserve, write) will either succeed as a whole or fail as a whole.

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft