從 CLFS 數據流讀取資料記錄

Common Log File System （CLFS） 數據流中有兩種類型的記錄：數據記錄和重新啟動記錄。 本主題說明如何從數據流讀取一連串的數據記錄。 如需如何讀取重新啟動記錄的詳細資訊，請參閱 從CLFS資料流讀取重新啟動記錄。

從數據流中讀取數據記錄有多種方法。 您可以從指定的記錄在數據流中向前讀取，也可以沿著連結的記錄鏈向後讀取。

若要讀取數據記錄序列的各種變體，請完成下列步驟。

1. 呼叫 ClfsReadLogRecord 以取得讀取內容和序列中的第一筆數據記錄。

2. 將您在步驟 1 中取得的讀取內容傳遞至 ClfsReadNextLogRecord 重複取得序列中的其餘數據記錄。

謹慎 讀取上下文不是線程安全的。 用戶端負責序列化對讀取上下文的存取權。

下列子主題會討論讀取不同類型的記錄序列和鏈結的詳細數據。

從指定的數據記錄向前讀取

若要在 CLSF 數據流中向前讀取（從您選擇的數據記錄開始），您必須建立已將其模式設定為 ClfsContextForward 的讀取內容。 若要建立讀取內容並讀取第一筆記錄（在您選擇讀取的集合中），請呼叫 ClfsReadLogRecord ，如下表所示。

參數名稱	價值
pvMarshalContext	提供封送處理區域的指標。
plsnFirst	請提供您想要讀取的第一筆記錄的 LSN。 這必須是資料記錄的 LSN，而不是重啟記錄。
peContextMode	提供 ClfsContextForward 值。
ppvReadBuffer	取得您的記錄資料。
pcbReadBuffer	獲取記錄數據的大小。
peRecordType	取得記錄類型。 這個值是一組標誌，表示記錄的不同特性。 記錄是一筆數據記錄，因此您收到的值應該已設定 ClfsDataRecord 標誌，並清除 ClfsRestartRecord 標誌。
plsnUndoNext	接收記錄的復原下一個 LSN。 您不需要此值即可繼續讀取鏈結，因此您可以忽略它。
plsnPrevious	接收先前數據記錄的 LSN。 您不需要此值即可繼續讀取鏈結，因此您可以忽略它。
ppvReadContext	接收一個用於不透明讀取上下文的指標。 使用讀取上下文來讀取後續記錄。

取得讀取內容和第一筆記錄之後，您可以重複呼叫 ClfsReadNextLogRecord ，以取得數據流中的後續記錄。 當數據流中沒有其他數據記錄時， ClfsReadNextLogRecord 會傳回STATUS_END_OF_FILE。 下表顯示如何設定和解譯參數。

參數名稱	價值
pvReadContext	提供從 ClfsReadLogRecord 收到的讀取上下文的指標。
ppvBuffer	收到您的記錄資料。
pcbBuffer	獲取記錄資料的大小。
peRecordType	提供 ClfsDataRecord 的值。
plsnUndoNext	接收資料記錄的「回退下一個 LSN」欄位。 您不需要此值即可繼續讀取鏈結，因此您可以忽略它。
plsnPrevious	取得資料記錄的 previous-LSN 欄位。 您不需要此值即可繼續讀取鏈結，因此您可以忽略它。
plsnRecord	接收已讀取之數據記錄的 LSN。

讀取由先前 LSN 連結的數據記錄鏈

當您將資料記錄寫入 CLFS 資料流時，您可以將先前的數據記錄 LSN 設定為您先前寫入資料流之任何記錄的 LSN。 藉由設定先前的 LSN，您可以建立稍後可以反向遍歷的相關記錄鏈。 例如，假設您正在執行資料庫交易，而且您必須撰寫數個 CLFS 記錄檔記錄來描述交易所做的更新。 每次寫入描述交易更新的日誌記錄時，您可以將該記錄的上一個 LSN 設定為描述相同交易更新的上一個日誌記錄的 LSN。

假設您已撰寫一串由其先前 LSN 連結的數據記錄。 若要讀取記錄鏈結，您必須建立已將其模式設定為 ClfsContextPrevious 的讀取上下文。 若要建立讀取內容並讀取鏈結中的第一筆記錄，請呼叫 ClfsReadLogRecord ，如下表所示。

參數名稱	價值
pvMarshalContext	提供封送處理區域的指標。
plsnFirst	提供鏈結中第一筆記錄的 LSN。 這必須是資料記錄的 LSN，而非重新啟動記錄。
peContextMode	提供 ClfsContextPrevious 的值。
ppvReadBuffer	接收您的記錄資料。
pcbReadBuffer	取得記錄資料的大小。
peRecordType	接收記錄類型。 這個值是一組標誌，表示記錄的各種特性。 記錄是一筆數據記錄，因此您收到的值應該已設定 ClfsDataRecord 旗標，並清除 ClfsRestartRecord 旗標。
plsnUndoNext	接收資料紀錄的撤銷下一個 LSN。 您不需要此值即可繼續讀取鏈結，因此您可以忽略它。
plsnPrevious	取得先前的數據記錄 LSN。 您不需要此值即可繼續讀取鏈結，因此您可以忽略它。
ppvReadContext	接收一個指向不透明讀取上下文的指標。 使用讀取上下文來讀取鏈結中的先前記錄。

擁有讀取內容和第一筆記錄之後，您可以重複呼叫 ClfsReadNextLogRecord 來讀取鏈結中的剩餘記錄。 下表顯示如何設定和解譯參數。

參數名稱	價值
pvReadContext	提供您從 ClfsReadLogRecord 收到的讀取上下文的指標。
ppvBuffer	接收您的記錄資料。
pcbBuffer	接收到您的記錄資料的大小。
peRecordType	提供 ClfsDataRecord 的值。
plsnUndoNext	接收資料記錄的 undo-next LSN。 您不需要此值即可繼續讀取鏈結，因此您可以忽略它。
plsnPrevious	接收數據記錄的上一個 LSN。 您不需要此值即可繼續讀取鏈結，因此您可以忽略它。
plsnRecord	接收已讀取的數據記錄的 LSN（日志序列號）。

當您對 ClfsReadNextLogRecord 進行重複呼叫時，您的呼叫順序將會以下列其中一種方式結束。

• 最後，您將會讀取到一個先前 LSN 被設定為 CLFS_LSN_INVALID 的資料紀錄。 下次呼叫 ClfsReadNextLogRecord 時，它會傳回STATUS_END_OF_FILE。

• 最後，您將讀取具有先前 LSN 的數據記錄，該記錄小於數據流的基底 LSN 和數據流的 封存結尾 。 下次呼叫 ClfsReadNextLogRecord 時，它會傳回STATUS_LOG_START_OF_LOG。

讀取由回復下一個 LSN 連結的資料記錄鏈

當您將資料記錄寫入 CLFS 資料流時，您可以將資料記錄的復原下一個 LSN 設定為您先前寫入資料流之任何記錄的 LSN。 藉由設定復原的下一個 LSN，您可以建立可以逆向瀏覽的相關紀錄鏈。 如需建立和解譯復原下一個鏈結的詳細資訊，請參閱 CLFS 記錄序號。

假設您已撰寫由其復原下一個 LSN 連結的數據記錄鏈結。 若要讀取記錄鏈結，您必須呼叫 ClfsReadLogRecord 來建立其模式設定為 ClfsContextUndoNext 的讀取內容。 之後，這個過程與讀取由先前 LSN 連結的鏈條是一致的（如本主題之前所述）。

讀取由使用者層級順序號 (LSN) 連結的數據記錄鏈條

除了先前的 LSN 鏈結和復原下一個 LSN 的鏈結之外，您還可以建立由您自己的 LSN 鏈結，將它們嵌入在記錄的數據中。

假設您已撰寫由儲存在記錄數據本身的 LSN 連結的數據記錄鏈。 若要讀取記錄鏈，您必須建立一個讀取上下文，其模式設定為 ClfsContextPrevious 或 ClfsContextUndoNext。 呼叫 ClfsReadLogRecord 來建立讀取上下文，並取得鏈結中最新寫入的記錄。 然後重複呼叫 ClfsReadNextLogRecord 以取得鏈結中的先前記錄。 每次呼叫 ClfsReadNextLogRecord 時，請將 plsnUser 參數設定為鏈結中上一筆記錄的 LSN。 您在 plsnUser 中提供的 LSN 會覆寫目前記錄中 previous-LSN 或 undo-next LSN 欄位儲存的任何值。

請注意，當您呼叫 ClfsReadNextLogRecord 以讀取記錄鏈結時，您只能在數據流中向後移動。 您在 plsnUser 中提供的 LSN 必須小於鏈結中目前記錄的 LSN。