gmStudio is a platform for building VB6/ASP upgrade solutions that meet real-world requirements. The platform offers several very powerful and expressive ways to customize how it works:
gmPL Scripts using an XML-like notation to implement declarative specifications that direct and inform the translation engine's operation
gmSL Scripts using a C-like notation to implement classes, methods, and event handlers that can extend the services of the translation engine
Many gmPL and gmSL files are included in the standard gmStudio distribution and also available for download from this documentation portal. Furthermore, gmPL and gmSL provide a great deal of expressive power and precision. For example, we built several advanced COM API migrations, and a VB6 Forms to WPF/XAML extension using gmSL. But, they have their limitations. For example, gmSL lacked a contemporary development support (i.e. no intellisense and no debugger).
In the course of planning a big VB6-to-WPF project, the customer asked if they could use a C# API instead of the scripting language and gmAPI was born. gmAPI is as a powerful alternative to gmSL. gmAPI can access the same system services as gmSL, but gmAPI logic is developed in C# (or http://VB.NET ) so has all of the benefits of being part of the .NET ecosystem (using a contempora4ry IDE, pre-compilation, interactive debugging, framework services, etc.)
The introduction of gmPL Extensions makes integrating gmAPI logic with the translation engine robust and seamless. gmPL Extensions define the conventions for defining new gmPL language elements and integrating gmAPI assemblies with the core translation engine. gmPL Extensions extend the set of gmPL statements that are recognized and processed by the translation platform to provide new code analysis and transformation features.
gmPL Extension dll Resolution and invocation
When gmBasic is processing a gmPL script and it encounters a script statement that it does not recognize, it looks for a .NET assembly named "gmPL_(%statement%).dll". If the dll is found, gmBasic looks for a class "gBasicMain.gmPL_(%statement%)". If that class can be instantiated, the resulting instance is used to invoke a method named XeqStatement to handle the extended command.
The process for finding the extension DLL first looks in the folder containing gmBasic. If the extension DLL is to be placed in a different location, then the extension element must specify that location in a Dllname attribute. For example, the extension tag below will engage extension code in gmPL_GlobalStubs.dll located in the same folder as gmBasic.exe. This is used for the gmPL dlls in the gmStudio distribution.
<GlobalStubs> ... </GlobalStubs>
The extension tag below will engage extension code in gmPL_GlobalStubs.dll located in the C:\Dev\gmGlobalStubs\bin\Debug\ folder.
<GlobalStubs DllName="C:\Dev\gmGlobalStubs\bin\Debug\gmPL_GlobalStubs.dll"> ... </GlobalStubs> NOTE: The DllName value will typically be specified as a relative path or a path using a gmPL script variable (e.g. %UserFolder%).
gmPL extensions assemblies and classes must have the following conventions:
Unable to find source-code formatter for language: csharp. Available languages are: actionscript, ada, applescript, bash, c, c#, c++, cpp, css, erlang, go, groovy, haskell, html, java, javascript, js, json, lua, none, nyan, objc, perl, php, python, r, rainbow, ruby, scala, sh, sql, swift, visualbasic, xml, yaml*** gmPL_GlobalStubs.dll *** <-- recommended name is gmPL_<ExtensionName>.dll
namespace gmBasic <-- namespace must be gmBasic
{
public class gmPL_GlobalStubs <-- class name must be gmPL_<ExtensionName>
{
XeqStatement(string record); <-- extension command handler
Building a gmPL Extension
The high-level process for creating and using a gmPL Extension is as follows:
Define your requirements and decide on a name for your extension
Implement a .NET DLL following gmPL extension conventions and using gmAPI methods to access and manipulate the translation model
Engage your extension by adding one or more extension XML Elements into translation scripts
If your gmPL extension will interact at several points in the translation process, XeqStatement must return Script.HasEventHandlers. This tells gmBasic to hand-off processing to the gmPL dll when it encounters the three main processing operations (Compile, Analyse, and Author). During each hand-off, the gmPL extension may engage its own pre- and post-processing logic and engage the tools standard processing for these operations. For example, see the implementation of the gmPL_CodeStyle below.
Examples of gmPL extensions
As of the September 2024 Release, gmStudio ships with several gmPL extensions:
Shared Files Reporting and Consolidation (gmPL_gmSharedFiles.dll)
Custom Coding Style Transformations (gmPL_gmCodeStyle.dll).
VB6 to WPF Migration (gmPL_WpfSubSystem.dll)
Global Support Framework Generation (gmPL_gmGlobalStubs.dll).
Global Analysis and Reporting (gmPL_gmGlobal.dll)
Advanced Code Analysis Reporting (gmPL_Search.dll)
There are three flavors of extended gmPL libraries:
Single Statement,
Multiple Statement, and
Event handler.
gmPL_Search.dll (Single Statement)
gmPL_Search.dll is a single statement gmPL extension command that executes the "Search" command.
The script template below contains the <Search> command that triggers execution of gmPL_Search.
<gmBasic>
<Select Target="%UserFolder%"/>
<Select CodeSize="500000"/>
<Select VirtualRoot="%VirtualRoot%"/>
<Select DeployLocation="%VirtualRoot%\..\SrcPrep"/>
%AuditMode%
<Storage action="Open" identifier="%InfoFile%" />
<Output Status="New" Filename="%RptPath%" StripTrail="on" %Syntax% />
<Search>
<%InfoType% %Project% />
</Search>
<Storage Action="Close" />
</gmBasic>
gmBasic also engages gmPL_Search.dll to produce a VBI audit using this call to ExecutedExtendedStatement:
returnCode = ExecuteExtendedStatement("search",
"<Search identifier=\"" + fileName + "\" />");
gmPL_SharedFile.dll (Single Statement)
gmSharedFile.dll is single statement gmPL extension library that executes the "SharedFile" command.
<gmBasic> <Storage Action="Create" Identifier="SharedFile" /> <Load project="%VirtualRoot%\A.vbp" SourceCode="On" /> <Load project="%VirtualRoot%\B.vbp" SourceCode="On" /> ... <Output Status="New" Filename="%BndPath%" /> <SharedFile RegistryFile="..\usr\Registry_SharedFile" > <VbiFile identifier="A.vbi" /> <VbiFile identifier="B.vbi" /> ... </SharedFile> <Storage Action="Close" /> </gmBasic>
gmGlobal.dll (Multiple Statement)
gmPL_gmGlobal.dll is a multiple statement gmPL extension library that executes the 5 gmPL commands:
InformationFiles/Load: load VBI files for subsequent global analysis
FindCallByName: report LateCalls
RemoveUnused: identify and report unused symbols as an XML script containing Remove commands
ReportRemovals: identify and report unused symbols as a tabular report
GlobalIncludes: report and apply refactoring commands for ASP includes based on global analysis
See Support Statement: Unused Symbol Analysis and Reporting
gmCodeStyle.dll (event handler)
The gmCodeStyle.dll is an event handler gmPL extension that assists with generating "CodeStyle" translations. In order to engage this dll, the translation script must contain a <CodeStyle> statement. For example:
<CodeStyle Configuration="..\usr\CodeStyle.std.xml" />
This statement triggers loading the gmPL_CodeStyle.dll and configuring it with the specified CodeStyle rules. It also registers the DLL to extend the handling of Analyse and Author events when they occur during the translation process.
This integration is done in the DLL code.
Unable to find source-code formatter for language: csharp. Available languages are: actionscript, ada, applescript, bash, c, c#, c++, cpp, css, erlang, go, groovy, haskell, html, java, javascript, js, json, lua, none, nyan, objc, perl, php, python, r, rainbow, ruby, scala, sh, sql, swift, visualbasic, xml, yamlnamespace gmBasic {
public class gmPL_CodeStyle {
...
public static int XeqStatement(string record)
{
string scriptTag = null;
string configuration = null;
int returnCode = 0;
bool ending = false;
scriptTag = Script.GetTag(record,out ending);
if(String.Equals("CodeStyle", scriptTag, StringComparison.OrdinalIgnoreCase))
{
configuration = Script.GetAttribute("Configuration",record);
if(configuration == null) returnCode = 0;
else
{
Configuration.Startup(configuration);
returnCode = Script.HasEventHandlers;
}
}
else if(String.Equals("Compile", scriptTag, StringComparison.OrdinalIgnoreCase))
{
returnCode = Execute.gmPL(record); // no special processing during Compile
}
else if(String.Equals("Analyse", scriptTag, StringComparison.OrdinalIgnoreCase))
{
returnCode = Execute.gmPL(record);
if (returnCode == 0)
{
ScanCode(); // CodeStyle Analyser post-processing
}
}
else if(String.Equals("Author", scriptTag, StringComparison.OrdinalIgnoreCase))
{
record = record.Replace("<Author", "<Author Finish='off' ");
returnCode = Execute.gmPL(record); // Partial Authoring
if (returnCode == 0)
{
if (Configuration.TargetCode)
{
Parser.SetReserved(Dialects.xml);
Runtime.EditTarget editor = new Runtime.EditTarget(TargetCode.Edit);
Runtime.TargetCodeScan(editor); // CodeStyle Author post-processing
}
VerticalList.TargetCode(); // CodeStyle Author post-processing
Runtime.FinishTranslation(); // Final Authoring and Publishing
}
}
else
{
returnCode = Script.UndefinedNestedStatement;
}
return returnCode;
}
gmPL_GlobalStubs.dll (Single Statement)
gmPL_GlobalStubs.dll is a single statement gmPL extension that executes the "GlobalStubs" command. With this library loaded gmBasic is able to execute the GlobalStubs statement using C# code. The extension dll handles loading all of the VBI files for a system then generates the GlobalStubs bundle. This command will typically be placed at the bottom of a gmBasic script that references the external IDFs used by the VBIs. See Incremental Scope Analysis using gmStudio
<GlobalStubs> <Load id="A.vbi" /> <Load id="B.vbi" /> ... </GlobalStubs>
gmPL_WpfSubsystem.dll (Single Statement)
gmPL_WpfSubsystem.dll is a single statement gmPL extension that executes the "WpfSubsystem" command. With this loaded, gmBasic is able to produce WPF translations. The WPF extension handles authoring XAML files instead of Designer files for Forms and UserControls as well making various changes to code and project structure. This command will typically be placed at the top of a gmBasic script and tell the translator to handle compile, analyse, and author operations adding special processing for WPF features.
<!-- Activate WpfSubsystem migration services --> <WpfSubsystem DllName="%AppExeFolder%\gmPL_WpfSubsystem.dll"/> <Select SubSystem="wpf"/>