JetSetColumn 函数

适用于:Windows |Windows服务器

JetSetColumn 函数

JetSetColumn 函数修改要插入的修改记录中的单个列值,或更新当前记录。 它可以覆盖现有值,将新值添加到多值列中的值序列,从多值列中的值序列中删除值,或者更新长值的列、类型 为JET_coltypLongTextJET_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 。 或者,可以提供 0 (零) 的 列 id 值。 给定 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> 中的序列号。 如果给定的大小大于现有列值,则列将用 0 进行扩展。 如果大小小于现有列值,则将截断该值。

JET_bitSetUniqueMultiValues

此选项用于强制实施多值列中的所有值都是不同的。 此选项将源列数据(没有任何转换)与其他现有列值进行比较,如果找到重复项,则会返回错误。 如果提供此选项,则JET_bitSetAppendLV、JET_bitSetOverwriteLV和JET_bitSetSizeLV也不能给出。

JET_bitSetUniqueNormalizedMultiValues

此选项用于强制实施多值列中的所有值都是不同的。 此选项将列数据的关键规范化转换与其他类似转换的现有列值进行比较,如果找到重复项,则返回错误。 如果提供此选项,则JET_bitSetAppendLV、JET_bitSetOverwriteLV和JET_bitSetSizeLV也不能给出。

JET_bitSetZeroLength

此选项用于将值设置为零长度。 通常,列值通过传递 0 (零) 的 cbMax 设置为 NULL 。 但是,对于某些类型(如 JET_coltypText),列值可以是 0 (零) 长度而不是 NULL,此选项用于区分 NULL 和 0 (零) 长度。

注意 一般情况下,如果列是固定长度的列,则忽略此位,并且该列设置为 NULL。 但是,如果列是固定长度标记列,则列长度设置为 0。 当固定长度标记列设置为 0 长度时,尝试使用 JetRetrieveColumnJetRetrieveColumns 检索列将成功,但 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 ,则函数的行为类似于 itagSequence 为 1,并且给定的 ibLongValue 为 0 (零) 。 这会导致列集设置多值列的第一个值,并设置从偏移量 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

无法完成该操作,因为与会话关联的实例遇到了一个致命错误,要求撤销对所有数据的访问权限以保护该数据的完整性。

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_coltypLongTextJET_coltypLongBinary类型的列JET_coltypLongBinary设置长值。 如果调用会话不在事务中,即使更新操作稍后取消,对单独存储的长值的修改也可能完全提交。 如果调用会话位于事务中,则可以通过取消更新并回滚会话事务来完全回滚更新的影响。

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

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

要求

要求

客户端

需要 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_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn
JetSetColumns