Last modified: January 09, 2012
Applies to: Windows | Windows Server
The JetCreateTable function creates an empty table in an ESE database.
JET_ERR JET_API JetCreateTable( __in JET_SESID sesid, __in JET_DBID dbid, __in const tchar* szTableName, __in unsigned long lPages, __in unsigned long lDensity, __out JET_TABLEID* ptableid );
The database session context to use.
The database identifier to use.
The name of the index to create.
The name must be formatted according to the following rules:
Be less than JET_cbNameMost, not including the terminating NULL.
Be made of the following set of characters: 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, 0x5d through 0x7f.
Not begin with a space.
Be made of at least one non-space character.
The initial number of database pages to allocate for the table. Specifying a number larger than one can reduce fragmentation if many rows are inserted into this table.
The table density, in percentage points. The number must be either 0 or in the range of 20 through 100. Passing 0 means that the default value should be used. The default is 80.
On success, the table identifier is returned in this field. The value is undefined if the API does not return JET_errSuccess.
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.
The operation completed successfully.
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.
An attempt was made to index over an escrow-update or SLV column (note that SLV columns are deprecated).
If ptablecreate->grbit specifies JET_bitTableCreateTemplateTable, but ptablecreate->szTemplateTableName is set to NULL.
A column already exists.
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.
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.
Signifies that the table named in the szTemplateTableName member of the JET_TABLECREATE structure was not a marked as a template table (that is, that table did not have JET_bitTableCreateTemplateTable set).
An attempt was made to define two identical indexes.
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.
An invalid index definition was specified. Some of the possible reasons for receiving this error are:
Windows XP and later. A tuple index cannot be unique (that is, the grbit member of the JET_INDEXCREATE structure must not have both JET_bitIndexPrimary and JET_bitIndexUnique set).
Windows XP and later. A tuple index can only be over a single column (that is, if the grbit member of the JET_INDEXCREATE structure has JET_bitIndexTuples set, and the szKey member of the JET_INDEXCREATE structure specifies more than one column).
Windows XP and later. A tuple index cannot be a primary index (that is, the grbit member of the JET_INDEXCREATE structure must not have both JET_bitIndexPrimary and JET_bitIndexTuples set).
Windows XP and later. A tuple index does not allow the cbVarSegMac member of the JET_INDEXCREATE structure to be set.
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.
An attempt was made to create an index without version information while in a transaction.
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).
The coltyp member of the JET_COLUMNCREATE structure was not set to a valid column type.
Some of the reasons this error may occur:
The index definition is invalid because the grbit member contains inconsistent values. Some possible reasons are:
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_INDEXCREATE structure, or through the lcid field of the JET_INDEXCREATE structure).
An invalid parameter was given. Some possible reasons are:
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.
The table already exists.
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.
An error occurred attempting to normalize a Unicode column. This can be caused by running out of system resources.
JetCreateTable creates a table which does not contain any columns. To add columns, see JetAddColumn.
JET_TABLECREATE2.cbStruct = sizeof( JET_TABLECREATE2 )
JET_TABLECREATE2.szTableName = szTableName
JET_TABLECREATE2.ulPages = lPage
JET_TABLECREATE2.ulDensity = lDensity
JET_TABLECREATE2.tableid = JET_tableidNil
All the other fields of the internal JET_TABLECREATE2 structure are set to zero or NULL. On output, ptableid will be set to JET_TABLECREATE2.tableid.
See JetCreateTableColumnIndex2 for more details.
Requires Windows Vista, Windows XP, or Windows 2000 Professional.
Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server.
Declared in Esent.h.
Implemented as JetCreateTableW (Unicode) and JetCreateTableA (ANSI).