The gmBasic system does tool-assisted rewrite of VB6/ASP/COM code into the .NET languages.
It is highly configurable using a variety of subsystems. This is a users manual for gmBasic. Its
purpose is to describe how to use gmBasic to configure and control the content of that rewrite.
There are many different types of users of this system, beginning with those who are simply interested
in producing a quick set of .NET codes which they can finish on their own, moving on to those who wish to
configure the content of the .NET codes produced beyond what is done for them automatically, and ultimately
ending with those who wish to apply the system to other source and target languages. The presentation
with in this manual is organized into five sections ordered by the level of expertise required to use
them and of course the type of license purchased:
Section
Description
gmPL
The Great Migrations Programming Language is a simple command language
used to issue instructions to gmBasic and to enter declarations into the symbol table. It
is not a procedural programming language, it is an xml-style scripting language. It is not compiled;
rather its commands are executed directly. All users of gmBasic who wish to do anything
beyond doing a standard one-off rewrite of their source code should review this section.
Code bases, the input to gmBasic, are interrelated combinations of VB6, ASP,
and COM code. To process them, gmBasic must be told where the code is, what files it
includes, what order the files are to be processed in, what general configurations should be used,
what migrations are to be performed, what fixes need to be made, and so on. The gmPL
language is needed to provide this information. Its statements are aggregated into xml-style
scripts which both direct the operation of gmBasic and document what operations are
performed. Initially, these scripts are produced entirely by gmStudio. Reading the
gmPL scripts, that gmStudio has produced allows the user to understand what was
done. Moving forward from there, the user can add gmPL to the scripts to further control
the process.
gmIL
The Great Migrations Intermediate Language is a reverse-polish
byte-code representation. Source languages are compiled into gmIL. That representation is
then analyzed, executed, and modified to be expressible in a target language so that it can be
authored in that target language. The rewriting of source code into the target languages
is not a simple syntax problem. It cannot be done with simple parsers, source code pattern
recognition, and keyword replacement. It requires detailed analysis of what the source code is
doing and of how similar operations can be performed and expressed in the target code. Also,
it requires identifying those operations in the source code that have no direct expression in
the target language. These operations must not only be isolated, they must be represented in
the target language in a way that allows the user to supply the missing functionality. The approach
taken by gmBasic revolves around this notion of "operations". It is these operations that
must be derived from the source code, analysed to make them expressible in the target code,
migrated to conform to user needs, and finally authored. The operations are defined and organized
into groups called opcodes. The gmIL is the language that defines these operations.
It is needed to organize every phase of the translation process. Users wishing to move beyond
simple gmPL scripts need to review the material in this section. They must be familiar
not only with the operations themselves, but also with the technology that uses these operations
to do translation.
gmSL
The Great Migrations Scripting Language is a procedural language
for use with the migration, authoring, and reporting facilities of gmBasic. It uses
Java-style syntax and is embedded into the gmPL scripts. It is compiled into the same
gmIL as used for the other source languages and is executed directly by gmBasic.
Procedures written in gmSL can to applied to every phase of the translation process.
Source files can to edited and/or fixed, compilation can be controlled, compiled code can be
analysed and modified, symbol tables can be searched, symbol references in the code can be
reported, authoring can be controlled at production time or edited after the fact, and so on.
Most importantly, the gmSL language has classes that allow direct access and control
of the gmIL code blocks.
gmNI
The Great Migrations Native Interface makes writing native methods
in C possible to handle situations when a migration cannot be written entirely in the
languages supported by the standard capabilities of the translation tool. The capabilities
of gmNI are very similar to those of the gmSL. Native code methods, loaded into
runtime libraries, can handle events triggered during the translation process. These
native methods have direct access to all of the information being managed during the translation
via an extensive set of service classes. The methods within these classes are largely the same
as those referenced through gmSL, though their reference syntax and the form of some of
the arguments differ to accommodate the differences in C and gmSL. The advantages
of using gmNI over gmSL are three-fold: first, because gmNI is C-based it
has access to external libraries and functionality in general that are not directly available
in gmSL; second gmNI code is compiled and runs much more quickly than the
gmSL byte-code which is executed interpretively by the tool set; and third, the gmNI
can be distributed in compiled, obfuscated, dll form while gmSL is distributed
in source form. The disadvantages of gmNI are that it requires knowledge of ANSI-C
programming and development. The gmBasic tool set itself is not used to produce these
gmNI Dlls, it simply uses them.
gmCL
The Great Migrations Command Line tools are a set of ANSI-C programs
that perform the various independent operations needed by gmBasic. These include
pBasic which executes gmPL scripts, Deploy which facilitates the deployment
and creation of bundled text files, and Document which produces an HTML based
manual using a simplified set of XML input files.
gmSC
The Great Migrations Service Classes form an ANSI-C library shared by
the different tools. They manage storage, build symbol tables, process text, manage characters,
parse statements and expressions into gmIL, manage a registry, and so on. Using the
discussion in this section and the resources available in the service classes provides the
information needed to apply the system to other source and target languages.
gmAPI
The Great Migrations APplication Interface is a set of C#
implemented libraries that implement the gmSL capabilities in .NET form. It
supports all of the capabilities of the scripting language, but has many capabilities
that go beyond it like being able to execute any gmPL command and supporting many of
the gmNI service methods that were not included with gmSL.
Access to this manual is via the main control page gmUser.html. Direct access to the individual
sections can be obtained via the main control pages for those sections: gmPL.html, gmIL.html,
gmSL.html, gmNI.html, gmCL.html, or gmSC.html.
