Set the Build Order

This page describes the Set Build Order migration step.

VB6 Migration Order

Many large VB6 systems are composed of multiple inter-related components. For example, your executables (EXEs) reference your libraries (DLLs) and controls (OCXs). The references between components define a dependency-first build ordersuch that referenced components must be built before referencing components.

gmStudio sets the build order for your migration project when you select [Tools/Set Build Order] from the menu. The process only orders the tasks which are selected in the task list. Note that at the beginning of a default batch processing cycle, all tasks will be selected for you, so the build order and other preparation tasks can be applied to the entire set.

VB6 Build Order Outputs

The "Set Build Order" operation saves a Build Order Reportin the workspace\reports folder.

A sample build order report for the Interop2_csh.gmproj sample is shown below. This report shows that ScanToolLib.vbp (a DLL) is ordered 1st and ScanToolUI.vbp (an EXE which depends on the ScanToolLib DLL) is ordered 2nd.

   Source Extraction Tool V9.77 (BETA.007) System Build(6/18/09 8:40:51)
   The ordering over 2 projects converged.
   There were 1 order test iterations
   (1)C:\gms\samples\source\ScanTool\ScanToolLib_VB6\ScanToolLib.vbp
      (I)*\G{00020430-0000-0000-C000-000000000046}#2.0#0#..\..\..\..\WINDOWS\system32\stdole2.tlb#OLE Automation
      (x)*\G{8B217740-717D-11CE-AB5B-D41203C10000}#1.0#0#..\..\..\..\WINDOWS\system32\TLBINF32.DLL#TypeLib Information
      (I)*\G{420B2830-E718-11CF-893D-00A0C9054228}#1.0#0#..\..\..\..\WINDOWS\system32\scrrun.dll#Microsoft Scripting Runtime
      (x)*\G{F5078F18-C551-11D3-89B9-0000F81FE221}#4.0#0#..\..\..\..\WINDOWS\system32\msxml4.dll#Microsoft XML, v4.0
   (2)C:\gms\samples\source\ScanTool\ScanToolUI_VB6\ScanToolUI.vbp
      (I)*\G{00020430-0000-0000-C000-000000000046}#2.0#0#..\..\..\..\WINDOWS\system32\stdole2.tlb#OLE Automation
      (I)*\G{420B2830-E718-11CF-893D-00A0C9054228}#1.0#0#..\..\..\..\WINDOWS\system32\scrrun.dll#Microsoft Scripting Runtime
      (0)*\G{8ABED115-2D9A-49A3-9A8F-6CB393F19FE7}#1.0#0#..\ScanToolLib_VB6\build\ScanToolLib.dll#ScanTool Scanner Library
      (I){F9043C88-F6F2-101A-A3C9-08002B2F49FB}#1.2#0; ComDlg32.OCX

The build order algorithm uses the explicit COM references and names of the build products specified in the VBP files.

The build order process produces a report that lists all references and assigns an order code to each:

• (#) a local component where # is a number indicating the build order sequence
   
• (I) an external component whose IDF was found in the IDF cache
   
• (X) an external component whose IDF was not found in the IDF cache

gmStudio saves the build order by setting the SrcOrdr field of each migration task, and then sorting the task list by SrcOrdr.

Web Migration Order

Large ASP web sites make extensive use of the #include directive to facilitate reuse of markup and logic across the pages. Web sites contain files of three different types:

• Page files are those that get processed by the ASP handler on the web server. Pages typically have an ASP extension. 
• Include files are those that are #included from pages or from other #include files.  
• Pulp files are part of the site, but have no effect on ASP processing (images, client-side scripts, static html, style sheets)

The global.asa is a special case of a Page file. If a global.asa file is found, it is assigned the first position in the include order.

The [Tools/Set Build Order] option sets the include order for the migration units in a web site. This process only orders the tasks which are selected in the task list; however, during a default batch run, all tasks will be selected for you.

Web Build Order Outputs

The "Set Build Order" operation saves a Build Order Report in the workspace\reports folder.

A sample build order report for the DemoFMSWeb_csh sample is shown below.

Source Extraction Tool V9.77 (BETA.007) System Build(6/18/09 8:40:51)
The ordering over 33 pages converged.
There were 7 references missing:
 1. FMSStore_Bus from FMSStore_Bus.ShoppingCart
 2. FMStocks_Bus from FMStocks_Bus
 3. ADODB from ADODB
 4. FMStocks_ext from FMStocks_ext
 5. FMStocks_DB from FMStocks_DB
 6. FMSStore_Bus from FMSStore_Bus
 7. FMStocks_Bus from FMStocks_Bus.Account
There were 1 order test iterations
(1)\gmSrc\GMDemo\FMStocks\FMSWeb\ASP\strings.asp
(2)\gmSrc\GMDemo\FMStocks\FMSWeb\ASP\t_head.asp
   (1) Include: \gmSrc\GMDemo\FMStocks\FMSWeb\ASP\strings.asp
(3)\gmSrc\GMDemo\FMStocks\FMSWeb\ASP\t_begin.asp
(4)\gmSrc\GMDemo\FMStocks\FMSWeb\ASP\t_begin_cart.asp
   (3) Include: \gmSrc\GMDemo\FMStocks\FMSWeb\ASP\t_begin.asp
(5)\gmSrc\GMDemo\FMStocks\FMSWeb\ASP\t_end.asp
(6)\gmSrc\GMDemo\FMStocks\FMSWeb\ASP\_about.asp
   (2) Include: \gmSrc\GMDemo\FMStocks\FMSWeb\ASP\t_head.asp
   (3) Include: \gmSrc\GMDemo\FMStocks\FMSWeb\ASP\t_begin.asp
   (5) Include: \gmSrc\GMDemo\FMStocks\FMSWeb\ASP\t_end.asp
'. . . LINES REMOVED . . .'
(33)\gmSrc\GMDemo\FMStocks\FMSWeb\ASP\ViewProduct.asp
   (2) Include: \gmSrc\GMDemo\FMStocks\FMSWeb\ASP\t_head.asp
   (4) Include: \gmSrc\GMDemo\FMStocks\FMSWeb\ASP\t_begin_cart.asp
   (5) Include: \gmSrc\GMDemo\FMStocks\FMSWeb\ASP\t_end.asp

The include order algorithm uses the #include statements in the web files. It produces a report that lists the pages and the targets of the include statements.

The report may also list missing COM externals -- those for which IDFs could not be found in the IDF cache.

gmStudio saves the build order by setting the SrcOrdr field on each migration task, the SrcOrdr values are given a prefix to reflect the content type of each file ('_' = Page, '#' = Include, or '~'=Pulp). The name of the content type is also saved in the BldType field for each file.

Using Content Types

Presently, gmStudio does not do anything with your pulp files. Pulp files such as images, static html, style sheets, etc. that are not processed by the ASP handler should be moved "as is" to the target site folder. This can be done manually as part of setting up the migration test environment or it can be done using User Batch command associated with a task in your migration project.

Ignoring pulp files, the question becomes: what to do about pages and includes? The answer is the PageSlice. A PageSlice consists of an ASP (or global.asa) file and all files it includes directly or indirectly. When gmStudio migrates a website it only needs to process the PageSlices. There is no need to process included files explicitly because they are processed in the context of the PageSlices. In theory, PageSlices can be processed in any order; so, the purpose of setting an include order is to set the file content types, not to set the file processing sequence. The content types come into play when you generate the multi-unit script for your site later in the preparation process. For example, the DemoFMSWeb_csh sample site directory contains about 78 files, but there are only 28 pages. The multi-unit site migration script contains the following commands to process the pages. The includes are processed implicitly be these commands as well.

   <!-- Compile the site -->
   <Compile PageSlice="\gmSrc\gmDemo\FMStocks\FMSWeb\ASP\_about.asp" />
   <Compile PageSlice="\gmSrc\gmDemo\FMStocks\FMSWeb\ASP\_GetXMLPortfolio.asp" />
   <Compile PageSlice="\gmSrc\gmDemo\FMStocks\FMSWeb\ASP\_GetXMLTickerHistory.asp" />
      ' ... LINES REMOVED ... '
   <Compile PageSlice="\gmSrc\gmDemo\FMStocks\FMSWeb\ASP\_NewAccount.asp" />
   <Compile PageSlice="\gmSrc\gmDemo\FMStocks\FMSWeb\ASP\TickerDetail.asp" />
   <Compile PageSlice="\gmSrc\gmDemo\FMStocks\FMSWeb\ASP\TickerList.asp" />
   <Compile PageSlice="\gmSrc\gmDemo\FMStocks\FMSWeb\ASP\ViewProduct.asp" />

Customizing Migration Order

The build order produced by gmStudio is directly influenced by the original order of units in the migration project file. Consequently, the results may not fit your ideal conceptual ordering of units and you may wish set the order manually after the automated ordering. This is accomplished as follows:

1. Click [Save] on the Toolbar; this will save any work in progress to the project file. 
2. Click [Edit] on the Toolbar; this will save the tasks to a tab-delimited file ([migration_name].tab) in the same folder as your gmProj file and open it with whatever application is associated with (*.tab) files. In our environment this opens the file in a spreadsheet application. 
3. Use the editor (e.g., the spreadsheet application) to hand edit the SrcOrdr fields and then re-sort the list by SrcOrdr. 
4. Save the *.tab file as plain text -- making sure to preserve the tab characters. 
5. Click [File/Load Task List] to reload the tasks from the tab-delimited file.

A migration solution for a complex system is likely to  contain custom processing steps to analyze and transform the code using advanced techniques (e.g. COM+ to WCF, Advanced Error Handling, Shared Files consolidation, etc.)  These custom processing steps are implemented with migration scripts that must be executed  in a specific sequence when the migration solution runs and you will need to manually set the order of these files in your migration project.  You can tell gmStudio to omit those files from the build order process by manually setting the SrcOrder field of your custom tasks to begin with an exclamation point.  Our convention is to use \!A, \!B, \!C, etc..  See the ScanTool sample for an example.