JetRetrieveColumn 函数

适用于： Windows |Windows Server

JetRetrieveColumn 函数

JetRetrieveColumn 函数从当前记录中检索单个列值。 记录是与光标当前位置的索引项关联的记录。 或者，此函数可以从在游标复制缓冲区中创建的记录中检索列。 此函数还可以从引用当前记录的索引项中检索列数据。 除了检索实际的列值外， JetRetrieveColumn 还可用于检索列的大小，然后再检索列数据本身，以便可以适当调整应用程序缓冲区的大小。

    JET_ERR JET_API JetRetrieveColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __out_opt     void* pvData,
      __in          unsigned long cbData,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit,
      __in_out_opt  JET_RETINFO* pretinfo
    );

参数

sesid

用于此调用的会话。

tableid

要用于此调用的游标。

columnid

要检索的列的 JET_COLUMNID 。

可以给出 列 id 值 0 (零) ，它本身不引用任何单独的列。 给定 columnid 0 (零) 时，所有标记列、稀疏列和多值列都被视为单个列。 这有助于检索记录中存在的所有稀疏列。

pvData

接收列值的输出缓冲区。

cbData

输出缓冲区的最大大小（以字节为单位）。

2013

接收列值的实际大小（以字节为单位）。

如果此参数为 NULL，则不会返回列值的实际大小。

grbit

一组位，其中包含要用于此调用的选项，其中包括以下零个或多个内容：

值	含义
JET_bitRetrieveCopy	此标志使检索列检索修改后的值而不是原始值。 如果尚未修改该值，则检索原始值。 这样，在插入或更新记录的操作期间，可以检索尚未插入或更新的值。
JET_bitRetrieveFromIndex	如果可能，此选项用于从索引中检索列值，而无需访问记录。 这样，当索引条目本身提供了所需的数据时，可以避免不必要的记录加载。 如果由于不可逆的转换或数据截断而无法从索引中检索原始列值，则将访问记录并正常检索数据。 这是一个性能选项，应仅在可能从索引中检索列值时指定。 如果当前索引是聚集索引，则不应指定此选项，因为聚集索引或主索引的索引条目是记录本身。 如果同时设置JET_bitRetrieveFromPrimaryBookmark，则无法设置此位。
JET_bitRetrieveFromPrimaryBookmark	此选项用于从索引书签检索列值，当列同时出现在主索引和当前索引中时，此选项可能与索引值不同。 如果当前索引是聚集索引或主索引，则不应指定此选项。 如果同时设置JET_bitRetrieveFromIndex，则无法设置此位。
JET_bitRetrieveTag	此选项用于检索 pretinfo-itagSequence> 中多值列值的序列号。 itagSequence 字段通常是用于从记录中检索多值列值的输入。 但是，从索引中检索值时，还可以将索引项与特定序列号相关联，并检索此序列号。 检索序列号可能是一项成本高昂的操作，仅在必要时才应执行。
JET_bitRetrieveNull	此选项用于检索多值列 NULL 值。 如果未指定此选项，将自动跳过多值列 NULL 值。
JET_bitRetrieveIgnoreDefault	此选项仅影响多值列，并导致当请求的序列号为 1 且记录中的列没有设置值时返回 NULL 值。
JET_bitRetrieveLongId	此标志仅供内部使用，不应在应用程序中使用。
JET_bitRetrieveLongValueRefCount	此标志仅供内部使用，不应在应用程序中使用。
JET_bitRetrieveTuple	此标志将允许检索索引的元组段。 必须使用 JET_bitRetrieveFromIndex 指定此位。

pretinfo

如果 pretinfo 给定为 NULL ，则函数的行为就像给定 了 itagSequence 1 和 ibLongValue 0 (零) 一样。 这会导致列检索检索多值列的第一个值，并检索偏移量为 0 (零) 的长数据。

此参数用于提供以下一项或多项：

值	含义
ibLongValue	检索列值的一部分时，为长列值提供二进制偏移量。
itagSequence	提供所需多值列值的序列号。 请注意，仅当指定了JET_bitRetrieveTag时，才会设置此字段。 否则，它是未修改的。
columnidNextTagged	使用传递列 ID 0 (零) 检索所有标记、稀疏和多值列时，返回返回的 列值的列 ID。

返回值

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

返回代码	说明
JET_errSuccess	操作已成功完成。
JET_errBadColumnId	给定的列 ID 超出了列 ID 的法定限制。
JET_errBadItagSequence	在 pretinfo-itagSequence> 中传递了无效的多值列序列号值。 多值列值序列号的有效值为 1 或更大。 对于此函数，值为 0 (零) 无效。
JET_errClientRequestToStopJetService	无法完成操作，因为与会话关联的实例上的所有活动都因调用 JetStopService 而停止。
JET_errColumnNotFound	表中不存在由给定 columnid 描述的列。
JET_errIndexTuplesCannotRetrieveFromIndex	无法从索引中检索索引为子字符串的列，因为每个索引条目中通常只存在列的一小部分。
JET_errInstanceUnavailable	无法完成操作，因为与会话关联的实例遇到严重错误，要求撤销对所有数据的访问权限以保护该数据的完整性。 此错误仅由 Windows XP 及更高版本返回。
JET_errInvalidBufferSize	在某些情况下，为检索列给定的缓冲区必须具有足够的大小才能返回任意数量的列值。 例如，将托管可更新列调整为在调用会话的事务上下文中保持一致，此调整需要调用方提供的缓冲区。 如果提供的缓冲区空间不足，则返回JET_errInvalidBufferSize，并且不返回任何列数据。
JET_errInvalidParameter	给定的一个或多个参数不正确。 如果 retinfo.cbStruct 小于 JET_RETINFO 的大小，则可能会发生这种情况。
JET_errInvalidgrbit	提供的选项未知或已知位设置的非法组合。
JET_errNoCurrentRecord	光标未定位在记录上。 导致这种情况发生的原因有很多。 例如，如果光标当前位于当前索引上最后一条记录之后，则会发生此情况。
JET_errNotInitialized	无法完成操作，因为与会话关联的实例尚未初始化。
JET_errRestoreInProgress	无法完成该操作，因为正在对与会话关联的实例执行还原操作。
JET_errSessionSharingViolation	同一会话不能同时用于多个线程。 Windowsxp： 此错误仅由 Windows XP 及更高版本返回。
JET_errTermInProgress	无法完成操作，因为正在关闭与会话关联的实例。
JET_wrnBufferTruncated	无法检索整个列值，因为给定的缓冲区小于列的大小。
JET_wrnColumnNull	检索到的列值为 NULL。

成功后，给定列的列值将复制到给定缓冲区中。 将复制小于所有列值，并返回警告JET_wrnBufferTruncated。 如果给定 了该参数 ，则返回列值的实际大小。 请注意， NULL 值的长度为 0 (零) ，因此会将返回的大小设置为 0 (零) 。 如果检索到的列是多值列，并且给定 了 pretinfo ，并且JET_bitReturnTag设置为选项，则列值的序列号以 pretinfo-itagSequence> 返回。

失败时，游标位置保持不变，并且不会将数据复制到提供的缓冲区中。

备注

此调用仅用于检索非多值列的固定或已知大小的数据一次。 但是，当列数据的大小未知时，此调用通常会使用两次。 首先调用它来确定数据的大小，以便它可以分配必要的存储空间。 然后，再次执行相同的调用以检索列数据。 当值的实际数目未知时，由于列是多值列，调用通常使用三次。 首先获取值数，然后再获取两次以分配存储和检索实际数据。

检索多值列的所有值可以通过使用 pretinfo-itagSequence> 值从 1 开始并在每次后续调用时递增来重复调用此函数来完成。 已知在从函数返回JET_wrnColumnNull时检索最后一列值。 请注意，如果多值列的值序列中设置了显式 NULL 值，则无法执行此方法，因为这些值将被跳过。 如果应用程序需要检索所有多值列值（包括那些显式设置为 NULL 的值），则必须使用 JetRetrieveColumns 而不是 JetRetrieveColumn。 请注意，当给定 itagSequence 值为 0 (零) 时，此函数不会返回多值函数的值数。 当传递 itagSequence 值为 0 (零) 时，只有 JetRetrieveColumns 将返回列值的数目。

例如，如果在事务级别 0 (零) 调用此函数，则调用会话本身不在事务中，则事务在函数中打开和关闭。 这样做的目的是在长值跨数据库页的情况下返回一致的结果。 请注意，当会话不在事务中时，该事务在函数调用和对此函数的一系列调用之间释放，可能会返回在首次调用此函数后更新的数据。

如果未将列显式设置为另一个值，除非设置了 JET_bitRetrieveIgnoreDefault 选项，否则将检索默认列值。

在插入规范化数据到多个表中时，从复制缓冲区检索自动递增列值是唯一标识链接记录的常用方法。 自动增加值在插入操作开始时分配，并且可以随时从复制缓冲区检索，直到更新完成。

检索所有标记、多值和稀疏列时，通过将 columnid 设置为 0 (零) ，按 columnid 顺序从最低 columnid 到最高 columnid 检索 列。 每次检索列值时，都会返回相同的列值顺序。 顺序是确定性的。

要求

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

另请参阅

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_RETINFO
JetSetColumn
JetRetrieveColumns