OLE DB 消費者樣板的巨集和全域函式

發行項
11/21/2024

OLE DB 消費者範本包含下列巨集和全域函式：

全域函式

名稱	描述
AtlTraceErrorRecords	如果傳回錯誤，則會將 OLE DB 錯誤記錄資訊傾印到傾印裝置。

存取子對應巨集

名稱	描述
BEGIN_ACCESSOR	標記存取子項目的開頭。
BEGIN_ACCESSOR_MAP	標記存取子對應項目的開頭。
END_ACCESSOR	標記存取子項目的結尾。
END_ACCESSOR_MAP	標記存取子對應項目的結尾。

數據行對應巨集

名稱	描述
BEGIN_COLUMN_MAP	標記用戶記錄類別中數據行對應專案的開頭。
BLOB_ENTRY	用來系結二進位大型物件（BLOB）。
BLOB_ENTRY_LENGTH	報告 BLOB 資料行的長度。
BLOB_ENTRY_LENGTH_STATUS	報告 BLOB 資料行的長度和狀態。
BLOB_ENTRY_STATUS	報告 BLOB 資料行的狀態。
BLOB_NAME	用來依數據行名稱系結二進位大型物件。
BLOB_NAME_LENGTH	報告 BLOB 資料行的長度。
BLOB_NAME_LENGTH_STATUS	報告 BLOB 資料行的長度和狀態。
BLOB_NAME_STATUS	報告 BLOB 資料行的狀態。
BOOKMARK_ENTRY	表示數據列集上的書籤專案。書籤專案是一種特殊的數據行專案。
COLUMN_ENTRY	表示資料庫中特定數據行的系結。
COLUMN_ENTRY_EX	表示資料庫中特定數據行的系結。支援類型、長度、有效位數、小數位數和狀態參數。
COLUMN_ENTRY_LENGTH	表示資料庫中特定數據行的系結。支援長度變數。
COLUMN_ENTRY_LENGTH_STATUS	表示資料庫中特定數據行的系結。支援狀態和長度參數。
COLUMN_ENTRY_PS	表示資料庫中特定數據行的系結。支援有效位數和小數位數參數。
COLUMN_ENTRY_PS_LENGTH	表示資料庫中特定數據行的系結。支援長度變數、有效位數和小數字數參數。
COLUMN_ENTRY_PS_LENGTH_STATUS	表示資料庫中特定數據行的系結。支援狀態和長度變數、有效位數和小數字數參數。
COLUMN_ENTRY_PS_STATUS	表示資料庫中特定數據行的系結。支持狀態變數、有效位數和小數字數參數。
COLUMN_ENTRY_STATUS	表示資料庫中特定數據行的系結。支援狀態變數。
COLUMN_ENTRY_TYPE	表示資料庫中特定數據行的系結。支援類型參數。
COLUMN_ENTRY_TYPE_SIZE	表示資料庫中特定數據行的系結。支援類型和大小參數。
COLUMN_NAME	表示依名稱對資料庫中特定數據行的系結。
COLUMN_NAME_EX	表示依名稱對資料庫中特定數據行的系結。支援數據類型、大小、有效位數、小數位數、數據行長度和數據行狀態的規格。
COLUMN_NAME_LENGTH	表示依名稱對資料庫中特定數據行的系結。支援數據行長度的規格。
COLUMN_NAME_LENGTH_STATUS	表示依名稱對資料庫中特定數據行的系結。支援數據行長度和狀態的規格。
COLUMN_NAME_PS	表示依名稱對資料庫中特定數據行的系結。支援精確度和小數位數的規格。
COLUMN_NAME_PS_LENGTH	表示依名稱對資料庫中特定數據行的系結。支援精確度、小數位數和數據行長度的規格。
COLUMN_NAME_PS_LENGTH_STATUS	表示依名稱對資料庫中特定數據行的系結。支援精確度、小數位數、數據行長度和數據行狀態的規格。
COLUMN_NAME_PS_STATUS	表示依名稱對資料庫中特定數據行的系結。支援精確度、小數位數和數據行狀態的規格。
COLUMN_NAME_STATUS	表示依名稱對資料庫中特定數據行的系結。支援資料行狀態的規格。
COLUMN_NAME_TYPE	表示依名稱對資料庫中特定數據行的系結。支援數據類型的規格。
COLUMN_NAME_TYPE_PS	表示依名稱對資料庫中特定數據行的系結。支援數據類型、有效位數和小數位數的規格。
COLUMN_NAME_TYPE_SIZE	表示依名稱對資料庫中特定數據行的系結。支援數據類型和大小的規格。
COLUMN_NAME_TYPE_STATUS	表示依名稱對資料庫中特定數據行的系結。支援數據類型和數據行狀態的規格。
END_COLUMN_MAP	標記數據行對應項目的結尾。

命令巨集

名稱	描述
DEFINE_COMMAND	指定使用 CCommand 類別時用來建立資料列集的命令。只接受符合指定應用程式類型的字串類型（ANSI 或 Unicode）。建議您使用 DEFINE_COMMAND_EX ，而不是使用 DEFINE_COMMAND。
DEFINE_COMMAND_EX	指定使用 CCommand 類別時用來建立資料列集的命令。支援 ANSI 和 Unicode 應用程式。

參數對應巨集

名稱	描述
BEGIN_PARAM_MAP	標記用戶記錄類別中參數對應項目的開頭。
END_PARAM_MAP	標記參數對應項目的結尾。
SET_PARAM_TYPE	指定COLUMN_ENTRY巨集，以SET_PARAM_TYPE巨集做為輸入、輸出或輸入/輸出。

AtlTraceErrorRecords

如果傳回錯誤，則會將 OLE DB 錯誤記錄資訊傾印到傾印裝置。

語法

inline void AtlTraceErrorRecords(HRESULT hrErr = S_OK);

參數

先生
[in]OLE DB 消費者範本成員函式所傳回的 HRESULT。

備註

如果 hErr 未S_OK，AtlTraceErrorRecords請將 OLE DB 錯誤記錄資訊傾印到傾印裝置（輸出視窗或檔案的 [偵錯] 索引標籤）。從提供者取得的錯誤記錄資訊包含每個錯誤記錄項目的數據列編號、來源、描述、說明檔、內容和 GUID。 AtlTraceErrorRecords 只會在偵錯組建中傾印此資訊。在發行組建中，它是已優化的空白存根。如需詳細資訊，請參閱 CDBErrorInfo類別。

BEGIN_ACCESSOR

標記存取子項目的開頭。

語法

BEGIN_ACCESSOR(num, bAuto)

參數

num
[in]這個存取子對應中存取子的零位移數位。

bAuto
[in]指定這個存取子是否為自動存取子或手動存取子。如果 true為，則存取子為 auto;如果 false為，則存取子為手動存取子。自動存取子表示在移動作業時會為您擷取數據。

備註

在數據列集上有多個存取子的情況下，您必須指定BEGIN_ACCESSOR_MAP並使用每個個別存取子的 BEGIN_ACCESSOR 巨集。 BEGIN_ACCESSOR巨集已完成END_ACCESSOR巨集。 BEGIN_ACCESSOR_MAP巨集已完成END_ACCESSOR_MAP巨集。

範例

請參閱 BEGIN_ACCESSOR_MAP。

BEGIN_ACCESSOR_MAP

標記存取子對應項目的開頭。

語法

BEGIN_ACCESSOR_MAP(x, num)

參數

x
[in] 使用者資料錄類別的名稱。

num
[in] 此存取子對應中的存取子數目。

備註

在數據列集上有多個存取子的情況下，您必須在開頭指定BEGIN_ACCESSOR_MAP，並針對每個個別存取子使用 BEGIN_ACCESSOR 巨集。 BEGIN_ACCESSOR巨集已完成END_ACCESSOR巨集。存取子對應已完成END_ACCESSOR_MAP巨集。

如果使用者資料錄中只有一個存取子，請使用巨集 BEGIN_COLUMN_MAP。

範例

class CArtistsAccessor
{
public:
// Data Elements
   TCHAR m_szFirstName[21];
   TCHAR m_szLastName[31];
   short m_nAge;

// Output binding map
BEGIN_ACCESSOR_MAP(CArtistsAccessor, 2)
   BEGIN_ACCESSOR(0, true)
      COLUMN_ENTRY(1, m_szFirstName)
      COLUMN_ENTRY(2, m_szLastName)
   END_ACCESSOR()
   BEGIN_ACCESSOR(1, false) // Not an auto accessor
      COLUMN_ENTRY(3, m_nAge)
   END_ACCESSOR()
END_ACCESSOR_MAP()

   HRESULT OpenDataSource()
   {
      CDataSource _db;
      _db.Open();
      return m_session.Open(_db);
   }

   void CloseDataSource()
   {
      m_session.Close();
   }

   CSession m_session;

   DEFINE_COMMAND_EX(CArtistsAccessor, L" \
   SELECT \
      FirstName, \
      LastName, \
      Age \
      FROM Artists")
};

END_ACCESSOR

標記存取子項目的結尾。

語法

END_ACCESSOR()

備註

針對數據列集上的多個存取子，您必須指定BEGIN_ACCESSOR_MAP，並使用每個個別存取子的 BEGIN_ACCESSOR 巨集。 BEGIN_ACCESSOR巨集已完成END_ACCESSOR巨集。 BEGIN_ACCESSOR_MAP巨集已完成END_ACCESSOR_MAP巨集。

範例

請參閱 BEGIN_ACCESSOR_MAP。

END_ACCESSOR_MAP

標記存取子對應項目的結尾。

語法

END_ACCESSOR_MAP()

備註

範例

請參閱 BEGIN_ACCESSOR_MAP。

BEGIN_COLUMN_MAP

標記資料行對應項目的開頭。

語法

BEGIN_COLUMN_MAP(x)

參數

x
[in] 衍生自 CAccessor之使用者資料錄類別的名稱。

備註

如果資料列集上只有單一存取子，就會使用此巨集。如果資料列集上有多個存取子，請使用 BEGIN_ACCESSOR_MAP。

BEGIN_COLUMN_MAP巨集已完成END_COLUMN_MAP巨集。當使用者資料錄中只需要一個存取子時，就會使用此巨集。

資料行會對應至您想要繫結之資料列集中的欄位。

範例

以下是範例資料行和參數對應︰

BLOB_ENTRY

與BEGIN_COLUMN_MAP和END_COLUMN_MAP搭配使用，以系結二進位大型物件（BLOB）。

語法

BLOB_ENTRY(nOrdinal, IID, flags, data)

參數

nOrdinal
[in] 資料行編號。

IID
[in]用來擷取 BLOB 的介面 GUID，例如 IDD_ISequentialStream。

flags
[in]儲存模式旗標，如 OLE 結構化儲存模型所定義（例如， STGM_READ）。

data
[in] 使用者記錄中相對應的資料成員。

範例

請參閱如何擷取 BLOB？。

BLOB_ENTRY_LENGTH

與BEGIN_COLUMN_MAP和END_COLUMN_MAP搭配使用，以系結二進位大型物件（BLOB）。類似於 BLOB_ENTRY，不同之處在於這個巨集也會取得 BLOB 數據行的位元組長度。

語法

BLOB_ENTRY_LENGTH(nOrdinal, IID, flags, data, length)

參數

nOrdinal
[in] 資料行編號。

IID
[in]用來擷取 BLOB 的介面 GUID，例如 IDD_ISequentialStream。

flags
[in]儲存模式旗標，如 OLE 結構化儲存模型所定義（例如， STGM_READ）。

data
[in] 使用者記錄中相對應的資料成員。

length
[out]BLOB 資料行位元組的（實際）長度。

範例

請參閱如何擷取 BLOB？。

BLOB_ENTRY_LENGTH_STATUS

與BEGIN_COLUMN_MAP和END_COLUMN_MAP搭配使用，以系結二進位大型物件（BLOB）。類似於 BLOB_ENTRY，不同之處在於這個巨集也會取得 BLOB 數據行的長度和狀態。

語法

BLOB_ENTRY_LENGTH_STATUS(
    nOrdinal,
    IID,
    flags,
    data,
    length,
    status )

參數

nOrdinal
[in] 資料行編號。

IID
[in]用來擷取 BLOB 的介面 GUID，例如 IDD_ISequentialStream。

flags
[in]儲存模式旗標，如 OLE 結構化儲存模型所定義（例如， STGM_READ）。

data
[in] 使用者記錄中相對應的資料成員。

length
[out]BLOB 資料行位元組的（實際）長度。

status
[out]BLOB 資料行的狀態。

範例

請參閱如何擷取 BLOB？。

BLOB_ENTRY_STATUS

與BEGIN_COLUMN_MAP或BEGIN_ACCESSOR_MAP搭配使用，以系結二進位大型物件（BLOB）。類似於 BLOB_ENTRY，不同之處在於這個巨集也會取得 BLOB 數據行的狀態。

語法

BLOB_ENTRY_STATUS(nOrdinal, IID, flags, data, status)

參數

nOrdinal
[in] 資料行編號。

IID
[in]用來擷取 BLOB 的介面 GUID，例如 IDD_ISequentialStream。

flags
[in]儲存模式旗標，如 OLE 結構化儲存模型所定義（例如， STGM_READ）。

data
[in] 使用者記錄中相對應的資料成員。

status
[out]BLOB 欄位的狀態。

範例

請參閱如何擷取 BLOB？。

BLOB_NAME

與BEGIN_COLUMN_MAP和END_COLUMN_MAP搭配使用，以系結二進位大型物件（BLOB）。類似於 BLOB_ENTRY，不同之處在於這個巨集會採用數據行名稱，而不是數據行編號。

語法

BLOB_NAME(pszName, IID, flags, data )

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

IID
[in]用來擷取 BLOB 的介面 GUID，例如 IDD_ISequentialStream。

flags
[in]儲存模式旗標，如 OLE 結構化儲存模型所定義（例如， STGM_READ）。

data
[in] 使用者記錄中相對應的資料成員。

範例

請參閱如何擷取 BLOB？。

BLOB_NAME_LENGTH

與BEGIN_COLUMN_MAP和END_COLUMN_MAP搭配使用，以系結二進位大型物件（BLOB）。類似於 BLOB_NAME，不同之處在於這個巨集也會取得 BLOB 數據行位元組的長度。

語法

BLOB_NAME_LENGTH(pszName, IID, flags, data, length )

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

IID
[in]用來擷取 BLOB 的介面 GUID，例如 IDD_ISequentialStream。

flags
[in]儲存模式旗標，如 OLE 結構化儲存模型所定義（例如， STGM_READ）。

data
[in] 使用者記錄中相對應的資料成員。

length
[out]BLOB 資料行位元組的（實際）長度。

BLOB_NAME_LENGTH_STATUS

與BEGIN_COLUMN_MAP和END_COLUMN_MAP搭配使用，以系結二進位大型物件（BLOB）。類似於 BLOB_NAME，不同之處在於這個巨集也會取得 BLOB 數據行的長度和狀態。

語法

BLOB_NAME_LENGTH_STATUS(pszName, IID, flags, data, length, status )

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

IID
[in]用來擷取 BLOB 的介面 GUID，例如 IDD_ISequentialStream。

flags
[in]儲存模式旗標，如 OLE 結構化儲存模型所定義（例如， STGM_READ）。

data
[in] 使用者記錄中相對應的資料成員。

length
[out]BLOB 資料行位元組的（實際）長度。

status
[out]BLOB 欄位的狀態。

BLOB_NAME_STATUS

與BEGIN_COLUMN_MAP和END_COLUMN_MAP搭配使用，以系結二進位大型物件（BLOB）。類似於 BLOB_NAME，不同之處在於這個巨集也會取得 BLOB 數據行的狀態。

語法

BLOB_NAME_STATUS(pszName, IID, flags, data, status )

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

IID
[in]用來擷取 BLOB 的介面 GUID，例如 IDD_ISequentialStream。

flags
[in]儲存模式旗標，如 OLE 結構化儲存模型所定義（例如， STGM_READ）。

data
[in] 使用者記錄中相對應的資料成員。

status
[out]BLOB 欄位的狀態。

BOOKMARK_ENTRY

系結書籤數據行。

語法

BOOKMARK_ENTRY(variable)

參數

variable
[in]要系結至書籤數據行的變數。

範例

class CArtistsBookmark
{
public:
// Data Elements
   CBookmark<4> m_bookmark;
   short m_nAge;
   TCHAR m_szFirstName[21];
   TCHAR m_szLastName[31];

// Output binding map
BEGIN_COLUMN_MAP(CArtistsBookmark)
   BOOKMARK_ENTRY(m_bookmark)
   COLUMN_ENTRY(1, m_nAge)
   COLUMN_ENTRY(2, m_szFirstName)
   COLUMN_ENTRY(3, m_szLastName)
END_COLUMN_MAP()

   void GetRowsetProperties(CDBPropSet* pPropSet)
   {
      pPropSet->AddProperty(DBPROP_BOOKMARKS, true);
   }

   HRESULT OpenDataSource()
   {
      CDataSource _db;
      _db.Open();
      return m_session.Open(_db);
   }

   void CloseDataSource()
   {
      m_session.Close();
   }

   CSession m_session;

   DEFINE_COMMAND_EX(CArtistsBookmark, L" \
   SELECT \
      Age, \
      FirstName, \
      LastName \
      FROM Artists")
};

如需詳細資訊，請參閱使用書籤和 CBookmark 類別。

COLUMN_ENTRY

表示數據列集上與數據列集中特定數據行的系結。

語法

COLUMN_ENTRY(nOrdinal, data)

參數

請參閱 OLE DB 程式設計人員參考中的 DBBINDING。

nOrdinal
[in] 資料行編號。

data
[in] 使用者記錄中相對應的資料成員。

備註

COLUMN_ENTRY巨集用於下列位置：

在 BEGIN_COLUMN_MAP 和 END_COLUMN_MAP 巨集之間。
在BEGIN_ACCESSOR與END_ACCESSOR巨集之間。
在 BEGIN_PARAM_MAP 與 END_PARAM_MAP 巨集之間。

範例

請參閱巨集主題中的範例， BEGIN_COLUMN_MAP 和 BEGIN_ACCESSOR_MAP。

COLUMN_ENTRY_EX

表示從資料列集至資料庫的特定資料行的繫結。

語法

COLUMN_ENTRY_EX(nOrdinal, wType, nLength, nPrecision, nScale, data, length, status)

參數

請參閱 OLE DB 程式設計人員參考中的 DBBINDING。

nOrdinal
[in] 資料行編號。

wType
[in]數據類型。

nLength
[in]以位元組為單位的數據大小。

nPrecision
[in]取得資料與 wType 時要使用的最大有效位數為 DBTYPE_NUMERIC。否則會忽略此參數。

nScale
[in]取得資料與 wType 時要使用的小數字數是 DBTYPE_NUMERIC 或 DBTYPE_DECIMAL。

data
[in] 使用者記錄中相對應的資料成員。

length
[in] 要繫結至資料行長度的變數。

status
[in] 要繫結至資料行狀態的變數。

備註

COLUMN_ENTRY_EX巨集用於下列位置：

在 BEGIN_COLUMN_MAP 和 END_COLUMN_MAP 巨集之間。
在BEGIN_ACCESSOR與END_ACCESSOR巨集之間。
在 BEGIN_PARAM_MAP 與 END_PARAM_MAP 巨集之間。

範例

請參閱 BOOKMARK_ENTRY。

COLUMN_ENTRY_LENGTH

表示從資料列集至資料庫的特定資料行的繫結。

語法

COLUMN_ENTRY_LENGTH(nOrdinal, data, length)

參數

請參閱 OLE DB 程式設計人員參考中的 DBBINDING。

nOrdinal
[in]數據行編號，從一個開始。書籤會對應至數據行零。

data
[in] 使用者記錄中相對應的資料成員。

length
[in] 要繫結至資料行長度的變數。

備註

這個巨集支援長度變數。這個參數可以用於下列狀況：

在 BEGIN_COLUMN_MAP 和 END_COLUMN_MAP 巨集之間。
在BEGIN_ACCESSOR與END_ACCESSOR巨集之間。
在 BEGIN_PARAM_MAP 與 END_PARAM_MAP 巨集之間。

COLUMN_ENTRY_LENGTH_STATUS

表示從資料列集至資料庫的特定資料行的繫結。

語法

COLUMN_ENTRY_LENGTH_STATUS(nOrdinal, data, length, status)

參數

請參閱 OLE DB 程式設計人員參考中的 DBBINDING。

nOrdinal
[in] 資料行編號。

data
[in] 使用者記錄中相對應的資料成員。

length
[in] 要繫結至資料行長度的變數。

status
[in] 要繫結至資料行狀態的變數。

備註

當您想要支援長度和狀態變數時，可使用這個巨集。這個參數可以用於下列狀況：

在 BEGIN_COLUMN_MAP 和 END_COLUMN_MAP 巨集之間。
在BEGIN_ACCESSOR與END_ACCESSOR巨集之間。
在 BEGIN_PARAM_MAP 與 END_PARAM_MAP 巨集之間。

COLUMN_ENTRY_PS

表示數據列集上與數據列集中特定數據行的系結。

語法

COLUMN_ENTRY_PS(nOrdinal, nPrecision, nScale, data)

參數

請參閱 OLE DB 程式設計人員參考中的 DBBINDING。

nOrdinal
[in] 資料行編號。

nPrecision
[in] 要繫結之資料行的最大精確度。

nScale
[in] 要繫結之資料行的小數位數。

data
[in] 使用者記錄中相對應的資料成員。

備註

可讓您指定要繫結之資料行的精確度和小數位數。這個參數可以用於下列狀況：

在 BEGIN_COLUMN_MAP 和 END_COLUMN_MAP 巨集之間。
在BEGIN_ACCESSOR與END_ACCESSOR巨集之間。
在 BEGIN_PARAM_MAP 與 END_PARAM_MAP 巨集之間。

COLUMN_ENTRY_PS_LENGTH

表示從資料列集至資料庫的特定資料行的繫結。

語法

COLUMN_ENTRY_PS_LENGTH(nOrdinal, nPrecision, nScale, data, length)

參數

請參閱 OLE DB 程式設計人員參考中的 DBBINDING。

nOrdinal
[in]數據行編號，從一個開始。書籤會對應至數據行零。

nPrecision
[in] 要繫結之資料行的最大精確度。

nScale
[in] 要繫結之資料行的小數位數。

data
[in] 使用者記錄中相對應的資料成員。

length
[in] 要繫結至資料行長度的變數。

備註

可讓您指定要繫結之資料行的精確度和小數位數。這個巨集支援長度變數。這個參數可以用於下列狀況：

在 BEGIN_COLUMN_MAP 和 END_COLUMN_MAP 巨集之間。
在BEGIN_ACCESSOR與END_ACCESSOR巨集之間。
在 BEGIN_PARAM_MAP 與 END_PARAM_MAP 巨集之間。

COLUMN_ENTRY_PS_LENGTH_STATUS

表示從資料列集至資料庫的特定資料行的繫結。

語法

COLUMN_ENTRY_PS_LENGTH_STATUS(nOrdinal, nPrecision, nScale, data, length, status)

參數

請參閱 OLE DB 程式設計人員參考中的 DBBINDING。

nOrdinal
[in] 資料行編號。

nPrecision
[in] 要繫結之資料行的最大精確度。

nScale
[in] 要繫結之資料行的小數位數。

data
[in] 使用者記錄中相對應的資料成員。

length
[in] 要繫結至資料行長度的變數。

status
[in] 要繫結至資料行狀態的變數。

備註

可讓您指定要繫結之資料行的精確度和小數位數。當您想要支援長度和狀態變數時，可使用這個巨集。這個參數可以用於下列狀況：

在 BEGIN_COLUMN_MAP 和 END_COLUMN_MAP 巨集之間。
在BEGIN_ACCESSOR與END_ACCESSOR巨集之間。
在 BEGIN_PARAM_MAP 與 END_PARAM_MAP 巨集之間。

COLUMN_ENTRY_PS_STATUS

表示從資料列集至資料庫的特定資料行的繫結。

語法

COLUMN_ENTRY_PS_STATUS(nOrdinal, nPrecision, nScale, data, status)

參數

請參閱 OLE DB 程式設計人員參考中的 DBBINDING。

nOrdinal
[in] 資料行編號。

nPrecision
[in] 要繫結之資料行的最大精確度。

nScale
[in] 要繫結之資料行的小數位數。

data
[in] 使用者記錄中相對應的資料成員。

status
[in] 要繫結至資料行狀態的變數。

備註

可讓您指定要繫結之資料行的精確度和小數位數。此巨集支持狀態變數。這個參數可以用於下列狀況：

在 BEGIN_COLUMN_MAP 和 END_COLUMN_MAP 巨集之間。
在BEGIN_ACCESSOR與END_ACCESSOR巨集之間。
在 BEGIN_PARAM_MAP 與 END_PARAM_MAP 巨集之間。

COLUMN_ENTRY_STATUS

表示從資料列集至資料庫的特定資料行的繫結。

語法

COLUMN_ENTRY_STATUS(nOrdinal, data, status)

參數

請參閱 OLE DB 程式設計人員參考中的 DBBINDING。

nOrdinal
[in] 資料行編號。

data
[in] 使用者記錄中相對應的資料成員。

status
[in] 要繫結至資料行狀態的變數。

備註

此巨集支持狀態變數。這個參數可以用於下列狀況：

在 BEGIN_COLUMN_MAP 和 END_COLUMN_MAP 巨集之間。
在BEGIN_ACCESSOR與END_ACCESSOR巨集之間。
在 BEGIN_PARAM_MAP 與 END_PARAM_MAP 巨集之間。

COLUMN_ENTRY_TYPE

表示資料庫中特定數據行的系結。支援類型參數。

語法

COLUMN_ENTRY_TYPE (nOrdinal, wType, data)

參數

nOrdinal
[in] 資料行編號。

wType
[in]數據行項目的數據類型。

data
[in] 使用者記錄中相對應的資料成員。

備註

這個巨集是COLUMN_ENTRY巨集的特殊變體，可提供指定數據類型的方法。

COLUMN_ENTRY_TYPE_SIZE

表示資料庫中特定數據行的系結。支援類型和大小參數。

語法

COLUMN_ENTRY_TYPE_SIZE(nOrdinal, wType, nLength, data)

參數

nOrdinal
[in] 資料行編號。

wType
[in]數據行項目的數據類型。

nLength
[in]以位元組為單位的數據行專案大小。

data
[in] 使用者記錄中相對應的資料成員。

備註

這個巨集是COLUMN_ENTRY巨集的特殊變體，可提供指定數據大小和類型的方法。

COLUMN_NAME

表示數據列集上與數據列集中特定數據行的系結。類似於 COLUMN_ENTRY，不同之處在於這個巨集會採用數據行名稱，而不是數據行編號。

語法

COLUMN_NAME(pszName, data)

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

data
[in] 使用者記錄中相對應的資料成員。

備註

COLUMN_NAME_* 巨集會用於與COLUMN_ENTRY相同的位置：

在 BEGIN_COLUMN_MAP 和 END_COLUMN_MAP 巨集之間。
在BEGIN_ACCESSOR與END_ACCESSOR巨集之間。
在 BEGIN_PARAM_MAP 與 END_PARAM_MAP 巨集之間。

COLUMN_NAME_EX

表示數據列集上與數據列集中特定數據行的系結。與 COLUMN_NAME類似，不同之處在於此巨集也會採用數據類型、大小、有效位數、小數位數、數據行長度和數據行狀態。

語法

COLUMN_NAME_EX(pszName, wType, nLength, nPrecision, nScale, data, length, status )

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

wType
[in]數據類型。

nLength
[in]以位元組為單位的數據大小。

nPrecision
[in]取得資料與 wType 時要使用的最大有效位數為 DBTYPE_NUMERIC。否則會忽略此參數。

nScale
[in]取得資料與 wType 時要使用的小數字數是 DBTYPE_NUMERIC 或 DBTYPE_DECIMAL。

data
[in] 使用者記錄中相對應的資料成員。

length
[in] 要繫結至資料行長度的變數。

status
[in] 要繫結至資料行狀態的變數。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

COLUMN_NAME_LENGTH

表示數據列集上與數據列集中特定數據行的系結。類似於 COLUMN_NAME，不同之處在於這個巨集也會採用數據行長度。

語法

COLUMN_NAME_LENGTH(pszName, data, length)

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

data
[in] 使用者記錄中相對應的資料成員。

length
[in] 要繫結至資料行長度的變數。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

COLUMN_NAME_LENGTH_STATUS

表示數據列集上與數據列集中特定數據行的系結。類似於 COLUMN_NAME，不同之處在於這個巨集也會採用數據行長度和數據行狀態。

語法

COLUMN_NAME_LENGTH_STATUS(pszName, data, length, status )

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

data
[in] 使用者記錄中相對應的資料成員。

length
[in] 要繫結至資料行長度的變數。

status
[in] 要繫結至資料行狀態的變數。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

COLUMN_NAME_PS

表示數據列集上與數據列集中特定數據行的系結。類似於 COLUMN_NAME，不同之處在於這個巨集也會採用有效位數和小數字數。

語法

COLUMN_NAME_PS(pszName, nPrecision, nScale, data )

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

nPrecision
[in] 要繫結之資料行的最大精確度。

nScale
[in] 要繫結之資料行的小數位數。

data
[in] 使用者記錄中相對應的資料成員。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

COLUMN_NAME_PS_LENGTH

表示數據列集上與數據列集中特定數據行的系結。類似於 COLUMN_NAME，不同之處在於這個巨集也採用有效位數、小數位數和數據行長度。

語法

COLUMN_NAME_PS_LENGTH(pszName, nPrecision, nScale, data, length )

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

nPrecision
[in] 要繫結之資料行的最大精確度。

nScale
[in] 要繫結之資料行的小數位數。

data
[in] 使用者記錄中相對應的資料成員。

length
[in] 要繫結至資料行長度的變數。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

COLUMN_NAME_PS_LENGTH_STATUS

表示數據列集上與數據列集中特定數據行的系結。與 COLUMN_NAME類似，不同之處在於此巨集也採用有效位數、小數位數、數據行長度和數據行狀態。

語法

COLUMN_NAME_PS_LENGTH_STATUS(pszName, nPrecision, nScale, data, length, status )

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

nPrecision
[in] 要繫結之資料行的最大精確度。

nScale
[in] 要繫結之資料行的小數位數。

data
[in] 使用者記錄中相對應的資料成員。

length
[in] 要繫結至資料行長度的變數。

status
[in] 要繫結至資料行狀態的變數。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

COLUMN_NAME_PS_STATUS

表示數據列集上與數據列集中特定數據行的系結。與 COLUMN_NAME類似，不同之處在於此巨集也採用有效位數、小數位數和數據行狀態。

語法

COLUMN_NAME_PS_STATUS(pszName, nPrecision, nScale, data, status )

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

nPrecision
[in] 要繫結之資料行的最大精確度。

nScale
[in] 要繫結之資料行的小數位數。

data
[in] 使用者記錄中相對應的資料成員。

status
[in] 要繫結至資料行狀態的變數。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

COLUMN_NAME_STATUS

表示數據列集上與數據列集中特定數據行的系結。類似於 COLUMN_NAME，不同之處在於這個巨集也會接受數據行狀態。

語法

COLUMN_NAME_STATUS(pszName, data, status )

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

data
[in] 使用者記錄中相對應的資料成員。

status
[in] 要繫結至資料行狀態的變數。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

COLUMN_NAME_TYPE

表示數據列集上與數據列集中特定數據行的系結。類似於 COLUMN_NAME，不同之處在於這個巨集也會採用數據類型。

語法

COLUMN_NAME_TYPE(pszName, wType, data)

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

wType
[in]數據類型。

data
[in] 使用者記錄中相對應的資料成員。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

COLUMN_NAME_TYPE_PS

表示數據列集上與數據列集中特定數據行的系結。類似於 COLUMN_NAME，不同之處在於這個巨集也會採用數據類型、有效位數和小數字數。

語法

COLUMN_NAME_TYPE_PS(pszName, wType, nPrecision, nScale, data)

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

wType
[in]數據類型。

nPrecision
[in]取得資料與 wType 時要使用的最大有效位數為 DBTYPE_NUMERIC。否則會忽略此參數。

nScale
[in]取得資料與 wType 時要使用的小數字數是 DBTYPE_NUMERIC 或 DBTYPE_DECIMAL。

data
[in] 使用者記錄中相對應的資料成員。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

COLUMN_NAME_TYPE_SIZE

表示數據列集上與數據列集中特定數據行的系結。類似於 COLUMN_NAME，不同之處在於這個巨集也會採用數據類型和大小。

語法

COLUMN_NAME_TYPE_SIZE(pszName, wType, nLength, data)

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

wType
[in]數據類型。

nLength
[in]以位元組為單位的數據大小。

data
[in] 使用者記錄中相對應的資料成員。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

COLUMN_NAME_TYPE_STATUS

表示數據列集上與數據列集中特定數據行的系結。類似於 COLUMN_NAME，不同之處在於這個巨集也會採用數據類型和數據行狀態。

語法

COLUMN_NAME_TYPE_STATUS(pszName, wType, status, data)

參數

pszName
[in]數據行名稱的指標。名稱必須是 Unicode 字串。您可以將『L' 放在名稱前面，例如： L"MyColumn"。

wType
[in]數據類型。

status
[in] 要繫結至資料行狀態的變數。

data
[in] 使用者記錄中相對應的資料成員。

備註

如需使用COLUMN_NAME_* 巨集的資訊，請參閱 COLUMN_NAME 。

END_COLUMN_MAP

標記數據行對應項目的結尾。

語法

END_COLUMN_MAP()

備註

它會與數據列集上的單一存取子搭配使用。 BEGIN_COLUMN_MAP巨集已完成END_COLUMN_MAP巨集。

範例

請參閱 BEGIN_COLUMN_MAP。

DEFINE_COMMAND

指定使用 CCommand 類別時用來建立資料列集的命令。只接受符合指定應用程式類型的字串類型（ANSI 或 Unicode）。

注意

建議您使用 DEFINE_COMMAND_EX ，而不是使用 DEFINE_COMMAND。

語法

DEFINE_COMMAND(x, szCommand)

參數

x
[in]用戶記錄（command）類別的名稱。

szCommand
[in]使用 CCommand 時用來建立資料列集的命令字串。

備註

如果您未在 CCommand：：Open 方法中指定命令文字，則會使用您指定的命令字串做為預設值。

如果您將應用程式建置為 ANSI，則此巨集會接受 ANSI 字串，如果您將應用程式建置為 Unicode，則接受 Unicode 字串。建議您使用 DEFINE_COMMAND_EX 而不是 DEFINE_COMMAND，因為前者接受 Unicode 字串，而不論 ANSI 或 Unicode 應用程式類型為何。

範例

請參閱 BOOKMARK_ENTRY。

DEFINE_COMMAND_EX

指定使用 CCommand 類別時用來建立資料列集的命令。支援 Unicode 和 ANSI 應用程式。

語法

DEFINE_COMMAND_EX(x, wszCommand)

參數

x
[in]用戶記錄（command）類別的名稱。

wszCommand
[in]使用 CCommand 時用來建立資料列集的命令字串。

備註

如果您未在 CCommand：：Open 方法中指定命令文字，則會使用您指定的命令字串做為預設值。

不論應用程式類型為何，這個巨集都會接受 Unicode 字串。此巨集優先於 DEFINE_COMMAND ，因為它支援 Unicode 和 ANSI 應用程式。

範例

請參閱 BOOKMARK_ENTRY。

BEGIN_PARAM_MAP

標記參數對應項目的開頭。

語法

BEGIN_PARAM_MAP(x)

參數

x
[in] 使用者資料錄類別的名稱。

備註

命令會使用參數。

範例

請參閱 BEGIN_COLUMN_MAP 巨集的範例。

END_PARAM_MAP

標記參數對應項目的結尾。

語法

END_PARAM_MAP()

範例

請參閱 BEGIN_PARAM_MAP 巨集的範例。

SET_PARAM_TYPE

指定SET_PARAM_TYPE巨集輸入、輸出或輸入/輸出之後的COLUMN_ENTRY巨集。

語法

SET_PARAM_TYPE(type)

參數

type
[in] 用來設定參數的類型。

備註

提供者只支援基礎資料來源支援的參數輸入/輸出類型。此類型是一或多個DBPARAMIO值的組合（請參閱 OLE DB 程式設計人員參考中的 DBBINDING 結構）：

DBPARAMIO_NOTPARAM 存取子沒有參數。一般而言，您會在數據列存取子中設定 eParamIO 為此值，以提醒使用者忽略參數。
DBPARAMIO_INPUT 輸入參數。
DBPARAMIO_OUTPUT 輸出參數。
DBPARAMIO_INPUT | DBPARAMIO_OUTPUT 參數同時為輸入和輸出參數。

範例

class CArtistsProperty
{
public:
   short m_nReturn;
   short m_nAge;
   TCHAR m_szFirstName[21];
   TCHAR m_szLastName[31];

BEGIN_PARAM_MAP(CArtistsProperty)
   SET_PARAM_TYPE(DBPARAMIO_OUTPUT)
   COLUMN_ENTRY(1, m_nReturn)
   SET_PARAM_TYPE(DBPARAMIO_INPUT)
   COLUMN_ENTRY(2, m_nAge)
END_PARAM_MAP()

BEGIN_COLUMN_MAP(CArtistsProperty)
   COLUMN_ENTRY(1, m_szFirstName)
   COLUMN_ENTRY(2, m_szLastName)
END_COLUMN_MAP()

   HRESULT OpenDataSource()
   {
      CDataSource _db;
      _db.Open();
      return m_session.Open(_db);
   }

   void CloseDataSource()
   {
      m_session.Close();
   }

   CSession m_session;

   DEFINE_COMMAND_EX(CArtistsProperty, L" \
      { ? = SELECT Age FROM Artists WHERE Age < ? }")
};

需求

標頭檔：atldbcli.h

另請參閱

OLE DB 消費者範本的巨集和全域函式
 OLE DB 消費者範本
 OLE DB 消費者範本參考

共用方式為

OLE DB 消費者樣板的巨集和全域函式

全域函式

存取子對應巨集

數據行對應巨集

命令巨集

參數對應巨集

AtlTraceErrorRecords

語法

參數

備註

BEGIN_ACCESSOR

語法

參數

備註

範例

BEGIN_ACCESSOR_MAP

語法

參數

備註

範例

END_ACCESSOR

語法

備註

範例

END_ACCESSOR_MAP

語法

備註

範例

BEGIN_COLUMN_MAP

語法

參數

備註

範例

BLOB_ENTRY

語法

參數

範例

BLOB_ENTRY_LENGTH

語法

參數

範例

BLOB_ENTRY_LENGTH_STATUS

語法

參數

範例

BLOB_ENTRY_STATUS

語法

參數

範例

BLOB_NAME

語法

參數

範例

BLOB_NAME_LENGTH

語法

參數

BLOB_NAME_LENGTH_STATUS

語法

參數

BLOB_NAME_STATUS

語法

參數

BOOKMARK_ENTRY

語法

參數

範例

COLUMN_ENTRY

語法

參數

備註

範例

COLUMN_ENTRY_EX

語法

參數

備註

範例

COLUMN_ENTRY_LENGTH

語法

參數