CCommand (Clase)CCommand Class

Proporciona métodos para establecer y ejecutar un comando.Provides methods to set and execute a command.

SintaxisSyntax

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

ParámetrosParameters

TAccessorTAccessor
El tipo de clase de descriptor de acceso (como CDynamicParameterAccessor , CDynamicStringAccessor o CEnumeratorAccessor ) que desea que use el comando.The type of accessor class (such as CDynamicParameterAccessor, CDynamicStringAccessor, or CEnumeratorAccessor) that you want the command to use. El valor predeterminado es CNoAccessor , que especifica que la clase no admite parámetros ni columnas de salida.The default is CNoAccessor, which specifies that the class not support parameters or output columns.

TRowsetTRowset
El tipo de clase de conjunto de filas (por ejemplo, CArrayRowset o CNoRowset ) que desea que use el comando.The type of rowset class (such as CArrayRowset or CNoRowset) that you want the command to use. De manera predeterminada, es CRowset.The default is CRowset.

TMultipleTMultiple
Para usar un comando OLE DB que puede devolver varios resultados, especifique cmultipleresults (.To use an OLE DB command that can return multiple results, specify CMultipleResults. De lo contrario, use cnomultipleresults (.Otherwise, use CNoMultipleResults. Para obtener más información, consulte IMultipleResults.For details, see IMultipleResults.

RequisitosRequirements

Encabezado: atldbcli.hHeader: atldbcli.h

MiembrosMembers

MétodosMethods

NombreName DescripciónDescription
CerrarClose Cierra el comando actual.Closes the current command.
GetNextResultGetNextResult Captura el siguiente resultado cuando se usan varios conjuntos de resultados.Fetches the next result when using multiple result sets.
AbrirOpen Ejecuta y, de forma opcional, enlaza el comando.Executes and optionally binds the command.

Métodos heredadosInherited Methods

NombreName DescripciónDescription
CreaciónCreate Crea un nuevo comando para la sesión especificada y, a continuación, establece el texto del comando.Creates a new command for the specified session, then sets the command text.
CreateCommandCreateCommand Crea un nuevo comando.Creates a new command.
GetParameterInfoGetParameterInfo Obtiene una lista de los parámetros del comando, sus nombres y sus tipos.Gets a list of the command's parameters, their names, and their types.
PreparaciónPrepare Valida y optimiza el comando actual.Validates and optimizes the current command.
ReleaseCommandReleaseCommand Libera el descriptor de acceso del parámetro si es necesario y, a continuación, libera el comando.Releases the parameter accessor if necessary, then releases the command.
SetParameterInfoSetParameterInfo Especifica el tipo nativo de cada parámetro de comando.Specifies the native type of each command parameter.
UnprepareUnprepare Descarta el plan de ejecución de comandos actual.Discards the current command execution plan.

ComentariosRemarks

Utilice esta clase cuando necesite realizar una operación basada en parámetros o ejecutar un comando.Use this class when you need to perform a parameter-based operation or execute a command. Si solo necesita abrir un conjunto de filas simple, use CTable en su lugar.If you merely need to open a simple rowset, use CTable instead.

La clase de descriptor de acceso que está usando determina el método de enlace de datos y parámetros.The accessor class you are using determines the method of binding parameters and data.

Tenga en cuenta que no puede utilizar procedimientos almacenados con el proveedor de OLE DB para Jet porque ese proveedor no admite procedimientos almacenados (solo se permiten constantes en las cadenas de consulta).Note that you cannot use stored procedures with the OLE DB Provider for Jet because that provider does not support stored procedures (only constants are allowed in query strings).

CCommand:: CloseCCommand::Close

Libera el conjunto de filas de descriptor de acceso asociado al comando.Releases the accessor rowset associated with the command.

SintaxisSyntax

void Close();

ComentariosRemarks

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).A command uses a rowset, result set accessor, and (optionally) a parameter accessor (unlike tables, which do not support parameters and do not need a parameter accessor).

Al ejecutar un comando, debe llamar a Close y ReleaseCommand después del comando.When you execute a command, you should call both Close and ReleaseCommand after the command.

Si desea ejecutar el mismo comando repetidamente, debe liberar cada descriptor de acceso del conjunto de resultados llamando a Close antes de llamar a Execute .When you want to execute the same command repeatedly, you should release each result set accessor by calling Close before calling Execute. Al final de la serie, debe liberar el descriptor de acceso de parámetro mediante una llamada a ReleaseCommand .At the end of the series, you should release the parameter accessor by calling ReleaseCommand. Otro escenario común es llamar a un procedimiento almacenado que tenga parámetros de salida.Another common scenario is calling a stored procedure that has output parameters. En muchos proveedores (como el proveedor de OLE DB para SQL Server), los valores de los parámetros de salida no serán accesibles hasta que se cierre el descriptor de acceso del conjunto de resultados.On many providers (such as the OLE DB provider for SQL Server) the output parameter values will not be accessible until you close the result set accessor. Llame Close a para cerrar el descriptor de acceso devuelto y del conjunto de resultados, pero no el descriptor de acceso del parámetro, lo que le permite recuperar los valores del parámetro de salida.Call Close to close the returned rowset and result set accessor, but not the parameter accessor, thus allowing you to retrieve the output parameter values.

EjemploExample

El ejemplo siguiente muestra cómo se puede llamar a Close y ReleaseCommand cuando se ejecuta el mismo comando varias veces.The following example shows how you can call Close and ReleaseCommand when you execute the same command repeatedly.

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:: GetNextResultCCommand::GetNextResult

Captura el siguiente conjunto de resultados, si hay alguno disponible.Fetches the next result set if one is available.

SintaxisSyntax

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

ParámetrosParameters

pulRowsAffectedpulRowsAffected
[in/out] Puntero a la memoria en la que se devuelve el recuento de filas afectadas por un comando.[in/out] A pointer to memory where the count of rows affected by a command is returned.

bBindbBind
de Especifica si se debe enlazar el comando automáticamente después de ejecutarse.[in] Specifies whether to bind the command automatically after being executed. El valor predeterminado es true , lo que hace que el comando se enlace automáticamente.The default is true, which causes the command to be bound automatically. Establecer bBind en false impide el enlace automático del comando para que pueda enlazar manualmente.Setting bBind to false prevents the automatic binding of the command so that you can bind manually. (El enlace manual es de especial interés para los usuarios de OLAP).(Manual binding is of particular interest to OLAP users.)

Valor devueltoReturn Value

HRESULT estándar.A standard HRESULT.

ComentariosRemarks

Si se ha capturado previamente un conjunto de resultados, esta función libera el conjunto de resultados anterior y desenlaza las columnas.If a result set has been previously fetched, this function releases the previous result set and unbinds the columns. Si bBind es true , enlaza las nuevas columnas.If bBind is true, it binds the new columns.

Solo debe llamar a esta función si ha especificado varios resultados estableciendo el parámetro de CCommand plantilla TMultiple = CMultipleResults .You should call this function only if you have specified multiple results by setting the CCommand template parameter TMultiple=CMultipleResults.

CCommand:: OpenCCommand::Open

Ejecuta y, de forma opcional, enlaza el comando.Executes and optionally binds the command.

SintaxisSyntax

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ámetrosParameters

sesiónsession
de Sesión en la que se va a ejecutar el comando.[in] The session in which to execute the command.

wszCommandwszCommand
de Comando que se va a ejecutar, pasado como una cadena Unicode.[in] The command to execute, passed as a Unicode string. Puede ser NULL cuando se usa CAccessor , en cuyo caso el comando se recuperará del valor pasado a la macro DEFINE_COMMAND .Can be NULL when using CAccessor, in which case the command will be retrieved from the value passed to the DEFINE_COMMAND macro. Vea ICommand:: Execute en la Referencia del programador de OLE DB para obtener más información.See ICommand::Execute in the OLE DB Programmer's Reference for details.

szCommandszCommand
de Igual que wszCommand , salvo que este parámetro toma una cadena de comando ANSI.[in] Same as wszCommand except that this parameter takes an ANSI command string. El cuarto formulario de este método puede tomar un valor NULL.The fourth form of this method can take a NULL value. Vea la sección "Comentarios" más adelante en este tema para obtener más información.See "Remarks" later in this topic for details.

pPropSetpPropSet
de Puntero a una matriz de estructuras DBPROPSET que contiene las propiedades y los valores que se van a establecer.[in] A pointer to an array of DBPROPSET structures containing properties and values to be set. Vea conjuntos de propiedades y grupos de propiedades en la Referencia del programador de OLE DB en el Windows SDK.See Property Sets and Property Groups in the OLE DB Programmer's Reference in the Windows SDK.

pRowsAffectedpRowsAffected
[in/out] Puntero a la memoria en la que se devuelve el recuento de filas afectadas por un comando.[in/out] A pointer to memory where the count of rows affected by a command is returned. Si * * PROWSAFFECTED* es null, no se devuelve ningún recuento de filas.If *pRowsAffected is NULL, no row count is returned. De lo contrario, Open establece * * pRowsAffected* según las condiciones siguientes:Otherwise, Open sets *pRowsAffected according to the following conditions:

SiIf EntoncesThen
El cParamSets elemento de pParams es mayor que 1The cParamSets element of pParams is greater than 1 * * pRowsAffected* representa el número total de filas afectadas por todos los conjuntos de parámetros especificados en la ejecución.*pRowsAffected represents the total number of rows affected by all of the parameter sets specified in the execution.
El número de filas afectadas no está disponibleThe number of affected rows is not available * * pRowsAffected* se establece en-1.*pRowsAffected is set to -1.
El comando no actualiza, elimina o inserta filasThe command does not update, delete, or insert rows * * pRowsAffected* no está definido.*pRowsAffected is undefined.

guidCommandguidCommand
de GUID que especifica la sintaxis y las reglas generales que el proveedor debe usar para analizar el texto del comando.[in] A GUID that specifies the syntax and general rules for the provider to use in parsing the command text. Consulte ICommandText:: GetCommandText y ICommandText:: SetCommandText en la Referencia del programador de OLE DB para obtener más información.See ICommandText::GetCommandText and ICommandText::SetCommandText in the OLE DB Programmer's Reference for details.

bBindbBind
de Especifica si se debe enlazar el comando automáticamente después de ejecutarse.[in] Specifies whether to bind the command automatically after being executed. El valor predeterminado es true , lo que hace que el comando se enlace automáticamente.The default is true, which causes the command to be bound automatically. Establecer bBind en false impide el enlace automático del comando para que pueda enlazar manualmente.Setting bBind to false prevents the automatic binding of the command so that you can bind manually. (El enlace manual es de especial interés para los usuarios de OLAP).(Manual binding is of particular interest to OLAP users.)

ulPropSetsulPropSets
de El número de estructuras DBPROPSET pasadas en el argumento pPropSet .[in] The number of DBPROPSET structures passed in the pPropSet argument.

Valor devueltoReturn Value

HRESULT estándar.A standard HRESULT.

ComentariosRemarks

Las tres primeras formas de Open tomar una sesión, crear un comando y ejecutar el comando, enlazando los parámetros según sea necesario.The first three forms of Open take a session, create a command, and execute the command, binding any parameters as necessary.

La primera forma de Open toma una cadena de comandos Unicode y no tiene ningún valor predeterminado.The first form of Open takes a Unicode command string and has no default value.

La segunda forma de Open toma una cadena de comandos ANSI y ningún valor predeterminado (se proporciona por compatibilidad con versiones anteriores de las aplicaciones ANSI existentes).The second form of Open takes an ANSI command string and no default value (provided for backward compatibility with existing ANSI applications).

La tercera forma de Open permite que la cadena de comando sea nula, debido al tipo int con un valor predeterminado de NULL.The third form of Open allows the command string to be NULL, because of type int with a default value of NULL. Se proporciona para llamar a Open(session, NULL); o Open(session); porque NULL es de tipo int .It is provided for calling Open(session, NULL); or Open(session); because NULL is of type int. Esta versión requiere y valida que el int parámetro sea NULL.This version requires and asserts that the int parameter be NULL.

Use el cuarto formulario de Open cuando ya haya creado un comando y desee realizar una sola preparación y varias ejecuciones.Use the fourth form of Open when you have already created a command and you want to perform a single Prepare and multiple executions.

Nota

Open llama a Execute , que a su vez llama a GetNextResult .Open calls Execute, which in turn calls GetNextResult.

CCommand:: CreateCCommand::Create

Llama a CCommand:: CreateCommand para crear un comando para la sesión especificada y, a continuación, llama a ICommandText:: SetCommandText para especificar el texto del comando.Calls CCommand::CreateCommand to create a command for the specified session, then calls ICommandText::SetCommandText to specify the command text.

SintaxisSyntax

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ámetrosParameters

sesiónsession
de Sesión en la que se va a crear el comando.[in] A session on which to create the command.

wszCommandwszCommand
de Puntero al texto Unicode de la cadena de comandos.[in] A pointer to the Unicode text of the command string.

szCommandszCommand
de Puntero al texto ANSI de la cadena de comandos.[in] A pointer to the ANSI text of the command string.

guidCommandguidCommand
de GUID que especifica la sintaxis y las reglas generales que el proveedor debe usar para analizar el texto del comando.[in] A GUID that specifies the syntax and general rules for the provider to use in parsing the command text. Para obtener una descripción de los dialectos, vea ICommandText:: GetCommandText en la Referencia del programador de OLE DB.For a description of dialects, see ICommandText::GetCommandText in the OLE DB Programmer's Reference.

Valor devueltoReturn Value

HRESULT estándar.A standard HRESULT.

ComentariosRemarks

La primera forma de Create toma una cadena de comandos Unicode.The first form of Create takes a Unicode command string. La segunda forma de Create toma una cadena de comandos ANSI (se proporciona por compatibilidad con versiones anteriores de las aplicaciones ANSI existentes).The second form of Create takes an ANSI command string (provided for backward compatibility with existing ANSI applications).

CCommand:: CreateCommandCCommand::CreateCommand

Crea un nuevo comando.Creates a new command.

SintaxisSyntax

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

ParámetrosParameters

sesiónsession
de CSession Objeto que se va a asociar al nuevo comando.[in] A CSession object to be associated with the new command.

Valor devueltoReturn Value

HRESULT estándar.A standard HRESULT.

ComentariosRemarks

Este método crea un comando mediante el objeto de sesión especificado.This method creates a command using the specified session object.

CCommand:: GetParameterInfoCCommand::GetParameterInfo

Obtiene una lista de los parámetros del comando, sus nombres y sus tipos.Gets a list of the command's parameters, their names, and their types.

SintaxisSyntax

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

ParámetrosParameters

Vea ICommandWithParameters:: GetParameterInfo en la Referencia del programador de OLE DB.See ICommandWithParameters::GetParameterInfo in the OLE DB Programmer's Reference.

Valor devueltoReturn Value

HRESULT estándar.A standard HRESULT.

CCommand::P redondearCCommand::Prepare

Valida y optimiza el comando actual.Validates and optimizes the current command.

SintaxisSyntax

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

ParámetrosParameters

cExpectedRunscExpectedRuns
de Número de veces que se espera ejecutar el comando.[in] The number of times you expect to execute the command.

Valor devueltoReturn Value

HRESULT estándar.A standard HRESULT.

ComentariosRemarks

Este método ajusta el método OLE DB ICommandPrepare::P reparet.This method wraps the OLE DB method ICommandPrepare::Prepare.

CCommand:: ReleaseCommandCCommand::ReleaseCommand

Libera el descriptor de acceso del parámetro y, a continuación, libera el propio comando.Releases the parameter accessor, then releases the command itself.

SintaxisSyntax

void CCommandBase::ReleaseCommand() throw();

ComentariosRemarks

ReleaseCommand se usa junto con Close .ReleaseCommand is used in conjunction with Close. Vea cerrar para obtener detalles de uso.See Close for usage details.

CCommand:: SetParameterInfoCCommand::SetParameterInfo

Especifica el tipo nativo de cada parámetro de comando.Specifies the native type of each command parameter.

SintaxisSyntax

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

ParámetrosParameters

Vea ICommandWithParameters:: SetParameterInfo en la Referencia del programador de OLE DB.See ICommandWithParameters::SetParameterInfo in the OLE DB Programmer's Reference.

Valor devueltoReturn Value

HRESULT estándar.A standard HRESULT.

CCommand:: UnprepareCCommand::Unprepare

Descarta el plan de ejecución de comandos actual.Discards the current command execution plan.

SintaxisSyntax

HRESULT CCommandBase::Unprepare() throw();

Valor devueltoReturn Value

HRESULT estándar.A standard HRESULT.

ComentariosRemarks

Este método ajusta el método OLE DB ICommandPrepare:: Unprepare.This method wraps the OLE DB method ICommandPrepare::Unprepare.

Consulte tambiénSee also

Plantillas de consumidor OLE DBOLE DB Consumer Templates
Referencia de plantillas de consumidor OLE DBOLE DB Consumer Templates Reference