...

The VB6 language and the intrinsic VB6 object model provides many types of services to VB6 applications.  A few examples are listed here:

• Logic: Intrinsic keywords, functions, and commands
• Object Model / Data Model Definition
• Custom Event Handling
• File IO, Database Access, Printing
• User Interface Forms/Controls and Graphics
• Error Handling
• Interfacing with COM and Win32 APIs
• Interfacing with the Operating System Services

...

The first step in customizing how gmStudio rewrites VB6 to .NET is to identify the specific VB6 language elements that provide services to your application and to understand, at a high level, how the services work.   

...

In this example, we look at how to customize the replacement of VB6’s Len function. 

1)     Understand how legacy language elements are used by your application

In VB6, the Len function offers a convenient way to compute the length of a string.  Documentation for Len from the VB6 object browser says the following: 

Function Len(Expression)

...

    Member of VBA.Strings

...

    Returns string length or bytes required to store a variable

    Returns string length or bytes required to store a variable

gmStudio’s default translation of Len(x) is VBNET.Strings.Len(x). In default gmStudio translation conventions, VBNET is an alias for the Microsoft.VisualBasic namespace.  This namespace is distributed in Microsoft.VisualBasic.dll and contains an extensive set of classes that emulate VB6 runtime and VBA.    

public static int Len(string Expression)
 {
     if (Expression == null)
     {
         return 0;
     }
     return Expression.Length;
 }

You can use gmStudio’s reporting tools to see how your application uses the Len function.  The Source Scan Report can be run from the Search panel or the Reports menu.  Simply searching for “Len” will show were you use Len, but may also show some false matches.  A more precise Source Scan Report can be done using a more sophisticated regular expression; for example “@\bLen\(“ (the leading @ indicates case-sensitivity).  The most precise report for how and where you use Len will be obtained by running the Analytics References Report.  See the records in the Analytics References report having MemLibr=Basic,  MemClas=Vb6Function, and Memname=Len.

...

The next step in the process is to find the rule for expressing the Len operation and change it.  The easiest way to find a rule is to look for the .NET code pattern that you want to change in the metalanguage files.  You can do this with the Search Panel in gmStudio.  For this example, enter VBNET.Strings.Len in the search box on the left, check the [Lang] checkbox, and click [Run Search].  The results of this search are shown below:

The results show us that the rule for Len is in the VBASIC.xml file, which is located in the gmStudio installation folder, [installdir]\support\trancfg\lang.    The actual text of the rule for Len in VBASIC.xml looks like this

...

An additional modification that can be useful when changing a method to a property is to add the status=”postfix” attribute.  In this example, status=’postfix’ directs gmStudio to put parentheses around x if needed. 

...

...

4)     Apply and refine those rules for additional source codes as needed

Typically a large, mature code will not meet the assumptions of every migration rule 100% and you should plan to consider alternatives and to refine or extend the rule to deal with variations.  This incremental refinement is an important aspect of our iterative methodology. 

In this example, the new rule assumes that the type of original argument to Len has a Length property in .NET and that argument is not null at runtime.  The first assumption is easy to check using the C# compiler.  The second assumption can be checked by static analysis of the code and by runtime testing.  We know that the rule will not work for situations where the argument is a struct; in fact the resulting code will not even build.  A more appropriate translation of Len(struct), that still avoids using VBNET, is to use System.Runtime.Interop.Marshal.SizeOf().    

In this type of situation, a Migration DLL can be used to implement a rule that specifies x.Length is used for strings and Marshal.SizeOf(x) for is used for structs.   However,  when you encounter exceptions to your coding/upgrade standards, take time to see what the code is actually doing.  For example, in the case of code that uses Len with struct you will typically also find Win32 APIs calls or record-based file IO.  Both of these things warrant additional redesign as they move to .NET.   It may make more sense to rework that section of your code in a different way.   Also beware that VB6 language frequently provides high-level services that can only be reproduced by runtime routines that integrate several .NET operations.  The check for null in VBNET. Strings.Len is a good example of this. 

...

Key Point

...

Appendix X: Activating a Custom Metalanguage Configuration

...

Metalanguage files are XML documents that direct gmStudio as it rewrites your VB6 program for .NET.

...

...

There are two types of Metalanguage files: default Interface Description Files (IDFs) and default Language Files. 

• The Default IDFs are processed every time you run the translation process.
  
  The default IDFs are deployed in [installdir]\support\trancfg\idf
  
  To list and inspect the default IDFs:

1. 1. Open the Settings dialog by clicking the [Settings] button on the toolbar. 
   2. Click the [Configuration Files] tab
   3. Select the [Interface Descriptions] button

• The Default Language Files must be pre-processed by gmStudio to create the metalanguage information file (VB7Lang.vbi)
  
  The language script (VB7Lang.xml) directs gmStudio in processing default language files to create the metalanguage information file (VB7Lang.vbi)
  
  The translator StartUp file (gmBasic.xml) specifies the location of the metalanguage information file. 
  
  The default language files are deployed in [installdir]\support\trancfg\lang

To list and inspect the default Language Files:

1. 1. Open the Settings dialog by clicking the [Settings] button on the toolbar. 
   2. Click the [Configuration Files] tab
   3. Select the [Language] button

Customizing default interface description files

...

1. Open the Settings dialog by clicking the [Settings] button on the toolbar.
2. Click the [Configuration Files] tab
3. Copy the desired default IDF to your workspace.
   1. Click the [Interface Descriptions] button to list the default IDFs
   2. Click the desired default IDF, for example MigrationSupport.xml
   3. Click [Save As…] and save a copy of the file in the [workspace]\usr folder.

...

Key Points

...

Customizing default language files

The [Configuration Files] tab on the Settings dialog is designed to help you inspect and manage all the files that play a role in configuring gmStudio.  The following instructions explain how to setup gmStudio to do custom language replacement.

Part 1: Activating project-specific metalanguage information

1. Open the Settings dialog by clicking the [Settings] button on the toolbar
2. Click the [Configuration Files] tab
3. Click the [Project] option in the [Translator Configuration] group box.

...

The Language Information Script indicates which default language files should be processed to create the language information file.  The Project option uses a version of the script that can be edited to specify that your custom language files should be used instead of the default files.

...

Key Points

...

...

Part 2: customizing default language files

1. Identify the metalanguage file that you wish to update and make a copy of the file in your workspace -- if you have not already done so.  For example, assume you want to modify the VBASIC.xml file. 
   
   
   1. Click [Language Files] to list the default language files
       
2. Modify the VBASIC.xml file in your work space user folder so as desired.  For example.
   
   
   1. Click VBASIC.xml
   2. Click [Save As…] and save a copy of the VBASIC.xml in the [workspace]\usr\lang folder
       
3. Modify the VB7Lang.xml file in your workspace so that it will include the VBASIC.xml in your workspace instead of the one in the default metalanguage folder. 
   
   The default location for default language files is specified as %MetaLangFolder%; for example:
   
    <Include FileName="%MetaLangFolder%\vbasic.xml"/>
   The convention follow for customized Language Files is to place them in the usr\lang folder in the workspace and specify this using %UserFolder% script variable; for example:
   <Include FileName="%UserFolder%\lang\vbasic.xml"/>
    
4. Rebuild the metalanguage information file by clicking the [Update Translator Configuration] button.  
   
   This processes the VB7Lang.xml script and display the Translator Configuration Build Log into the text box. 
   If the process is successful, the listing will show the directory listing for the new VB7Lang.VBI file in your workspace.

...