Page tree
Skip to end of metadata
Go to start of metadata

Process Overview

Upgrade solution development proceeds through a series of three stages each producing specific results:

  1. Clean Translation Results

    By "Clean" we mean no errors reported during the translation process.  Translation errors occur due to missing or mis-referenced code, missing COM descriptions or other environmental issues, or by unexpected code.  If any errors are reported, they should be addressed before proceeding.
  2. Local (Stand-Alone) Build-Complete Results 

    The Local Build is a simplified build model where the resulting projects are stand-alone.  They are independent of each other even if they were cross referential in the legacy codebase.   Legacy references to COM components are replaced by references to COM files within the projects as a project-specific local "Stub Framework" .   
  3. Global (Integrated) Build-Complete Results

    The Global Build is an integrated build model where the resulting projects reference  each another.  Generally speaking, external references in the legacy projects are reproduced as external references in the new projects.  Legacy references to COM components are replaced by references to a set of generated "COM Stub Framework" assemblies.  The Stub Framework is all .NET code, but it exposes the interfaces needed to allow building the upgraded legacy projects.

The scripts for first two steps are setup more or less automatically and can normally be handled with various translation tuning techniques in a single upgrade script template. The third step requires a special type of script called a Global Stubs script.   This document describes the concepts and activities required to setup and run a GlobalStubs script and then use its output in your upgraded system to produce your Global Build.

As mentioned above, after reaching local build-complete results with stand-alone .NET projects, the next step is to reach global build-complete results with cross-referential .NET projects. In this Global Build step, the stub files that were generated for and referenced by each upgraded project become consolidated into stub projects.  The stub projects build into stub assemblies that may be linked with the upgrade projects. The collection of stub projects/assemblies is referred to as the Global Stub Framework.

The process of generating the stub framework is referred to as the GlobalStubs operation and it is done using a GlobalStubs.xml script that takes as input the VBI files and IDFs from the local build work. The upgrade rules used in the GlobalStubs script must be consistent with those used for the local build work -- although it is expected to need a few additions and changes to produce a complete, clean, and internally consistent stub framework. Clicking Report\Utility\GlobalStubs on the main menu will generate a starter GlobalStubs.xml script template for a selection of VBPs.

In addition to authoring and deploying the stub framework code, the migration team must compile the projects to assemblies that will be linked to the application projects. The GlobalStubs.bnd file contains MSBUILD commands do do this.   These commands may be placed in a GlobalStubs.cmd script that can be integrated with the gmStudio GlobalStubs task.  Presently setting up the GlobalStubs.cmd with the MSBUILD commands is a manual task.

The diagrams in this article show a system with two inter-related projects. Large applications may have dozens or even hundreds of inter-related projects; or in some cases a system will have just one VBP.  The same stages and steps apply to these cases as well. The main purpose of the Global Stubs step is to generate your Stub Framework projects and assemblies and set the a solid foundation for upgrading COM dependencies with the .NET replacements of your choice as described in this Custom COM Replacement article.


Example of Integrated Solution in gmStudio GUI

Here is an screen shot of gmStudio holding a solution that generates and integrated upgrade solution for a enterprise application comprised of 17 inter-related VBPs.  

Notice that the translations for the "Standalone" translations are larger because they contain the generated stub framework as embedded files rather than referencing the consolidated stub framework as external assemblies.


Going to the Next Level

The global build complete results  are what one might call a "direct" conversion of the source system to the target language.  They provides a solid foundation for refactoring the .NET code and adding .NET upgrade features – by tool and by hand.  The number and nature of upgrade features you will add depends on your project scope and is generally referred to as Custom Build Complete Results as shown in the following figure.


Step-by-Step Global Stubs Process

The following text describes the process to produce a GlobalStubs framework and the integrated upgraded application code for a set of VBPs. .

1) Verify that your BuildFile=local translation scripts produce build-complete results.

This step produces BuildFile=local VBI and IDF files for the VBPs.  These VBI and IDF files describe the dependencies of the VBP code and will be used to generate a stub framework for those dependencies later in this process.

2) Prepare a GlobalStubs script that references all COM IDFs that will become part of the stub framework and the VBIs for the VBPs generated from step 1. The IDF references must be placed in build order.

Select the VBPs that you used in Step 1.  Click Reports\Utilities\GlobalStubs Script on the main menu to generate a starter GlobalStubs script template for the selected VBPs.  The tool will generate the script and add it to your project as a GlobalStubs task.  In addition, this task will have an associated GlobalStubs.cmd batch file that will be used to build the Stub Framework projects.

3) Translate the GlobalStubs script.

Select the GlobalStubs task and run the Translate process from the task context menu.  The tool will produce a bundle containing the GlobalStubs framework codes: one .NET project for each COM IDF referenced in the GlobalStubs and one for the MigrationSupport IDF.

4) Deploy the GlobalStubs bundle

Select the GlobalStubs task and run the Deploy process from the task context menu. This breaks the GlobalStubs bundle file into separate .NET projects and code files that can be built using MSBuild.

5) Build the GlobalStubs projects

Select the GlobalStubs task and run the Build process from the task context menu.  This runs the GlobalStubs.cmd file that was created in Step 2 and creates a full set of stub framework assemblies that may be linked with the upgraded application codes.

6) Prepare a set of BuildFile=global translations tasks for the VBPs

See: usr\tran.ScanTool_int.xml

NOTE: these are very close the buildFile=local scripts with a few changes. Of course the big one is this:

<Select BuildFile="local" />
<Select BuildFile="global" />

I also change Library; I set it to deployFolder to simplify project-cross-references and linking to the stub framework.

<Select Library="%DeployFolder%" />


You can insert a conditional rule block (e.g. <if>) for Global stubs translations above the <Compile statement> like the example following. (this sample assumes that the Global Stubs translations have TaskTag='int')

<if id="%MigName%-%SrcName%-int-csh">
  <Select BuildFile="global" />
  <Select Library="%NetProjFolder%" />
<Compile Project="%SrcPath%" >

You may also change the setting in a ScriptRules file:

<ScriptRule id="Standard">
<Option Condition="%TaskTag%=='std'">
      <Select BuildFile="local"/>
<Option Condition="%TaskTag%=~'int|upg'">
      <Select BuildFile="global"/>
      <Select Library="%DeployFolder%" />


7) Translate, Deploy, and Build the BuildFile=global translation scripts.

This will generated, deploy, and build the global build results.

8) Generate a VisualStudio solution to reference your integrated projects

Click [Report\Utility\Generate Visual Studio Solution] on the main menu to generate a SLN file the .NET projects in your deployment space.  The tool will also generate a GenerateSolution.txt file that you may edit to include only the Global Build COM and ..NET projects. 

NOTE: Generating the VS Solution modifies the related projects so they reference their project files rather than assemblies.

  • No labels