gmPL Declaraction Statements

The gmPL declaration statements are organized into libraries and except for the Library statement itself are substatements of that command. The fundamental difference between the declaration statements and the other statement groups is that declaration statements are initially authored by gmBasic and then modified by the user as the translation process proceeds. The content of gmBasic authored declaration statements comes from two sources, Idl representations of external libraries and the translated code itself. The declaration statements are as follows:

Statement	Description of use
Library	Declares an external component like a dll, or an ocx, or an olb, or a tlb whose components are referenced by a source code but not defined within the source code.
Class	Declares a class within a library.
Coclass	Declares a class that is actually defined as the union of a set of classes.
Enumeration	Declares an enumeration within a class or a library.
Method	Declares a method within a class.
Argument	Declares an argument within a method, event or accessor.
Property	Declares a property within a class
GetSetLet	Declares separate Get, Set, Let components within a property
Field	Declares a property in a class whose origin was a class variable as opposed to a property.
Accessor	Declares a property with both set and get access that has arguments.
Event	Declares a event within a class.
Constant	Declares a constant within a class or library.
Structure	Declares a structure within a class or library
Typedef	Declares a typedef within a library.

All components managed by gmBasic share three sets of flags -- context, status, and process. Each flag is a binary property -- on, off or true, false. Each flag has the same meaning regardless of the component that it is assigned to. Many of the attributes within the declaration statements manipulate these flags in various ways. The flags themselves are described in general as topics here. The phrase "is marked with a flag" is used to mean that the flag is turned On. In all cases, the default value of a flag for a given component is Off.

Declarations that define quantity components, components that have values, have a Type attribute that defines the binary type of those values. This attribute is the same for all declarations and is described here.

Component Context flags

The component use context flags specify how the component is used, or is to be seen as used in its source context. The names of the context flags are in the ContextFlags enumeration in the language file. The flags themselves are as follows:

Flag	Description
Private	The component is declared as being private to the parent that contains it. This may because of an explicit declaration or it may be a flag added to the component for some reason.
Public	The component is declared as being public. This normally means that it may be referenced anywhere in the code.
Static	The component is declared as being static. This normally means that its parent keeps only one parent-wide value for the component as opposed to allocating a new value each time a parent object is created.
WithEvents	The component was declared as being WithEvents. Which means that events can occur for the object for which event handlers might be present in the source code.
Argument	The component is an argument of a subprogram or method or accessor or event.
ByVal	The component is an argument which will be called by value.
ByRef	The component is an argument which will be called by reference.
Foreign	The component was referenced in a comprehensible way, but no definition of it could be found in either the user code or the libraries being referenced.
DeadCode	The component has been marked as being dead code. This means that its declaration will be skipped. This flag has no effect on references to the component. See the Migration status flags for more information on dead component references.
UseGet	The component requires the use of a "getter" to access its value.
ByOut	The component is an argument whose value will be stored in the calling reference location when its subprogram exits.
Optional	The component is an argument that may be optionally omitted when its subprogram is called.
NotDeclared	The component is being used as a variable but was never declared.
FixedType	The component has been assigned a type which should not be changed by the analyser.
Friend	The component has the Friend status, which is derived but which often simply means that it was not explicitly declared to be public or private.
Overload	The component needs to be explicitly given the Overload adornment when declared.
Dimensioned	The component when declared was explicitly dimensioned via a size or set of size specifications. This size specification is stored as well.
Changed	In processing the source code the compiler determined that the value of the component was being changed. This flag is later used by the algorithm that assigns arguments ByVal calling status.
New	The component was declared as being new.
ParamArray	The argument component is in fact a parameter array -- will contain a variable-length list of objects/values being passed to a subprogram.
InLibrary	The component is allocated to an external library and its declaration may require extra adornments. This is used in particular with structures that are referenced via declare arguments.
IsDefault	The component is the default component for its parent.
Collection	The component is a collection class or a control vector.
Array	The component is declared or is referenced as though it were an array even though it may not have been explicitly dimensioned.
2dArray	The component is declared or is referenced as though it were a two-dimensional array even though it may not have been explicitly dimensioned.
Inferred	The component has an inferred type.
Protected	The component requires the protected adornment when it is declared.
InModule	The component is declared within a module file.
Initial	When the component is declared it should be initialized with the default initialization value for its type.
Resources	The component has a set of resources associated with it that were originally stored in an frx file.
Passed	The component is an argument whose calling status is unspecified, that has been passed to another subprogram. This flag is needed to trace the change status of that argument.

Component status flags

The component status flags describe the status of the component relative to the overall migration. They can be assigned by gmBasic, but are also often declared via the declaration statements and are manipulated via the refactoring statements. The names of the status flags are in the MigStatusFlags enumeration in the language file. The flags themselves are as follows:

Flag	Description
NotImplemented	The component has no implementation in the target. References to it are commented out and adorned using "#if !DEBUG\n\t#error \sUPGRADE ISSUE: %1d was not upgraded.\s\n#endif\n"
Delete	The component should be deleted from the target. References to it are literally removed from the target code.
CanBeNull	The component itself, or its instances, are being for being empty. These instances can be Null as well. References to them in the intermediate code have to be checked if they are they are Null or Empty.
UserCode	There may be runtime gmNI user code for processing this component. The identifier of this component, that triggers the event handler code, is specified for the component in its comment field.
External	The component is external to the parent in the target implementation to which it was assigned in the source implementation. Therefore, when authoring the identifier of the component do not precede it with its source parent membership information.
NeedsInit	In general this flag specifies whether the component needs to be initialized by the author in the target code. For control arrays, when the analyser detects an explicit reference to the control array in any subprogram code, it sets this flag for the control.
HasMigclass	There is a user-defined or library-defined migClass that controls some aspect of the component.
LocalLibrary	The library was formed as via a translation of a VB6 project within the migration set as opposed to being formed directly from an IDL file.
Remove	References to the component should be removed as opposed to deleting and statements that reference the component. This is used primarily for subprograms and subprogram arguments.
ChangeParent	This flag is deprecated and not currently used, though references to it may still exist in older reference files.
AddArgument	This flag is used with subprograms. It indicates that an argument should be added to the argument list in the target translation.
CallPattern	The surface form pattern associated with the component should be used when it is referenced, not when it is translated.
OverrideUser	For components that are used to satisfy Implementation requirements, this flag forces the component to have the attributes as specified in the interface as opposed to as specified in the user code. When applied to classes whose identifiers match those of control classes within the internal VB6 language description, this flag indicates that the internal description should be overridden.
SkipDecl	Set by the analyser to mark property setters and/or getters that can be skipped.
Static	The component is static in the target implementation and thus any New creations must be removed.
IsDbNull	The component is a class whose instances should be checked against DbNull as opposed to Null.
MustCorrect	The component must be corrected in the target. References to it are commented out and adorned using "#if !DEBUG\n\t#error \sUPGRADE ISSUE: %1d was not upgraded.\s\n#endif\n"
Noncreatable	The component class objects cannot be created. When declaring objects of this class simply NULL them as opposed to using new to create an instance.
SingletonRef	The library component has been referenced as a singleton, without any class or parent designation. This may be an incorrect reference that has to be repaired.
StubOut	Any code associated with the component should be ignored but a stub for the component should still be declared.
Override	The subprogram component requires the Override specification when it is declared.
CastType	The component does not require type casts when setting its values.
Referenced	This flag is used by the author to mark those components that are actually referenced and that need to be included when authoring a wrapper.
SingletonUsed	The library component has been used as a singleton, without any class or parent designation. This usage may be incorrect and in need of repair.
AppObject	The component is an application wide singleton object which requires that special AppObject code be authored for it.
ArrayArray	The component is two-dimensional but should be authored as a array of arrays -- e.g. [][] -- as opposed to [,].
Module	The interface component is a module as opposed to a class, so its members may be referenced as singletons.
Implements	The class or interface component is implemented by another class in the current migration group.
ActiveX	The coclass component is a control which can appear on a form; consequently there are special Ax naming conventions that must be used.
UsesCOM	The component should be treated as though it were an ActiveX control.
BoxTypes	This deprecated flag is used by the compiler when it encounters a potential late binding to this component. It checks if that late binding could be resolved if the reference were boxed to one of several types. If so do it, if not do the late binding. The CallByName refactoring statement provides an extensive facility for dealing with late bindings.

Component Process Flags

The component process flags specify the details about the migration process associated with the component.They can be assigned by gmBasic, but are also often declared via the declaration statements and are manipulated via the refactoring statements. The names of the status flags are in the MigProcessFlags enumeration in the language file. The flags themselves are as follows:

Flag	Description
CallBack	When the main analyser logic encounters a reference to the VB6 function AddressOf then it must determine if the use of the AddressOf call is to establish a CallBack. If so then it marks both the method that is the callback and the argument receiving the AddressOf with the CallBack flag so that they can be dealt with properly by the author.
ZeroBased	This is not set internally only via refactoring statements. It is used by the analyser to decrement subscripted references to components with this flag set.
WasActiveX	When coclasses that were ActiveX controls are declared they are marked with this flag. It is used by the author to indicate the need to inherit from the Control class.
HasForEach	This flag is attributable to classes and coclasses. It indicates that the component is used in ForEach and must, therefore, implement IEnumerable.
Constructor	This attribute is a flag attributable to members whose On entry indicates that they are being called directly within the code; therefore, their wrapper class requires a constructor.
ColObject	This attribute is a flag attributable to the library whose On entry indicates that a referenced component within the class has a collection type; therefore, the library stub must import VBNET = Microsoft.VisualBasic.
HaveEventArgs	This attribute is a flag attributable to event handlers whose On entry indicates that they have arguments.
NeedsLet	This attribute is attributed to library methods to indicate that they are being used to set a property value and thus need a Let.
Implements	When the compiler notes that a component is being used to implement a separate component it marks the implementing component with this flag.
Shadows	'Shadows' is yet another alternative to 'Overrides' and 'Overloads'. The 'Shadows' keyword indicates that a declared programming element shadows, or hides, an identically named element, or set of overloaded elements, in a base class. You can shadow any kind of declared element with any other kind. The purpose of shadowing is to protect the definition of the class members. It is used with Class, Const, Declare, Delegate, Dim, Enum, Event, Function, Interface, Property, Structure, and Sub Statements.
PropertyBag	This attribute tells the property bag processor of to look for BeginProperty and NameValue pairs for this component.
RemoveResumeNext	This attribute tells the analyser to turn off the "On Error Resume Next" to try-catch conversions for a particular subprogram. The algorithms used here are fairly robust, but can never be perfect. Specific codes may well encounter problems that are best dealt with by simply turning the algorithms off.
RemoveOnErrorGoTo	This attribute tells the analyser to turn off the "On Error Goto" to try-catch conversions for a particular subprogram. The algorithms used here are fairly robust, but specific codes may well encounter problems that are best dealt with by simply turning the algorithms off.
Overloads	The component requires the Overloads adornment when it is declared within VB.NET as a subprogram. When applied to a parameter, it means that the parameter is an optional argument whose value must be supplied when the subprogram containing it is declared.
CodeAnalysed	Indicates that the code associated with a code unit has already been analysed.
TypeInferred	Indicates that the type of a component has been inferred.
InInterface	Indicates that a component is in an interface
OptionBase1	First if Option Base = 1, the pass1 compiler marks those variables that have explicit dimensions as having OptionBase1 subscripts; Second, the final pass of the analyser looks for references to the LBound and UBound functions applied to the variables marked and adjusts them by adding 1; Third, the author of the subscripts makes the appropriate adjustment to the dimension value in the declaration of the marked variables.
FixedSource	This attribute is applies to an ASP page once it has been processed by the Fix logic. Once this flag is set the page is skipped if it appears in a subsequent pageslice.
ObjectOnly	Indicates that a quantity of type Variant or Object should not be type inferred.
BlockTemps	This attribute is applied to subprograms. It blocks the formation of a TempArg when converting a Select into an If.
ArrayInfer	Indicates that a quantity has had its array status inferred based on a reference to it in the code.
Exposed	Only public symbols in classes are exposed in VB6 however in .NET module components can be exposed as well. The SharedFile logic marks these components accordingly.
SharedFile	Not used
NotByRef	Some value bearing components like members of structures, even in an indexed context, can not be passed by reference. This flag is used to indicate this.
HasCodeHandler	When a refactoring specification for an external component encounters gmSL code it scans that code for transform methods. Any component for which a transform method is found is has its HasCodeHandler flag set true and has its migTransform method set equal to the root offset of the handling user code method.
EnforceType	This attribute is set true via the refactoring FixType statement. It applies to subprogram parameters and means that any argument passed to this parameter should have the parameter type enforced on it as opposed to doing any type inference.
HasWeakSetter	This attribute is set true via the refactoring Migrate statement. It applies to library components that have setters. If the attribute is True then the setter is treated as having type Variant or object regardless of any type associated with the component. It also blocks any type inferences for the component that might be derived from a strongly typed set to it.
HasPatterns	This attribute is set within the processing of Property statements in external classes. It indicates that the old GetSetLet syntax was used to define those patterns. The pattern capabilities were extended to use a generalize pattern syntax and this flag blocks a migration that does not apply to the older form.
ConditionalRemove	This attribute is set true via the refactoring Remove statement. It tells the author that rather than stubbing out the code the code should be removed by surrounding it with conditional statements.
ImplicitByRef	This attribute is set true via the ImplicitByRef attribute on the library declaration statement. When it is on, the tool assumes that the .NET compiler will be handling ref arguments implicitly. For the purposes of ByRef optimization, the analyzer will still treat ref arguments as ByRef, but it will not generate temporary arguments.

Declaration Type Attribute

This attribute specifies the binary type of the identifier. It consists of a type-specification followed by [] indicating that it is a 1-dimensional array, or [,] indicating that it is a 2-dimensional array, or [][] indicating that it is a 1-dimensional array of 1-dimensional arrays There are a large number of built in types defined within gmBasic. First there are the basic types. The names of these types are considered to be reserved words. They are checked first when processing a type-specification before checking for a code defined type. These types are as follows:

VB6	.NET Equivalent C#, VB.NET
Byte	byte, Byte
Short	short, Short
Integer	int, Integer
Long	long, Long
Currency	decimal, Decimal
Single	float, Single
Double	double, Double
String	string, String
Boolean	bool, Boolean
Date	DateTime
Variant	object, Object
Object	object, Object
User	object, Object
Control	System.Windows.Forms.Control

Second, there are some IdlSpecial type names that appear in the IDL files and are passed through to the description files:

IdlSpecial	.NET Equivalent C#, VB.NET
IUnknown	object, Object
LongLong	long, Long
Long	int, Integer
stdole.IUnknown	object, Object
Collection	VBNET.Collection, Collection
Font	System.Drawing.Font
stdole.Font	System.Drawing.Font
OLE_COLOR	System.Drawing.Color
stdole.IDispatch	object, Object
stdole.OLE_COLOR	System.Drawing.Color
None	object, Object
BSTR	string, String
VARIANT_BOOL	bool, Boolean
OLE_HANDLE	IntPtr
System.UInt32	int, Integer
System.Double	Double
System.IntPtr	IntPtr
System.Byte	byte, Byte
System.Decimal	decimal, Decimal

Third there the special processing types used by gmBasic to deal with various special circumstances:

Vb6Special	.NET Equivalent C#, VB.NET
Icon	System.Drawing.Icon
FrxPicture	System.Drawing.Image
Any	object, Object
TwipsX	int, Integer
TwipsY	int, Integer
UnsInteger	unit, Integer
WinPanel	System.Windows.Forms.GroupBox
VarArray	Object[], Object()
StringPtr	System.Text.StringBuilder, String
CallHwnd4	MigrationSupport.Vb7_Callback.Hwnd4
ControlCollection	System.Windows.Forms.Control.ControlCollection
CheckedListBox	System.Windows.Forms.ListBox
Exception	System.Exception
SafeArray	System.Array
SecurityManager	UserSecurityManager
Dynamic	dynamic
ValueType	object, Object

Fourth are the VB6 classes:

Vb6Class	.NET Equivalent C#, VB.NET
PictureBox	System.Windows.Forms.PictureBox
Label	System.Windows.Forms.Label
TextBox	System.Windows.Forms.TextBox
Frame	System.Windows.Forms.GroupBox
CommandButton	System.Windows.Forms.Button
CheckBox	System.Windows.Forms.CheckBox
OptionButton	System.Windows.Forms.RadioButton
ComboBox	System.Windows.Forms.ComboBox
ListBox	System.Windows.Forms.ListBox
HScrollBar	System.Windows.Forms.HScrollBar
VScrollBar	System.Windows.Forms.VScrollBar
Timer	System.Windows.Forms.Timer
Printer	MigrationSupport.Printer
Form	System.Windows.Forms.Form
DriveListBox	Microsoft.VisualBasic.Compatibility.VB6.DriveListBox
DirListBox	Microsoft.VisualBasic.Compatibility.VB6.DirListBox
FileListBox	Microsoft.VisualBasic.Compatibility.VB6.FileListBox
Menu	System.Windows.Forms.ToolStripMenuItem
MDIForm	System.Windows.Forms.Form
Shape	System.Windows.Forms.Label
Line	System.Windows.Forms.Label
Image	System.Windows.Forms.PictureBox
Data	MigrationSupport.DataControl.DataControl
PropertyPage	MigrationSupport.PropertyBag
TabControl	System.Windows.Forms.TabControl
ErrObject	VBNET.ErrObject, ErrObject

Fifth are the VB6 enumerations:

Vb6Enumeration	.NET Equivalent C#, VB.NET
SimpleBorderStyle	System.Windows.Forms.BorderStyle
KeyCodeConstants	System.Windows.Forms.Keys
LogEventTypeConstants	System.Diagnostics.EventLogEntryType
DrawStyle	MigrationSupport.Utils.DrawStyle
DrawMode	MigrationSupport.Utils.DrawMode
MousePointerConstants	System.Windows.Forms.Cursor
WindowStyle	VBNET.AppWinStyle, AppWinStyle
OpenMode	VBNET.OpenMode, OpenMode
vbTristate	VBNET.TriStatem TriState
ScaleType	MigrationSupport.Utils.ScaleType
VbCompareMethod	VBNET.CompareMethod, CompareMethod
VbFileAttribute	VBNET.FileAttribute, FileAttribute
MsgBoxResult	VBNET.MsgBoxResult, MsgBoxResult
VbMsgBoxStyle	VBNET.MsgBoxStyle, MsgBoxStyle
VariableType	VBNET.VariantType, VariantType
ButtonAppearanceStyle	System.Windows.Forms.Appearance
ApplicationStartMode	MigrationSupport.Utils.StartMode
MouseButtonConstants	System.Windows.Forms.MouseButtons
ResourceType	MigrationSupport.Utils.ResourceType
FirstDayOfWeek	VBNET.FirstDayOfWeek, FirstDayOfWeek
FirstDayOfYear	VBNET.FirstDayOfYear, FirstDayOfYear
DueDate	VBNET.DueDate, DueDate
AlignConstants	MigrationSupport.Utils.AlignConstants
CheckboxConstants	System.Windows.Forms.CheckState
AlignmentConstants	System.Drawing.ContentAlignment
BorderStyle	System.Windows.Forms.FormBorderStyle
ComboBoxStyle	System.Windows.Forms.ComboBoxStyle
ColorConstants	System.Drawing.Color
LayoutArrangement	MdiLayout
RLDirection	System.Windows.Forms.RightToLeft
ShiftConstants	MigrationSupport.Utils.ShiftConstants
BackStyle	MigrationSupport.Utils.BackStyleConstants
QueryUnloadConstants	MigrationSupport.Utils.QueryUnloadConstants
ClipboardConstants	MigrationSupport.Utils.ClipboardConstants

Declaration Status attribute

The context flags to be explicitly associated with components are often combined with each other in logical sets or are given names that resemble the equivalent names used in VB6 or IDL. These are defined in a metalanguage enumeration PropertyStatus and are specified via a Status attribute in various declaration statements. The entries are as follows:

PropertyStatus	Equivalent context flags
SetByRef	ByRef + UseGet
GetSet	UseGet
GetSetLet	UseGet
UseGet	ByVal + UseGet
In	ByVal
Out	ByOut
InOut	ByRef
Dimen	ByVal + Dimensioned
ByVal	ByVal
Static	Static
ByRef	ByRef
Indexer	Collection
Protected	Protected
ColItem	Collection
Vector	Array
ParamArray	ParamArray
RefParamArray	ByRef + ParamArray
AsNew	ByRef + New

Declaration MigStatus attribute

The various declaration statements all have On/Off flag attributes like External or CanBeNull that set the status of one of the context, status, or process flags described above. These are used to highlight the particular flags that are most often used with the type of component being declared. There is also a generic MigStatus attribute that can be used to set any flag or to specify a migration authoring fragment or to trigger a gmNI code event.

The attribute value is first checked to see if it consists of a sequence of MigStatusFlag entry names. These must be entered with no embedded blanks with each entry name except the first preceded by a plus or minus indicating that the flag should be turned on (+) or off (-). If there is no sign preceding the first entry, then it is assumed to be a plus.

If not a set of status flags, the attribute value is checked to see if it consists of a sequence of MigProcessFlag entry names. These must be entered with no embedded blanks with each entry name except the first preceded by a plus or minus indicating that the flag should be turned on (+) or off (-). If there is no sign preceding the first entry, then it is assumed to be a plus.

If neither a status nor a process flag, then that attribute value is assumed to be a user code string. The status flag UserCode is set and the string is stored as part of the component's description for later access by the analyser and the author. The analyser triggers a gmNI code event first during the initialization phase and second during the code review phase when it encounters a reference in the code to a component that has the UserCode status flag set. The triggered code event compares the first token of the user code string against the event identifiers of the currently active migration handlers. If a matching handler is found and if that handle has CodeEvent handler registered, then this service executes that handler.

The author looks for authoring fragments: Add1, Add2, and Type. It uses the first two when it is authoring the "AddRange" specification for a control. By default this is as follows for say a control called "ToolBar1"

    this.Toolbar1.Controls.AddRange(new System.Windows.Forms.Control[] {
             this.Toolbar1_Button1,

but the component that owns the "AddRange" method might not be "Controls" and the "AddRange" method argument might not be of the control class. The generic form of the above then becomes

    this.Toolbar1.%Add1%.AddRange(new %Add2%[] {
            this.Toolbar1_Button1,

and the specification status="Add1:Items,Add2:System.Windows.Forms.ToolStripItem" will make the above,

   this.Toolbar1.Items.AddRange(new System.Windows.Forms.ToolStripItem[] {
   this.Toolbar1_Button1,

It uses the Type when it is authoring the type declaration of an event argument without actually changing the type of the argument.

Table of Contents

gmStudio Documentation

gmplDeclarationStatements