JetRetrieveColumns 函数

适用于：Windows |Windows服务器

JetRetrieveColumns 函数

JetRetrieveColumns 函数从单个操作中的当前记录中检索多个列值。 JET_RETRIEVECOLUMN结构的数组用于描述要检索的列值集，以及描述要检索的每个列值的输出缓冲区。

    JET_ERR JET_API JetRetrieveColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_out_opt  JET_RETRIEVECOLUMN* pretrievecolumn,
      __in          unsigned long cretrievecolumn
    );

参数

sesid

要用于此调用的会话。

tableid

用于此调用的游标。

pretrievecolumn

指向一个或多个 JET_RETRIEVECOLUMN 结构的数组的指针。 每个结构都包含要检索的列值以及存储返回的数据的位置的说明。

cretrievecolumn

由 pretrievecolumn 给出的数组中的JET_RETRIEVECOLUMN结构数。

返回值

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

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

成功后，列数据和列大小在 JET_RETRIEVECOLUMN 结构数组中所述的缓冲区中返回。 如果 itagSequence 设置为 0 (零) 以指示需要多值字段的实例数而不是列数据，则会在 itagSequence 字段本身中返回多值列的实例数。 每个 JET_RETRIEVECOLUMN 结构都有一个错误字段，其中包含检索的列的警告。 如果列为 NULL 值，则错误代码将设置为JET_wrnColumnNull。

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

注解

JetRetrieveColumns 支持 JetRetrieveColumn 不支持的一项功能。 这是检索多值列实例数的功能。 此功能的目的是允许应用程序检索列的所有值。 这可以通过首先确定列具有的值数来完成。 接下来，可以通过再次调用 JetRetrieveColumns 来确定其长度，并为每个值分配了一 个JET_RETRIEVECOLUMN 结构，以确定列数据的长度。 为此，可以使用 cbMax 为 0 (零) 传递 NULLpvData 指针，并在 cbActual 中检索列长度。 可以使用为列值数据分配的内存进行第三次和最后一次调用。

如果由于长度缓冲区不足而截断检索的任何列，则 API 将返回JET_wrnBufferTruncated。 但是，其他错误JET_wrnColumnNull仅在 JET_RETRIEVECOLUMN的错误字段中返回。 原因是应用程序通常希望确保已检索所有数据，并从 JetRetrieveColumns 返回此错误有助于理解。

要求

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

另请参阅

JET_ERR
JET_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns