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 also 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.

      Note: These procedures are explained in the Pacbase installation guide specific to your operating system.
    3. Transfer the files
      Transfer the files to the workstation on which 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, MIBR, or MIBJ procedure to the MIBR.ta2 file. 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.
    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.

        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 automatic migration 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 the automatic migration 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

        The workspace that is created by the automatic migration 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.

        After running the automatic migration, you must start Rational Programming Patterns in graphic mode (Start > All programs > IBM Software Delivery Platform > IBM Rational Programming Patterns by default). Enter the name of the workspace that is to be used upon the migration.

      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 carried out:
        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.

          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.


Feedback