Applies to: Windows | Windows Server
JetCreateTableColumnIndex Function
The JetCreateTableColumnIndex function creates a table in an ESE database with an initial set of indexes and an initial set of columns from an array of JET_TABLECREATE structures. The name JetCreateTableColumnIndex comes from the order of creation of the objects. It first creates a table, columns, and then finally indexes.
JET_ERR JET_API JetCreateTableColumnIndex(
__in JET_SESID sesid,
__in JET_DBID dbid,
__in_out JET_TABLECREATE* ptablecreate
);
Parameters
sesid
The database session context to use for the API call.
dbid
The database identifier to use for the API call.
ptablecreate
A pointer to a JET_TABLECREATE structure which defines the table to be created. See JET_TABLECREATE for more details.
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 completed successfully. |
| 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. With sufficient logging enabled, the event log will provide more details. |
| JET_errCannotIndex | An attempt was made to index over an escrow-update or SLV column (note that SLV columns are deprecated). |
| JET_errCannotNestDDL | If ptablecreate->grbit specifies JET_bitTableCreateTemplateTable, but ptablecreate->szTemplateTableName is set to NULL. |
| JET_errColumnDuplicate | A column already exists. |
| JET_errColumnNotFound | An attempt was made to index over a non-existent column. Attempting to conditionally index over a non-existent column can also produce this error. |
| 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_errDensityInvalid | This error will be returned if the ulDensity member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure is set to a number less than 20 or more than 100. |
| JET_errDDLNotInheritable | Signifies that the table named in the szTemplateTableName member of the <a href="gg294146(v=exchg.10).md">JET_TABLECREATE</a> structure was not marked as a template table (that is, that table did not have JET_bitTableCreateTemplateTable set). |
| JET_errIndexDuplicate | An attempt to define two identical indexes was made. |
| JET_errIndexHasPrimary | An attempt was made to specify more than one primary index for a table. A table must have exactly one primary index. If no primary index is specified, the database engine will transparently create one. |
| JET_errIndexInvalidDef | An invalid index definition was specified. Some of the possible reasons for receiving this error are:<ul><li>A primary index is conditional (that is, the grbit member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure has JET_bitIndexPrimary set, and cConditionalColumn member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure is greater than zero).</li><li>Windows Server 2003 and later. Attempting to create a tuple index with tuple limits, but without passing the ptuplelimits member in the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure (that is, the grbit member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure has JET_bitIndexTupleLimits set, but the ptuplelimits pointer is NULL).</li><li>Passing in an invalid key definition in the szKey member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure. See <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> for a discussion of valid definitions.</li><li>Setting the cbVarSegMac member in <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> to be greater than JET_cbPrimaryKeyMost (for a primary index) or greater than JET_cbSecondaryKeyMost (for a secondary index).</li><li>Passing an invalid combination for a user-defined Unicode index (one which has the JET_bitIndexUnicode bit set in the grbit member of <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a>). Some common causes include the pidxunicode member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure is NULL, or the LCID specified in the pidxunicode structure is invalid.</li><li>Specifying a multi-valued column for a primary index.</li><li>Trying to index too many conditional columns. The cConditionalColumn member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure must not be greater than JET_ccolKeyMost.</li></ul> |
| JET_errIndexTuplesInvalidLimits | Windows XP and later. A <a href="gg269207(v=exchg.10).md">JET_TUPLELIMITS</a> structure was specified, and its limits are not supported. See the remarks section of the <a href="gg269207(v=exchg.10).md">JET_TUPLELIMITS</a> structure. |
| JET_errIndexTuplesNonUniqueOnly | Windows XP and later. A tuple index cannot be unique (that is, the grbit member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure must not have both JET_bitIndexPrimary and JET_bitIndexUnique set). |
| JET_errIndexTuplesOneColumnOnly | Windows XP and later. A tuple index can only be over a single column (that is, if the grbit member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure has JET_bitIndexTuples set, and the szKey member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure specifies more than one column). |
| JET_errIndexTuplesSecondaryIndexOnly | Windows XP and later. A tuple index cannot be a primary index (that is, the grbit member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure must not have both JET_bitIndexPrimary and JET_bitIndexTuples set). |
| JET_errIndexTuplesTextColumnsOnly | Windows XP and later. A tuple index can only be on a text or Unicode column. An attempt to index other columns (such as binary columns) will result in JET_errIndexTuplesTextColumnsOnly. |
| JET_errIndexTuplesVarSegMacNotAllowed | Windows XP and later. A tuple index does not allow the cbVarSegMac member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure to be set. |
| JET_errInTransaction | An attempt was made to create an index without version information while in a transaction. |
| JET_errInvalidCodePage | The cp member of the <a href="gg269252(v=exchg.10).md">JET_COLUMNCREATE</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_errInvalidColumnType | The coltyp member of the <a href="gg269252(v=exchg.10).md">JET_COLUMNCREATE</a> structure was not set to a valid column type. |
| JET_errInvalidCreateIndex | Some of the reasons this error may occur:<ul><li>The rgindexcreate member of the <a href="gg269203(v=exchg.10).md">JET_TABLECREATE2</a> structure was set to NULL.</li><li>The rgcolumncreate member of the <a href="gg269203(v=exchg.10).md">JET_TABLECREATE2</a> structure was set to NULL.</li><li>The cbStruct member of a <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure was not set to a valid value.</li></ul> |
| JET_errInvalidgrbit | An invalid combination of grbit members was specified in <a href="gg294146(v=exchg.10).md">JET_TABLECREATE</a> or <a href="gg269203(v=exchg.10).md">JET_TABLECREATE2</a>.The index definition is invalid because the grbit member contains inconsistent values. Some possible reasons are:<ul><li>A primary index had an ignore bit specified (that is, JET_bitIndexPrimary was passed with JET_bitIndexIgnoreNull, JET_bitIndexIgnoreAnyNull, or JET_bitIndexIgnoreFirstNull).</li><li>An empty index does not ignore any NULL members (that is, the grbit member of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure has JET_bitIndexEmpty set, but does not have JET_bitIndexIgnoreAnyNull set).</li><li>Passing in a <a href="gg269214(v=exchg.10).md">JET_CONDITIONALCOLUMN</a> structure with an invalid grbit member.</li></ul> |
| JET_errInvalidLanguageId | An invalid Locale ID (LCID) was passed in (either through the lcid member of the <a href="gg294097(v=exchg.10).md">JET_UNICODEINDEX</a> structure which is pointed to by the pidxunicode member in the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure, or through the lcid field of the <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure). |
| JET_errInvalidParameter | An invalid parameter was given. Some possible reasons are:<ul><li>The rgcolumncreate member of the <a href="gg269203(v=exchg.10).md">JET_TABLECREATE2</a> structure is NULL.</li><li>The cbStruct member of one of the <a href="gg269252(v=exchg.10).md">JET_COLUMNCREATE</a> structures given in the rgcolumncreate member of the <a href="gg269203(v=exchg.10).md">JET_TABLECREATE2</a> structure was not set to sizeof( JET_COLUMNCREATE).</li><li>The cbKey member of a <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure is set to zero.</li><li>The cbStruct member of a <a href="gg269186(v=exchg.10).md">JET_INDEXCREATE</a> structure is not set to sizeof( JET_INDEXCREATE).</li></ul> |
| JET_errRecordTooBig | The record is too big. The sum of the cbMax member of the <a href="gg269252(v=exchg.10).md">JET_COLUMNCREATE</a> structure for all fixed columns must not exceed a certain value. |
| JET_errTableDuplicate | The table already exists. |
| 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_errUnicodeTranslationFail | An error occurred attempting to normalize a Unicode column. This can be caused by running out of system resources. |
Remarks
Calling JetCreateTableColumnIndex is identical to calling JetCreateTableColumnIndex2, with each field in the JET_TABLECREATE2 structure containing the value of the corresponding field of JET_TABLECREATE, with the following exceptions:
-
JET_TABLECREATE2.cbStruct set to sizeof( JET_TABLECREATE2)
-
JET_TABLECREATE2.szCallback set to NULL
-
JET_TABLECREATE2.cbtyp set to 0
See JetCreateTableColumnIndex2 for more details.
Like JetOpenTable, when the application is done using the returned tableid, it should usually be closed with JetCloseTable.
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 JetCreateTableColumnIndexW (Unicode) and JetCreateTableColumnIndexA (ANSI). |
See Also
JET_DBID
JET_ERR
JET_GRBIT
JET_TABLEID
JET_TABLECREATE
JET_TABLECREATE2
JetAddColumn
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.
