JetEnumerateColumns 函数

项目
06/13/2023

适用于： Windows |Windows Server

JetEnumerateColumns 函数

JetEnumerateColumns 函数从游标的当前记录或该游标的副本缓冲区中有效地检索一组列及其值。检索的列和值可以受列 ID、 itagSequence 编号和其他特征的列表的限制。此列检索 API 是唯一的，因为它返回使用用户提供的与重新分配兼容的回调获取的动态分配内存中的信息。这种新的灵活性允许高效检索具有特定特征 (（例如调用方未知的大小和多重) ）的列数据。这样就无需使用 JetRetrieveColumn 的发现模式来确定这些特征，从而设置对 JetRetrieveColumn 的最终调用，以成功检索所需数据。

Windows XP：JetEnumerateColumns 在 Windows XP 中引入。

    JET_ERR JET_API JetEnumerateColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long cEnumColumnId,
      __in_opt      JET_ENUMCOLUMNID* rgEnumColumnId,
      __out         unsigned long* pcEnumColumn,
      __out         JET_ENUMCOLUMN** prgEnumColumn,
      __in          JET_PFNREALLOC pfnRealloc,
      __in          void* pvReallocContext,
      __in          unsigned long cbDataMost,
      __in          JET_GRBIT grbit
    );

parameters

sesid

用于此调用的会话。

tableid

用于此调用的游标。

cEnumColumnId

列 ID 的数组，每个列 ID 都具有要枚举的 itagSequence 数字的可选数组。

如果 cEnumColumnId 为 0 (零) 则忽略 rgEnumColumnId ，并枚举所有列值并将其返回到调用方。如果列 ID 数组的元素引用列 ID 为 0 (零) 则跳过该列的枚举，并将在输出中生成列状态为JET_wrnColumnSkipped的相应槽。

如果列 ID 数组的给定元素 的 ctagSequence 为 0 (零) ，则 忽略 rgtagSequence ，并枚举该列 ID 的所有列值并将其返回到调用方。如果 itagSequence 数字数组的元素引用 itagSequence 编号为 0 (零) 则跳过该 itagSequence 编号的枚举，并且输出中的相应槽将生成列值状态为JET_wrnColumnSkipped。

rgEnumColumnId

请参阅 cEnumColumnId。

pcEnumColumn

返回通过提供的 itagSequence 兼容回调分配的内存中的列的枚举数组及其值。

如果在输入时请求列 ID 数组，则输出数组的顺序和大小将反映输入数组的顺序和大小。同样，如果在输入时为特定列 ID 请求 itagSequence 数字数组，则该列值的输出数组的顺序和大小将反映输入数组的顺序和大小。

输出参数设置为 0 (零 ) ，如果 出现任何错误，则JET_errBadColumnId和JET_errColumnNotFound除外。返回这些错误时，除受影响列 ID 的所有输出数据都有效且完整。每个受影响的列 ID 的状态代码都设置为这些错误之一，以便调用方可以确定哪些列 ID 是错误的，并可能采取纠正措施。

prgEnumColumn

请参阅 pcEnumColumn。

pfnRealloc

标识与重新定位兼容的回调以及用于为列及其值的输出数组分配内存的可选上下文指针。

pvReallocContext

请参阅 pfnRealloc。

cbDataMost

设置要从长文本或长二进制列返回的数据量的上限。

此参数可用于防止枚举非常大的列值。通常，此类枚举可能会使 API 调用失败，并JET_errOutOfMemory。如果以这种方式截断大型列值，则列值的状态将JET_wrnColumnTruncated。

grbit

一组指定以下选项的零个或多个位。

值	含义
JET_bitEnumerateCompressOutput	枚举列值时，可以压缩格式返回要检索所有值且只有一个非 NULL 列值的所有列。此类列的状态将设置为JET_wrnColumnSingleValue，列值的大小和包含列值的内存将直接在 JET_ENUMCOLUMN 结构中返回。不能保证以这种方式压缩所有符合条件的列。有关详细信息，请参阅JET_ENUMCOLUMN 。
JET_bitEnumerateCopy	此选项指示应枚举记录的修改列值，而不是原始列值。如果未修改列值，则会枚举原始列值。这样，在插入或更新记录时，可能会枚举尚未插入或更新的列值。与 JetRetrieveColumn 或 JetRetrieveColumns 一起使用时，此选项与 JET_bitRetrieveCopy 相同。
JET_bitEnumerateIgnoreDefault	如果记录中不存在给定列，则不会返回任何列值。通常，在这种情况下，将返回列的默认值（如果有）。可以保证，如果列设置为与默认值不同的值，则返回不同的值 (即，如果具有默认值的列显式设置为 NULL ，则 NULL 将作为该列的值返回) 。请注意，即使请求了此选项，仍可以看到恰好等于默认值的列值。不努力删除与默认值匹配的列值。请务必注意，此选项在与 JET_bitEnumeratePresenceOnly 或 JET_bitEnumerateTaggedOnly 一起使用时会影响 JetEnumerateColumns 的输出。
JET_bitEnumerateIgnoreUserDefinedDefault	如果记录中不存在给定列，并且该列具有用户定义的默认值，则不会返回任何列值。此选项将阻止在枚举该列的值时调用计算该列的用户定义的默认值的回调。 Windows Server 2003 及更早版本：对于 Windows Server 2003 及更早版本，操作将失败并出现JET_errCallbackFailed。 Windows Server 2003 SP1：此可能的值仅适用于 Windows Server 2003 SP1 及更高版本的操作系统。如果指定了此可能的值，并且表中包含具有用户定义的默认值的列，则操作将失败并JET_errCallbackFailed。
JET_bitEnumeratePresenceOnly	如果请求的列或列值存在非 NULL 值，则不会返回关联的数据。相反，该列或列值的关联状态将设置为JET_wrnColumnPresent。如果列或列值为 NULL ，则JET_wrnColumnNull将照常返回。
JET_bitEnumerateTaggedOnly	例如，当枚举记录中的所有列值 (，即 cEnumColumnId 为零) 时，将仅返回标记的列值。枚举特定列 ID 数组时，不允许使用此选项。
JET_bitEnumerateInRecordOnly	Windows 7： Windows 7 中引入了JET_bitEnumerateInRecordOnly。

返回值

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

返回代码	描述
JET_errSuccess	操作已成功完成。
JET_errBadColumnId	给定的列 ID 超出了列 ID 的法律限制。如果请求了特定的列 ID，其中一个列 ID 无效，并且第一个无效列 ID 失败，并且其列状态代码出现此错误，则 JetEnumerateColumns 将返回此错误。
JET_errClientRequestToStopJetService	无法完成操作，因为由于调用 JetStopService，与会话关联的实例上的所有活动都已停止。
JET_errColumnNotFound	表中不存在由给定列 ID 描述的列。如果请求了特定的列 ID，其中一个列 ID 无效，并且第一个无效列 ID 失败并显示其列状态代码，则 JetEnumerateColumns 将返回此错误。
JET_errInstanceUnavailable	无法完成该操作，因为与会话关联的实例遇到一个致命错误，该错误要求撤销对所有数据的访问以保护该数据的完整性。 Windowsxp：此错误仅由 Windows XP 和更高版本返回。
JET_errInvalidgrbit	请求的选项之一无效或未实现。在以下情况下， JetEnumerateColumns 将返回此错误：指定JET_bitEnumerateLocal。指定了非法 grbit 。
JET_errInvalidParameter	提供的其中一个参数包含意外值，或者包含与另一个参数的值组合时没有意义的值。在以下情况下， JetEnumerateColumns 将返回此错误： pcEnumColumn 为 NULL。 prgEnumColumn 为 NULL。 pfnRealloc 为 NULL。
JET_errNoCurrentRecord	光标未定位在记录上。导致这种情况发生的原因有很多。例如，如果光标当前位于当前索引上最后一条记录之后，则会发生此情况。
JET_errNotInitialized	无法完成操作，因为与会话关联的实例尚未初始化。
JET_errRecordDeleted	光标位于已删除的记录上。导致这种情况发生的原因有很多。最常见的原因是会话不在事务中，游标位于记录上，该记录已被删除，然后游标尝试引用该记录。
JET_errRestoreInProgress	无法完成该操作，因为正在对与会话关联的实例执行还原操作。
JET_errSessionSharingViolation	同一会话不能同时用于多个线程。 Windowsxp：此错误仅由 Windows XP 及更高版本返回。
JET_errTermInProgress	无法完成操作，因为正在关闭与会话关联的实例。

成功后，请求的数据将在输出缓冲区中返回。调用方负责释放此回调分配并在输出缓冲区中返回的任何内存。应通过提供的与 realloc 兼容的回调释放该内存。不会更改数据库状态。

失败时，将不返回任何请求的数据。调用期间分配的任何内存都将使用提供的与 realloc 兼容的回调自动释放。不会更改数据库状态。

备注

如果要枚举记录中的所有列值，并且未指定JET_bitEnumerateIgnoreDefaults则不能假定永远不会看到状态代码为 JET_wrnColumnNull 的列或列值。如果列具有默认值且显式设置为 NULL ，或者列是非稀疏列 (例如固定列或变量列) ，则可以看到此状态代码。

cbDataMost 参数不适用于所有列值。此参数将仅截断长文本和长二进制列值，这些值太大，以至于它们已与记录分开存储。

如果 JetEnumerateColumns 在其输出参数中返回数据，则调用方负责释放数组中的内存以及该数组中嵌入的指针引用的任何内存。

要求

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

另请参阅

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_ENUMCOLUMNID
JET_ENUMCOLUMN
JET_ENUMCOLUMNVALUE
JET_PFNREALLOC
realloc
JetRetrieveColumn
JetRetrieveColumns

JetEnumerateColumns 函数