CRecordset::Open
Ouvre le recordset en extrayant la table ou en exécutant la requête que le recordset représente.
virtual BOOL Open(
UINT nOpenType = AFX_DB_USE_DEFAULT_TYPE,
LPCTSTR lpszSQL = NULL,
DWORD dwOptions = none
);
Paramètres
nOpenType
Acceptez la valeur par défaut, AFX_DB_USE_DEFAULT_TYPE, ou utilisez une des valeurs suivantes enum OpenType:CRecordset::dynaset Un recordset avec le défilement bidirectionnel. L'appartenance et le classement des enregistrements sont déterminés lorsque le recordset est ouvert, mais les modifications des valeurs de données effectuées par d'autres utilisateurs sont visibles après une opération d'extraction. Les feuilles de réponse dynamiques sont également appelés record sets motivés par jeu de clés.
CRecordset::snapshot Un Recordset statique avec défilement bidirectionnel. L'appartenance et le classement des enregistrements sont déterminés lorsque le recordset est ouvert ; les valeurs de données sont déterminées lorsque les archivages sont récupérés. Les modifications effectuées par d'autres utilisateurs ne sont pas visibles jusqu'à ce que le recordset soit fermé puis réouvert.
CRecordset::dynamic Un recordset avec le défilement bidirectionnel. Les modifications effectuées par d'autres utilisateurs à l'appartenance, à la commande, et aux valeurs de données sont visibles après une opération d'extraction. Notez que la plupart des pilotes ODBC ne prennent pas en charge ce type de recordset.
CRecordset::forwardOnly Un recordset en lecture seule avec uniquement le défilement en avant.
Pour CRecordset, la valeur par défaut est CRecordset::snapshot. Le mécanisme par défaut permet aux Assistants Visual C++ d'interagir à la fois avec ODBC CRecordset et DAO CDaoRecordset, qui ont différentes valeurs par défaut.
Pour plus d'informations sur ces types de recordset, consultez l'article Recordset (ODBC). Pour plus d'informations, consultez l'article « Utilisation de bloc et de curseurs à défilement » dans le Kit de développement logiciel Windows.
Avertissement
Si le type demandé n'est pas pris en charge, l'infrastructure renvoie une exception.
lpszSQL
Une chaîne de curseur contenant l'un des suivants :Un pointeur NULL.
Nom d'une table.
Un relevé SQL SELECT (optionnellement avec une clause SQL WHERE et/ou ORDER BY )
Un relevé CALL spécifiant le nom d'une requête prédéfinie (procédure stockée). Assurez-vous que vous n'entrez pas d'espace blanc entre les accolades et le mot clé CALL.
Pour plus d'informations sur cette chaîne, consultez la table et la discussion du rôle ClassWizard sous les remarques.
Notes
L'ordre des colonnes dans le jeu de résultats doit correspondre à celui de RFX ou des appels de fonction RFX en bloc dans la substitution de fonction DoFieldExchange ou de DoBulkFieldExchange.
dwOptions
Un masque de bits qui peut spécifier une combinaison de valeurs listé ci-dessous. Certaines de ces dernières s'excluent mutuellement. La valeur par défaut est none.CRecordset::none Aucune option définie. Cette valeur de paramètre s'exclut mutuellement avec toutes autres valeurs. Par défaut, le recordset peut être mis à jour avec Modification ou Suppression et permet d'ajouter de nouveaux enregistrements avec ajout. L'évolutivité dépend de la source de données ainsi que de l'option nOpenType que vous spécifiez. L'optimisation pour les ajouts en bloc n'est pas disponible. L'extraction de lignes en bloc n'est pas implémentée. Les enregistrements supprimés ne seront pas ignorés pendant la navigation de recordset. Les signets sont pas disponibles. La vérification de champs erronés est implémentée.
CRecordset::appendOnly ne permet pas Edition ou Supprimer dans le recordset. Cela permet uniquement AddNew. Cette option s'exclut mutuellement avec CRecordset::readOnly.
CRecordset::readOnly Ouvrir le recordset en lecture seule. Cette option s'exclut mutuellement avec CRecordset::appendOnly.
CRecordset::optimizeBulkAdd Utilise une instruction SQL préparée pour optimiser l'ajout simultané de nombreux enregistrements. S'applique uniquement si vous n'utilisez pas la fonction API ODBC SQLSetPos pour mettre à jour le recordset. La première mise à jour détermine quels champs sont marqués comme erronés. Cette option et le CRecordset::useMultiRowFetch s'excluent mutuellement.
CRecordset::useMultiRowFetch implémente l'extraction de rangées en bloc pour autoriser l'extraction de plusieurs rangées dans une seule opération d'extraction. Cette fonctionnalité avancée est conçue pour améliorer les performances ; toutefois, le mécanisme RFX en bloc n'est pas pris en charge par l'Assistant. Cette option s'exclut mutuellement avec CRecordset::optimizeBulkAdd. Notez que si vous spécifiez CRecordset::useMultiRowFetch, l'option CRecordset::noDirtyFieldCheck sera activée automatiquement (le mécanisme de double tampon ne sera pas disponible) ; pour les recordsets en avant seulement, l'option CRecordset::useExtendedFetch sera activée automatiquement. Pour plus d'informations sur l'extraction de lignes en bloc, consultez l'article Recordset : extraction globale d'enregistrements (ODBC).
CRecordset::skipDeletedRecords Saute tous les enregistrements supprimés lors de la navigation dans le recordset. Cela entraînera un ralentissement du niveau de performance dans certaines extractions relatives. Cette option n'est pas valide pour les recordsets en avant seulement. Si vous appelez Déplacer avec le paramètre nRows égal à 0, puis l'option CRecordset::skipDeletedRecords, Déplacer confirmera. Notez que CRecordset::skipDeletedRecords est similaire à la compression de pilote, ce qui signifie que des rangées supprimées seront supprimées du recordset. Toutefois, si votre pilote comprime des enregistrements, il ne sautera que les enregistrements que vous supprimez ; il n'ignorera pas les enregistrements supprimés par d'autres utilisateurs pendant que le recordset est ouvert. CRecordset::skipDeletedRecords ignorera les rangées supprimées par d'autres utilisateurs.
CRecordset::useBookmarks Peut insérer un signet dans le recordset si cette fonctionnalité est prise en charge. Les signets ralentissent l'extraction de données mais améliore les performances pour la navigation de données. Non valide pour les recordsets en avant seulement. Pour plus d'informations, consultez l'article Recordset : extraction globale d'enregistrements (ODBC).
CRecordset::noDirtyFieldCheck Désactive la recherche automatique de champs erronés (mécanisme de double tampon). Cela améliore les performances ; toutefois, vous devez manuellement marquer des champs comme erronés en appelant les fonctions membres de SetFieldDirty et SetFieldNull . Remarquez que le mécanisme de double tampon dans la classe CRecordset est semblable au mécanisme de double tampon dans la classe CDaoRecordset. Toutefois, dans CRecordset, vous ne pouvez pas activer le mécanisme de double tampon sur différents champs ; vous pouvez soit l'activer pour tous les champs ou bien la désactiver pour tous les champs. Notez que si vous spécifiez l'option CRecordset::useMultiRowFetch, CRecordset::noDirtyFieldCheck est activé automatiquement ; Toutefois, SetFieldDirty et SetFieldNull ne peuvent pas être utilisés sur des recordsets implémentant l'extraction de lignes en bloc.
CRecordset::executeDirect N'utilise pas d'instruction SQL préparée. Pour de meilleures performances, spécifiez cette option si la fonction membre Ré exécuter la requête ne sera jamais appelée.
CRecordset::useExtendedFetch implémente SQLExtendedFetch au lieu de SQLFetch. Cela est conçu pour implémenter l'extraction de rangées en bloc sur les recordsets en avant seulement. Si vous spécifiez l'option CRecordset::useMultiRowFetch sur un recordset en avant seulement, CRecordset::useExtendedFetch sera activée automatiquement.
CRecordset::userAllocMultiRowBuffers L'utilisateur allouera des mémoires tampons pour les données stockées. Utilisez cette option en collaboration avec CRecordset::useMultiRowFetch si vous souhaitez allouer votre propre stockage ; sinon, l'infrastructure allouera automatiquement le stockage nécessaire. Pour plus d'informations, consultez l'article Recordset : extraction globale d'enregistrements (ODBC). Notez que spécifier CRecordset::userAllocMultiRowBuffers sans spécifier CRecordset::useMultiRowFetch provoquera un échec dans l'assertion.
Valeur de retour
Une valeur différente de zéro si l'objet CRecordset a été correctement ouverte ; sinon 0 CDatabase::Open (si appelé) retourne 0.
Notes
Vous devez appeler cette fonction membre pour exécuter la requête définie par le recordset. Avant d'appeler Ouvrir, vous devez construire l'objet recordset.
La connexion de ce recordset vers la source de données dépend de la manière dont vous construisez le recordset avant d'appeler Ouvrir. Si vous passez un objet de CDatabase au constructeur de recordset qui n'a pas été connecté à la source de données, cette fonction membre utilise GetDefaultConnect pour essayer d'ouvrir l'objet de base de données. Si vous passez NULL au constructeur de recordset, le constructeur crée un objet CDatabase pour vous, et Ouvrir tente de connecter l'objet de la base de données. Pour plus d'informations sur la fermeture du recordset et la connexion dans ces circonstances variantes, consultez Fermer.
Notes
L'accès à une source de données via un objet CRecordset est toujours partagé.Contrairement à la classe CDaoRecordset, vous ne pouvez pas utiliser un objet CRecordset pour ouvrir une source de données avec accès exclusif.
Lorsque vous appelez Ouvrir, une requête, habituellement une instruction SQL SELECT, sélectionne des enregistrements en fonction de critères présentés dans le tableau suivant.
Valeur du paramètre lpszSQL. |
Les enregistrements sélectionnés sont déterminés par |
Exemple |
|---|---|---|
NULL |
La chaîne retournée par GetDefaultSQL. |
|
Nom de la table SQL |
Toutes les colonnes du tableau dans DoFieldExchange ou DoBulkFieldExchange. |
"Customer" |
Nom de requête prédéfinie (procédure stockée) |
Les colonnes que la requête doit retourner. |
"{call OverDueAccts}" |
CHOISIR une liste de colonne DE une liste de tableau |
Les colonnes spécifiées depuis une/des table(s) spécifiée(s). |
"SELECT CustId, CustName FROM Customer" |
Avertissement
Assurez-vous que vous n'entrez pas d'espace blanc supplémentaire dans la chaîne SQL.Par exemple, si vous insérez un espace blanc entre les accolades et le mot clé CALL, MFC interprétera par erreur la chaîne SQL comme nom de la table et l'incorporera dans une instruction SELECT, ce qui provoquera l'apparition d'une exception.De même, si votre requête prédéfinie utilise un paramètre de sortie, n'insérez pas d'espace blanc entre les accolades et le symbole « ? » .Enfin, vous ne devez pas insérer un espace blanc avant l'accolade dans une instruction CALL ou avant le mot clé SELECT dans une instruction SELECT.
La procédure habituelle consiste à passer NULL pour Ouvrir; Dans ce cas, GetDefaultSQLappelle Ouvrir. Si vous utilisez une classe CRecordset dérivée, GetDefaultSQL indique le nom de la table que vous avez spécifiés dans l'Assistant. Vous pouvez aussi spécifier d'autres informations dans les paramètres lpszSQL.
Quoi que vous passiez, Ouvrir construit une chaîne finale SQL pour la requête (la chaîne peut avoir des clauses SQL WHERE et ORDER BY ajoutées à la chaîne lpszSQL que vous avez passé) puis exécute la requête. Examinez la chaîne construite en appelant GetSQL après l'appel Ouvrir. Pour des informations supplémentaires sur la façon dont le recordset construit une instruction SQL et sélectionne des enregistrements, consultez l'article Recordset : Comment les recordsets sélectionnent les enregistrements (ODBC).
Les champs de données membres de votre classe de recordset sont liées aux colonnes de données sélectionnées. Si des enregistrements sont retournés, le premier enregistrement devient l'enregistrement courant.
Si vous souhaitez définir des options du recordset, tel qu'un filtre ou un tri, spécifiez ces derniers après avoir construit l'objet recordset mais avant d'appeler Ouvrir. Si vous souhaitez actualiser les enregistrements du recordset après que le recordset est déjà ouvert, appelez Actualiser.
Pour plus d'informations, y compris des exemples supplémentaires, consultez les articles Recordset (ODBC), Recordset : Comment les recordsets sélectionnent les enregistrements (ODBC), et Recordset : Création et fermeture de recordsets (ODBC).
Exceptions
Cette méthode peut retourner des exceptions de type CDBException* et CMemoryException*.
Exemple
Les exemples de code suivants montrent différentes formes de l'appel de Ouvrir.
// rsSnap, rsLName, and rsDefault are CRecordset or CRecordset-derived
// objects
// Open rs using the default SQL statement, implement bookmarks, and turn
// off automatic dirty field checking
rsSnap.Open(CRecordset::snapshot, NULL, CRecordset::useBookmarks |
CRecordset::noDirtyFieldCheck);
// Pass a complete SELECT statement and open as a dynaset
rsLName.Open(CRecordset::dynaset, _T("Select L_Name from Customer"));
// Accept all defaults
rsDefault.Open();
Configuration requise
En-tête: afxdb.h