gmslExecuteClass

Owned by Mark Juras
Last updated: Jul 25, 2018Version comment

The Execute Service Class

The class Execute executes the mainline translation operations performed by gmBasic. The individual methods correspond exactly with the gmPL commands of the same name, have parameters whose names match the attribute names of the corresponding gmPL command, and literally execute the same implementation code in the tool. In addition to the matching parameters the ability of gmPL commands to process embedded refactoring and fix commands is also implemented in this class via the use of the #textstart command.

A gmSL Translation Script

To show the correspondence between the gmPL commands and the Execute methods, the following is a simple gmPL translation script. The mainline commands are highlighted. 


<gmBasic>
   <Storage Action="Create" Identifier="vb001" />
   <Select DevEnv="VS2008" />
   <Select Dialect="csh" />
   <Select BuildFile="on" />
   <Select AuthorLibrary="Deploy" />
   <Select UseInterfaces="on" />
   <Select computeConditional="on" />
   <Registry Type="idfstatus" Source="stdole2.tlb" Target="migrate" />
   <Registry Type="idfstatus" Source="MSVBVM60_3.dll" Target="migrate" />
   <Select Local="C:\gmProj\VB6TestCSH\idf\FromCode" />
   <Select System="C:\gmProj\VB6TestCSH\IDF\FromIDL" />
   <Select Target="C:\gmProj\VB6TestCSH\IDF\FromIDL" />
   <Select DeployLocation="C:\gmProj\VB6TestCSH\Deploy\VB001_csh" />
   <Compile Project="C:\gmSrc\GMTest\vb6test\VB0001\vb6\VB0001.vbp" />
   <Analyse />
   <Output Status="New" Filename="vb001.bnd" />
   <Author />
   <Storage Action="Close" />
</gmBasic>
The following file, with the extension gmSL, produces the identical result as the file above. In this case the mainline Execute method calls are highlighted. 


Execute.Storage Action:="Create", Identifier:="vb001"
Select.DevEnv = "VS2008"
Select.Dialect = Dialects.csh
Select.BuildFile = BuildFileStatus.On
Select.AuthorLibrary = AuthorLibType.Deploy
Select.UseInterfaces = true
Select.computeConditional = "on"
Execute.Registry Type:="idfstatus", Source:="stdole2.tlb", Target:="migrate"
Execute.Registry Type:="idfstatus", Source:="MSVBVM60_3.dll", Target:="migrate"
Select.Local = "C:\gmProj\VB6TestCSH\idf\FromCode"
Select.System = "C:\gmProj\VB6TestCSH\IDF\FromIDL"
Select.Target = "C:\gmProj\VB6TestCSH\IDF\FromIDL"
Select.DeployLocation= "C:\gmProj\VB6TestCSH\Deploy\VB001_csh"
Execute.Compile Project:="C:\gmSrc\GMTest\vb6test\VB0001\vb6\VB0001.vbp"
Execute.Analyse
Execute.Output Status:="New", Filename:="vb001.bnd"
Execute.Author
Execute.Storage Action:="Close"
In this example the standard gmSL free-form method call syntax is used to bring out the similarities of the two notations. In gmSL attribute names are separated from their value with := as opposed to simply =, and the name-value pairs must be separated by commas.

A Complex gmSL Translation Script

Complex, as well as simple, translations can be performed using gmSL as well. Even scripts with complicated fixes and/or refactoring can be written. Here is a complicated gmPL translation script. It is necessarily long. 


<gmBasic>
   <Storage Action="Create" Identifier="GMTest" />
   <Select DevEnv="VS2008" />
   <Select Dialect="csh" />
   <Select DeployLocation="E:\gmProj\FileExplorer\deploy\FileExplorer_std_csh" />
   <Select Library="C:\gmProj\FileExplorer\interop" />
   <Select Local="C:\gmProj\FileExplorer\idf\FromCode" />
   <Select System="C:\gmProj\FileExplorer\idf\FromIdl" />
   <Select Target="C:\gmProj\FileExplorer\usr" />
   <Compile Project="C:\gmSrc\GMTest\FileExplorer\FileExplorer_vb6\FileExplorer.vbp" Resx="C:\gmProj\FileExplorer\resx\FileExplorer-FileExplorer">
      <Refactor>
         <FixType identifier="FileExplorer.frmExploreLite.mSplitLimit" type="TwipsX" />
         <Fixtype identifier="FileExplorer.frmExploreLite.SizeControls.X" type="TwipsX" />
      </Refactor>
   </Compile>
   <Analyse />
   <Output Status="New" Filename="GMTest.bnd" />
   <Author>
   <Fix>
   <Type>ReplaceGlobal</Type>
   <Name>Treeview Migration</name>
   <Replace status="active" name="(FYI1) R: A few more properties helped with reproducing the TreeView UI">
   <OldBlock><![CDATA[
         this.tvTreeView.ImageList = ilMain;
         this.tvTreeView.Name = "tvTreeView";
Note that the Compile uses the unusual resx attribute and does refactoring. The Author does extensive author fixes using complicated embedded xml fix substatements.

The equivalent script written in gmSL looks as follows. 


int CompileFixes;
int AuthorFixes;

   Execute.Storage(Action := "Create", Identifier := "GMTest");
   Select.DevEnv = "VS2008";
   Select.Dialect = Dialects.csh;
   Select.DeployLocation = "E:\gmProj\FileExplorer\deploy\FileExplorer_std_csh";
   Select.Library = "C:\gmProj\FileExplorer\interop";
   Select.Local = "C:\gmProj\FileExplorer\idf\FromCode";
   Select.System = "C:\gmProj\FileExplorer\idf\FromIdl";
   Select.Target ="C:\gmProj\FileExplorer\usr";
   Write.OpenStream();
   #TextStart
   <Refactor>
       <FixType identifier="FileExplorer.frmExploreLite.mSplitLimit" type="TwipsX" />
       <Fixtype identifier="FileExplorer.frmExploreLite.SizeControls.X" type="TwipsX" />
    </Refactor>
   #TextEnd
   CompileFixes = Write.CloseStream();
   Execute.Compile(Project := "C:\gmSrc\GMTest\FileExplorer\FileExplorer_vb6\FileExplorer.vbp", Resx := "C:\gmProj\FileExplorer\resx\FileExplorer-FileExplorer", Commands := CompileFixes);
   Execute.Analyse();
   Execute.Output(Status := "New", Filename := "GMTest.bnd");
   Write.OpenStream();
   #TextStart
   <Fix>
   <Type>ReplaceGlobal</Type>
   <Name>Treeview Migration</name>
   <Replace status="active" name="(FYI1) R: A few more properties helped with reproducing the TreeView UI">
   <OldBlock><![CDATA[
         this.tvTreeView.ImageList = ilMain;
         this.tvTreeView.Name = "tvTreeView";
The Execute methods that take embedded script statements have one extra parameter Commands that takes the root offset of a text stream that contains the script commands to be executed. The script commands themselves are exactly the same as those that would be embedded if gmPL were being used. As is discussed elsewhere, the easiest way to create a text stream is via the #textstart ... #textEnd end. The highlighted statements above show this explicitly. Remember gmSL is a compiled language. In this example the substatement blocks were intentionally placed directly by the statements doing this. In general, gmSL offers far more flexibility in how these various components can be combined. The output of the above gmSL script is identical to that produced by the gmPL version.

Execute.Analyse Method

gmSL: void Analyse(string project, string dialect, int commands); 


<method id="Analyse" type="void" opcode="SCM.Execute_Analyse" >
   <Argument id="project" type="String" status="ByVal" optional="NULL" />
   <Argument id="dialect" type="String" status="ByVal" optional="NULL" />
   <Argument id="commands" type="Integer" status="ByVal" optional="0" />
</Method>

The method Execute.Analyse initiates the code analysis phase of the translation process. This phase takes as input the intermediate code produced by the compiler and outputs an intermediate code that can be authored in the target language. Once completed each active code unit has two intermediate code representations stored in the virtual binary information file.

The optional parameter project specifies the name of a previously compiled VBP project or ASP page. It restricts the analyzer to effect the specified component only. The use of this parameter should be limited to complex migrations where the order in which code units are processed must be controlled.

The optional parameter dialect specifies one of the three target language identifiers csh, vbn, or usr. It changes the system wide target language as selected and thus effects all further processing.

The optional parameter commands is the root offset of an set of gmPL refactoring statement to be executed. Though this parameter is available, the Analyse method has no substatements at this time.

This method performs the same operations as are performed by the gmPL statement Analyse. See the discussion there for additional details.

Execute.Author Method

gmSL: void Author(string project, string name, int commands); 


<method id="Author" type="void" opcode="SCM.Execute_Author" >
   <Argument id="project" type="String" status="ByVal" optional="NULL" />
   <Argument id="name" type="String" status="ByVal" optional="NULL" />
   <Argument id="commands" type="Integer" status="ByVal" optional="0" />
</Method>

The method Execute.Author takes as input the intermediate code produced by the analysis phase of the translation process. Using that code and the information contained in the symbol table it produces a fully functional code in the target language.

The optional parameter project specifies the name of a previously compiled and analysed VBP project or ASP page. It restricts the author to that component only. If NULL, all active components are authored.

The optional parameter Name specifies the overall name to be used as the web project name for an ASP site translation. If NULL, the name WebProject is used. This parameter is ignored in VB6 translations.

The optional parameter commands is the root offset of an set of gmPL fix statements to be executed.

This method performs the same operations as are performed by the gmPL statement Author. See the discussion there for additional details.

Execute.Compile Method

gmSL: void Compile(string project,string echo,string resx,string level,string pageslice,int commands); 


<method id="Compile" type="void" opcode="SCM.Execute_Compile" >
   <Argument id="project" type="String" status="ByVal" optional="NULL" />
   <Argument id="echo" type="String" status="ByVal" optional="NULL" />
   <Argument id="resx" type="String" status="ByVal" optional="NULL" />
   <Argument id="level" type="String" status="ByVal" optional="NULL" />
   <Argument id="pageslice" type="String" status="ByVal" optional="NULL" />
   <Argument id="commands" type="Integer" status="ByVal" optional="0" />
</Method>
The method Execute.Compile compiles a specified source code project or ASP file. Within the translation process, the first significant step beyond simply loading a source code is converting that source code into an intermediate representation that can be analysed, refactored, and authored. The intermediate representation itself contains two subcomponents -- a symbol table that describes the components being manipulated and intermediate code that describes the actual operations being performed. Both VB6 projects and ASP sites can be compiled. The project parameter compiles VB6 projects and the pageslice parameter compiles ASP pages.

The optional parameter project requests that the indicated project file, vbp, along with all references it makes and any code files that it loads be compiled.

The optional parameter echo has one of the values Pass1, Pass2, or All. It is used to override the echoing of source code input as set in the Select class attributes for the current compilation only.

The gmStudio has the capability needed to author into a separate file the resX information for controls that do not use the standard resX conventions to store their property values. The optional parameter resx specifies the name of this separate file. The compiler searches this file first for property values before it searches the project supplied resX files. At present this feature is used only for ImageStream Resx data generated from MSComCtl.ImageLists that are being replaced by WinForms.ImageList.

The optional parameter level has one of the values Project, Load, Pass1, Pass2, and All. This parameter requests that the compile phase end after completing the indicated step. The default is All. The other values are only used for debugging purposes.

The optional parameter pageslice requests that the specified page file within an ASP site be compiled, treating it in the same manner as it would be treated by the server when it gets a request for a page. It builds a source representation starting with any ASA file and its includes and then loads the page inserting any other includes as it sees them. The result of this step is a single source representation that can be compiled.

The optional parameter commands is the root offset of an set of gmPL refactor and/or fix statements to be executed.

This method performs the same operations as are performed by the gmPL statement Compile. See the discussion there for additional details.

Execute.Load Method

gmSL: void Load(string sourcecode,string project,string page,int commands); 


<method id="Load" type="void" opcode="SCM.Execute_Load" >
   <Argument id="sourcecode" type="String" status="ByVal" optional="NULL" />
   <Argument id="project" type="String" status="ByVal" optional="NULL" />
   <Argument id="page" type="String" status="ByVal" optional="NULL" />
   <Argument id="commands" type="Integer" status="ByVal" optional="0" />
</Method>
The method Execute.Load loads source compilation units so that they can be edited, analysed, or ordered by other utility operations in preparation for processing.

The optional parameter sourcecode applies only to project loads. If on, the individual source files in the project are loaded. This involves searching the project file for Form, UserDocument, UserControl, Module, and Class entries whose values are the source code filenames to be loaded. Each file is then loaded into an edit buffer and its name is stored in the symbol table. For each file the GlobalSettings file is checked to see if any edit fixes are to be applied to it.

The optional parameter project names a project file to be loaded in the same manner as the first step of the compiler. Loading the project file begins by first storing the name of the project file in the symbol table and making certain that it is unique. Second, the project file itself is loaded into an edit buffer. Third, the GlobalSettings file is checked to see if any edit fixes are to be applied to the project file. Fourth, the file is searched for the its Name and Exename32 entries whose values are then stored in the symbol table.

The optional parameter page names a file in an ASP site to be loaded into a text buffer in raw form. This is not a PageSlice load as is performed by the compiler.

The optional parameter commands is the root offset of an set of gmPL fix statements to be executed.

This method performs the same operations as are performed by the gmPL statement Load. See the discussion there for additional details.


Execute.LoadRuntime Method

gmSL: void LoadRuntime(string dllname, string event,string filename); 


<method id="LoadRuntime" type="void" opcode="SCM.Execute_LoadRuntime" >
   <Argument id="dllname" type="String" status="ByVal" optional="NULL" />
   <Argument id="event" type="String" status="ByVal" optional="NULL" />
   <Argument id="filename" type="String" status="ByVal" optional="NULL" />
</Method>
The method Execute.LoadRuntime loads a runtime Dll into the current execution space of gmBasic. This Dll may well be intermingled with Dlls loaded via the selected runtime environment and Dlls loaded via refactoring operations. There are a maximum of 64 Dlls that may be loaded. Each DLL exports certain methods, event handlers, that are then looked for by the execution logic of gmBasic when certain things happen or when certain points in the processing are reached.

The optional parameter dllname specifies a simple local file name of the runtime Dll to be loaded. It is looked for using the standard search order. That order is target location, local location, system location, and language location.

If the DLL being loaded implements a CodeEvent event handler then the optional parameter event specifies the identifier of this event. This event is triggered by references in the code to subcomponents that have a migUserCode value attributed to them.

The optional parameter filename specifies the full pathname of the runtime Dll to be loaded. It is used only if the dllname parameter is NULL.

This method performs the same operations as are performed by the gmPL statement LoadRuntime. See the discussion there for additional details.

Execute.Output Method

gmSL: void Output(string filename,string status,string syntax,string striptrail); 


<method id="Output" type="void" opcode="SCM.Execute_Output" >
   <Argument id="filename" type="String" status="ByVal" optional="NULL" />
   <Argument id="status" type="String" status="ByVal" optional="NULL" />
   <Argument id="syntax" type="String" status="ByVal" optional="NULL" />
   <Argument id="stripTrail" type="String" status="ByVal" optional="NULL" />
</Method>
The method Execute.Output specifies where information being output should be written and how it should be formatted.

The optional parameter filename contains the full pathname of the text file that is to receive the output to be produced. If this attribute is Null, then standard output file is used.

The optional parameter status specifies the status of the file -- New means create a new file, Old means open an existing file and append the coming output at its end, and Close means simply close the current file. If NULL, then New is assumed.

Besides authoring record-oriented translations, gmBasic can also be used to write tabular reports. via the DataTable class, based on the information collected while it was processing the source codes. The optional parameter syntax specifies the output style to be used when producing these tabular reports. They can be produced in one of three styles: Tabbed simple tab delimited; Text text tabular; or Html html tabular. If NULL, then the style is Text.

The optional parameter striptrail if On, requests that any trailing blanks be stripped from output records. This attribute is rarely needed.

This method performs the same operations as are performed by the gmPL statement Output. See the discussion there for additional details.

Execute.Registry Method

gmSL: void Registry(string source,string target,string type,int commands); 


<method id="Registry" type="void" opcode="SCM.Execute_Registry" >
   <Argument id="source" type="String" status="ByVal" optional="NULL" />
   <Argument id="target" type="String" status="ByVal" optional="NULL" />
   <Argument id="type" type="String" status="ByVal" optional="NULL" />
   <Argument id="commands" type="Integer" status="ByVal" optional="0" />
</Method>
The method Execute.Registry makes an entry in the registry, which stores named settings and options for a variety of special uses within gmBasic or within user specified runtime Dlls. It contains a simple hierarchical set of name-value pairs stored under a type identifier. The values are either simple strings or a text buffer.

The parameter source contains the source name of the pair to which a target value is to be assigned. It may have any content. If a given pair is intended to be unique within a given type, then its name must be unique within that type only.

The optional parameter target is used only with the commands parameter is zero. It contains the target value of the pair. It may have any content and need not be unique. At any given time a given source with a given type can have only one target. If NULL, then the name value pair is treated as though it no longer exists within its location.

The optional parameter type contains the identifier of the "special use" of the name-value pair being entered. If NULL, then the value LibName is supplied.

The optional parameter commands is the root offset of an set of a text buffer to be the value of the name-value pair.

This method performs the same operations as are performed by the gmPL statement Registry. See the discussion there for additional details.

Execute.Storage Method

gmSL: void Storage(string action,string identifier,string startup); 


<method id="Storage" type="void" opcode="SCM.Execute_Storage" >
   <Argument id="action" type="String" status="ByVal" optional="NULL" />
   <Argument id="identifier" type="String" status="ByVal" optional="NULL" />
   <Argument id="startup" type="String" status="ByVal" optional="NULL" />
 </Method>
The method Execute.Storage specifies the status of the virtual binary information file to be used. It should always be included if a translation is to be performed.

The parameter action specifies the storage action to be performed. It can have one of five options -- CREATE, OPEN, APPEND, CLOSE, and SAVE.

The optional parameter identifier is the full pathname of the file containing or to contain the information being stored. Optionally, the filename extension may be omitted. In which case the extension vbi is used. If this parameter is NULL, then a memory-based storage area is used. Memory-based storage is much quicker to use, but any information stored is lost when the run ends.

The optional parameter startup is the full pathname of a file whose content should be used to initialize the current storage area when it is created. Optionally, the filename extension may be omitted. In this case, vbi is used. This parameter is only valid when a file-based storage area is being created. The content of the startup file itself is not changed.

This method performs the same operations as are performed by the gmPL statement Storage. See the discussion there for additional details.

Table of Contents