Compartilhar via

Classe CCommand

  • Artigo

Fornece métodos para definir e executar um comando.

Sintaxe

template <class TAccessor = CNoAccessor,
   template <typename T> class TRowset = CRowset,
   class TMultiple = CNoMultipleResults>
class CCommand :
   public CAccessorRowset <TAccessor, TRowset>,
   public CCommandBase,
   public TMultiple

Parâmetros

TAccessor
O tipo de classe de acessador (como CDynamicParameterAccessor, CDynamicStringAccessor ou CEnumeratorAccessor) que você deseja que o comando use. O padrão é CNoAccessor, que especifica que a classe não dá suporte a parâmetros ou colunas de saída.

TRowset
O tipo de classe de conjunto de linhas (como CArrayRowset ou CNoRowset) que você deseja que o comando use. O padrão é CRowset.

TMultiple
Para usar um comando OLE DB que pode retornar vários resultados, especifique CMultipleResults. Caso contrário, use CNoMultipleResults. Para obter detalhes, consulte IMultipleResults.

Requisitos

Cabeçalho: atldbcli.h

Membros

Métodos

Nome Descrição
Fechar Fecha o comando atual.
GetNextResult Busca o próximo resultado ao usar vários conjuntos de resultados.
Aberto Executa e, opcionalmente, associa o comando.

Métodos herdados

Nome Descrição
Criar Cria um novo comando para a sessão especificada e define o texto do comando.
CreateCommand Cria um novo comando.
GetParameterInfo Obtém uma lista dos parâmetros do comando, seus nomes e seus tipos.
Preparar Valida e otimiza o comando atual.
ReleaseCommand Libera o acessador de parâmetro se necessário, e, em seguida, libera o comando.
SetParameterInfo Especifica o tipo nativo de cada parâmetro do comando.
Unprepare Descarta o plano de execução do comando atual.

Comentários

Use essa classe quando precisar executar uma operação baseada em parâmetros ou executar um comando. Se você precisar apenas abrir um conjunto de linhas simples, use CTable.

A classe de acessador que você está usando determina o método de dados e parâmetros de associação.

Observe que não é possível usar procedimentos armazenados com o provedor OLE DB para Jet porque esse provedor não dá suporte a procedimentos armazenados (somente constantes são permitidas em cadeias de caracteres de consulta).

CCommand::Close

Libera o conjunto de linhas do acessador associado ao comando.

Sintaxe

void Close();

Comentários

Um comando usa um conjunto de linhas, um acessador de conjunto de resultados e (opcionalmente) um acessador de parâmetros (ao contrário das tabelas, que não dão suporte a parâmetros e não precisam de um acessador de parâmetro).

Ao executar um comando, você deve chamar Close e ReleaseCommand após o comando.

Quando quiser executar o mesmo comando repetidamente, você deve liberar cada acessador do conjunto de resultados chamando Close antes de chamar Execute. No final da série, você deve liberar o acessador de parâmetro chamando ReleaseCommand. Outro cenário comum é chamar um procedimento armazenado que tenha parâmetros de saída. Em muitos provedores (como o provedor OLE DB para SQL Server), os valores do parâmetro de saída não estarão acessíveis até que você feche o acessador do conjunto de resultados. Chame Close para fechar o conjunto de linhas retornado e o acessador do conjunto de resultados, mas não o acessador de parâmetros, permitindo que você recupere os valores do parâmetro de saída.

Exemplo

O exemplo a seguir mostra como você pode chamar Close e ReleaseCommand quando executa o mesmo comando repetidamente.

void DoCCommandTest()
{
   HRESULT hr;

   hr = CoInitialize(NULL);

   CCustomer rs;           // Your CCommand-derived class
   rs.m_BillingID = 6611;  // Open billing ID 6611
   hr = rs.OpenAll();      // (Open also executes the command)
   hr = rs.MoveFirst();    // Move to the first row and print it

   _tprintf_s(_T("First name: %s, Last Name: %s, Customer ID: %d, Postal Code: %s\n"),
      rs.m_ContactFirstName, rs.m_L_Name, rs.m_CustomerID, rs.m_PostalCode);

   // Close the first command execution
   rs.Close();

   rs.m_BillingID = 3333;     // Open billing ID 3333 (a new customer)
   hr = rs.Open();            // (Open also executes the command)
   hr = rs.MoveFirst();       // Move to the first row and print it

   _tprintf_s(_T("First name: %s, Last Name: %s, Customer ID: %d, Postal Code: %s\n"),
      rs.m_ContactFirstName, rs.m_L_Name, rs.m_CustomerID, rs.m_PostalCode);

   // Close the second command execution;
   // Instead of the two following lines
   // you could simply call rs.CloseAll()
   // (a wizard-generated method):
   rs.Close();
   rs.ReleaseCommand();

   CoUninitialize();
}

CCommand::GetNextResult

Buscará o próximo conjunto de resultados se algum estiver disponível.

Sintaxe

HRESULT GetNextResult(DBROWCOUNT* pulRowsAffected,
   bool bBind = true) throw();

Parâmetros

pulRowsAffected
[in/out] Um ponteiro para a memória onde a contagem de linhas afetadas por um comando é retornada.

bBind
[in] Especifica se o comando deve ser associado automaticamente após a execução. O padrão é true, o que faz com que o comando seja associado automaticamente. Configurar o bBind como false impede a associação automática do comando para que você possa fazer a associação manualmente. (A associação manual é de interesse particular de usuários OLAP.)

Valor de retorno

Um valor HRESULT padrão.

Comentários

Se um conjunto de resultados tiver sido buscado anteriormente, essa função liberará o conjunto de resultados anterior e desassociará as colunas. Se bBind for true, ele associará as novas colunas.

Você deve chamar essa função somente se tiver especificado vários resultados definindo o parâmetro de modelo CCommand TMultiple=CMultipleResults.

CCommand::Open

Executa e, opcionalmente, associa o comando.

Sintaxe

HRESULT Open(const CSession& session,
   LPCWSTR wszCommand,
   DBPROPSET *pPropSet = NULL,
   DBROWCOUNT* pRowsAffected = NULL,
   REFGUID guidCommand = DBGUID_DEFAULT,
   bool bBind = true,
   ULONG ulPropSets = 0) throw();

HRESULT Open(const CSession& session,
   LPCSTR szCommand,
   DBPROPSET *pPropSet = NULL,
   DBROWCOUNT* pRowsAffected = NULL,
   REFGUID guidCommand = DBGUID_DEFAULT,
   bool bBind = true,
   ULONG ulPropSets = 0) throw();

HRESULT Open(const CSession& session,
   INT szCommand = NULL,
   DBPROPSET *pPropSet = NULL,
   DBROWCOUNT* pRowsAffected = NULL,
   REFGUID guidCommand = DBGUID_DEFAULT,
   bool bBind = true,
   ULONG ulPropSets = 0) throw();

HRESULT Open(DBPROPSET *pPropSet = NULL,
   DBROWCOUNT* pRowsAffected = NULL,
   bool bBind = true,
   ULONG ulPropSets = 0) throw();

Parâmetros

sessão
[in] A sessão na qual executar o comando.

wszCommand
[in] O comando a ser executado, passado como uma cadeia de caracteres Unicode. Pode ser NULL ao usar CAccessor. Nesse caso, o comando será recuperado do valor passado para a macro DEFINE_COMMAND. Consulte ICommand::Execute na Referência do Programador OLE DB para obter detalhes.

szCommand
[in] O mesmo que wszCommand, exceto que esse parâmetro usa uma cadeia de caracteres de comando ANSI. A quarta forma desse método pode ter um valor NULL. Consulte "Comentários" mais adiante neste tópico para obter detalhes.

pPropSet
[in] Um ponteiro para uma matriz de estruturas DBPROPSET que contêm propriedades e valores a serem definidos. Confira Conjuntos de propriedades e grupos de propriedades na Referência do programador OLE DB no SDK do Windows.

pRowsAffected
[in/out] Um ponteiro para a memória onde a contagem de linhas afetadas por um comando é retornada. Se *pRowsAffected for NULL, nenhuma contagem de linhas será retornada. Caso contrário, Open define *pRowsAffected de acordo com as seguintes condições:

If Então
O elemento cParamSets de pParams é maior que 1 O *pRowsAffected representa o número total de linhas afetadas por todos os conjuntos de parâmetros especificados na execução.
O número de linhas afetadas não está disponível *pRowsAffected está definido como -1.
O comando não atualiza, exclui ou insere linhas *pRowsAffected é indefinido.

guidCommand
[in] Um GUID que especifica a sintaxe e as regras gerais para o provedor usar na análise de texto do comando. Consulte ICommandText::GetCommandText e ICommandText::SetCommandText na Referência do Programador OLE DB para obter detalhes.

bBind
[in] Especifica se o comando deve ser associado automaticamente após a execução. O padrão é true, o que faz com que o comando seja associado automaticamente. Configurar o bBind como false impede a associação automática do comando para que você possa fazer a associação manualmente. (A associação manual é de interesse particular de usuários OLAP.)

ulPropSets
[in] O número de estruturas DBPROPSET passadas no argumento pPropSet.

Valor de retorno

Um valor HRESULT padrão.

Comentários

As três primeiras formas de Open recebem uma sessão, criam um comando e executam o comando associando todos os parâmetros conforme necessário.

A primeira forma de Open recebe uma cadeia de caracteres de comando Unicode e não tem nenhum valor padrão.

A segunda forma de Open recebe uma cadeia de caracteres de comando ANSI e nenhum valor padrão (fornecido para compatibilidade com versões anteriores com aplicativos ANSI existentes).

A terceira forma de Open permite que a cadeia de caracteres de comando seja NULL, devido ao tipo int com um valor padrão de NULL. Ele é fornecido para chamar Open(session, NULL); ou Open(session); porque NULL é do tipo int. Essa versão requer e declara que o parâmetro int seja NULL.

Use a quarta forma de Open quando você já criou um comando e deseja executar uma única Preparação e várias execuções.

Observação

Open chama Execute, que, por sua vez, chama GetNextResult.

CCommand::Create

Chama CCommand::CreateCommand para criar um comando para a sessão especificada e, em seguida, chama ICommandText::SetCommandText para especificar o texto do comando.

Sintaxe

HRESULT CCommandBase::Create(const CSession& session,
   LPCWSTR wszCommand,
   REFGUID guidCommand = DBGUID_DEFAULT) throw ();

HRESULT CCommandBase::Create(const CSession& session,
   LPCSTR szCommand,
   REFGUID guidCommand = DBGUID_DEFAULT) throw ();

Parâmetros

sessão
[in] Uma sessão na qual criar o comando.

wszCommand
[in] Um ponteiro para o texto Unicode da cadeia de caracteres de comando.

szCommand
[in] Um ponteiro para o texto ANSI da cadeia de caracteres de comando.

guidCommand
[in] Um GUID que especifica a sintaxe e as regras gerais para o provedor usar na análise de texto do comando. Para obter uma descrição dos dialetos, consulte ICommandText::GetCommandText na Referência do Programador OLE DB.

Valor de retorno

Um valor HRESULT padrão.

Comentários

A primeira forma de Create recebe uma cadeia de caracteres de comando Unicode. A segunda forma de Create recebe uma cadeia de caracteres de comando ANSI (fornecida para compatibilidade com versões anteriores com aplicativos ANSI existentes).

CCommand::CreateCommand

Cria um novo comando.

Sintaxe

HRESULT CCommandBase::CreateCommand(const CSession& session) throw ();

Parâmetros

sessão
[in] Um objeto CSession a ser associado ao novo comando.

Valor de retorno

Um valor HRESULT padrão.

Comentários

Esse método cria um comando usando o objeto de sessão especificado.

CCommand::GetParameterInfo

Obtém uma lista dos parâmetros do comando, seus nomes e seus tipos.

Sintaxe

HRESULT CCommandBase::GetParameterInfo(DB_UPARAMS* pParams,
   DBPARAMINFO** ppParamInfo,
   OLECHAR** ppNamesBuffer) throw ();

Parâmetros

Consulte ICommandWithParameters::GetParameterInfo na Referência do programador OLE DB.

Valor de retorno

Um valor HRESULT padrão.

CCommand::Prepare

Valida e otimiza o comando atual.

Sintaxe

HRESULT CCommandBase::Prepare(ULONG cExpectedRuns = 0) throw();

Parâmetros

cExpectedRuns
[in] O número de vezes que você espera executar o comando.

Valor de retorno

Um valor HRESULT padrão.

Comentários

Esse método encapsula o método OLE DB ICommandPrepare::Prepare.

CCommand::ReleaseCommand

Libera o acessador de parâmetro e libera o próprio comando.

Sintaxe

void CCommandBase::ReleaseCommand() throw();

Comentários

ReleaseCommand é usado em conjunto com Close. Consulte Fechar para obter detalhes de uso.

CCommand::SetParameterInfo

Especifica o tipo nativo de cada parâmetro do comando.

Sintaxe

HRESULT CCommandBase::SetParameterInfo(DB_UPARAMS ulParams,
   const DBORDINAL* pOrdinals,
   const DBPARAMBINDINFO* pParamInfo) throw();

Parâmetros

Consulte ICommandWithParameters::SetParameterInfo na Referência do programador OLE DB.

Valor de retorno

Um valor HRESULT padrão.

CCommand::Unprepare

Descarta o plano de execução do comando atual.

Sintaxe

HRESULT CCommandBase::Unprepare() throw();

Valor retornado

Um valor HRESULT padrão.

Comentários

Esse método encapsula o método OLE DB ICommandPrepare::Unprepare.

Confira também

Modelos de consumidor OLE DB
Referência de modelos de consumidor do OLE DB