Criando tabelas do SQL Server
O provedor do OLE DB do SQL Server Native Client expõe a função ITableDefinition::CreateTable, permitindo que os consumidores criem tabelas SQL Server. Os consumidores usam CreateTable para criar tabelas permanentes nomeadas pelo consumidor, além de tabelas permanentes ou temporárias com nomes exclusivos gerados pelo provedor do OLE DB do SQL Server Native Client.
Quando o consumidor chama ITableDefinition::CreateTable, se o valor da propriedade DBPROP_TBL_TEMPTABLE é VARIANT_TRUE, o provedor do OLE DB do SQL Server Native Client gera um nome de tabela temporária para o consumidor. O consumidor define o parâmetro pTableID do método CreateTable como NULL. As tabelas temporárias com nomes gerados pelo provedor do OLE DB do SQL Server Native Client não aparecem no conjunto de linhas de TABLES, mas são acessíveis pela interface IOpenRowset.
Quando os consumidores especificam o nome da tabela no membro pwszName da união uName no parâmetro pTableID, o provedor do OLE DB do SQL Server Native Client cria uma tabela SQL Server com esse nome. As restrições de nomeação de tabela SQL Server se aplicam, e o nome da tabela pode indicar uma tabela permanente, ou uma tabela temporária local ou global. Para obter mais informações, consulte CREATE TABLE. O parâmetro ppTableID pode ser NULL.
O provedor do OLE DB do SQL Server Native Client pode gerar os nomes de tabelas permanentes ou temporárias. Quando o consumidor define o parâmetro pTableID como NULL e define ppTableID para que aponte para um DBID* válido, o provedor do OLE DB do SQL Server Native Client retorna o nome gerado da tabela no membro pwszName da união uName do DBID apontado no valor de ppTableID. Para criar uma tabela temporária nomeada pelo provedor do OLE DB do SQL Server Native Client, o consumidor inclui a propriedade de tabela DBPROP_TBL_TEMPTABLE do OLE DB em um conjunto de propriedades de tabela referenciado no parâmetro rgPropertySets. As tabelas temporárias nomeadas pelo provedor do OLE DB do SQL Server Native Client são locais.
CreateTable retornará DB_E_BADTABLEID se o membro eKind do parâmetro pTableID não indicar DBKIND_NAME.
Uso de DBCOLUMNDESC
O consumidor pode indicar um tipo de dados de coluna usando o membro pwszTypeName ou o membro wType. Se o consumidor especificar o tipo de dados em pwszTypeName, o provedor do OLE DB do SQL Server Native Client ignorará o valor de wType.
Se estiver usando o membro pwszTypeName, o consumidor especificará o tipo de dados usando nomes de tipo de dados do SQL Server. Os nomes de tipo de dados válidos são aqueles retornados na coluna de TYPE_NAME do conjunto de linhas de esquema de PROVIDER_TYPES.
O provedor do OLE DB do SQL Server Native Client reconhece um subconjunto de valores DBTYPE enumerados por OLE DB no membro wType. Para obter mais informações, consulte Mapeamento do tipo de dados em ITableDefinition.
.gif "Observação") Observação |
|---|
CreateTable retornará DB_E_BADTYPE se o consumidor definir o membro pTypeInfo ou o pclsid para especificar o tipo de dados de coluna. |
O consumidor especifica o nome da coluna no membro pwszName da união uName do membro dbcid de DBCOLUMNDESC. O nome da coluna é especificado como uma cadeia de caracteres Unicode. O membro eKind de dbcid precisa ser DBKIND_NAME. CreateTable retornará DB_E_BADCOLUMNID se eKind for inválido, se pwszName for NULL ou se o valor de pwszName não for um identificador válido do SQL Server.
Todas as propriedades de coluna estão disponíveis em todas as colunas definidas para a tabela. CreateTable poderá retornar DB_S_ERRORSOCCURRED ou DB_E_ERRORSOCCURRED se os valores de propriedade forem definidos em conflito. CreateTable retornará um erro quando configurações de propriedade de coluna inválidas causarem falha na criação de tabelas do SQL Server.
As propriedades de coluna em um DBCOLUMNDESC são interpretadas da seguinte maneira.
ID da propriedade |
Descrição |
|---|---|
DBPROP_COL_AUTOINCREMENT |
Leitura/gravação: leitura/gravação Padrão: VARIANT_FALSE Descrição: define a propriedade de identidade na coluna criada. Para SQL Server, a propriedade de identidade é válida para uma única coluna de uma tabela. A definição da propriedade como VARIANT_TRUE para mais de uma única coluna gera um erro quando o provedor do OLE DB do SQL Server Native Client tenta criar a tabela no servidor. A propriedade de identidade do SQL Server só é válida para os tipos integer, numeric e decimal quando a escala é 0. A definição da propriedade como VARIANT_TRUE em uma coluna de qualquer tipo de dados gera um erro quando o provedor do OLE DB do SQL Server Native Client tenta criar a tabela no servidor. O provedor do OLE DB do SQL Server Native Client retorna DB_S_ERRORSOCCURRED quando DBPROP_COL_AUTOINCREMENT e DBPROP_COL_NULLABLE são ambos VARIANT_TRUE e o dwOption de DBPROP_COL_NULLABLE não é DBPROPOPTIONS_REQUIRED. DB_E_ERRORSOCCURRED é retornado quando DBPROP_COL_AUTOINCREMENT e DBPROP_COL_NULLABLE são ambos VARIANT_TRUE e o dwOption de DBPROP_COL_NULLABLE é igual a DBPROPOPTIONS_REQUIRED. A coluna é definida com a propriedade de identidade SQL Server e o membro dwStatus DBPROP_COL_NULLABLE é definido como DBPROPSTATUS_CONFLICTING. |
DBPROP_COL_DEFAULT |
Leitura/gravação: leitura/gravação Padrão: nenhum Descrição: Cria uma restrição SQL Server DEFAULT para a coluna. O membro de DBPROP vValue pode ser qualquer um dentre inúmeros tipos. O membro vValue.vt deveria especificar um tipo compatível com o tipo de dados da coluna. Por exemplo, a definição de BSTR N/A como o valor padrão para uma coluna definida como DBTYPE_WSTR é uma correspondência compatível. A definição do mesmo padrão em uma coluna definida como DBTYPE_R8 gera um erro quando o provedor do OLE DB do SQL Server Native Client tenta criar a tabela no servidor. |
DBPROP_COL_DESCRIPTION |
Leitura/gravação: leitura/gravação Padrão: nenhum Descrição: a propriedade de coluna DBPROP_COL_DESCRIPTION não é implementada pelo provedor do OLE DB do SQL Server Native Client. O membro dwStatus da estrutura DBPROP retorna DBPROPSTATUS_NOTSUPPORTED quando o consumidor tentar escrever o valor da propriedade. A definição da propriedade não constitui um erro fatal para o provedor do OLE DB do SQL Server Native Client. Se todos os outros valores de parâmetro forem válidos, será criada a tabela do SQL Server. |
DBPROP_COL_FIXEDLENGTH |
Leitura/gravação: leitura/gravação Padrão: VARIANT_FALSE Descrição: o provedor do OLE DB do SQL Server Native Client usa DBPROP_COL_FIXEDLENGTH para determinar o mapeamento de tipos de dados quando o consumidor define um tipo de dados de coluna usando o membro wType de DBCOLUMNDESC. Para obter mais informações, consulte Mapeamento do tipo de dados em ITableDefinition. |
DBPROP_COL_NULLABLE |
Leitura/gravação: leitura/gravação Padrão: nenhum Descrição: ao criar a tabela, o provedor do OLE DB do SQL Server Native Client indica se a coluna deve aceitar valores nulos se a propriedade for definida. Quando a propriedade não é definida, a capacidade da coluna de aceitar NULL como valor é determinado pela opção de banco de dados padrão ANSI_NULLS do SQL Server. O provedor do OLE DB do SQL Server Native Client está em conformidade com a norma ISO. Sessões conectadas exibem comportamentos de ISO. Se o consumidor não definir DBPROP_COL_NULLABLE, as colunas aceitarão valores nulos. |
DBPROP_COL_PRIMARYKEY |
Leitura/gravação: leitura/gravação Padrão: VARIANT_FALSE Descrição: quando VARIANT_TRUE, o provedor do OLE DB do SQL Server Native Client cria a coluna com uma restrição de PRIMARY KEY. Quando definido como uma propriedade de coluna, só uma única coluna pode determinar a restrição. A definição da propriedade como VARIANT_TRUE para mais de uma única coluna gera um erro quando o provedor do OLE DB do SQL Server Native Client tenta criar a tabela do SQL Server. Observação: o consumidor pode usar IIndexDefinition::CreateIndex para criar uma restrição de PRIMARY KEY em duas ou mais colunas. O provedor do OLE DB do SQL Server Native Client retorna DB_S_ERRORSOCCURRED quando DBPROP_COL_PRIMARYKEY e DBPROP_COL_UNIQUE são ambos VARIANT_TRUE e dwOption de DBPROP_COL_UNIQUE não é DBPROPOPTIONS_REQUIRED. DB_E_ERRORSOCCURRED é retornado quando DBPROP_COL_PRIMARYKEY e DBPROP_COL_UNIQUE são ambos VARIANT_TRUE e dwOption de DBPROP_COL_UNIQUE é igual a DBPROPOPTIONS_REQUIRED. A coluna é definida com a propriedade de identidade do SQL Server e o membro dwStatus de DBPROP_COL_PRIMARYKEY é definido como DBPROPSTATUS_CONFLICTING. O provedor do OLE DB do SQL Server Native Client retorna um erro quando DBPROP_COL_PRIMARYKEY e DBPROP_COL_NULLABLE são ambos VARIANT_TRUE. O provedor do OLE DB do SQL Server Native Client retorna um erro do SQL Server quando o consumidor tenta criar a restrição de PRIMARY KEY em uma coluna de tipo de dados inválido do SQL Server. Não podem ser definidas restrições de PRIMARY KEY em colunas criadas com os tipos de dados bit, text, ntext e image do SQL Server. |
DBPROP_COL_UNIQUE |
Leitura/gravação: leitura/gravação Padrão: VARIANT_FALSE Descrição: aplica uma restrição UNIQUE do SQL Server à coluna. Quando definido como uma propriedade de coluna, a restrição só é aplicada em uma única coluna. O consumidor pode usar IIndexDefinition::CreateIndex para aplicar uma restrição de UNIQUE nos valores combinados de duas ou mais colunas. O provedor do OLE DB do SQL Server Native Client retorna DB_S_ERRORSOCCURRED quando DBPROP_COL_PRIMARYKEY e DBPROP_COL_UNIQUE são ambos VARIANT_TRUE e dwOption não é DBPROPOPTIONS_REQUIRED. DB_E_ERRORSOCCURRED é retornado quando DBPROP_COL_PRIMARYKEY e DBPROP_COL_UNIQUE são ambos VARIANT_TRUE e dwOption é igual a DBPROPOPTIONS_REQUIRED. A coluna é definida com a propriedade de identidade do SQL Server e o membro dwStatus de DBPROP_COL_PRIMARYKEY é definido como DBPROPSTATUS_CONFLICTING. O provedor do OLE DB do SQL Server Native Client retorna DB_S_ERRORSOCCURRED quando DBPROP_COL_NULLABLE e DBPROP_COL_UNIQUE são ambos VARIANT_TRUE e dwOption não é DBPROPOPTIONS_REQUIRED. DB_E_ERRORSOCCURRED é retornado quando DBPROP_COL_NULLABLE e DBPROP_COL_UNIQUE são ambos VARIANT_TRUE e dwOption é igual a DBPROPOPTIONS_REQUIRED. A coluna é definida com a propriedade de identidade SQL Server e o membro dwStatus DBPROP_COL_NULLABLE é definido como DBPROPSTATUS_CONFLICTING. O provedor do OLE DB do SQL Server Native Client retorna um erro do SQL Server quando o consumidor tenta criar a restrição de UNIQUE em uma coluna de tipo de dados inválido do SQL Server. Não é possível definir restrições de UNIQUE em colunas criadas com o tipo de dados SQL Serverbit. |
Quando o consumidor chama ITableDefinition::CreateTable, o provedor do OLE DB do SQL Server Native Client interpreta propriedades de tabela da seguinte maneira.
ID da propriedade |
Descrição |
|---|---|
DBPROP_TBL_TEMPTABLE |
Leitura/gravação: leitura/gravação Padrão: VARIANT_FALSE Descrição: por padrão, o provedor do OLE DB do SQL Server Native Client cria tabelas nomeadas pelo consumidor. Quando VARIANT_TRUE, o provedor do OLE DB do SQL Server Native Client gera um nome de tabela temporária para o consumidor. O consumidor define o parâmetro pTableID de CreateTable como NULL. O parâmetro ppTableID precisa conter um ponteiro válido. |
Se o consumidor solicitar que um conjunto de linhas seja aberto em uma tabela criada com êxito, o provedor do OLE DB do SQL Server Native Client abrirá um conjunto de linhas com suporte de cursor. Qualquer propriedade de conjunto de linhas pode ser indicada nos conjuntos de propriedade passados.
O exemplo a seguir cria uma tabela do SQL Server.
// This CREATE TABLE statement shows the details of the table created by
// the following example code.
//
// CREATE TABLE OrderDetails
// (
// OrderID int NOT NULL
// ProductID int NOT NULL
// CONSTRAINT PK_OrderDetails
// PRIMARY KEY CLUSTERED (OrderID, ProductID),
// UnitPrice money NOT NULL,
// Quantity int NOT NULL,
// Discount decimal(2,2) NOT NULL
// DEFAULT 0
// )
//
// The PRIMARY KEY constraint is created in an additional example.
HRESULT CreateTable
(
ITableDefinition* pITableDefinition
)
{
DBID dbidTable;
const ULONG nCols = 5;
ULONG nCol;
ULONG nProp;
DBCOLUMNDESC dbcoldesc[nCols];
HRESULT hr;
// Set up column descriptions. First, set default property values for
// the columns.
for (nCol = 0; nCol < nCols; nCol++)
{
dbcoldesc[nCol].pwszTypeName = NULL;
dbcoldesc[nCol].pTypeInfo = NULL;
dbcoldesc[nCol].rgPropertySets = new DBPROPSET;
dbcoldesc[nCol].pclsid = NULL;
dbcoldesc[nCol].cPropertySets = 1;
dbcoldesc[nCol].ulColumnSize = 0;
dbcoldesc[nCol].dbcid.eKind = DBKIND_NAME;
dbcoldesc[nCol].wType = DBTYPE_I4;
dbcoldesc[nCol].bPrecision = 0;
dbcoldesc[nCol].bScale = 0;
dbcoldesc[nCol].rgPropertySets[0].rgProperties =
new DBPROP[NCOLPROPS_MAX];
dbcoldesc[nCol].rgPropertySets[0].cProperties = NCOLPROPS_MAX;
dbcoldesc[nCol].rgPropertySets[0].guidPropertySet =
DBPROPSET_COLUMN;
for (nProp = 0; nProp < NCOLPROPS_MAX; nProp++)
{
dbcoldesc[nCol].rgPropertySets[0].rgProperties[nProp].
dwOptions = DBPROPOPTIONS_REQUIRED;
dbcoldesc[nCol].rgPropertySets[0].rgProperties[nProp].colid
= DB_NULLID;
VariantInit(
&(dbcoldesc[nCol].rgPropertySets[0].rgProperties[nProp].
vValue));
dbcoldesc[nCol].rgPropertySets[0].rgProperties[nProp].
vValue.vt = VT_BOOL;
}
}
// Set the column-specific information.
dbcoldesc[0].dbcid.uName.pwszName = L"OrderID";
dbcoldesc[0].rgPropertySets[0].rgProperties[0].dwPropertyID =
DBPROP_COL_NULLABLE;
dbcoldesc[0].rgPropertySets[0].rgProperties[0].vValue.boolVal =
VARIANT_FALSE;
dbcoldesc[0].rgPropertySets[0].cProperties = 1;
dbcoldesc[1].dbcid.uName.pwszName = L"ProductID";
dbcoldesc[1].rgPropertySets[0].rgProperties[0].dwPropertyID =
DBPROP_COL_NULLABLE;
dbcoldesc[1].rgPropertySets[0].rgProperties[0].vValue.boolVal =
VARIANT_FALSE;
dbcoldesc[1].rgPropertySets[0].cProperties = 1;
dbcoldesc[2].dbcid.uName.pwszName = L"UnitPrice";
dbcoldesc[2].wType = DBTYPE_CY;
dbcoldesc[2].rgPropertySets[0].rgProperties[0].dwPropertyID =
DBPROP_COL_NULLABLE;
dbcoldesc[2].rgPropertySets[0].rgProperties[0].vValue.boolVal =
VARIANT_FALSE;
dbcoldesc[2].rgPropertySets[0].cProperties = 1;
dbcoldesc[3].dbcid.uName.pwszName = L"Quantity";
dbcoldesc[3].rgPropertySets[0].rgProperties[0].dwPropertyID =
DBPROP_COL_NULLABLE;
dbcoldesc[3].rgPropertySets[0].rgProperties[0].vValue.boolVal =
VARIANT_FALSE;
dbcoldesc[3].rgPropertySets[0].cProperties = 1;
dbcoldesc[4].dbcid.uName.pwszName = L"Discount";
dbcoldesc[4].wType = DBTYPE_NUMERIC;
dbcoldesc[4].bPrecision = 2;
dbcoldesc[4].bScale = 2;
dbcoldesc[4].rgPropertySets[0].rgProperties[0].dwPropertyID =
DBPROP_COL_NULLABLE;
dbcoldesc[4].rgPropertySets[0].rgProperties[0].vValue.boolVal =
VARIANT_FALSE;
dbcoldesc[4].rgPropertySets[0].rgProperties[1].dwPropertyID =
DBPROP_COL_DEFAULT;
dbcoldesc[4].rgPropertySets[0].rgProperties[1].vValue.vt = VT_BSTR;
dbcoldesc[4].rgPropertySets[0].rgProperties[1].vValue.bstrVal =
SysAllocString(L"0");
dbcoldesc[4].rgPropertySets[0].cProperties = 2;
// Set up the dbid for OrderDetails.
dbidTable.eKind = DBKIND_NAME;
dbidTable.uName.pwszName = L"OrderDetails";
if (FAILED(hr = pITableDefinition->CreateTable(NULL, &dbidTable,
nCols, dbcoldesc, NULL, 0, NULL, NULL, NULL)))
{
DumpError(pITableDefinition, IID_ITableDefinition);
goto SAFE_EXIT;
}
SAFE_EXIT:
// Clean up dynamic allocation in the property sets.
for (nCol = 0; nCol < nCols; nCol++)
{
for (nProp = 0; nProp < NCOLPROPS_MAX; nProp++)
{
if (dbcoldesc[nCol].rgPropertySets[0].rgProperties[nProp].
vValue.vt == VT_BSTR)
{
SysFreeString(dbcoldesc[nCol].rgPropertySets[0].
rgProperties[nProp].vValue.bstrVal);
}
}
delete [] dbcoldesc[nCol].rgPropertySets[0].rgProperties;
delete [] dbcoldesc[nCol].rgPropertySets;
}
return (hr);
}