IncludeOrder Statement Summary

IncludeOrder is a terminal or nonterminal, utility statement that can occur only in command scripts. This statement computes the processing order of web site components based on their includes. The introduction of PageSlices largely deprecated the need for this statement; however, it is still useful for finding missing includes and missing references.

The terminal form of the IncludeOrder statement writes a report describing the results of the analysis. The nonterminal form authors a script contained in its substatements that can include the references found and the names of the pageslice files that have to be processed.

A command script using the IncludeOrder statement follows the following general form.


   <gmBasic>
      <Storage Action="Create" ... />
      <Select Local="..." />
      <Select System="..." />
      <Select Target="..." />
      <Load Page="filename(1)" />
           ...
      <Load Page="filemame(n)" />
      <Output Status="New" Filename="..." />
      <IncludeOrder ...
      <Storage Action="Close" />
   </gmBasic>

A major piece of the analysis performed by this statement involves finding all references to external components in the web site pages and verifying that those components are described via reference scripts stored in the search locations to be used when doing the translations. Therefore, those search locations must be specified here. The Load Page statements simple load the raw files into text buffers in the storage area so that they can be searched for external references and for includes.

The attributes of the IncludeOrder statement are as follows:

Attribute	Description
Identifier	This attribute is only used with the nonterminal form. It is a semicolon-delimited character string containing the parameter strings to be used when writing the substatement script. Each input record in that script is search for entries like %1d or %2d, etc. These are then replaced by the corresponding entry in this list.
Filename	This attribute limits the analysis performed to the single page named by this attribute. This page must be one of the pages loaded. It can be helpful when initially setting up or for debugging particular issues that may be associated with the page.

The script errors associated with the IncludeOrder statement are as follows:

Error	Description
1121	Unable to locate requested file: %1d
1122	Encountered EOF while reading search information.

The report generated by the terminal form IncludeOrder statement begins with three statements


   The ordering over %d pages converged.
   There were %d references missing:
       list of missing references
   There were 1 order test iterations

Then the pages loaded, or the single one requested along with its includes, are listed in their suggested build order along with a listing of the files that they include.

The intent of the report generated by the nonterminal form of the command is to author the actual command script to be used to do the PageSlice oriented site translations. In is described in the Fmstocks topic.

Creating the Fmstocks Site Translation script

This discussions uses the Fmstocks sample ASP site to show how the IncludeOrder utility statement is used to aid in the creation of an initial PageSlice oriented translation command script. The Fmstocks code base consists of a set of VB6 projects and then a collection of ASP pages, some of which are only includes, that reference those projects. The assumption here is that the VB6 code has been translated and the libraries that it created have descriptions in the Local search location.

The first step is the create the initial IncludeOrder command script that will give an analysis report. This might look as follows


   <gmBasic>
      <Storage Action="Create" />
      <Select Local="C:\gmProj\FmStocks\IDF\FromCode" />
      <Select System="C:\gmProj\FmStocks\IDF\FromIDL" />
      <Select Target="C:\gmProj\FmStocks\IDF\FromIDL" />
      <Load Page=
          ...
      <Output Status="New" Filename="Order0.lst" />
      <IncludeOrder />
      <Storage Action="Close" />
  </gmBasic>

The problem, of course, are the Load Page statements. Web sites can contain thousands of pages. A simple way of generating this script is needed. In addition to the utility statements embedded within gmBasic there are also external utility statements available that are created via the gmNI and discussed under the gmNI Utilities topic. One of these is the LoadSite utility than is designed for just this type of situation. The command script needed to generate the needed IncludeOrder command script is simply


   <gmBasic>
   <Storage Action="Create" />
   <LoadRuntime dllName="Document.dll" />
   <Output Status="New" Filename="Order0.xml" />
   <LoadSite Directory="C:\gmSrc\fmstocks\WebSite" Extensions="asa,asp" >
   <gmBasic>
      <Storage Action="Create" />
      <Select Local="C:\gmProj\FmStocks\IDF\FromCode" />
      <Select System="C:\gmProj\FmStocks\IDF\FromIDL" />
      <Select Target="C:\gmProj\FmStocks\IDF\FromIDL" />
      <Load Page="%filename%" />
      <Output Status="New" Filename="Order0.lst" />
      <IncludeOrder />
     <Storage Action="Close" />
   </gmBasic>
   </LoadSite>
   <Storage Action="Close" />
  </gmBasic>

Running the command script produces an Order0.xml file that contains the needed set of Load Page statements. Running that script produces a report


   The ordering over 33 pages converged.
   There were 6 order test iterations
       ...

showing no missing references or missing includes, so the actual translation script can be authored by modifying the IncludeOrder statement in the script.


   <IncludeOrder Identifier="FmstockWeb;csh" >
   <gmBasic>
      <Storage Action="Create" Identifier="%1d"/>
      <Select DevEnv="VS2010" />
      <Select Dialect="%2d" />
      <Select Local="C:\gmProj\FmStocks\IDF\FromCode" />
      <Select System="C:\gmProj\FmStocks\IDF\FromIDL" />
      <Select Target="C:\gmProj\FmStocks\IDF\FromIDL" />
      <Select DeployLocation="C:\gmProj\FmStocks\Deploy\%1d_%2d" />
      <Select VirtualRoot="C:\gmSrc\FmStocks\WebSite" />
      %references%
      %compile%
      <Analyse />
      <Output Status="New" Filename="%1d.bnd" />
      <Author />
      <Storage Action="Close"/>
   </gmBasic>
   </IncludeOrder>

Running this script now produces the desired translation command script.


   <gmBasic>
      <Storage Action="Create" Identifier="FmstockWeb"/>
      <Select DevEnv="VS2010" />
      <Select Dialect="csh" />
         ...
      <Select DeployLocation="C:\gmProj\FmStocks\Deploy\FmstockWeb_csh" />
      <Select VirtualRoot="C:\gmSrc\FmStocks\WebSite" />
      <reference id="FMStocks_Bus.dll"/>
      <reference id="FMSStore_Bus.dll"/>
      <reference id="msado25.tlb"/>
      <reference id="FMStocks_Ext.dll"/>
      <reference id="FMStocks_DB.dll"/>
      <compile pageslice="C:\gmSrc\fmstocks\WebSite\401k.asp"/>
      <compile pageslice="C:\gmSrc\fmstocks\WebSite\AccountSummary.asp"/>
          ...
     <Analyse />
     <Output Status="New" Filename="FmstockWeb.bnd" />
     <Author />
     <Storage Action="Close"/>
 </gmBasic>

The name of the script and the desired dialect have been filled in. The meta variable %references% has been replaced by the set of needed Reference statements and the meta variable %compile% has been replaced by the needed set of Compile PageSlice statements.

Table of Contents

IncludeOrderStatement

IncludeOrder Statement Summary

Creating the Fmstocks Site Translation script