Pour comprendre les conventions utilisées dans les diagrammes, voir Lecture des diagrammes de syntaxe.
Les applications qui utilisent du SQL imbriqué lié statiquement à des packages DB2 ont des avantages inhérents en termes de performances, de fiabilité, de sécurité, de surveillance et d'administration.
Avant d'exécuter l'utilitaire StaticBinder, exécutez l'utilitaire Generator de pureQuery afin de générer les classes d'implémentation pour les interfaces contenant les instructions SQL que vous souhaitez lier. Lors de l'exécution de l'utilitaire Generator de pureQuery, toutes les informations nécessaires à la création d'un package DB2 statique sont collectées et stockées dans la classe d'implémentation générée. Il s'agit d'instructions SQL et de toutes les informations relatives au type de données applicable à partir des définitions de classe Java et de toutes les métadonnées de colonne ou de paramètre provenant de la base de données cible. Les informations comprennent également les noms de package racine et, éventuellement, les ID collection et versions des packages DB2.
L'utilitaire StaticBinder consulte ces information dans les classes d'implémentation lors de la création et de la liaison des packages DB2. Lors de l'exécution de l'utilitaire StaticBinder, sur la ligne de commande, vous pouvez spécifier les classes d'implémentation à consulter ou les interfaces correspondant à ces classes. Si vous utilisez un fichier d'options, vous pouvez spécifier une ou plusieurs interfaces. L'utilitaire StaticBinder consulte les informations dans les classes d'implémentation correspondantes.
Cependant, si vous utilisez l'option -forceSingleBindIsolation lorsque vous utilisez l'utilitaire Generator, le numéro de niveau d'isolement n'est pas associé au nom du package créé.
Si vous utilisez l'option -isolationLevel lors d'une liaison ou si vous indiquez le niveau d'isolement dans la chaîne des options de liaison, seul le package ou le fichier DBRM associé au niveau d'isolement indiqué est créé. Le nom suit les conventions que l'utilitaire StaticBinder adopte lors de la création des packages ou des fichiers DBRM pour chacun des quatre niveaux d'isolement.
Un fichier d'options répertorie la ou les interfaces que l'utilitaire pureQuery StaticBinder doit traiter, ainsi que les options indiquant à l'utilitaire StaticBinder comment traiter les interfaces. Vous pouvez définir les options par défaut s'appliquant à toutes les interfaces répertoriées dans un fichier d'options. Vous pouvez également définir des options d'interfaces afin de remplacer les options par défaut et d'en définir d'autres spécifiques aux interfaces individuelles.
Dans la commande d'exécution de l'utilitaire StaticBinder, vous pouvez indiquer le fichier à utiliser avec l'option -optionsFile.
defaultOptions = -bindOptions "QUALIFIER qual1" -url jdbc:db2://SRVR01:50000/DB01 -username user01 -password pass01 com.myCompany.MyInterfaceA = -bindOptions "QUALIFIER qual2" com.myCompany.MyInterfaceB com.myCompany.MyInterfaceC = -url jdbc:db2://SRVR01:50001/DB02 -username user02 -password pass02Dans cet exemple, la ligne commençant par defaultOptions indique le qualificatif des packages DB2 et définit l'URL de connexion par défaut. La ligne suivante indique une interface avec un qualificatif qui remplace le qualificatif par défaut. La ligne suivante indique une interface à laquelle toutes les options par défaut s'appliquent. La dernière ligne indique une interface dont l'accès doit être défini sur une base de données différente.
-pkgVersion "ver#1"
DB2 Database for Linux, UNIX, and Windows : Si l'utilisateur dispose du droit SYSADM mais sans privilèges explicites pour la définition d'accès, le gestionnaire de la base de données DB2 accorde automatiquement un droit DBADM explicite.
Vous pouvez utiliser cette commande pour exécuter l'utilitaire StaticBinder sur une archive contenant votre application. L'archive doit contenir les interfaces et classes d'implémentation à fournir à l'utilitaire StaticBinder. Utilisez un fichier d'options avec l'extension .bindProps dans lequel figurent les interfaces et classes d'implémentation.
(1) >>-java--com.ibm.pdq.tools.StaticBinder-------------------------> (2) >-------- -url--jdbc--:--db2--:--//--serveur--+---------+--/--base_de_données--> '-:--port-' >-- -username--ID-utilisateur-- -password--motdepasse-----------> >-- -archive-- -nom_fichier--+-.ear-+---------------------------> +-.jar-+ +-.war-+ '-.zip-' >--+------------------------------------------------------------------------------------+--> | (3) | +-| options DBRM |-------------------------------------------------------------------+ +- -bindOptions-- -"--options_définition_accès--"--+-------------------------------+-+ | '- -verifyPackages--+-DETAIL--+-' | | '-SUMMARY-' | '- -verifyPackages--+-DETAIL--+------------------------------------------------------' '-SUMMARY-' >--+-----------------------------+--+----------------+----------> | .-FALSE-. | | (4) | '- -differenceOnly--+-TRUE--+-' '-| -grant |-----' >--+--------------------------+--+--------------------------+-->< '- -isolationLevel--+-CS-+-' | (5) | +-RR-+ '-| Options de trace |-----' +-RS-+ '-UR-'
Vous pouvez utiliser cette commande pour spécifier le nom des interfaces ou des classes d'implémentation et les options de création d'un package DB2 ou d'un fichier DBRM.
(1) >>-java--com.ibm.pdq.tools.StaticBinder-------------------------> (2) >-------- -url--jdbc--:--db2--:--//--serveur--+---------+--/--base_de_données--> '-:--port-' >-- -username--ID-utilisateur-- -password--motdepasse-----------> >--+------------------------------------------------------------------------------------+--> | (3) | +-| options DBRM |-------------------------------------------------------------------+ +- -bindOptions-- -"--options_définition_accès--"--+-------------------------------+-+ | '- -verifyPackages--+-DETAIL--+-' | | '-SUMMARY-' | '- -verifyPackages--+-DETAIL--+------------------------------------------------------' '-SUMMARY-' >--+-----------------------------+--+----------------+----------> | .-FALSE-. | | (4) | '- -differenceOnly--+-TRUE--+-' '-| -grant |-----' >--+--------------------------+--+--------------------------+---> '- -isolationLevel--+-CS-+-' | (5) | +-RR-+ '-| Options de trace |-----' +-RS-+ '-UR-' .------------------------. V | >-- -interface----package_java.interface-+---------------------><
Vous pouvez utiliser la commande et un fichier d'options pour spécifier le nom des interfaces et les options de création de packages DB2 ou de fichiers DBRM reposant sur chacune de ces interfaces.
(1) >>-java--com.ibm.pdq.tools.StaticBinder-------------------------> >--+--------------------------------------------------------------------------------------------------------------------------+--> '- -url--jdbc--:--db2--:--//--serveur--+---------+--/--base_de_données-- -username--ID-utilisateur-- -password--motdepasse-' '-:--port-' >--+------------------------------------------------+-----------> | .-------------------------------. | | V | | '- -interface----package-java.interface.classe-+-' >-- -optionsFile--nom_fichier--+--------------------------+-----> | (2) | '-| Options de trace |-----' >--+-------------------------------+--------------------------->< '- -verifyPackages--+-DETAIL--+-' '-SUMMARY-'
Ce diagramme de syntaxe affiche les options par défaut que vous pouvez définir pour toutes interfaces figurant dans un fichier d'options.
(1) >>-defaultOptions--=--------------------------------------------> >--+--------------------------------------------------------------------------------------------------------------------------------+--> | (2) | '------- -url--jdbc--:--db2--:--//--serveur--+---------+--/--base_de_données-- -username--ID-utilisateur-- -password--motdepasse-' '-:--port-' >--+---------------------------------------------------------+--> '-+-----------------------------------------------------+-' '-+- -bindOptions-- -"--options_définition_accès--"-+-' | (3) | '-| options DBRM |--------------------------------' >--+----------------+--+--------------------------+-------------> | (4) | '- -isolationLevel--+-CS-+-' '-| -grant |-----' +-RR-+ +-RS-+ '-UR-' >--+--------------------------+-------------------------------->< | (5) | '-| Options de trace |-----'
Ce diagramme de syntaxe affiche les options que vous pouvez définir pour chaque interface figurant dans un fichier d'options.
(1) >>-package_java.interface--=------------------------------------> >--+--------------------------------------------------------------------------------------------------------------------------------+--> | (2) | '------- -url--jdbc--:--db2--:--//--serveur--+---------+--/--base_de_données-- -username--ID-utilisateur-- -password--motdepasse-' '-:--port-' >--+---------------------------------------------------------+--> '-+-----------------------------------------------------+-' '-+- -bindOptions-- -"--options_définition_accès--"-+-' | (3) | '-| options DBRM |--------------------------------' >--+----------------+--+--------------------------+------------>< | (4) | '- -isolationLevel--+-CS-+-' '-| -grant |-----' +-RR-+ +-RS-+ '-UR-'
Utilisez la méthode de définition des accès() de la classe com.ibm.pdq.tools.StaticBinder pour définir les accès des instructions SQL de votre application dans les packages DB2 lors de l'exécution. La méthode renvoie une valeur FALSE si l'opération de définition des accès échoue, et une valeur TRUE si elle réussit.
La méthode utilise deux paramètres. Le premier est un tableau de type "chaîne de caractères" utilisé pour passer des arguments dans l'utilitaire StaticBinder. Le second est un objet PrintWriter sur lequel l'utilitaire StaticBinder peut imprimer des messages et des exceptions.
Voici un exemple d'appel de la méthode de définition des accès() :
biner StaticBinder = new StaticBinder (); PrintWriter out = new PrintWriter( new FileWriter("BinderOutput.txt")); String[] argsArray = {"-user","nom_utilisateur","-password","mot_de_passe", "-url","URL-JDBC","-interface","classe-interface"}; Boolean check=binder.bind(argsArray, out);
L'archive peut contenir un fichier d'options avec l'extension .bindProps dans lequel figurent les fichiers pureQueryXML que vous transmettez à l'utilitaire StaticBinder. Si vous n'indiquez pas de fichier .bindProps dans la commande, l'utilitaire StaticBinder recherche un fichier .bindProps dans l'archive. StaticBinder utilise le premier fichier .bindProps détecté dans l'archive. L'utilitaire lance la recherche dans les fichiers EAR, JAR ou WAR de niveau supérieur.
Si vous indiquez le nom du fichier .bindProps avec la commande StaticBinder, le fichier indiqué est utilisé.
Lorsque vous liez des implémentations DAO avec l'option -archive, l'utilitaire StaticBinder charge des classes d'implémentation pour obtenir les informations qu'elles contiennent. Le chargement de classes peut nécessiter le chargement de classes dépendantes à partir des fichiers EAR, JAR ou WAR.
Lorsque vous effectuez l'opération de liaison avec l'option -archive, l'utilitaire StaticBinder peut renvoyer des erreurs signalant des classes introuvables. Par exemple, certaines applications d'entreprise nécessitant le contexte d'un serveur d'applications peuvent renvoyer ce type d'erreur.
Pour limiter les dépendances de chargement de l'utilitaire StaticBinder, vous pouvez placer la bibliothèque BCEL d'Apache dans le chemin de classe. Lorsque l'utilitaire StaticBinder dispose de la bibliothèque BCEL, il utilise la modification de code d'octets pour exclure les dépendances d'implémentation et limiter le nombre de classes chargées. Dans la plupart des cas, l'ajout de la bibliothèque au chemin de classe résout les erreurs liées à des classes introuvables.
Le fichier JAR BCEL d'Apache n'est pas fourni avec pureQuery Runtime. La bibliothèque BCEL est disponible sur le site du projet Apache.
La syntaxe de la chaîne est la suivante : "option_1 valeur_1 option_2 valeur_2".
Une fois les fichiers DBRM créés par l'utilitaire StaticBinder, vous devez les copier dans un fichier. Le nom du fichier DBRM est préfixe.DBRMLIB.DATA, où préfixe représente le qualificatif de haut niveau qui est indiqué dans le profil TSO de l'utilisateur. En règle générale, préfixe correspond à votre ID utilisateur dans TSO.
Si le fichier DBRM n'existe pas, vous devez le créer. Ce fichier doit disposer de suffisamment d'espace pour contenir toutes les instructions SQL, avec un supplément d'espace pour chaque nom de variable hôte ainsi qu'un certain nombre d'informations d'en-tête. Les informations d'en-tête requièrent environ deux enregistrements pour chaque package d'interrogation de base de données (DBRM), et il faut prévoir 20 octets pour chaque enregistrement SQL et 6 octets pour chaque variable hôte. Pour le format DBRM précis, reportez-vous à la macro de mappage DBRM, DSNXDBRM, dans la bibliothèque préfixe.SDSNMACS.
Le diagramme de syntaxe suivant décrit les options permettant de générer des fichiers DBRM.
>>- -generateDBRM--+-TRUE--+-- -outputDBRMPath--chemin--------->< '-FALSE-'
Le nom racine des fichiers DBRM générés est le nom de package racine que vous indiquez lorsque vous exécutez le générateur. Si ce nom comporte plus de sept caractères, l'utilitaire StaticBinder émet une exception.
Par exemple, supposez que vous avez exécuté l'utilitaire StaticBinder sur un fichier pureQueryXML appelé capture.pdqxml. L'utilitaire crée les package MYPKGA, MYPKGB et MYPKGC. Vous modifiez ensuite l'ensemble d'instructions MYPKGA dans capture.pdqxml avec le plan de travail et vous exécutez l'utilitaire Configure sur ce fichier, avec l'option -cleanConfigure associée à sa valeur par défaut FALSE. L'utilitaire Configure affecte une nouvelle marque de cohérence à l'ensemble d'instructions car ce jeu a été modifié. Lorsque vous exécutez à nouveau l'utilitaire StaticBinder sur capture.pdqxml pour définir les accès de la nouvelle version de MYPKGA, vous spécifiez -differenceOnly TRUE. L'utilitaire redéfinit uniquement les accès de MYPKGA et non ceux des deux autres packages.
.-,-------------------. V | >>- -grant-- "--grantees--(----+-ID_autorisation-+-+--) - "---->< '-PUBLIC----------'
Pour DB2 Database for Linux, UNIX, and Windows : vous pouvez utiliser les mots clés USER, GROUP et ROLE. Pour tout détail concernant ces mots clés, voir GRANT (Package Privileges) statement.
Pour DB2 for z/OS : vous pouvez utiliser le mot clé ROLE. Pour tout détail concernant ce mot clé, voir GRANT (package privileges).
Restriction : Vous ne pouvez pas utiliser l'option -grant lorsque l'option -generateDBRM a pour valeur TRUE.
Si le fichier d'options ne contient pas d'entrée pour les interfaces, l'utilitaire StaticBinder utilise les options de définition des accès qui se trouvent sur la ligne de commande et dans l'entrée defaultOptions du fichier d'options.
Le niveau d'isolement s'applique à toutes les instructions SQL du package. Si vous définissez un niveau d'isolement à l'aide de la méthode Connection.setTransactionIsolation() du pilote IBM® Data Server Driver for JDBC and SQLJ, pureQuery ignore ce niveau d'isolement pour les instructions exécutées de manière statique.
>>-+--------------------------+---------------------------------> '- -traceFile--nom_fichier-' >--+---------------------------+------------------------------->< | .-OFF-----. | '- -traceLevel--+-ALL-----+-' +-SEVERE--+ +-WARNING-+ +-INFO----+ +-CONFIG--+ +-FINE----+ +-FINER---+ '-FINEST--'
Par exemple, admettons que vous exécutiez l'utilitaire Generator sur une interface appelée OrdersData qui déclare les méthodes de requête et de mise à jour de la table ORDERS. L'utilitaire Generator crée la classe d'implémentation OrdersDataImpl.
Lors de l'exécution de l'utilitaire, vous avez indiqué les valeurs des options -collection, -pkgVersion, et -rootPkgName options, et l'utilitaire les a stockées dans la classe d'implémentation. Vous exécutez l'utilitaire StaticBinder, en indiquant le nom de cette classe ; l'utilitaire crée alors les packages DB2.
Plus tard, vous souhaitez afficher une liste des packages créés par l'utilitaire StaticBinder à partir de la classe d'implémentation. Lorsque vous exécutez l'utilitaire, vous pouvez utiliser l'option -verifyPackages,indiquer la valeur DETAIL, et indiquer à nouveau le nom de la classe.
Si les valeurs des options -collection, -pkgVersion, et -rootPkgName sont identiques à celles définies lors de la précédente exécution de l'utilitaire StaticBinder, l'utilitaire trouve les packages et les répertorie.
Cependant, si vous avez exécuté l'utilitaire Generator sur l'interface OrdersData après la première exécution de l'utilitaire StaticBinder et que vous avez modifié la valeur de l'une des options -collection, -pkgName, et -rootPkgName, l'utilitaire StaticBinder ne trouvera aucun des packages correspondant à ces nouvelles valeurs. Dans son rapport, l'utilitaire StaticBinder indiquera que les packages recherchés sont introuvables.
L'option -verifyPackages ne fonctionne pas si, suite à la génération de la classe d'implémentation et à l'exécution de l'utilitaire StaticBinder sur cette classe, vous avez exécuté à nouveau l'utilitaire Generator sur l'interface et indiqué de nouvelles valeurs pour les options -collection, -pkgVersion, et -rootPkgName.
Vous pouvez indiquer cette option avec l'option -bindOptions. Cependant, l'utilitaire StaticBinder ne définira pas l'accès aux packages. Utilisez -bindOptions uniquement pour indiquer la collecte des packages que vous souhaitez vérifier si vous avez utilisé cette option pour spécifier la collecte lors de la création des packages.