CCommand (Clase)
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. |
| Abierta | Ejecuta y, opcionalmente, enlaza el comando. |
Métodos heredados
| Nombre | Descripción |
|---|---|
| Crear | 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 CCommandTMultiple=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
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de