db_commanddb_command

Tworzy polecenie OLE DB.Creates an OLE DB command.

SkładniaSyntax

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

ParametryParameters

dotyczącecommand
Ciąg polecenia zawierający tekst polecenia OLE DB.A command string containing the text of an OLE DB command. Prosty przykład:A simple example is:

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

Składnia polecenia jest następująca:The command syntax is as follows:

powiązanie bloku parametrów 1 binding parameter block 1
  Polecenie OLE DB   OLE DB command
powiązanie parametru — blok 2 binding parameter block 2
  Kontynuacja polecenia OLE DB   continuation of OLE DB command
powiązanie bloku parametrów 3 binding parameter block 3
......

Blok parametrów powiązania jest definiowany w następujący sposób:A binding parameter block is defined as follows:

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

gdzie:where:

  • ( oznacza początek bloku powiązania danych.( marks the start of the data binding block.

  • *[***BindType ] to jeden z następujących ciągów bez uwzględniania wielkości liter:[ bindtype ] is one of the following case-insensitive strings:

    • [ Db_column] wiąże wszystkie zmienne Członkowskie z kolumną w zestawie wierszy.[db_column] binds each of the member variables to a column in a rowset.

    • [ BindTo] (tak samo jak [ Db_column]).[bindto] (same as [db_column]).

    • [ in] wiąże Zmienne Członkowskie jako parametry wejściowe.[in] binds member variables as input parameters.

    • [ out] tworzy powiązania zmiennych składowych jako parametrów wyjściowych.[out] binds member variables as output parameters.

    • [ w, out] tworzy zmienne składowe jako parametry wejściowe/wyjściowe.[in,out] binds member variables as input/output parameters.

  • szVarX, nVarX jest rozpoznawana jako zmienna członkowska w bieżącym zakresie.szVarX, nVarX resolves to a member variable within the current scope.

  • ) oznacza koniec bloku powiązania danych.) marks the end of the data binding block.

Jeśli ciąg polecenia zawiera jeden lub więcej specyfikatorów, takich jak [ in], [ out] lub [ in/out], db_command kompiluje mapę parametrów.If the command string contains one or more specifiers such as [in], [out], or [in/out], db_command builds a parameter map.

Jeśli ciąg polecenia zawiera jeden lub więcej parametrów, takich jak [ Db_column] lub [ BindTo], db_command generuje zestaw wierszy i mapę dostępu, aby obsłużyć te zmienne powiązane.If the command string contains one or more parameters such as [db_column] or [bindto], db_command generates a rowset and an accessor map to service these bound variables. Aby uzyskać więcej informacji, zobacz db_accessor .See db_accessor for more information.

Uwaga

[BindType] Składnia i parametr bindings są nieprawidłowe, gdy jest używany db_command na poziomie klasy.[bindtype] syntax and the bindings parameter are not valid when using db_command at the class level.

Oto kilka przykładów bloków parametrów powiązań.Here are some examples of binding parameter blocks. Poniższy przykład wiąże m_au_fname i m_au_lname składowe danych z i au_fname odpowiednio do au_lname kolumn w tabeli autorów w bazie danych pubs:The following example binds the m_au_fname and m_au_lname data members to the au_fname and au_lname columns, respectively, of the authors table in the pubs database:

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)")
]

Nazwijname
Obowiązkowe Nazwa dojścia używanego do pracy z zestawem wierszy.(Optional) The name of the handle you use to work with the rowset. Jeśli określisz nazwę, db_command generuje klasę o określonej nazwie, która może być używana do przechodzenia zestawu wierszy lub wykonywania wielu zapytań akcji.If you specify name, db_command generates a class with the specified name, which can be used to traverse the rowset or to execute multiple action queries. Jeśli Nazwa nie zostanie określona, nie będzie możliwe zwrócenie więcej niż jednego wiersza wyników do użytkownika.If you do not specify name, it will not be possible to return more than one row of results to the user.

source_namesource_name
Obowiązkowe CSession Zmienna lub wystąpienie klasy, db_source do której zastosowano polecenie.(Optional) The CSession variable or instance of a class that has the db_source attribute applied to it on which the command executes. Zobacz db_source.See db_source.

db_command sprawdza, czy zmienna użyta dla source_name jest prawidłowa, więc określona zmienna powinna być w funkcji lub globalnym zakresie.db_command checks to ensure that the variable used for source_name is valid, so the specified variable should be in function or global scope.

wynikhresult
Obowiązkowe Identyfikuje zmienną, która będzie otrzymywać wartość HRESULT tego polecenia bazy danych.(Optional) Identifies the variable that will receive the HRESULT of this database command. Jeśli zmienna nie istnieje, zostanie automatycznie wprowadzona przez atrybut.If the variable does not exist, it will be automatically injected by the attribute.

powiązańbindings
Obowiązkowe Umożliwia rozdzielenie parametrów powiązania za pomocą polecenia OLE DB.(Optional) Allows you to separate the binding parameters from the OLE DB command.

Jeśli określisz wartość powiązań, db_command przeanalizuje skojarzoną wartość i nie przeanalizuje parametru [ BindType].If you specify a value for bindings, db_command will parse the associated value and will not parse the [bindtype] parameter. To użycie umożliwia użycie składni dostawcy OLE DB.This usage allows you to use OLE DB provider syntax. Aby wyłączyć analizowanie bez parametrów powiązań, określ Bindings="" .To disable parsing, without binding parameters, specify Bindings="".

Jeśli nie określisz wartości powiązań, db_command przeanalizuje Blok parametrów powiązania, szukając znaku "(", po którym następuje [ powiązanietype] w nawiasach, po którym następuje co najmniej jedna zadeklarowana wcześniej zmienna członkowska języka C++, po której następuje znak ")".If you do not specify a value for bindings, db_command will parse the binding parameter block, looking for '(', followed by [bindtype] in brackets, followed by one or more previously declared C++ member variables, followed by ')'. Cały tekst między nawiasami zostanie usunięty z wyniku polecenia i te parametry będą używane do konstruowania powiązań kolumn i parametrów dla tego polecenia.All text between the parentheses will be stripped from the resulting command, and these parameters will be used to construct column and parameter bindings for this command.

bulk_fetchbulk_fetch
Obowiązkowe Wartość całkowita określająca liczbę wierszy do pobrania.(Optional) An integer value that specifies the number of rows to fetch.

Wartość domyślna to 1, która określa Pobieranie pojedynczego wiersza (zestaw wierszy będzie typu CRowset).The default value is 1, which specifies single row fetching (the rowset will be of type CRowset).

Wartość większa niż 1 określa pobieranie wierszy zbiorczych.A value greater than 1 specifies bulk row fetching. Pobieranie wierszy zbiorczych odnosi się do zdolności zbiorczych zestawów wierszy do pobrania wielu dojść do wierszy (zestaw wierszy będzie typu CBulkRowset i będzie wywoływał SetRows określoną liczbę wierszy).Bulk row fetching refers to the ability of bulk rowsets to fetch multiple row handles (the rowset will be of type CBulkRowset and will call SetRows with the specified number of rows).

Jeśli bulk_fetch jest mniejsza niż 1, SetRows zwróci wartość zero.If bulk_fetch is less than one, SetRows will return zero.

UwagiRemarks

db_command tworzy obiekt CCommand , który jest używany przez konsumenta OLE DB do wykonania polecenia.db_command creates a CCommand object, which is used by an OLE DB consumer to execute a command.

Można użyć db_command z zakresem klasy lub funkcji; Główną różnicą jest zakres CCommand obiektu.You can use db_command with either class or function scope; the main difference is the scope of the CCommand object. Wraz z zakresem funkcji dane takie jak powiązania kończą się na końcu funkcji.With function scope, data such as bindings terminate at function end. Użycie zakresów klasy i funkcji obejmuje OLE DB klasy szablonu konsumenta CCommand<> , ale argumenty szablonu różnią się w przypadku funkcji i klas.Both class and function scope usages involve the OLE DB Consumer Template class CCommand<>, but the template arguments differ for the function and class cases. W przypadku funkcji, powiązania zostaną wykonane do obiektu, Accessor który składa się ze zmiennych lokalnych, podczas gdy użycie klasy spowoduje wywnioskowanie CAccessor klasy pochodnej jako argumentu.In the function case, bindings will be made to an Accessor that comprises local variables, while the class usage will infer a CAccessor-derived class as the argument. Gdy jest używany jako atrybut klasy, db_command działa w połączeniu z Db_column.When used as a class attribute, db_command works in conjunction with db_column.

db_command może służyć do wykonywania poleceń, które nie zwracają zestawu wyników.db_command can be used to execute commands that do not return a result set.

Gdy dostawca atrybutu konsumenta zastosuje ten atrybut do klasy, kompilator zmieni nazwę klasy na _ YourClassName, gdzie YourClassName jest nazwą, która została nadana klasie, a kompilator utworzy również klasę o nazwie YourClassName, która pochodzi z _ metody dostępu YourClassName.When the consumer attribute provider applies this attribute to a class, the compiler will rename the class to _YourClassName Accessor, where YourClassName is the name you gave the class, and the compiler will also create a class called YourClassName, which derives from _YourClassName Accessor. W Widok klasy są wyświetlane obie klasy.In Class View, you will see both classes.

PrzykładyExamples

Ten przykład definiuje polecenie, które wybiera imiona i nazwiska z tabeli, w której kolumna State pasuje do "CA".This sample defines a command that selects the first and last names from a table where the state column matches 'CA'. db_command tworzy i odczytuje zestaw wierszy, w którym można wywołać funkcje generowane przez kreatora, takie jak metody OpenAll i CloseAll, a także CRowset funkcje członkowskie, takie jak MoveNext.db_command creates and reads a rowset on which you can call wizard-generated functions such as OpenAll and CloseAll, as well as CRowset member functions such as MoveNext.

Należy zauważyć, że ten kod wymaga podania własnych parametrów połączenia, które łączą się z bazą danych pubs.Note that this code requires you to provide your own connection string that connects to the pubs database. Aby uzyskać informacje o tym, jak to zrobić w środowisku deweloperskim, zobacz How to: Connect to a Database and Browse Existing objectss and Add New Connections.For information on how to do this in the development environment, see How to: Connect to a Database and Browse Existing Objects and Add new connections.

// 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
// 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();
}

Ten przykład używa db_source na klasie źródła danych CMySource i db_command w klasach poleceń CCommand1 i CCommand2 .This sample uses db_source on a data source class CMySource, and db_command on command classes CCommand1 and 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();
}

WymaganiaRequirements

Kontekst atrybutuAttribute context WartośćValue
DotyczyApplies to class, struct , członek, metoda, lokalnaclass, struct, member, method, local
PowtarzalnośćRepeatable NieNo
Wymagane atrybutyRequired attributes BrakNone
Nieprawidłowe atrybutyInvalid attributes BrakNone

Aby uzyskać więcej informacji na temat kontekstów atrybutów, zobacz konteksty atrybutów.For more information about the attribute contexts, see Attribute Contexts.

Zobacz teżSee also

OLE DB atrybuty konsumentaOLE DB Consumer Attributes
Atrybuty autonomiczneStand-Alone Attributes