MDAC 2.5 SDK - OLE DB Programmer's Reference
OLE DB Interfaces

ITableDefinition::CreateTable

Creates a new base table in the data store.

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 decides the values to use in the nonproperties elements of this structure based on values from 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).

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 there is no requirement to do so, providers should implement the PROVIDER_TYPES schema rowset if also implementing ITableDefinition. Otherwise, it may force the consumer to know the provider's types in advance, since 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	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 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.

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, it is provider-specific which value is used. If cPropertySets is zero, this argument is ignored.

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.”

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.

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.

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 following:

The colid element of the DBPROP structure for a rowset property was invalid. To be valid, this element 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.
The colid element of the DBPROP structure for a table property 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.
The property was not supported by the provider.
The property set was not supported by the provider.
It was not possible to set the property.
The property was not in the Column, Rowset, or Table property group.

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.

E_NOINTERFACE

The rowset did not support the interface specified in riid.

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.

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

The wType, pwszTypeName, or pTypeInfo element, in an element of rgColumnDescs was invalid.

In an element of rgColumnDescs, pwszTypeName was non-null and implied a DBTYPE other than the type specified by wType.

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 store.

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 provider is an OLE DB 1.0 or 1.1 provider that does not support aggregation of the rowset object being created.

pUnkOuter was not a null pointer, and riid was not IID_IUnknown.

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.

XACT_E_XTIONEXISTS

The provider supports transactional DDL, the session is participating in a transaction, and the value of DBPROP_SUPPORTEDTXNDDL is DBPROPVAL_TC_DML.

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.