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

ITableDefinitionWithConstraints::CreateTableWithConstraints

Creates a new base table in the data store.

HRESULT CreateTableWithConstraints(
   IUnknown *         pUnkOuter,
   DBID *             pTableID,
   ULONG              cColumnDescs,
   DBCOLUMNDESC       rgColumnDescs[],
   ULONG              cConstraintDescs,
   DBCONSTRAINTDESC   rgConstraintDescs[],
   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. For more information on the DBCOLUMNDESC structure, please refer to ITableDefinition::CreateTable.

cConstraintDescs

[in]
The number of DBCONSTRAINTDESC structures in the rgConstraintDescs array. If this is zero, rgConstraintDescs is ignored.

rgConstraintDescs

[in]
An array of DBCONSTRAINTDESC structures that describe constraints to be created on the table. For more information on this structure, please refer to ITableDefinitionWithConstraints::AddConstraint.

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.

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.

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

cConstraintDescs was not zero, and rgConstraintDescs was a null pointer.

In an element of rgConstraintDescs, cForeignKeyColumns was not zero and rgForeignKeyColumnList was null.

In an element of rgConstraintDescs, cColumns was not zero and rgColumnList was null.

In an element of rgConstraintDescs, cPropertySets was not zero and rgPropertySets was a null pointer.

DB_E_BADCOLUMNID

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

The DBCONSTRAINTDESC structure contained a reference to an invalid column ID, either in rgForeignKeyColumnList, when rgForeignKeyColumnList is not ignored, or in rgColumnList.

DB_E_DUPLICATECONSTRAINTID

In an element of rgConstraintDescs, pConstraintID was the same as an existing constraint.

DB_E_BADID

In an element of rgConstraintDescs, pConstraintID was invalid.

In an element of rgConstraintDescs, pReferencedTableID was invalid.

DB_E_BADCONSTRAINTTYPE

In an element of rgConstraintDescs, ConstraintType was invalid or not supported by the provider.

DB_E_BADUPDATEDELETERULE

In an element of rgConstraintDescs, UpdateRule or DeleteRule was invalid or the value was not supported by the provider.

DB_E_BADMATCHTYPE

In an element of rgConstraintDescs, MatchType was invalid or the value was not supported by the provider.

DB_E_BADDEFERRABILITY

In an element of rgConstraintDescs, Deferrability was invalid or the value was not supported by the provider.

DB_E_BADCONSTRAINTFORM

ConstraintType was not DBCONSTRAINTTYPE_FOREIGNKEY, and cForeignKeyColumns was not zero.

ConstraintType was not DBCONSTRAINTTYPE_FOREIGNKEY, and pReferencedTableID was not a null pointer.

ConstraintType was DBCONSTRAINTTYPE_CHECK, and pwszConstraintText was a null pointer.

ConstraintType was not DBCONSTRAINTTYPE_CHECK, and pwszConstraintText was not a null pointer.

ConstraintType was DBCONSTRAINTTYPE_FOREIGNKEY, and cForeignKeyColumns was zero.

ConstraintType was DBCONSTRAINTTYPE_FOREIGNKEY, DBCONSTRAINTTYPE_PRIMARYKEY, or DBCONSTRAINTTYPE_UNIQUE and cColumns was zero.

In an element of rgConstraintDescs, pReferencedTableID was a null pointer, and cForeignKeyColumns was not zero.

DB_E_BADTABLEID

*pTableID was an invalid table ID.

DB_E_BADPRECISION

The precision in an element of rgColumnDescs was invalid.

DB_E_BADPROPERTYVALUE

The value of a property 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 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—were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. None of the satisfiable properties are remembered. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED, except the reason that states that it was not possible to set the property.

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 ITableDefinitionWithConstraints::CreateTableWithConstraints returns any errors, the table is not created nor are any relationships on that table created.

ITableDefinitionWithConstraints::CreateTableWithConstraints is similar to ITableDefinition::CreateTable except that it also provides the ability to create constraints such as primary keys, foreign keys, unique clauses, or check clauses in the same call as the creation of the table. This closely mimics the functionality of the CREATE TABLE SQL statement.

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.