`db_command`

Artículo
06/16/2023

Crea un comando OLE DB.

Sintaxis

[ db_command(command, name, source_name, hresult, bindings, bulk_fetch) ]

Parámetros

command
Cadena de comandos que contiene el texto de un comando OLE DB. Veamos un ejemplo sencillo:

[ db_command ( command = "Select * from Products" ) ]

La sintaxis de command es la siguiente:

bloque 1 de parámetro de enlace
Comando de OLE DB
bloque 2 de parámetro de enlace
continuación del Comando de OLE DB
bloque 3 de parámetro de enlace
...

Se define un bloque de parámetros de enlace del siguiente modo:

(bindtype szVar1 [, szVar2 [, nVar3 [, ...]]])

donde:

( marca el inicio del bloque de enlace de datos.
bindtype es una de las siguientes cadenas que no distinguen mayúsculas de minúsculas:
- [db_column] enlaza todas las variables de miembro con una columna en un conjunto de filas.
- [bindto] (igual que [db_column]).
- [in] enlaza variables de miembro como parámetros de entrada.
- [out] enlaza variables de miembro como parámetros de salida.
- [in,out] enlaza variables de miembro como parámetros de entrada/salida.
szVarN, nVarN se resuelven en variables miembro dentro del ámbito actual.
) marca el final del bloque de enlace de datos.

Si la cadena de comando contiene uno o varios especificadores, como [in], [out] o [in/out], db_command compila una asignación de parámetros.

Si la cadena de comandos contiene uno o varios parámetros como [db_column] o [bindto], db_command genera un conjunto de filas y una asignación de descriptor de acceso para dar servicio a estas variables enlazadas. Para obtener más información, vea db_accessor.

Nota:

La sintaxis bindtype y el parámetro bindings no son válidos cuando se usa db_command en el nivel de clase.

A continuación se muestran algunos ejemplos de bloques de parámetros de enlace. En el siguiente ejemplo se enlazan los miembros de datos m_au_fname y m_au_lname con las columnas au_fname y au_lname, respectivamente, de la tabla authors de la base de datos pubs:

TCHAR m_au_fname[21];
TCHAR m_au_lname[41];
TCHAR m_state[3] = 'CA';

[db_command (command = "SELECT au_fname([bindto]m_au_fname), au_lname([bindto]m_au_lname) " \
   "FROM dbo.authors " \
   "WHERE state = ?([in]m_state)")
]

name
(Opcional) Nombre del identificador usado para trabajar con el conjunto de filas. Si especifica name, db_command genera una clase con el name especificado, que se puede usar para recorrer el conjunto de filas o para ejecutar varias consultas de acción. Si no especifica name, no se podrá devolver al usuario más de una fila de resultados.

source_name
(Opcional) Variable o instancia CSession de una clase que tiene aplicado el atributo db_source, en el que se ejecuta el comando. Vea db_source.

db_command se asegura de que la variable usada para source_name sea válida, por lo que la variable especificada debe estar en el ámbito global o de función.

hresult
(Opcional) Identifica la variable que recibirá el HRESULT de este comando de base de datos. Si la variable no existe, el atributo la insertará de forma automática.

bindings
(Opcional) Le permite separar los parámetros de enlace del Comando de OLE DB.

Si especifica un valor para bindings, db_command analiza el valor asociado y no analiza el parámetro bindtype. De este modo, puede usar la sintaxis del proveedor OLE DB. Para deshabilitar el análisis sin enlazar parámetros, especifique Bindings="".

Si no especifica un valor para bindings, db_commandanaliza el bloque de parámetros de enlace. Busca '(', seguido de un parámetro bindtype entre corchetes, seguido de una o varias variables miembro C++ declaradas previamente, seguido de ')'. Quita todo el texto entre paréntesis del comando resultante. Estos parámetros se usan para construir enlaces de columnas y parámetros para este comando.

bulk_fetch
(Opcional) Valor entero que especifica el número de filas que se capturará.

El valor predeterminado es 1, que especifica que se obtendrá una única fila (el conjunto de filas será del tipo CRowset).

Un valor superior a 1 especifica una obtención de filas masiva. La captura masiva de filas hace referencia a la capacidad de los conjuntos de filas masivos de capturar varios identificadores de fila (el conjunto de filas será del tipo CBulkRowset y llamará a SetRows con el número de filas especificado).

Si bulk_fetch es menor que uno, SetRows devolverá cero.

Comentarios

db_command crea un objeto CCommand, que usa un consumidor OLE DB para ejecutar un comando.

Puede usar db_command con cualquier ámbito de función o clase; la principal diferencia radica en el ámbito del objeto CCommand. Con el ámbito de función, los datos tales como los enlaces concluyen al final de la función. El uso de los ámbitos de clase y de función involucra a la clase de plantilla de consumidor OLE DB CCommand<>, aunque los argumentos de la plantilla difieren en los casos de la función y la clase. En el caso de la función, los enlaces se efectuarán con un descriptor de acceso Accessor formado por variables locales, mientras que el uso de la clase deducirá una clase derivada de CAccessor como argumento. Cuando se usa como atributo de clase, db_command funciona junto con db_column.

db_command se puede usar para ejecutar comandos que no devuelven un conjunto de resultados.

Cuando el proveedor de atributos de consumidor aplica este atributo a una clase, el compilador cambia el nombre de la clase a _[YourClassName]Accessor, donde [YourClassName] es el nombre que agregó a la clase. El compilador también crea una clase denominada [YourClassName], que se deriva de _[YourClassName]Accessor. En Vista de clases verá ambas clases.

Ejemplos

En este ejemplo se define un comando que selecciona los nombres y apellidos de una tabla en la que la columna state coincide con “CA”. db_command crea y lee un conjunto de filas en el que puede llamar a funciones generadas por el asistente, como OpenAll y CloseAll, así como funciones miembro CRowset, como MoveNext.

En este código debe proporcionar su propia cadena de conexión que se conecte a la base de datos pubs. Para obtener información sobre cómo proporcionar una cadena de conexión en el entorno de desarrollo, vea Procedimientos: Conectar con una base de datos y examinar objetos existentes y Adición de nuevas conexiones.

Archivo de origen db_command.h:

// db_command.h
#include <atlbase.h>
#include <atlplus.h>
#include <atldbcli.h>

#pragma once

[  db_source(L"your connection string"), db_command(L" \
      SELECT au_lname, au_fname \
      FROM dbo.authors \
      WHERE state = 'CA'")  ]

struct CAuthors {
   // In order to fix several issues with some providers, the code below may bind
   // columns in a different order than reported by the provider

   DBSTATUS m_dwau_lnameStatus;
   DBSTATUS m_dwau_fnameStatus;
   DBLENGTH m_dwau_lnameLength;
   DBLENGTH m_dwau_fnameLength;

   [ db_column("au_lname", status="m_dwau_lnameStatus", length="m_dwau_lnameLength") ] TCHAR m_au_lname[41];
   [ db_column("au_fname", status="m_dwau_fnameStatus", length="m_dwau_fnameLength") ] TCHAR m_au_fname[21];

   [ db_param("7", paramtype="DBPARAMIO_INPUT") ] TCHAR m_state[3];

   void GetRowsetProperties(CDBPropSet* pPropSet) {
      pPropSet->AddProperty(DBPROP_CANFETCHBACKWARDS, true, DBPROPOPTIONS_OPTIONAL);
      pPropSet->AddProperty(DBPROP_CANSCROLLBACKWARDS, true, DBPROPOPTIONS_OPTIONAL);
   }
};

Archivo de origen db_command.cpp:

// db_command.cpp
// compile with: /c
#include "db_command.h"

int main(int argc, _TCHAR* argv[]) {
   HRESULT hr = CoInitialize(NULL);

   // Instantiate rowset
   CAuthors rs;

   // Open rowset and move to first row
   strcpy_s(rs.m_state, sizeof(rs.m_state), _T("CA"));
   hr = rs.OpenAll();
   hr = rs.MoveFirst();

   // Iterate through the rowset
   while( SUCCEEDED(hr) && hr != DB_S_ENDOFROWSET ) {
      // Print out the column information for each row
      printf("First Name: %s, Last Name: %s\n", rs.m_au_fname, rs.m_au_lname);
      hr = rs.MoveNext();
   }

   rs.CloseAll();
   CoUninitialize();
}

En este ejemplo se usa db_source en la clase de origen de datos CMySourcey db_command en las clases de comandos CCommand1 y CCommand2.

// db_command_2.cpp
// compile with: /c
#include <atlbase.h>
#include <atlplus.h>
#include <atldbcli.h>
// class usage for both db_source and db_command

[  db_source(L"your connection string"), db_command(L" \
      SELECT au_lname, au_fname \
      FROM dbo.authors \
      WHERE state = 'CA'")  ]
struct CMySource {
   HRESULT OpenDataSource() {
      return S_OK;
   }
};

[db_command(command = "SELECT * FROM Products")]
class CCommand1 {};

[db_command(command = "SELECT FNAME, LNAME FROM Customers")]
class CCommand2 {};

int main() {
   CMySource s;
   HRESULT hr = s.OpenDataSource();
   if (SUCCEEDED(hr)) {
      CCommand1 c1;
      hr = c1.Open(s);

      CCommand2 c2;
      hr = c2.Open(s);
   }

   s.CloseDataSource();
}

Requisitos

Contexto de atributo	Valor
Se aplica a	`class`, `struct`, miembro, método, local
Reiterativo	No
Atributos requeridos	Ninguno
Atributos no válidos	Ninguno

Para más información sobre los atributos de contexto, consulte Atributos de contexto.

Consulte también

Atributos de consumidor OLE DB
Atributos independientes

Compartir a través de

`db_command`

Sintaxis

Parámetros

Comentarios

Ejemplos

Requisitos

Consulte también

Comentarios

Recursos adicionales