ITableDefinition::CreateTable

Creates a new base table in the data source.

HRESULT CreateTable(
   IUnknown *            pUnkOuter,
   DBID *                  pTableID,
   ULONG               cColumnDescs,
   DBCOLUMNDESC   rgColumnDescs[],
   REFIID                  riid,
   ULONG               cPropertySets,
   DBPROPSET         rgPropertySets[],
   DBID **               ppTableID,
   IUnknown **            ppRowset);

Parameters

pUnkOuter

[in]
The controlling unknown if the rowset is to be aggregated, otherwise a null pointer.

pTableID

[in]
A pointer to the ID of the table to create. If this is a null pointer, the provider must assign a unique ID to the table.

cColumnDescs

[in]
The number of DBCOLUMNDESC structures in the rgColumnDescs array. This can be zero if the provider allows the creation of tables with no columns.

rgColumnDescs

[in/out]
An array of DBCOLUMNDESC structures that describe the columns of the table.

typedef struct tagDBCOLUMNDESC {
 LPOLESTR  pwszTypeName;
 ITypeInfo * pTypeInfo;
 DBPROPSET * rgPropertySets;
 CLSID *   pclsid;
 ULONG   cPropertySets;
 ULONG   ulColumnSize;
 DBID    dbcid;
 DBTYPE    wType;
 BYTE    bPrecision;
 BYTE    bScale;
} DBCOLUMNDESC;

The elements of this structure are used as follows. The consumer generally decides the values to use in the non-properties 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.
pTypeInfo	If pTypeInfo is not a null pointer, then 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 it may be 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, then it is provider-specific which value is used. If cPropertySets is zero, this argument is ignored. For information about the properties in the Column property group that are defined by OLE DB, see "Column Properties" in Appendix C. For information about the DBPROPSET and DBPROP structures, see "DBPROPSET Structure" and "DBPROP Structure" in Chapter 11.
pclsid	If the column contains OLE 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.
cPropertySets	The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets.
ulColumnSize	If wType is DBTYPE_STR or DBTYPE_WSTR, this is the maximum length in characters for values in this column. If wType is DBTYPE_BYTES, this is the maximum length in bytes for values in this column. For all other values of wType, this is ignored. Providers that do not require a length argument in the specification of the provider type (pwszTypeName) ignore this value.
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 a numeric type; 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 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.

riid

[in]
The IID of the interface to be returned for the resulting rowset; this is ignored if ppRowset is a null pointer.

cPropertySets

[in]
The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets.

rgPropertySets

[in/out]
An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures must belong to the Rowset property group (for properties that apply to the rowset returned in *ppRowset) or the Table property group (for properties that apply to the table). If the same property is specified more than once in rgPropertySets, then it is provider-specific which value is used. If cPropertySets is zero, this argument is ignored.

For information about the properties in the Rowset and Tables property groups that are defined by OLE DB, see "Rowset Properties" and "Table Properties" in Appendix C. For information about the DBPROPSET and DBPROP structures, see "DBPROPSET Structure" and "DBPROP Structure" in Chapter 11.

ppTableID

[out]
A pointer to memory in which to return the DBID of the newly created table. If ppTableID is a null pointer, no DBID is returned.

ppRowset

[out]
A pointer to memory in which to return the requested interface pointer on an empty rowset opened on the newly created table. If ppRowset is a null pointer, no rowset is created.

Return Code

S_OK
The method succeeded and the table is created and opened. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK.

DB_S_ERRORSOCCURRED
The table was created and the rowset was opened, but one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_OPTIONAL—were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. The method can fail to set properties for a number of reasons, including:

The property was not supported by the provider.
The property was not in the Column, Rowset, or Table property group.
The property set was not supported by the provider.
It was not possible to set the property.
colid in the DBPROP structure was not DB_NULLID.
The data type in vValue in the DBPROP structure was not the data type of the property or was not VT_EMPTY.
The value in vValue in the DBPROP structure was invalid.
The property's value conflicted with an existing property.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
pTableID and ppTableID were both null pointers.

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.

DB_E_BADCOLUMNID
dbcid in an element of rgColumnDescs was an invalid column ID.

DB_E_BADTABLEID
*pTableID was an invalid table ID.

DB_E_BADPRECISION
The precision in an element of rgColumnDescs was invalid.

DB_E_BADSCALE
The scale in an element of rgColumnDescs was invalid.

DB_E_BADTYPE
One or more of the wType, pwszTypeName, and pTypeInfo elements in an element of rgColumnDescs was invalid.

DB_E_DUPLICATECOLUMNID
dbcid was the same in two or more elements of rgColumnDescs.

DB_E_DUPLICATETABLEID
The specified table already exists in the current data source.

DB_E_ERRORSOCCURRED
The table was not created and no rowset was returned because one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED or an invalid value—could not be set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED.

DB_E_NOAGGREGATION
pUnkOuter was not a null pointer and the rowset being created does not support aggregation.

pUnkOuter was non-null and riid was not IID_Unknown.

DB_SEC_E_PERMISSIONDENIED
The consumer did not have sufficient permission to create the table.

DB_E_OBJECTOPEN
The provider would have to open a new connection to support the operation and DBPROP_MULTIPLECONNECTIONS is set to VARIANT_FALSE.

Comments

If ppRowset is not a null pointer, an empty rowset is opened on the newly created table. If CreateTable returns any errors, the table is not created, and ppTableID is set to NULL on output.