Table of Contents

1. Overview
2. The Main Menu
3. Toolbar
4. Migration Project Panel
5. Migration Details Panels
6. Statusbar
7. Side-By-Side Comparison Form
8. Batch Control Form
9. Task Filter Form

 Overview

The gmStudio Main Form provides access to all common application functions. The screen has six major components:

• A Title Bar, which displays the currently active migration project file.
   
• A Main Menu, which contains items that invoke various functions and display other forms and workspace folders.
   
• A Toolbar, which contains buttons to invoke various functions and display other forms.
   
• A Migration Project Panel, which fills the top of the screen. It displays a list of the tasks in the migration project. An extensive Task Context Menu allows you to perform operations on selected tasks. This list can be filtered to show only a subset of tasks.
   
• A Migration Task Details Panel, which allows access to an extensive array of information associated with each migration task. It also contains a session log viewer and a powerful code search reporting tool.
   
• A Status Bar, which displays the latest message from gmStudio and various counts (selected tasks, filtered tasks and all tasks).
   
• The Filter Tasks Form and the Batch Control Form are also discussed here.

Tip	The relative heights of the Migration Project Panel and the Task Details Panel can be set by clicking the form between the panels and dragging up or down.

An image of the Main Form is shown below.

 The Main Menu

The gmStudio Main Menu is discussed below.

1. File Menu
2. View Menu
3. Tools Menu
4. Reports Menu
5. Help Menu

 File Menu

The File Menu is used for managing migration project files:

Item	Description
New...	Displays the Migration Setup form so you can create a new migration project file. Same as clicking [New] on the Toolbar.
Open...	Displays an open file dialog to select a migration project file and loads the file if one is selected. Same as clicking [Open] on the Toolbar.
Add Tasks...	Displays the Migration Setup form for editing migration project settings and for adding or removing tasks from the current migration project. Same as clicking [Add Tasks] on the Toolbar.
Save	Saves the current migration project file. Same as clicking [Save] on the Toolbar.
Save As	Saves the current migration project to a different file. Note this also changes the Migration name within the project file.
Edit Task List	Saves the task data of the current migration project to a tab-delimited file ([MigName].tab) and loads the file into the application you have associated with .tab files (e.g., a spreadsheet application). If no application is associated with .tab files, you will get an error. Same as clicking [Edit] on the Toolbar.
Load Task List	Loads the task data from the tab-delimited ([MigName].tab) file and replaces the tasks in the current migration project with the data from the file.
1..5	Opens one of the last five most recently used migration projects
Exit	Saves the current migration project and exits gmStudio. Saving the migration project is automatic and silent by default. If you wish to be prompted to save (or not save) the file, set AutoSave = "False" in the application config file. See the Configuration Form page.

 View Menu

Most of the View Menu items open the various working folders for the current migration project. Several other items open various application and system Configuration File folders:

Item	Description
Workspace	Opens the current workspace root folder.
Interop Assemblies	Opens the Interop Assembly folder, where pre-generated Interop assemblies are stored.
Interface Descriptions	Opens the Interface Description folder, where pre-generated IDF files are stored (and read during the translation process as needed).
Reports	Opens the Reports folder, where all report files are stored.
Logs	Opens the log folder, where logs of the translation process are stored. This is also the working folder where translations are performed.
User Files	Opens the User Files folder, where migration project-specific templates and other supporting files are typically stored.
Deployment Root	Opens the Deployment Root folder, where the folders for each generated .NET project are stored.
System Config	Opens various System and Application Configuration file folders.

 Tools Menu

Most of the Tools Menu items perform various migration preparation operations:

• The Scope of these operations covers all selected tasks in the Migration Project Panel.
   
• The Order in which these operations are processed is the order in which they are stored in the migration project file -- usually the Build Order.

The View Menu items are as follows:

Item	Description
Validate Source	Computes the total line count and checks the status of external references for each task. The total line count is stored in the SrcSize field. The status of external references is stored in the RefStat field and is discussed in the Preparation section
Set Build Order	Attempts to compute, apply, and save the Build Order among the selected tasks
Build VB6	For VB6 migration units, this item attempts to build the VBP with the VB6 compiler then checks the results and updates the SrcBlds field accordingly
Author Interface Descriptions	Authors the Interface Description files for the selected tasks then updates RefStat accordingly
Author Interop Assemblies	Authors the Interop Assembly files for the selected tasks then updates RefStat accordingly
Create BuildSet	Creates a BuildSet for the selected tasks. See the Translation Section for a description of a BuildSet
Author Resx Files	Authors Resx Files for the selected tasks

The following View Menu items execute special purpose operations:

Item	Description
Author Interface Description(s)	Displays an open file dialog for selecting ad hoc inputs to the IDF generation process.
Batch Control	Displays the batch control form that allows you to select specific operations for processing when you click the [Upgrade] button on the Toolbar.

 Reports Menu

Each Reports Menu item runs a specific type of report for all selected tasks and then opens the resulting report file for viewing:

Item	Description
Code Scan	Select and run Code Scan reports.
Project	Select and run Project reports.
Analytics	Select and run Analytics reports.
Utilities	Select and run Utility reports.

See the Assessment section for details about the various gmStudio reports.

 Help Menu

The Help Menu items access system documentation and diagnostics:

Item	Description
Documentation	Open the gmStudio documentation.
About	Display the application version and license information in the Task Details box.
Check Environment	Display a report showing the locations and status of the various files and folders currently directing system behavior in the Task Details box.
Register	Display the Registration Form where you can prepare a license request and install a license file.

 Toolbar

The gmStudio Toolbar offers one-click access to the most common application functions. Most of the buttons are enabled only when you have a migration project loaded and a migration task selected.

The Toolbar buttons are:

Button	Description
New	Displays the Migration Setup form where you can create a new migration project.
Open	Displays an open file dialog to select an existing migration project file (*.gmProj).
Add Tasks	Displays the Migration Setup form so you can add tasks to the current migration project.
Save	Saves the current migration project file.
Edit	Saves the task data from the current migration project to a tab-delimited file (i.e., [MigName].tab) and loads the file into the application you have associated with .TAB files (e.g., a spreadsheet application). If no application is associated with .TAB files you will get an error.
Filter	Displays the [Task Filter] dialog where you can specify criteria to display a subset of tasks in the Migration Project Panel. This can also be done by pressing (CTRL-F).
Upgrade	Displays the [Batch Control] dialog from which to optionally select and run a batch of upgrade operations. This can also be done by pressing (ALT-X).
Reports	Displays the [Reports] dialog from where you can select and generate various reports and/or browse the contents of the Reports Folder.
Compare	If two different migration tasks are selected, this loads their translation bundles in the user-specified file comparison tool. If one task is selected, this loads the last translation bundle and the last snapshot in the user specified translation tool. This is useful for comparing the effects of different translation configurations on resulting code translations This can also be done by pressing (ALT-C).
Old IDE	Loads the source migration unit (Vbp or Web file) in the associated IDE (usually VB6).
New IDE	Loads the generated .NET project in the associated IDE (usually Visual Studio .NET 2008).
Settings	Displays the [Configuration] dialog so you can edit application and system settings.

 Migration Project Panel

The Migration Project Panel displays the list of migration tasks for the current migration project.

The fields displayed in the list are defined in the Reference Section (see the Migration Project Files topic).

The following operations can be performed with the Migration Project Panel:

• Right-Clicking on the list displays the Task Context menu
   
• Clicking items selects and activates them for subsequent processing or reporting. This also updates the content of the task details pane with data for the selected task. The selected count is displayed in the Status Bar.
   
• Clicking a column header sorts the list (toggling sort direction).

The Task Context Menu items perform operations on the selected tasks. Some of these operations work on all selected tasks, others work on the first selected task only:

Item	Description
Select All	Selects all non-filtered tasks. This can also be done by pressing (CTRL-A).
Edit Task Script(s)	Loads the Translation Script and user batch script for the selected task in the user-specified text editor. This can also be done by pressing (ALT-S).
Open Source Folder	Opens the folder containing the VBP (or ASP) source associated with the selected task.
Open .NET Project Folder	Opens the folder containing the generated .NET project associated with the selected task.
Reset Task Status	Resets key tracking fields associated with all selected tasks (RefStat, TrnStat, NetBlds, NetSize, LastMsg).
Run Translation	Translates all selected tasks. This can also be done by pressing (ALT-T).
Deploy Translation	Deploys the generated code bundles of all selected tasks.
Build Translation	Builds the .NET projects for all selected tasks.
Snapshot a Baseline	Saves a snapshot file of the last translation bundle for all selected tasks. The snapshots are saved in the [workspace]\log\sav folder. Snapshots are useful for inspecting the effects of source and configuration changes. See the section on Translation for how snapshots are used. This can also be done by pressing (ALT-B)
View Bundle File	Loads the generated code bundle file for the first selected task into the user-specified text editor. See the Deployment section for a full discussion of code bundle files.
Open Translation	Loads the generated project file for the first selected task in the associated IDE (e.g., VS2008). Selecting this menu item is the same as clicking [New IDE] on the Toolbar.
Re-bundle Translation	Generates a bundle file using the code in the .NET project folder and loads it into the user- specified comparison tool for comparison with the last code generated by the translator . This is used to help identify hand changes that should be integrated into the translation configuration and automated in subsequent translation runs.
Compare Translations	If two different migration tasks are selected, this loads their translation bundles in the user-specified comparison tool. If one task is selected, this loads the last translation bundle and the corresponding snapshot in the user specified comparison tool. This is useful for comparing translations of different source codes and different translation configurations. Selecting this menu item is the same as clicking [Compare] on the Toolbar.
Side-By-Side Viewer...	Opens the Side-By-Side Viewer form that facilitates comparison of the source and target codes for the selected task.
Toggle Fields: ...	Changes the set of fields displayed in the Migration Project Panel as specified by the FieldLayoutDefault and FieldLayoutAlt values in the application config file.
Remove Selected Task(s)...	Permanently removes the selected tasks from the migration project file.

Migration Project Panel Tips

Clicking the [Filter] button on the Toolbar displays the Task Filter dialog so you can filter the list to a specific subset of tasks. The filtered task count is displayed in the status bar. Clicking [Report/Project/Migration Set] on the menu produces a tab-delimited file based on the content of the task list. The relative height of the Migration Project Panel and the Task Details Panel can be set by clicking the form between the panels and dragging up or down as desired.

 Migration Details Panels

The Migration Details Panels is a set of four tab pages or panels at the bottom of the Main Form. In general, these panels present information associated with the migration task or tasks that are selected in the Migration Project panel.

1. Information Panel
2. Task References Panel
3. Source Metrics Panel
4. Session Log Panel
5. Code Search Panel

 Information Panel

The Information Panel provides access to seven different views of information:

• Task Details View is a one-up listing of the key fields that define the nature and status of the selected migration task. Below the field list you will find content of the file associated migration unit -- VBP or web file depending on the type of the migration project.

  Tip	Selecting a set of tasks and clicking [Reports/Projects/Migration Set] will produce a tab-delimited report of task detail data.

  
   

• VB6 Build Log View is summary information about the last attempted build of the VBP file associated with the migration task. An example of this content is shown below:

     ----- LOG: C:\GMS\samples\workspace\DemoScanTool\log\Interop2_csh-ScanToolLib-iop2-csh.VB6Bld.log -----
     Build of 'ScanToolLib.dll' succeeded.
     ----- OUT:C:\GMS\samples\source\ScanTool\ScanToolLib_VB6\build\ScanToolLib.dll -----
     Created:  06/05/2009 3:36:40 PM
     Modified: 09/09/2009 3:57:44 PM
     Size:     94208
  

  
   
• Translation Log View is the log produced by the translation process. The following operations can be performed in the translation log view:
  • Clicking the [Grid] checkbox will present the errors, warnings, and certain messages from the log in tabular form.
  • Double-Clicking a row in the grid will open the associated record of the Translation Script (if applicable).
  • Clicking the [Edit] button will open the log in the user-specified text editor.
  Right-Clicking a grid row will display the grid context menu that can be used to copy data for the selected row(s) to the clipboard.

  Tip	Selecting a set of tasks and clicking [Reports/Projects/Translation Log] will produce a tab-delimited report of translation log data.

  
   

• Deploy Log view is information about the deployment process and the generated code bundle. The following operations can be performed on the deployment log view:
  • Clicking the [Grid] checkbox will present the contents of the code bundle in tabular form.
  • Double-Clicking a row in the grid will open the associated record in the code bundle file.
  • Clicking the [Edit] button will open the log or the bundle file in the user-specified text editor, depending on which one is presently displayed.
  Right-Clicking a grid row will display the grid context menu that can be used to copy data for the selected row(s) to the clipboard.

  Tip	Selecting a set of tasks and clicking [Reports/Projects/Code Bundles] will produce a tab-delimited report of code bundle data.

  
   

• .NET Build Log is the log produced by the .NET build process. The following operations can be performed in the .NET Build log view:
  • Clicking the [Grid] checkbox will present the errors and warnings from the log in tabular form.
  • Double-Clicking a row in the grid will open the associated record of .NET code (if applicable).
  • Clicking the [Edit] button will open the log in the user-specified text editor.
  Right-Clicking a grid row will display the grid context menu that can be used to copy data for the selected row(s) to the clipboard.

  Tip	Selecting a set of tasks and clicking [Reports/Projects/.NET Build Log] will produce a tab-delimited report of .NET build log data. If you configure gmStudio to produce .NET projects contain instructions for doing code analysis, your .NET build log will contain code review results.

  
   

• Project Summary View is a brief report of summarizing totals and frequency counts for key field values of all tasks in the migration project. And example report is shown here.

     MigName: Interop2_csh (as of 09/09/2009 5:32:10 PM)
     Project: C:\gms\samples\workspace\_migrations\Interop2_csh.gmproj
     TaskTag: iop2=2;
     NetLang: csh=2;
     SrcBlds: SUCCESS=2;
     SrcSize: SUM=2245 LOC
     TScript: tran.scantool_iop.xml=2;
     RefStat: READY=2;
     TrnStat: SUCCESS=2;
     NetSize: SUM=3885 LOC
     NetBlds: SUCCESS=2;
     BldType: OleDll=1; Exe=1;
  

  Tip	Selecting a set of tasks and clicking [Reports/Projects/Metrics Summary] will produce an HTML report of project summary data.

  
   
• Edit/Save Task View is a grid for editing fields associated with the current migration task.

  Key Point: Only a few task fields should be hand-edited

  Most of the task fields are maintained by the system and should never be edited by hand. However, a few fields are there for the user. The following fields are the ones you may wish to edit: TaskTag: a user-defined code to identify logs and deployment folders TScript: a Translation Script template UsrCmds: a batch script template UsrCmnt: a user-defined comment (notes or categorization) UsrDesc: a user-defined description (notes or categorization)

 Task References Panel

The Task References Panel displays the external files referenced by the selected migration task. The list of external references is on the left and details about each reference is on the right.

If the migration task is for a VBP, the list contains COM components. Note that both explicit and implicit (i.e., imported library) COM references are shown.

If the migration task is for a web file, the list contains COM components and include files. Note that both explicit and implicit (i.e. nested includes of includes) are shown.

The following operations can be performed on the task references:

• Right-Clicking the list will display the reference context menu discussed below.
   
• Clicking a list item will select that item and cause its details to be displayed in the right-side pane. The details include a one-up report of the reference information and logs relating to creating the interface description file and Interop assembly for the reference.

Tip	Selecting a set of tasks and clicking [Reports/Code Scans/Source References] will produce a tab-delimited report of source reference data.

The References Context Menu items perform operations on the configuration information relating to each external reference of the first selected task:

Item	Description
Edit Source	Loads the source file for a given an external references into the user-specified text editor. For COM references this is an IDL file generated by gmStudio; for includes, this is the included file.
Edit Interface Description	Loads the Interface Description file associated with an external COM reference into the user- specified text editor.
Edit Refactor Library	Loads the Refactor Library file associated with an external COM reference into the user- specified text editor.
Rebuild Interop File	Rebuild the Interop Assembly file associated with an external COM reference
Rebuild Interface Description	Rebuild the Interface Description file associated with an external COM reference
Copy Record(s) to Clipboard	Copy detailed information for selected reference record(s) to clipboard
Select Source Task	If a referenced component has a source migration unit associated with it, this will select that unit in the migration task list.

 Source Metrics Panel

The Source Metrics Panel displays crude metrics for the selected migration task. The following operations can be preformed on the source metrics panel:

• Double-Clicking a row in the grid will open the associated source file
• in the user-defined text editor
• Right-Clicking a grid row will display the grid context menu

Tip	Selecting a set of tasks and clicking [Reports/Code Scans/Source Structure] will produce a tab-delimited report of source metrics data.

 Session Log Panel

The Session Log Panel displays a running activity log of your current session. The following operations can be preformed on the session log view:

• Clicking the [Grid] checkbox will present the log in tabular form.
   
• Clicking [Clear] button will clear the free-form text view.
   
• Right-Clicking a grid row will display the grid context menu that can be used to copy data for the selected row(s)

Key Point

The session log is saved as a tab-delimited file workspace\log\gmStudio.Session.tab. Beware that opening this file in a spreadsheet program during a session may lock it and prevent logging.

 Code Search Panel

The Code Search Panel is a useful tool for assessing your source codebase and inspecting translations.

The panel has two parts.

On the left side of the panel is a set of Search controls:

• The text box contains the content of the file [INSTALLDIR]\support\settings\CodeScanList.txt. This file contains the patterns that will be searched for. The file contains these instructions:

     ' Code Scan Pattern List Instructions
     '
     ' The scan reporter looks for each pattern above and
     ' reports matches.  When it encounters a blank record in
     ' the list of patterns it stops processing the pattern list
     '
     ' Each pattern is enclosed in double quotes.
     '
     ' "@pattern" -- @ means ignore case
     ' "~pattern" -- ~ means report files that do not contain
     '               For example ~Option Explicit string
  

  
   
• The two check boxes control the scope of the search.

  Source Search indicates that the source code associated with the selected migration tasks will be searched.

  Target Search indicates that the generated code bundles associated with the selected migration tasks will be searched.
   

• The [Search...] Button saves the text box content to the CodeScanList.txt file and then starts the search process. Matching records are written to the Search Results list.

On the right hand side is the Search Results list:

• Double-Clicking a row in the grid will open the associated source file in the user-defined text editor at the location of the match
   
• Right-Clicking a grid row will display the grid context menu that can be used to copy data for the selected row(s) to the clipboard.

Tip	Selecting a set of tasks and clicking [Reports/Code Scans/Source Code Scan] will produce a tab-delimited report of matches in the source code. Selecting a set of tasks and clicking [Reports/Utilities/Target Code Scan] will produce a tab-delimited report of matches in the target code.

 Statusbar

The status bar displays information about the state of the application.

The Status bar on the Main Form has two panels:

• The Message panel displays information messages and error messages. Error
• messages are displayed with a red back ground.

The Task Counts panel displays a string of the form:

   tasks: selected=#  filtered=#   total=#

Tip: See File...

When the status message is of the form "* See *", for example: Set Build Order Complete: See ... Interop2_csh-SrcOrder.txt double-clicking on the message panel will open the named file in the user-defined text editor.

 Side-By-Side Comparison Form

The Side-By-Side Comparison Form is used to compare specific sections in the source codes to the corresponding sections in the target codes. It is displayed by clicking [Side-By-Side Viewer...] from the Task Context menu.

You can use the class and member filters to narrow the member list at the top of the screen then select a specific member for display in source form, on the left, and .NET form, on the right.

You can also filter the content of the side-by-side view to display only those records that contain a given string.

 Batch Control Form

The Batch Control Form is used to setup and initiate the execution of a series of migration processing steps.

Default sequences of steps are setup for you and saved with the project file when you create a new migration project. If you change the selected set of steps and start the batch, that new sequence of steps is saved to the project file.

The batch control form also presents two check boxes:

• The first check box controls if the batch control box will display each time you click [Upgrade] on the Toolbar. This allows you to confirm the batch process before starting it. If you turn this option off, you can open the Batch Control dialog from the tools menu.
   
• The second check box controls if the session log should be displayed during processing so you can monitor progress.

Tip: Optimizing Batch Processing

Some of the batch steps are only required during initial Preparation or when your source codebase dependencies change. These preparation steps include: Apply Task Filter   Setting Build Order   Authoring Interface Descriptions   Authoring Interop Assemblies If the external dependencies of your codebase are fairly static, you can optimize your batch processing by un-checking the preparation steps and doing only the three core operations: Run Translation   Deploy Translation   Build Translation

Detailed descriptions of the Batch processing steps are presented in the Preparation, Translation, Deployment, and Verification sections of this guide.

 Task Filter Form

The Task Filter Form is used to specify which tasks should be displayed in the Migration Project Panel. This is helpful when you wish to work with a subset of the migration units.

The filter criteria is specified as pattern strings for each field in the task record structure. The patterns are not case sensitive and support '*' as a wild card; for example:

pattern	meaning
*	field can be any value
abc*	field begins with 'abc'
*abc*	field contains 'abc'
*abc	field ends with 'abc'
abc	field equals 'abc'

Your filter settings are saved in the project file so they can be reapplied automatically when you open the migration project.

Tips	Pressing CTRL-F will display the Filter dialog. Checking Ignore will temporarily turns off Task Filtering.