`db_command`

發行項
07/05/2024

建立 OLE DB 命令。

語法

[ db_command(command, name, source_name, hresult, bindings, bulk_fetch) ]

參數

command
包含 OLE DB 命令文字的命令字串。簡單範例如下︰

[ db_command ( command = "Select * from Products" ) ]

語法 command 如下：

binding 參數區塊 1
OLE DB 命令
binding 參數區塊 2
OLE DB 命令的接續
binding 參數區塊 3
...

「繫結參數區塊」 (binding parameter block) 定義如下︰

(bindtype szVar1 [ szVar2 [, nVar3 [,, ...]]])

其中：

( 標記數據系結區塊的開頭。
bindtype 是下列其中一個不區分大小寫的字串：
- [db_column] 將每個成員變數系結至數據列集中的數據行。
- [bindto] （與 [db_column]相同）。
- [in] 將成員變數系結為輸入參數。
- [out] 將成員變數系結為輸出參數。
- [in,out] 將成員變數系結為輸入/輸出參數。
szVarN，nVarN 解析為目前範圍內的成員變數。
) 標記數據系結區塊的結尾。

如果命令字串包含一或多個規範，例如 [in]、 [out]或 [in/out]， db_command 則會建置參數對應。

如果命令字串包含一或多個參數，例如 [db_column] 或 [bindto]，則 db_command 會產生數據列集和存取子對應至服務這些係結變數。如需詳細資訊，請參閱db_accessor。

注意

bindtype在類別層級使用 db_command 時，語法和 bindings 參數無效。

以下是繫結參數區塊的一些範例。下列範例會將 m_au_fname 和資料成員分別系結至 au_fname 資料庫中作者數據表的 pubs 和 m_au_lname au_lname 資料行：

TCHAR m_au_fname[21];
TCHAR m_au_lname[41];
TCHAR m_state[3] = 'CA';

[db_command (command = "SELECT au_fname([bindto]m_au_fname), au_lname([bindto]m_au_lname) " \
   "FROM dbo.authors " \
   "WHERE state = ?([in]m_state)")
]

name
（選擇性）您用來處理資料列集的句柄名稱。如果您指定 name， db_command 會產生具有指定 name之的類別，可用來周遊數據列集或執行多個動作查詢。如果您未指定 name，則無法將一個以上的結果列傳回給使用者。

source_name
（選擇性） CSession 類別的變數或實例，其屬性 db_source 已套用至命令執行所在的屬性。請參閱 db_source。

db_command 會檢查，以確保所使用的 source_name 變數有效，因此指定的變數應位於函式或全域範圍中。

hresult
（選擇性）識別將接收這個資料庫命令之 HRESULT 的變數。如果變數不存在，屬性會自動插入變數。

bindings
（選擇性）可讓您將係結參數與 OLE DB 命令分開。

如果您為指定值 bindings， db_command 則會剖析相關聯的值，而且不會剖析 bindtype 參數。這種用法可讓您使用 OLE DB 提供者語法。若要停用不含係結參數的剖析，請指定 Bindings=""。

如果您未指定的值 bindings， db_command 則會剖析係結參數區塊。它會尋找『(，後面接著 bindtype 括弧中的，後面接著一或多個先前宣告C++成員變數，後面接著『)。它會從產生的命令移除括號之間的所有文字。這些參數可用來建構此命令的數據行和參數係結。

bulk_fetch
（選擇性）整數值，指定要擷取的數據列數目。

預設值為 1，指定單一數據列擷取（數據列集的類型為 CRowset）。

大於 1 的值指定大量資料列擷取。大量數據列擷取是指大量數據列集擷取多個數據列句柄的能力（數據列集的類型為 CBulkRowset ，且會以指定的數據列數目呼叫 SetRows ）。

如果 bulk_fetch 小於一， SetRows 則會傳回零。

備註

db_commandCCommand會建立物件，此物件由 OLE DB 取用者用來執行命令。

您可以搭配類別或函式範圍使用 db_command ;主要差異在於物件的範圍 CCommand 。使用函式範圍時，繫結這類資料會終止於函式結尾。類別和函式範圍使用方式都牽涉到 OLE DB 消費者範本類別 CCommand<>，但函式和類別案例的樣板自變數不同。在函式案例中，會將系結設為 Accessor 包含局部變數的，而類別使用方式會將衍生類別推斷 CAccessor為自變數。當做類別屬性使用時， db_command 可與搭配運作 db_column。

db_command 可用來執行不會傳回結果集的命令。

當取用者屬性提供者將這個屬性套用至類別時，編譯程式會將類別重新命名為 _[YourClassName]Accessor，其中 [YourClassName] 是您提供類別的名稱。編譯程式也會建立名為 [YourClassName]的類別，其衍生自 _[YourClassName]Accessor。在 [類別檢視] 中，您會看到這兩個類別。

範例

此範例所定義的命令會從狀態資料行符合 'CA' 的表格中選取第一個和最後一個名稱。 db_command 會建立並讀取資料列集，您可以在其中呼叫精靈產生的函式，例如 OpenAll 和 CloseAll，以及 CRowset 成員函式，例如 MoveNext。

此程式代碼會要求您提供連接到資料庫連接字串pubs。如需如何在開發環境中提供連接字串的資訊，請參閱如何：連線到資料庫並瀏覽現有的物件和新增連接。

原始程式檔 db_command.h：

// db_command.h
#include <atlbase.h>
#include <atlplus.h>
#include <atldbcli.h>

#pragma once

[  db_source(L"your connection string"), db_command(L" \
      SELECT au_lname, au_fname \
      FROM dbo.authors \
      WHERE state = 'CA'")  ]

struct CAuthors {
   // In order to fix several issues with some providers, the code below may bind
   // columns in a different order than reported by the provider

   DBSTATUS m_dwau_lnameStatus;
   DBSTATUS m_dwau_fnameStatus;
   DBLENGTH m_dwau_lnameLength;
   DBLENGTH m_dwau_fnameLength;

   [ db_column("au_lname", status="m_dwau_lnameStatus", length="m_dwau_lnameLength") ] TCHAR m_au_lname[41];
   [ db_column("au_fname", status="m_dwau_fnameStatus", length="m_dwau_fnameLength") ] TCHAR m_au_fname[21];

   [ db_param("7", paramtype="DBPARAMIO_INPUT") ] TCHAR m_state[3];

   void GetRowsetProperties(CDBPropSet* pPropSet) {
      pPropSet->AddProperty(DBPROP_CANFETCHBACKWARDS, true, DBPROPOPTIONS_OPTIONAL);
      pPropSet->AddProperty(DBPROP_CANSCROLLBACKWARDS, true, DBPROPOPTIONS_OPTIONAL);
   }
};

原始程式檔 db_command.cpp：

// db_command.cpp
// compile with: /c
#include "db_command.h"

int main(int argc, _TCHAR* argv[]) {
   HRESULT hr = CoInitialize(NULL);

   // Instantiate rowset
   CAuthors rs;

   // Open rowset and move to first row
   strcpy_s(rs.m_state, sizeof(rs.m_state), _T("CA"));
   hr = rs.OpenAll();
   hr = rs.MoveFirst();

   // Iterate through the rowset
   while( SUCCEEDED(hr) && hr != DB_S_ENDOFROWSET ) {
      // Print out the column information for each row
      printf("First Name: %s, Last Name: %s\n", rs.m_au_fname, rs.m_au_lname);
      hr = rs.MoveNext();
   }

   rs.CloseAll();
   CoUninitialize();
}

此範例會在資料來源類別 db_source 上使用 CMySource，並在命令類別 db_command 和 CCommand1 上使用 CCommand2。

// db_command_2.cpp
// compile with: /c
#include <atlbase.h>
#include <atlplus.h>
#include <atldbcli.h>
// class usage for both db_source and db_command

[  db_source(L"your connection string"), db_command(L" \
      SELECT au_lname, au_fname \
      FROM dbo.authors \
      WHERE state = 'CA'")  ]
struct CMySource {
   HRESULT OpenDataSource() {
      return S_OK;
   }
};

[db_command(command = "SELECT * FROM Products")]
class CCommand1 {};

[db_command(command = "SELECT FNAME, LNAME FROM Customers")]
class CCommand2 {};

int main() {
   CMySource s;
   HRESULT hr = s.OpenDataSource();
   if (SUCCEEDED(hr)) {
      CCommand1 c1;
      hr = c1.Open(s);

      CCommand2 c2;
      hr = c2.Open(s);
   }

   s.CloseDataSource();
}

需求

屬性內容	值
適用於	`class`、、 `struct`成員、方法、本機
可重複	No
必要屬性	無
無效屬性	無

如需屬性內容的詳細資訊，請參閱屬性內容。

另請參閱

OLE DB 取用者屬性
 獨立屬性

共用方式為

`db_command`

語法

參數

備註

範例

需求

另請參閱

意見反應

意見反應

其他資源