Compartilhar via

ITableDefinition::CreateTable

  • Artigo

Creates a new base table in the data store.

Syntax

HRESULT CreateTable(
   IUnknown            *pUnkOuter,
   DBID                *pTableID,
   DBORDINAL            cColumnDescs,
   const 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;
   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.

    TipTip
    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 DBPROP_COL_ISLONG and DBPROP_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.

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

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

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

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

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

See Also

Reference

IDBProperties::GetPropertyInfo

ITableDefinition::AddColumn

ITableDefinition::DropColumn

ITableDefinition::DropTable