gmplLanguageStatement

Language Statement Summary

Language is the primary statement that controls a language definition. The language statement occurs within a command script whose startup tag is Metalanguage. When gmBasic encounters a command script with the Metalanguage startup tag in suspends its normal operation in expectation of processing its language definition. The standard language specification file starts as follows

   <MetaLanguage>
      <Include Filename="Messages.xml" />
      <language id="Basic" >
        ...

The messages file contains a Messages statement which defines the error messages used by gmBasic when it processes statements, including its own language definition. The language statement must be preceded by the Messages statement, but may not be preceded by any other statement. The final output of the Metalanguage command script is a virtual binary information file called vb7lang.vbi which must be stored in the home directory of gmBasic which, by default, is the directory that contains the actual executable file. See the gmCL discussion for details on controlling how gmBasic starts up.

The attributes of the Language statement are as follows:

Attribute	Description
Id	This required attribute is the identifier of the language being defined. gmBasic requires a definition identifier of Basic.

The substatements of the Language statement are as follows:

Substatement	Description
Select	This is a standard Select statement as described on that page; however, it has one important difference. The attribute settings are saved in the language file and are used to set the default values of those attributes on all subsequence uses of gmBasic.
Library	This is a standard Library declaration used to define an external set of classes for the internal scripting language gmSL. The library is called gmSLang.dll. The actual implementation of these classes is internal to gmBasic. The pages under gmSL describe this language and its classes.
Class	This is a slightly enhanced version of the Class statement that references the operation codes. These enhancements are described in the declaration description pages for the various class components. The classes defined are the built in classes of the VB6 language and its various control class extensions (See the discussion on overriding language classes).
Enumeration	This is a slightly enhanced version of the Enumeration statement that references the operation codes. These enhancements are described on the Enumeration page.
Opcodes	This statement associates identifiers with the numeric operation codes that specify the basic operations performed within the intermediate language. It is these identifiers that are used to refer to those operations in the language definition.
Default	This statement is used to specify default control properties that are ultimately to be authored in the designer code.
Patterns	This statement initiates the definition of surface patterns for the operation codes in the intermediate language.
Statements	This statement is used to specify which statements are available in the language and what the attributes are of those statements. In this context, the languages defined are not the source language, VB6, but the internal languages used by gmBasic.

The script errors associated with the Language statement are as follows:

Error	Description
1064	Language command missing required id attribute.
1065	Unable to store Language id: %1d
1066	The following record is not recognized: %1d

Overriding VB6 Language Classes

The language file, among other things, contains generic descriptions and migrations for the common controls defined within the VB6 libraries that were loaded implicitly by Visual Basic:

Control	Opcode, .NET Class
PictureBox	PBX, System.Windows.Forms.PictureBox
Label	LAB, System.Windows.Forms.Label
TextBox	TXB, System.Windows.Forms.TextBox
Frame	FRA, System.Windows.Forms.GroupBox
CommandButton	CMB, System.Windows.Forms.Button
CheckBox	CBX, System.Windows.Forms.CheckBox
OptionButton	OBU, System.Windows.Forms.RadioButton
ComboBox	CBO, System.Windows.Forms.ComboBox
ListBox	LSB, System.Windows.Forms.ListBox
HScrollBar	HBR, System.Windows.Forms.HScrollBar
VScrollBar	VBR, System.Windows.Forms.VScrollBar
Timer	TIM, System.Windows.Forms.Timer
DriveListBox	DLB, Microsoft.VisualBasic.Compatibility.VB6.DriveListBox
DirListBox	DIR, Microsoft.VisualBasic.Compatibility.VB6.DirListBox
FileListBox	FLB, Microsoft.VisualBasic.Compatibility.VB6.FileListBox
Menu	MEN, System.Windows.Forms.ToolStripMenuItem
Shape	SHA, System.Windows.Forms.Label
Line	LIN, System.Windows.Forms.Label
Image	IMA, System.Windows.Forms.PictureBox

The bulk of these generic migrations are probably sufficient for most migration projects; however the three controls — DriveListBox, DirListBox, and FileListBox — do not have direct .NET equivalents and therefore are migrated to the Microsoft.VisualBasic.Compatibility.VB6 namespace. The use of this namespace raises a red flag for many migrations. The distribution of gmBasic contains a reference script Language.std.xml that will replace the migration of these three controls with a standard COM/IDF translation into a MigrationSupport.UI migration. These translations will contain the standard stubbed implementations that can then be completed by the migration team. To use this file simply place it in the IDF search path of the migration.

The only special characteristic of the Language.std.xml reference script is that it is auto-loaded by gmBasic immediately before it performs a compilation. See the discussion of the LoadEnvironment statement for details. The file itself is a source file, so it can be edited by the user if desired. In addition, the std portion of the name is the sysid of the translation script; therefore, alternative migrations can be specified that are triggered by different ids. Finally, completely independent reference scripts can be authored and loaded via the Reference statement. During a given translation run, and reference script class whose name matches and internal control class name and that has the additional adornment migStatus=“OverrideUser” will override the specification of the internal control. Thus, an entry

 <class id="DriveListBox" parent="None" default="Drive" migStatus="OverrideUser" >

overrides the definition of the internal DriveListBox control in the language file; while, the entry

 <class id="TextBox" parent="None">

as taken from the Excel.exe.xml reference script does not override the internal TextBox control in the language file.

To begin the external migration of a language control begin by extracting its class definition from the source language file vbcontrols.xml and placing it in a new reference script. Next, remove all the opcode attributes and add migStatus=“OverrideUser” to all class definitions. There may also a few refactoring specifications that can be simplified and removed. In the case of the Language.std.xml, properties that had the adornment status=“Dimen” where simply changed to have the Collection type; and some properties that had individual GetSetLet specifications were simplified.