JetCreateTableColumnIndex3 Function

Applies to: Windows | Windows Server

JetCreateTableColumnIndex3 Function

The JetCreateTableColumnIndex3 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_TABLECREATE3 structures. The JET_TABLECREATE3 structure allows a callback function to be specified.

Windows 7: JetCreateTableColumnIndex3 is introduced in the Windows 7 operating system.

    JET_ERR JET_API JetCreateTableColumnIndex3(
      __in          JET_SESID sesid,
      __in          JET_DBID dbid,
      __in_out      JET_TABLECREATE3* 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_TABLECREATE3 structure that defines the table to be created. See JET_TABLECREATE3 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 JET_INDEXCREATE2 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 JET_TABLECREATE3 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. The following are some of the possible reasons for receiving this error:

  • A primary index is conditional (that is, the grbit member of the JET_INDEXCREATE2 structure has JET_bitIndexPrimary set, and cConditionalColumn member of the JET_INDEXCREATE2 structure is greater than zero).

  • Windows Server 2003 and later versions of Windows. Attempting to create a tuple index with tuple limits, but without passing the ptuplelimits member in the JET_INDEXCREATE2 structure (that is, the grbit member of the JET_INDEXCREATE2 structure has JET_bitIndexTupleLimits set, but the ptuplelimits pointer is NULL).

  • Passing in an invalid key definition in the szKey member of the JET_INDEXCREATE2 structure. See JET_INDEXCREATE2 for a discussion of valid definitions.

  • Setting the cbVarSegMac member in JET_INDEXCREATE2 to be greater than JET_cbPrimaryKeyMost (for a primary index) or greater than JET_cbSecondaryKeyMost (for a secondary index).

  • Passing an invalid combination for a user-defined Unicode index (one that has the JET_bitIndexUnicode bit set in the grbit member of JET_INDEXCREATE2). Some common causes include the pidxunicode member of the JET_INDEXCREATE2 structure is NULL, or the LCID specified in the pidxunicode structure is invalid.

  • Specifying a multi-valued column for a primary index.

  • Trying to index too many conditional columns. The cConditionalColumn member of the JET_INDEXCREATE2 structure must not be greater than JET_ccolKeyMost.

JET_errIndexTuplesInvalidLimits

Windows XP and later versions of Windows. A JET_TUPLELIMITS structure was specified, and its limits are not supported. See the remarks section of the JET_TUPLELIMITS structure.

JET_errIndexTuplesNonUniqueOnly

Windows XP and later versions of Windows. A tuple index cannot be unique (that is, the grbit member of the JET_INDEXCREATE2 structure must not have both JET_bitIndexPrimary and JET_bitIndexUnique set).

JET_errIndexTuplesOneColumnOnly

Windows XP and later versions of Windows. A tuple index can only be over a single column (that is, if the grbit member of the JET_INDEXCREATE2 structure has JET_bitIndexTuples set, and the szKey member of the JET_INDEXCREATE2 structure specifies more than one column).

JET_errIndexTuplesSecondaryIndexOnly

Windows XP and later versions of Windows. A tuple index cannot be a primary index (that is, the grbit member of the JET_INDEXCREATE2 structure must not have both JET_bitIndexPrimary and JET_bitIndexTuples set).

JET_errIndexTuplesTextColumnsOnly

Windows XP and later versions of Windows. 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 versions of Windows. A tuple index does not allow the cbVarSegMac member of the JET_INDEXCREATE2 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 JET_COLUMNCREATE 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 JET_COLUMNCREATE structure was not set to a valid column type.

JET_errInvalidCreateIndex

The following are some reasons why this error may occur:

JET_errInvalidgrbit

An invalid combination of grbit members was specified in JET_TABLECREATE3.

The index definition is invalid because the grbit member contains inconsistent values. The following are some possible reasons:

  • A primary index had an ignore bit specified (that is, JET_bitIndexPrimary was passed with JET_bitIndexIgnoreNull, JET_bitIndexIgnoreAnyNull, or JET_bitIndexIgnoreFirstNull).

  • An empty index does not ignore any NULL members (that is, the grbit member of the JET_INDEXCREATE2 structure has JET_bitIndexEmpty set, but does not have JET_bitIndexIgnoreAnyNull set).

  • Passing in a JET_CONDITIONALCOLUMN structure with an invalid grbit member.

JET_errInvalidLanguageId

An invalid Locale ID (LCID) was passed in (either through the lcid member of the JET_UNICODEINDEX structure which is pointed to by the pidxunicode member in the JET_INDEXCREATE2 structure, or through the lcid field of the JET_INDEXCREATE2 structure).

JET_errInvalidParameter

An invalid parameter was given. The following are some possible reasons:

JET_errRecordTooBig

The record is too big. The sum of the cbMax member of the JET_COLUMNCREATE 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.

JET_errSpaceHintsInvalid

An element of the JET space hints structure was not correct or actionable.

Remarks

The name JetCreateTableColumnIndex3 comes from the order of creation of the objects: It first creates a table, columns, and then finally indexes. JetCreateTableColumnIndex3 creates a table with an initial set of columns and indexes. Additional columns and indexes can be added and removed dynamically with JetAddColumn, JetDeleteColumn, JetDeleteColumn2, JetCreateIndex, JetCreateIndex2, JetCreateIndex3, and JetDeleteIndex.

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 or Windows XP.

Server

Requires Windows Server 2008 or Windows Server 2003.

Header

Declared in Esent.h.

Library

Use ESENT.lib.

DLL

Requires ESENT.dll.

Unicode

Implemented as JetCreateTableColumnIndex3W (Unicode) and JetCreateTableColumnIndex3A (ANSI).

See Also

JET_CBTYP
JET_DBID
JET_ERR
JET_GRBIT
JET_INDEXCREATE
JET_INDEXCREATE2
JET_SESID
JET_TABLEID
JET_TABLECREATE2
JET_TABLECREATE3
JET_TUPLELIMITS
JetAddColumn
JetCreateIndex
JetCreateIndex2
JetCreateIndex3
JetCreateTable
JetCreateTableColumnIndex
JetDeleteColumn
JetDeleteColumn2