Applies to: Windows | Windows Server
JetAddColumn Function
The JetAddColumn function adds a new column to an existing table in an ESE database.
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
The database session context to use for the API call.
tableid
The table to which to add the column.
szColumnName
The name of the column to add. The name must meet the following criteria:
-
It must be fewer than JET_cbNameMost characters in length, not including the terminating NULL.
-
It must contain characters only from the following sets: 0 through 9, A through Z, a through z, and all other punctuation except for exclamation point (!), comma (,), opening bracket ([), and closing bracket (]) — that is, ASCII characters 0x20, 0x22 through 0x2d, 0x2f through 0x5a, 0x5c, and 0x5d through 0x7f.
-
It cannot begin with a space.
-
It must contain at least one non-space character.
pcolumndef
A pointer to a JET_COLUMNDEF structure, which defines the data that can be stored in a column.
pvDefault
A pointer to a buffer that contains the default value for the column. The length of the buffer is cbDefault. If there is no default, set pvDefault to NULL and cbDefault to zero. Default values cannot be larger than JET_cbColumnMost bytes for fixed columns or JET_cbLVDefaultValueMost bytes for long values. If a default value is larger than that, it will be silently truncated.
If grbit has JET_bitColumnUserDefinedDefault set, pvDefault will be interpreted as a pointer to a JET_USERDEFINEDDEFAULT structure.
cbDefault
The size, in bytes, of the buffer that is specified in pvDefault.
pcolumnid
A pointer to a JET_COLUMNID structure, which, on success, will receive the identifier of the newly created column. On failure, the value is undefined.
Return Value
This function returns the JET_ERR datatype with one of the following return codes. For more information about the possible ESE errors, see Extensible Storage Engine Errors and Error Handling Parameters.
| Return code | Description |
|---|---|
| JET_errSuccess | The operation was successful. |
| JET_errFixedDDL | An attempt was made to modify the data definition of a fixed DDL table. An example of a table with fixed DDL is a Template Table. |
| JET_errInvalidParameter | An invalid parameter was passed into the API. Some examples of invalid parameters are:<ul><li>Passing in the wrong size of the <a href="gg294130(v=exchg.10).md">JET_COLUMNDEF</a> structure in its cbStruct member.</li><li>Passing in JET_bitColumnUserDefinedDefault, but not setting cbDefault to sizeof(<a href="gg269200(v=exchg.10).md">JET_USERDEFINEDDEFAULT</a>).</li></ul> |
| JET_errInTransaction | An attempt was made to add a column with the JET_bitColumnUnversioned bit set, but the session is currently in a transaction. |
| JET_errColumnDuplicate | A column already exists. An attempt was made to add a column without version information, and that column already exists. |
| JET_errTableNotEmpty | The table contains data. An Escrow Update column can only be added to an empty table. |
| JET_errRecordTooBig | The record is too big. The sum of the cbMax parameter for the fixed columns must not exceed a certain value. |
| JET_errTooManyColumns | An attempt was made to add too many columns to the table. A table can have no more than JET_ccolFixedMost fixed columns, no more than JET_ccolVarMost variable-length columns, and no more than JET_ccolTaggedMost tagged columns. |
| JET_errColumnRedundant | An attempt was made to add a redundant column. There should be no more than one autoincrement column, and no more than one version column per table. |
| JET_errCallbackNotResolved | The callback function could not be resolved. The DLL might not have been found, or the function in the DLL might not have been found. The event log will provide more details if sufficient logging is enabled. |
| JET_wrnColumnMaxTruncated | A warning indicating that the maximum length (cbMax) of a fixed or variable column was greater than JET_cbColumnMost. This limit does not apply to Long Values (that is <a href="gg269213(v=exchg.10).md">JET_coltypLongBinary</a> and <a href="gg269213(v=exchg.10).md">JET_coltypLongText</a>). |
| JET_errInvalidName | An invalid name was passed as szColumnName. For more information about the restrictions, see the criteria for szColumnName. |
| JET_errInvalidColumnType | The coltyp field was not set to a valid column type. |
| JET_errInvalidCodePage | The cp parameter of the <a href="gg294130(v=exchg.10).md">JET_COLUMNDEF</a> structure was not set to a valid code page. The only valid values for text columns are English (1252) and Unicode (1200). A value of 0 means the default will be used (English, 1252). |
| JET_errTaggedNotNULL | JET_bitColumnNotNULL cannot be used with tagged, Long Value, or SLV columns. |
| JET_errInvalidgrbit | An invalid combination of grbits was specified. Some of the reasons for this error are:<ul><li>JET_bitColumnFixed was used on a tagged, Long Value, or SLV column.</li><li>JET_bitColumnEscrowUpdate was used on a column that was not of type <a href="gg269213(v=exchg.10).md">JET_coltypLong</a>.</li><li>JET_bitColumnEscrowUpdate was used on a Version column (JET_bitColumnVersion).</li><li>JET_bitColumnEscrowUpdate was used on an AutoIncrememnt column (JET_bitColumnAutoincrement).</li><li>JET_bitColumnEscrowUpdate was used on a column that did not have a default value (cbDefault was equal to zero).</li><li>JET_bitColumnFinalize was used on a column that was not an Escrow Update column (JET_bitColumnEscrowUpdate was not set).</li><li>JET_bitColumnDeleteOnZero was used on a column that was not an Escrow Update column (JET_bitColumnEscrowUpdate was not set).</li><li>JET_bitColumnAutoincrement was used on a column that was not <a href="gg269213(v=exchg.10).md">JET_coltypLong</a>.Windows 2000: This reason for the error code is used only in Windows 2000.JET_bitColumnAutoincrement was used on a column that was neither <a href="gg269213(v=exchg.10).md">JET_coltypLong</a> nor <a href="gg269213(v=exchg.10).md">JET_coltypCurrency</a>.Windows XP: This reason for the error code is used in Windows XP and later operating systems.</li><li>JET_bitColumnVersion was used on a column that was not <a href="gg269213(v=exchg.10).md">JET_coltypLong</a>.</li><li>JET_bitColumnVersion was used on an autoincrement column.</li><li>JET_bitColumnUserDefinedDefault was used in conjunction with JET_bitColumnFixed.</li><li>JET_bitColumnUserDefinedDefault was used in conjunction with JET_bitColumnNotNULL.</li><li>JET_bitColumnUserDefinedDefault was used in conjunction with JET_bitColumnVersion.</li><li>JET_bitColumnUserDefinedDefault was used in conjunction with JET_bitColumnAutoincrement.</li><li>JET_bitColumnUserDefinedDefault was used in conjunction with JET_bitColumnUpdatable.</li><li>JET_bitColumnUserDefinedDefault was used in conjunction with JET_bitColumnEscrowUpdate.</li><li>JET_bitColumnUserDefinedDefault was used in conjunction with JET_bitColumnFinalize.</li><li>JET_bitColumnUserDefinedDefault was used in conjunction with JET_bitColumnDeleteOnZero.</li><li>JET_bitColumnUserDefinedDefault was used in conjunction with JET_bitColumnMaybeNull.</li><li>JET_bitColumnUserDefinedDefault was used on a non-tagged column (that is fixed or variable).</li></ul> |
| JET_errMultiValuedColumnMustBeTagged | A multi-valued column (JET_bitColumnMultiValued) can only be used on a tagged or Long Value (<a href="gg269213(v=exchg.10).md">JET_coltypLongBinary</a> or <a href="gg269213(v=exchg.10).md">JET_coltypLongText</a>) column. |
| JET_errCannotBeTagged | An attempt was made to use a tagged column when the column might not be tagged. Some of the constraints for disallowing tagged columns are:<ul><li>An Escrow Update column (JET_bitColumnEscrowUpdate) cannot be used on a tagged or Long Value (<a href="gg269213(v=exchg.10).md">JET_coltypLongBinary</a> or <a href="gg269213(v=exchg.10).md">JET_coltypLongText</a>) column.</li><li>An autoincrement column might not be tagged.</li><li>A Version column might not be tagged.</li></ul> |
| JET_errExclusiveTableLockRequired | An exclusive lock on the table was required for this operation. |
| JET_wrnColumnMaxTruncated | A warning indicating that the maximum length (cbMax) of a fixed or variable column was greater than JET_cbColumnMost. This limit does not apply to Long Values (that is <a href="gg269213(v=exchg.10).md">JET_coltypLongBinary</a> and <a href="gg269213(v=exchg.10).md">JET_coltypLongText</a>). |
Requirements
| Requirement | Value |
|---|---|
| Client | Requires Windows Vista, Windows XP, or Windows 2000 Professional. |
| Server | Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server. |
| Header | Declared in Esent.h. |
| Library | Use ESENT.lib. |
| DLL | Requires ESENT.dll. |
| Unicode | Implemented as JetAddColumnW (Unicode) and JetAddColumnA (ANSI). |
See Also
JET_COLTYP
JET_COLUMNCREATE
JET_COLUMNDEF
JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateTableColumnIndex
JetCreateTableColumnIndex2
Source: Microsoft Learn / Windows Win32 documentation by Microsoft and contributors. Documentation licensed CC BY 4.0. Code samples are covered by the MIT License. Converted from Markdown, with links normalized and embedded media omitted.
