The gmStudio Main Form provides access to all common application functions. The screen has six major components:
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 gmStudio Main Menu is discussed below.
The File Menu is used for managing migration project files:
|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.|
Most of the View Menuitems open the various working folders for the current migration project. Several other items open various application and system Configuration File folders:
|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.|
Most of the Tools Menuitems 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 selectedtasks 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 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).|
|Settings||Displays the [Configuration] dialog so you can edit application and system settings.|
The Migration Project Paneldisplays 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:
The Task Context Menuitems 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. (TODO: update new behavior)|
|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.
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.
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 Size: 94208
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) 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 Viewis a grid for editing fields associated with the current migration task.
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)
The Task References Paneldisplays 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 Paneldisplays 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 Paneldisplays 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 configuration and the system translation configuration. 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:
Replacement indicates that the tool should perform a search and replace operation. In this mode of operation, you must supply one or more replacement blocks:
Enter regular expressions for search and replace. Use multiple replace blocks to perform multiple replacements. User, Target Code files can be used as input; Or, Specify Directory|FileSpec in Custom Box.
Results will be written to a workspace\report\replacement
1) The search replace uses .NET regular expressions. You can use capture groups in the OldBlock by enclosing them in parentheses and then reauthor those groups in the result using $n notation.
2) After the search and replace is complete, you can use your file comparison tool to verify/merge the modified copies back into the original file locations.
3) The Replacement feature is typically used to do widespread maintain your user files in response to changing coding standards.
The CodeScanList.txt file contains the patterns that will be searched for.
When first installed, the file contains the usage instructions shown below. The installed file also contains some samples of search patterns.
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 selectedrecords 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:
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.
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.
Selecting [All Tasks] will run the reports for all tasks in the migration project -- even if they are filtered from the list on the project panel, and even if they are not selected on the project panel.
Selecting [Selected Tasks Only] will run the reports only for the tasks that are selected on the project panel -- like running a report from the Report menu on the Main Form.
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.
Most of the gmStudio reports are in tab-delimited format and saved as .TAB files. When you try to open one from gmStudio, it runs the application you have associated with .TAB files -- ideally a spreadsheet program that can facilitate filtering, sorting, and making pivot tables of the data. If you do not have an application associated with .TAB files, gmStudio will not be able to open the files and will report an error. Instructions for how to associate a file with an application are here.
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=#
Click on 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.
The Side-By-Side Comparison Formis 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.
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
Some of the batch steps are only required during initial Preparation or when your source codebase dependencies change. These preparation steps include:
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:
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'|
|+||multiple patterns may be specified as a '+'-delimited list|
Your filter settings are saved in the project file so they can be reapplied automatically when you open the migration project.
Pressing CTRL-F will display the Filter dialog. Checking Ignore will temporarily turns off Task Filtering.