gmplSearchStatement

Search Statement Summary

Search is nonterminal, utility statement that occurs only in command scripts. It searches the currently open storage area for symbols and produces reports as requested within the statement.

The Search statement has no attributes.

The substatements within the Search statement are as follows:

Substatement	Description
Symbols	Produces a symbol listing
Details	Produces a detailed symbol audit
Interface	Displays a listing of the interface objects
AuditReferences	Produces a sorted symbol reference list
AuditDefinitions	Produces a sorted symbol definitions list
AuditExternals	Produces a sorted external symbol reference list.

The substatements all have the same attributes:

Attribute	Description
Project	This attribute contains the name of project. It restricts the reports to the symbols within that project.

To show what these reports contain Vb001 is a very simple code with one form. This search script for it

   <gmBasic>
      <Storage Action="Open" Identifier="C:\fkgtest\vb6test\csh\VB001.vbi" />
      <Output filename="vb001.txt" StripTrail="on" />
      <Search >
          <Symbols project="VB0001" />
          <Details project="VB0001" />
          <Interface project="VB0001" />
      </Search>
      <Storage Action="Close" />
  </gmBasic>

only audits the symbols in the project code itself. Much of the material in the audit reports is intended for use in the gmNI when working directly with the intermediate language. They are presented here only in a general sense.

The Symbols Report for VB001

The report produced by the Symbols substatement is

Audit of Symbol tree in C:\fkgtest\vb6test\csh\VB001.vbi storage area:
Lev |  Address |   Parent | Symbol Type      | Full Symbol Identifier
--- |  ------- |   ------ | -----------      | ----------------------
  0 |     3692 |     2523 | FormFile         | VB0001.frm
  1 |    22730 |     3692 | Form             | VB0001.VB0001Form.VB0001Form
  2 |    22817 |    22730 | CommandButton    | VB0001.VB0001Form.VB0001Form.Command1
  1 |    22964 |     3692 | Subprogram       | VB0001.VB0001Form.Command1_Click
  2 |    23019 |    22964 | Variable         | VB0001.VB0001Form.Command1_Click.MyNumber
  0 |    22938 |     2523 | Vb_Name.3692     | VB0001.VB0001Form

The symbol table is hierarchical. The Lev column shows the nesting level relative to the root symbol of the symbol.

The Address column is the root address of the symbol. All symbols are assigned a unique root address in the symbol table. As will be seen later in this topic and as will be discussed fully within the gmNI topics these addresses remain constant over multiple translation runs. Since the same identifier is often used for many different components, finding specific references to components in the audit reports is often difficult. The address on the other hand are unique and are always appended to symbols in the detailed reports to make them easy to find.

The Parent column specifies the root address of the parent of the symbol in the hierarchical tree.

The Symbol Type column specifies the symbol object type. These are described more fully in the gmNI discussion.

The Full Symbol Identifier column is the fully qualifier identifier of the symbol. These identifiers are used to specify particular components in the Refactoring statements. They are relatively easy to construct but simply copying them out of an audit report is often easier.

The Details Report for VB001

The Details report shows the detailed entries in the storage area for each symbol. The actual meaning of these entries is not in the scope of this discussion beyond knowing that they exist and generally the sort of information that they contain. The following shows the start of the information shown for the Command1_Click subprogram.

Detailed Description of Subprogram VB0001.VB0001Form.Command1_Click with root address 22964:
Property                       | Content
--------                       | -------
Migrate Status                 | SkipDecl
Migrate Flags                  | CodeAnalysed
Status Flags                   | Private
VB_Name                        | VB0001Form:22938
Binary Type                    | Void
Dimensions                     | 0
Triggering Control             | 22817:CommandButton:Command1
Triggering Event               | Click
Number of Arguments            | 0
Number Required                | 0
Address of Code                | 24517
Bytes of Code                  | 324

Actual C# Codeblock Associated with Command1_Click:
Offset |  Sl.Start |  Ql.Start | Quantity type | Opcode | Operation support information
------ |  -------- |  -------- | ------------- | ------ | -----------------------------
     0 |           |           |               | NEW    | 29 ChDir ".\"
     3 |           |           |               | LEV    | Nest0
     5 |       1.5 |       1.5 | String        | LSC    | 2:.\
    10 |       1.5 |           |               | ARG    | String
    12 |           |      1.12 | Void          | CMD    | ChDir
    14 |           |           |               | NEW    | 30 Open "VB0001.out" For Output As #2
    17 |           |           |               | LEV    | Nest0
    19 |      1.19 |      1.19 | String        | LSC    | 10:VB0001.out
    24 |      1.19 |           |               | ARG    | String
    26 |      1.19 |           |               | LEV    | Nest0
    28 |      2.28 |      1.28 | Integer       | LIC    | 2
    31 |      2.28 |           |               | ARG    | Integer
    33 |      2.28 |           |               | SPV    | PoundSign
    35 |      3.35 |      1.35 | OpenMode      | OMO    | Output

Codeblocks are the intermediate language forms of source code units. They are structured sequences of intermediate Opcodes — operation identifiers — that are manipulated by gmBasic and ultimately authored in the target language. This particular code is ready to be authored in C#.

The Interface Report for VB001

The Interface report assumes that the symbol table contains components that are controls. The properties of these controls are displayed in the report.

Lev | Count | Status     | Role       | Object Type    | Object Identifier
--- | ----- | ------     | ----       | -----------    | -----------------
  1 |     0 | Ok         | Control    | Form           | VB0001Form
  2 |     0 | Ok         | Control    | CommandButton  | Command1

The symbol table is hierarchical. The Lev column shows the nesting level relative to the root symbol of the symbol.

The Count column shows “0” if the control is not a control array; else it shows the number of members in the control array.

The Status column shows the migration status of the component. By default it is Ok. It might also be Delete, Deprecated, NotImplemented, or MustCorrect.

The Role column shows the role that the component serves. By default it is Control. It might also be Event, Define, Resource, Migclass, Index, Property, Collection, or Utility.

The Object Type column specifies the symbol control type. These are described more fully in the gmNI discussion.

The Object Identifier is the identifier of the component as it was originally defined in the source.

The AuditReferences Report Statement Summary

AuditReferences is a Search substatement. The compiler, after it processes a subprogram, a property method, or an ASP page, scans the intermediate code produced and produces a sorted symbol reference list. For each symbol reference in the intermediate code the following six fields are saved:

Field	Description of content
MAKES_REF	The root offset of the subprogram, method, or page containing the reference to a symbol.
BEING_REFD	The root offset of the symbol being referenced. This is the field upon which the reference list is sorted.
REC_NUMBER	The text record number in the text buffer of the source statement that produced the reference. These text buffers are retained in the storage files produced by translation scripts. If the text buffer was edited via Fix statements then it is the edited version that is saved.
CODE_OFFSET	The relative offset in the intermediate code of the actual symbol reference.
HOST_FILE	The root offset of the information file containing the MAKES_REF code unit. This is the parent class, form, module, or page file.
TERMINAL	If the reference to the symbol was terminal then True (1), else False (0). In a source code context an identifier like namespace.class.symbol has a terminal reference to symbol and nonterminal references to namespace and class. All three are retained.

This list is then used by the analyser to aid in its type inference decisions and in particular to trace argument values through subprogram calls. The AuditReferences report is a listing of the terminal references in this list.

The following command script produced this references report from the first VB6 project in the FMSTOCKS sample code.

<gmBasic>
  <Storage Action="Open" Identifier="C:\gmTools\gmPL\fmstock1.vbi" />
  <Output filename="AuditDefinitions.html" StripTrail="on" syntax="Html" />
  <Search>
     <AuditReferences />
   </Search>
   <Storage Action="Close" />
</gmBasic>

Note the use of Html syntax for the output file. This causes gmBasic to use Html annotations to write the table.

The columns in the report are as follows:

Column	Description of content
Type	If the MAKES_REF component is a control, then the type is GUI else the type is REF.
Member Name	This is the identifier of the BEING_REFD symbol. Normally, this is simply the identifier associated with the symbol when it was initially stored in the symbol table. The special case has to do with properties that can have the Let, Get, and Set methods associated with then. When one of these methods is identified, it must be combined with the identifier of its parent property.
Member Class	This is the class name of the BEING_REFD symbol. For symbols within library description files this is the name of the class or enumeration that contains the component. If the symbol is a variable, subprogram, constant, property, or enumeration, then this is the name associated with the code file that contains it. For higher level symbols within projects, this is the name of the project. For higher symbols in libraries, it is the library name.
Member Library	This is the library name of the BEING_REFD symbol. For symbols within library description files this is the name of the library. For symbols within VB6 projects this is the name of the project. For any other symbols this is simply the identifier of the highest symbol in the tree above it but below the root.
Member Type	This is the object type name of the BEING_REFD symbol. This is either an entry ObjectType enumeration in the language file, or a library reference type name, or a Basic built in class name, or the fully qualified identifier of the control if it is an external control class.
Loc Line	If available, this is the line number in the source file of the reference.
Loc Text	If available, this is the actual source statement that made the reference.
Loc Member	This is the identifier of the MAKES_REF symbol. Normally, this is simply the identifier associated with the symbol when it was initially stored in the symbol table. The special case has to do with properties that can have the Let, Get, and Set methods associated with then. When one of these methods is identified, it must be combined with the identifier of its parent property.
Loc Path	This is the pathname of the HOST_FILE component. For components within library description files the pathname is the hintpath of the library containing the component. For components within VB6 projects, this is the identifier of the file that contains the component. If no pathname can be found then it is simply blank.
Loc Name	This is the class name of the MAKES_REF symbol. For symbols within library description files this is the name of the class or enumeration that contains the component. If the symbol is a variable, subprogram, constant, property, or enumeration, then this is the name associated with the code file that contains it. For higher level symbols within projects, this is the name of the project. For higher symbols in libraries, it is the library name.
Loc Type	This is the file extension of the HOST_FILE component. For components within library description files it is the extension on the hintpath of the library containing the component. For components within VB6 projects, this is the extension the file that contains the component. If no extension can be found then it is simply blank.

The AuditDefinitions Report Statement Summary

AuditDefinitions is a utility statement implemented by the ReferencesAudit runtime Dll. It uses the same sorted symbol reference list as is used by the AuditReferences statement, but in a very different way. Its purpose is to detect how often user code symbols are used and in particular which user symbols are never used. The AuditDefinitions report is driven by a full traversal of the symbol table, though only source code symbols are included in the report. For each symbol, the symbol reference list is used to count its terminal references. This count along with the information about the symbol are then reported.

The attributes of the AuditDefinitions statement are as follows:

Attribute	Description
Storage	This attribute specifies the full pathname of the storage file whose symbol definitions are to be audited.

The following command script produced this definitions report from the first VB6 project in the FMSTOCKS sample code.

   <gmBasic>
      <LoadRuntime dllName="ReferencesAudit.dll" />
      <Output filename="c:\gmBasic\AuditDefinitions.html" syntax="Html" />
      <AuditDefinitions Storage="fmstock1.vbi" />
   </gmBasic>

Note the use of Html syntax for the output file. This causes gmBasic to use Html annotations to write the table.

The columns in the report are as follows:

Column	Description of content
Type	This is DEF:n where n is the nesting level of the symbol in the symbol table.
Member Name	This is the identifier of the symbol. Normally, this is simply the identifier associated with the symbol when it was initially stored in the symbol table. The special case has to do with properties that can have the Let, Get, and Set methods associated with then. When one of these methods is identified, it must be combined with the identifier of its parent property.
Member Class	This is the class name of the symbol. For symbols within library description files this is the name of the class or enumeration that contains the component. If the symbol is a variable, subprogram, constant, property, or enumeration, then this is the name associated with the code file that contains it. For higher level symbols within projects, this is the name of the project. For higher symbols in libraries, it is the library name.
Member Library	This is the library name of the symbol. For symbols within library description files this is the name of the library. For symbols within VB6 projects this is the name of the project. For any other symbols this is simply the identifier of the highest symbol in the tree above it but below the root.
Member Type	This is the object type name of the symbol. This is either an entry ObjectType enumeration in the language file, or a library reference type name, or a Basic built in class name, or the fully qualified identifier of the control if it is an external control class.
Num Refer	This is the number of terminal references to the symbol. It may be zero.
Loc Text	This is a declaration of the symbol. For variables, subprograms, property methods, and constants it is the Context flags associated with the symbol, followed by the symbol type, and the local identifier. For subprograms this is followed by a list of the argument types and calling status. For non quantity symbols it is simply the identifier.
Loc Path	This is the pathname of the symbol. For components within library description files the pathname is the hintpath of the library containing the component. For components within VB6 projects, this is the identifier of the file that contains the component. If no pathname can be found then it is simply blank.
Loc Name	This is the library name of the symbol. For symbols within library description files this is the name of the library. For symbols within VB6 projects this is the name of the project. For any other symbols this is simply the identifier of the highest symbol in the tree above it but below the root.
Loc Type	This is the file extension of the symbol. For components within library description files it is the extension on the hintpath of the library containing the component. For components within VB6 projects, this is the extension the file that contains the component. If no extension can be found then it is simply blank.

The AuditExternals Report Statement Summary

AuditExternals is a utility statement implemented by the ReferencesAudit runtime Dll. It produces the same report format as the AuditReferences report, but only shows components in external libraries. Most importantly, the sorted references list is produced from the analysed code and not the simple compiled code and the range of application is greatly expanded. In addition to subprograms, property methods, and pages, the code in constants, enumeration entry values, and controls. is also searched. The report also includes the specific COM events that have event handlers in a given compilation unit. Finally, the references themselves are expanded to include things like sysRS!PropertyName = “Node Count” as a field reference; default item methods in collection classes when the code simply shows an COL.Item reference; and references to components in the MigrationSupport library that were hiding under operations codes.

The attributes of the AuditExternals statement are as follows:

Attribute	Description
Storage	This attribute specifies the full pathname of the storage file whose external symbol references are to be audited.

The following command script produced this externals report from the first VB6 project in the FMSTOCKS sample code.

   <gmBasic>
      <LoadRuntime dllName="ReferencesAudit.dll" />
      <Output filename="c:\gmBasic\AuditExternals.html" syntax="Html" />
      <AuditExternals Storage="fmstock1.vbi" />
   </gmBasic>

Note the use of Html syntax for the output file. This causes gmBasic to use Html annotations to write the table.

See the description of AuditReferences for a description of the content of the columns.