JetAddColumn 函数

  • 项目

适用于： Windows |Windows Server

JetAddColumn 函数

JetAddColumn 函数将新列添加到 ESE 数据库中的现有表中。

    JET_ERR JET_API JetAddColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_PCSTR szColumnName,
      __in          const JET_COLUMNDEF* pcolumndef,
      __in_opt      const void* pvDefault,
      __in          unsigned long cbDefault,
      __out_opt     JET_COLUMNID* pcolumnid
    );

parameters

sesid

用于 API 调用的数据库会话上下文。

tableid

要向其添加列的表。

szColumnName

要添加的列的名称。 该名称必须满足以下条件：

  • 长度必须少于 JET_cbNameMost 个字符， 不包括终止 NULL。

  • 它只能包含以下集中的字符：0 到 9、A 到 Z、a 到 z、 以及除感叹号 (！) 、逗号 (、) 、左方括号 ([) 和右方括号 (]) 以外的所有其他标点，即 ASCII 字符0x20、0x22 0x2d、0x2f到0x5a、0x5c，以及通过0x7f 0x5d。

  • 它不能以空格开头。

  • 它必须至少包含一个非空格字符。

pcolumndef

指向 JET_COLUMNDEF 结构的指针，该结构定义可以存储在列中的数据。

pvDefault

指向包含列默认值的缓冲区的指针。 缓冲区的长度为 cbDefault。 如果没有默认值，请将 pvDefault 设置为 NULL ， 将 cbDefault 设置为零。 对于固定列，默认值不能大于 JET_cbColumnMost 个字节，对于长值，默认值不能大于 JET_cbLVDefaultValueMost 个字节。 如果默认值大于该值，则会以无提示方式将其截断。

如果 grbit 已设置JET_bitColumnUserDefinedDefault， pvDefault 将被解释为指向 JET_USERDEFINEDDEFAULT 结构的指针。

cbDefault

pvDefault 中指定的缓冲区的大小（以字节为单位）。

pcolumnid

指向 JET_COLUMNID 结构的指针，如果成功，该结构将接收新创建的列的标识符。 失败时，该值未定义。

返回值

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

返回代码

说明

JET_errSuccess

操作成功。

JET_errFixedDDL

尝试修改固定 DDL 表的数据定义。 具有固定 DDL 的表的一个示例是模板表。

JET_errInvalidParameter

将无效参数传递到 API 中。 无效参数的一些示例包括：

JET_errInTransaction

尝试添加设置了 JET_bitColumnUnversioned 位的列，但会话当前位于事务中。

JET_errColumnDuplicate

列已存在。 尝试添加没有版本信息的列，并且该列已存在。

JET_errTableNotEmpty

表包含数据。 托管更新列只能添加到空表中。

JET_errRecordTooBig

记录太大了。 固定列的 cbMax 参数之和不得超过特定值。

JET_errTooManyColumns

尝试向表添加过多列。 一个表的固定列不能超过JET_ccolFixedMost个，长度不能超过JET_ccolVarMost个可变长度列，并且不能超过JET_ccolTaggedMost个标记列。

JET_errColumnRedundant

尝试添加冗余列。 每个表不应有一个以上的自动递增列和一个以上的版本列。

JET_errCallbackNotResolved

无法解析回调函数。 可能未找到 DLL，或者未找到 DLL 中的函数。 如果启用了足够的日志记录，事件日志将提供更多详细信息。

JET_wrnColumnMaxTruncated

一个警告，指示固定列或变量列的最大长度 (cbMax) 大于 JET_cbColumnMost。 此限制不适用于 JET_coltypLongBinary和JET_coltypLongText) 的 长值 ( 。

JET_errInvalidName

作为 szColumnName 传递了无效的名称。 有关限制的详细信息，请参阅 szColumnName 的条件。

JET_errInvalidColumnType

coltyp 字段未设置为有效的列类型。

JET_errInvalidCodePage

JET_COLUMNDEF 结构的 cp 参数未设置为有效的代码页。 文本列的唯一有效值为英语 (1252) 和 Unicode (1200) 。 值为 0 表示将使用默认值 (英语、1252) 。

JET_errTaggedNotNULL

JET_bitColumnNotNULL不能与标记列、长值列或 SLV 列一起使用。

JET_errInvalidgrbit

指定的 grbit 组合 无效。 此错误的一些原因包括：

  • JET_bitColumnFixed用于标记、长值或 SLV 列。

  • JET_bitColumnEscrowUpdate用于非 JET_coltypLong类型的列。

  • JET_bitColumnEscrowUpdate用于版本列 (JET_bitColumnVersion) 。

  • JET_bitColumnEscrowUpdate用于 AutoIncrememnt 列 (JET_bitColumnAutoincrement) 。

  • JET_bitColumnEscrowUpdate用于没有默认值的列， (cbDefault 等于零) 。

  • JET_bitColumnFinalize用于不是托管更新列的列， (JET_bitColumnEscrowUpdate未设置) 。

  • JET_bitColumnDeleteOnZero用于非托管更新列的列， (JET_bitColumnEscrowUpdate未设置) 。

  • JET_bitColumnAutoincrement用于未 JET_coltypLong的列。

    Windows 2000： 错误代码的此原因仅在 Windows 2000 中使用。

    JET_bitColumnAutoincrement用于既非JET_coltypLong也不JET_coltypCurrency列。

    Windowsxp： 此错误代码原因在 Windows XP 和更高版本的操作系统中使用。

  • JET_bitColumnVersion用于未 JET_coltypLong的列。

  • JET_bitColumnVersion用于自动增加列。

  • JET_bitColumnUserDefinedDefault与 JET_bitColumnFixed 结合使用。

  • JET_bitColumnUserDefinedDefault与 JET_bitColumnNotNULL 结合使用。

  • JET_bitColumnUserDefinedDefault与 JET_bitColumnVersion 结合使用。

  • JET_bitColumnUserDefinedDefault与 JET_bitColumnAutoincrement 结合使用。

  • JET_bitColumnUserDefinedDefault与 JET_bitColumnUpdatable 结合使用。

  • JET_bitColumnUserDefinedDefault与 JET_bitColumnEscrowUpdate 一起使用。

  • JET_bitColumnUserDefinedDefault与 JET_bitColumnFinalize 结合使用。

  • JET_bitColumnUserDefinedDefault与 JET_bitColumnDeleteOnZero 结合使用。

  • JET_bitColumnUserDefinedDefault与 JET_bitColumnMaybeNull 结合使用。

  • JET_bitColumnUserDefinedDefault用于固定或可变) 的非标记列 (。

JET_errMultiValuedColumnMustBeTagged

多值列 (JET_bitColumnMultiValued) 只能在标记或长值 (JET_coltypLongBinary 或 JET_coltypLongText) 列上使用。

JET_errCannotBeTagged

尝试使用标记的列时，可能未标记该列。 禁止标记列的一些约束包括：

JET_errExclusiveTableLockRequired

此操作需要表上的独占锁。

JET_wrnColumnMaxTruncated

指示固定列或可变列的最大长度 (cbMax) 大于JET_cbColumnMost的警告。 此限制不适用于JET_coltypLongBinary和JET_coltypLongText) 的长值 (。

要求

要求 值

客户端

需要 Windows Vista、Windows XP 或 Windows 2000 Professional。

服务器

需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。

标头

在 Esent.h 中声明。

Library

使用 ESENT.lib。

DLL

需要ESENT.dll。

Unicode

实现为 JetAddColumnW (Unicode) 和 JetAddColumnA (ANSI) 。

另请参阅

JET_COLTYP
JET_COLUMNCREATE
JET_COLUMNDEF
JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateTableColumnIndex
JetCreateTableColumnIndex2