Comprendre les Recordset ADO

Ces événements se déclenchent avant et après l'exécution d'une commande, implicite ou non. En clair, ces événements se produisent sur l'appel de Connection.Execute, Command.Execute et Recordset.Open.

Private Sub Connection_WillExecute(Source As String, CursorType As ADODB.CursorTypeEnum, _ 
     LockType As ADODB.LockTypeEnum, Options As Long, adStatus As ADODB.EventStatusEnum, ByVal pCommand As ADODB.Command, _
     ByVal pRecordset As ADODB.Recordset, ByVal pConnection As ADODB.Connection)

Private Sub Connection_ExecuteComplete(ByVal RecordsAffected As Long, _ 
     ByVal pError As ADODB.Error, adStatus As ADODB.EventStatusEnum,  _ 
     ByVal pCommand As ADODB.Command, ByVal pRecordset As ADODB.Recordset, _ 
      ByVal pConnection As ADODB.Connection)

pConnection doit toujours contenir une référence à une connexion valide.

Si l'événement est dû à Connection.Execute, pCommand et pRecordset sont à « Nothing ».

Si l'événement est dû à Command.Execute, pCommand est la référence de l'objet Command et pRecordset vaut « Nothing ».

Si l'événement est dû à Recordset.Open, pCommand vaut « Nothing » et pRecordset est la référence de l'objet Recordset.

Définit la connexion utilisée pour l'objet Command. Cette propriété doit être passée à Nothing avant de changer la connexion d'un objet Command. Comme les objets Command héritent de certaines propriétés de la connexion, faites attention au paramétrage de celle-ci.

La propriété CommandText contient le texte de la commande à exécuter. Ce texte peut être le nom d'une requête stockée, une chaîne SQL, etc.

La valeur est en seconde. S'applique en général sur l'objet connection

Donne le type de la commande. Cette propriété est très importante. En effet, il y aura une erreur récupérable si le paramètre donné est faux. De plus ne pas valoriser correctement cette propriété peut dégrader fortement les performances. Les valeurs peuvent êtres

Définit si le nom des paramètres est passé au fournisseur, ce qui lui permet de ne pas avoir à les interpréter dans l'ordre de leur création.

Détermine si une commande doit être Précompilée. N'est utile que si la commande doit être exécutée plusieurs fois. Attention, certains fournisseurs n'acceptent pas cette modification sans toutefois déclencher d'erreur.

Renvoie l'état de la commande (ouverte ou fermée)

Annule l'exécution de la commande si celle-ci est asynchrone.

Execute la commande. De la forme :

command.Execute RecordsAffected, Parameters, Options

Où RecordsAffected renvoie le nombre d'enregistrements affectés par la commande. Ceci n'est vrai que pour une requête action ou pour l'appel d'une procédure d'action. Le paramètre n'est pas valorisé avec le nombre d'enregistrements extraits si la commande renvoie un recordset.

Parameters est un tableau contenant les paramètres (pour les requêtes/procédures paramétrées évidemment)

Option est identique a ce qui est décrit dans la méthode Open de l'objet Recordset.

Nous avons là plusieurs cas qui nous intéressent :

• On utilise toujours Command.Execute ou Connection.Execute pour utiliser des requêtes actions.
• Pour récupérer un recordset de l'objet Command, on peut soit passer la commande dans la méthode Open du recordset, soit affecter les enregistrements renvoyés dans un recordset.

Regardons le code suivant :

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

Set Cnn1 = New ADODB.Connection
Cnn1.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=d:\biblio.mdb ;User Id=Admin; Password="
Set MaCommand = New ADODB.Command
With MaCommand
    .ActiveConnection = Cnn1
    .CommandText = "SELECT * FROM Authors"
    Set MonRs = MaCommand.Execute
End With
MonRs.Close
Set MonRs = Nothing
Set MonRs = New ADODB.Recordset
MonRs.Open MaCommand, , adOpenKeyset, adLockOptimistic, adCmdText

J'utilise les deux méthodes que je vous ai données plus haut. Notez toutefois que dans le Command.Execute je n'ai pas défini le curseur. J'obtiens donc un curseur côté serveur en avant seulement et en lecture seule. Supposons que je paramètre mon Recordset au préalable :

Set MonRs = New ADODB.Recordset
With MonRs
    .CursorLocation = adUseClient
    .CursorType = adOpenStatic
    .LockType = adLockOptimistic
End With
Set MonRs = MaCommand.Execute

J'obtiendrais pourtant le même curseur qu'avec le code précédent. Cela vient du fait que lors de la création d'un recordset à l'aide de la méthode Execute, que ce soit sur l'objet Connection ou sur l'objet Command, hérite d'un curseur défini par la connexion. Selon la valeur de la propriété CursorLocation de l'objet Connection, vous obtiendrez soit un curseur en avant seulement en lecture seule (serveur) soit un curseur statique en lecture seule (Client). Le recordset sera toujours en lecture seule.

Sert à créer un paramètre (voir explications plus loin).

De la forme command.CreateParameter (Name, Type, Direction, Size, Value)

Attention à ne pas faire une erreur courante avec cette méthode. Celle-ci crée un paramètre, mais ne l'ajoute pas à la collection Parameters de l'objet Command. Ceci est d'ailleurs indispensable afin de pouvoir valoriser d'autres propriétés avant l'ajout.

Il faut déjà faire attention, pour les utilisateurs d'autres SGBD qu'Access à bien faire la différence entre procédure stockée et requête paramétrée.

Quoique regroupés dans la même collection, il existe deux types de paramètres. Les paramètres d'entrée, attendus par la procédure/requête pour pouvoir s'exécuter, et les paramètres de sorties qui peuvent être renvoyés par une procédure. Il convient de faire attention avec ceux-ci, une connection n'acceptant jamais plus de deux objets Command ayant des paramètres de sorties.

Append

Ajoute un paramètre à la collection. De la forme

Command.Parameters .Append Name, Type, DefinedSize, Attrib

Il est possible d'utiliser la méthode CreateParameter dans le Append. Vous devez avoir typé votre paramètre avant ou lors de l'ajout à la collection. Il est préférable de valoriser votre paramètre avant de l'ajouter à la collection afin de ne pas solliciter le fournisseur.

Delete

Enlève un paramètre de la collection. On doit spécifier soit le nom, soit l'index du paramètre à retirer.

Attributes

Précise si le paramètre accepte les valeurs signées, binaires ou NULL.

Direction

Définit si le paramètre est un paramètre d'entrée, de sortie ou de retour. Attention de ne pas confondre un paramètre de retour(adParamReturnValue) qui est l'entier éventuellement renvoyé par une procédure (dans le Return) d'un paramètre de sortie (adParamOutput) qui est le paramètre renvoyé par une procédure.

Name

Définit le nom du paramètre. N'est pas obligatoire

NumericScale

Donne la précision (nombre de chiffres à droite de la virgule) d'un paramètre numérique.

Size

Donne la taille en octet d'un paramètre dont le type est potentiellement de longueur variable (par exemple String). Ce paramètre est obligatoire pour les types de longueur indéterminée (String, Variant).

Elle doit être toujours valorisée avant ou lors de l'ajout à la collection.

Type

Comme son nom l'indique !

Ne vous emmêlez pas les pinceaux entre les chaînes adVarChar et les chaînes Unicode adVarWChar

Value

De manière générale, valorisez cette propriété après l'ajout à la collection.

AppendChunk

Permet d'accéder aux textes ou binaires longs.

Nous allons voir ici un exemple d'utilisation de requête paramétrée.

Prenons la requête stockée nommée ReqFerie définie comme :

PARAMETERS DateCib DateTime;
SELECT tblFerie.DateFer
FROM tblFerie
WHERE (((tblFerie.DateFer)>DateValue([DateCib])))
ORDER BY tblFerie.DateFer;

La fonction suivante crée un recordset en utilisant l'objet Command.

Private Sub Command5_Click()
Dim cnn1 As ADODB.Connection, Comm1 As ADODB.Command, Param1 As Parameter, MonRecordset As ADODB.Recordset

Set cnn1 = New ADODB.Connection
With cnn1
    .Provider = "Microsoft.Jet.OLEDB.4.0;"
    .ConnectionTimeout = 30
    .CursorLocation = adUseClient
    .IsolationLevel = adXactChaos
    .Mode = adModeShareExclusive
    .Properties("Jet OLEDB:System database") = "D:\User\jmarc\tutorial\ADOX\system.mdw"
    .Open "Data Source=D:\User\jmarc\tutorial\ADOX\baseheb.mdb ;User Id=Admin; Password="
End With
Set Comm1 = New ADODB.Command
With Comm1
    .ActiveConnection = cnn1
    .CommandType = adCmdStoredProc
    .CommandText = "ReqFerie"
End With
Set Param1 = New Parameter
With Param1
    .Direction = adParamInput
    .Type = adDate
    .Name = "DateCib"
End With
Comm1.Parameters.Append Param1
Comm1("DateCib").Value = #1/1/2002#
Set MonRecordset = Comm1.Execute
    
End Sub

On peut aussi utiliser aussi l'objet Command pour exécuter des requêtes actions sur la source de données. En général, comme celles-ci sont rarement utilisées plusieurs fois dans le même code, on utilise plus souvent l'objet Connection, ce qui permet de tout passer dans une ligne, tel que :

Cnn1.Execute "DELETE * FROM Authors WHERE [year Born]=1938", , adExecuteNoRecords

Néanmoins on peut aussi utiliser l'objet Command.

With Comm1
    .ActiveConnection = cnn1
    .CommandType = adCmdText
    .CommandText = "UPDATE Authors SET [Year Born]= [Year Born]+1"
End With
Comm1.Execute

On trouve par contre beaucoup plus souvent l'usage de requête stockée paramétrée avec l'objet command. Par exemple:

Dim cnn1 As ADODB.Connection, Comm1 As ADODB.Command, Param1 As Parameter, Param2 As Parameter, MonRecordset As ADODB.Recordset

Set cnn1 = New ADODB.Connection
With cnn1
    .Provider = "Microsoft.Jet.OLEDB.4.0;"
    .ConnectionTimeout = 30
    .CursorLocation = adUseClient
    .Open "Data Source=D:\basehebdo.mdb ;User Id=Admin; Password="
End With
cnn1.BeginTrans
Set Comm1 = New ADODB.Command
With Comm1
    .ActiveConnection = cnn1
    .CommandType = adCmdText
    .CommandText = "PARAMETERS DateCib DateTime, BancCib Text;" & _
         "DELETE * From tblAnomalie WHERE tblAnomalie.NumBanc=[BancCib] AND tblAnomalie.DatDimanche>=[DateCib];"
    .NamedParameters = True
End With
Set Param1 = New Parameter
With Param1
    .Direction = adParamInput
    .Type = adDate
    .Name = "DateCib"
End With
Set Param2 = New Parameter
With Param2
    .Direction = adParamInput
    .Type = adVarWChar
    .Size = 3
    .Name = "BancCib"
End With
Comm1.Parameters.Append Param1
Comm1.Parameters.Append Param2
Comm1("BancCib").Value = "S01"
Comm1("DateCib").Value = #1/1/2002#
Comm1.Execute
If MsgBox("valider la transaction", vbYesNo) = vbYes Then
    cnn1.CommitTrans
Else
    cnn1.RollbackTrans
End If

L'avantage de ce genre d'utilisation repose sur le fait qu'un nouvel appel d'Execute avec de nouvelles valeurs de paramètres est immédiatement accessible. Ainsi

Comm1.Execute , Array(#1/1/2002#, "S04"), adCmdText + adExecuteNoRecords

Est une réutilisation aisée de ma commande.