`db_command`

Artigo
06/16/2023

Cria um comando OLE DB.

Sintaxe

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

Parâmetros

command
Uma cadeia de caracteres de comando que contém o texto de um comando OLE DB. Um exemplo simples é:

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

A sintaxe de command é a seguinte:

bloco de parâmetro de associação 1
Comando OLE DB
bloco de parâmetro de associação 2
continuação do comando OLE DB
bloco de parâmetro de associação 3
...

Um bloco de parâmetro de associação é definido da seguinte maneira:

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

em que:

( marca o início do bloco de associação de dados.
bindtype é uma das cadeias de caracteres a seguir que não diferenciam maiúsculas de minúsculas:
- [db_column] associa cada uma das variáveis de membro a uma coluna em um conjunto de linhas.
- [bindto] (mesmo que [db_column]).
- [in] associa variáveis de membro como parâmetros de entrada.
- [out] associa variáveis de membro como parâmetros de saída.
- [in,out] associa variáveis de membro como parâmetros de entrada/saída.
szVarN, nVarN resolvem para variáveis de membro dentro do escopo atual.
) marca o fim do bloco de associação de dados.

Se a cadeia de caracteres de comando contiver um ou mais especificadores, como [in], [out] ou [in/out], db_command criará um mapa de parâmetros.

Se a cadeia de caracteres de comando contiver um ou mais parâmetros como [db_column] ou [bindto], em seguida db_command gerará um conjunto de linhas e um mapa do acessador para atender a essas variáveis associadas. Para obter mais informações, consulte db_accessor.

Observação

A sintaxe de bindtype e o parâmetro bindings não são válidos ao usar db_command no nível da classe.

A seguir estão alguns exemplos de blocos de parâmetro de associação. O exemplo a seguir associa os membros de dados m_au_fname e m_au_lname às colunas au_fname e au_lname, respectivamente, da tabela de autores no banco de dados pubs:

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
(Opcional) O nome do identificador usado para trabalhar com o conjunto de linhas. Se você especificar name, db_command gerará uma classe com a name especificada, que pode ser usada para percorrer o conjunto de linhas ou para executar várias consultas de ação. Se você não especificar name, não será possível retornar mais de uma linha de resultados ao usuário.

source_name
(Opcional) A variável CSession ou instância de uma classe que tem o atributo db_source aplicado a ela na qual o comando é executado. Consulte db_source.

db_command verifica se a variável usada por source_name é válida, portanto, a variável especificada deve estar na função ou no escopo global.

hresult
(Opcional) Identifica a variável que receberá o HRESULT desse comando de banco de dados. Se a variável não existir, ela será injetada automaticamente pelo atributo.

bindings
(Opcional) Permite separar os parâmetros de associação do comando OLE DB.

Se você especificar um valor para bindings, db_command analisará o valor associado e não analisará o parâmetro bindtype. Esse uso permite que você use a sintaxe do provedor OLE DB. Para desabilitar a análise sem parâmetros de associação, especifique Bindings="".

Se não for especificado um valor para bindings, db_command analisará o bloco de parâmetros de associação. Ele procura '(', seguido por um bindtype entre colchetes, seguidos por uma ou mais variáveis de membro C++ declaradas anteriormente, seguidas por ')'. Ele remove todo o texto entre os parênteses do comando resultante. Esses parâmetros são usados para construir associações de coluna e parâmetro para esse comando.

bulk_fetch
(Opcional) Um valor inteiro que especifica o número de linhas a ser efetuado fetch.

O valor padrão é 1, que especifica a busca de linha única (o conjunto de linhas será do tipo CRowset).

Um valor maior que 1 especifica a busca em de linhas em massa. A busca de linhas em massa refere-se à capacidade de conjuntos de linhas em massa buscar várias alças de linha (o conjunto de linhas será do tipo CBulkRowset e chamará SetRows com o número especificado de linhas).

Se bulk_fetch for menor que um, SetRows retornará zero.

Comentários

db_command cria um objeto CCommand, que é usado por um consumidor OLE DB para executar um comando.

Você pode usar db_command com o escopo de classe ou função; a principal diferença é o escopo do objeto CCommand. Com o escopo da função, dados como associações terminam no final da função. Os usos de classe e escopo de função envolvem a classe modelo de consumidor OLE DB CCommand<>, mas os argumentos de modelo diferem para os casos de função e classe. No caso de função, as associações serão feitas a um Accessor, que inclua variáveis locais, enquanto o uso da classe inferirá uma classe derivada de CAccessor como o argumento. Quando usado como um atributo de classe, db_command funciona em conjunto com db_column.

db_command pode ser usado para executar comandos que não retornam um conjunto de resultados.

Quando o provedor de atributos de consumidor aplica esse atributo a uma classe, o compilador renomeia a classe para _[YourClassName]Accessor, onde [YourClassName] é o nome que você deu à classe. O compilador também cria uma classe chamada [YourClassName], que deriva de _[YourClassName]Accessor. No Modo de Exibição de Classe, você verá ambas as classes.

Exemplos

Esta amostra define um comando que seleciona o primeiro e os sobrenomes de uma tabela em que a coluna de estado corresponde a 'CA'. db_command cria e lê um conjunto de linhas no qual você pode chamar funções geradas pelo assistente, como OpenAll e CloseAll, bem como funções de membro CRowset, como MoveNext.

Esse código exige que você forneça sua própria cadeia de conexão que se conecta ao banco de dados pubs. Para obter informações sobre como fornecer uma cadeia de conexão no ambiente de desenvolvimento, consulte Como se conectar a um banco de dados e procurar objetos existentes e Adicionar novas conexões.

Arquivo de origem 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);
   }
};

Arquivo de origem 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();
}

Esta amostra usa db_source em uma classe de fonte de dados e CMySource db_command em classes de comando CCommand1 e 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();
}

Requisitos

Contexto do atributo	Valor
Aplicável ao	`class`, `struct`, membro, método, local
Repetível	Não
Atributos obrigatórios	Nenhum
Atributos inválidos	Nenhum

Para obter mais informações sobre os contextos de atributo, consulte Contextos de atributo.

Confira também

Atributos do consumidor OLE DB
Atributos autônomos

Compartilhar via

`db_command`

Sintaxe

Parâmetros

Comentários

Exemplos

Requisitos

Confira também

Comentários

Recursos adicionais