Page tree
Skip to end of metadata
Go to start of metadata

 

Select Statement Summary

Select is a terminal, command statement that occurs in both command scripts and reference scripts. It is the most used statement in gmPL. It specifies a large number of attributes which control the behavior of the translation process at every phase. They are organized by type and role.

 

The Select statement attributes also form a Select static class of properties within the gmSL. Each property value can be gotten via its identifier but can not be set, as the Select statement is used to do the sets. The fully qualified name of these properties is gmSL.Select.%attribute%. The gmSL namespace name may be omitted as may the Select class name, if the name is unique through-out the gmSL namespace. Omitting the class name is not recommended and may well be deprecated. The discussion of gmSL gives details about the gmSL.Select class.

Select Identifier Attributes

The Identifier attributes are relatively short names used to identify various parts of the system. When referenced within the gmSL these names are all string properties.

The Name,ToolName Identifier Attribute

The 63-character Name attribute contains the name used to refer to the gmBasic tool. This name appears in the banner and may be used and/or changed as the user desires. It can also be referred to using the attribute name ToolName.

The Version Identifier Attribute

The 31-character Version attribute contains the build version number of the gmBasic tool. It can be used in banners and/or translation headers to document the version used to produce some translation. It may be changed by the user, but this is not recommended.

The Company Identifier Attribute

The 63-character Company attribute can contain any company/application specific string that identifies the Company/copyright in effect. It is initialized as the release identifier for the tool itself which is the string System Build(%date% %time%).

The Id Identifier Attribute

The 31-character Id attribute is the translation scenario identifier. This identifier is always set to identify the particular set of translation conventions being used. It typically has short values like std or bld and is usually added to the names of all bundle and virtual files created.

 

The tool has associated with it an Xml startup script. This script must have the same name as the executable file, except for the xml extension, and must reside in the same directory as the executable for the tool. The purpose of these startup files is to control how the tool presents itself and to specify the exact locations of the files that determine the behavior of the tool. These files do not in themselves control what the tools do, only where the tools should look for detailed information. Since it is often desirable to have multiple configurations available each Startup file consists of a series of subsystems, which have an id and then an independent set of specifications. Different subsystems are activated by following the tool name with a slash and then the subsystem id. If no subsystem id is used then the first subsystem is activated -- usually called std. Though it can be changed, this property contains the subsystem startup identifier that is used. Once set it should not be changed.

 

The tool itself uses this property to distinguish versions of components like type-inference files and deployment locations.

The RootSpace Identifier Attribute

The 63-character RootSpace attribute specifies a string to use as the root of all namespaces -- i.e., it simply precedes all namespace declarations. Its default value is the empty string. If its value is set and then needs to be reset to the empty string, the notation rootspace="off" should be used.

The AppNameSpace Identifier Attribute

The 63-charater AppNameSpace attribute specifies an alternative name for use in translations or reports. It is not presently used explicitly by the tool or in any of the standard text codes. If its value is set and then to be reset to the empty string, the notation AppNameSpace="off" should be used.

The DevEnv Identifier Attribute

The 63-character DevEnv attribute contains the name of the development environment to be used to build the translated code. Its current vales are as follows:

 

Value Description of use
VS2005To request Visual Studio 2005
VS2008To request Visual Studio 2008
VS2010To request Visual Studio 2010


The actual use of this property is restricted to the authoring facilities of the tool so that its values and conventions can be easily controlled by tool users.

Select Value Attributes

The value attributes supply values to control the translation process or to supply sizes to various components. When referenced within the gmSL these values are all integer properties.

The Codesize Value Attribute

The integer Codesize attribute specifies the maximum size of the packed code storage area which receives the code emissions produced by the compiler. Its default setting is 200000 bytes. As the compiler adds code of some size to the back of this storage area it checks to make certain that there is sufficient room. If there is not it logs the message

 

EMROOM: pcnt = (%= bytesused %) lPackedCode = (%= CodeSize %) size = (%= size %)

and ends execution. This is not a recoverable condition. The resolution is to add a command to the translation script to increase the CodeSize and then to rerun the script.

The Progress Value Attribute

The integer Progress attribute controls progress reporting while the tool is operating. Each level includes all messages from lower levels as well as those it introduces itself. Its values are as follows:

 

Value Description of use
0Do not write progress messages
1Do write progress messages
2Describe text block replacements made while doing Fixes.
3Include elapsed time messages for the various subsystems in the tool

 

In particular the following types of messages are written:

 

StateofTool Message issued
Asp CompileCompiling asp file: filename
Fix EditingDetailed messages describing what is being done
ReferencesLoading reference: location
Vb6 CompileReprocessing file: filename
ResourcesLoading resource: from resource file
Vb6 LoadProcessing file: filename



The Indent Value Attribute

The integer Indent attribute specifies the indentation width in the authored output. It should be set to a reasonably small positive value or zero. The default value is 3. When authoring gmBasic does not attempt to reproduce the leading white space in the source code; rather it keeps track of the margin nesting level via the p and q escape characters in the surface patterns or via the Author.IncreaseMargin() and Author.DecreaseMargin() method calls in gmSL scripts and then uses this margin level times the indentation width to determine the amount of leading blanks to add. Note that if this property is zero then gmBasic uses the margin level number of tab-characters to lead the line.

The BlockMethods Value Attribute

The integer BlockMethods attribute specifies that subprogram codes should be blocked for readability. This value has two effects -- first, it adds blank lines between method declarations and second it shows blank lines within methods as empty comments to make them stand out. The default value is 0. The values are as follows:

 

Value Description of use
0Do not do any additional formatting to block methods.
+nBlock methods by adding n blank lines before the comments that introduce the method and change any blank lines within the method to empty comments.



The MaxOutputWidth Value Attribute

The integer MaxOutputWidth attribute specifies the maximum length of lines authored in codes. By default it is set to 256. Note that setting this value too high could cause problems for the editor. An absolute maximum value of 2048 is suggested. For ASP translations, it is suggested that this property be set to at least 1000 if a lot of complex markup is involved. gmBasic is careful to break long statements at the appropriate token boundaries so as not to cause any syntax errors in the target codes.

Select Enumerated Attributes

The enumerated attributes take attribute specific enumeration entry values to control the translation process. When referenced within the gmSL each attribute value can be referenced as enumeration.entry.

The Echo Enumerated Attribute

The enumerated Echo attribute requests that source code be echoed as it is processed. It is defined via the EchoType enumeration whose entries are as follows:

 

Entry Description
offNo not echo the source code during compilation
pass1Echo the source code during the first pass of the compiler
pass2Echo the source code during the second pass of the compiler
allEcho the source code during both passes of the compiler


To have any effect this attribute value must be set prior to the compile statements that are to echo their input. The default setting is off. Note that individual compile statements can locally override this attribute if they require special treatment.

The Dialect Enumerated Attribute

The enumerated Dialect attribute specifies the target dialect to be used. It is defined via the DialectType enumeration whose entries are as follows:

 

Entry Description
vbpSpecifies that target is a project or assembly file.
vb7Specifies that the target language should be Version 7 Basic. This is the combined VB6, ASP, VbScript source language processed by gmBasic.
cshSpecifies that the target language should be C#.
vbnSpecifies that the target language should be VB.NET.
usrSpecifies that the target language should reflect a user specified dialect as described in the language description.
gmsSpecifies that the target language should be gmSL.
javSpecifies that the target language should be Java.


The default setting is csh. The only target languages supported in the standard release of gmBasic are csh and vbn. Applications of gmBasic have targeted all of the above languages. The capabilities of the surface-pattern author as well as the other MetaLanguage specifications combined with the gmSL and the gmNI make supporting other target languages possible. It is important that the target dialect in a translation script be specified before the first compile statement. The target dialect effects all phases of the translation process including the compilation phase.

The TypeInteger Enumerated Attribute

The enumerated TypeInteger attribute specifies whether BASIC integers should be treated as 2-byte integers or 4-byte integers. It is defined via the FixedType enumeration whose entries are as follows:

 

Entry Description
ShortTreat BASIC integers as 2-byte integers in the target languages.
IntegerTreat BASIC integers as 4-byte integers in the target languages.
LongTreat BASIC integers as 4-byte integers in the target languages.


The default setting is Integer. To date all applications of gmBasic have used this default setting and it should probably not be set to short unless the BASIC code is performing operations that require BASIC short arithmetic. If this the case, migration logic will probably be needed anyway.

The TypeLong Enumerated Attribute

The enumerated TypeLong attribute specifies whether BASIC longs should be treated as 4-byte integers or 8-byte integers. It is defined via the FixedType enumeration whose entries are as follows:

 

Entry Description
ShortTreat BASIC longs as 4-byte integers in the target languages.
IntegerTreat BASIC longs as 4-byte integers in the target languages.
LongTreat BASIC longs as 8-byte integers in the target languages.


The default setting is Integer. To date all applications of gmBasic have used this default settings and it should probably not be set to long unless the BASIC code is performing operations that require that longs be larger than integers. If this the case, migration logic will probably be needed anyway.

The ExceptionHandling Enumerated Attribute

The enumerated ExceptionHandling attribute specifies how the analyzer should deal with exception handling. It is defined via the ExceptionType enumeration whose entries are as follows:

 

Entry Description
SimpleIndicates that logic to set the VBNET.Error object will not be authored.
setErrorObjectIndicates that logic should be authored in try/catch blocks so that the VBNET.Err object will be set to reflect the error number.
useTryCatchIndicates that the tool should use Try-Catch as opposed to On Error GoTo style error handling for VBN translations. In essence, this switch tells the analyzer to use the same analyzer method that is presently used for CSH for VBN as well.


When the setErrorObject exception type is active the first statement of each catch block has a call to MigrationSupport.Utils.SetErrorObject included. Thus, for example, a simple block becomes

 

  catch(Exception exc)
  {
      MigrationSupport.Utils.SetErrorObject(exc);
  }

 

The CheckDeclares Enumerated Attribute

The enumerated CheckDeclares attribute controls the checking and reporting of the consistency between DECLARE statements in the source codes and those in a interface description files. It is defined via the CheckType enumeration whose entries are as follows:

 

Entry Description
OffDoes not use external descriptions to check declares.
OnChecks the declares and warns about inconsistencies.
IgnoreChecks the declares but ignores differences between source and external descriptions
AuditReports on all Declares found in the source codes.


In particular this attribute is used by the pass1 compiler when it processes a DECLARE statement. Its first step is to attempt to find an interface description file for the library file that contains the method being declared. The standard search order -- target, local, system, language file -- is used. At the present time partial descriptions for the following libraries are available:

 

LibraryFileName Interface Description file
advapi32.dcladvapi32.dcl.xml
comdlg32.dclcomdlg32.dcl.xml
gdi32.dclgdi32.dcl.xml
IpHlpAPI.dclIpHlpAPI.dcl.xml
kernel32.dclkernel32.dcl.xml
mpr.dclmpr.dcl.xml
ole32.dclole32.dcl.xml
olepro32.dclolepro32.dcl.xml
shell32.dclshell32.dcl.xml
user32.dcluser32.dcl.xml
vb6control.dclvb6control.dcl.xml
version.dclversion.dcl.xml


If there is no IDF or if the attribute is set to off, then gmBasic does no more checking and issues no messages. If the method is found and the attribute is set to audit then the following message is logged

 

NOTE: DECLARE (%= Ident %) with Alias (%= Alias %) in Library (%= library %) is being defined.

If the method is not found and the attribute is set to on then the following message is logged

 

WARNING#004: DECLARE <%= Ident %) with Alias (%= Alias %) in Library (%= Library %) is not defined.

Finally, if a method description is found and it the property is not set off, the tool checks the number of parameters, the return type, and the individual argument types and logs messages if it finds any differences.

The MissingRef Enumerated Attribute

The enumerated MissingRef attribute describes the treatment of missing references either to project file references to external libraries or ASP page references to include files. It is defined via the MissingType enumeration whose entries are as follows:

 

Entry Description
OffIssue a warning message about the missing reference and continue processing.
FatalIssue a message about the missing reference end execution.
JustDoItIssue no message and continue processing as though the referenced library description file or include file had been found and loaded.



The AuthorLibrary Enumerated Attribute

The enumerated AuthorLibrary attribute requests that interface description files be authored when libraries or control projects are translated. It is defined via the AuthorType enumeration whose entries are as follows:

 

Entry Description
offRequests that no interface description file be authored.
onRequests that an interface description file be authored to the code bundle. It is not sent to the local location until the bundle is deployed.
deployRequests that the IDF be authored directly to the local location when the defining source code is translated.


Any interface description file authored is ultimately sent to the current local location.

The LateBindings Enumerated Attribute

The enumerated LateBindings attribute specifies how late bindings should be treated by the compiler. It is defined via the ProcessingType enumeration whose entries are as follows:

 

Entry Description
IgnoreSimply generate code to call the .NET Interaction.CallByName method which makes a runtime determination of what component to access or execute.
WarnBefore generating the CallByName code send a warning message to the log file.
ErrorBefore generating the CallByName code send an error message to the log file. Depending upon the setting of the SyntaxFatal attribute, this can end execution.


A late binding is a reference to a method or property of an object when the class of that object has not been resolved.

The UndefinedVariables Enumerated Attribute

The enumerated UndefinedVariables attribute specifies how to handle variables that are referenced in the source code but are not declared. It is defined via the ProcessingType enumeration whose entries are as follows:

 

Entry Description
IgnoreSimply add the variable to the symbol table and continue processing. and report nothing for undeclared variables.
WarnAdd the variable to the symbol table and send a warning to the log file.
ErrorBefore adding the variable to the symbol table, send an error message to the log file. Depending upon the setting of the SyntaxFatal attribute, this can end execution.



The UndefinedProperties Enumerated Attribute

The enumerated UndefinedProperties attribute specifies how to handle properties that are referenced in designer code but not declared in the interface description file. It is defined via the ProcessingType enumeration whose entries are as follows:

 

Entry Description
IgnoreReport nothing for undefined properties.
WarnSend a warning to the log file for undefined properties.
ErrorSend an error message to the log file for undefined properties. Depending upon the setting of the SyntaxFatal attribute, this can end execution.



The BuildFile Enumerated Attribute

The enumerated BuildFile attribute specifies the external handling strategy for migration. The migration process proceeds as follows:

  1. The tool associates with each translation local stubs for the external references made by that translation. This then makes checking that the translation is correctly formed possible and gives an inventory of the external components referenced.
  2. Once the above has been performed for every code in a code set, the storage files produced are scanned as a group and a set of global library stub files are created that encompass the entire set of references made.
  3. The library stubs are build so they can be referenced. It is these stubs that get filled in and maintained by the migration team from this point forward.
  4. A new set of translations are then created which do not contain any stubs but that reference the libraries created above.

The discussion of the GlobalStubs utility statement describes the actual creation of the global library stubs. The BuildFile is concerned with controlling the production of the local stubs. It is defined via the BuildFileStatus enumeration whose entries are as follows:

 

Entry Description
OffThis entry specifies that some other migration approach is being used. No stubs, local or global, are being used.
OnThis entry specifies that local stubs are being authored. It is deprecated.
LocalThis entry specifies that local stubs are being authored.
GlobalThis entry specifies that global native stub files have been created and should be used. This will be the typical setting, once a code set migration is running beyond step 1 above.



Select Search String Attributes

The search string attributes are used to specify search locations for reference scripts and runtime Dlls. When referenced within the gmSL these attributes are all string properties. Several of the search string attributes have alternative attributes used in gmStudio template files.

 

The search order is Target, Local, System, and Language.

The Target Search String Attribute

The Target search string attribute specifies the location used to store the migrated versions of reference scripts needed for the target translations. It is also the location for user authored runtime Dlls. It is the first location searched by gmBasic when it is looking for an external reference description file or a runtime dll. This area should only be used for user files.

The UserFolder Search String Attribute

The UserFolder search string attribute is a gmStudio template variable. When used within command scripts it specifies the Target location. This attribute should only be used within template files.

The Local Search String Attribute

The Local search string attribute is the full path of the location used by gmBasic for its authored AuthorLibrary local description files and other intermediate output files. It is the second location searched by gmBasic when it is looking for an external reference description file or a runtime dll. This area should not be used for user files, because it is normally emptied before the start of each migration cycle.

The IdfFromCodeFolder Search String Attribute

The IdfFromCodeFolder search string attribute is a gmStudio template variable. When used within command scripts it specifies the Local search location. This attribute should only be used within template files.

The System Search String Attribute

The System search string attribute is the full path of the location used by gmBasic for its authored reference script, interface description files. These files are translations of IDL files describing COM components stored in the system and referenced by the source code being translated. The discussion of the gmCL has a description of IDL to reference script translation. It is the third location searched by gmBasic when it is looking for an external reference description file or a runtime dll. This area should not be used for user files, because it normally contains interface description files for the codes being translated in their original form. These are needed to facilitate translations during the early phases of the migration before all build order and circular reference problems have been resolved.

The IdfFromIdlFolder Search String Attribute

The IdfFromIdlFolder search string attribute is a gmStudio template variable. When used within command scripts it specifies the System location. This attribute should only be used within template files.

The Language Search String Attribute

The Language search string attribute is the full path of the location used by gmBasic to store the language file needed whenever gmBasic runs. Once the language file has been loaded, this location is changed to specify the storage area used to contain the default versions of reference scripts and runtime Dlls as installed. It is the fourth and final location searched by gmBasic when it is looking for an external reference description file or a runtime dll.

Select Location String Attributes

The location string attributes are used to specify non search locations to be used by gmBasic. When referenced within the gmSL these attributes are all string properties. Several of the location string attributes have alternative attributes used in gmStudio template files.

The VirtualRoot Location String Attribute

The VirtualRoot location string attribute is used with ASP pageslice translations. It contains the full path of the folder that should be used as the virtual root when resolving includes.

The Library Location String Attribute

The Library location string attribute is the full path of a library storage area. In particular, this is the location of the cached Interop libraries. This attribute is used widely via the gmSL when Library declarations are processed. Both the Location and AxLocation attributes of that statement are authored by gmBasic to begin with %library%. The gmSL description has details about this use of select attributes in gmPL statements.

The GenExternFolder Location String Attribute

The GenExternFolder location string attribute is a gmStudio template variable. When used within command scripts, it specifies the Library location. This attribute should only be used within template files.

The Idl Location String Attribute

The Idl location string attribute specifies the location of library Idl files to be imported. When the Idl compiler executes an import statement it first searches the current directory for the file being imported and then searches the directory specified by this attribute. If the imported file cannot be located an error message is logged and execution is ended.

The DeployLocation Location String Attribute

The DeployLocation location string attribute specifies the location to which generated projects are deployed. If omitted a location within the source project location is used. By default before copying a translated project code to a deployment location the previous content of that location is removed completely using the following deployment commands

 

  rmdir (%= DeployLocation %)
  mkdir (%= DeployLocation %)
  mkdir (%= DeployLocation %)\bin

Note that the deployment rmdir command does not require that the location already exists. Deployment commands are documented within the gmCL discussion.

 

When doing multiple project translations each project should be assigned its own unique deployment location.

The NetProjFolder Location String Attribute

The NetProjFolder location string attribute is a gmStudio template variable. When used within command scripts, it specifies the DeployLocation location. This attribute should only be used within template files.

The RuntimeDlls Location String Attribute

The RuntimeDlls location string attribute specifies a list of external Dll names which will be loaded by gmBasic before it begins its first compile. The LoadEnvironment statement discussion describes this operation. The RuntimeDlls select must precede the first Compile or Reference statement in the command script or it must be placed in the environment file itself.

The GlobalSettings Location String Attribute

The GlobalSettings location string attribute specifies the full pathname of a pre compiled GlobalSettings file which will be loaded by gmBasic before it begins its first compile. The LoadEnvironment statement discussion describes this operation. The GlobalSettings select must precede the first Compile or Reference statement in the command script or it must be placed in the environment file itself. The GlobalSetting file is a storage area produced by a command script which can contain almost anything. At this point in time the primary entries are Registry statements, gmSL methods, and loaded references. Simply stated, this file contains all of the globally checked for "things" which alternatively are entered into template files. Its content is described in many places throughout this manual.

Select ComputeConditional String Attribute

The ComputeConditional string attribute controls the conditional compilation approach taken by gmBasic. Its entries are as follows:

 

Entry Description
OffWhen ComputeConditional is Off, gmBasic treats conditional statements as though they were simply another statement in the language. They are compiled and their intermediate code is authored as though equivalent statements existed in the target language. This approach is workable when a few simple conditional statements exist in the code, but is unworkable when complicated conditional logic is being used.
MigrateWhen ComputeConditional is Migrate, gmBasic attempts to do a full migration to the .NET languages. To do this requires assuming that all conditional variables are boolean, where True corresponds to defined and False corresponds to undefined. Variables defined either via a CondComp specification in the project file or a #const specification in the source code, that are not True or False are set to True if they are nonzero and False if they are zero.
OnWhen ComputeConditional is On, gmBasic traps all conditional value settings in project files and #const directives. The compiler, not the editor, then evaluates the actual conditional expressions using the standard expression processor and its internal engine that evaluates gmIL code. Based on this evaluation, source code records that should be included are included and source code records that should not be included are commented out. All code conditional statements themselves are also commented out.


The default entry is Off. When ComputeCondional is specified but not one of the above it is assumed to contain a CondComp style specification like

 

   <Select ComputeConditional="DEBUGMODE=0:WIN32_IE=0x400" />
         or
   <Select ComputeConditional="Win32=1:Win16=0" />

This specification is processed as though it have been entered in the project file and the entry is changed to On.

 

Within Visual Basic Compilation constants can be set within a module using #Const. The examples normally provided for this statement show simple integer values being assigned. More complicated value specifications are also allowed. To date the True and False reserved words have also been encountered as well as Hex constants.

 

On the .NET side Conditional Constants are simply defined or they are undefined. They can carry no values. It is this fact that makes the logic surrounding ComputeConditional a necessity as opposed to a simple optional approach. Various approaches using name_mangling have been tried, but all have fallen far short of dealing with the actual use of these constants in VB6. A typical VB6 program that uses Conditional Compilation at all aggressively will not build unless the ComputeConditional capability is turned on. It is also common to see conditional variables referenced but never assigned values in contradictory ways. It is this fact that makes the simple on setting unworkable in many instances.

Select Author Flag Attributes

The Author Flag attributes are on/off flags that control conventions used within the Author. When referenced within the gmSL they are boolean properties with On being True and Off being False.

The BlockComments Author Flag Attribute

The BlockComments author flag attribute requests that comments be blocked in the authored output -- i.e., be surrounded by blank lines, in the authored output. The values are as follows:

 

Value Description of use
OffDo not surround comments with extra blank lines.
OnBlock comments by surrounding them with an extra blank line.


The default value is Off.

 

Note that the writing of comment blocks and of subprogram declarations are interrelated. In particular if the block of comments is directly followed by a subprogram declaration then the BlockMethods spacing overrides the BlockComments spacing -- i.e., both are not applied.

The DeleteUnused Author Flag Attribute

The DeleteUnused author flag attribute controls the removal of unused constants from the translations. Its values are as follows:

 

Value Description of use
OffDo not remove unused constants from the translations.
OnRemove unused constants from the translations


The default value is Off.

The SingleQuotes Author Flag Attribute

The SingleQuotes author flag attribute specifies that single quotes should be used when nested literal strings result from the migration of ASP codes. Its values are as follows:

 

Value Description of use
onRequests that single quotes are used.
offRequests that other nested literal string techniques are used such as inserting backslashes or double quotes as is appropriate for the target language.


The default value is Off.

The CompilerWarnings Author Flag Attribute

The CompilerWarnings author flag attribute is used to control the authoring of TreatWarningsAsErrors entries in the project file. Its values are as follows:

 

Value Description of use
OffSet TreatWarningsAsErrors to "true"
OnSet TreatWarningsAsErrors to "false".


The default value is On.

The OmitAppObjects Author Flag Attribute

The OmitAppObjects author flag attribute removes the AppObject declarations from the translations without effecting the reference logic to them in the compiler. Its values are as follows:

 

Value Description of use
OffInclude AppObject declarations in the translations.
OnOmit AppObject declarations from the translations.


The default value is Off.

The useUserControls Author Flag Attribute

The useUserControls author flag attribute specifies that all ASP PageSlice includes should be authored as user controls. Its values are as follows:

 

Value Description of use
OffDo not author all PageSlice includes as user controls.
OnDo author all PageSlice includes as user controls.


The default value is Off.

The ShowVerticalLists Author Flag Attribute

The ShowVerticalLists author flag attribute controls how long statements that include array initializations are authored. Its values are as follows:

 

Value Description of use
OffDo not check for array initializations in long statements.
OnWhen authoring a long statement that includes an array initialization, put each element of the array initialization on its own line.


The default value is Off.

 

A "long line" is any line whose length exceeds the value of the attribute MaxOutputWidth. Therefore, it is a line that must be broken anyway. The test for "includes an array initialization" is a text search for string []{. The algorithm is fairly general, but there may always be weird cases where it breaks down.

The Migrate2 Author Flag Attribute

The Migrate2 author flag attribute controls the authoring of the long description comment that is usually associated with all resx files. Note that empty resource files are often created even when no resource data is present; however, gmBasic authors a resx file only if resource data is present. Its values are as follows:

 

Value Description of use
OffAuthor the descriptive comment with all resx files.
OnDo not author the descriptive comment.


The default value is Off.

The ProjectReference Author Flag Attribute

The ProjectReference author flag attribute controls how project files reference external dependencies. Its values are as follows:

 

Value Description of use
OffDependencies are referenced as binary assemblies
OnDependencies are referenced via their source project


The default value is Off.

 

The implementation of the On behavior is complicated by the fact that the originally authored project file and the downstream reference to that project file must have matching GUIDS specified. To understand this attribute and its On implementation, consider a simple project, that authors a library and an interface description file. When the ProjectReference attribute is Off, the project file for the library contains no GUID and the library specification is as follows

 

 <library
    id="ArrayFuncDll.dll"
    name="ArrayFuncDLL"
    migName="ArrayFuncDLL"
    location="c:\gmProj\lab\deploy\ArrayFuncDLL_std_csh\bin\ArrayFuncDLL.dll"
    type="Native"
 >

In addition, when a downstream project references this library, the reference is written as follows

 

 <Reference Include="ArrayFuncDLL">
    <HintPath>c:\gmProj\lab\deploy\ArrayFuncDLL_std_csh\bin\ArrayFuncDLL.dll</HintPath>
 </Reference>

When the ProjectReference property is On the project file for the library contains a GUID

 

<ProjectGuid>{EC869FCD-083F-4FE8-BB16-D4A1F44387C2}</ProjectGuid>

and the library specification in the IDF is as follows

 

 <library
    id="ArrayFuncDll.dll"
    name="ArrayFuncDLL"
    migName="ArrayFuncDLL"
    location="c:\gmProj\lab\deploy\ArrayFuncDLL_std_csh\ArrayFuncDll.csproj"
    uuid="{EC869FCD-083F-4FE8-BB16-D4A1F44387C2}"
    type="Native"
 >

Note that the location attribute is now the pathname of the project file and not the pathname of the binary assembly. Note also that the uuid attribute matches the ProjectGuid for the library.

 

When the downstream project authors its reference to this library, it notes that it has a uuid specified, and therefore it authors a ProjectReference as opposed to a simple Reference

 

  <ProjectReference Include="c:\gmProj\lab\deploy\ArrayFuncDLL_std_csh\ArrayFuncDll.csproj">
    <Project>{EC869FCD-083F-4FE8-BB16-D4A1F44387C2}</Project>
    <Name>ArrayFuncDLL</Name>
 </ProjectReference>

In the referencing code the setting of the ProjectReference attribute is ignored. Some libraries will have GUIDS and their reference will be authored using a ProjectReference; and some libraries will not have a GUID and their reference will be authored using a simple reference. The ProjectReference attribute only directly controls how defining projects are authored.

 

When the ProjectReference property is On, a GUID is needed. The whole point behind the use of ProjectReferences is that this type of reference does a better job of keeping referenced binaries in sync with each other as code changes during ongoing development and debugging. The point of GUIDs is to ensure that a user of a library is using the correct version of that library. The system checks not only that the library names agree but also that the GUIDS agree.

 

Unfortunately, in real world migration projects the constant changing and syncing of GUIDS can make development and testing difficult. A simple change is made in a utility library, which causes a change in its GUID, which then requires that every downstream project be re authored as well. To give a bit more flexibility, setting the ProjectReference attribute On also requires that a "project" GUID be specified as well. That project GUID then can either be fixed or can be set to generate a new unique GUID on each translation of the library. The command script that defines the library has the following two statements added.

 

 <Select ProjectReference="on" />
 <Registry type="guid" source="Project" target="(%= Guid("new") %)" />

The first statement turns the ProjectReference attribute On. The registry statement then assigns a value to the "project" GUID. The Guid method attempts to find the named Guid in the registry. If it cannot find it, it creates a unique Guid. Since "new" does not exist, the above will assign a unique instance GUID to the Project GUID in the registry. If the same GUID is always wanted, the Registry command can simply specify it.

 

 <Registry type="GUID" source="Project" target="{11111111-2222-3333-4444-555555555555}" />

 

The ASPNETCompiler Author Flag Attribute

The ASPNETCompiler author flag attribute controls whether ASPX builds should be performed on ASP pageslice translations. In particular when On this flag sets the parameter AspParse in the language file method gmSL.AuthorText.EndWebProject to "Yes". This setting then executes the following code within that method.

 

 if(AspParse == "Yes")
 {
    #TextStart
    <Target Name="AfterBuild">
       <AspNetCompiler
          VirtualPath="/(%= ProjectName %)"
          PhysicalPath="(%= Project.DeployLocation %)"
          TargetPath="(%= Project.DeployLocation %)_build"
          Force="true"
          Debug="true"
       />
    </Target>
    #TextEnd
 }

The default setting for this attribute is Off. ASPX/ASCX files in the web site are compiled by the ASPNET_COMPILER.EXE tool. Running it is not part of the default build behavior of a web application project; consequently, this attribute is needed when these additional compiles are desired.

The LinearizeFiles Author Flag Attribute

The LinearizeFiles author flag attribute is used to supplement the ASPNETCompiler attribute to remove circular file location references. When using the ASPNETCompiler, parts of a pageslice that are in different directory locations cannot cross-reference each other. When the LinearizeFiles attribute is set On all authored files are stored in the target root location by changing backslashes into underscores. It leaves the source locations alone. The default setting for this attribute is Off. Some care should be taken when setting this attribute On, as there may be unintended consequences here. It has been used with sites that have complex source directory structures with success.

Select Compiler Flag Attributes

The Compiler Flag attributes are on/off flags that control conventions used within the Compiler. When referenced within the gmSL they are boolean properties with On being True and Off being False.

The AcceptByRef Compiler Flag Attribute

The AcceptByRef compiler flag attribute is used to control how explicit ByRef annotations are treated by the compiler when processing ASP code. Its values are as follows:

 

Value Description of use
OnThe compiler is forced to accept explicit ByRef parameters as ByRef regardless of what the uses of that parameter in the code seem to indicate. The property itself is used by the pass1 compiler, whose primary task is to build the symbol table, when it encounters the definition of a Sub or Function.
OffThe ByRef specification is treated in the same manner as a missing specification.


The default value is Off

 

When a VB6 code is being processed, then this property has no effect. The problem and reason that the VB6 and ASP codes are treated differently relate to the type inference process. In the target, object-oriented languages, conversions and type weakening can occur when an argument is passed to a parameter by value. In particular, an argument of type object can be passed to almost any other type. When ByRef is used, however, an almost exact type-match is required. Because of this gmBasic resists making type inference changes for ByRef parameters. Since ASP parameters are always VARIANT and thus of type object in the target, very little type inference can be done. The user is forced to trade off type-inference versus getting the correct ByRef status. That is the role of this attribute.

The CheckUUIDs Compiler Flag Attribute

The CheckUUIDs compiler flag attribute is used when gmBasic first loads an interface description file for a code reference. It purpose is to compare the UUID specified in the source reference request with the UUID specified on the library statement in the description file. Its values are as follows:

 

Value Description of use
OffDo not compare the reference UUID with the library UUID
OnDo compare the UUIDs and issue warning messages if there are problems or differences.


The default value is Off

 

When the attribute is On and there is no UUID specified in the source reference then the following message is logged

 

   WARNING#102: This Project Reference has no UUID specified: (%= reference %)

If there is a source reference but it differs from the library one then the following is logged

 

   WARNING#003: The Project UUID (%= src_uuid %) and Library UUID (%= lib_uuid %) do not agree.

This attribute does not cause any error conditions, it merely issues warnings.

The ShowReferences Compiler Flag Attribute

The ShowReferences compiler flag attribute describes how external references are being satisfied. It is used in multi project translations that have co referential projects. Given the build order within the command script a given reference can either be satisfied by a previous compilation in the same script or via an external library description. Its values are as follows:

 

Value Description of use
OffDo not log messages describing how external references are being satisfied.
OnDo log messages describing how external references are being satisfied.


The default value is Off.

 

When On one of the following two messages is logged for each satisfied external reference.

 

   REFERENCE (%= reference %) satisfied within compilation.
       or
   REFERENCE (%= reference %) satisfied via library.

 

The SortReferences Compiler Flag Attribute

The SortReferences compiler flag attribute controls the saving of a sorted symbol reference list for later analysis. Its value are as follows:

 

Value Description of use
OffDo not save a sorted symbol reference list.
OnDo save a sorted symbol reference list.


The default value is On. It should not be turned Off. The sorted reference list is used extensively by the analyzer to trace argument values through subprogram calls.

The LibrariesOnly Compiler Flag Attribute

The LibrariesOnly compiler flag attribute requests how external references should be satisfied. It is used in multi project translations that have co referential projects. Given the build order within the command script a given reference can either be satisfied by a previous compilation in the same script or via an external library description. Its values are as follows:

 

Value Description of use
OffIn multi-project translations, attempt to satisfy references by first checking previously compiled projects within the current compilation script and then via referenced libraries specified by interface description files.
OnOnly use libraries specified via interface description files to satisfy component references.


Its default value is Off.

The StructExtern Compiler Flag Attribute

The StructExtern compiler flag attribute specifies that primitive integer types in structs should be declared using VB6 conventions. Its values are as follows:

 

Value Description of use
OffRequests Integer becomes int and Long becomes long
OnRequests Integer becomes short and Long becomes int


The default value is Off.

The SyntaxFatal Compiler Flag Attribute

The SyntaxFatal compiler flag attribute specifies how to handle syntax errors in the source code. Its values are as follows:

 

Value Description of use
OffIssue an error and continue processing.
OnIssue an error and stop processing.


The default value is Off. Error causing source code statements are simply entered into the target translations as though they had been commented out in the source.

The IgnoreWin32 Compiler Flag Attribute

The IgnoreWin32 compiler flag attribute specifies that DECLARES ignore the Win32 specification files as processed under the control of the CheckDeclares attribute. Its values are as follows:

 

Value Description of use
OffProcess the WIN32 declaration definition files as controlled by the CheckDeclares property.
OnIgnore the WIN32 declaration definition files and processing. Simply accept the declared interface as specified in the code.


The default value is Off.

The AcceptRedefine Compiler Flag Attribute

The AcceptRedefine compiler flag attribute specifies how the compiler is to handle duplicate definitions of subprograms or variables in source codes. It has an effect when the pass1 compiler is processing a Sub,Function, or Dim statements and it encounters an identifier within the current scope level that has already been defined. The values are as follows:

 

Value Description of use
OffIn this case redefines are not allowed and gmBasi generates a syntax error which says "Unable to store variable vector: 'identifier'" or "Unable to define subroutine 'identifier'". Note that pass1 syntax errors block further processing of the tool. When they occur no translation is attempted.
OnIn this case gmBasic the redefinition replaces the original one as opposed to being skipped.


The default value is On.

The ShowChanges Compiler Flag Attribute

The ShowChanges compiler flag attribute controls whether changes made to ASP VbScript code should be shown. gmBasic uses its VB6 compiler to process the VbScript code in ASP pages. There are instances where the compiler detects content that is not compatible with the VB6 compiler and changes it. The values are as follows:

 

Value Description of use
OffDo not show changes made to VbScript code
OnDo show changes to VbScript code.


The default value is Off. The coding issues corrected are as follows:

  1. Replacing =< with <=
  2. Replacing isolated CR with a colon
  3. Remove Extra End if
  4. Insert : before Else Code
  5. Inserting colon after case Else
  6. Inserting colon after case value

 

The OmitResxData Compiler Flag Attribute

The OmitResxData compiler flag attribute can be used to block the authoring of the resx files, but does not effect any other of the resource processing logic. Its values are as follows:

 

Value Description of use
OffAuthor resx files.
OnDo not author resx files.


The default value is Off.

The SupplyMissingResx Compiler Flag Attribute

The SupplyMissingResx compiler flag attribute specifies what to do with property value a when it is unable to open a referenced resx file.

 

Its values are as follows:

 

Value Description of use
OffIf unable to open a reference resx file simply continue as though no resx file had been specified.
OnProcess the effected properties as though the resx file had been found but the property did not have a value given -- i.e., assign it a default value based on its type.


The default value is Off.

The RuntimeConditional Compiler Flag Attribute

The RuntimeConditional compiler flag attribute specifies a work-around for complex compilation statements like

 

        #if cdCallStackDebug && ((CallStackDebug) ? -1 : 0) == 1
          if (!(myCallStack == null))
          {
             myCallStack.Enter(new object[]{CompID,"Initialize()"});
          }
       #endif

In .NET only simple exists/(does not exist) type conditional statements are allowed. This is a complex migration issue which requires further work but for the short term the goal is simply to build everything to be certain that the translations are all well-formed and reasonably well-typed. The work-around encloses the complex expression in quotes and then calls a MigrationSupport method TestCond. Thus the above becomes

 

          if (MigrationSupport.Utils.TestCond("cdCallStackDebug && ((CallStackDebug) ? -1 : 0) == 1"))
          {
             if (!(myCallStack == null))
             {
                myCallStack.Enter(new object[]{CompID,"Initialize()"});
             }
          }

The advantage of this approach is that all code within conditional blocks is built, not just that code in True blocks. The disadvantage is that this only works for conditional code, not for conditional declarations. Its values are as follows:

 

Value Description of use
OffProcess conditionals in the manner specified by the ComputeConditionals attribute.
OnUse migration support calls to hide the actual conditional expressions while still allowing the compiler to see all of the code within the condition.


The default value is Off.

Select Analyser Flag Attributes

The Analyser Flag attributes are on/off flags that control conventions used within the Analyser. When referenced within the gmSL they are boolean properties with On being True and Off being False.

The NullOrEmpty Analyser Flag Attribute

The NullOrEmpty Analyser flag attribute requests additional NullOrEmpty checks in the code. In particular, it scans the code looking for library components with the CanBeNull migration property set to On. When the source is testing them against an empty string, it tests them for a NULL or empty string. Its values are as follows:

 

Value Description of use
OffDo not do the extra code scan for CanBeNull migrations.
OnDo the extra code scan for CanBeNull migrations.


The default value is Off.

The TypeInference Analyser Flag Attribute

The TypeInference Analyser flag attribute requests that gmBasic author a TypeInference reference script which contains a list of all source code symbols associated with a code base that have had a type inferred for them by either the compiler, the analyser, or the user. The list itself consists of a set of Registry.Fixtype commands that specify the final type of any component whose type has been inferred during the translation process. Its values are as follows:

 

Value Description of use
OffDo not author a TypeInference script, but if there is a TypeInference script present in one of the search locations then it is loaded before the tool begins the first compilation. See the LoadEnvironment statement for details.
OnAfter the analysis of the current compiled source code, write to the current local search location the current set of symbols with inferred types in the form of registry commands.


The default value is Off.

 

Using the TypeInferences attribute usually proceeds as follows. First the a few Registry.FixType statements are added to the translation script. These might look something as follows.

 

<Registry type="FixType" source="[<%=VirtualRoot%>\script\db_config.asp].SQLExecRS" target="ADODB.RecordSet" />
<Registry type="FixType" source="[<%=VirtualRoot%>\script\db_config.asp].GetTables" target="ADODB.RecordSet" />
<Registry type="FixType" source="[<%=VirtualRoot%>\script\db_config.asp].GetViews" target="ADODB.RecordSet" />
<Registry type="FixType" source="[<%=VirtualRoot%>\script\db_config.asp].GetColumns" target="ADODB.RecordSet" />

Using these statements gmBasic is now able to infer the types of many more components that need to be retained and then reapplied so that even more components can have their typing changed. This is the purpose of the TypeInferences attribute. After the first run the TypeInference script will contain registry commands that look exactly like the one above and will in addition contain registry commands for all new components whose types have been inferred. The TypeInference script always contains a cumulative list of all components whose types have changed.

 

When the script is being written gmBasic has stored all Registry.FixType entries that came either from the previous version of the script or from any such commands in the translation script itself. The first step is to scan this list for any symbols whose type has not been inferred during the current session. This can be true either because no additional inference was made or because the symbol is not involved in the present session. All these non-inferred symbols are written to the new script in exactly the same form as they were before. The second step is to scan all symbols in the current translation session and write any whose types have been inferred during the session. To emphasize, The TypeInference reference script is a migration-wide script. It contains the inferences made in all codes involved in the migration.

 

The Refactor.FixType commands do not make entries in the registry, but they do mark the symbols that they apply to as having been TypeInferred; therefore, these symbols will end up being in the script as well.

The CodeCommentOut Analyser Flag Attribute

The CodeCommentOut analyser flag attribute specifies how warnings and error pragmas produced for specific upgrade issues are handled. Its values are as follows:

 

Value Description of use
OffWhen a reference to an unupgradable component occurs in the code add a conditional DEBUG warning to the code.
OnWhen a reference to an unupgradable component occurs in the code simply add a comment naming the component.


The default value is Off.

 

As an example the following code is authored for references to some shape properties that cannot be upgraded when this attribute is Off

 

 #if !DEBUG
    #warning "UPGRADE ISSUE: Shape.FillColor was not upgraded."
 #endif
 // circRx.FillColor = System.Drawing.ColorTranslator.FromOle(Convert.ToInt32(LED_CENTER_OFF));
 #if !DEBUG
    #warning "UPGRADE ISSUE: Shape.BorderColor was not upgraded."
 #endif
 // circRx.BorderColor = System.Drawing.ColorTranslator.FromOle(Convert.ToInt32(LED_BORDER_OFF));

The same code is authored as follows when the attribute is On

 

 // Shape.FillColor
 // circRx.FillColor = System.Drawing.ColorTranslator.FromOle(Convert.ToInt32(LED_CENTER_OFF));
 // Shape.BorderColor
 // circRx.BorderColor = System.Drawing.ColorTranslator.FromOle(Convert.ToInt32(LED_BORDER_OFF));

Note that in both cases gmBasic still provides a reasonable translation for the unupgraded property, but then comments that translation out.

Select Process Flag Attributes

The Process Flag attributes are on/off flags that control conventions used within the entire translation process or at least within more than one phase. When referenced within the gmSL they are boolean properties with On being True and Off being False.

The UseOverload Process Flag Attribute

The UseOverload process flag attribute specifies if operator overloading should be used to migrate declarations and calls to methods with optional arguments. Its values are as follows:

 

Value Description of use
OffIndicates that overloads should not be used.
OnIndicates that overloads should be used.


The default value is Off.

 

This attribute effects not just the authoring of subprograms with optional arguments, but also how they are called in the compiler. The statement that turns this attribute On must preceded the first Compile statement in its command script. It may be set in an Environment file.

The UseZeroBased Process Flag Attribute

The UseZeroBased process flag attribute controls the adjustment of subscripts associated with 1-based dimensions. Its values are as follows:

 

Value Description of use
OffDo not adjust subscripts.
OnSubscripts associated with 1-based dimensions are adjusted to be 0-based.

 

 

The default value is Off.

 

When this attribute is On: 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.

The IssueWarnings Process Flag Attribute

The IssueWarnings process flag attribute controls the reporting of warnings throughout the translation process. Its values are as follows:

 

Value Description of use
OffDo not issue warning messages
OnIssue warning messages


The default value is Off.

The CheckMultiSet Process Flag Attribute

The CheckMultiSet process flag attribute controls the behavior of the type inference process when it encounters inferences to different user types being applied to the same component. Its values are as follows:

 

Value Description of use
OffUse the first user type inference encountered for the component.
OnUse the last user type inference for the component.


The default value is Off.

The RemoveByRef Process Flag Attribute

The RemoveByRef process flag attribute controls the treatment of ByRef parameters. In VB6, ByRef marshaling is the default and is very frequently used by accident, even with arguments that are often passed as literals or arithmetic expressions. C#, on the other hand is very strict and explicit about passing arguments by ref, and it is often necessary, in translations of VB6 to C#, to have to define a temporary variable only for the purpose of passing a literal or an expression ByRef. If the use of ByRef was not intentional, this added complexity is also unnecessary. Therefore, as an optimization, gmBasic inspects the body of the routine and removes ByRef marshalling when it is not needed. This provides for a cleaner translation because temporary argument variables are not created. Typically this optimization is not applied to arguments that were explicitly marked in the code as ByRef. Its values are as follows:

 

Value Description of use
OffDo not apply ByRef optimization to parameters that are explicitly declared ByRef.
OnApply the ByRef optimization to explicit ByRef parameters.


The default value is Off.

The OmitOcxState Process Flag Attribute

The OmitOcxState process flag attribute controls the inclusion of OcxState information with resource files for ActiveX controls. Its values are as follows:

 

Value Description of use
OnExclude OcxState data from resource files.
OffInclude OcxState data in resource files.


The default value is Off

The UseLocalMemory Process Flag Attribute

The UseLocalMemory process flag attribute requests that only local memory be used for the storage areas created by Storage statements. Its values are as follows:

 

Value Description of use
OffStorage statements with Identifier attributes should use file based storage as specified.
OnThe Identifier attributes of Storage statements should be ignored.


The default value is Off.

 

File based storage is necessary if the results of a translation run are to debugged or audited. Almost all command scripts request file based storage via their Storage statement. gmBasic is using highly effective paging and symbol search algorithms to minimize file access times; however, memory based storage areas still have significantly faster access times. Turning the UseLocalMemory attribute On can greatly improve run times once a set of migrations is stable.

 

To use this attribute effectively a startup file should be used to turn the attribute On or Off. See the gmCL discussion for details on startup files.

The UsesInterfaces Process Flag Attribute

The UsesInterfaces process flag attribute controls the check for UsesInterfaces registry entries. UsesInterfaces is a terminal registry type that is stored in the globalsettings storage area. It is used to resolve references between independent projects that do not correspond to the build order. Its values are as follows:

 

Value Description of use
OffDo not check for UsesInterfaces registry entries.
OnDo check for UsesInterfaces registry entries.


The default value is Off.

 

The UsesInterface logic described under Registry statement is complex and difficult to implement. This attribute allows the user to begin and test the specifications needed in the GlobalSettings file without having to continually alter the entries in that file.

The SharedFile Process Flag Attribute

The SharedFile process flag attribute controls the check for SharedFile registry entries. SharedFile is a terminal registry type that is stored in the globalsettings storage area. It is used to identify those files that are used by more than one VB6 project and to identify which project should be the only one that processes it. Its values are as follows:

 

Value Description of use
OffDo not check for SharedFile registry entries.
OnDo check for SharedFile registry entries.


The default value is Off.

 

The SharedFile logic described under Registry statement is complex and difficult to implement. This attribute allows the user to begin and test the specifications needed in the GlobalSettings file without having to continually alter the entries in that file.

The AddDefaultProperties Process Flag Attribute

The AddDefaultProperties process flag attribute controls the decision to add default properties to singleton references to variant arguments. Some VB6 codes make extensive use of default properties. The problem with these occurs when calls are made to Variant arguments. If these are ultimately to be Objects then default properties are not wanted but if they are ultimately to be Values then default properties are wanted. Its values are as follows:

 

Value Description of use
OffMake the conservative choice and do not add default properties unless there is some certainty that they are appropriate.
OnMake a more aggressive assumption about adding default properties. They are added whenever a Variant argument is being passed. Using this approach a few additional FixTypes are needed to avoid places where Objects like RecordSets that have an Object Property, such as Fields, as the default become inferred as the default property type and not the direct type.


The default value is Off

 

 

The MigrationSupportUI Process Flag Attribute

The MigrationSupportUI process flag attribute controls the use of a MigrationSupportUI Form class that extends System.Windows.Forms.Form. VB6 forms can inherit from this class to give control over how and when the Load event is invoked. Its values are as follows:

 

Value Description of use
OffDo not use the new form class.
OnDo use the new form class.


The default value is On.

 

The base class created when this attribute is On will only have a single public member named InvokeLoad() that should be called where Load is called in the VB6. Because of changes that need to happen around how and when the Load event is invoked, there is a need to inherit from a base class that extends System.Windows.Forms.Form. The intent here is to change the manner gmBasic deals with Form Loading in general.

The SuppressNumericEncoding Process Flag Attribute

Japanese source codes contain japanese character (double-byte) comments and in the body of HTML. By default, they are encoding using numeric character-code sequences. Customers in the international market will be working with the generated code in an environment that can render the characters directly and that will be much more maintainable. The SuppressNumericEncoding select flag suppresses the encoding. Its values are as follows:

 

Value Description of use
OffEncode double byte characters
OnDo not encode double byte characters.


Its default setting is off.

The CheckFinalCode Process Flag Attribute

The CheckFinalCode process flag attribute triggers code when the analyser starts and finishes that attempts to repair issues in the compiled code that were caused by the very weak typing of variables. In addition, it attempts to resolve issues that might cause build problems. The logic in this code reproduces and then greatly improves on what could be done with the FixType ObjectOnly commands. There are cases where the logic in this code might interfere with work being done explicitly via user migration code; therefore, it can be turned off. Its values are as follows:

 

Value Description of use
OffDo not do the final checks of code quality
OnDo the final checks on code quality.


Its default setting is on.

The OptionalArguments Process Flag Attribute

Visual C# 2010 introduced optional arguments. The definition of a method, constructor, indexer, or delegate can specify that its parameters are required or that they are optional. Any call must provide arguments for all required parameters, but can omit arguments for optional parameters. Each optional parameter has a default value as part of its definition. If no argument is sent for that parameter, the default value is used. A default value must be a constant expression and it must be ByVal. Optional parameters are defined at the end of the parameter list, after any required parameters. If the caller provides an argument for any one of a succession of optional parameters, it must provide arguments for all preceding optional parameters. Comma-separated gaps in the argument list are not supported.

 

The default translation into C# do not use optional arguments, rather they supply the VB6 default values in the calls. Consder the following VB6 method declaration and calls to it.

 

Public Sub AppendBox(i_Width As Long, i_Color As Long, ByVal i_ColourByReel As Boolean, _
                     Optional i_Status As Integer = 11, Optional i_QuestionStatus As Boolean = False, _
                     Optional i_AsteriskStatus As Boolean = True, Optional i_WinderN As Long = 12, _
                     Optional i_WinderNColor As Long = 13, Optional i_IsWaste As Boolean = False)

Private Sub Form_Load()
   Dim l_Boxes As LineObj
   Set l_Boxes = New LineObj
   l_Boxes.AppendBox 20, 61, False
   l_Boxes.AppendBox 30, 62, True, , , , , , True
   l_Boxes.AppendBox 30, 63, True, i_WinderN:=10
End Sub

The default translation for the code is as follows.

 

public void AppendBox(int i_Width,int i_Color,bool i_ColourByReel,
                      int i_Status,bool i_QuestionStatus,
                      bool i_AsteriskStatus,int i_WinderN,
                      int i_WinderNColor,bool i_IsWaste)

private void Form_Load(object sender, EventArgs e)
{
   LineObj l_Boxes = null;
   l_Boxes = new LineObj();
   l_Boxes.AppendBox(20,61,false,11,false,true,12,13,false);
   l_Boxes.AppendBox(30,62,true,11,false,true,12,13,true);
   l_Boxes.AppendBox(30,63,true,11,false,true,10,13,false);
}

The declaration shows only required parameters and the calls supply the missing values within the argument list. Using the following select

 

<Select OptionalArguments="on" />

generates the following translation

 

 public void AppendBox(int i_Width,int i_Color,bool i_ColourByReel,
                       int i_Status = 11,bool i_QuestionStatus = false,
                       bool i_AsteriskStatus = true,int i_WinderN = 12,
                       int i_WinderNColor = 13,bool i_IsWaste = false)

private void Form_Load(object sender, EventArgs e)
{
   LineObj l_Boxes = null;
   l_Boxes = new LineObj();
   l_Boxes.AppendBox(20,61,false);
   l_Boxes.AppendBox(30,62,true,i_IsWaste: true);
   l_Boxes.AppendBox(30,63,true,i_WinderN: 10);
}

The declaration now shows the values of the optional parameters and the calls list the argument values as specified until a missing argument is encountered. At that point name: value syntax is used to supply the remaining argument values.

The UseDoublePrecision Process Flag Attribute

The UseDoublePrecision process flag attribute indicates that when doing C# translations binary arithmetic operations involving combinations of integers with strings should be changed into operations using Double Precision -- both sides of the operator are converted. When this attribute is On there are two changes in the behavior of the tool. First, in the compiler number constants that contain no decimal point but that have a # suffix are declared as being double precision, while when the attribute is off the suffix is ignored and they are declared as being integer. Second, when the flag is On the combinations of string and integer values are converted into combinations of doubles. There are two exceptions to this. Numeric constants are not explicitly converted since the implicit conversions of C# take care of this. Also the concatenation operator & in VB6 and simply + in C# is not subject to this.

 

Great care should be used in activating this flag. In most cases translations not using it are functionally correct and easier to read. To understand when the flag might be needed the issue relates to situations where numeric strings and literal numbers containing decimal points are used in calculations and other arithmetic operations. It does reflect risky practice on the VB6 side, but it is none the less commonly found in the logic that brings data from the GUI (as strings) into the program variables (as numbers).

 

Consider this sample when translated with UseDoublePrecision being Off. The GUI consists of a few text boxes and a button click handler.

 

Private Sub cmdNeg_Click()
   If txtAmount1 < 0 Then
       txtResult1 = -1 * txtAmount1
   Else
       txtResult1 = txtAmount1
   End If
   If txtAmount1 < 0 Then
       txtResult2 = -1# * txtAmount1
   Else
      txtResult2 = txtAmount1
   End If
   writeLog "amount1 = " & txtAmount1
   writeLog "result1 = " & txtResult1
   writeLog "result2 = " & txtResult1
End Sub

Running this with a couple test values entered into txtAmount1 (-1, and -1.1). The runlog is listed below.

 

amount1 = -1
result1 = 1
result2 = 1
amount1 = -1.1
result1 = 1.1
result2 = 1.1

This is all as expected. Here is the C# translation with this attribute Off

 

private void cmdNeg_Click(object sender, EventArgs e)
{
   if (Convert.ToInt32(txtAmount1.Text) < 0)
   {
       txtResult1.Text = Convert.ToString(-1 * Convert.ToInt32(txtAmount1.Text));
   }
   else
   {
       txtResult1.Text = txtAmount1.Text;
   }
   if (Convert.ToInt32(txtAmount1.Text) < 0)
   {
       txtResult2.Text = Convert.ToString(-1 * Convert.ToInt32(txtAmount1.Text));
   }
   else
   {
       txtResult2.Text = txtAmount1.Text;
   }
   modConvertTemp.writeLog("amount1 = " + txtAmount1.Text);
   modConvertTemp.writeLog("result1 = " + txtResult1.Text);
   modConvertTemp.writeLog("result2 = " + txtResult1.Text);
}

The C# is build-complete, but there are a couple issues. First, the explicit double -1# in the calculation of txtResult2 is lost and second, it assumes that the conversion of string to number should use ToInt32. Unfortunately, that will cause a loss of precision. In fact, running this code with txtAmount1="-1.1" gets runtime exception at this line. C# does not guess how to convert "1.1" to Int32, it throws exception "Input string was not in a correct format." Thus, the use of ToDouble also has to be applied to strings in relational expressions with numbers.

 

The same translation now with the UseDoublePrecision attribute on produces the following.

 

private void cmdNeg_Click(object sender, EventArgs e)
{
   if (Convert.ToDouble(txtAmount1.Text) < 0)
   {
      txtResult1.Text = Convert.ToString(-1 * Convert.ToDouble(txtAmount1.Text));
   }
   else
   {
      txtResult1.Text = txtAmount1.Text;
   }
   if (Convert.ToDouble(txtAmount1.Text) < 0)
   {
      txtResult2.Text = Convert.ToString(-1D * Convert.ToDouble(txtAmount1.Text));
   }
   else
   {
      txtResult2.Text = txtAmount1.Text;
   }
   modConvertTemp.writeLog("amount1 = " + txtAmount1.Text);
   modConvertTemp.writeLog("result1 = " + txtResult1.Text);
   modConvertTemp.writeLog("result2 = " + txtResult1.Text);
}

 

Select Debugging Flag Attributes

The Debugging Flag attributes are on/off flags that allow the advanced user to debug problems occurring in complex migration projects. The outputs produced make extensive use of symbol root offsets which can be resolved using the reports produced by the Search utility statements. The debugging flags not only produce additional messages in the log file they also can be used to produce additional output for the Search statements. When referenced within the gmSL they are boolean properties with On being True and Off being False.

 

Each debugging flag potentially produces a large amount of additional output; therefore, the default setting for them is always Off.

The TraceCalls Debugging Flag Attribute

The TraceCalls debugging flag attribute tells the expression processor within the compiler to issues detailed progress messages. These messages can be used to determine why particular types of code have been generated. The output produced is extensive as the following fragment shows.

 

Vb6Factor(3,9,0)
  Input:(20)  "" then
Leaving Vb6Factor: iReturn = 1 type = 8 reference = 0
  Input: then
Leaving Vb6CallArgument: type = 9
CmpLvalue(0,3,1,-1) pcnt=370
  Input:  g_AccountID= Request.Cookies("Account")
Leaving CmpLvalue: iReturn = 41 retVal = 219910 valueType = 11 pcnt = 375
  Input:= Request.Cookies("Account")
Vb6CallArgument(3,0,0,1,85)
Vb6Factor(3,0,0)
  Input:(2) Request.Cookies("Account")
CmpLvalue(0,3,0,0) pcnt=377
  Input:Request.Cookies("Account")
CmpQuantity(2,0,3,13):Request.Cookies("Account")
Parent Stac: Length = 3
   Parent[1] = AspFile.C:\gmSrc\FmStocks\WebSite\t_head.asp:195967
   Parent[2] = AspFile.C:\gmSrc\FmStocks\WebSite\t_head.asp:195967
   Parent[3] = Subprogram.[C:\gmSrc\FmStocks\WebSite\t_head.asp].VerifyLogin:220081
CmpQuantity#5: Found Identifier <Request> before: .Cookies("Account")
UserType(244635): asp.IRequest
Reference: none
  ....
Vb6GetBoxType(220081,242894,0,10) BoxType=0
  Input:("Account")
<CallByName source="VerifyLogin" host="asp.IRequest.Cookies" boxtype="*None" />
CmpQuantity#5: Found Identifier <Cookies> before: ("Account")
UserType(207962): asp.IReadCookies

Using this information requires detailed knowledge of the expression processor.

The EchoInput Debugging Flag Attribute

The EchoInput debugging flag attribute can be used with ASP code projects to show the actual input code being set to the compiler. To deal with the language-level orientation of ASP the pages are segmented using #META, #VB6, and #HTML transition markers to aid the compiler in determining its current language. The EchoInput debugging flag can be used to display this actual intermediate input. It can be used with either the compiler or the search utility. When used with the compiler the output looks as follows

 

1,1:#META Language=VBScript
4,0:#VB6
5,1:  Option Explicit
4,0:#VB6
5,1:  Response.Buffer = true
6,0:#HTML
7,2:<HTML>
7,2:<HEAD>
9,1:
2,1:#XREM #include file="t_head.asp"
6,0:#HTML
7,2:	<TITLE>Managing your 401(k)</TITLE>
7,2:</HEAD>
7,2:<BODY>
2,1:#XREM #include file="t_begin.asp"
6,0:#HTML
7,2:<p>
7,2:<font size="+1"><b>L</b></font>orem ipsum dolor sit amet
  ...

When used with the search utility the additional output looks as follows.

 

Text Associated with Scanned Code:
RecNo | Rai | nRec | Content
----- | --- | ---- | -------
    1 |   0 |    7 | #line 1
    2 |   0 |   24 | #META Language=VBScript
    3 |   0 |    4 | #VB6
    4 |   0 |    7 | #line 2
    5 |   0 |   18 |   Option Explicit
    6 |   0 |    4 | #VB6
    7 |   0 |    7 | #line 3
    8 |   0 |   24 |   Response.Buffer = true
    9 |   0 |    5 | #HTML
   10 |   0 |    7 | #line 5
   11 |   0 |    6 | <HTML>
   12 |   0 |    7 | #line 6
   13 |   0 |    6 | <HEAD>
   14 |   0 |    7 | #line 7
   15 |   0 |    3 |
   16 |   0 |    7 | #line 7
   17 |   0 |   32 | #XREM #include file="t_head.asp"
   18 |   0 |    5 | #HTML
   19 |   0 |    7 | #line 8
   20 |   0 |   36 |    <TITLE>Managing your 401(k)</TITLE>
   21 |   0 |    7 | #line 9
   22 |   0 |    7 | </HEAD>
   23 |   0 |    8 | #line 10
   24 |   0 |    6 | <BODY>
   25 |   0 |    8 | #line 12
   26 |   0 |   33 | #XREM #include file="t_begin.asp"
   27 |   0 |    5 | #HTML
   28 |   0 |    8 | #line 13
   29 |   0 |    3 | <p>
   30 |   0 |    8 | #line 14
   31 |   0 |  118 | <font size="+1"><b>L</b></font>orem ipsum dolor sit amet
 ....

 

The LitmusTests Debugging Flag Attribute

The LitmusTests debugging flag attribute directs the analyser to perform various detailed tests on the compiled code as it is processed and transformed into its final form. The messages produced can be used to trace particular problems being introduced into the analysed code. A sample output is as follows.

 

AnaLitmus#100: maxAddr = 598333
AnaLitmus#101: maxAddr = 598333
AnaLitmus#1911: <C:\gmSrc\FmStocks\WebSite\401k.asp> subRoot = 194761 maxAddr = 598333 codesize = 647 maxsize = 200000
AnaLitmus#1912: <C:\gmSrc\FmStocks\WebSite\401k.asp> subRoot = 194761 maxAddr = 598333 codesize = 647 maxsize = 200000
AnaLitmus#1913: <C:\gmSrc\FmStocks\WebSite\401k.asp> subRoot = 194761 maxAddr = 598333 codesize = 647 maxsize = 200000
AnaLitmus#1911: <C:\gmSrc\FmStocks\WebSite\t_head.asp> subRoot = 195942 maxAddr = 598497 codesize = 84 maxsize = 200000
AnaLitmus#1912: <C:\gmSrc\FmStocks\WebSite\t_head.asp> subRoot = 195942 maxAddr = 598497 codesize = 84 maxsize = 200000
   ...
AnaLitmus#1911: <[C:\gmSrc\FmStocks\WebSite\_version.asp].pair> subRoot = 577284 maxAddr = 610845 codesize = 43 maxsize = 200000
AnaLitmus#1912: <[C:\gmSrc\FmStocks\WebSite\_version.asp].pair> subRoot = 577284 maxAddr = 610845 codesize = 43 maxsize = 200000
AnaLitmus#1913: <[C:\gmSrc\FmStocks\WebSite\_version.asp].pair> subRoot = 577284 maxAddr = 610845 codesize = 43 maxsize = 200000
AnaLitmus#500: <C:\gmSrc\FmStocks\WebSite\401k.asp> subRoot = 194761 maxAddr = 610857 codesize = 651 maxsize = 200000
AnaLitmus#505: <C:\gmSrc\FmStocks\WebSite\401k.asp> subRoot = 194761 maxAddr = 610857 codesize = 651 maxsize = 200000
AnaLitmus#510: <C:\gmSrc\FmStocks\WebSite\401k.asp> subRoot = 194761 maxAddr = 610857 codesize = 651 maxsize = 200000
AnaLitmus#500: <C:\gmSrc\FmStocks\WebSite\t_head.asp> subRoot = 195942 maxAddr = 610857 codesize = 86 maxsize = 200000
AnaLitmus#505: <C:\gmSrc\FmStocks\WebSite\t_head.asp> subRoot = 195942 maxAddr = 610857 codesize = 86 maxsize = 200000
  ...

 

The TraceChanges Debugging Flag Attribute

The TraceChanges debugging flag attribute writes a log message each time the compiler or analyser changes the type or context flags of a component. The message has the following columns:

 

Column Description of content
subRootThe root offset of the subprogram containing the code upon which the change is based
symRootThe root offset of the component that is being changed
linenoThe approximate line number of the source statement upon which the change is based
valueThe new value being set
fileThe root offset of the source file containing the code upon which the change is based
changeA code indicating the context in which the change was made

 

A sample output is as follows. The values have to be looked up in a search dump file.

 

 subRoot  symRoot   lineno    Value     File   change
  218535   218663      103        3   195967    10033
  269718   269769       54    16542   257890    10030
  270051   270101       45    16542   257775    10030
  292660   292711      134    16542   292447    10030
  306127   319264      574    16542   306127    10030
  317585   317635       45    16542   317380    10030
  331644   331694      241    89098   331386    10029
  355459   355489       62    16542   343345    10030
 ....

 

The EchoTranslation Debugging Flag Attribute

The EchoTranslation debugging flag attribute can be used to log the translation records written by the author. When used with a translation script the records are displayed prior to the application of any author fixes. A sample output here looks as follows.

 

  0 rmdir C:\gmProj\FmStocks\Deploy\FmStock9_vbn
  0 mkdir C:\gmProj\FmStocks\Deploy\FmStock9_vbn
  0 cat >C:\gmProj\FmStocks\Deploy\FmStock9_vbn\FMStocks.vbproj <<'!)(!'
  0 <Project DefaultTargets="Build" xmlns="http://schemas.Microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
  1 <PropertyGroup>
  2 <ProjectType>Local</ProjectType>
  2 <TargetFrameworkVersion>v4.0</TargetFrameworkVersion>
  2 <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
  2 <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
  2 <SchemaVersion>2.0</SchemaVersion>
    ....

When used with the search utility the output shows the final form of the translation as shown here.

 

Text Associated with Authored Code:
RecNo | Rai | nRec | Content
----- | --- | ---- | -------
    1 |   3 |    1 | 
    2 |   0 |   44 | rmdir C:\gmProj\FmStocks\Deploy\FmStock9_vbn
    3 |   0 |   44 | mkdir C:\gmProj\FmStocks\Deploy\FmStock9_vbn
    4 |   0 |   52 | mkdir C:\gmProj\FmStocks\Deploy\FmStock9_vbn\externs
    5 |   0 |   68 | cat >C:\gmProj\FmStocks\Deploy\FmStock9_vbn\FMStocks.vbproj <<'!)(!'
    6 |   0 |  111 | <Project DefaultTargets="Build" xmlns="http://schemas.Microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
    7 |   1 |   15 | <PropertyGroup>
    8 |   2 |   32 | <ProjectType>Local</ProjectType>
    9 |   2 |   53 | <TargetFrameworkVersion>v4.0</TargetFrameworkVersion>
   10 |   2 |   75 | <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
   11 |   2 |   61 | <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
   12 |   2 |   34 | <SchemaVersion>2.0</SchemaVersion>
    ....

 

The EchoRaw Debugging Flag Attribute

The EchoRaw debugging flag attribute is used with the search utility to echo the raw text that was associated with a compilation unit. This is used primarily with asp translations where the raw text is converted into an annotated input before it is compiled. This attribute shows the original form. The additional output here looks as follows.

 

Text Associated with Raw Input Code:
RecNo | Rai | nRec | Content
----- | --- | ---- | -------
    1 |  60 |   24 | <%@ Language=VBScript %>
    2 |  60 |   21 | <% Option Explicit %>
    3 |  60 |   27 | <% Response.Buffer = true%>
    4 |  60 |    0 |
    5 |  60 |    6 | <HTML>
    6 |  60 |    6 | <HEAD>
    7 |   9 |   34 |    <!--#include file="t_head.asp"-->
    8 |   9 |   36 |    <TITLE>Managing your 401(k)</TITLE>
    9 |  60 |    7 | </HEAD>
   10 |  60 |    6 | <BODY>
   11 |  60 |    0 |
   12 |  60 |   34 | <!--#include file="t_begin.asp"-->
   13 |  60 |    3 | <p>
 ....

 

The EchoStubs Debugging Flag Attribute

The EchoStubs debugging flag attribute is used with the search utility to echo the stubs authored for external components. The additional output here looks as follows.

 

Text Associated with Stub Wrappers:
RecNo | Rai | nRec | Content
----- | --- | ---- | -------
    1 |   3 |    1 | 
    2 |   0 |   69 | cat >C:\gmProj\FmStocks\Deploy\FmStock9_vbn\externs\ADODB.vb <<'!)(!'
    3 |   0 |   14 | Imports System
    4 |   0 |   26 | Imports System.Collections
    5 |   0 |    0 |
    6 |   0 |   15 | Namespace ADODB
    7 |   1 |   25 | Public Class Connection15
    8 |   2 |  161 | Public Function Execute(ByVal CommandText As String,Optional ByRef RecordsAffected As Object = Nothing,Optional ByVal Options As Integer = -1) As ADODB.Recordset
    9 |   3 |   17 | Execute = Nothing
   10 |   2 |   12 | End Function
   11 |   2 |  178 | Public Sub Open(Optional ByVal ConnectionString As String = "",Optional ByVal UserID As String = "",Optional ByVal Password As String = "",Optional ByVal Options As Integer = -1)
   12 |   2 |    7 | End Sub
   13 |   1 |    9 | End Class

....

The EchoFixes Debugging Flag Attribute

The EchoFixes debugging flag attribute is used to display fix messages when the progress flag itself is not set. The messages produced are the same as those by the progress="1" select; however, only those fixes that actually make a change are listed.

Table of Contents

  • No labels