MDAC 2.5 SDK - OLE DB Programmer's Reference
OLE DB Interfaces
Adds a new constraint to a base table.
HRESULT AddConstraint(
DBID * pTableID,
DBCONSTRAINTDESC * pConstraintDesc);
Parameters
pTableID
[in]
A pointer to the DBID of the table to which the constraint is to be added.
pConstraintDesc
[in]
A pointer to the DBCONSTRAINTDESC structure that describes the new constraint. DBCONSTRAINTDESC is defined as follows:
typedef struct tagDBCONSTRAINTDESC {
DBID * pConstraintID;
DBCONSTRAINTTYPE ConstraintType;
ULONG cColumns;
DBID rgColumnList[];
DBID * pReferencedTableID;
ULONG cForeignKeyColumns;
DBID rgForeignKeyColumnList[];
OLECHAR * pwszConstraintText;
DBUPDELRULE UpdateRule;
DBUPDELRULE DeleteRule;
DBMATCHTYPE MatchType;
DBDEFERRABILITY Deferrability;
ULONG cPropertySets;
DBPROPSET rgPropertySets[];
} DBCONSTRAINTDESC;
The elements of this structure are used as described in the following table.
| Element | Description |
| pConstraintID | The constraint identifier. If this is null, the provider generates a unique ID for the constraint. This ID is not returned to the consumer through the DBCONSTRAINTDESC structure. Consumers should generally specify a value for the constraint and not set pConstraintID to null, because there is no easy way to get back the ID for the added constraint. |
| ConstraintType | The type of the constraint as defined in the DBCONSTRAINTYPE enum. One of the following values:
DBCONSTRAINTTYPE_UNIQUE |
| cColumns | The number of elements in the array passed in rgColumnList. For check constraints, this is always zero. If cColumns is zero, rgColumnList is ignored. |
| rgColumnList | For unique and primary key constraints, this contains the list of columns that comprise the constraint. For foreign key constraints, this defines the list of columns that make up the referenced key in a relationship.
The order of the elements in this array comprise the key columns in descending order of significance. As such, the first element is the most significant key column and the last element in the array is the least significant key column. |
| pReferencedTableID | For foreign keys, this contains the referenced table in a relationship. For all other types of constraints, this is null. |
| cForeignKeyColumns | The number of elements in the array passed in rgForeignKeyColumnList. If cForeignKeyColumns is zero, rgForeignKeyColumnList is ignored. This field must be zero if pReferencedTableID is a null pointer. |
| rgForeignKeyColumnList | The columns that comprise the foreign key in a relationship.
The order of the elements in this array comprise the key columns in descending order of significance. As such, the first element is the most significant key column and the last element in the array is the least significant key column. This field is ignored if cForeignKeyColumns is zero. |
| pwszConstraintText | The constraint clause. If ConstraintType is not DBCONSTRAINTTYPE_CHECK, this must be a null pointer. |
| UpdateRule | The update rule (as defined in SQL-92). One of the following values:
DBUPDELRULE_NOACTION This field is ignored unless ConstraintType is DBCONSTRAINTTYPE_FOREIGNKEY. |
| DeleteRule | The delete rule (as defined in SQL-92). One of the following values:
DBUPDELRULE_NOACTION This field is ignored unless ConstraintType is DBCONSTRAINTTYPE_FOREIGNKEY. |
| MatchType | The match type (as defined in SQL-92). This field is ignored unless ConstraintType is DBCONSTRAINTTYPE_FOREIGNKEY. One of the following values:
DBMATCHTYPE_NONE |
| Deferrability | Whether the constraint is applied immediately. Values from the following bitmask:
DBDEFERRABILITY_DEFERRED Deferred Not specifying DBDEFERRABILITY_DEFERRED implies that the constraint is immediate. Not specifying DBDEFERRABILITY_ DEFERRABLE implies that the constraint is not deferrable. If DBDEFERRABILITY_DEFERRABLE is not specified, the DBDEFERRABILITY_DEFERRED bit is ignored and the constraint is immediate. |
| cPropertySets | The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets.
This parameter applies to constraint properties and is reserved for future use. |
| rgPropertySets | An array of DBPROPSET structures containing properties and values to be set. If cPropertySets is zero, this argument is ignored.
This parameter applies to constraint properties and is reserved for future use. |
Return Code
S_OK
The method succeeded.
E_FAIL
A provider-specific error occurred.
E_INVALIDARG
pTableID or pConstraintDesc was a null pointer.
cForeignKeyColumns was not zero, and rgForeignKeyColumnList was null.
cColumns was not zero, and rgColumnList was null.
cPropertySets was not zero, and rgPropertySets was a null pointer.
DB_E_BADTABLEID
*pTableID was an invalid table ID.
pReferencedTableID was an invalid table ID.
DB_E_DUPLICATECONSTRAINTID
pConstraintID was the same as an existing constraint.
DB_E_BADID
pConstraintID was invalid.
DB_E_BADCONSTRAINTTYPE
ConstraintType was invalid or not supported by the provider.
DB_E_BADUPDATEDELETERULE
UpdateRule or DeleteRule was invalid, or the value was not supported by the provider.
DB_E_BADMATCHTYPE
MatchType was invalid, or the value was not supported by the provider.
DB_E_BADDEFERRABILITY
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.
pReferencedTableID was a null pointer, and cForeignKeyColumns was not zero.
DB_E_BADCOLUMNID
The DBCONSTRAINTDESC structure contained a reference to an invalid column ID, either in rgForeignKeyColumnList, when rgForeignKeyColumnList is not ignored, or in rgColumnList.
DB_E_NOTABLE
The specified table does not exist in the data store.
The table defined in pReferencedTableID does not exist.
DB_E_TABLEINUSE
The specified table was in use, and the provider could not add a constraint as a result.
DB_SEC_E_PERMISSIONDENIED
The consumer did not have sufficient permission to add a constraint.
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 AddConstraint returns any errors, the constraint is not created.
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.
See Also
ITableDefinitionWithConstraints::CreateTableWithConstraints, ITableDefinitionWithConstraints::DropConstraint