Set the Build Order

This page describes the Set Build Order migration step.

VB6 Build 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.

Note

Translation Order

The build order also applies to translation: the referenced components must be translated before the referencing components are translated. gmStudio “learns” about your components when it translates them and it uses that information in translating codes that depend on them.

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.

Tip

Circular References

If the migration units being ordered contain circular references, gmStudio will report this in the build order log and will not compute the build order for those units. The circular references will continue to cause issues in processing your codes and ultimately in the .NET version of your system. If circular references are discovered, you should rework your dependencies to remove them. Note that gmStudio can be configured to restructure your application model to replace circular references with interface references.

ASP Build Order - Classifying Web Site Files

An ASP site directory may contain many types of files. A critical task in preparing for translation is identifying the files that contain “active” content: server-side VBScript blocks, embedded script tags, and various ASP processing directives.

The first step is selecting the files to include in your web upgrade project. The active files will typically have an ASP extension, but may also be named HTM or whatever the legacy site developers wanted. The files are specified as a list of file wildcard patterns (*.asp, *.asa, *.inc, *.htm) in the New Project Wizard or the Add Files dialog. Once that is done, you will use the Set Build Order operation from the Tools menu to classify the files. This process will examine the names and content of files and identify them as PAGE, INCLUDE, or PULP:

• PAGE files are those that get processed by the ASP handler on the web server. Any file having an ASP extension will be initially identified as a PAGE. 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 translation order.
• PULP files are part of the site but have little effect on ASP processing (images, client-side JS files, static HTML, style sheets). Generally these files can be excluded from the migration project unless you want them in your project for convenience. Initially all files not having an ASP or ASA extension are classified as PULP.
• INCLUDE files are those that are found in an #include tag in any other file. An include file may have any extension, but most of the time the extension is INC or ASP. The only requirement for classifying a file as INCLUDE is that it is found included by some other file. During processing, files initially classified as type PAGE or PULP may change to type INCLUDE.

The Tools → Set Build Order option classifies the files in the web upgrade project. This process only orders the tasks that are present and selected in the task list; however, during a default batch run, all tasks will be selected automatically.

Clean Out the Kruft!

ASP is a scripting platform with just‑in‑time processing. It is quite common for inactive files to accumulate on a web site, since they are usually ignored by the site at runtime. However, when it is time to prepare site files for a migration, kruft files confound the process. Kruft files might contain anything: malformed code, obsolete code, work‑in‑progress code that was abandoned, that code you created to prank your coworkers—anything goes. Unfortunately, attempting to translate these files is a waste of resources and is also likely to result in translation and build errors. The upgrade project presents a great opportunity to identify and clean out the kruft. The good news is you do not actually need to delete these files from the source folder; just make sure they are not included as tasks in your web upgrade project.

Translating Web Files - Do Not Translate INCLUDE Files

Generally speaking, translations are directed by translation scripts that reference one or more PAGE files. You should not translate files that are classified as INCLUDE. INCLUDE files will be processed in the context of the PAGES that reference them. Most of the time, PULP files can simply be copied over from the legacy site to the new site. One edge case is PULP files that reference file.asp (for example, in a redirect). These should be translated so that the redirect changes to reference file.aspx.

---

If you’d like, I can next help standardize the headings and inline code formatting across the rest of this page, or adjust the tone to be more formal/concise.

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.