Classe CCommand
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 Devolução
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 CCommandTMultiple=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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de