CCommand, classe
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
Members (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 | Dis carte 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
Dis carte 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
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour