gmplMigrateStatement
Mark Juras
Owned by Mark Juras
Migrate Statement Summary
Migrate is a terminal, refactoring statement that occurs within hostid oriented Refactor statements. It specifies the migration of a specific symbol introduced via an external library description file. The Migrate command is by far the most complex command within a refactoring specification. Though the use of separate migration files, as opposed to simply changing the description file being migrated, complicates the notation, it is being retained not only for use with external libraries, but also for use within translation scripts and to migrate user code.| Attribute | Description |
|---|---|
| Id | This attribute specifies which component in the library or projectfile being refactored is the receive the specified changes. If the attribute is omitted that the library or projectfile specification itself is to be changed. |
| MigComment | This deprecated string attribute associates a comment with the component. This comment does not trigger the gmNI event handlers and can interfere with the MigUserCode attribute. |
| Overrideuser | This is an On/Off flag attribute. The On setting sets the Overrideuser status flag On. For components that are used to satisfy implementation requirements, this flag forces the component to have the attributes as specified in the interface as opposed to as specified in the user code. |
| Overridecall | This attribute applies only to classes and coclasses and the only setting recognized is on. It is used with those classes whose migrated reference class is being split; thus, the analyser should not insert type casts when it sees what appear to be type violations associated with this class. |
| Canbenull | This is an On/Off flag attribute. The On setting sets the CanbeNull status flag On. This means that checks of the component's value for being empty can be Null as well. References to them in the intermediate code have to be checked if they are Null or Empty. |
| MigPattern | This string attribute associates a surface pattern string with code references to the component. See the Patterns page for details on the content of pattern strings. It is equivalent to the All pattern. |
| CshPattern | This string attribute associates a surface pattern string with code references to the component. See the Patterns page for details on the content of pattern strings. It is equivalent to the Csh pattern. |
| VbnPattern | This string attribute associates a surface pattern string with code references to the component. See the Patterns page for details on the content of pattern strings. It is equivalent to the Vbn pattern. |
| Npram | This integer attribute specifies the number of parameters associated with the surface pattern strings. |
| Role | This attribute contains an optional keyword describing the overall role of the operation being authored via the surface pattern strings: Unknown, Property, Method, Define, Utility, Command, Constant, Function, Event, Control, Collection, Resource, Index, or Migclass. The default is None. |
| Patstatus | An optional keyword describing the overall status of the operation authored via the surface pattern strings: Ok, Delete, Deprecated, NotImplemented, MustCorrect, NotIdent, Postfix, or NeedsPren. The default is Ok. |
| Reftype | Within a class there are three non-constant component types -- property, method, and accessor. The manner in which these components are referenced in the source code depends upon what type of component they are. This attribute changes this reference type to one of the above three. Obviously, great care must be taken in the use of this attribute. Note that when properties are being converted to methods this attribute also sets the CallPattern migration status flag. Simply stated the CallPattern flag, if set, indicates that the pattern specifies how the symbol is used as opposed to identified. |
| Status | This attribute applies only to library class components like field, property, method, and accessor. It is used to set its status flags and must contain one of the entries from the PropertyStatus enumeration. This attribute completely replaces any other status flags set for the indicated component. |
| Type | This attribute only has meaning if the identified migration component is a property, method, accessor, argument, or coclass. For coclasses the type specification literally changes them into TypeDefs. For the other components it changes their binary type information. |
| MigName | This attribute changes the migration name of the component. It may be used with any component. The migration name is the name the author uses when it displays the identifier of this component. It does not effect the identifier of the component in so far as references to that component are concerned. In addition, to setting the name, this attribute also turns off the External and ActiveX migration status flags. |
| Static | This is a On/Off flag attribute. The On setting sets the External status flag On. This means that the class is external to the library in the target implementation to which it was assigned in the source implementation. Therefore, when authoring the identifier of the component do not precede it with its source parent membership information. |
| Appobject | This identifier attribute sets the AppObject status flag on and stores the identifier in the description table of the component. It means that the component is an application wide singleton object which requires that special AppObject code be authored for it. |
| Libtype | This attribute changes the changes library type. It may only be used with Library components. This is an entry from the LibraryType enumeration. |
| MigStatus | This attribute has meaning for all components. Its purpose is to turn on one of the component status flags as listed on the Declaration page. |
| Location | This attribute only has meaning if the identified migration component is a library. In this case the location string for that library is replaced by the supplied attribute value. The most commonly used replacement value is DoNotDeclare which tells the project file author not to include a reference to this library. |
| MigUsercode | This attribute is used to trigger a Code event in a migration dll. The first token of the attribute string must match the event attribute value specified for a migration dll. Any additional tokens are optional and are processed by the event handler itself. |
| Creatable | This is an On/Off flag attribute. The Off setting sets the Noncreatable status flag On. It means that the component class objects cannot be created. When declaring objects of this class simply NULL them as opposed to using new to create an instance. |
| Casttype | This attribute applies only to classes and coclasses and the only setting recognized is off. It is used with those classes whose migrated reference class is being split; thus, the analyser should not insert type casts when it sees what appear to be type violations associated with this class. |
| NetHandler | This attribute is the name of the event handler to be used in the authored code. |
| NetArgs | This attribute is the name of the class to be associated with the arguments of the event handler to be used in the authored code. |
| BoxTypes | This attribute only applies to library components. It specifies a comma delimited list of possible types that this component may contain. |
| Optional | This attribute specifies that the component is an optional argument and specifies the value to be used if the argument is omitted. The Argument page contains a description of the valid entries here. |
| ZeroBased | This is an On/Off flag attribute. The On setting sets the ZeroBased process flag On. It is used by the analyser to decrement subscripted references to components with this flag set. |
| IsDbNull | This is an On/Off flag attribute. The On setting sets the IsDbNull status flag On. The component is a class whose instances should be checked against DbNull as opposed to Null. |
| Propertybag | This is an On/Off flag attribute. The On setting sets the Propertybag process flag On. This attribute tells the property bag processor of to look for BeginProperty and NameValue pairs for this component. |
| Axlocation | This string attribute applies to external libraries only. It is used for IDL authored ActiveX libraries that are to be used as COM components. It declares the pathname of the AxInterop library. |
| Removeresumenext | This is an On/Off flag attribute. The On setting sets the Removeresumenext process flag On. This attribute tells the analyser to turn off the "On Error Resume Next" to try-catch conversions for a particular subprogram. The algorithms used here are fairly robust, but can never be perfect. Specific codes may well encounter problems that are best dealt with by simply turning the algorithms off. |
| Removeonerrorgoto | This is an On/Off flag attribute. The On setting sets the Removeonerrorgoto process flag On. This attribute tells the analyser to turn off the "On Error Goto" to try-catch conversions for a particular subprogram. The algorithms used here are fairly robust, but specific codes may well encounter problems that are best dealt with by simply turning the algorithms off. |
| HasWeakSetter | This is an On/Off flag attribute for library components that have setters. If the attribute is On then the setter is treated as having type Variant or object regardless of any type associated with the component. It also blocks any type inferences for the component that might be derived from a strongly typed set to it. |
| uuid | This string attribute applies to external libraries only. It changes the uuid value associated with the library. |
UseEventClass | This is an On/Off flag attribute for events. If the attribute is On then the an Event argument class will be generated for the event. |
| OptionalArguments | This is an On/Off flag attribute for methods. If the attribute is Off then the OptionalArguments migration will be suppressed for the method. |
| MoveToTop | This is an on/off flag attribute for local variables. If the attribute is on, the variable specified by the id attribute is moved to the top of the containing method. This may be needed for variables that end up declared within one scope and used within another due to complex code restructuring such as for Select-Case to if-else, GoSub to functions, etc.  This may be needed in some cases to correct CS0165: Use of unassigned local variable errors. |
The script errors associated with the Migrate statement are as follows:
| Error | Description |
| 1097 | Migrate identifier [%1d] is not defined. |
Table of Contents