JetAddColumn 函式

發行項
06/12/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
    );

參數

sesid

要用於 API 呼叫的資料庫會話內容。

tableid

要加入資料行的資料表。

szColumnName

要加入的資料行名稱。名稱必須符合下列準則：

長度必須少於JET_cbNameMost個字元，不包括終止 的 Null。
它只能包含下列集合中的字元：0 到 9、A 到 Z、a 到 z、和除了驚嘆號 (！) 、逗號 (、) 、左括弧 ([) 和右括弧 (]) 以外，亦即 ASCII 字元0x20、0x22到0x2d、0x2f 0x5a、0x5c和0x5d 0x7f。
它不能以空格開頭。
它至少必須包含一個非空白字元。

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 錯誤的詳細資訊，請參閱可延伸儲存引擎錯誤和錯誤處理參數。

傳回碼	Description
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	資料表包含資料。 Escrow Update 資料行只能加入空白資料表。
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不能與標記、Long Value 或 SLV 資料行搭配使用。
JET_errInvalidgrbit	指定了不正確 grbit 組合。此錯誤的一些原因如下： JET_bitColumnFixed用於標記、Long Value 或 SLV 資料行。 JET_bitColumnEscrowUpdate用於不是類型JET_coltypLong的資料行。 JET_bitColumnEscrowUpdate用於 [版本] 資料行 (JET_bitColumnVersion) 。 JET_bitColumnEscrowUpdate用於 AutoIncrememnt 資料行 (JET_bitColumnAutoincrement) 。 JET_bitColumnEscrowUpdate用於沒有預設值的資料行， (cbDefault 等於零) 。 JET_bitColumnFinalize不是 Escrow Update 資料行的資料行上使用， (JET_bitColumnEscrowUpdate未設定) 。 JET_bitColumnDeleteOnZero不是 Escrow Update 資料行的資料行上使用， (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) 只能用於標記或 Long Value (JET_coltypLongBinary 或 JET_coltypLongText) 資料行。
JET_errCannotBeTagged	嘗試在未標記資料行時使用標記的資料行。不允許標記資料行的一些條件約束如下：委付更新資料行 (JET_bitColumnEscrowUpdate) 不能用於標記或 Long Value (JET_coltypLongBinary 或 JET_coltypLongText) 資料行。可能不會標記自動遞增資料行。 [版本] 資料行可能不會標記。
JET_errExclusiveTableLockRequired	此作業需要資料表的獨佔鎖定。
JET_wrnColumnMaxTruncated	警告，指出固定或變數資料行的 cbMax) 長度上限 (大於 JET_cbColumnMost。此限制不適用於JET_coltypLongBinary和 JET_coltypLongText) (。

規格需求

需求	值
用戶端	需要 Windows Vista、Windows XP 或 Windows 2000 Professional。
Server	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
標頭	在 Esent.h 中宣告。
程式庫	使用 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 函式