gmBasic Users Manual
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. The different tools themselves share a library of classes, called "service classes", that 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. |