DataGrid & 4D Oracle Par Sebastian FREY Chiheb NASR, Ingénieur Contrôle Qualité, 4D SA Note technique 4D-200110-31-FR Version 0 Date 1 Octobre 2001 Résumé Cette note technique 4D est la quatrième d'une série qui décrit le fonctionnement interne de l'application de DataGrid. Elle détaille la mise en œuvre de 4D pour Oracle dans le module EDM, noyau de l'application de DataGrid. 4D Notes techniques Copyright 1985-2003 4D SA - Tous droits réservés Tous les efforts ont été faits pour que le contenu de cette note technique présente le maximum de fiabilité possible. Néanmoins, les différents éléments composant cette note technique, et le cas échéant, le code, sont fournis sans garantie d'aucune sorte. L'auteur et 4D S.A. déclinent donc toute responsabilité quant à l'utilisation qui pourrait être faite de ces éléments, tant à l'égard de leurs utilisateurs que des tiers. Les informations contenues dans ce document peuvent faire l'objet de modifications sans préavis et ne sauraient en aucune manière engager 4D SA. La fourniture du logiciel décrit dans ce document est régie par un octroi de licence dont les termes sont précisés par ailleurs dans la licence électronique figurant sur le support dulogiciel et de la Documentation afférente. Le logiciel et sa documentation ne peuvent être utilisés, copiés oureproduits sur quelque support que ce soit et de quelque manière que ce soit, que conformément aux termes de cette licence. Aucune partie de ce document ne peut être reproduite ourecopiée de quelque manière que ce soit, électronique ou mécanique, y compris par photocopie, enregistrement, archivage ou tout autre procédé de stockage, de traitement et de récupération d'informations, pour d'autres buts que l'usage personnel de l'acheteur, et ce exclusivement aux conditions contractuelles, sans la permission explicite de 4D SA. 4D, 4D Calc, 4D Draw, 4D Write, 4D Insider, 4ème Dimension, 4D Server, 4D Compiler ainsi que les logos 4e Dimension, sont des marques enregistrées de 4D SA. Windows,Windows NT,Win 32s et Microsoft sont des marques enregistrées de Microsoft Corporation. Apple, Macintosh, Power Macintosh, LaserWriter, ImageWriter, QuickTime sont des marques enregistrées ou des noms commerciaux de Apple Computer,Inc. Mac2Win Software Copyright 1990-2002 est un produit de Altura Software,Inc. 4D Write contient des éléments de "MacLink Plus file translation", un produit de DataViz, Inc,55 Corporate drive,trumbull,ct,usa. XTND Copyright 1992-2002 4D SA. Tous droits réservés. XTND Technology Copyright 1989-2002 Claris Corporation.. Tous droits réservés ACROBAT Copyright 1987-2002, Secret Commercial Adobe Systems Inc.Tous droits réservés. ACROBAT est une marque enregistrée d'adobe Systems Inc. Tous les autres noms de produits ou appellations sont des marques déposées ou des noms commerciaux appartenant à leurs propriétaires respectifs. 1 / 9
Introduction Si vous n'avez pas déjà lu la première note de cette série, nous vous le recommandons vivement avant d aborder la présente note technique pour que vous puissiez vous familiariser avec les concepts : modèles et requêtes du module EDM. 4D for Oracle 4D pour Oracle est un produit de la gamme " 4D Open suite ", avec 4D ODBC et le Driver ODBC pour 4D serveur. C est un plug-in 4D disponible sur les deux plates-formes Macintosh et Windows. Il peut être utilisé avec 4D Mono, 4D Runtime et 4D Client. Pour pouvoir utiliser 4D pour Oracle, il indispensable d installer les librairies d un Client oracle (OCI 7.3 et plus) sur votre machine. Le logiciel Client Oracle pour Windows est disponible sur tous les CD d installation et peut aussi être téléchargé sur le site Internet d Oracle. Par contre, la version Macintosh est livrée au client uniquement sur CD suite à sa demande au près de la société ORACLE Corporation. Les dernières versions des OCI, au moment de la rédaction de cette note technique, sont : OCI 7.3 pour Macintosh OCI 8.1.7 pour Windows Ceci ne cause aucun problème pour le plug-in 4D pour Oracle car ce dernier supporte toutes les versions supérieures ou égales à 7.3. 4D pour Oracle permet de: - se connecter à une ou plusieurs instances de bases de données Oracle - interroger les schémas et les tables des utilisateurs d une instance de base de données Oracle - rechercher et trier les enregistrements - rapatrier les données dans des enregistrements, des variables ou des tableaux 4D - insérer, mettre à jour et supprimer des enregistrements Préférences de Couche Oracle Ci-dessous les trois comportements paramétrables dans la boite de dialogue de préférences du plug-in 4D pour Oracle : Mode asynchrone Validation automatique des transactions (Auto Commit) en cas de modifications Utilisation de "OD Execute object" Mode asynchrone : A la différence de 4D ODBC, 4D pour Oracle possède le mode asynchrone. En cochant la case correspondante on active le mode asynchrone pour toutes les connexion à Oracle. 2 / 9
Validation automatique des transactions : Par défaut, pour toutes les sessions Oracle, les modifications (insérer, mettre à jour et supprimer) ne sont réellement stockées qu au moment de la validation de la transaction (appel explicite à l instruction COMMIT). Dans l application DataGrid la validation automatique des transaction est activée donc, toute modification sera immédiatement stockée. Utilisation de "OD Execute object" : Avec 4D Pour Oracle, on peut exécuter des procédure stockée sur le serveur Oracle à l aide de la commande OD Execute SQL. La commande OD Execute object peut également être utiliser pour lancer des procédures stockées et a l avantage d avoir des paramètres de sortie permettant de recevoir des données dans des variables 4D. La boite de dialogue de préférences vous permet aussi de configurer les nom des serveurs Oracle, les noms des utilisateurs et les mots de passe. Les serveurs Oracle aux quels vous voulez vous connecter doivent déjà être définis par le logiciel de connexion Oracle. Connexion à une instance Oracle Les deux méthodes de haut niveau suivantes vous permettent d ouvrir une connexion et de récupérer son numéro d identification : ou $iconnectionid := EDM_ConnectionForType (EDM_kData4dOracle) $iconnectionid := EDM_QueryConnectionID ($iqueryindex) Afin utiliser les commandes bas niveau pour établir une connexion vous pouvez appeler la méthode EDM_OraConnectionID. Cette méthode reçoit comme paramètres le nom du serveur, le nom d utilisateur et son mot de passe. En ne lui passant pas de paramètres, les valeurs prises par défaut seront les valeurs passées à cette méthode au premier appel. Si aucune valeur n a été passée à la méthode au paravent, la boite de dialogue de login du plug-in 4D pour Oracle sera présentée à l utilisateur. Toutes les informations concernant les nouvelles connexions sont stockées par la méthode EDM_OraConnectionRecord qui permet également de fixer quelques options pour la connexion en question. Les connexions utiliseront le mode asynchrone qui le de fonctionnement par défaut du module EDM: OD SET OPTIONS ($iconnectionid;64; 0) ` activer le mode déféré OD SET NB MODE ($iconnectionid; 1) ` activer le mode non- bloquant La validation automatique des transactions est aussi fixée pour toutes les connexions : OD SET OPTIONS ($iconnectionid; 2; 0) 3 / 9
4 / 9
Lister les noms des tables Oracle Contrairement à 4D ODBC et 4D Open, il n y a aucune commande dans 4D pour Oracle qui permet de récupérer la liste des tables du serveur Oracle. La solution est d utiliser le dictionnaire de données qui est un ensemble de tables qu Oracle met à jour pour une base de données. Dans le module EDM, ce dictionnaire est exploité par les tables [EDM_DataModel], [EDM_ModelColumn] et [EDM_Relations]. La liste des noms des tables sur serveur peut être obtenue à partir de trois tables suivantes de dictionnaire de données d Oracle : USER_TABLES (contient les tables qui appartiennent à l utilisateur) ALL_TABLES (contient les tables que l utilisateur a déjà utilisé) DBA_TABLES (contient toutes les tables de la base de données Oracle). De la même manière, on peut récupérer la liste des vues à partir des trois tables suivante : USER_VIEWS, ALL_VIEWS, et DB_VIEWS. Pour trouver la liste des noms des tables, dans sa méthode EDM_OraTableCatalog, le module EDM se base sur l une des deux tables : USER_TABLES ou USER_VIEWS. Exemple : SELECT table_name FROM user_tables ou SELECT table_name FROM user_views Lister les noms des colonnes des tables Oracle Cette liste est obtenue par la méthode EDM_OraTableInfo qui reçoit comme paramètres : nom de la table, ID de la connexion et des tableaux qui recevront les noms, les types et les longueurs maximales des colonnes. Pareillement, il n y a aucune commande qui permet de retrouver la liste des colonnes directement à partir du plug-in 4D pour Oracle. Il faut donc faire appel au dictionnaire des données d Oracle et plus précisément à la table USER_TAB_COLUMNS. Exemple : SELECT column_name, data_type, data_length, data_scale FROM user_tab_columns WHERE table_name = 'MaTable' ORDER BY column_id Les procédures stockées D oracle (PS) 5 / 9
La couche Oracle du module EDM vous permet d insérer, mettre à jour et supprimer un modèle de ligne à l aide des requêtes SQL au sein d une procédure stockée. Pour pouvoir utiliser ces procédures stockées il faut fixer le modèle de données adéquat. Lorsque vous éditez un modèle de données d Oracle, vous remarquerez dans le formulaire entrée et sous la liste des modèles des colonnes la présence de trois cases à cocher (insérer, mettre à jour et supprimer via une PS) et trois zones saisissables. Le modèle de données peut être configuré pour exécuter, par exemple, un ajout ou une modification dans une procédure stockée alors que la suppression s effectue directement par le langage SQL. Vous pouvez également spécifier un nom de procédure stockée. Si vous cochez une des cases et vous ne donnez pas un nom à votre procédure stockée, un nom sera calculé pour vous par la méthode EDM_ModelProcedureGet. A partir de la fenêtre de dialogue affichée au démarrage de DataGrid vous pouvez créer une procédure stockée par défaut pour l ajout, la mis à jour et la suppression d un modèle de données d une ligne. Si vous choisissez cette option, une deuxième boite de dialogue de choix du modèle de données sera affichée. Les procédures stockées seront créées sous la forme d une série du fichiers SQL (fichiers texte avec l extension.sql) qui doivent être exécutée par l outil SQL*Plus d Oracle. Recherche et tri des enregistrements Dans une base de données 4D les critères de recherche et de tri sont séparés alors que dans le langage SQL ils peuvent être imbriqués dans une même requête. Pour pouvoir lancer une requête via le module de données EDM vous avez besoin de créer un objet dans ce module. Supposons que vous avez un module de données nommé " Clients ". Pour trouver la liste des clients qui vivent en Oakland, on procède de la façon suivante : $imodelindex := EDM_ModelIndex ("clients") $iqueryindex := EDM_QueryCreate ("OaklandClients"; $imodelindex; $iconnectionid) `fixer les critères de recherche (la clause de WHERE) $twhere := "city = 'Oakland'" EDM_QueryText ($iqueryindex; EDM_kQueryWhereClause; $twhere) ` fixer les critères de tri (the ORDER BY clause) $torderby := "lastname" EDM_QueryText ($iqueryindex; EDM_kQueryOrderBy; $torderby) ` exécution de la recherche et chargement de la première page des résultas $fok := EDM_QueryExecuteSelect ($iqueryindex) Chargement des résultas de la recherche Le chargement de données des tables Oracle dans des variables ou des tableaux 4D peut s effectuer de différentes manières. Certains développeurs utilisent encore la notion des contextes qui facilite la manipulation des données Oracle mais qui, dans certains cas de figure, peut être très limitée. La commande de 6 / 9
haut : OD Execute SQL est également facile à utiliser mais représente une importante limitation. En effet, cette commande permet soit de tronquer le résultat en un nombre spécifié de lignes, soit charger la totalité du résultat mais ne permet pas, sans le chargement, un simple accès à la totalité des lignes. Pour remédier à cette contrainte, le module EDM utilise les commandes de bas niveau de 4D pour Oracle. Par exemple : $tsql:="select id, firstname, lastname FROM clients" $iconnectionid:=<>ora_i_connectionid $irowlimit:=<>ora_i_pagesize $icusrsorid:=od Create cursor($iconnectionid) $iresult:=od Set SQL in cursor ($icursorid;$tsql) OD BIND TOWARDS 4D($iCusorID;1;->APP_ai_LongintArray1) OD BIND TOWARDS 4D($iCusorID;2;->APP_at_TextArray1) OD BIND TOWARDS 4D($iCusorID;3;->APP_at_TextArray2) $iresult:=od Load rows cursor ($icursorid;$irowlimit) OD DROP CURSOR($iCursorID) Les résultats des requêtes SQL sont chargés par la méthode EDM_OraQueryLoadResults qui crée un curseur et relie les tableaux 4D au colonnes de la requêtes à travers un Bind. Les lignes résultantes seront chargées dans les tableaux 4D correspondant par tranche à l aide de la méthode EDM_OraLoadRows. Grâce aux commandes de bas niveau, la segmentation des résultats des requêtes en un certain nombre de pages vous permet de rapatrier et manipuler une taille beaucoup plus importante de données. Insertion, mise à jour et suppression des lignes L insertion, la mise à jour et la suppression sont réalisées par la seule méthode EDM_SqlRowIUD car ces trois actions nécessitent la même structure que la requêtes SQL. Cette méthode reçoit comme paramètres : l indexe du modèle de données, l identifiant de connexion et le type de l action (insertion, mis à jour, suppression) et exécute la requêtes SQL spécifiée. Examinons l exemple suivant : INSERT INTO clients (id, lastname, firstname) VALUES (501, 'Joseph', 'Blutarsky') Cette requêtes SQL permet de créer une ligne dans la base de données Oracle. Vous pouvez noter qu elle ne requière pas de paramètres. Pour l exécuter vous devez faire appel à une commande de 4D pour Oracle de haut niveau : $iconnectionid:=<>ora_i_connectionid $tsql:="insert INTO clients (id, lastname, firstname) VALUES (501, 'Joseph', 'Blutarsky')" $imaxrows:=1 7 / 9
$iresult:=od Execute SQL ($iconnectionid;$tsql;$imaxrows) Si vous avez plusieurs enregistrements dans votre base 4D à insérer dans la base de données Oracle, il est plus judicieux d insérer dans les requêtes SQL des références aux champs 4D que de modifier dans une boucle la requêtes SQL elle même. A chaque passage dans la boucle les valeurs des champs sont remplacées par celles de l enregistrement courant de la table [Clients]: $tsql:="insert INTO clients (id, lastname, firstname) VALUES (<<[Clients]ID>>, <<[Clients]First_Name>>, <<[Clients]Last_Name>>)" Boucle($I;1;Enregistrements trouves([clients])) ALLER DANS SELECTION([Clients];$I) $iresult:=od Execute SQL ($iconnectionid;$tsql;$imaxrows) Fin de boucle Inclure les références aux champs, aux variables, ou aux tableaux 4D dans une requête SQL est une technique très recommandée. Malheureusement, elle a un inconvénient. En effet, vous ne pouvez vous référer qu à une seule valeur de taille variable à la fois. Par exemple, la requêtes suivante échouera et vous aurez l erreur "multiple parameters in bind list > 2000": C_ENTIER LONG(iID) C_TEXTE(tLastName;tFirstName) iid:=1 tlastname="blutarsky" tfirstname:="joseph" $tsql:="insert INTO clients (id, lastname, firstname) VALUES (<<iid>>, <<tfirstname>>, <<tlastname>>)" On peut contourner ce problème par un simple changement de type des variables en alphanumérique de 255 caractères. Ce contournement est très utile car il est fréquent de rencontrer des tables ayant des colonnes de longueur supérieure à 255 caractères. Dans ces situations, vous pouvez ne pas utiliser l attachement des paramètres par votre modèle de données qui construira à la place des requêtes SQL contenant des " coquilles de chaîne de caractères" (string literals). Toutefois, il faut faire attention, en utilisant des coquilles, de ne pas dépasser des requêtes SQL de 32k. Pour envoyer un BLOB ou une images à une base de données Oracle, vous devez obligatoirement utiliser l attachement des paramètres. Si vous avez plusieurs BLOBs ou images à envoyer, il faudra exécuter des requêtes multiples. Afin d effectuer des requêtes multiples (ajout ou modification) avec le module EDM sur table contenant plusieurs colonnes de type VARCHAR2 (supérieure à 255), LONG, ou LONG RAW, il faut créer plusieurs modèles de données. La solution consiste à créer un modèle de données de base pour toutes 8 / 9
les colonnes de taille court ou/et fixe de la table et un modèle de donnée propre à chaque colonne de type VARCHAR2 (supérieure à 255), LONG, ou LONG RAW. Gestion d'erreurs Afin d intercepter les erreurs du plug-in 4D pour Oracle, il faut installer une méthode de gestion d erreur à l aide de la commande the OD ON ERROR CALL. Cette commande fonctionne de la même façon que la méthode de gestion des erreurs de 4D APPELER SUR ERREUR : elle reçoit comme paramètre la méthode à exécuter. En revanche, la méthode de 4D est exécuter dans le contexte du process appelant alors que celle de 4D pour Oracle est commune à tous les process et toutes les connexions. Dans le module EDM la gestion des erreurs est assurée par la méthode EDM_OraErrorHandle. Conclusion Cette note technique vous a présenter l utilisation du plug-in 4D pour Oracle dans le module de données de l entreprise EDM. 9 / 9