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"
Dans un fichier d'options, vous pouvez créer une entrée indiquant les propriétés StaticBinder appliquées à un ensemble d'interfaces Java. Créez une ligne commençant par groupOptions.nom-groupe. L'identificateur de groupe correspond à la valeur de nom-groupe. La valeur nom-groupe est la chaîne attribuée à une interface ayant l'annotation @Group de pureQuery.
@Group ("Payroll") public Interface CalculateTax { … }Si l'entrée groupOptions.Payroll est spécifiée dans un fichier d'options, StaticBinder effectue une opération de liaison sur les méthodes annotées dans l'interface CalculateTax pour laquelle les paramètres d'option ont été spécifiés.
groupOptions.Payroll -bindOptions "QUALIFIER(Payroll), COLLECTION(Payroll)" -url "jdbc:db2://com.prod.hr:50000/DB01"
Vous pouvez utiliser plusieurs entrées groupOptions pour lier une interface avec différentes options. Par exemple, une interface est annotée avec @Group("Group1") et contient des instructions SQL non qualifiées. Vous pouvez lier le package à cette interface dans deux collections de package différentes avec des valeurs de schéma différentes. Créez deux entrées groupOptions dans le fichier d'options de Group1. Pour chaque entrée groupOptions.Group1, indiquez une option COLLECTION et une option QUALIFIER différentes. StaticBinder lie les packages comme indiqué par chaque entrée groupOptions correspondante.
Pour obtenir des informations sur l'annotation @Group, voir Controlling how pureQuery utilities process interfaces.
DB2 Database for Linux, UNIX et 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-' >--+-------------------------+----------------------------------> | .-FALSE-. | '- -autoDetect--+-TRUE--+-' >--+------------------------------------------------------------------------------------+--> | (3) | +-| options DBRM |-------------------------------------------------------------------+ +- -bindOptions-- -"--options_définition_accès--"--+-------------------------------+-+ | '- -verifyPackages--+-DETAIL--+-' | | '-SUMMARY-' | '- -verifyPackages--+-DETAIL--+------------------------------------------------------' '-SUMMARY-' >--+-----------------------------+--+----------------+----------> | .-FALSE-. | | (4) | '- -differenceOnly--+-TRUE--+-' '-| -grant |-----' >--groupOptions--.--nom-groupe--=-------------------------------> >--+--------------------------+--+--------------------------+-->< '- -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 |-----' >--groupOptions--.--nom-groupe--=-------------------------------> >--+--------------------------+--+--------------------------+---> '- -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-'
Ce diagramme de syntaxe indique les options que vous pouvez définir pour les interfaces appliquées à un ensemble d'interfaces Java avec l'identificateur de groupe nom-groupe. La valeur nom-groupe est attribuée à une interface portant l'annotation pureQuery @Group. La valeur nom_groupe est sensible à la casse.
La ligne groupOptions.nom-groupe peut apparaître plusieurs fois pour le même nom-groupe.
(1) >>-groupOptions--.--nom-groupe--= ------------------------------> >--+--------------------------------------------------------------------------------------------------------------------------------+--> | (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 |-----'
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.
Lorsque l'option est spécifiée avec la valeur FALSE, l'utilitaire StaticBinder n'effectue aucune recherche dans le fichier archive.
Si un fichier de propriétés de l'utilitaire StaticBinder est explicitement spécifié avec la propriété -optionsFile, l'utilitaire StaticBinder exécute le processus de liaison sur les artefacts indiqués dans le fichier de propriétés. Puis le processus de liaison est exécuté sur les fichiers figurant dans l'archive, mais qui n'ont pas été spécifiés dans les fichiers de propriétés. L'utilitaire ne recherche pas les fichiers .bindprops si la propriété -optionsFile est spécifiée.
Lors de l'exécution d'une opération de liaison sur les fichiers trouvés dans le fichier archive, l'utilitaire StaticBinder utilise les options de propriétés de liaison par défaut spécifiées par les autres options StaticBinder. Par exemple : l'option de liaison peut être spécifiée dans la ligne -defaultOptions. Elles peuvent aussi être spécifiées par une propriété -groupOptions StaticBinder, s'il existe une annotation dans la classe d'implémentation indiquant une annotation @GroupId.
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.
Pour plus d'informations sur l'annotation @Group, voir Contrôle de la manière dont les utilitaires pureQuery traitent les interfaces.
.-,-------------------. V | >>- -grant-- "--grantees--(----+-ID_autorisation-+-+--) - "---->< '-PUBLIC----------'
Pour DB2 Database for Linux, UNIX et 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.