JetAddColumn 函数

项目
06/13/2023

适用于： 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 中。无效参数的一些示例包括：在其 cbStruct 成员中传入错误大小的 JET_COLUMNDEF 结构。传入JET_bitColumnUserDefinedDefault，但不将 cbDefault 设置为 sizeof (JET_USERDEFINEDDEFAULT) 。
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_bitColumnEscrowUpdate) 不能用于标记或长值 (JET_coltypLongBinary 或 JET_coltypLongText) 列。可能不会标记自动递增列。版本列可能未标记。
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

通过

JetAddColumn 函数