建立 SQL Server Native Client 數據表

發行項
07/04/2024

適用於：SQL Server Azure SQL 資料庫 Azure SQL 受控執行個體 Azure Synapse Analytics Platform System （PDW）

SQL Server Native Client OLE DB 提供者會 公開 ITableDefinition：：CreateTable 函式，讓取用者能夠建立 SQL Server 數據表。取用者會使用 CreateTable 來建立取用者命名的永久數據表，以及具有 SQL Server Native Client OLE DB 提供者所產生之唯一名稱的永久或臨時表。

當取用者呼叫 ITableDefinition：：CreateTable 時，如果DBPROP_TBL_TEMPTABLE屬性的值是VARIANT_TRUE，SQL Server Native Client OLE DB 提供者就會為取用者產生臨時表名稱。取用者會將 CreateTable 方法的 pTableID 參數設定為 NULL。 SQL Server Native Client OLE DB 提供者所產生的名稱臨時表不會出現在 TABLES 數據列集中，但可透過 IOpenRowset 介面存取。

當取用者在 pTableID 參數中 uName 等位的 pwszName 成員中指定數據表名稱時，SQL Server Native Client OLE DB 提供者會建立具有該名稱的 SQL Server 數據表。 SQL Server 資料表的命名條件約束便會套用，而且資料表名稱可以表示永久資料表，或者本機或全域暫存資料表。如需詳細資訊，請參閱 CREATE TABLE。 ppTableID 參數可以是 NULL。

SQL Server Native Client OLE DB 提供者可以產生永久或臨時表的名稱。當取用者將 pTableID 參數設定為 NULL，並將 ppTableID 設定為指向有效的 DBID*時，SQL Server Native Client OLE DB 提供者會傳回 pwszName 成員中由 ppTableID 值所指向之 UName 聯集的 pwszName 成員中產生的數據表名稱。若要建立暫時的 SQL Server Native Client OLE DB 提供者命名數據表，取用者會在 rgPropertySets 參數所參考的數據表屬性集中包含 OLE DB 數據表屬性DBPROP_TBL_TEMPTABLE。 SQL Server Native Client OLE DB 提供者命名的臨時表是本機的。

如果 pTableID 參數的 eKind 成員不包含 DBKIND_NAME，CreateTable 會傳回 DB_E_BADTABLEID。

DBCOLUMNDESC 用法

取用者可以使用 pwszTypeName 成員或 wType 成員來指出資料行資料類型。如果取用者在 pwszTypeName 中指定數據類型，SQL Server Native Client OLE DB 提供者會忽略 wType 的值。

如果使用 pwszTypeName 成員，取用者會使用 SQL Server 資料類型名稱指定資料類型。有效的資料類型名稱是在 PROVIDER_TYPES 結構描述資料列集之 TYPE_NAME 資料行中傳回的資料類型名稱。

SQL Server Native Client OLE DB 提供者可辨識 wType 成員中 OLE DB 列舉 DBTYPE 值的子集。如需詳細資訊，請參閱 ITableDefinition 中的資料類型對應。

注意

如果取用者將 pTypeInfo 或 pclsid 成員設定為指定資料行資料類型，CreateTable 會傳回 DB_E_BADTYPE。

取用者會在 DBCOLUMNDESC dbcid 成員之 uName 聯集的 pwszName 成員中，指定資料行名稱。資料行名稱會指定為 Unicode 字元字串。 dbcid 的 eKind 成員必須是 DBKIND_NAME。如果 eKind 無效、pwszName 為 NULL，或者 pwszName 的值不是有效的 SQL Server 識別碼，CreateTable 會傳回 DB_E_BADCOLUMNID。

在針對資料表定義的所有資料行上都可以使用所有資料行屬性。如果屬性值的設定發生衝突，CreateTable 可能會傳回 DB_S_ERRORSOCCURRED 或 DB_E_ERRORSOCCURRED。當無效的資料行屬性設定造成 SQL Server 資料表建立失敗時，CreateTable 會傳回錯誤。

DBCOLUMNDESC 中的資料行屬性解譯如下。

屬性識別碼	描述
DBPROP_COL_AUTOINCREMENT	R/W︰讀取/寫入預設值：VARIANT_FALSE 描述：在建立的資料行上設定 identity 屬性。對於 SQL Server，識別屬性適用於資料表內的單一資料行。當 SQL Server Native Client OLE DB 提供者嘗試在伺服器上建立數據表時，將屬性設定為 VARIANT_TRUE會產生錯誤。當小數位數為 0 時，SQL Server 識別屬性僅適用於 integer、numeric 和 decimal 類型。當 SQL Server Native Client OLE DB 提供者嘗試在伺服器上建立數據表時，將屬性設定為VARIANT_TRUE任何其他數據類型的數據行會產生錯誤。當DBPROP_COL_AUTOINCREMENT和DBPROP_COL_NULLABLE同時VARIANT_TRUE 且未 DBPROPOPTIONS_REQUIRED DBPROP_COL_NULLABLE的 dwOption 時，SQL Server Native Client OLE DB 提供者會傳回DB_S_ERRORSOCCURRED。當 DBPROP_COL_AUTOINCREMENT 和 DBPROP_COL_NULLABLE 同時為 VARIANT_TRUE，而且 DBPROP_COL_NULLABLE 的 dwOption 等於 DBPROPOPTIONS_REQUIRED 時，會傳回 DB_E_ERRORSOCCURRED。資料行會以 SQL Server 識別屬性定義，而 DBPROP_COL_NULLABLE dwStatus 成員會設定為 DBPROPSTATUS_CONFLICTING。
DBPROP_COL_DEFAULT	R/W︰讀取/寫入預設值：None 描述：建立資料行的 SQL Server DEFAULT 條件約束。 vValue DBPROP 成員可以是任何一種類型。 vValue.vt 成員應該指定一個與資料行資料類型相容的類型。例如，對於定義為 DBTYPE_WSTR 的資料行而言，將 BSTR N/A 定義為預設值是相容符合。當 SQL Server Native Client OLE DB 提供者嘗試在伺服器上建立數據表時，在定義為DBTYPE_R8的數據行上定義相同的預設值會產生錯誤。
DBPROP_COL_DESCRIPTION	R/W︰讀取/寫入預設值：None 描述：SQL Server Native Client OLE DB 提供者不會實作DBPROP_COL_DESCRIPTION數據行屬性。當取用者嘗試寫入屬性值時，DBPROP 結構的 dwStatus 成員會傳回 DBPROPSTATUS_NOTSUPPORTED。設定屬性並不構成 SQL Server Native Client OLE DB 提供者的嚴重錯誤。如果其他所有參數值都有效，則會建立 SQL Server 資料表。
DBPROP_COL_FIXEDLENGTH	R/W︰讀取/寫入預設值：VARIANT_FALSE 描述：當取用者使用 DBCOLUMNDESC 的 wType 成員定義數據行數據類型時，SQL Server Native Client OLE DB 提供者會使用 DBPROP_COL_FIXEDLENGTH 來判斷數據類型對應。如需詳細資訊，請參閱 ITableDefinition 中的資料類型對應。
DBPROP_COL_NULLABLE	R/W︰讀取/寫入預設值：None 描述：建立數據表時，SQL Server Native Client OLE DB 提供者會指出如果設定屬性，數據行是否應該接受 Null 值。未設定屬性時，資料行是否能夠接受 NULL 做為值取決於 SQL Server ANSI_NULLS 預設資料庫選項。 SQL Server Native Client OLE DB 提供者是符合 ISO 規範的提供者。已連接的工作階段會表現 ISO 行為。如果取用者沒有設定 DBPROP_COL_NULLABLE，資料行接受 Null 值。
DBPROP_COL_PRIMARYKEY	R/W︰讀取/寫入默認值：VARIANT_FALSE描述：VARIANT_TRUE時，SQL Server Native Client OLE DB 提供者會建立具有 PRIMARY KEY 條件約束的數據行。定義為資料行屬性時，只有單一資料行可以決定條件約束。當 SQL Server Native Client OLE DB 提供者嘗試建立 SQL Server 數據表時，設定屬性VARIANT_TRUE會傳回錯誤。注意:取用者可以使用 IIndexDefinition::CreateIndex 在兩個以上的資料行上建立 PRIMARY KEY 條件約束。當DBPROP_COL_PRIMARYKEY和DBPROP_COL_UNIQUE同時VARIANT_TRUE 且DBPROP_COL_UNIQUE的 dwOption 未DBPROPOPTIONS_REQUIRED時，SQL Server Native Client OLE DB 提供者會傳回DB_S_ERRORSOCCURRED。當 DBPROP_COL_PRIMARYKEY 和 DBPROP_COL_UNIQUE 同時為 VARIANT_TRUE，而且 DBPROP_COL_UNIQUE 的 dwOption 等於 DBPROPOPTIONS_REQUIRED 時，會傳回 DB_E_ERRORSOCCURRED。資料行會以 SQL Server 識別屬性定義，而 DBPROP_COL_PRIMARYKEY dwStatus 成員會設定為 DBPROPSTATUS_CONFLICTING。當DBPROP_COL_PRIMARYKEY和DBPROP_COL_NULLABLE都VARIANT_TRUE時，SQL Server Native Client OLE DB 提供者會傳回錯誤。當取用者嘗試在無效 SQL Server 數據類型的數據行上建立 PRIMARY KEY 條件約束時，SQL Server Native Client OLE DB 提供者會從 SQL Server 傳回錯誤。在使用 SQL Server 資料類型 bit、text、ntext 和 image 建立的資料行上，無法定義 PRIMARY KEY 條件約束。
DBPROP_COL_UNIQUE	R/W︰讀取/寫入預設值：VARIANT_FALSE 描述：將 SQL Server UNIQUE 條件約束套用到資料行。定義為資料行屬性時，僅會在單一資料行上套用條件約束。取用者可以使用 IIndexDefinition::CreateIndex，在結合兩個或多個資料行的值上套用 UNIQUE 條件約束。當DBPROP_COL_PRIMARYKEY和DBPROP_COL_UNIQUE同時VARIANT_TRUE 且 dwOption 未DBPROPOPTIONS_REQUIRED時，SQL Server Native Client OLE DB 提供者會傳回DB_S_ERRORSOCCURRED。當 DBPROP_COL_PRIMARYKEY 和 DBPROP_COL_UNIQUE 同時為 VARIANT_TRUE，而且 dwOption 等於 DBPROPOPTIONS_REQUIRED 時，會傳回 DB_E_ERRORSOCCURRED。資料行會以 SQL Server 識別屬性定義，而 DBPROP_COL_PRIMARYKEY dwStatus 成員會設定為 DBPROPSTATUS_CONFLICTING。當 DBPROP_COL_NULLABLE 和 DBPROP_COL_UNIQUE 都VARIANT_TRUE 且 dwOption 未DBPROPOPTIONS_REQUIRED時，SQL Server Native Client OLE DB 提供者會傳回DB_S_ERRORSOCCURRED。當 DBPROP_COL_NULLABLE 和 DBPROP_COL_UNIQUE 同時為 VARIANT_TRUE，而且 dwOption 等於 DBPROPOPTIONS_REQUIRED 時，會傳回 DB_E_ERRORSOCCURRED。資料行會以 SQL Server 識別屬性定義，而 DBPROP_COL_NULLABLE dwStatus 成員會設定為 DBPROPSTATUS_CONFLICTING。當取用者嘗試在無效 SQL Server 數據類型的數據行上建立 UNIQUE 條件約束時，SQL Server Native Client OLE DB 提供者會從 SQL Server 傳回錯誤。在使用 SQL Server bit 資料類型建立的資料行上，無法定義 UNIQUE 條件約束。

當取用者呼叫 ITableDefinition：：CreateTable 時，SQL Server Native Client OLE DB 提供者會解譯數據表屬性，如下所示。

屬性識別碼	描述
DBPROP_TBL_TEMPTABLE	R/W︰讀取/寫入默認值：VARIANT_FALSE描述：根據預設，SQL Server Native Client OLE DB 提供者會建立取用者所命名的數據表。 VARIANT_TRUE時，SQL Server Native Client OLE DB 提供者會產生取用者的臨時表名稱。取用者會將 CreateTable 的 pTableID 參數設定為 NULL。 ppTableID 參數必須包含有效的指標。

如果取用者要求在成功建立的數據表上開啟數據列集，SQL Server Native Client OLE DB 提供者會開啟數據指標支持的數據列集。在傳遞的屬性集中可以指出任何資料列集屬性。

此範例會建立 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);  
    }

另請參閱

資料表和索引

共用方式為

建立 SQL Server Native Client 數據表

DBCOLUMNDESC 用法

另請參閱

意見反應

意見反應

其他資源