The gmStudio Main Form provides access to all common application functions. The screen has six major components:
Resizing the Top Panel
An image of the Main Form is shown below.
The gmStudio Main Menu is discussed below.
The File Menu is used for managing migration project files:
|New... Use New Project Wizard...|
Runs the gmStudio Upgrade Wizard for automatically creating and running a new upgrade project from a source code folder – in turnkey, push-button fashion.
|New... Use Project Setup Form...||Displays the Migration Setup form so you can create a new migration project file.|
|New... Create a Specification Code...||Displays the Specification Code Setup form so you can shell VB6 code and corresponding project and experiment with a specific upgrade issue|
|New ... Add Tasks to Current Project...||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.|
|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. Note: Holding the Ctrl-Key while clicking Open will allow you to open a gmProj in a new gmStudio instance.|
|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.|
|Recent Files||Allows you to open one of the 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.|
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 in an instance of Windows Explorer. Note: Holding the Ctrl-Key while clicking a View menu Item will open a Windows Console prompt in the selected folder.
|Source Root||Opens the current source code folder|
|Workspace||Opens the current workspace root folder.|
|Runtime Assemblies||Opens the Runtime Assembly folder, where pre-generated runtime assemblies are stored (Interop or other .NET assemblies).|
|Interface Descriptions||Opens the Interface Description folder, where pre-generated Interface Description Files (IDFs) are stored (and used 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 the generated .NET code bundles are stored for subsequent deployment.|
|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.|
|Interop Workspace||Opens the Interop Workspace folder, where any pre-generated Interop assemblies are located|
|Compare Snapshot Folder||Opens the Deployment Folder of the current upgrade, for side-by-side comparison with the snapshot of a previously-saved upgrade.|
Most of the Tools Menu items perform various migration preparation operations:
The View Menu items are as follows:
|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:
|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.|
Each Reports Menu item runs a specific type of report for all selected tasks and then opens the resulting report file for viewing:
|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.
The Help Menu items access system documentation and diagnostics:
|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.|
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:
|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).|
|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 translationsThis can also be done by pressing (ALT-C).|
|VB6/ASP||Loads the source migration unit (Vbp or Web file) in the associated IDE (usually VB6).|
|.NET||Loads the generated .NET project in the associated IDE (usually Visual Studio).|
|Settings||Displays the [Configuration] dialog so you can edit application and system settings.|
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:
Optimizing Batch Processing
The Presets dropdown allows you to select from a number of default presets or indicate you are using your own custom set.
Detailed descriptions of the Batch processing steps are presented in the Preparation, Translation, Deployment, and Verification sections of this guide.
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:
|*||field can be any value|
|abc*||field begins with 'abc'|
|*abc*||field contains 'abc'|
|*abc||field ends with 'abc'|
|abc||field equals 'abc'|
|pattern1+pattern2||field matches pattern1 or patten2|
Your filter settings are saved in the project file so they can be reapplied automatically when you open the migration project.
The Project Task List 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 Project Task List:
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:
|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.|
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.
The Project 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.
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.
Selecting a set of tasks and clicking [Reports/Projects/Migration Set] will produce a tab-delimited report of task detail data.
----- 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
Selecting a set of tasks and clicking [Reports/Projects/Translation Log] will produce a tab-delimited report of translation log data.
Selecting a set of tasks and clicking [Reports/Projects/Code Bundles] will produce a tab-delimited report of code bundle data.
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.
MigName: Interop2_csh (as of 09/09/2009 5:32:10 PM)
SrcSize: SUM=2245 LOC
NetSize: SUM=3885 LOC
BldType: OleDll=1; Exe=1;
Selecting a set of tasks and clicking [Reports/Projects/Metrics Summary] will produce an HTML report of project summary data
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:
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.
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:
|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.|
The Source Metrics Panel displays crude metrics for the selected migration task. The following operations can be preformed on the source metrics panel:
Selecting a set of tasks and clicking [Reports/Code Scans/Source Structure] will produce a tab-delimited report of source metrics data.
The Session Log Panel displays a running activity log of your current session. The following operations can be preformed on the session log view:
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.
The Search Panel is a useful tool for assessing your source codebase and inspecting translations. You can also use it to quickly find content in your migration project's configruation and the system translation configuration.
Setting the Scope of the Search
In most cases the scope of the searching process is limited to the tasks selected in the migration task panel if applicable.
On the top of the panel is a the search option box it allows you to control the scope of the search:
Allows you to restrict the search process to a files matching a specific pattern. For example entering *.vbp will only search VBP files.
The Custom box also allows you to specify a folder as well as a file pattern. Using the form folder|filespec. For example
The folder|filespec format also allows searching multiple filespec patterns by separating them with ';' for example *c:\gmtestBed|*.frm;*.bas;*.cls*
Setting the patterns to search for
On the bottom left is the search pattern box. A default set of search terms is in the file[INSTALLDIR]\support\settings\CodeScanList.txt. This will be copied to your workspace\usr folder if one is not present in your workspace. The default file contains the usage instructions shown below. The file in your workspace\usr folder may be used to store past search terms.
The search pattern box in general contains regex expressions, but the first character has special significance.
You may search for multiple terms at once by putting each one on a separate line.
On the left, under the search option box is the [Start] Button. Clicking [Start] saves the search pattern list to CodeScanList.txt file and then starts the search process. Matching records are written to the Search Results list.
Next to the [Search] button is the [Save] Button. Clicking [Save] will display a Save File dialog so that you can save selected records from the Search Results List to a tab delimited file. By default the file will be saved in the reports folder and named [MigName]-Search-[name].tab where [MigName] is the migration project name and [name] is the string you type into the Save File dialog.
On the right hand side is the Search Results list:
Many of the search results can be also generated using the Reports menu or the Reports Panel. For example.
Search results may be reported using parameterized reporting templates as specified in the template textbox. A reporting template is static text and value placeholders. Examples of value placeholders are shown below:
The reporting template starts at the top of this template box and ends with the record containing '.' in column 1, or the end of the template textbox.
If the pattern for the search had regex groups (i.e. enclosed in parentheses), then the parameters may correspond to the values from the groups (% ... %[n])
To author a '%' in the pattern, precede it with caret '^'.
Pre-defined templates may be named and stored in this file as shown below. These templates may be selected from the context menu of the template textbox.
The Reports panel is used to run gmStudio reports in batch and browse the contents of the reports folder for your migration project.
On the left side of the reports panel is the Report Settings controls:
The report selection Listbox contains various migration reports grouped by report type. You can add a report to the batch for by checking its check box. Likewise, un-checking a report's checkbox removes it from the batch.
There are two report scope radio buttons.
Clicking [Edit Patterns For Scan Reports...] will load CodeScanList.txt into the user-defined text editor. This file contains a list of search patterns to search for when you run the [Source Code Scan] and/or [Target Code Scan] reports.
Clicking [Run Selected Reports] will start the reporting process. This button will toggle to [Cancel] while reports are running, clicking [Cancel] aborts the reporting process.
On the right side of the report form is the list of files in the reports folder. Double-Clicking a row in the list will open the selected report file in the associated editor.
Learn more about gmStudio reports in the Reporting section of the guide.
The status bar displays information about the state of the application.
The Status bar on the Main Form has two panels:
The Task Counts panel displays a string of the form:
tasks: selected=# filtered=# total=#
Status Bar Features
Quick Open a Log 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.
Display Full Message
If the status bar message is not like "See *", double clicking the message will open the full text of the message in the session panel. This is useful if a message does not fit in the status panel.
The Side-By-Side Comparison Form is used to compare specific source codes to the corresponding 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 search the content of the side-by-side view for records that contain a given string or regular expression.