Overview
ASNA Upgrade Assistant is a companion tool to AVR for .NET that upgrades AVR Classic applications to AVR for .NET. Several factors make this migration challenging: first, COM, the environment on which AVR Classic applications run, is very different from the .NET framework. The support for windows and window controls is an example of this difference. Second, the AVR language was revised and updated to a fully object oriented language to be compliant with the Common Language Specification of the .NET framework, which implies that Classic code cannot simply be cut and pasted and expected to run: it needs to be adapted. ASNA’s Upgrade Assistant performs this migration with up to 95% accuracy.
The Upgrade Assistant takes as input an AVR Classic project and some options, and generates a Visual Studio project together with AVR for .NET source files. In addition to the output VS project and the AVR for .NET source files, it also produces a series of in-code translation messages, called Upgrade Notes, Upgrade Warnings, Upgrade ToDos, and Upgrade Issues depending on severity, for all those items found by the Upgrade Assistant during the translation that require programmer intervention. It is imperative for a programmer using the Upgrade Assistant to be fluent in AVR .NET and familiar with AVR Classic.
What projects can the Upgrade Assistant translate
Given the architectural differences between .NET Windows Forms controls and COM (ActiveX) controls the upgrade assistant should not be used to translate Active X control projects. Similarly, the Upgrade Assistant should not be used to translate DLLs for ASP, as ASP is very different to ASP .NET and the upgraded code simply won’t work in the new environment. In file terms, the Upgrade Assistant will translate .vrf, .vrp, and .vrc program files.
Effectiveness of the translation
The Upgrade Assistant is capable of translating up to 95% of the Classic code. Here we talk about the 5% that requires programmer intervention.
Language
The AVR for .NET language differs from the AVR Classic language in several areas. A non-exhaustive list follows. While many of these differences are correctly resolved by the UA, some may require programmer intervention to ensure the semantics of the program is not compromised.
- Object orientation, no concept of ‘main’ program
- Commands with different keywords (e.g. DclDiskFile)
- Unsupported types or type formats (e.g. *Variant, *Ole) in .NET
- Maximum size for Fixed-decimal numbers is smaller in .NET
- AVR for .NET uses the standard .NET windows controls, AVR Classic uses specialized controls
- AVR Classic allows DS, constants, and print files to be declared locally in subroutines. AVR for .NET doesn’t
- Certain automatic type conversions that are valid in Classic are not allowed in .NET (e.g. assignment of a fixed-decimal field, like *zoned, to a *char field)
Commands
Out of 150 Classic commands in AVR Classic 126 are migrated by the Upgrade Assistant. The remaining 24 are those commands that have no support in AVR for .NET, mainly the 5 dealing with Zone movements (e.g. MHLZO); the 14 DG commands (e.g. DGCpyMbr); the 4 that declare stock properties, event, and methods in COM components (e.g. DclStockProp), which are only used in the non-upgradeable Active X projects; and CREATEOBJECT, used to create instances of objects that are late bound.
Of the 126 supported commands, 122 map one to one to their .NET counterparts as either their keywords are identical or map to commands or expressions with the same meaning (e.g. IFXX). One command, DclFld has in Classic the keyword VARYING which is not supported in .NET. The remaining 3 commands are the file declaration commands. For these the Upgrade Assistant creates the AVR for .NET declaration and in some cases runtime code to support the Classic keywords that do not exist in the .NET command, but which are properties of the file object at runtime. The cases that require programmer intervention are related to the use of a field in DB or DBDESC, which is when the database to be used is contained in a variable at runtime.
*Variant fields
Fields of *variant type are converted as having *object type, which won’t necessarily work in all contexts.
Controls
The Upgrade Assistant maps AVR Classic controls to standard .NET windows forms controls, with the exceptions detailed in the next paragraphs. Most of the Classic control properties, methods, and events map to identical or similar counterparts in the corresponding .NET control . Control collections are not supported in AVR for .NET, but the Upgrade Assistant creates the necessary program structures to simulate them in the migrated code. It is of particular importance to verify that code dealing with Focus, either setting focus or handling the focus events, behaves correctly in the migrated code as Classic has historically had a non-standard firing sequence of focus events.
IO Field Control
The IO Field Control in AVR Classic is used in forms to receive input from the user. This control supports fixed decimal and fixed character type input. In the upgrade process this controls can be mapped to either the IODecimal control or the IOString control, which are specialized versions of the .NET TextBox control that support the AVR fixed decimal and fixed character data types respectively.
Subfile control
The subfile control is not supported as such in AVR for .NET. Instead, AVR for .NET supports a Memory file which represents tables of data in memory that can be bound to any arbitrary grid. The Upgrade Assistant translates subfiles as memory files that are coupled with the .NET framework DataGridView control. While the mapping is not perfect and requires some programmer intervention, it allows the use of any arbitrary third party .NET grid control to display the data. Because the memory file is not tied to any particular grid this architecture opens the door to very specialized customizations of the subfile presentation.
Common Dialog
The Common Dialog control is not translated in the current release of the Upgrade Assistant. The single common dialog Classic control can map to one of several dialog controls in .NET depending on usage.
Third-party controls
In general, the .NET framework supports communication with COM components, and therefore third-party controls in theory can be used in .NET applications. For third-party controls, the Upgrade Assistant generates the required wrappers around the COM libraries supporting them. Controls that will not upgrade and will not work in .NET are those that are control containers, i.e. which contain other controls, for example a tab control. Knowing the popularity of TabPro among the AVR Classic customer base, the Upgrade Assistant is enhanced with the ability to detect TabPro usage finding the child controls in each of the tab pages. With them the UA creates a .NET tab control positioning the translated child controls in their proper pages. While no attempt is made to translate any of the properties, methods, or events of TabPro, this partial translation covers most usages of TabPro in Classic code.
Other controls and program objects
The current version of the Upgrade Assistant doesn’t support:
- Avi, Line, Shape, Wave, nor OSFile control migration
- *Err translation
- Message file support in the *App object translation
- Late binding
Program Structures
Data structures in Classic allow their fields to start and end in arbitrary positions. It may be the case where fields have partial overlapping (e.g. a field shares its end with the beginning of the next field in the DS). This kind of overlapping, called ‘promiscuous’, is not supported in AVR for .NET and the current version of the Upgrade Assistant flags it with an error message.
Program Semantics
The biggest semantic difference between AVR Classic and AVR for .NET lies in the structure of programs. In Classic programs are callable entities with an entry point. In .NET programs are encapsulated in objects that expose state and behavior via fields, properties, and methods (subroutines). To mimic the Classic program runtime behavior in .NET, the Upgrade Assistant inserts additional code that produces in effect the ‘single instance’ behavior of Classic. A Classic program converted to a .NET class will contain a class factory that takes care of having one and only one object of this class alive at any given time. Therefore, if a program returns without setting *INLR its instance is kept around and the next time the program is called the factory will return it. If a program sets *INLR then its instance will be deleted when it returns.
The Upgrade Assistant also supports the Classic concept of ‘Main’ program by making all fields and subroutines in Main *public to the other programs in the application and converting all uses of main global names to access them via the main program object, e.g. globalFld = 3 becomes main.globalFld = 3. In other programs, all their fields and subroutines become *private so they are not accessible by anyone else in the application.