Extracting and migrating Pacbase data

You can extract and migrate the Pacbase users and development databases. Jazz™ can be interconnected with an LDAP or a security system such as RACF®. In this case, there is no migration of Pacbase users.

About this task

The following diagram shows the extraction and migration processes of Pacbase data.
Figure 1. Overall process
This diagram shows the extraction of the users and instances from Pacbase, the generation of the Macros and Programs and their transfer to the local workspace. It also shows the local generation and the transfer of the users and the instances (models and generated files) to the Rational Team Concert server.

Procedure

  1. Migrate the users
    1. Extract the users

      Extract and transfer all the users from the administration database with the MIUS procedure.

      This procedure extracts the identifiers, names, and email addresses of users.
      Note: This procedure is explained in the Pacbase installation guide specific to your operating system.

      Pacbase administrators are granted a JazzAdmins permission, whereas the other users are granted a JazzUsers permission.

    2. Import the users into Rational Team Concert™

      Import the extracted users into Rational Team Concert. The Jazz Team Server must be running.

      Transfer the file that contains the extracted users to the machine that hosts the Jazz Team Server.

      You must first convert the ASCII file that is produced by the Pacbase extraction to the UTF-8 format. To do so, run the AsciiToUTF8.bat file that is located under the rpp directory of the Software Delivery Platform. Enter the following command line:

      AsciiToUTF8 AsciiInputFile Utf8OutputFile

      Where:
      • AsciiInputFile is the complete path to the file produced by the MIUS procedure. This file has an ASCII format.
      • Utf8OutputFile is the complete path to the file used as input to -createUsers, the standard command for the creation of users in Rational Team Concert: . This file has a UTF-8 format.
      Note: The AsciiToUTF8.bat file is designed to run from where it is delivered. So it is advised to keep it there. If you move it, you must modify it.
      To import the users, you must enter the standard command for creating users: -createUsers.
      Figure 2. Command lines for creating users
      C:\...\IBM\JazzTeamServer\server\repotools-ccm -createUsers 
      	fromFile=C:\...\MIUSFILE (after its conversion to the UTF-8 format)
       	repositoryURL=https://…:9443/ccm 
      	adminUserId=xxxx 
      	adminPassword=xxxx
      Note: The -createUsers command is explained in the Rational Team Concert help.

      The errors, if any, are displayed in the repotools-ccm_createUsers.log journal.

      A user that is already created is modified.
      Attention: The attempt to update the ADMIN user might end with a CRJAZ1350E error. So this code must not be reused.
  2. Migrate a development database
    1. Analyze a Pacbase database
      The MIAM procedure retrieves and completes some functions of the repository analysis:
      • Search for instance names that contain special characters or correspond to a Windows reserved word (for example: LPT1): Loading of the CS file.
      • Search for the Program instances (P) to be transformed into Macros: Loading of the PM file.
      • Search for the instances not to be retrieved (for example: Report for PDM layout): Loading of the NR file.
      • Loading of the RQ file with details of various searches (for example: list of the instances that contain a special character). This file can be edited with a spreadsheet application. Its description is included in the Pacbase installation guide.
      Note: Refer to the Pacbase installation guide for the complete list of the searches.

      You must analyze the results of this procedure and complete all the actions that are indicated in the Pacbase installation guide before you extract the data. For example, you must manage the special characters and the instances that have the same external name. If the database contains Database Blocks with a DB type, you must run the TRDQ procedure to transform their type into Q2 before the migration.

    2. Extract the data from Pacbase
      Extract the data with one of the Pacbase batch procedures: MIBA or MIBR.
      MIBA carries out an in-depth extraction of a list of instances. MIBR extracts all the instances of the selected Library network or subnetwork in a context (once for a session).
      Note: The MIBR procedure can be complemented by the MIBU procedure to customize the migration by taking into account design modifications (modified selection of the Segments in a Data Structure call for example).

      You can then use the MIBJ procedure to extract transactions from the Pacbase archived journal.
      Use as input two files that are produced by the MIAM procedure:
      • The PM file that contains the Programs to be transformed into Macros,
      • The NR file that contains the instances not to be retrieved.

      These procedures can replace the unrecognized special characters in an instance code with other characters. To do so, use the special characters file from the MIAM procedure and complete it.

      These procedures provide the list of the Macros to be generated with the MIMA procedure and the input for the MIA1, MIA2, MIA3, and MIA4 procedures. Remember to indicate the codes of the optional control cards to insert separators in the MIAn procedures.

      You can use the MIBR and MIBJ procedures to retrieve the Pacbase locks on the migrated instances. If the lock extraction option is indicated, script files are automatically created in the .metadata directory of the migration workspace. These files are named scmUnLock.bat to unlock the instances after the journal import and scmLock.bat to lock the instances or lock them again on the server.

      Note: All the extraction procedures are explained in the Pacbase installation guide specific to your operating system.
    3. Transfer the files
      Transfer the files to the workstation where the client parts of Rational® Programming Patterns and of the required products are installed. You must transfer the files that are produced from the various procedures to the same directory:
      • MIBA or MIBR procedure to the MIBR.ta2 file.

        If you run the MIBJ or MIBU procedure, you must transfer the transactions to a file whose extension is .ta2 but whose name is different from MIBR.

        You must also transfer the list of the generated entities to the MIA1.txt, MIA2.txt, MIA3.txt, and MIA4.txt files.

      • MIMA procedure to the MIMA.cblgen file.
      • MIA1 procedure to the COBOL_MIA1.txt and CONTROL_COBOL_MIA1.txt files.
      • MIA2 procedure to the COBOL_MIA2.txt and CONTROL_COBOL_MIA2.txt files.
      • MIA3 procedure to the COBOL_MIA3.txt and CONTROL_COBOL_MIA3.txt files.
      • MIA4 procedure to the COBOL_MIA4.txt and CONTROL_COBOL_MIA4.txt files.
      Important: You must be careful with the code pages used upon the transfer.
      To transfer a file from a System z® environment (English EBCDIC) to the workstation with FTP, you must enter the following lines in a file.scr file
      Table 1. FTP transfer commands to enter
      Command lines to enter Explanations
      open hostname Replace hostname with the source host address.
      tsouid Replace tsouid with the TSO user.
      tsopwd Replace tsopwd with the TSO password.
      quote site sbdataconn=(IBM-1047,ISO8859-1) Parameters for transferring the English EBCDIC to ASCII.
      quote site notrailingblanks Parameter for removing blank characters at the end of the records
      get 'zFileName' c:\LocalFileName Frame the name of the System z file with simple quotation marks (it defaults to 'tsouid').
      quit  
      You can then enter the transfer command: ftp -s:file.scr.
      Optional files can also be copied into this directory:
      • If COBOL files have been generated with a Microfocus COBOL type (COBOL type 3 : UNIX, Windows), you must also copy the transform.txt file into this directory. This file is available in the installation directory of your Rational Software Delivery Platform, under rpp/migration. It corrects the generated COBOL syntax to make it compatible with the IBM® compiler. It contains five default rules but you can add rules or modify the existing rules, except the first one. This first rule adds dots in the WORKING-STORAGE SECTION and the PROCEDURE DIVISION (before the tags). The other rules are built around a regular expression and its replacement string.
        Note: To restore the syntactic control of the COBOL files, you must select the preference COBOL syntax for type 3 (UNIX, Windows) certified as compatible with IBM COBOL for AIX syntax after the migration. You access it by selecting Window > Preferences > Pattern Driven Programming > Pacbase patterns.
      • If you want to create Error Message instances, you must create an errorLabels.txt file and copy it into the migration directory. This file must contain as many lines as Error Message instances to be created. Each line must conform to the following syntax:
        • The Pacbase generation command (GED, GEO, GEC, or GES).
        • The generation Library.
        • After a space, the associated Data Structure or Dialog.
        • After a space, an optional generation option (C1 to C4). If this option is not indicated, C1 is the default value.
        • After a space, the name that will be given to the new Error Message instance.
        Example: GEDCEN DD C1 ERROR1
      • If you want the Pacbase specific error message file (extracted with the MILA procedure) to be recognized by default in the Rational Programming Patterns Error Message instances, you must copy this file into this directory and name it specificErrorLabel.txt.
      • If you want to map Pacbase sets of optional control cards with z/OS® language definitions, you must create an inputzCompMap.txt file and add it to this directory.

        This file must contain one line for each mapping, according to the following format:
        XX LangageDefinition
        where:
        XX is the set of the control cards (front and back) in Pacbase,
        LangageDefinition is the target language definition in Rational Team Concert.

    4. Populate the local workspace
      1. Preparing the migration commands

        Run the rpp --automaticMigration command. This command creates the command file that is used to run the import, dispatch the Macros, modify the generation target (if it is requested), and run the migration help. It creates the directories of the migrated sources by splitting the various programs. You must conform to the structure of the directory that contains the transferred files. See section Transfer the files.

        The automatic migration command optionally completes the following steps:
        • The Microfocus COBOL files are transformed if the transform.txt file is present in the migration input directory. The rules that are contained in this file are used to make the COBOL syntax compatible with the IBM compiler. An ORIGINAL_COBOL directory is created to keep the original version of the modified COBOL files.
        • The Pacbase sets of optional control cards are mapped with z/OS language definitions if the inputzCompMap.txt is present (see the information on the rpp --automaticMigration command). The migration creates as many mapping files as z/OS COBOL projects for the rpp-zcompmap command. By default, these files are generated in the metadata/zCompMap directory of the migration workspace.
        • The specificerrorLabel.txt file is copied into the .INTER project of the location, if it is present in the migration input directory. Then, when an Error Message instance is generated, if no file is indicated in its Specific error message file field, the specificerrorLabel.txt file will be automatically recognized.
        • If an errorLabels.txt file is present, an MIBR_modified.ta2 file is created. This file contains the data that is extracted from Pacbase and the Error Message instances that are to be automatically created when the import command is run. This import command then uses this MIBR_modified.ta2 file. The initial file that is produced by the Pacbase extraction is never modified. The script to be run is automatically modified according to the presence or absence of the MIBR_modified.ta2 file.

        Be sure to correctly use the parameters to create the projects that contain the COBOL sources. These projects can be zComponent projects or standard projects.

        Information is available on the Progressive migration and the Multi-session migration.

        The automatic migration produces a location.txt file (where location is the name of the location).

        Example of an automatic migration command that creates a zComponent project and separates the COBOL source files from the Rational Programming Patterns metadata files. The metadata files will be stored in the design directory:

        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: The rpp --automaticMigration command creates a workspace. This workspace is not indexed. So, opening it before uploading it to Rational Team Concert is not recommended. However, you might have to open it in some cases. If Rational Programming Patterns is installed on top of Rational Developer for System z, you must open the workspace after running rpp --automaticMigration because Rational Developer for System z automatically duplicates the workspace upon its opening. The duplication time is limited because the workspace contains only a small amount of data then. If you open the workspace after running the command file, the duplication time will be much longer
      2. Running the command file
        Run the rpp --commands command and indicate the location.txt file as an option.
        Figure 3. Syntax of rpp.bat
        Syntax: rpp.bat --commands [options]
                --data - workspace. (required)
                --log - Log file name. (trace.log by default)
                --file - File containing the list of batch commands. (required)
                --exitOnError - Exit in case of error on a command.
        The following steps are completed:
        1. Converting the design files

          This step initializes a local workspace that contains a hierarchy of projects. Each project contains the instances that belong to a  Pacbase Library.

          Error Message instances are created if an errorLabels.txt file is present in the migration input directory.

          To validate the import, you can analyze the errors that are contained, by default, in the .pacmigration.log file in the .metadata folder of your workspace. This file summarizes the contents of the imported .ta2 file. It displays the following information:
          • The context of the import such as the database, user, session, Library, and date.
          • The replaced special characters.
          • The statistics of the instances that are present in the .ta2 file. These figures include the instances that were duplicated by the migration procedures.
          • The errors that were detected upon the import.
          • The Data Structures and Dialogs that were duplicated by the import.
          • The number of imported instances and the number of the instances in the .ta2 file. The number of imported instances can be lower than the number of the instances in the .ta2 file if you import a new Pacbase session into the same workspace. In this case, the instances that were not modified are not counted among the imported instances.
          • The number of modified/created/deleted design entities.
        2. Dispatching the Macro source files

          This step recognizes the file that is produced by the MIMA procedure. It assigns the Macro sources to the corresponding Macros of the projects in your workspace.

          If errors occurred during the dispatch, you can consult the .pacdispatchmacro.log error file in the .metadata folder of your workspace.

        3. Modifying the generation target

          This optional step modifies the default generation target of the instance before its migration.

        4. Migration help function

          This step recognizes the source files that are generated by MIAn and migrates the COBOL files of Programs, Screens, and Servers into the workspace.

          If several instances of the same entity have the same external name in a Pacbase Library, the duplicate files are managed upon migration. For explanations about this management, see Managing duplicate generated files.

        The workspace that is created by the rpp --commands command can be used as is for a lookup only. To complete some updates or an impact analysis, for example, you must index it. To do so, right-click the Design Explorer view. Select Rebuild local workspace and Rebuild mappings between designs and generated files.


Feedback