JetSetLS 函式
適用于: Windows |Windows Server
JetSetLS 函式
JetSetLS函式可讓應用程式將稱為「本機儲存體」的內容控制碼與資料指標或與該資料指標相關聯的資料表產生關聯。 應用程式可以使用此內容控制碼來儲存與資料指標或資料表相關聯的輔助資料。 應用程式稍後會在必須釋放內容控制碼時,使用執行時間回呼收到通知。 這可讓您將動態配置的狀態與資料指標或資料表產生關聯。
Windows XP:JetSetLS 是在 Windows XP 中引進。
JET_ERR JET_API JetSetLS(
__in JET_SESID sesid,
__in JET_TABLEID tableid,
__in JET_LS ls,
__in JET_GRBIT grbit
);
參數
sesid
要用於這個呼叫的會話。
tableid
要用於這個呼叫的資料指標。
ls
要與資料指標或資料表相關聯的內容控制碼。
指定JET_bitLSReset時,會忽略此參數的實際值,並使用JET_LSNil。
grbit
一組位,其中包含要用於此呼叫的選項,其中包含下列零個或多個選項。
值 |
意義 |
---|---|
JET_bitLSCursor |
此選項表示內容控制碼應該與指定的資料指標相關聯。 如果未指定JET_bitLSCursor或JET_bitLSTable,則會假設JET_bitLSCursor。 搭配使用此選項與JET_bitLSTable不合法。 如果嘗試此作業,作業將會失敗,並JET_errInvalidgrbit。 |
JET_bitLSReset |
此選項表示應該忽略指定的內容控制碼,而且所選物件的內容控制碼應該重設為JET_LSNil。 請務必注意,此動作不會產生回呼,以清除所選物件之內容控制碼的先前值。 您可以使用 JetGetLS 搭配JET_bitLSReset,來正確清除先前的內容控制碼。 如需詳細資訊,請參閱 JetGetLS 。 |
JET_bitLSTable |
此選項表示內容控制碼應該與與指定資料指標相關聯的資料表相關聯。 搭配使用此選項與JET_bitLSCursor不合法。 如果嘗試此作業,作業將會失敗,並JET_errInvalidgrbit。 |
傳回值
此函式會傳回具有下列其中一個傳回碼 的 JET_ERR 資料類型。 如需可能 ESE 錯誤的詳細資訊,請參閱 可延伸儲存引擎錯誤 和 錯誤處理參數。
傳回碼 |
Description |
---|---|
JET_errSuccess |
作業已成功完成。 |
JET_errClientRequestToStopJetService |
無法完成作業,因為與會話相關聯之實例上的所有活動因 JetStopService呼叫而停止。 |
JET_errInvalidgrbit |
要求的其中一個選項無效、未正確使用或未實作。 當同時指定JET_bitLSCursor和JET_bitLSTable時 ,JetSetLS 就會發生這種情況。 |
JET_errInstanceUnavailable |
無法完成作業,因為與會話相關聯的實例發生嚴重錯誤,需要撤銷所有資料的存取權,以保護該資料的完整性。 此錯誤只會由 Windows XP 和更新版本傳回。 |
JET_errLSAlreadySet |
指定的內容控制碼無法與要求的物件相關聯,因為它已經有與其相關聯的內容控制碼。 |
JET_errLSCallbackNotSpecified |
指定的內容控制碼無法與要求的物件相關聯,因為尚未針對與會話相關聯的實例設定執行時間回呼。 |
JET_errNotInitialized |
無法完成作業,因為與會話相關聯的實例尚未初始化。 |
JET_errRestoreInProgress |
無法完成作業,因為與會話相關聯的實例上正在進行還原作業。 |
JET_errTermInProgress |
無法完成作業,因為與會話相關聯的實例正在關閉。 |
成功時,指定的內容控制碼已成功與要求的物件相關聯。 不會變更資料庫狀態。
失敗時,不會變更所要求物件的狀態。 不會變更資料庫狀態。
備註
資料指標或資料表的本機儲存體應該視為變動性快取。 應用程式應該先嘗試使用 JetGetLS擷取內容控制碼。 如果未設定值 (JET_LSNil) 則應用程式應該建立新的內容,並使用 JetSetLS將它載入快取。 應用程式可以使用呼叫 JetGetLS 搭配JET_bitLSReset清除快取。 如果資料庫引擎清除快取,則會產生執行時間回呼,讓應用程式有機會清除該內容。 與資料指標相關聯的內容控制碼會JET_cbtypFreeCursorLS回呼類型,並針對與資料表相關聯的內容控制碼JET_cbtypFreeTableLS。 不論是哪一種情況,內容控制碼都會以 pvArg1 的形式傳遞。 如需詳細資訊 ,請參閱JET_CALLBACK 。
您必須針對與指定會話相關聯的實例正確設定執行時間回呼,才能使用本機儲存體。 您可以使用 JetSetSystemParameter 搭配 JET_paramRuntimeCallback來設定此回呼。 如需詳細資訊,請參閱系統參數中的 JetSetSystemParameter 和 JET_paramRuntimeCallback 。
規格需求
需求 | 值 |
---|---|
用戶端 |
需要 Windows Vista 或 Windows XP。 |
Server |
需要 Windows Server 2008 或 Windows Server 2003。 |
標頭 |
在 Esent.h 中宣告。 |
程式庫 |
使用 ESENT.lib。 |
Dll |
需要ESENT.dll。 |
另請參閱
JET_CALLBACK
JET_ERR
JET_GRBIT
JET_LS
JET_SESID
JET_TABLEID
JetGetLS
JetSetSystemParameter
系統參數