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, Pacbase users are not migrated.
About this task

Procedure
- Migrate the users.
- 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: For information, see The Pacbase analysis and migration procedures.Pacbase administrators are granted a JazzAdmins permission, whereas the other users are granted a JazzUsers permission.
- 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
This line is constituted of the following elements:- 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 usersC:\...\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. This code must not be reused.
- Extract the users.
- Migrate a development database.
- 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). They are indicated into CS file.
- Search for the Program instances (P) to be transformed into Macros. They are indicated in the PM file.
- Search for the instances not to be retrieved (Report for PDM layout for example). They are indicated in the NR file.
- Loading of the RQ file with details of various searches (list of the instances that contain a special character for example). This file can be edited with a spreadsheet application.
Note: For information, see The Pacbase analysis and migration procedures.You must analyze the results of this procedure and complete all the required actions 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.Reminder: The COBOL code that is generated to be migrated to Rational Programming Patterns does not recognize the COBOL formatting option of the Library. - 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: For information, see The Pacbase analysis and migration procedures. - 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 that are 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 fileYou can then enter the transfer command: ftp -s:file.scr.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. Note: These parameters are given as examples. You must indicate the parameters that correspond to your environment.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 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.
XX is the set of control cards (front and back) in Pacbase on 2 characters. If there is no control card in front or back, you must enter a space in its place.
LangageDefinition is the target language definition in Rational Team Concert. It is separated from the set of control cards by a space.
- MIBA or MIBR procedure to the
MIBR.ta2 file.
- Populate the local workspace.
- 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 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.
- A ££USER Macro and a ££80EX Macro are created in the
.INTER project of the location. They cannot be copied and pasted, renamed,
moved, deleted, or modified.
These two Macros constitute the only way to implement, respectively, user services and extraction methods in Business Components. They are used to migrate the Pacbase applications. In this case, they are automatically called with the correct parameters in the -CP Lines of the relevant Business Components. If you want to implement user services or extraction methods, you must call the appropriate Macro in the -CP Lines of a Business Component and specify its parameters. The user services and extraction methods that are implemented in another way are ignored. From Rational Programming Patterns V9.5.1, they constitute inactive code that you can remove. A warning is automatically displayed in the COBOL code. This case also applies to the user services and extraction methods that were called from the function and subfunction wizard in an earlier version of Rational Programming Patterns.
Make 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 (IBM Developer for z Systems™), you must open the workspace after running rpp --automaticMigration because Rational Developer for System z (IBM Developer for z Systems) 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 - 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:- 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.
- 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.
- Modifying the generation target.
This optional step modifies the default generation target of the instance before its migration.
- 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.
- Converting the design files.
- Preparing the migration commands.
- Analyze a Pacbase database.
- The Pacbase analysis and migration procedures
Before using your Pacbase data in Rational Programming Patterns, you must migrate it to Rational Team Concert. You must first run the Pacbase database analysis and migration procedures. - Managing the errors from the MIAM procedure
The MIAM migration help procedure analyzes the Pacbase databases and detects the errors before the migration. - Importing instances
The rpp --automaticMigration command automatically imports instances. However, you can also import instances independently. You can import instances from a file that was exported with the export function of the Design Explorer view or produced by the Pacbase batch migration procedures. These instances will populate the selected location of the Design Explorer view. - Exporting instances
You can group instances into a file to be exported. You can save this file, which has an xmi extension, to any directory. When it is exported, it is available for any subsequent import with the Import function of the Design Explorer view. - Macro dispatching
The rpp --automaticMigration command automatically dispatches the Macros. However, you can also dispatch the Macros independently. The Macro dispatching function migrates, into your workspace, the Macro sources that are generated in Pacbase. You can start this function in a batch or interactive mode. - Additional step to migrate to a System z environment
If you use the Rational Team Concert builds to target a System z environment, the migration help step must be preceded by the creation of a zComponent project and of one or more zFolder folders. In this case, you must indicate the location of the sources that are produced by the migration help function. - Starting the migration help
The rpp --automaticMigration command automatically starts the migration help. However, you can also start the migration help independently. This function migrates the COBOL code of a Program, Screen, or Server that was generated in Pacbase. It copies the Pacbase COBOL code into your workspace and generates it again locally. The COBOL code that is obtained after the local regeneration is then compared with the initial COBOL code. You can ensure that the local regeneration conforms to what is expected. You can start the migration help function in a batch or interactive mode.
Feedback