Classe CCommand

  • Artigo
  • 8 minutos para o fim da leitura

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 ( CDynamicParameterAccessor como, 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 do conjunto de linhas ( CArrayRowset como 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
Close Fecha o comando atual.
GetNextResult Busca o próximo resultado ao usar vários conjuntos de resultados.
Abrir Executa e, opcionalmente, associa o comando.

Métodos herdados

Nome Descrição
Criar Cria um novo comando para a sessão especificada e, em seguida, 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 libera o comando.
SetParameterInfo Especifica o tipo nativo de cada parâmetro de 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âmetro ou executar um comando. Se você simplesmente precisar abrir um conjunto de linhas simples, use CTable em vez disso.

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

Observe que você não pode usar procedimentos armazenados com o provedor de OLE DB para Jet, pois esse provedor não oferece suporte a procedimentos armazenados (somente constantes são permitidas em cadeias de caracteres de consulta).

CCommand::Close

Libera o conjunto de linhas de acessador associado ao comando.

Sintaxe

void Close();

Comentários

Um comando usa um conjunto de linhas, acessador de conjunto de resultados e (opcionalmente) um acessador de parâmetro (ao contrário de 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 ambos Close e ReleaseCommand após o comando.

Quando você quiser executar o mesmo comando repetidamente, deverá liberar cada acessador de 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 tem parâmetros de saída. em muitos provedores (como o provedor de OLE DB para SQL Server), os valores de parâmetros de saída não estarão acessíveis até que você feche o acessador de conjunto de resultados. Chame Close para fechar o conjunto de linhas retornado e o acessador de conjunto de resultados, mas não o acessador de parâmetro, permitindo assim que você recupere os valores de 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

Busca o próximo conjunto de resultados, se houver um disponível.

Sintaxe

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

Parâmetros

pulRowsAffected
[entrada/saída] Um ponteiro para a memória em que a contagem de linhas afetadas por um comando é retornada.

bBind
no Especifica se o comando deve ser associado automaticamente após ser executado. O padrão é true , que faz com que o comando seja vinculado automaticamente. Definir bBind para false impedir a associação automática do comando para que você possa associar manualmente. (A vinculação manual é de interesse particular para os usuários OLAP.)

Valor Retornado

Um HRESULT padrão.

Comentários

Se um conjunto de resultados tiver sido previamente buscado, 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 CCommand modelo 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
no A sessão na qual executar o comando.

wszCommand
no O comando a ser executado, passado como uma cadeia de caracteres Unicode. Pode ser NULL ao usar CAccessor , caso em que o comando será recuperado do valor passado para a macro DEFINE_COMMAND . Consulte ICommand:: execute na referência do programador de OLE DB para obter detalhes.

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

pPropSet
no Um ponteiro para uma matriz de estruturas DBPROPSET que contém propriedades e valores a serem definidos. consulte conjuntos de propriedades e grupos de propriedades na referência do programador de OLE DB no SDK do Windows.

pRowsAffected
[entrada/saída] Um ponteiro para a memória em que a contagem de linhas afetadas por um comando é retornada. Se * pRowsAffected for nulo, nenhuma contagem de linhas será retornada. Caso contrário, Opendefine *pRowsAffected de acordo com as seguintes condições:

If Então
O cParamSets elemento de pParams é maior que 1 *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 do 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 vinculado automaticamente depois de ser executado. O padrão é true, que faz com que o comando seja vinculado automaticamente. Definir bBind como false impede a associação automática do comando para que você possa se vincular manualmente. (A associação manual é de interesse específico para usuários OLAP.)

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

Valor Retornado

Um HRESULT padrão.

Comentários

As três primeiras formas de Open fazer uma sessão, criar um comando e executar o comando, vinculando os parâmetros conforme necessário.

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

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

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

Use a quarta forma de Open quando você já tiver criado um comando e quiser 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 o comando será criado.

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 do texto do comando. Para obter uma descrição dos dialetos, consulte ICommandText::GetCommandText na referência OLE DB programador.

Valor Retornado

Um HRESULT padrão.

Comentários

A primeira forma de assume uma Create cadeia de caracteres de comando Unicode. A segunda forma de assume uma Create cadeia de caracteres de comando ANSI (fornecida para compatibilidade com aplicativos ANSI existentes).

CCommand::CreateCommand

Cria um novo comando.

Sintaxe

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

Parâmetros

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

Valor Retornado

Um 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 OLE DB do programador.

Valor Retornado

Um 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 Retornado

Um HRESULT padrão.

Comentários

Esse método envolve o método OLE DB ICommandPrepare::P repare.

CCommand::ReleaseCommand

Libera o acessador de parâmetro e, em seguida, 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 de comando.

Sintaxe

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

Parâmetros

Consulte ICommandWithParameters::SetParameterInfo na OLE DB do programador.

Valor Retornado

Um HRESULT padrão.

CCommand::Unprepare

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

Sintaxe

HRESULT CCommandBase::Unprepare() throw();

Valor retornado

Um HRESULT padrão.

Comentários

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

Confira também

Modelos de consumidor OLE DB
referência OLE DB modelos de consumidor