Comprendre les Recordset ADO

Renvoie ou définit la position de l'enregistrement courant dans le Recordset. Toujours disponible avec les curseurs non en avant seulement.

Permet d'utiliser des signets pour marquer les enregistrements. Toujours disponible avec les curseurs non en avant seulement.

Renvoie ou définit le nombre d'enregistrements qui vont être stockée dans le cache.

Indique le statut de modification de l'enregistrement en cours.

Peut prendre les valeurs adEditNone, adEditInProgress, adEditAdd, adEditDelete

Très utile pour savoir si des actions sont en cours sur le recordset, ce qui permet le cas échéant d'annuler ou de valider ces modifications.

Permet de filtrer les enregistrements d'un recordset selon les critères spécifiés. Le Recordset filtré se comporte comme un nouvel objet recordset. En général cette propriété ne s'utilise pas sur les recordset côté serveur, car elle tend à faire s'effondrer les performances. Par contre on l'utilise beaucoup lors des traitements par lot des curseurs clients. Le filtre peut être de deux sortes :

Filtre SQL : il s'utilise comme une clause WHERE sans le WHERE.

Une des valeurs prédéfinies

Définit l'index en cours dans le recordset. Uniquement utilisé avec la méthode Seek.

Définit le mode de mise à jour lors de la reconnexion d'un recordset déconnecté. Peut prendre les valeurs

AdMarshalAll, adMarshalModifiedOnly.

Permet de définir un nombre maximum d'enregistrements que la requête peut renvoyer.

Renvoie le nombre d'enregistrements disponible dans le recordset. Toujours disponible avec les curseurs qui ne sont pas de type « en avant seulement ».

S'utilise avec une chaîne contenant le(s) nom(s) de(s) champ(s) suivi de ASC ou DESC, chaque champ étant séparé par une virgule. Préférez toujours un tri par le SQL qui est beaucoup plus performant sur les recordset côté serveur.

Renvoie la source des données d'un recordset. Lorsqu'il s'agit d'un objet Command, renvoie la propriété CommandText de celui-ci.

Renvoie toujours l'état du recordset (fermé / ouvert). Dans le cas d'une connection asynchrone peut prendre les valeurs adStateConnecting, adStateExecuting, adStateFetching. Presque uniquement utilisé dans les cas asynchrones

Cette propriété est très importante, nous la reverrons d'ailleurs plus loin dans cet article. Elle indique l'état de l'enregistrement en cours lors d'une opération globale (ex. : mise à jour par lot). Peut prendre une ou plusieurs des valeurs suivantes :

Dans le cas d'un traitement par lot il est indispensable d'aller lire cette propriété pour les enregistrements n'ayant pu être mis à jour.

Permet d'implémenter l'interface Rowset OLEDB sur les curseurs serveurs. Certains contrôles ont besoin de cette interface pour afficher les données. Attends une valeur booléenne.

Exemple d'utilisation

Permet de créer un index sur un champ (objet Field) d'un recordset côté client. Cet index n'existe que dans le jeu d'enregistrements, mais n'est pas créé dans la base de données sous-jacente. L'ajout d'un index peut permettre un accroissement important des performances sur l'utilisation des recherches ou des filtres. Dans l'exemple suivant, j'ajoute un index au champ « Author » avant d'exécuter le filtre :

Set Cnn1 = New ADODB.Connection
Cnn1.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=d:\biblio.mdb ;User Id=Admin; Password=" 
Set MonRs = New ADODB.Recordset
With MonRs
    .CursorLocation = adUseClient
    .ActiveConnection = Cnn1
    .Open "SELECT * FROM Authors", , adOpenStatic, adLockOptimistic, adCmdText
    .Fields("Author").Properties("Optimize") = True
    .Filter = "[ Author] like '*a'"
End With

Permet de synchroniser un recordset créé à partir d'une jointure, lors de la modification ou de l'ajout de la clef étrangère d'une des tables. S'utilise toujours en conjonction avec la propriété dynamique « Unique Table ». Attends une chaîne SQL étant la commande de synchronisation.

Évidemment; on peut se passer de cette propriété en réexécutant les requêtes plutôt que de les synchroniser. Il ne faut toutefois pas perdre de vue que le coût d'exécution n'est pas le même.

Comme vous devez spécifier la table qui subira les modifications, vous devez aussi préciser la clef primaire de celle-ci à l'aide du marqueur (?).

Reprenons l'exemple ébauché dans la discussion sur les curseurs, nous allons donc utiliser une requête similaire à :

SELECT * FROM Publishers, Titles WHERE Publishers.PubID = Titles.PubID

Sous la forme simplifiée à des fins de lisibilité :

SELECT Publishers.PubID, Publishers.Name, Titles.Title, Titles.ISBN, Titles.PubID
FROM Publishers , Titles 
WHERE Publishers.PubID = Titles.PubID

Le but étant toujours de corriger le titre en changeant l'éditeur.

Nous allons utiliser le code suivant :

Dim Cnn1 As ADODB.Connection, MonRs As ADODB.Recordset

Set Cnn1 = New ADODB.Connection
Cnn1.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=d:\biblio.mdb ;User Id=Admin; Password="
Set MonRs = New ADODB.Recordset
With MonRs
    .CursorLocation = adUseClient
    .ActiveConnection = Cnn1
    .Open "SELECT Publishers.PubID, Publishers.Name, Titles.Title, Titles.ISBN, Titles.PubID FROM Publishers, Titles WHERE Publishers.PubID = Titles.PubID", _
         , adOpenStatic, adLockOptimistic, adCmdText
    .Properties("Unique Table") = "Titles"
    'car les modifications réelles des données ne porteront que sur cette table
    .Properties("Resync Command") = "SELECT Publishers.PubID, Publishers.Name, Titles.Title, Titles.ISBN, Titles.PubID FROM Publishers, _ 
         Titles WHERE Publishers.PubID = Titles.PubID AND Titles.ISBN=?"
    ' où Titles.ISBN=? précise la clef primaire de la table déclarée dans unique table
    .Find "Title='Evaluating Practice'"
    .Fields("Titles.PubId") = 192 'Numéro de l'éditeur Alpha Books
    .Fields("Title") = .Fields("Title") & "s"
    .Update
    .Resync adAffectCurrent
    Debug.Print .Fields("Name").Value
End With

Nous voyons alors que la valeur apparaissant dans la fenêtre exécution est la bonne et que la modification désirée a bien eu lieu dans la table.

Permet de désigner une table qui sera la cible unique des modifications d'un recordset issu d'une requête avec jointure. La clef primaire de cette table devient alors la clef primaire de tout le recordset.

Définit comment le moteur de curseur va construire l'identification de l'enregistrement cible d'une modification, c'est-à-dire les valeurs qui apparaîtront dans le WHERE de la requête UPDATE. Prend une des valeurs suivantes :

Attention à l'utilisation de adCriteriaKey. Ceci implique que l'enregistrement sera identifié correctement, et que la valeur sera mise à jour même si elle a été modifiée par quelqu'un d'autre. N'oubliez pas que les valeurs utilisées par le moteur de curseur sont les valeurs stockées dans la propriété OriginalValue des objets Fields concernés.

Définit comment le recordset est synchronisé après un appel de la méthode Update ou UpdateBatch. N'oubliez pas que seuls les enregistrements modifiés ou ajoutés sont concernés par cette synchronisation. Prend une ou plusieurs des valeurs suivantes :

Attention, le fait de paramétrer la propriété avec adResyncInserts ne suffira pas pour récupérer la valeur des champs à numérotation automatique. Dans ce cas vous devrez utiliser :

MonRs.Properties("Update Resync") = adResyncAutoIncrement + adResyncInserts

Ajoutes un nouvel enregistrement au recordset. De la forme

recordset .AddNew FieldList, Values

Ou FieldList et Values sont des paramètres facultatifs permettant d'entrer directement des valeurs dans le nouvel enregistrement.

Dès l'appel de AddNew, l'enregistrement créé devient l'enregistrement en cours.

Attention, l'utilisation des paramètres lance un Update implicite. Par exemple:

With MonRs
    .AddNew
    .Fields("Author") = "RABILLOUD, Jean-Marc"
    .Fields("year born") = 1967
    .Update
End With

Est équivalent à :

MonRs.AddNew Array("Author", "year born"), Array("RABILLOUD, Jean-Marc", 1967)

Annule les modifications en attente dans un traitement par lot. De la forme :

recordset.CancelBatch AffectRecords

Où AffectRecords détermine si la méthode porte sur un ou plusieurs enregistrements. Il peut prendre les valeurs adAffectAll, adAffectGroup ou adAffectCurrent.

Déclenche en fait un appel de la méthode CancelUpdate sur tous les enregistrements modifiés, ajoutés ou supprimés du recordset. Attention, comme toutes les opérations par lot, la méthode peut définir des erreurs dans la collection Errors de l'objet connection, sans interrompre le traitement.

Annule les modifications apportées sur l'enregistrement en cours, ou annule l'enregistrement créé par AddNew.

Duplique un objet Recordset. Les clones sont synchronisés avec l'original jusqu'à l'application de la méthode Requery sur celui-ci.

Supprime un ou plusieurs enregistrements. De la forme :

recordset.Delete AffectRecords

Où AffectRecords détermine si la méthode porte sur l'enregistrement en cours ou sur tous les enregistrements qui correspondent à la propriété Filter.

Recherche les enregistrements répondant aux critères spécifiés. Cette méthode ne permet une recherche que sur un seul champ. De la forme :

recordset.Find (criteria, SkipRows, searchDirection, start)

Où SkipRows est une valeur facultative qui donne le décalage par rapport à la ligne en cours ou au paramètre Start, quand il est défini.

SearchDirection est une valeur facultative qui peut prendre les valeurs adSearchForward ou adSearchBackward

Start donne la position de l'enregistrement de démarrage de la recherche.

Criteria est l'expression du critère de recherche. Il se compose toujours du nom du champ suivi de l'opérateur de comparaison suivi de la valeur.

Le nom du champ doit être entre crochets s'il contient un espace

L'opérateur doit être (« > » (supérieur à), « < » (inférieur à), « = » (égal) « >= » (supérieur à ou égal), « <= » (inférieur à ou égal), « <> » (différent de) ou « Like » (concordance avec un modèle).)

La valeur doit être entourée de simples quotes ' s'il s'agit d'un texte, de dièse # si c'est une date ou de rien pour une valeur numérique.

Si aucun enregistrement correspondant n'est trouvé, le recordset se positionnera sur EOF ou BOF, selon le sens de la recherche.

N.B : Cette méthode est très coûteuse en ressource, essayez toujours de privilégier une méthode SQL sur les curseurs serveur.

Cette méthode permet de convertir un Recordset en tableau à deux dimensions (champ, enregistrement) de la forme :

Tableau = recordset.GetRows( Rows, Start, Fields )

Où Rows représente le nombre d'enregistrements à convertir, si la valeur est -1 tous les enregistrements seront convertis à partir de la position donnée par le paramètre « Start », s'il est omis tous les enregistrements du Recordset seront convertis.

Start donne la position du premier enregistrement à convertir. Peut prendre les valeurs adBookmarkCurrent, adBookmarkFirst, adBookmarkLast

Fields est la liste des champs devant être converti.

Après l'appel de la méthode, le recordset se positionne sur le premier enregistrement non converti ou sur EOF.

Renvoie le recordset sous forme d'une chaîne. De la forme :

Set Variant = recordset.GetString(StringFormat, NumRows, ColumnDelimiter, RowDelimiter, NullExpr)

Où StringFormat est toujours AdClipString

Les lignes sont délimitées par RowDelimiter, les colonnes par ColumnDelimiter et les valeurs NULL par NullExpr. Ces trois paramètres sont valides uniquement avec adClipString.

Ces méthodes permettent de se déplacer dans le jeu d'enregistrements. À la différence des mêmes méthodes DAO, le déplacement de l'enregistrement en cours valide l'ensemble des modifications effectuées.

Ouvre le Recordset. Nous verrons plus loin qu'il y a plusieurs méthodes pour obtenir un jeu d'enregistrements. De la forme :

recordset.Open Source, ActiveConnection, CursorType, LockType, Options

CursorType et LockType sont les propriétés du même nom, ActiveConnection est un objet Connection (explicite) ou une chaîne de connexion (Implicite).

Options peut prendre une ou plusieurs valeurs (masque binaire) de CommandTypeEnum et de ExecuteOptionEnum qui sont des paramètres de la méthode Execute de l'objet Command.

Ce paramètre doit être passé si le texte de la commande n'est pas une commande SQL, sous peine de ralentir le traitement.

Ce paramètre doit être passé si l'on travaille en mode Asynchrone.

Recrée le jeu d'enregistrements en réexécutant la requête. De la forme :

recordset.Requery Options

Où options est le même paramètre que dans le cas de la méthode Open.

Comme la requête est exécutée à nouveau, il peut y avoir des enregistrements en plus ou en moins ou provoquant des conflits du fait des actions d'autres utilisateurs. L'appel de la méthode déclenche une erreur si l'enregistrement en cours est en mode édition.

Attention, il n'est pas possible de modifier les paramètres du curseur dans l'appel de Requery. Pour modifier le curseur, vous devez utiliser Close puis Open.

Met à jour le jeu d'enregistrements. Utilisée seulement sur des curseurs statiques ou en avant seulement ; si le curseur est côté client, il ne doit pas être en lecture seule. De la forme

recordset.Resync AffectRecords, ResyncValues

Où AffectRecords spécifie les enregistrements à mettre à jour et ResyncValues précise si les modifications sont écrasées. Si la valeur est adResyncAllValues, toutes les modifications sont écrasées, on repart avec un recordset d'origine, si la valeur est adResyncUnderlyingValues les modifications en cours sont préservées.

Voyons comment cela fonctionne▲

Sauvegarde le Recordset comme un fichier. Un tel Recordset est appelé jeu d'enregistrements permanent. De la forme recordset.Save FileName, PersistFormat

Où PersistFormat, précise si le recordset est sauvegardé comme un fichier XML ou selon un format spécifique. Nous verrons dans les exemples comment on peut utiliser ces recordset persistant, mais sachez dès à présent qu'il n'est pas nécessaire d'avoir le fournisseur qui a créé le recordset pour pouvoir l'ouvrir.

Permet de faire une recherche multichamp sur les recordset indexés. Ne s'utilise que sur les curseurs serveurs. De la forme :

recordset.Seek KeyValues, SeekOption

Où KeyValues est une suite de valeurs de type « Variant ». Un index consiste en une ou plusieurs colonnes ou le tableau contient autant de valeurs qu'il y a de colonne, permettant ainsi la comparaison avec chaque colonne correspondante.

SeekOption peut prendre les valeurs suivantes :

Pour utiliser la méthode Seek, il faut que le recordset supporte les index et que la commande soit ouverte en adCmdTableDirect.

Comme vous le verrez dans l'exemple le principe est simple, on ajoute un ou des index sur le(s) champ(s) cible de la recherche, et on passe le tableau des valeurs cherchées à la méthode Seek.

Cette méthode est la meilleure amie du développeur ADO. Elle permet de savoir si un recordset donné va accepter une fonctionnalité spécifique. De la forme :

boolean = recordset.Supports( CursorOptions )

Où CursorOptions peut prendre les valeurs suivantes :

On utilise dans le code la méthode Supports pour savoir comment va réagir le recordset et éviter de faire de la gestion d'erreurs a posteriori.

Sauvegarde les modifications apportées à l'enregistrement en cours. De la forme :

recordset.Update Fields, Values

Où Fields et Values sont la liste des champs et des valeurs à modifier (facultatif).

Met à jour toutes les modifications en attente (opération par lot). De la forme

recordset.UpdateBatch AffectRecords

Où AffectRecords définit les enregistrements concernés.

Si toutes les modifications échouent, une erreur se produit, s'il n'y a que quelques échecs, ils sont ajoutés à la collection Errors de la connexion.

Valeur que peut prendre le paramètre adStatus présent dans presque tous les événements.

Private Sub Recordset_EndOfRecordset(fMoreData As Boolean, adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)

Se produit lorsque le recordset arrive en position EOF.

Où FMoreData définit s'il reste des enregistrements après. Doit être valorisé à « True » si pendant le traitement de l'événement on ajoute des enregistrements

AdStatus est l'état du recordset. Vaut adStatusOK si l'opération s'est bien passée et adStatusCantDeny si l'opération qui a déclenché l'événement ne peut être annulée. Si vous devez modifier le recordset pendant la procédure, ce paramètre doit être mis à adStatusUnwantedEvent afin de supprimer les notifications non désirées.

Precordset est la référence à l'objet subissant l'événement.

Private Sub MonRs_FetchProgress(ByVal Progress As Long, ByVal MaxProgress As Long, _
  adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)

Cet événement se déclenche périodiquement lors des opérations d'extractions asynchrones de longues durées. Les paramètres :

Progress représente le nombre de lignes extraites

MaxProgress le nombre de lignes qui doivent être extraites

Private Sub MonRs_FetchComplete(ByVal pError As ADODB.Error, adStatus As ADODB.EventStatusEnum, _ 
  ByVal pRecordset As ADODB.Recordset)

Se produit après la récupération du dernier enregistrement.

Où PError est un objet erreur ADO

Private Sub MonRs_WillChangeField(ByVal cFields As Long, _ 
    ByVal Fields As Variant, adStatus As ADODB.EventStatusEnum,  ByVal pRecordset As ADODB.Recordset)

Private Sub MonRs_FieldChangeComplete(ByVal cFields As Long, ByVal Fields As Variant, _
  ByVal pError As ADODB.Error, adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)

Où cFields est le nombre de champs modifiés et Fields un tableau contenant ces champs.

La méthode WillChangeField est appelée avant qu'une opération en attente modifie la valeur d'un ou plusieurs objets Field dans le Jeu d'enregistrements. La méthode FieldChangeComplete est appelée après modification de la valeur d'un ou plusieurs objets Field.

Là il convient bien de ne pas se mélanger dans les événements. Ces événements se produisent lorsque la propriété value d'un ou plusieurs objets Field(s) est modifiée. Cela n'a rien à voir avec la transmission de valeur vers la base de données.

Pour annuler la modification, il suffit de mettre le paramètre adStatus à la valeur adStatusCancel dans l'événement WillChangeField.

Private Sub MonRs_WillChangeRecord(ByVal adReason As ADODB.EventReasonEnum, _
  ByVal cRecords As Long, adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)

Private Sub MonRs_RecordChangeComplete(ByVal adReason As ADODB.EventReasonEnum, _ 
 ByVal cRecords As Long, ByVal pError As ADODB.Error, adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)

La méthode WillChangeRecord est appelée avant qu'un ou plusieurs enregistrements dans le Recordset ne soient modifiés. La méthode RecordChangeComplete est appelée après qu'un ou plusieurs enregistrements sont modifiés.

adReason peut prendre les valeurs suivantes : adRsnAddNew, adRsnDelete, adRsnUpdate, adRsnUndoUpdate, adRsnUndoAddNew, adRsnUndoDelete, adRsnFirstChange ou adRsnFirstChange.

Ce paramètre indique l'action ayant provoqué le déclenchement de l'événement.

cRecords renvoie le nombre d'enregistrements modifiés.

Ces événements se produisent donc lorsqu'il y a modifications des recordset ou mise à jour des données. Ce sont des événements qui peuvent modifier ou annuler des modifications dans la base de données.

Private Sub MonRs_WillChangeRecordset(ByVal adReason As ADODB.EventReasonEnum, _
  adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)

Private Sub MonRs_RecordsetChangeComplete(ByVal adReason As ADODB.EventReasonEnum,_ 
 ByVal pError As ADODB.Error, adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)

La méthode WillChangeRecordset est appelée avant qu'une opération en attente modifie le Recordset. La méthode RecordsetChangeComplete est appelée après que le Recordset a été modifié.

adReason peut prendre les valeurs suivantes : adRsnReQuery, adRsnReSynch, adRsnClose, adRsnOpen

Ces événements se produisent lors de remise à jour du recordset, ce sont des événements de recordset, ils n'influent jamais directement sur la base de données.

Private Sub MonRs_WillMove(ByVal adReason As ADODB.EventReasonEnum, _ 
 adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)

Private Sub MonRs_MoveComplete(ByVal adReason As ADODB.EventReasonEnum, _ 
 ByVal pError As ADODB.Error, adStatus As ADODB.EventStatusEnum, ByVal pRecordset As ADODB.Recordset)

La méthode WillMove est appelée avant que l'opération en attente change la position actuelle dans le Jeu d'enregistrements. La méthode MoveComplete est appelée après modification de la position actuelle dans le Recordset.

adReason peut prendre les valeurs suivantes : adRsnMoveFirst, adRsnMoveLast, adRsnMoveNext, adRsnMovePrevious, adRsnMove ou adRsnRequery

Attention à l'utilisation de ces événements. De nombreuses méthodes provoquent une modification de l'enregistrement en cours ce qui déclenche systématiquement cet événement. De plus il est très facile d'écrire un événement en cascade.