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。 请务必注意，此操作不会导致回调以清理所选对象的上下文句柄的先前值。 可以使用带有 JET_bitLSReset 的 JetGetLS 来正确清理以前的上下文句柄。 有关详细信息，请参阅 JetGetLS 。
JET_bitLSTable	此选项指示上下文句柄应与给定游标关联的表相关联。 将此选项用于JET_bitLSCursor是非法的。 如果尝试此操作，操作将失败并JET_errInvalidgrbit。

返回值

此函数返回具有以下返回代码之一 的JET_ERR 数据类型。 有关可能的 ESE 错误的详细信息，请参阅 可扩展存储引擎错误 和 错误处理参数。

返回代码	说明
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 将其加载到缓存中。 应用程序可以通过调用具有 JET_bitLSReset的 JetGetLS 来清除缓存。 如果数据库引擎清除缓存，则会生成运行时回调，使应用程序有机会清理该上下文。 回调类型将为与游标关联的上下文句柄JET_cbtypFreeCursorLS，对于与表关联的上下文句柄JET_cbtypFreeTableLS。 在任一情况下，上下文句柄都将作为 pvArg1 传递。 有关详细信息 ，请参阅JET_CALLBACK 。

必须先为与给定会话关联的实例正确配置运行时回调，然后才能使用本地存储。 可以使用 JetSetSystemParameter和 JET_paramRuntimeCallback 设置此回调。 有关详细信息 ，请参阅 JetSetSystemParameter 和系统参数中的 JET_paramRuntimeCallback 。

要求

要求	值
客户端	需要 Windows Vista 或 Windows XP。
服务器	需要 Windows Server 2008 或 Windows Server 2003。
标头	在 Esent.h 中声明。
Library	使用 ESENT.lib。
DLL	需要ESENT.dll。

另请参阅

JET_CALLBACK
JET_ERR
JET_GRBIT
JET_LS
JET_SESID
JET_TABLEID
JetGetLS
JetSetSystemParameter
系统参数