JetSetColumn 函数

2025-06-10

适用于： Windows |Windows Server

JetSetColumn 函数

JetSetColumn 函数修改要插入的已修改记录中的单个列值或更新当前记录。它可以覆盖现有值，将新值添加到多值列中的值序列，从多值列中的值序列中删除值，或者更新长值的全部或部分值、类型为JET_coltypLongText 或 JET_coltypLongBinary的列。

    JET_ERR JET_API JetSetColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit,
      __in_opt      JET_SETINFO* psetinfo
    );

参数

sesid

要用于此调用的会话。

tableid

要用于此调用的游标。

columnid

要检索的列的JET_COLUMNID 。或者，可以给定 列 id 值为 0（零）。如果给定 columnid 0 （零），则所有标记的列、稀疏列和多值列都被视为单个列。这有助于检索记录中存在的所有稀疏列。

pvData

包含要用于列值的数据的输入缓冲区。

cbData

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

grbit

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

价值	含义
JET_bitSetAppendLV	此选项用于将数据追加到 JET_coltypLongText 或 JET_coltypLongBinary类型的列。可以通过确定现有长值的大小并在 psetinfo 中指定 ibLongValue 来实现相同的行为。但是，使用此 grbit 更简单，因为知道现有列值的大小没有必要。
JET_bitSetOverwriteLV	此选项将现有长值替换为新提供的数据。使用此选项时，就好像在设置新数据之前，现有长值已设置为 0（零）长度。
JET_bitSetRevertToDefaultValue	此选项仅适用于带标记、稀疏或多值列。它会导致列在后续检索列作中返回默认列值。删除所有现有列值。
JET_bitSetSeparateLV	此选项用于强制JET_coltypLongText或 JET_coltypLongBinary类型的长值列与记录数据的其余部分分开存储。当长值的大小阻止它与剩余的记录数据一起存储时，通常会发生这种情况。但是，此选项可用于强制单独存储长值。请注意，长值 4 个字节的大小不能强制为单独的大小。在这种情况下，将忽略该选项。
JET_bitSetSizeLV	此选项用于将输入缓冲区解释为整数字节数，以设置为给定 columnid 描述的长值的长度，如果提供，则为 psetinfo-itagSequence> 中的序列号。如果给定的大小大于现有列值，则以 0s 扩展列。如果大小小于现有列值，则将截断该值。
JET_bitSetUniqueMultiValues	此选项用于强制实施多值列中的所有值都是不同的。此选项将源列数据（没有任何转换）与其他现有列值进行比较，如果找到重复项，则返回错误。如果提供了此选项，则不能同时提供JET_bitSetAppendLV、JET_bitSetOverwriteLV和JET_bitSetSizeLV。
JET_bitSetUniqueNormalizedMultiValues	此选项用于强制实施多值列中的所有值都是不同的。此选项将列数据的关键规范化转换与其他类似转换的现有列值进行比较，如果找到重复项，则返回错误。如果提供了此选项，则不能同时提供JET_bitSetAppendLV、JET_bitSetOverwriteLV和JET_bitSetSizeLV。
JET_bitSetZeroLength	此选项用于将值设置为零长度。通常，列值通过传递 cbMax 为 0（零）设置为 NULL 。但是，对于某些类型（如 JET_coltypText），列值可以是 0（零）长度而不是 NULL，此选项用于区分 NULL 和 0（零）长度。注意通常，如果列是固定长度的列，则忽略此位，并且该列设置为 NULL。但是，如果列是固定长度标记列，则列长度设置为 0。当固定长度标记列设置为 0 长度时，尝试使用 JetRetrieveColumn 或 JetRetrieveColumns 检索列将成功，但 cbActual 参数中返回的实际长度为 0。
JET_bitSetIntrinsicLV	此选项用于将整个长值存储在记录中。
JET_bitSetCompressed	此选项用于在存储数据时尝试数据压缩。 Windows 7： Windows 7 中引入了JET_bitSetCompressed。
JET_bitSetUncompressed	在存储数据时，不会使用此选项尝试压缩。 Windows 7： Windows 7 中引入了JET_bitSetUnCompressed。

psetinfo

指向可以使用 JET_SETINFO 结构为此函数设置的可选输入参数的指针。

如果 psetinfo 被指定为 NULL ，则函数的行为就像 1 的 itagSequence 和 0（零）的 ibLongValue 一样。这会导致列集设置多值列的第一个值，并设置从偏移量 0（零）开始的长数据。

可以为此参数设置以下选项：

价值	含义
ibLongValue	二进制偏移量到应开始设置数据的长列值。
itagSequence	要设置的所需多值列值的序列号。如果 itagSequence 设置为 0（零），则应将所提供的值追加到多值值的序列的末尾。如果提供的序列号大于最后一个现有多值值值，则给定值再次追加到值序列的末尾。如果序列号对应于现有值，则将该值替换为给定值。

返回值

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

返回代码	DESCRIPTION
JET_errSuccess	操作已成功完成。
JET_errBadColumnId	给定的列 ID 超出了列 ID 的法律限制。
JET_errClientRequestToStopJetService	无法完成该作，因为由于调用 JetStopService 而停止了与会话关联的实例上的所有活动。
JET_errColumnNotFound	表中不存在由给定 columnid 描述的列。
JET_errColumnNotUpdatable	在插入复制删除原始更新作期间，非法尝试更新长值。
JET_errColumnTooBig	输入缓冲区中给定的给定列值数据超出了固定长度列或为固定长度文本或二进制列配置的固定长度列的自然大小限制。在为长列传递超过 1024 字节的数据并设置JET_bitSetIntrinsicLV标志时，也会返回此错误。
JET_err实例不可用	无法完成该作，因为与会话关联的实例遇到了一个致命错误，要求撤销对所有数据的访问以保护该数据的完整性。 Windows XP：此错误仅由 Windows XP 和更高版本返回。
JET_errInvalidBufferSize	给定的列值数据大小与固定长度数据类型的自然值不匹配。
JET_errInvalidColumnType	非法尝试在插入或更新作期间更新自动递增列，或在替换作期间更新版本列。
JET_errInvalidgrbit	提供的选项未知或已知位设置的非法组合。
JET_errInvalidParameter	给定的 psetinfo-cbStruct> 不是 JET_SETINFO 结构的有效大小。
JET_errMultiValuedDuplicate	设置列作尝试创建重复值，并指定JET_bitSetUniqueMultiValues或JET_bitSetUniqueNormalizedMultiValues。
JET_errNotInitialized	无法完成该作，因为尚未初始化与会话关联的实例。
JET_errNotInTransaction	在调用会话不在事务中时，尝试更新长列值。
JET_errNullInvalid	非法尝试将非 NULL 列设置为 NULL。
JET_errColumnIllegalNull	与JET_errNullInvalid相同。
JET_errRecordTooBig	无法将列值设置为输入缓冲区中的值，因为它会导致记录超出其页面大小相关大小限制。 JET_coltypLongText或JET_coltypLongBinary类型的列可以独立于剩余的记录数据进行存储。但是，其他列必须随记录一起存储，并可能导致超过记录大小限制。即使是长列也需要记录中的 5 字节空间作为链接，这也可能导致返回JET_errRecordTooBig。
JET_errRestoreInProgress	无法完成该作，因为与会话关联的实例正在进行还原作。
JET_errSessionSharingViolation	同一会话不能同时用于多个线程。 Windows XP：此错误仅由 Windows XP 和更高版本返回。
JET_errTermInProgress	无法完成该作，因为与会话关联的实例正在关闭。
JET_errUpdateNotPrepared	游标当前不在插入新记录或更新现有记录的过程中。
JET_errVersionStoreOutOfMemory	当版本存储的已配置大小不足以保存所有未完成的更新时，将发生此错误。
JET_wrnColumnMaxTruncated	输入缓冲区中的列值超过了可变长度列的最大配置长度，并且被截断。

成功后，使用从输入缓冲区复制的数据设置给定列的列值的所需部分。如果数据集超出了为可变长度列指定的最大长度，则数据集可能会被截断。

失败时，游标位置保持不变，并且复制缓冲区中没有更新列值数据。

注解

仅当调用会话位于事务中时，才应设置长值（类型为JET_coltypLongText或JET_coltypLongBinary的列JET_coltypLongBinary的值）。如果调用会话不在事务中，即使更新作稍后取消，对单独存储的长值的修改也可能完全提交。如果调用会话位于事务中，则可以通过取消更新并回滚会话事务来完全回滚更新的影响。

由于 JetSetColumn 作，索引更新不会执行。相反，只有在完成所有列修改并调用 JetUpdate 之后，才会更新索引。这允许在索引涉及修改多个列时，对索引进行最有效的更新。

记录的大小根据数据库页大小进行限制。如果记录中的数据超出了 JetSetColumn 作的限制，则记录中大于 5 个字节的任何长值都将与记录分开存储。只有在所有可分离记录列数据与记录分开存储并且记录仍超过记录大小限制之后，才会返回错误JET_errRecordTooBig。

要求

要求	价值
客户	需要 Windows Vista、Windows XP 或 Windows 2000 Professional。
服务器	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
标头	在 Esent.h 中声明。
图书馆	使用 ESENT.lib。
DLL	需要 ESENT.dll。

另请参阅

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns

通过

JetSetColumn 函数

JetSetColumn 函数

参数

返回值

注解

要求

另请参阅

反馈

其他资源