Legacy Migration Sample

Objective

The objective of this sample is to help you migrate from earlier versions of VisualAge C++. It also illustrates how to use existing DLLs and static libraries (built with prior versions of VisualAge C++) with version 4. For more information on migrating from earlier versions of VisualAge C++, refer to the Migrate to VisualAge C++ Version 4.0 section under Tasks.

The sample is organized in a set of steps, where each step corresponds to a the results of a stage in the migration process.

Step 1: Start

This is the application before it has been migrated. It consists of the following elements:

File Description
main.exe Program executable
payroll.dll Program DLL
payroll.lib Import library for payroll.dll
title.lib Static library, built from C source

Step 2: Generate configuration files

In this step, the make2cfg utility is used to convert the program's makefile into a configuration file. For more information on the make2cfg utility, see Convert Makefiles to Configuration Files.

Make2cfg produces three configuration files.

clean.icc
Clean was a target in the makefile which deleted all the products of the make. It is not needed in VisualAge C++ 4.0, since the IDE's Project Workbook menu contains the item Clean which will delete all targets for a project. The file clean.icc can be deleted.
main.icc
This configuration file produces main.exe.
payroll.icc
This configuration file produces title.lib, payroll.dll and payroll.lib.

The makefile contains rules for building payroll.lib. In VisualAge C++ 4.0, payroll.lib is automatically generated when the link(exportAll) option is specified. However, make2cfg produces entries in payroll.icc and main.icc to explicitly generate this file. These entries should be removed.

Add the option link(exportAll) to the options used to build payroll.dll. This option will generate the export library for payroll.dll.

In order to show how to use a library or object file purely as input to the build process, in payroll.icc comment out the stanza building title.lib.

Step 3: Migrate main.exe, use forwarding DLLs

In this step, a migration build is run on the main.icc configuration file. For more information on migration builds, see Migrate Source Files. The file payroll.icc will be migrated in a later step.

To run a migration build on main.icc using the IDE, open the project main.icc. Select no when prompted to begin a build. Select Migration Build from the Tools menu. Once the migration build has completed successfully, restart the IDE and run a regular build on main.icc.

At this stage, main.exe is built using VisualAge C++ 4.0 and payroll.dll is built with a prior version of VisualAge C++. This next part of this step is intended to show you how to produce a working application where the executables and DLLs are not all built with the same level of VisualAge C++. This would not be necessary if payroll.dll was migrated to VisualAge C++ 4.0.

When main.exe is run, it generates a trap. The trap occurs at line 16 in the payroll() function in payroll.dll, on the delete s; statement. The character array s is allocated in code associated with main.exe and is deleted in code associated with payroll.dll. The problem occurs because main.exe is using the VisualAge C++ 4.0 C/C++ runtime, while payroll.dll is still using the C/C++ runtime from the prior version of VisualAge C++. This is an artificially induced problem, but it is indicative of the many problems than can occur when more than one C/C++ runtime is used by a single process.

This problem can be solved by using forwarding DLLs. The forwarding DLLs look like the old runtime to old executables and DLLs, but a single copy of the version 4.0 runtime is used under the covers.

For more information on forwarding DLLs, see Use DLLs and Executable Modules Created in Previous VisualAge Releases. ( Note: On AIX, the target page of the preceeding link is not in the online documentation)

To determine what runtime payroll.dll uses, enter

dllrname payroll.dll
in a VisualAge C++ command window. This will list all the DLLs used by payroll.dll.

The file cppws35i.dll is the Windows VisualAge C++ 3.5 runtime dll used by the application. Based on the mappings found in Use DLLs and Executable Modules Created in Previous VisualAge Releases, the correct forwarding DLL is cppzsi40.dll. To convert payroll.dll to use this forwarding DLL, enter

dllrname payroll.dll cppws35i=cppzsi40
in a VisualAge C++ command window. The application will now run successfully.

The file cppos30.dll is the OS/2 VisualAge C++ 3.0 runtime dll used by the application. Based on the mappings found in Use DLLs and Executable Modules Created in Previous VisualAge Releases, the correct forwarding DLL is cppzs40.dll. To convert payroll.dll to use this forwarding DLL, enter

dllrname payroll.dll cppos30=cppzs40
in a VisualAge C++ command window. The application will now run successfully.

Step 4: Migrate payroll.dll, combine the configuration files

In this step, payroll.dll will be migrated to VisualAge C++ 4.0, and then the two configuration files will be merged.

To migrate payroll.dll, start the IDE, and open the project payroll.icc. Select no when prompted to begin a build. Select Migration Build from the Tools menu. Once the migration build has completed successfully, restart the IDE and run a regular build on payroll.icc.

Since the application is built as two projects, the IDE is not able to access all the information about the application. This can be corrected by combining the two configuration files. To combine the configuration files, in a command window enter

copy payroll.icc+main.icc combined.icc

In combined.icc, one of the sources for the target main.exe is the import library payroll.lib. This is not needed in the combined configuration file, and should be removed. Also remove the duplicate definitions of compatibility_options from the combined.icc file.

The combined configuration file can now be build using a regular build. Press the Build button on the IDE's toolbar, or select Build from the Project Workbook menu.

Step 5: Build title.lib

In this step, title.lib is built as part of the project. This library could continue to be used as is, but if it where a C library still under development, or being maintained, changing it using VisualAge C++ 4.0 is possible.

To do this, uncomment the stanza to build this library in combined.icc, and rebuild.

Step 6: Convert to using ISO C++ streams library.

First, in file combined.icc, remove the following lines from the stanza for the target payroll.dll:

   option macros('global', 'yes')
   {
      source type('cpp') 'iostream.h'
   }

Then, remove all the lang(nokeyword) options from compatibility_options, and also remove the gen(mangleLinkageKeywordOnlyFuncs,no) option.

In the IDE, press the Search button on the Project Combined tab. Search for iostream. This string will be found in payroll.cpp, where there is the statement

#include <iostream.h>
Change this to
#include <iostream>
using namespace std;

Step 7: Optimize the configuration file

An optimized configuration file makes builds more efficient. The configuration files were optimized as part of the migration step, but since the program now uses different header files, the config file should be re-optimized.

For more information on optimizing configuration files, see Optimize Configuration Files

To optimize the configuration, select Optimize Configuration from the Tools menu in the IDE.


Supported
Supported
Not Supported