JetRenameColumn 函数

  • 项目

适用于： Windows |Windows Server

JetRenameColumn 函数

JetRenameColumn 函数可用于更改表上现有列的名称。

Windows XP：JetRenameColumn 是在 Windows XP 中引入的。

    JET_ERR JET_API JetRenameColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_PCSTR szName,
      __in          JET_PCSTR szNameNew,
      __in          JET_GRBIT grbit
    );

parameters

sesid

用于此调用的会话。

tableid

用于此调用的游标。

szName

要重命名的列的当前名称。

szNameNew

将重命名的列的新名称。

grbit

此参数必须为 0。

返回值

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

返回代码

说明

JET_errSuccess

操作已成功完成。

JET_errClientRequestToStopJetService

无法完成操作，因为由于调用 JetStopService，与会话关联的实例上的所有活动都已停止。

JET_errColumnNotFound

此表不存在此指定的列。

JET_errInvalidName

指定的对象名称之一无效。 所有对象名称都必须符合同一组规则。 这些规则如下：

  • 对象名称必须由 ASCII 字符组成。

  • 对象名称的长度必须至少为一个字符。

  • 对象名称的长度不得超过 JET_cbNameMost (64) 个字符。

  • 对象名称不能以空格开头 - 对象名称不能包含通过0x1F) (0x00 ASCII 控制字符。

  • 对象名称不得包含感叹号 (！) 、句点 (.) 、左括号 ([) 或右括号 (]) 字符。

  • 验证后，只有字符串的第一个空格部分 (（如果有任何) ）将用于对象名称。 这实际上意味着对象名称也可能不包含空格。

JET_errInvalidParameter

提供的其中一个参数包含意外值或包含一个值，当与另一个参数的值组合时，该值没有意义。 在以下情况下 ，JetRenameColumn 可能会发生这种情况：

  • szName 为 NULL。

  • szNameNew 为 NULL。

JET_errInstanceUnavailable

无法完成该操作，因为与会话关联的实例遇到一个致命错误，该错误要求撤销对所有数据的访问以保护该数据的完整性。 此错误仅由 Windows XP 和更高版本返回。

JET_errInTransaction

仅当会话当前不在事务中时，才能执行此操作。

JET_errNotInitialized

无法完成操作，因为尚未初始化与会话关联的实例。

JET_errRestoreInProgress

无法完成操作，因为正在与会话关联的实例上执行还原操作。

JET_errSessionSharingViolation

同一会话不能同时用于多个线程。 此错误仅由 Windows XP 和更高版本返回。

JET_errTermInProgress

无法完成操作，因为与会话关联的实例正在关闭。

JET_errTransReadOnly

在只读事务的范围内时，无法进行更新。 只读事务是已使用调用 JetBeginTransaction2 和 JET_bitTransactionReadOnly 启动的事务。 此错误仅由 Windows XP 和更高版本返回。

成功后，与游标关联的表中指定列的名称将永久更改为新名称。 引用该列的任何索引也将更新。

失败时，不会更改数据库状态。

备注

列重命名操作不寻常，因为与其他架构操作不同，它不是作为事务执行的。 当给定表中的列在一个会话中重命名时，使用该表的任何其他会话都将立即看到更改，即使它们位于事务中，该事务会阻止该会话看到执行重命名操作的会话所做的任何其他更改。

列的列 ID 不受重命名操作的影响。

要求

要求 值

客户端

需要 Windows Vista 或 Windows XP。

服务器

需要 Windows Server 2008 或 Windows Server 2003。

标头

在 Esent.h 中声明。

Library

使用 ESENT.lib。

DLL

需要ESENT.dll。

Unicode

实现为 JetRenameColumnW (Unicode) 和 JetRenameColumnA (ANSI) 。

另请参阅

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetBeginTransaction2