Creazione di tabelle di SQL Server
Il provider OLE DB di SQL Server Native Client espone la funzione ITableDefinition::CreateTable, consentendo ai consumer di creare tabelle di SQL Server. I consumer utilizzano CreateTable per creare tabelle permanenti denominate dal consumer e tabelle permanenti o temporanee con nomi univoci generati dal provider OLE DB di SQL Server Native Client.
Se quando il consumer chiama ITableDefinition::CreateTable il valore della proprietà DBPROP_TBL_TEMPTABLE è VARIANT_TRUE, il provider OLE DB di SQL Server Native Client genera un nome di tabella temporanea per il consumer. Il consumer imposta il parametro pTableID del metodo CreateTable su NULL. Le tabelle temporanee con nomi generati dal provider OLE DB di SQL Server Native Client non vengono visualizzate nel set di righe TABLES, ma è possibile accedervi tramite l'interfaccia IOpenRowset.
Quando i consumer specificano il nome di tabella nel membro pwszName dell'unione uName nel parametro pTableID, il provider OLE DB di SQL Server Native Client crea una tabella di SQL Server con tale nome. Vengono applicati vincoli di denominazione delle tabelle di SQL Server e il nome di tabella può indicare una tabella permanente oppure una tabella temporanea locale o globale. Per ulteriori informazioni, vedere CREATE TABLE. Il parametro ppTableID può essere NULL.
Il provider OLE DB di SQL Server Native Client può generare i nomi delle tabelle permanenti o temporanee. Quando il consumer imposta il parametro pTableID su NULL e configura ppTableID perché punti a un DBID* valido, il provider OLE DB di SQL Server Native Client restituisce il nome generato della tabella nel membro pwszName dell'unione uName del DBID a cui punta il valore di ppTableID. Per creare una tabella temporanea denominata dal provider OLE DB di SQL Server Native Client, il consumer include la proprietà di tabella OLE DB DBPROP_TBL_TEMPTABLE in un set di proprietà di tabella cui viene fatto riferimento nel parametro rgPropertySets. Le tabelle temporanee denominate dal provider OLE DB di SQL Server Native Client sono locali.
CreateTable restituisce DB_E_BADTABLEID se il membro eKind del parametro pTableID non indica DBKIND_NAME.
Utilizzo di DBCOLUMNDESC
Il consumer può indicare un tipo di dati di colonna tramite il membro pwszTypeName o il membro wType. Se il consumer specifica il tipo di dati in pwszTypeName, il provider OLE DB di SQL Server Native Client ignora il valore di wType.
Se si utilizza il membro pwszTypeName, il consumer specifica il tipo di dati utilizzando i nomi dei tipi di dati di SQL Server. I nomi dei tipi di dati validi sono quelli restituiti nella colonna TYPE_NAME del set di righe dello schema PROVIDER_TYPES.
Il provider OLE DB di SQL Server Native Client riconosce un subset di valori DBTYPE enumerati da OLE DB nel membro wType. Per ulteriori informazioni, vedere Mapping dei tipi di dati in ITableDefinition.
[!NOTA]
CreateTable restituisce DB_E_BADTYPE se il consumer imposta il membro pTypeInfo o pclsid per specificare il tipo di dati della colonna.
Il consumer specifica il nome di colonna nel membro pwszName dell'unione uName del membro dbcid di DBCOLUMNDESC. Il nome di colonna viene specificato come stringa di caratteri Unicode. Il membro eKind di dbcid deve essere DBKIND_NAME. CreateTable restituisce DB_E_BADCOLUMNID se eKind non è valido, se pwszName è NULL o se il valore di pwszName non è un identificatore di SQL Server valido.
Tutte le proprietà delle colonne sono disponibili in tutte le colonne definite per la tabella. CreateTable può restituire DB_S_ERRORSOCCURRED o DB_E_ERRORSOCCURRED in caso di conflitto tra i valori di proprietà impostati. CreateTable restituisce un errore quando impostazioni delle proprietà delle colonne non valide provocano un errore di creazione di tabelle di SQL Server.
Le proprietà delle colonne in un parametro DBCOLUMNDESC vengono interpretate nel modo seguente.
ID proprietà |
Descrizione |
|---|---|
DBPROP_COL_AUTOINCREMENT |
L/S: Lettura/Scrittura Impostazione predefinita: VARIANT_FALSE Descrizione: imposta la proprietà Identity nella colonna creata. Per SQL Server, la proprietà Identity è valida per una singola colonna all'interno di una tabella. L'impostazione della proprietà su VARIANT_TRUE per più di una colonna genera un errore quando il provider OLE DB di SQL Server Native Client tenta di creare la tabella nel server. La proprietà Identity di SQL Server è valida solo per i tipi integer, numeric e decimal quando la scala è 0. L'impostazione della proprietà su VARIANT_TRUE in una colonna di qualsiasi altro tipo di dati genera un errore quando il provider OLE DB di SQL Server Native Client tenta di creare la tabella nel server. Il provider OLE DB di SQL Server Native Client restituisce DB_S_ERRORSOCCURRED quando le proprietà DBPROP_COL_AUTOINCREMENT e DBPROP_COL_NULLABLE sono entrambe VARIANT_TRUE e il membro dwOption di DBPROP_COL_NULLABLE non è DBPROPOPTIONS_REQUIRED. DB_E_ERRORSOCCURRED viene restituito quando DBPROP_COL_AUTOINCREMENT e DBPROP_COL_NULLABLE sono entrambe VARIANT_TRUE e il membro dwOption di DBPROP_COL_NULLABLE è uguale a DBPROPOPTIONS_REQUIRED. La colonna viene definita con la proprietà Identity di SQL Server e il membro dwStatus di DBPROP_COL_NULLABLE è impostato su DBPROPSTATUS_CONFLICTING. |
DBPROP_COL_DEFAULT |
L/S: Lettura/Scrittura Impostazione predefinita: nessuna Descrizione: crea un vincolo DEFAULT di SQL Server per la colonna. Il membro vValue di DBPROP può essere uno qualsiasi di diversi tipi. Il membro vValue.vt deve specificare un tipo compatibile con il tipo di dati della colonna. La definizione di BSTR N/A come valore predefinito per una colonna definita come DBTYPE_WSTR rappresenta una corrispondenza compatibile. La definizione dello stesso valore predefinito in una colonna definita come DBTYPE_R8 genera un errore quando il provider OLE DB di SQL Server Native Client tenta di creare la tabella nel server. |
DBPROP_COL_DESCRIPTION |
L/S: Lettura/Scrittura Impostazione predefinita: nessuna Descrizione: la proprietà della colonna DBPROP_COL_DESCRIPTION non viene implementata dal provider OLE DB di SQL Server Native Client. Il membro dwStatus della struttura DBPROP restituisce DBPROPSTATUS_NOTSUPPORTED quando il consumer tenta di scrivere il valore della proprietà. L'impostazione della proprietà non costituisce un errore irreversibile per il provider OLE DB di SQL Server Native Client. Se tutti gli altri valori di parametro sono validi, viene creata la tabella di SQL Server. |
DBPROP_COL_FIXEDLENGTH |
L/S: Lettura/Scrittura Impostazione predefinita: VARIANT_FALSE Descrizione: il provider OLE DB di SQL Server Native Client utilizza DBPROP_COL_FIXEDLENGTH per determinare il mapping dei tipi di dati quando il consumer definisce un tipo di dati della colonna utilizzando il membro wType di DBCOLUMNDESC. Per ulteriori informazioni, vedere Mapping dei tipi di dati in ITableDefinition. |
DBPROP_COL_NULLABLE |
L/S: Lettura/Scrittura Impostazione predefinita: nessuna Descrizione: durante la creazione della tabella, il provider OLE DB di SQL Server Native Client indica se la colonna deve accettare valori Null se la proprietà è impostata. Quando la proprietà non è impostata, la possibilità di accettare valori NULL per la colonna è determinata dall'opzione di database predefinita ANSI_NULLS di SQL Server. Il provider OLE DB di SQL Server Native Client è un provider conforme allo standard ISO. Le sessioni connesse adottano comportamenti ISO. Se il consumer non imposta DBPROP_COL_NULLABLE, le colonne accettano valori Null. |
DBPROP_COL_PRIMARYKEY |
L/S: Lettura/Scrittura Impostazione predefinita: VARIANT_FALSE Descrizione: se il valore è VARIANT_TRUE, il provider OLE DB di SQL Server Native Client crea la colonna con un vincolo PRIMARY KEY. Se definita come proprietà della colonna, solo una singola colonna può determinare il vincolo. L'impostazione della proprietà su VARIANT_TRUE per più di una colonna restituisce un errore quando il provider OLE DB di SQL Server Native Client tenta di creare la tabella di SQL Server. Nota: il consumer può utilizzare IIndexDefinition::CreateIndex per creare un vincolo PRIMARY KEY in due o più colonne. Il provider OLE DB di SQL Server Native Client restituisce DB_S_ERRORSOCCURRED quando le proprietà DBPROP_COL_PRIMARYKEY e DBPROP_COL_UNIQUE sono entrambe VARIANT_TRUE e il membro dwOption di DBPROP_COL_UNIQUE non è DBPROPOPTIONS_REQUIRED. DB_E_ERRORSOCCURRED viene restituito quando DBPROP_COL_PRIMARYKEY e DBPROP_COL_UNIQUE sono entrambe VARIANT_TRUE e il membro dwOption di DBPROP_COL_UNIQUE è uguale a DBPROPOPTIONS_REQUIRED. La colonna viene definita con la proprietà Identity di SQL Server e il membro dwStatus di DBPROP_COL_PRIMARYKEY è impostato su DBPROPSTATUS_CONFLICTING. Il provider OLE DB di SQL Server Native Client restituisce un errore quando DBPROP_COL_PRIMARYKEY e DBPROP_COL_NULLABLE sono entrambe VARIANT_TRUE. Il provider OLE DB di SQL Server Native Client restituisce un errore da SQL Server quando il consumer tenta di creare un vincolo PRIMARY KEY in una colonna con tipo di dati di SQL Server non valido. Non è possibile definire vincoli PRIMARY KEY in colonne create con i tipi di dati bit, text, ntext e image di SQL Server. |
DBPROP_COL_UNIQUE |
L/S: Lettura/Scrittura Impostazione predefinita: VARIANT_FALSE Descrizione: applica un vincolo UNIQUE di SQL Server alla colonna. Se è definita come proprietà della colonna, il vincolo viene applicato solo a una singola colonna. Il consumer può utilizzare IIndexDefinition::CreateIndex per applicare un vincolo UNIQUE nei valori combinati di due o più colonne. Il provider OLE DB di SQL Server Native Client restituisce DB_S_ERRORSOCCURRED quando le proprietà DBPROP_COL_PRIMARYKEY e DBPROP_COL_UNIQUE sono entrambe VARIANT_TRUE e dwOption non è DBPROPOPTIONS_REQUIRED. DB_E_ERRORSOCCURRED viene restituito quando DBPROP_COL_PRIMARYKEY e DBPROP_COL_UNIQUE sono entrambe VARIANT_TRUE e dwOption è uguale a DBPROPOPTIONS_REQUIRED. La colonna viene definita con la proprietà Identity di SQL Server e il membro dwStatus di DBPROP_COL_NULLABLE è impostato su DBPROPSTATUS_CONFLICTING. Il provider OLE DB di SQL Server Native Client restituisce DB_S_ERRORSOCCURRED quando le proprietà DBPROP_COL_NULLABLE e DBPROP_COL_UNIQUE sono entrambe VARIANT_TRUE e dwOption non è DBPROPOPTIONS_REQUIRED. DB_E_ERRORSOCCURRED viene restituito quando DBPROP_COL_NULLABLE e DBPROP_COL_UNIQUE sono entrambe VARIANT_TRUE e dwOption è uguale a DBPROPOPTIONS_REQUIRED. La colonna viene definita con la proprietà Identity di SQL Server e il membro dwStatus di DBPROP_COL_NULLABLE è impostato su DBPROPSTATUS_CONFLICTING. Il provider OLE DB di SQL Server Native Client restituisce un errore da SQL Server quando il consumer tenta di creare un vincolo UNIQUE in una colonna con tipo di dati di SQL Server non valido. Non è possibile definire vincoli UNIQUE in colonne create con il tipo di dati bit di SQL Server. |
Quando il consumer chiama ITableDefinition::CreateTable, il provider OLE DB di SQL Server Native Client interpreta le proprietà della tabella nel modo seguente.
ID proprietà |
Descrizione |
|---|---|
DBPROP_TBL_TEMPTABLE |
L/S: Lettura/Scrittura Impostazione predefinita: VARIANT_FALSE Descrizione: per impostazione predefinita, il provider OLE DB di SQL Server Native Client crea tabelle denominate dal consumer. Se impostata su VARIANT_TRUE, il provider OLE DB di SQL Server Native Client genera un nome di tabella temporanea per il consumer. Il consumer imposta il parametro pTableID di CreateTable su NULL. Il parametro ppTableID deve contenere un puntatore valido. |
Se il consumer richiede l'apertura di un set di righe in una tabella creata correttamente, il provider OLE DB di SQL Server Native Client apre un set di righe supportato dal cursore. Qualsiasi proprietà del set di righe può essere indicata nei set di proprietà passati.
In questo esempio viene creata una tabella di 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);
}