Partager via

CCommand, classe

  • Article

Fournit des méthodes pour définir et exécuter une commande.

Syntaxe

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

Paramètres

TAccessor
Type de classe d’accesseur (par CDynamicParameterAccessorexemple, ou CEnumeratorAccessorCDynamicStringAccessor) que vous souhaitez utiliser la commande. La valeur par défaut est CNoAccessor, qui spécifie que la classe ne prend pas en charge les paramètres ou les colonnes de sortie.

TRowset
Type de classe d’ensemble de lignes (par exemple CArrayRowset , ou CNoRowset) que vous souhaitez utiliser la commande. Par défaut, il s’agit de CRowset.

TMultiple
Pour utiliser une commande OLE DB qui peut retourner plusieurs résultats, spécifiez CMultipleResults. Sinon, utilisez CNoMultipleResults. Pour plus d’informations, consultez IMultipleResults.

Spécifications

En-tête : atldbcli.h

Membres

Méthodes

Nom Description
Close Ferme la commande active.
GetNextResult Récupère le résultat suivant lors de l’utilisation de plusieurs jeux de résultats.
Ouvrir Exécute et lie éventuellement la commande.

Méthodes héritées

Nom Description
Créer Crée une commande pour la session spécifiée, puis définit le texte de la commande.
CreateCommand Crée une commande.
GetParameterInfo Obtient une liste des paramètres de la commande, de leurs noms et de leurs types.
Préparer Valide et optimise la commande actuelle.
ReleaseCommand Libère l’accesseur de paramètre si nécessaire, puis libère la commande.
SetParameterInfo Spécifie le type natif de chaque paramètre de commande.
Annuler la préparation Ignore le plan d’exécution de commande actuel.

Notes

Utilisez cette classe lorsque vous devez effectuer une opération basée sur des paramètres ou exécuter une commande. Si vous avez simplement besoin d’ouvrir un ensemble de lignes simple, utilisez plutôt CTable .

La classe d’accesseur que vous utilisez détermine la méthode de liaison des paramètres et des données.

Notez que vous ne pouvez pas utiliser de procédures stockées avec le fournisseur OLE DB pour Jet, car ce fournisseur ne prend pas en charge les procédures stockées (seules les constantes sont autorisées dans les chaînes de requête).

CCommand::Close

Libère l’ensemble de lignes d’accesseur associé à la commande.

Syntaxe

void Close();

Notes

Une commande utilise un ensemble de lignes, un accesseur de jeu de résultats et (éventuellement) un accesseur de paramètre (contrairement aux tables, qui ne prennent pas en charge les paramètres et n’ont pas besoin d’un accesseur de paramètres).

Lorsque vous exécutez une commande, vous devez appeler à la fois Close et ReleaseCommand après la commande.

Lorsque vous souhaitez exécuter la même commande à plusieurs reprises, vous devez libérer chaque accesseur du jeu de résultats en appelant Close avant d’appeler Execute. À la fin de la série, vous devez libérer l’accesseur de paramètre en appelant ReleaseCommand. Un autre scénario courant consiste à appeler une procédure stockée qui a des paramètres de sortie. Sur de nombreux fournisseurs (tels que le fournisseur OLE DB pour SQL Server), les valeurs des paramètres de sortie ne seront pas accessibles tant que vous ne fermez pas l’accesseur du jeu de résultats. Appelez Close pour fermer l’ensemble de lignes retourné et l’accesseur du jeu de résultats, mais pas l’accesseur de paramètre, ce qui vous permet de récupérer les valeurs des paramètres de sortie.

Exemple

L’exemple suivant montre comment vous pouvez appeler Close et ReleaseCommand lorsque vous exécutez la même commande plusieurs fois.

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

Récupère le jeu de résultats suivant si l’un d’eux est disponible.

Syntaxe

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

Paramètres

pulRowsAffected
[in/out] Pointeur vers la mémoire où le nombre de lignes affectées par une commande est retourné.

bBind
[in] Spécifie s’il faut lier automatiquement la commande après l’exécution. La valeur par défaut est true, ce qui entraîne la liaison automatique de la commande. Définition de bBind pour false empêcher la liaison automatique de la commande afin que vous puissiez lier manuellement. (La liaison manuelle est particulièrement intéressante pour les utilisateurs OLAP.)

Valeur de retour

HRESULT standard.

Notes

Si un jeu de résultats a été extrait précédemment, cette fonction libère le jeu de résultats précédent et annule la liaison des colonnes. Si bBind est true, il lie les nouvelles colonnes.

Vous devez appeler cette fonction uniquement si vous avez spécifié plusieurs résultats en définissant le CCommand paramètre de modèle TMultiple=CMultipleResults.

CCommand::Open

Exécute et lie éventuellement la commande.

Syntaxe

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();

Paramètres

Session
[in] Session dans laquelle exécuter la commande.

wszCommand
[in] Commande à exécuter, passée en tant que chaîne Unicode. Peut être NULL lors de l’utilisation CAccessor, auquel cas la commande est récupérée à partir de la valeur passée à la macro DEFINE_COMMAND . Pour plus d’informations, consultez ICommand ::Execute dans la référence du programmeur OLE DB.

szCommand
[in] Identique à wszCommand , sauf que ce paramètre prend une chaîne de commande ANSI. La quatrième forme de cette méthode peut prendre une valeur NULL. Pour plus d’informations, consultez « Remarques » plus loin dans cette rubrique.

pPropSet
[in] Pointeur vers un tableau de structures DBPROPSET contenant des propriétés et des valeurs à définir. Consultez Les ensembles de propriétés et les groupes de propriétés dans la référence du programmeur OLE DB dans le Kit de développement logiciel (SDK) Windows.

pRowsAffected
[in/out] Pointeur vers la mémoire où le nombre de lignes affectées par une commande est retourné. Si *pRowsAffected a la valeur NULL, aucun nombre de lignes n’est retourné. Sinon, Open définit *pRowsAffected en fonction des conditions suivantes :

Si Alors
L’élément cParamSets de pParams est supérieur à 1 *pRowsAffected représente le nombre total de lignes affectées par tous les jeux de paramètres spécifiés dans l’exécution.
Le nombre de lignes affectées n’est pas disponible *pRowsAffected est défini sur -1.
La commande ne met pas à jour, supprime ou insère des lignes *pRowsAffected n’est pas défini.

guidCommand
[in] GUID qui spécifie la syntaxe et les règles générales du fournisseur à utiliser pour analyser le texte de la commande. Pour plus d’informations, voir ICommandText ::GetCommandText et ICommandText ::SetCommandText dans la référence du programmeur OLE DB.

bBind
[in] Spécifie s’il faut lier automatiquement la commande après l’exécution. La valeur par défaut est true, ce qui entraîne la liaison automatique de la commande. Définition de bBind pour false empêcher la liaison automatique de la commande afin que vous puissiez lier manuellement. (La liaison manuelle est particulièrement intéressante pour les utilisateurs OLAP.)

ulPropSets
[in] Nombre de structures DBPROPSET passées dans l’argument pPropSet .

Valeur de retour

HRESULT standard.

Notes

Les trois premières formes de prise de Open session, de création d’une commande et d’exécution de la commande, lient tous les paramètres si nécessaire.

La première forme de prend une chaîne de Open commande Unicode et n’a aucune valeur par défaut.

La deuxième forme de commande prend une chaîne de Open commande ANSI et aucune valeur par défaut (fournie pour la compatibilité descendante avec les applications ANSI existantes).

Le troisième formulaire permet à la chaîne de Open commande d’être NULL, en raison d’un type int avec une valeur par défaut null. Il est fourni pour appeler Open(session, NULL); ou Open(session); parce que NULL est de type int. Cette version nécessite et affirme que le paramètre a la int valeur NULL.

Utilisez la quatrième forme du moment où Open vous avez déjà créé une commande et que vous souhaitez effectuer une seule préparation et plusieurs exécutions.

Remarque

Open appels Execute, qui appellent GetNextResultà leur tour .

CCommand::Create

Appelle CCommand ::CreateCommand pour créer une commande pour la session spécifiée, puis appelle ICommandText ::SetCommandText pour spécifier le texte de la commande.

Syntaxe

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 ();

Paramètres

Session
[in] Session sur laquelle créer la commande.

wszCommand
[in] Pointeur vers le texte Unicode de la chaîne de commande.

szCommand
[in] Pointeur vers le texte ANSI de la chaîne de commande.

guidCommand
[in] GUID qui spécifie la syntaxe et les règles générales du fournisseur à utiliser pour analyser le texte de la commande. Pour obtenir une description des dialectes, consultez ICommandText ::GetCommandText dans la référence du programmeur OLE DB.

Valeur de retour

HRESULT standard.

Notes

La première forme de commande prend une chaîne de Create commande Unicode. La deuxième forme de commande prend une chaîne de Create commande ANSI (fournie pour la compatibilité descendante avec les applications ANSI existantes).

CCommand::CreateCommand

Crée une commande.

Syntaxe

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

Paramètres

Session
[in] Objet CSession à associer à la nouvelle commande.

Valeur de retour

HRESULT standard.

Notes

Cette méthode crée une commande à l’aide de l’objet de session spécifié.

CCommand::GetParameterInfo

Obtient une liste des paramètres de la commande, de leurs noms et de leurs types.

Syntaxe

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

Paramètres

Consultez ICommandWithParameters ::GetParameterInfo dans la référence du programmeur OLE DB.

Valeur de retour

HRESULT standard.

CCommand::Prepare

Valide et optimise la commande actuelle.

Syntaxe

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

Paramètres

cExpectedRuns
[in] Nombre de fois que vous prévoyez d’exécuter la commande.

Valeur de retour

HRESULT standard.

Notes

Cette méthode encapsule la méthode OLE DB ICommandPrepare ::P repare.

CCommand::ReleaseCommand

Libère l’accesseur de paramètre, puis libère la commande elle-même.

Syntaxe

void CCommandBase::ReleaseCommand() throw();

Notes

ReleaseCommand est utilisé conjointement avec Close. Pour plus d’informations sur l’utilisation, consultez Fermer .

CCommand::SetParameterInfo

Spécifie le type natif de chaque paramètre de commande.

Syntaxe

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

Paramètres

Consultez ICommandWithParameters ::SetParameterInfo dans la référence du programmeur OLE DB.

Valeur de retour

HRESULT standard.

CCommand::Unprepare

Ignore le plan d’exécution de commande actuel.

Syntaxe

HRESULT CCommandBase::Unprepare() throw();

Valeur de retour

HRESULT standard.

Notes

Cette méthode encapsule la méthode OLE DB ICommandPrepare ::Unprepare.

Voir aussi

Modèles du consommateur OLE DB
Référence des modèles du consommateur OLE DB