Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

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
LibraryDeclares 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.
ClassDeclares a class within a library.
CoclassDeclares a class that is actually defined as the union of a set of classes.
EnumerationDeclares an enumeration within a class or a library.
MethodDeclares a method within a class.
ArgumentDeclares an argument within a method, event or accessor.
PropertyDeclares a property within a class
GetSetLetDeclares separate Get, Set, Let components within a property
FieldDeclares a property in a class whose origin was a class variable as opposed to a property.
AccessorDeclares a property with both set and get access that has arguments.
EventDeclares a event within a class.
ConstantDeclares a constant within a class or library.
StructureDeclares a structure within a class or library
TypedefDeclares 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
PrivateThe 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.
PublicThe component is declared as being public. This normally means that it may be referenced anywhere in the code.
StaticThe 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.
WithEventsThe 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.
ArgumentThe component is an argument of a subprogram or method or accessor or event.
ByValThe component is an argument which will be called by value.
ByRefThe component is an argument which will be called by reference.
ForeignThe 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.
DeadCodeThe 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.
UseGetThe component requires the use of a "getter" to access its value.
ByOutThe component is an argument whose value will be stored in the calling reference location when its subprogram exits.
OptionalThe component is an argument that may be optionally omitted when its subprogram is called.
NotDeclaredThe component is being used as a variable but was never declared.
FixedTypeThe component has been assigned a type which should not be changed by the analyser.
FriendThe component has the Friend status, which is derived but which often simply means that it was not explicitly declared to be public or private.
OverloadThe component needs to be explicitly given the Overload adornment when declared.
DimensionedThe component when declared was explicitly dimensioned via a size or set of size specifications. This size specification is stored as well.
ChangedIn 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.
NewThe component was declared as being new.
ParamArrayThe argument component is in fact a parameter array -- will contain a variable-length list of objects/values being passed to a subprogram.
InLibraryThe 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.
IsDefaultThe component is the default component for its parent.
CollectionThe component is a collection class or a control vector.
ArrayThe component is declared or is referenced as though it were an array even though it may not have been explicitly dimensioned.
2dArrayThe component is declared or is referenced as though it were a two-dimensional array even though it may not have been explicitly dimensioned.
InferredThe component has an inferred type.
ProtectedThe component requires the protected adornment when it is declared.
InModuleThe component is declared within a module file.
InitialWhen the component is declared it should be initialized with the default initialization value for its type.
ResourcesThe component has a set of resources associated with it that were originally stored in an frx file.
PassedThe 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
NotImplementedThe 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"
DeleteThe component should be deleted from the target. References to it are literally removed from the target code.
CanBeNullThe 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.
UserCodeThere 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.
ExternalThe 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.
NeedsInitIn 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.
HasMigclassThere is a user-defined or library-defined migClass that controls some aspect of the component.
LocalLibraryThe 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.
RemoveReferences 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.
ChangeParentThis flag is deprecated and not currently used, though references to it may still exist in older reference files.
AddArgumentThis flag is used with subprograms. It indicates that an argument should be added to the argument list in the target translation.
CallPatternThe surface form pattern associated with the component should be used when it is referenced, not when it is translated.
OverrideUserFor 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.
SkipDeclSet by the analyser to mark property setters and/or getters that can be skipped.
StaticThe component is static in the target implementation and thus any New creations must be removed.
IsDbNullThe component is a class whose instances should be checked against DbNull as opposed to Null.
MustCorrectThe 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"
NoncreatableThe component class objects cannot be created. When declaring objects of this class simply NULL them as opposed to using new to create an instance.
SingletonRefThe 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.
StubOutAny code associated with the component should be ignored but a stub for the component should still be declared.
OverrideThe subprogram component requires the Override specification when it is declared.
CastTypeThe component does not require type casts when setting its values.
ReferencedThis flag is used by the author to mark those components that are actually referenced and that need to be included when authoring a wrapper.
SingletonUsedThe library component has been used as a singleton, without any class or parent designation. This usage may be incorrect and in need of repair.
AppObjectThe component is an application wide singleton object which requires that special AppObject code be authored for it.
ArrayArrayThe component is two-dimensional but should be authored as a array of arrays -- e.g. [][] -- as opposed to [,].
ModuleThe interface component is a module as opposed to a class, so its members may be referenced as singletons.
ImplementsThe class or interface component is implemented by another class in the current migration group.
ActiveXThe coclass component is a control which can appear on a form; consequently there are special Ax naming conventions that must be used.
UsesCOMThe component should be treated as though it were an ActiveX control.
BoxTypesThis 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
CallBackWhen 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.
ZeroBasedThis is not set internally only via refactoring statements. It is used by the analyser to decrement subscripted references to components with this flag set.
WasActiveXWhen 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.
HasForEachThis flag is attributable to classes and coclasses. It indicates that the component is used in ForEach and must, therefore, implement IEnumerable.
ConstructorThis attribute is a flag attributable to event handlers whose On entry indicates that they are being called directly within the code; therefore, their wrapper event arguments class requires a constructor.
ColObjectThis 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.
HaveEventArgsThis attribute is a flag attributable to event handlers whose On entry indicates that they have arguments.
NeedsLetThis attribute is attributed to library methods to indicate that they are being used to set a property value and thus need a Let.
ImplementsWhen 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.
PropertyBagThis attribute tells the property bag processor of to look for BeginProperty and NameValue pairs for this component.
RemoveResumeNextThis 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.
RemoveOnErrorGoToThis 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.
OverloadsThe 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.
CodeAnalysedIndicates that the code associated with a code unit has already been analysed.
TypeInferredIndicates that the type of a component has been inferred.
InInterfaceIndicates that a component is in an interface
OptionBase1First 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.
FixedSourceThis 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.
ObjectOnlyIndicates that a quantity of type Variant or Object should not be type inferred.
BlockTempsThis attribute is applied to subprograms. It blocks the formation of a TempArg when converting a Select into an If.
ArrayInferIndicates that a quantity has had its array status inferred based on a reference to it in the code.
ExposedOnly 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.
SharedFileNot used
NotByRefSome 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.
HasCodeHandlerWhen 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.
EnforceTypeThis 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.
HasWeakSetterThis 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.
HasPatternsThis 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.
ConditionalRemoveThis 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.
ImplicitByRefThis 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
Bytebyte, Byte
Shortshort, Short
Integerint, Integer
Longlong, Long
Currencydecimal, Decimal
Singlefloat, Single
Doubledouble, Double
Stringstring, String
Booleanbool, Boolean
Variantobject, Object
Objectobject, Object
Userobject, Object

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
IUnknownobject, Object
LongLonglong, Long
Longint, Integer
stdole.IUnknownobject, Object
CollectionVBNET.Collection, Collection
stdole.IDispatchobject, Object
Noneobject, Object
BSTRstring, String
VARIANT_BOOLbool, Boolean
System.UInt32int, Integer
System.Bytebyte, Byte
System.Decimaldecimal, Decimal

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

Vb6Special .NET Equivalent C#, VB.NET
Anyobject, Object
TwipsXint, Integer
TwipsYint, Integer
UnsIntegerunit, Integer
VarArrayObject[], Object()
StringPtrSystem.Text.StringBuilder, String
ValueTypeobject, Object

Fourth are the VB6 classes:

Vb6Class .NET Equivalent C#, VB.NET
ErrObjectVBNET.ErrObject, ErrObject

Fifth are the VB6 enumerations:

Vb6Enumeration .NET Equivalent C#, VB.NET
WindowStyleVBNET.AppWinStyle, AppWinStyle
OpenModeVBNET.OpenMode, OpenMode
vbTristateVBNET.TriStatem TriState
VbCompareMethodVBNET.CompareMethod, CompareMethod
VbFileAttributeVBNET.FileAttribute, FileAttribute
MsgBoxResultVBNET.MsgBoxResult, MsgBoxResult
VbMsgBoxStyleVBNET.MsgBoxStyle, MsgBoxStyle
VariableTypeVBNET.VariantType, VariantType
FirstDayOfWeekVBNET.FirstDayOfWeek, FirstDayOfWeek
FirstDayOfYearVBNET.FirstDayOfYear, FirstDayOfYear
DueDateVBNET.DueDate, DueDate

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
SetByRefByRef + UseGet
UseGetByVal + UseGet
DimenByVal + Dimensioned
RefParamArrayByRef + ParamArray
AsNewByRef + 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"

Code Block
    this.Toolbar1.Controls.AddRange(new System.Windows.Forms.Control[] {
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

Code Block
    this.Toolbar1.%Add1%.AddRange(new %Add2%[] {
and the specification status="Add1:Items,Add2:System.Windows.Forms.ToolStripItem" will make the above,

Code Block
   this.Toolbar1.Items.AddRange(new System.Windows.Forms.ToolStripItem[] {
It uses the Type when it is authoring the type declaration of an event argument without actually changing the type of the argument.
titleTable of Contents

Table of Contents