| OLE DB Programmer's Reference |  |
| OLE DB Programmer's Reference | |
Creates a new base table in the data store.
HRESULT CreateTable( IUnknown *pUnkOuter, DBID *pTableID, DBORDINAL cColumnDescs, const DBCOLUMNDESC rgColumnDescs[], REFIID riid, ULONG cPropertySets, DBPROPSET rgPropertySets[], DBID **ppTableID, IUnknown **ppRowset);
Parameters
typedef struct tagDBCOLUMNDESC {
LPOLESTR pwszTypeName;
ITypeInfo *pTypeInfo;
DBPROPSET *rgPropertySets;
CLSID *pclsid;
ULONG cPropertySets;
DBLENGTH ulColumnSize;
DBID dbcid;
DBTYPE wType;
BYTE bPrecision;
BYTE bScale;
} DBCOLUMNDESC;
The elements of this structure are used as follows. The consumer decides the values to use in the nonproperties elements of this structure based on values from the PROVIDER_TYPES schema rowset.
| Element | Description |
|---|---|
| pwszTypeName | The provider-specific name of the data type of the column. This name corresponds to a value in the TYPE_NAME column in the PROVIDER_TYPES schema rowset. In most cases, there is no reason for a consumer to specify a value for pwszTypeName that is different from the values listed in the PROVIDER_TYPES schema rowset.
Tip Although support for IDBSchemaRowset is optional, providers should implement IDBSchemaRowset and the PROVIDER_TYPES schema rowset if also implementing ITableDefinition. Otherwise, it may force the consumer to know the provider's types in advance, because the provider may be unable to determine the column type if pwszTypeName is NULL. If pwszTypeName is NULL, the provider determines the type of the column based upon wType and ulColumnSize, as well as any column properties, such as DBTYPE_COL_ISLONG and DBTYPE_COL_FIXEDLENGTH, passed in rgPropertySets. There may be some types that can only be created by specifying the name in pwszTypeName because they cannot be unambiguously determined based on the wType, ulColumnSize, and property values specified. Note Some 2.0 providers return an error if pwszTypeName is NULL. |
| pTypeInfo | If pTypeInfo is not a null pointer, the data type of the column is an abstract data type (ADT) and values in this column are actually instances of the type described by the type library. wType may be either DBTYPE_BYTES, with a length of at least 4, or DBTYPE_IUNKNOWN. The instance values are required to be COM objects derived from IUnknown. |
| rgPropertySets | An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures must belong to the Column property group. All properties specified in rgPropertySets for this element of rgColumnDescs apply to the column specified by dbcid; the colid element in the DBPROP structure for specified properties is ignored. If the same property is specified more than once in rgPropertySets, it is provider-specific which value is used. If cPropertySets is zero, this argument is ignored.
Note Although the colid element in the DBPROP structure for specified properties is ignored, the consumer must set the value of colid to DB_NULLID. Not to do so is a programming error. For information about the properties in the Column property group that are defined by OLE DB, see "Column Property Group" in Appendix C. For information about the DBPROPSET and DBPROP structures, see "DBPROPSET Structure" and "DBPROP Structure" in Chapter 14: Properties. |
| pclsid | If the column contains COM objects, a pointer to the class ID of those objects. If more than one class of objects can reside in the column, *pclsid is set to IID_NULL. If the column does not contain COM objects, this is ignored and pclsid should be a null pointer. |
| cPropertySets | The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets. |
| ulColumnSize | The maximum length in characters for values in this column if wType is DBTYPE_STR or DBTYPE_WSTR, or in bytes if wType is DBTYPE_BYTES.
If ulColumnSize is zero and a default maximum column length is defined, the provider creates a column of that length. If no default is defined, the length of the created column is provider-specific. For all other values of wType, ulColumnSize is ignored. Providers that do not require a length argument in the specification of the provider type (pwszTypeName) ignore this element. |
| dbcid | The column ID of the column. |
| wType | The type indicator for the data type of the column. This name corresponds to a value in the DATA_TYPE column in the PROVIDER_TYPES schema rowset. In most cases, there is no reason for a consumer to specify a value for wType that is different from the values listed in the PROVIDER_TYPES schema rowset. |
| bPrecision | The maximum precision of data values in the column when wType is the indicator for DBTYPE_NUMERIC or DBTYPE_VARNUMERIC; it is ignored for all other data types. This must be within the limits specified for the type in the COLUMN_SIZE column in the PROVIDER_TYPES schema rowset. For information about the precision of numeric data types, see "Precision of Numeric Data Types" in Appendix A. |
| bScale | The scale of data values in the column when wType is DBTYPE_NUMERIC, DBTYPE_VARNUMERIC, or DBTYPE_DECIMAL; it is ignored for all other data types. This must be within the limits specified for the type in the MINIMUM_SCALE and MAXIMUM_SCALE columns in the PROVIDER_TYPES schema rowset. |
Note The provider does not modify any elements of the DBCOLUMNDESC structures. However, upon a return code of S_OK, DB_S_ERRORSOCCURRED, or DB_E_ERRORSOCCURRED, the dwStatus element in the DBPROP structure for each column property indicates whether or not that column property was set (DBPROPSTATUS_OK).
Note The colid element of every DBPROP structure passed to the method must be set either to a valid DBID value or to DB_NULLID. For rowset properties, the colid element of the DBPROP structure must be set either to the ID of the rowset column to which the property applies or to DB_NULLID if the property applies to the entire rowset. For table properties, the property applies to the entire table and therefore the colid element of the DBPROP structure must be set to DB_NULLID.
For information about the properties in the Rowset and Tables property groups that are defined by OLE DB, see "Rowset Property Group" and "Table Property Group" in Appendix C. For information about the DBPROPSET and DBPROP structures, see "DBPROPSET Structure" and "DBPROP Structure" in Chapter 14: Properties.
Note The contents of *ppTableID might not exactly match the passed pTableID. (For example, it might contain additional version or other information.) The consumer should use *ppTableID to identify the newly created table. If ppTableID is NULL on input and the provider cannot create a table that exactly matches pTableID, ITableDefinition::CreateTable should fail with DB_E_BADTABLEID.
Return Code
cColumnDesc was not zero, or rgColumnDescs was a null pointer. cColumnDesc was zero, and the provider does not support creating tables with no columns.
cPropertySets was not zero, and rgPropertySets was a null pointer.
In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer.
In an element of rgColumnDescs, cPropertySets was not zero and rgPropertySets was a null pointer.
riid was IID_NULL, and ppRowset was not a null pointer.
DB_E_BADCOLUMNID
dbcid in an element of rgColumnDescs was an invalid column ID.
In an element of rgColumnDescs, pwszTypeName was non-null and implied a DBTYPE other than the type specified by wType.
pUnkOuter was not a null pointer, and riid was not IID_IUnknown.
Comments
If ppRowset is not a null pointer, an empty rowset is opened on the newly created table. If ITableDefinition::CreateTable returns any errors, the table is not created and ppTableID is set to NULL on output.
If the session is participating in a transaction, if DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DDL_IGNORE, and if the method succeeds, the operation is complete and is unaffected by subsequent calls to abort or commit the transaction.
If the session is participating in a transaction, if DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DDL_COMMIT, and if the method succeeds, the transaction is committed without retention. No new transaction is created. Any new work done on the session is outside the scope of a transaction. Attempting to explicitly commit or abort when there is no outstanding transaction returns an error.
IDBProperties::GetPropertyInfo | ITableDefinition::AddColumn | ITableDefinition::DropColumn | ITableDefinition::DropTable