`db_command`

Article
10/12/2023

Crée une commande OLE DB.

Syntaxe

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

Paramètres

command
Chaîne de commande contenant le texte d’une commande OLE DB. Voici un exemple simple :

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

La command syntaxe est la suivante :

bloc de paramètres de liaison 1
Commande OLE DB
bloc de paramètres de liaison 2
continuation de la commande OLE DB
bloc de paramètres de liaison 3
...

Un bloc de paramètres de liaison est défini comme suit :

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

où :

( marque le début du bloc de liaison de données.
bindtype est l’une des chaînes non sensibles à la casse suivantes :
- [db_column] lie chacune des variables membres à une colonne d’un ensemble de lignes.
- [bindto] (identique à [db_column]).
- [in] lie des variables membres en tant que paramètres d’entrée.
- [out] lie des variables membres en tant que paramètres de sortie.
- [in,out] lie des variables membres en tant que paramètres d’entrée/sortie.
szVarN, nVarN est résolu en variables membres dans l’étendue actuelle.
) marque la fin du bloc de liaison de données.

Si la chaîne de commande contient un ou plusieurs spécificateurs tels que [in], [out]ou [in/out], db_command génère un mappage de paramètres.

Si la chaîne de commande contient un ou plusieurs paramètres tels que [db_column] ou [bindto], génère db_command à la fois un ensemble de lignes et un mappage d’accesseur pour traiter ces variables liées. Pour plus d’informations, consultez db_accessor.

Remarque

bindtype la syntaxe et le bindings paramètre ne sont pas valides lors de l’utilisation db_command au niveau de la classe.

Voici quelques exemples de blocs de paramètres de liaison. L’exemple suivant lie les m_au_fname membres et m_au_lname les membres de données aux colonnes et au_lname aux au_fname colonnes, respectivement, de la table auteurs dans la pubs base de données :

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
(Facultatif) Nom du handle que vous utilisez pour utiliser l’ensemble de lignes. Si vous spécifiez name, db_command génère une classe avec la classe spécifiée name, qui peut être utilisée pour parcourir l’ensemble de lignes ou pour exécuter plusieurs requêtes d’action. Si vous ne spécifiez namepas, il n’est pas possible de renvoyer plusieurs lignes de résultats à l’utilisateur.

source_name
(Facultatif) Variable CSession ou instance d’une classe qui a l’attribut db_source appliqué à celle-ci sur laquelle la commande s’exécute. Consultez l’article db_source.

db_command vérifie que la variable utilisée pour source_name est valide, de sorte que la variable spécifiée doit être dans la fonction ou l’étendue globale.

hresult
(Facultatif) Identifie la variable qui recevra hrESULT de cette commande de base de données. Si la variable n’existe pas, elle est automatiquement injectée par l’attribut.

bindings
(Facultatif) Vous permet de séparer les paramètres de liaison de la commande OLE DB.

Si vous spécifiez une valeur pour bindings, db_command analyse la valeur associée et n’analyse pas le bindtype paramètre. Cette utilisation vous permet d’utiliser la syntaxe du fournisseur OLE DB. Pour désactiver l’analyse sans paramètres de liaison, spécifiez Bindings="".

Si vous ne spécifiez pas de valeur pour bindings, db_command analyse le bloc de paramètres de liaison. Il recherche «( », suivi d’un bindtype crochet, suivi d’une ou de plusieurs variables membres C++ précédemment déclarées, suivies de «) ». Il supprime tout le texte entre les parenthèses de la commande résultante. Ces paramètres sont utilisés pour construire des liaisons de colonnes et de paramètres pour cette commande.

bulk_fetch
(Facultatif) Valeur entière qui spécifie le nombre de lignes à extraire.

La valeur par défaut est 1, qui spécifie l’extraction de lignes unique (l’ensemble de lignes sera de type CRowset).

Une valeur supérieure à 1 spécifie l’extraction de lignes en bloc. L’extraction de lignes en bloc fait référence à la capacité des ensembles de lignes en bloc à extraire plusieurs handles de ligne (l’ensemble de lignes sera de type CBulkRowset et appellera SetRows avec le nombre spécifié de lignes).

Si bulk_fetch elle est inférieure à une, SetRows retourne zéro.

Notes

db_command crée un CCommand objet, qui est utilisé par un consommateur OLE DB pour exécuter une commande.

Vous pouvez utiliser db_command avec une étendue de classe ou de fonction ; la principale différence est l’étendue de l’objet CCommand . Avec la portée de fonction, les données telles que les liaisons se terminent à la fin de la fonction. Les utilisations de classe et d’étendue de fonction impliquent la classe CCommand<>OLE DB Consumer Template, mais les arguments de modèle diffèrent pour les cas de fonction et de classe. Dans le cas de la fonction, les liaisons sont apportées à une Accessor variable locale, tandis que l’utilisation de la classe déduit une CAccessorclasse dérivée comme argument. Lorsqu’il est utilisé en tant qu’attribut de classe, db_command fonctionne avec db_column.

db_command peut être utilisé pour exécuter des commandes qui ne retournent pas un jeu de résultats.

Lorsque le fournisseur d’attributs consommateur applique cet attribut à une classe, le compilateur renomme la classe _[YourClassName]Accessoren , où [YourClassName] est le nom que vous avez donné à la classe. Le compilateur crée également une classe appelée [YourClassName], qui dérive de _[YourClassName]Accessor. En mode Classe, vous verrez les deux classes.

Exemples

Cet exemple définit une commande qui sélectionne le prénom et le nom dans une table où la colonne d’état correspond à « CA ». db_command crée et lit un ensemble de lignes sur lequel vous pouvez appeler des fonctions générées par l’Assistant, telles que OpenAll et CloseAll, ainsi que des fonctions membres telles que CRowset MoveNext.

Ce code vous oblige à fournir votre propre chaîne de connexion qui se connecte à la pubs base de données. Pour plus d’informations sur la façon de fournir un chaîne de connexion dans l’environnement de développement, consultez Comment : se connecter à une base de données et parcourir les objets existants et ajouter de nouvelles connexions.

Fichier source 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);
   }
};

Fichier source 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();
}

Cet exemple utilise db_source sur une classe de source de données CMySource, et db_command sur les classes de commande CCommand1 et 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();
}

Spécifications

Contexte d’attribut	Valeur
S’applique à	`class`, membre `struct`, méthode, local
Renouvelable	Non
Attributs requis	Aucune
Attributs non valides	Aucune

Pour plus d’informations sur les contextes d’attribut, consultez Contextes d’attribut.

Voir aussi

Attributs du consommateur OLE DB
Attributs autonomes

Partager via