ITableCreation::GetTableDefinition

  • Article

Returns creation information for a table.

Syntax

HRESULT GetTableDefinition(
   DBID               *pTableID,
   DBORDINAL          *pcColumnDescs,
   DBCOLUMNDESC       *prgColumnDescs[],
   ULONG              *pcPropertySets,
   DBPROPSET          *prgPropertySets[],
   ULONG              *pcConstraintDescs,
   DBCONSTRAINTDESC   *prgConstraintDescs[],
   OLECHAR           **ppwszStringBuffer);

Parameters

  • pTableID
    [in] A pointer to the ID of the table to describe.

  • pcColumnDescs
    [out] A pointer to the number of DBCOLUMNDESC structures in the prgColumnDescs array. If pcColumnDescs is NULL, the provider ignores prgColumnDescs and does not return any column descriptions.

  • prgColumnDescs
    [out] A pointer to an array of DBCOLUMNDESC structures that describe the columns of the table, or NULL if the consumer is not interested in getting back column descriptions. For more information on the DBCOLUMNDESC structure, see ITableDefinition::CreateTable.

  • pcPropertySets
    [out] A pointer to the number of DBPROPSET structures in prgPropertySets. If this is NULL, the provider ignores prgPropertySets and does not return any table creation properties.

  • prgPropertySets
    [out] A pointer to an array of DBPROPSET structures containing properties and values used in creation of the table, or NULL if the consumer is not interested in getting back table creation properties. The properties returned in these structures belong to the Table property group.

    For information about the properties in the Tables property groups that are defined by OLE DB, see Table Property Group in Appendix C: OLE DB Properties. For information about the DBPROPSET and DBPROP structures, see DBPROPSET Structure and DBPROP Structure.

  • pcConstraintDescs
    [out] A pointer to the number of DBCONSTRAINTDESC structures in the prgConstraintDescs array. If this is NULL, the provider ignores the value of prgConstraintDescs and does not return any column descriptions.

  • prgConstraintDescs
    [out] A pointer to an array of DBCONSTRAINTDESC structures that describe the columns of the table, or NULL if no constraint definitions are to be returned to the consumer. For more information on DBCONSTRAINTDESC structure, see ITableDefinitionWithConstraints::AddConstraint.

  • ppwszStringBuffer
    [out] A pointer to memory in which to return a pointer to storage for all string values returned in the pwszTypeName element of DBCOLUMNDESC structure or the pwszConstraintText element of the DBCONSTRAINTDESC structure. The provider allocates this memory with IMalloc, and the consumer frees it with IMalloc::Free when it no longer needs the descriptions. If ppwszStringBuffer is a null pointer on input, ITableCreation::GetTableDefinition does not return the string values. If no shared memory is allocated for pwszTypeName or pwszConstraintText for any elements of prgColumnDescs or prgConstraintDescs, respectively, or if an error occurs, the provider does not allocate any memory and ensures that *ppwszStringBuffer is a null pointer on output. Each of the individual string values stored in this buffer is terminated by a null-termination character. Therefore, the buffer may contain one or more strings, each with its own null-termination character, and may contain embedded null-termination characters.

Return Code

  • S_OK
    The method succeeded.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    pTableID was a null pointer.

    pcColumnDescs was not null, and prgColumnDescs was a null pointer.

    pcPropertySets was not null, and prgPropertySets was a null pointer.

    pcConstraintDescs was not null, and prgConstraintDescs was a null pointer.

    pcColumnDescs, pcPropertySets, and pcConstraintDescs were all null pointers.

  • DB_E_NOTABLE
    The table specified in pTableID does not exist in the current data source.

Comments

ITableCreation::GetTableDefinition returns the properties and column definitions of the specified table. The provider also returns the definitions of the constraints currently applied to the table. These constraints may be different from the constraints with which the table was initially created if the consumer has added or dropped constraints since the table was created.

Providers are allowed to use a static property array to report table and column properties returned by this method, either within prgColumnDescs or within prgPropertySets. If a property does not apply to the table or column or if the provider cannot determine the setting for a table or column property, the provider can return DBPROPSTATUS_OK and a property value of VT_EMPTY.

See Also

Reference

ITableDefinition::CreateTable