Extraction et migration des données Pacbase

Vous pouvez extraire et migrer les utilisateurs et les bases de développement Pacbase. Jazz peut s'interconnecter avec un LDAP ou un système de sécurité tel que RACF. Dans ce cas, il n'y aura pas de migration des utilisateurs Pacbase.

Pourquoi et quand exécuter cette tâche

Voici le schéma général des actions d'extraction et de migration des données Pacbase.

Figure 1. Schéma général de la migration

1. Migration des utilisateurs.
   1. Extraction.

      Extrayez et transférez, depuis la base d'administration, tous les utilisateurs avec la procédure Pacbase MIUS.

      Cette procédure permet d'extraire les identifiants, noms et adresses de courrier électronique des utilisateurs.

      Remarque : Pour des informations, référez-vous à la section Les procédures d'analyse et de migration Pacbase.

      Les administrateurs Pacbase auront le droit JazzAdmins, tous les autres auront le droit JazzUsers.

   2. Chargement dans Rational Team Concert.

      Importez les utilisateurs dans Rational Team Concert. Le serveur Jazz Team Server doit être ouvert.

      Vous devez transférer le fichier des utilisateurs extraits avec la procédure MIUS vers la machine sur laquelle est installé le serveur Jazz.

      Vous devez tout d'abord transformer le fichier ASCII, issu de l'extraction Pacbase, au format UTF-8. Pour ce faire, vous devez exécuter le fichier AsciiToUTF8.bat, situé sous la racine rpp de la Software Delivery Platform. Saisissez la ligne de commande suivante :

      AsciiToUTF8 AsciiInputFile Utf8OutputFile

      Cette ligne inclut les éléments suivants :

      • AsciiInputFile est le chemin complet du fichier issu de la procédure MIUS. Ce fichier est au format ASCII.
      • Utf8OutputFile est le chemin complet du fichier qui sera utilisé en entrée de -createUsers, la commande standard de création des utilisateurs de Rational Team Concert. Ce fichier est au format UTF-8.

      Remarque : Le fichier AsciiToUTF8.bat a été conçu pour fonctionner à l'emplacement où il est livré. Il est donc souhaitable de le conserver à cet endroit. Si vous le déplacez, vous devez le modifier.
      Pour charger les utilisateurs, vous devez ensuite saisir la commande -createUsers de la façon suivante :

      Figure 2. Lignes de commande de création des utilisateurs

      C:\...\IBM\JazzTeamServer\server\repotools-ccm -createUsers 
      	fromFile=C:\...\MIUSFILE (après conversion au format UTF-8)
       	repositoryURL=https://…:9443/ccm 
      	adminUserId=xxxx 
      	adminPassword=xxxx

      Remarque : Consultez l'aide Rational Team Concert pour des explications sur la commande -createUsers.

      Le journal repotools-ccm_createUsers.log permet de voir les erreurs éventuelles.

      Un utilisateur déjà créé est modifié.

      Avertissement : La tentative de mise à jour de l'utilisateur ADMIN peut entraîner l'erreur de mise à jour CRJAZ1350E. Ce code ne peut être réutilisé.
2. Migration d'une base de développement.
   1. Analyse préalable de la base Pacbase.
      La procédure MIAM reprend et complète certaines fonctionnalités de l'analyse du référentiel, comme par exemple :

      • Recherche des codes d'instances contenant des caractères spéciaux ou correspondant à un mot réservé Windows (LPT1 par exemple). Le fichier CS est alimenté.
      • Recherche des Programmes (P) qui sont à transformer en Macros. Le fichier PM est alimenté.
      • Recherche des instances à ne pas reprendre (exemple : Etats pour maquette GDP). Le fichier NR est alimenté.
      • Alimentation du fichier RQ avec le détail des différentes recherches (exemple : liste des entités contenant un caractère spécial). Ce fichier peut être édité avec un tableur.

      Remarque : Pour des informations, référez-vous à la section Les procédures d'analyse et de migration Pacbase.

      Vous devez analyser les résultats de cette procédure et effectuer toutes les actions indiquées avant de procéder à l’extraction.

      Si, à l'issue de l'exécution de la procédure MIAM, le fichier OUTUP contient des enregistrements, vous devez impérativement mettre à jour la base Pacbase avec la procédure UPDP avant de la migrer pour éviter toute incohérence dans la base. Ce fichier peut contenir des erreurs liées aux entités client/serveur V2.5 : MP6 (appel d'une méthode d’extraction dans une Macro) et MP7 (Appel d'un service utilisateur dans une Macro). Il peut contenir aussi des erreurs EC7 (ligne -CE d'Ecran de longueur erronée) et WK2 (ligne suite de zone de travail commençant avant la marge B dans le COBOL). Ces erreurs sont détaillées dans Codes erreurs nécessitant une correction.

      Important : Si vous ne mettez pas à jour la base avec la procédure UPDP, les entités client/serveur V2.5 ne seront pas migrées correctement et leur génération dans Rational Programming Patterns sera incorrecte.
      Vous devez aussi, par exemple, gérer les caractères spéciaux et les instances ayant le même nom externe. Si la base contient des Blocs Bases de Données de type DB, vous devez exécuter la procédure TRDQ pour transformer leur type en Q2 avant la migration. Toutes les erreurs issues de l'exécution de la procédure MIAM sont expliquées dans Traitement des erreurs.

      Rappel : Le COBOL généré pour être migré dans Rational Programming Patterns ne prend pas en compte l'option de formatage du COBOL indiquée au niveau Bibliothèque.
   2. Extraction de Pacbase.
      Extrayez les données avec une des procédures d'extraction de Pacbase MIBA ou MIBR.
      MIBA permet une extraction chevelue d'une liste d'instances tandis que MIBR extrait toutes les instances du réseau ou sous-réseau sélectionné dans un contexte (une fois pas session).

      Remarque : La procédure MIBR peut être complétée par la procédure MIBU pour personnaliser la migration en prenant en compte des modifications de design (modification de la sélection des Segments dans l'appel d'une Structure de Données par exemple).

      
      Vous pouvez utiliser par la suite la procédure MIBJ pour extraire des mouvements du journal archivé Pacbase.

      Mettez en entrée deux fichiers issus de la procédure MIAM : le fichier PM des Programmes à transformer en Macros et le fichier NR des instances à ne pas reprendre.

      Ces procédures peuvent transformer les caractères spéciaux non reconnus dans un code instance par un autre caractère. Pour cela, utilisez le fichier des caractères spéciaux issu de la procédure MIAM et complétez-le.

      Ces procédures fournissent la liste des Macros à générer par la procédure MIMA et les entrées des procédures MIA1, MIA2, MIA3 et MIA4. Pensez à indiquer le code des cartes de contrôle optionnelles pour insérer des séparateurs dans les procédures MIAn.

      Vous pouvez utiliser les procédures MIBR et MIBJ pour reprendre les verrous Pacbase sur les instances migrées. Si l'option de migration des verrous est indiquée, des fichiers de script sont automatiquement créés dans le répertoire .metadata de l'espace de travail de migration. Ces fichiers se nomment scmUnLock.bat pour déverrouiller les instances après l'import du journal et scmLock.bat pour verrouiller ou réverrouiller les instances sur le serveur.

      Remarque : Pour des informations, référez-vous à la section Les procédures d'analyse et de migration Pacbase.
   3. Transfert des fichiers.
      Transférez les fichiers vers le poste sur lequel sont installées les parties clientes de Rational Programming Patterns et des produits requis.
      Vous devez transférer les fichiers issus des procédures dans un même répertoire :

      • MIBA ou MIBR dans le fichier MIBR.ta2.

        Si vous avez exécuté les procédures MIBJ ou MIBU, transférez les mouvements dans un fichier d'extension .ta2 mais de nom différent de MIBR.

        Transférez aussi les listes d'entités générées dans les fichiers MIA1.txt, MIA2.txt, MIA3.txt et MIA4.txt.

      • MIMA dans le fichier MIMA.cblgen. D'autres fichiers d'extension .cblgen mais de nom différent peuvent être présents dans ce répertoire. Ceci est le cas, par exemple, si vous avez modifié manuellement le code source d'une Macro. Tous les fichiers .cblgen sont alors pris en compte par la procédure de migration automatique.
      • MIA1 dans les fichiers COBOL_MIA1.txt et CONTROL_COBOL_MIA1.txt.
      • MIA2 dans les fichiers COBOL_MIA2.txt et CONTROL_COBOL_MIA2.txt.
      • MIA3 dans les fichiers COBOL_MIA3.txt et CONTROL_COBOL_MIA3.txt.
      • MIA4 dans les fichiers COBOL_MIA4.txt et CONTROL_COBOL_MIA4.txt.
      Important : Vous devez faire attention aux pages de code utilisées lors du transfert.

      Pour transférer, par FTP, un fichier d'un environnement System z (EBCDIC français) vers le poste, vous devez saisir les informations suivantes dans un fichier file.scr.

      ATTENTION :

      La présence d'un code utilisateur associé à son mot de passe dans le fichier file.scr constitue une information confidentielle. Vous devez donc sécuriser l'emplacement du fichier lors du lancement du transfert et détruire ce fichier quand le transfert est terminé.

      Tableau 1. Commandes de transfert FTP à saisir

      Commandes à saisir	Explications
      open hostname	Changez hostname par l'adresse de l'hôte origine.
      tsouid	Changez tsouid par l'utilisateur TSO.
      tsopwd	Changez tsopwd par le mot de passe TSO.
      quote site sbdataconn=(IBM-1147,ISO8859-1)	Paramètres du transfert EBCDIC français vers ASCII. Remarque : Ces paramètres sont donnés à titre d'exemple. Vous devez indiquer les paramètres correspondant à votre environnement.
      quote site notrailingblanks	Paramètre de suppression des caractères à blanc en fin d'enregistrement
      get 'NomFichierSurz' c:\NomFichierLocal	Encadrez le nom du fichier System z par des guillemets simples (par défaut, il se positionne sur tsouid).
      quit

      Vous lancez le transfert avec la commande : ftp -s:file.scr.
      Des fichiers facultatifs peuvent aussi être copiés dans le répertoire :

      • Si des fichiers COBOL ont été générés avec une variante Microfocus (variante 3 : UNIX, Windows), vous devez aussi copier dans ce répertoire le fichier transform.txt. Ce fichier est fourni dans le répertoire d'installation de votre Rational Software Delivery Platform, sous rpp/migration. Il corrige la syntaxe COBOL générée pour la rendre compatible avec le compilateur IBM®. Il contient cinq règles par défaut mais vous pouvez ajouter des règles ou modifier les règles existantes, sauf la première. Cette première règle ajoute des points dans la WORKING-STORAGE SECTION et la PROCEDURE DIVISION (avant les étiquettes). Les autres règles sont construites autour d'une expression régulière et de sa chaîne de remplacement.
        Remarque : Pour rétablir le contrôle syntaxique du code COBOL de ces fichiers, vous devez sélectionner la préférence La syntaxe COBOL pour la variante 3 (UNIX,Windows) est certifiée compatible avec la syntaxe IBM COBOL AIX après la migration. Pour accéder à cette préférence, sélectionnez Fenêtre > Préférences > Programmation pilotée par pattern > Patterns Pacbase.
      • Si vous voulez créer des instances de Libellés d'erreur, vous devez créer un fichier errorLabels.txt et le copier dans ce répertoire. Ce fichier doit contenir autant de lignes que d'instances de Libellés d'erreur à créer, selon la syntaxe suivante :
        • La commande de génération Pacbase (GED, GEO, GEC ou GES).
        • La Bibliothèque de génération.
        • Après un blanc, la Structure de Données ou le Dialogue associé.
        • Après un blanc, une option de génération (C1 à C4), facultative. Si cette option n'est pas indiquée, C1 sera pris en compte par défaut.
        • Après un blanc, le nom qui sera donné à l'instance de Libellé d'erreur créée.
        Exemple : GEDCEN DD C1 ERROR1
      • Si vous voulez que le fichier des libellés d'erreur spécifiques Pacbase (extrait par la procédure MILA) soit pris en compte par défaut dans les instances de Libellé d'Erreur Rational Programming Patterns, vous devez copier ce fichier dans ce répertoire et le nommer specificErrorLabel.txt.
      • Si vous voulez mettre en correspondance des jeux de cartes de contrôle optionnelles Pacbase avec des définitions de langage z/OS, vous devez créer un fichier inputzCompMap.txt et le copier dans ce répertoire.

        Ce fichier doit contenir une ligne par mise en correspondance, selon le format suivant :
        XX LangageDefinition.
        XX est le jeu carte avant et carte après dans Pacbase, sur 2 caractères. En l'absence de carte avant ou carte après dans Pacbase, vous devez saisir un blanc à la place.
        LangageDefinition est la définition de langage ciblée dans Rational Team Concert, séparée du jeu carte avant et après par un blanc.

   4. Alimentation de l'espace de travail local.
      1. Préparation des commandes de migration.

         Exécutez d’abord la commande de migration automatique rpp --automaticMigration. Cette commande crée le fichier de commandes qui permet d’enchaîner l’import, la répartition des Macros, la modification de la cible de génération (si elle est demandée) et l’aide à la migration. Elle crée les répertoires des sources de migration en éclatant les différents programmes. Vous devez respecter la structure du répertoire contenant les fichiers transférés. Voir le paragraphe Transfert des fichiers.

         La commande de migration automatique effectue les opérations suivantes :

         • Les fichiers COBOL Microfocus sont transformés si le fichier transform.txt est présent dans le répertoire d'entrée de la migration. Les règles contenues dans ce fichier sont utilisées pour rendre la syntaxe des fichiers COBOL compatible avec le compilateur IBM. Un répertoire ORIGINAL_COBOL est créé pour conserver la version originale des fichiers COBOL modifiés.
         • Les jeux de cartes de contrôle optionnelles Pacbase sont mis en correspondance avec les définitions de langage z/OS si le fichier inputzCompMap.txt est présent (voir les informations sur la commande rpp --automaticMigration). La migration crée autant de fichiers de mise en correspondance que de projets COBOL z/OS pour la commande rpp-zcompmap. Ces fichiers sont générés par défaut dans le répertoire metadata/zCompMap de l'espace de travail de migration.
         • Le fichier specificerrorLabel.txt est copié dans le projet .INTER du référentiel dans l'espace de travail, s'il est présent dans le répertoire d'entrée de la migration. Ainsi, lors d'une génération d'une instance de l'entité Libellé d'Erreur, si aucun fichier n'est indiqué dans la zone Fichier spécifique des libellés d'erreur, le fichier specificerrorLabel.txt sera automatiquement pris en compte.
         • Si un fichier errorLabels.txt est présent, un fichier MIBR_modified.ta2 est créé. Ce fichier contient les informations issues de l'extraction Pacbase ainsi que les instances de Libellé d'Erreur qui seront créées automatiquement lors de l'exécution de la commande d'import. Cette commande d'import s'exécute alors sur ce fichier MIBR_modified.ta2. Ainsi, le fichier original issu de l'extraction Pacbase n'est jamais modifié. Le script à exécuter est automatiquement modifié en fonction de la présence ou pas de ce fichier MIBR_modified.ta2.
         • Une Macro ££USER et une Macro ££80EX sont créées dans le projet .INTER du référentiel dans l'espace de travail. Elles ne peuvent pas être copiées et collées, renommées, déplacées, supprimées ou modifiées.

           Ces deux Macros constituent le seul moyen d'implémenter, respectivement, des services utilisateurs et des méthodes d'extraction dans les Composants Applicatifs. Elles sont utilisées dans le cadre de la reprise des applications Pacbase. Dans ce cas, elles sont automatiquement appelées avec les bons paramètres dans les Lignes -CP des Composants Applicatifs concernés. Pour implémenter vous-même des services utilisateurs ou des méthodes d'extraction, vous devez appeler la Macro appropriée dans les Lignes -CP d'un Composant Applicatif et valoriser ses paramètres. Les services utilisateurs et méthodes d'extraction implémentés par un autre moyen ne sont pas pris en compte. A partir de la version 9.5.1 de Rational Programming Patterns, ils constituent du code inactif que vous pouvez supprimer. Un avertissement est positionné dans ce cas dans le code COBOL. Ce cas concerne aussi les méthodes d'extraction et les services utilisateurs qui avaient été appelés à partir de l'assistant de création de fonctions et sous-fonctions dans une version antérieure de Rational Programming Patterns.

         Veillez à bien utiliser les paramètres pour la création des projets contenant les sources COBOL. Ces projets peuvent être de type zComponent ou standard.

         Des informations détaillées sont disponibles sur la Migration progressive et la Migration multi-sessions.

         La migration automatique produit un fichier location.txt (où location représente le nom du référentiel).

         Exemple d’une commande de migration automatique qui crée un projet de type zComponent et sépare les fichiers de source COBOL et les fichiers de métadonnées Rational Programming Patterns. Les fichiers de métadonnées seront stockés dans le répertoire design :

         rpp.bat --automaticMigration --data "C:\Migration\Workspace" --log "C:\Migration\automatic.log" --from "C:\Migration\Input" --location XXXX --separateCobolProject --cobolProjectType Z --separateMetadataFiles --pdpRootPath design

         Important : La commande rpp --automaticMigration crée un espace de travail. Cet espace de travail n'étant pas indexé, il n'est pas recommandé de l'ouvrir avant de le remonter dans Rational Team Concert. Cependant, vous pouvez être amené à l'ouvrir dans certains cas. Si Rational Programming Patterns est installé par-dessus Rational Developer for System z (IBM Developer for z Systems), vous devez ouvrir l'espace de travail après l'exécution de rpp --automaticMigration car Rational Developer for System z (IBM Developer for z Systems) copie automatiquement l'espace de travail lors de son ouverture. Comme l'espace de travail contient peu d'informations à ce moment-là, le temps de copie est limité. Si vous ouvrez l'espace de travail après l'exécution du fichier de commandes, le temps de copie sera beaucoup plus long.
      2. Exécution du fichier de commandes.
         Lancez la commande rpp --commands en indiquant le fichier location.txt comme option.

         Figure 3. Syntaxe de rpp.bat

         Syntaxe: rpp.bat --commands [options]
                 --data - Espace de travail. (obligatoire)
                 --log - Nom du fichier de consignes. (défaut trace.log)
                 --file - Fichier contenant la liste des commandes batch. (obligatoire)
                 --exitOnError - Sortie en cas d'erreur d'une commande.

         Les étapes suivantes sont exécutées :

         1. Conversion des fichiers de design.

            Cette étape initialise un espace de travail local contenant une hiérarchie de projets. Chaque projet contient les instances d'une Bibliothèque Pacbase.

            Si un fichier errorLabels.txt est présent dans le répertoire d'entrée de la migration, des instances de Libellés d'erreur sont créées.

            Pour valider l'import, vous pouvez analyser les erreurs contenues, par défaut, dans le fichier .pacmigration.log du répertoire .metadata de l'espace de travail. Ce fichier synthétise le contenu du fichier .ta2 importé en affichant les informations suivantes :

            • Le contexte de l'import comme la base, l'utilisateur, la session, la Bibliothèque et la date.
            • Le remplacement des caractères spéciaux.
            • Les statistiques des instances présentes dans le fichier .ta2. Ces chiffres incluent les instances dupliquées par les procédures de migration.
            • Les erreurs détectées lors de l'import.
            • Les Structures de Données et les Dialogues dupliqués par l'import.
            • Le nombre d'instances réellement importées et le nombre d'instances présentes dans le fichier .ta2. Le nombre d'instances réellement importées peut être inférieur au nombre d'instance présentes dans le fichier .ta2 dans le cas de l'import d'une nouvelle session Pacbase dans le même espace de travail. Dans ce cas, les instances qui n'ont pas été modifiées ne sont pas comptabilisées dans les instances importées.
            • Le nombre d'entités de design modifiées, créées ou supprimées.
         2. Répartition des fichiers sources des Macros.

            Cette étape prend en entrée le fichier issu de la procédure MIMA et répartit les sources des Macros dans les Macros correspondantes des différents projets de votre espace de travail.

            Si des erreurs sont apparues au cours de la répartition, vous pouvez consulter le rapport d'erreurs .pacdispatchmacro.log dans le dossier .metadata de l'espace de travail. Ce fichier affiche également le nombre de Macros dont le code source a été modifié/créé.

         3. Modification de la cible de génération.

            Cette étape, facultative, modifie la cible de génération par défaut de l'instance avant sa migration.

         4. Aide à la migration.

            Cette étape prend en compte les sources générés par MIAn et migre les fichiers COBOL des Programmes, Ecrans et Serveurs dans l'espace de travail.

            Si plusieurs instances de la même entité ont le même nom externe dans une Bibliothèque Pacbase, les doublons sont gérés lors de la migration. Pour des détails sur cette gestion, reportez-vous à Gestion des fichiers générés en double.

         L'espace de travail issu de la commande rpp --commands peut être utilisé tel quel à des fins de consultation. Pour pouvoir faire des mises à jour ou de l'analyse d'impact, par exemple, vous devez l'indexer. Pour cela, faites un clic droit dans la vue Explorateur de designs et sélectionnez Reconstruire l'espace de travail local puis Reconstruire les liens entre les modèles et les fichiers générés.