Compartir a través de

CCommand (Clase)

  • Artículo

Proporciona métodos para establecer y ejecutar un comando.

Sintaxis

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
Tipo de clase de descriptor de acceso (como CDynamicParameterAccessor, CDynamicStringAccessoro CEnumeratorAccessor) que desea que use el comando. El valor predeterminado es CNoAccessor, que especifica que la clase no admite parámetros ni columnas de salida.

TRowset
Tipo de clase de conjunto de filas (como CArrayRowset o CNoRowset) que desea que use el comando. El valor predeterminado es CRowset.

TMultiple
Para usar un comando OLE DB que pueda devolver varios resultados, especifique CMultipleResults. En caso contrario, use CNoMultipleResults. Para más información, consulte IMultipleResults.

Requisitos

Encabezado: atldbcli.h

Miembros

Métodos

Nombre Descripción
Cerrar Cierra el comando actual.
GetNextResult Captura el siguiente resultado si se usan varios conjuntos de resultados.
Abierto Ejecuta y, opcionalmente, enlaza el comando.

Métodos heredados

Nombre Descripción
Creación Crea un comando para la sesión especificada y, después, establece el texto del comando.
CreateCommand Crea un comando.
GetParameterInfo Obtiene una lista de los parámetros del comando, sus nombres y sus tipos.
Preparación Valida y optimiza el comando actual.
ReleaseCommand Libera el descriptor de acceso del parámetro si es necesario y, después libera el comando.
SetParameterInfo Especifica el tipo nativo de cada parámetro de comando.
Unprepare Descarta el plan de ejecución del comando actual.

Comentarios

Use esta clase cuando necesite realizar una operación basada en parámetros o ejecutar un comando. Si solo necesita abrir un conjunto de filas simple, use CTable.

La clase del descriptor de acceso que usa determina el método de enlace de los parámetros y datos.

Tenga en cuenta que los procedimientos almacenados no se pueden usar con el proveedor de OLE DB para Jet, ya que ese proveedor no admite procedimientos almacenados (solo se permiten constantes en cadenas de consulta).

CCommand::Close

Libera el conjunto de filas del descriptor de acceso asociado al comando.

Sintaxis

void Close();

Comentarios

Un comando usa un conjunto de filas, un descriptor de acceso de conjunto de resultados y (opcionalmente) un descriptor de acceso de parámetro (a diferencia de las tablas, que no admiten parámetros y no necesitan un descriptor de acceso de parámetro).

Al ejecutar un comando, debe llamar tanto a Close como a ReleaseCommand después del comando.

Si desea ejecutar el mismo comando repetidamente, debe liberar todos los descriptores de acceso del conjunto de resultados llamando a Close antes de llamar a Execute. Al final de la serie, debe liberar el descriptor de acceso de parámetro mediante una llamada a ReleaseCommand. Otro escenario común es llamar a un procedimiento almacenado que tenga parámetros de salida. En muchos proveedores (como el proveedor OLE DB para SQL Server), no se podrá acceder a los valores de los parámetros de salida hasta que se cierre el descriptor de acceso del conjunto de resultados. Llame a Close para cerrar el conjunto de filas devuelto y el descriptor de acceso del conjunto de resultados, pero no el descriptor de acceso de parámetros, lo que le permite recuperar los valores de los parámetros de salida.

Ejemplo

El ejemplo siguiente muestra cómo se puede llamar a Close y ReleaseCommand cuando se ejecuta el mismo comando varias veces.

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

Captura el siguiente conjunto de resultados, si hay alguno disponible.

Sintaxis

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

Parámetros

pulRowsAffected
[in/out] Puntero a la memoria donde se devuelve el recuento de filas afectadas por un comando.

bBind
[in] Especifica si enlazar el comando automáticamente después de ejecutarse. El valor predeterminado es true, lo que hace que el comando se enlace automáticamente. Si bBind se establece en false, se impide el enlace automático del comando para que el enlace se pueda realizar manualmente (el enlace manual es de especial interés para los usuarios de OLAP).

Valor devuelto

Un HRESULT estándar.

Comentarios

Si se ha capturado previamente un conjunto de resultados, esta función libera el conjunto de resultados anterior y elimina el enlace de las columnas. Si bBind es true, enlaza las nuevas columnas.

Solo se debe llamar a esta función si se han especificado varios resultados estableciendo el parámetro de plantilla de CCommand TMultiple=CMultipleResults.

CCommand::Open

Ejecuta y, opcionalmente, enlaza el comando.

Sintaxis

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

Sesión
[in] Sesión en la que se ejecuta el comando.

wszCommand
[in] Comando que se ejecuta, pasado como una cadena Unicode. Puede ser NULL cuando se usa CAccessor, en cuyo caso el comando se recuperará del valor pasado a la macro DEFINE_COMMAND. Para más información, consulte ICommand::Execute en la referencia del programador de OLE DB.

szCommand
[in] Igual que wszCommand, salvo que este parámetro toma una cadena de comando ANSI. La cuarta forma de este método puede tomar un valor NULL. Para más información, vea "Comentarios" en este mismo tema.

pPropSet
[in] Puntero a una matriz de estructuras DBPROPSET que contiene las propiedades y los valores que se van a establecer. Vea Conjuntos de propiedades y grupos de propiedades en la referencia del programador OLE DB de Windows SDK.

pRowsAffected
[in/out] Puntero a la memoria donde se devuelve el recuento de filas afectadas por un comando. Si el valor de *pRowsAffected es NULL, no se devuelve ningún recuento de filas. De lo contrario, Open establece *pRowsAffected, en función de las siguientes condiciones:

Si Entonces
El elemento cParamSets de pParams es mayor que 1 *pRowsAffected representa el número total de filas afectadas por todos los conjuntos de parámetros especificados en la ejecución.
El número de filas afectadas no está disponible *pRowsAffected se establece en -1.
El comando no actualiza, elimina ni inserta filas. *pRowsAffected es indefinido.

guidCommand
[in] GUID que especifica la sintaxis y las reglas generales que el proveedor usará al analizar el texto del comando. Para más información, consulte ICommandText::GetCommandText e ICommandText::SetCommandText en la referencia del programador de OLE DB.

bBind
[in] Especifica si enlazar el comando automáticamente después de ejecutarse. El valor predeterminado es true, lo que hace que el comando se enlace automáticamente. Si bBind se establece en false, se impide el enlace automático del comando para que el enlace se pueda realizar manualmente (el enlace manual es de especial interés para los usuarios de OLAP).

ulPropSets
[in] Número de estructuras DBPROPSET pasadas en el argumento pPropSet.

Valor devuelto

Un HRESULT estándar.

Comentarios

Las tres primeras formas de Open (tomar una sesión, crear un comando y ejecutar el comando) enlazando los parámetros que sean necesarios.

La primera forma de Open toma una cadena de comando Unicode y no tiene ningún valor predeterminado.

La segunda forma de Open toma una cadena de comandos ANSI y no tiene valor predeterminado (proporcionado para lograr compatibilidad con versiones anteriores con las aplicaciones ANSI existentes).

La tercera forma de Open permite que el valor de la cadena de comandos sea NULL, debido a un tipo int con un valor predeterminado de NULL. Se proporciona para llamar a Open(session, NULL); o Open(session); porque NULL es del tipo int. Esta versión requiere y afirma que el valor del parámetro int sea NULL.

Use la cuarta forma de Open cuando haya creado un comando y desee realizar una sola preparación y varias ejecuciones.

Nota:

Open llama a Execute, que a su vez llama a GetNextResult.

CCommand::Create

Llama a CCommand::CreateCommand para crear un comando para la sesión especificada y, después, llama a ICommandText::SetCommandText para especificar el texto del comando.

Sintaxis

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

Sesión
[in] Una sesión en la que se crea el comando.

wszCommand
[in] Puntero al texto Unicode de la cadena de comandos.

szCommand
[in] Puntero al texto ANSI de la cadena de comandos.

guidCommand
[in] GUID que especifica la sintaxis y las reglas generales que el proveedor usará al analizar el texto del comando. Para ver una descripción de los dialectos, consulte ICommandText::GetCommandText en la referencia del programador de OLE DB.

Valor devuelto

Un HRESULT estándar.

Comentarios

La primera forma de Create toma una cadena de comandos Unicode. La segunda forma de Create toma una cadena de comandos ANSI (proporcionado para lograr compatibilidad con versiones anteriores con las aplicaciones ANSI existentes).

CCommand::CreateCommand

Crea un comando.

Sintaxis

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

Parámetros

Sesión
[in] Objeto CSession que se va a asociar al nuevo comando.

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método crea un comando mediante el objeto de sesión especificado.

CCommand::GetParameterInfo

Obtiene una lista de los parámetros del comando, sus nombres y sus tipos.

Sintaxis

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

Parámetros

Vea ICommandWithParameters::GetParameterInfo en la referencia del programador de OLE DB.

Valor devuelto

Un HRESULT estándar.

CCommand::Prepare

Valida y optimiza el comando actual.

Sintaxis

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

Parámetros

cExpectedRuns
[in] Número de veces que espera ejecutar el comando.

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método ajusta el método OLE DB ICommandPrepare::Prepare.

CCommand::ReleaseCommand

Libera el descriptor de acceso del parámetro y, después libera el propio comando.

Sintaxis

void CCommandBase::ReleaseCommand() throw();

Comentarios

ReleaseCommand se usa junto con Close. Consulte Cerrar para más información sobre el uso.

CCommand::SetParameterInfo

Especifica el tipo nativo de cada parámetro de comando.

Sintaxis

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

Parámetros

Vea ICommandWithParameters::SetParameterInfo en la referencia del programador de OLE DB.

Valor devuelto

Un HRESULT estándar.

CCommand::Unprepare

Descarta el plan de ejecución del comando actual.

Sintaxis

HRESULT CCommandBase::Unprepare() throw();

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método ajusta el método OLE DB ICommandPrepare::Unprepare.

Consulte también

Plantillas de consumidor OLE DB
Referencia de plantillas de consumidor OLE DB