Comparaison de pages

...

1. Le client ODBC Divalto
Divalto est client ODBC et permet, à partir d'un programme DIVA, d'exécuter une requête et de récupérer le résultat pour une base de données quelconque possédant un driver ODBC. Nous fournissons avec ODBC deux programmes Diva d'exemple :

• DemoSql.dhop qui permet au programmeur de voir un exemple complet d'interfaçage avec ODBC.

• DemoObdc.dhop qui utilise un module (yodbc.dhop) et permet de récupérer le résultat d'une requête.

1.1 Les fonctions DIVA du client ODBC

ODBC est une interface de programmation permettant à une application de se connecter à un serveur, d'exécuter des requêtes SQL et de récupérer le résultat. Nous avons créé une série de fonctions Diva permettant de gérer la connexion, l'exécution d'une Requête SQL, la récupération du ou des résultats.

1.1.1 Ouverture de l'interface ODBC
Syntaxe :Status = SqlOpen
Type:X
Description :
La fonction SqlOpen ouvre l'interface ODBC. Elle est impérative avant l'utilisation de toute autre fonction ODBC. Elle renvoie 0 si l'opération s'est déroulée correctement et 1 en cas d'erreur. Cette fonction charge la dll DhOdbcClient.dll.
Exemple :
1 st x
st = SQLOpen
if st <> 0
;erreur
endif
Voir aussi :
SqlClose

1.1.2 Connexion directe à un driver ODBC
Syntaxe : ticket = SqlConnect (serv, uid, pwd)
servNom de la Source
uidCode utilisateur
pwdMot de passe
Type:X
Description :
La fonction SqlConnect permet de se connecter à une source de donnée.
La connexion est impérative avant toute autre opération sur une source. Un programme peut se connecter avec au maximum 10 sources de données simultanément.
SqlConnect est la fonction la plus simple pour se connecter à une source connue. Il existe une autre fonction de connexion à une source : SqlDriverConnect.
Retour :
Un ticket (1 à 10) correspondant au numéro de connexion. Ce ticket sera utilisé dans toutes les fonctions dialoguant avec cette source.
La fonction renvoie 0 en cas d'erreur.
Exemple :
1 ticket x
1 serv 256
1 uid 256
1 pwd 256
serv = "TEST DIVALTO"
uid = "root"
pwd = " "
ticket = SqlConnect (serv, uid, pwd)
if ticket = 0
;erreur
endif
Voir aussi :
SqlDriverConnect, SqlDisconnect, SqlError

1.1.3 Connexion à un driver ODBC par la boîte de dialogue du driver
Syntaxe : ticket = SqlDriverConnect (entree, sortie, mode)
entreeparamètres d'entrée
sortieparamètres renvoyés par le driver ODBC
mode 0 - ne pas afficher la boîte de dialogue
1 - connexion normale
2 - afficher la boîte de dialogue du driver
3 - connexion normale avec saisie de tous les paramètres
Type:X
Description :
La fonction SqlDriverConnect permet de se connecter à une source de données. C'est une alternative à la fonction SqlConnect qui permet plus de souplesse au niveau de la connexion. La connexion est impérative avant toute autre opération sur une source. Un programme peut se connecter avec au maximum 10 sources de données simultanément.

• Le paramètre entree est une chaîne de caractères contenant les paramètres de connexion. Elle peut contenir le nom du driver, le nom de la source, le code utilisateur, le mot de passe. Tous ces paramètres sont facultatifs. En fonction du mode, le driver ouvrira une boîte de dialogue pour demander les informations manquantes. La chaîne peut être à espace et dans ce cas, le driver Manager demande le nom de la source.

• Pour préciser le nom du driver, on utilisera le mot clé DRIVER=nom du driver;

• Pour préciser le nom de la source, le mot clé DSN=nom de la source;

• Pour préciser le nom de l'utilisateur, le mot clé UID=code de l'utilisateur;

• Pour préciser le mot de passe, le mot clé PWD=mot de passe;
  Dans la chaîne entree, on peut mettre une combinaison de ces paramètres, chaque paramètre est terminé par un ; (point virgule). Les mots clé doivent être en majuscule et les valeurs des paramètres doivent respecter la casse.
  Exemples : entree = "DRIVER=Divalto;"
  entree = "DSN=G3;UID=root;"

• Le paramètre sortie contient le texte de connexion complété par le driver. Il permet de se reconnecter au driver sans ouvrir de boîte de dialogue. Pour cela, il suffit dans la fonction SqlDriverConnect de passer le paramètre sortie en entrée.

• Le paramètre mode permet d'influer sur les boîtes de dialogue de la connexion :

La valeur 0 demande une connexion sans afficher la boîte de dialogue. Dans ce cas, si les paramètres d'entrée ne sont pas valides ou complets, le driver renvoie une erreur.
La valeur 1 demande une connexion (mode le plus courant). Dans ce cas, si les paramètres en entrée sont valides et complets, le driver n'affiche pas la boîte de dialogue et se connecte directement à la base de données. S'il manque des informations, il affiche une boîte de dialogue afin que l'utilisateur puisse compléter les paramètres manquants ou puisse changer de paramètres.
La valeur 2 demande une connexion avec affichage obligatoire de la boîte de dialogue. Si des paramètres sont fournis, ils sont présélectionnés.
La valeur 3 fonctionne comme la valeur 1 mais demande que TOUS les paramètres soient spécifiés, même les paramètres facultatifs.
Retour :
Un ticket (1 à 10) correspondant au numéro de connexion. Ce ticket sera utilisé dans toutes les fonctions dialoguant avec cette source.
La fonction renvoie 0 en cas d'erreur.
Exemple :
1 ticket x
1 mode x
1 entree 256
1 sortie 256
entree = "DRIVER=Divalto;"
mode = 1
ticket = SqlDriverConnect (entree, sortie, mode)
Voir aussi :
SqlConnect, SqlDisconnect, SqlError

1.1.4 Exécution d'une requête SQL
Syntaxe : Status=SqlExecDirect (ticket, sql)
ticketticket rendu par la connexion
sqldonnée contenant le source de la requête SQL
Type:X
Description :
La fonction SqlExecDirect exécute la requête SQL passé en paramètre.
La taille de la requête n'est pas limitée. La longueur maximum d'un nom de colonne est de 64 caractères.
Retour :
La fonction renvoie 0 si tout s'est bien passé, 1 en cas d'erreur.
Exemple :
1 ticket x
1 st x
1 texte 80
texte = "select * from f1"
st = SqlExecDirect (ticket, texte)
if st <> 0
;erreur
endif
Voir aussi :
SqlGetResult, SqlCancel, SqlError

1.1.5 Options
Syntaxe : SqlSetOption (ticket, typeoption, option)
ticketticket rendu par la connexion
typeoption type de l'option (type L)
option valeur de l'option (type L)
Description :
Ajoute une option à la liste des options de la future requête.
Avant d'exécuter une requête, Divalto appelle le driver avec une liste d'options (que le programme Diva a indiquée) puis lance l'exécution de la requête.
Voir avec le fournisseur de driver ODBC utilisé pour connaître les options reconnues par le driver.
Exemple :
;define SQL_ACCESS_MODE= 101
;define SQL_MODE_READ_WRITE= 0
;define SQL_MODE_READ_ONLY= 1
;define SQL_MODE_DEFAULT = 0 ;SQL_MODE_READ_WRITE
;
;define SQL_AUTOCOMMIT= 102
;define SQL_AUTOCOMMIT_OFF= 0
;define SQL_AUTOCOMMIT_ON= 1
;define SQL_AUTOCOMMIT_DEFAULT= 1 ;SQL_AUTOCOMMIT_ON
;
;define SQL_ODBC_CURSORS= 110
;define SQL_CUR_USE_IF_NEEDED= 0
;define SQL_CUR_USE_ODBC= 1
;define SQL_CUR_USE_DRIVER= 2
;define SQL_CUR_DEFAULT= 2 ;SQL_CUR_USE_DRIVER

Effacement des options
Syntaxe : SqlFreeOptions (ticket)
ticketticket rendu par la connexion
Description :
Cette fonction permet d'effacer cette liste options.

1.1.6 Lecture des résultats d'une requête SQL
Syntaxe : Status=SqlGetResult (ticket)
ticketticket rendu par la connexion
Type:X
Description :
La fonction SqlGetResult permet de récupérer le résultat d'une requête. Dans le cas d'une requête de type SELECT, on récupèrera le résultat colonne par colonne. Les requêtes de mise à jour permettent de connaître le nombre de lignes modifiées, ajoutées ou supprimées. La variable globale sqltype contient la nature du résultat. Par un simple automate, on pourra récupérer l'ensemble du résultat, y compris les en têtes de colonnes, avec l'indication des changements de ligne.
Attention : Il est interdit d'exécuter une nouvelle requête par SqlExecDirect avec un ticket pour lequel l'ensemble du résultat n'a pas été lu ou abandonné par la fonction SqlCancel.
sqltype vaut :

• 0 s'il n'y a plus de résultat à lire.

• 1 après une requête de mise à jour. Dans ce cas, la variable globale sqlnblig contient le nombre de lignes modifiées.

• 2 si le résultat est une en tête de colonne. Dans ce cas, les variables globales suivantes contiennent :

sqltextele nom de la colonne (64 caractères maximum).
sqlgcol la largeur de la colonne.
sqlstate le type de la variable en texte.
sqltypvarle type de la variable (cf zodbc pour les defines).
sqllgvar la longueur de la variable.
sqlscavar le nombre de décimales.
sqlnulvar colonne pouvant être nulle : 0 non, 1 oui, 2 peut-être.

• 3 si toutes les en têtes de colonnes ont été lues. Le prochain appel à SqlGetResult donnera la première colonne.

• 4 si le résultat est une colonne. Dans ce cas, les variables globales suivantes contiennent :

sqltextela valeur de la colonne (255 caractères maximum). Si la longueur dépasse 255 caractères, le 255ème est remplacé par >. Utilisez plutôt la fonction SqlGetData qui renvoie la valeur sans cette limite de 255 caractères et la fonction SqlGetDataSize qui renvoie la taille de la donnée.
sqlgcol la largeur de la colonne.
sqltypvarle type de la variable (cf zodbc pour les defines).
sqlstate le texte du type de la variable.
sqllgvar la longueur réelle de la variable.
sqlscavar le nombre de décimales.
sqlnulvar colonne pouvant être nulle : 0 non, 1 oui, autre peut-être.

• 5 si toutes les données d'une ligne ont été lues. Le prochain appel à SqlGetResult donnera la première donnée de la ligne suivante.

Retour :
La fonction renvoie 0 si tout s'est bien passé, 1 en cas d'erreur.

Syntaxe : texte =SqlGetData
Type:char
Description :
Renvoie la donnée en cours dans le SqlGetResult, et uniquement si sqltype vaut 4.
Cette fonction ne limite pas la taille de la donnée à 255 caractères.

Syntaxe : lg =SqlGetDataSize
Type:L
Description :
Renvoie la taille de la donnée qui sera rendue par SqlGetData ou SqlGetResult.

Syntaxe : SqlNextRecord (ticket)
ticketticket rendu par la connexion
Description :
Lors de la boucle de lecture des données, permet de passer directement à « l'enregistrement suivant », sans faire défiler tous les champs de la requête.

Exemple de lecture des données d'une requête :
1 ticket x
1 Status x
do
Status = SqlGetResult(ticket)
while Status = 0 and sqltype <> 0
;décodage du type de résultat de la requête
switch (sqltype)
;type 0 : il n'y a plus de résultat
case 0
;type 1 : nb de lignes modifiées, requête INSERT, DELETE ou UPDATE
case 1
display "ok, nombre de lignes modifiées " & sqlnblig
;type 2 : nom de l'en tête d'une colonne, requête du type SELECT
case 2
display "nom de la colonne " & sqltexte:1.sqllgcol
display "type " & sqlstate:1.20
display "précision " & sqllgvar
display "nb de décimales " & sqlscavar
;type 3 : fin des en têtes de colonne
case 3
display " "
;type 4 : résultat d'une colonne
case 4
display mid (SqlGetData,1,SqlGetDataSize) & " " 0
;type 5 : fin d'une ligne
case 5
display " "
endswitch
wend

Voir aussi :
SqlCancel, SqlError

1.1.7 Abandon de la requête
Syntaxe : Status=SqlCancel (ticket)
ticketticket rendu par la connexion
Type:X
Description :
La fonction SqlCancel permet d'interrompre une requête sans lire l'ensemble des résultats. Après cette fonction, tous les résultats sont perdus. Cette fonction est facultative si l'on a lu tous les résultats d'une requête par SqlGetResult.
Retour :
La fonction renvoie 0 si tout s'est bien passé, 1 en cas d'erreur.
Exemple :
1 ticket x
1 st x
st = SqlCancel (ticket)
Voir aussi :
SqlError

1.1.8 Déconnexion d'une source
Syntaxe : Status=SqlDisconnect (ticket)
ticketticket rendu par la connexion
Type:X
Description :
Cette fonction se déconnecte de la source et libère le ticket. On ne peut plus ensuite utiliser le ticket. Il faut impérativement se reconnecter avant toute nouvelle opération avec ce ticket.
Retour :
La fonction renvoie 0 si tout s'est bien passé, 1 en cas d'erreur.
Exemple :
1 ticket x
1 st x
st = SqlDisconnect (ticket)
Voir aussi :
SqlConnect, SqlDriverConnect, SqlError

1.1.9 Fermeture de l'interface ODBC
Syntaxe : Status=SqlClose
Type:X
Description :
Cette fonction ferme l'interface ODBC Divalto. Elle ferme aussi toutes les connexions encore ouvertes.
Retour :
La fonction renvoie 0 si tout s'est bien passé, 1 en cas d'erreur.
Exemple :
1 st x
st = SqlClose
Voir aussi :
SqlOpen

1.1.10 Compte rendu d'erreur
Syntaxe : SqlError (erreur1, erreur2)
erreur1code de l'erreur
erreur2libellé de l'erreur
Description :
En cas d'erreur après les fonctions SqlConnect, SqlDriverConnect, SqlExecDirect, SqlGetResult, SqlCancel, SqlDisconnect, la fonction SqlError permet de récupérer le compte rendu de l'erreur. Il est impératif d'appeler cette fonction avant tout autre appel à une fonction ODBC si l'on souhaite récupérer le code de l'erreur produite.
Exemple :
1 erreur1 256
1 erreur2 256
ErrorSql(erreur1,erreur2)
display left(erreur1)
display left erreur2)

2. Appel d'ODBC par l'interface du module YODBC.dhop
Le module yodbc.dhop contient des fonctions qui simplifient l'utilisation d'ODBC dans un programme Diva.
Exemple :
1cn L
1st L
1prix 13,2
main
cn = Connexion ("DSN=test Divalto;UID=root;PWD=;")
st = ExecuteRequete (cn, 'select * from article')
do
st = Fetch (cn)
while st = 0
display fstring ("F", GetData (cn,"Reference") & " " & GetData (cn,"Libelle")) 0
prix = GetData (cn,"pu");les données sont limitées à 4096 caractères
display prix 0
display GetData (cn,"stock") 0
display " "
wend
Deconnexion (cn)
DeconnecterSql

2.1 Connexion
Syntaxe : cn = Connexion (param)
param code de connexion (exemple : "DSN=test Divalto;UID=root;PWD=;")
cnticket de type L, numéro de la connexion
Description :
Crée une connexion avec un serveur. S'il y a une erreur , la fonction affiche l'erreur et termine l'exécution du programme.

2.2 Exécution d'une requête
Syntaxe : st = ExecuteRequete (cn,requete)
cnnuméro de la connexion (ticket de type L)
requete texte de la requête (exemple 'select * from article')
stvaleur de retour (0 = ok)
Description :
Exécute une requête.

2.3 Lecture d'un "enregistrement" de la requête
Syntaxe : st = Fetch (cn)
cnnuméro de la connexion (ticket de type L)
stvaleur de retour (0 = ok)
Description :
Lit le premier "enregistrement", puis les suivants, pour la requête en cours.

2.4 Lecture d'une valeur
Syntaxe : valeur = GetData (cn,donnée)
cnnuméro de la connexion (ticket de type L)
donnée nom de la donnée (exemple "pu")
Le test sur le nom de la donnée se fait en convertissant tous les noms de donnée
en majuscules.
valeurrésultat
Description :
Lecture d'une donnée.

2.5 Déconnexion
Syntaxe : Deconnexion (cn)
cnnuméro de la connexion (ticket de type L)
Description :
Ferme la connexion cn.

2.6 Fin de yodbc.dhop
Syntaxe : DeconnecterSql
Description :
Ferme les connexions encore ouvertes et ferme la Dll DhOdbcClient.



Annexe 1: Mode d'emploi des programmes d'exemple client ODBC

DemoSql.dhsp :
Ce programme est un exemple de programmation de l'interface client ODBC. Il s'adresse aux programmeurs désirant interfacer une application avec ODBC. Le source DemoSql.dhsp comporte les commentaires en complément de la documentation des fonctions. Pour utiliser ce programme, il suffit dans un premier temps de valider les réponses par « Flèche vers le bas ».
Les questions :

• Mode d'affichage des en têtes de colonne : permet d'afficher ou non toutes les informations sur les en têtes de colonne que va renvoyer le driver ODBC.

• Type de connexion : permet de choisir la connexion au driver ODBC, soit par la fonction SqlConnect soit par l'affichage d'une boîte de dialogue contenant la liste des sources installées sur votre ordinateur par la fonction SqlDriverConnect. Répondre 'C' pour une connexion directe. Il faudra dans ce cas introduire le nom de la source, votre code utilisateur et votre mot de passe. Répondre 'D' pour une connexion par boîte de dialogue. Il faudra dans ce cas sélectionner la source.

• Votre requête SQL.

Les résultats s'affichent alors à l'écran. Pour vous déconnecter, il faut mettre la requête à espace ou taper F9.


DemoOdbc .dhsp :
Le programme DemoOdbc.dhop est un exemple de programmation avec le module yodbc.dhop.
Le source yodbc.dhsp est fourni avec les exemples. Si vous modifiez ce source, il faut penser à changer le nom du module yodbc.dhop.