JetSetColumn 函数

适用于： 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
    );

parameters

sesid

用于此调用的会话。

tableid

用于此调用的游标。

columnid

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

pvData

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

cbData

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

grbit

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

值	含义
JET_bitSetAppendLV	此选项用于将数据追加到 类型为 JET_coltypLongText 或 JET_coltypLongBinary 的列。 可以通过确定现有长值的大小并在 psetinfo 中指定 ibLongValue 来实现相同的行为。 但是，使用此 grbit 更简单，因为不需要知道现有列值的大小。
JET_bitSetOverwriteLV	此选项用于将现有 long 值替换为新提供的数据。 使用此选项时，好像在设置新数据之前，现有 long 值已设置为 0 (零) 长度。
JET_bitSetRevertToDefaultValue	此选项仅适用于标记、稀疏或多值列。 它会导致列在后续检索列操作中返回默认列值。 删除所有现有列值。
JET_bitSetSeparateLV	此选项用于强制将JET_coltypLongText或JET_coltypLongBinary类型的长值与记录数据的其余部分分开存储。 当长值的大小阻止它与剩余记录数据一起存储时，通常会发生这种情况。 但是，此选项可用于强制单独存储长值。 请注意，不能强制分隔大小较小的四个字节的长值。 在这种情况下，将忽略 选项。
JET_bitSetSizeLV	此选项用于将输入缓冲区解释为整数字节数，以设置为给定 columnid 描述的长值的长度，如果提供，则为 psetinfo-itagSequence> 中的序列号。 如果给定的大小大于现有列值，则列将扩展为 0。 如果大小小于现有列值，则会截断该值。
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 错误的详细信息，请参阅 可扩展存储引擎错误 和 错误处理参数。

返回代码	说明
JET_errSuccess	操作已成功完成。
JET_errBadColumnId	给定的列 ID 超出了列 ID 的法律限制。
JET_errClientRequestToStopJetService	无法完成操作，因为由于调用 JetStopService，与会话关联的实例上的所有活动都已停止。
JET_errColumnNotFound	表中不存在由给定 columnid 描述的列。
JET_errColumnNotUpdatable	在插入副本删除原始更新操作期间，非法尝试更新长值。
JET_errColumnTooBig	输入缓冲区中给定的列值数据超出了固定长度列的自然大小限制，或者为固定长度文本或二进制列配置的大小限制。 为长列传递超过 1024 字节的数据并设置JET_bitSetIntrinsicLV标志时，也会返回此错误。
JET_errInstanceUnavailable	无法完成操作，因为与会话关联的实例遇到严重错误，要求撤销对所有数据的访问权限以保护该数据的完整性。 Windowsxp： 此错误仅由 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	同一会话不能同时用于多个线程。 Windowsxp： 此错误仅由 Windows XP 及更高版本返回。
JET_errTermInProgress	无法完成操作，因为正在关闭与会话关联的实例。
JET_errUpdateNotPrepared	光标当前不在插入新记录或更新现有记录的过程中。
JET_errVersionStoreOutOfMemory	当版本存储的配置大小不足以容纳所有未完成的更新时，将发生此错误。
JET_wrnColumnMaxTruncated	输入缓冲区中的列值超出了可变长度列的最大配置长度，并且被截断。

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

失败时，游标位置保持不变，复制缓冲区中不会更新任何列值数据。

备注

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

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

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

要求

要求	值
客户端	需要 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_SETINFO
JetRetrieveColumn
JetSetColumns