From Support Wiki
Centura Team Developer Migration Issues with COM and ActiveX
Joe Bunger and Srinath Janakiraman - Gupta Technologies Background Information
CTD 2.x has made improvements in the handling of COM objects. A new class called the COM Proxy Class has facilitated this. There are some issues this creates when migrating your application from the 1.5 to 2.x; there are fewer issues if the original application was using the ActiveX versions of the COM servers. This paper points out issues that you may encounter. Not all topics covered are necessarily applicable to every application.
AUTOMATION.APL Object Class
The Class Object contains the following changes that affect migration:
* Create method: In 2.x the Object.Create has changed to CreateObject. The parameter signature is the same and the effect is the same. Calls to Create with this signature need to be changed to CreateObject. There is also an Object.CreateObjectEx that is new to 2.x; it takes an additional host parameter.
* GetInterface has been removed from the Object class, GetInterface is now a function of the COM Proxy Class that is new to CTD 2.x. The parameter signature has changed as well.
ActiveX Library Generation (1.5)
* Key points, a COM Server's implementation of a Createable "Object" is called a CoClass. CoClasses implement or contain "Interfaces." In SAL Interfaces are represented as a Functional Class derived from the Automation.apl class called "Object." Createable Objects (CoClasses) are represented as either Functional Classes derived from Interface Classes (non-visual) or ActiveX classes derived from Interface Classes (visual.)
* "Createable Objects" expose a method called "Init" which calls the inherited method Create.
ActiveX Library Generation (2.x)
* Key points: a COM Server's implementation of a Createable "Object" is called a CoClass. CoClasses implement or contain "Interfaces." In SAL Interfaces are represented as a Functional Class derived from the Automation.apl class called "Object." Createable Objects (CoClasses) are represented as either COM Proxy Classes derived from Interface Classes (non-visual) or ActiveX classes derived from Interface Classes (visual.)
ActiveX Library Generation (Key Differences)
* In CTD 1.5 the maximum "name" length of anything was 32 Characters. This has been removed in 2.x.
* In CTD 1.5 the function Init is exposed for "Creatable" objects. In 2.x for "Creatable" objects a COM Proxy Class exposes "Create" and "CreateEx."
* In CTD 1.5 the function "Detach" is exposed for releasing a reference. In 2.x COM Proxy Classes expose a method called "Release." Interface Classes expose Detach or can be assigned to OBJ_Null to release their reference.
* There is a subtle difference in the naming convention of Enumerations between 1.5 and 2.0.
* There is a subtle difference in the naming convention of Visual ActiveX Objects between 1.5 and 2.0.
* In the Outline the COM Proxy Class is a different class type than a Functional Class. Likewise an Instance of a COM Proxy is a different outline item type than an instance of a functional class.
* The COM Proxy exposes a GetInterface function with a different signature in 2.x than in 1.5.
Steps for Migration
All CTD 1.5 APLs in the AXLIBS subfolder need to be removed.
Note: you may want to back up your CTD 1.5 AXLIBS APLs before regenerating those APLs in version 2.x. To see whether you need to do this, read the section below named "Enumerations may need to have their names changed."
If you are not getting an error message when you first open your existing application in CTD 2.x, you need to make sure that you already generated the APL in your new environment. Make sure you are not picking up the old library. If the libraries were merged under CTD 1.5 you will need to remove the classes manually.
AXLIBS APLs need to be "regenerated" with the CTD 2.x ActiveX Explorer.
Clarification: Go to Menu item Tools, ActiveX Explorer to generate the APLs for the desired object. The default location for ActiveX libraries is the AXLIBS subfolder of the CTD program folder. If you are attempting to generate a library for an object and are having trouble getting a successful generation you may need to use the Browse option in ActiveX Explorer and find the appropriate .TLB or .OLB file in the install folder of the object for which you are trying to generate the library.
Example: If you are attempting to build the Excel library and it has not been registered in CTD's ActiveX Explorer, click the Browse option, navigate to the MS Office install folder and select EXCEL9.OLB, then generate the library.
Some class definitions need to be changed from Functional Classes to COM Proxy Classes. This applies to all classes that in 1.5 were Functional Classes and were derived from ActiveX Functional Classes, and now the equivalent ActiveX parent class in 2.x is a COM Proxy Class.
Example: I have a Functional Class, CSCWord_Application, that is derived from Word_Application. In CTD 1.5x Word_Application was a functional class. However in CTD 2.x Word_Application is a COM Proxy Class. Therefore I need to declare CSCWord_Application a COM Proxy Class.
Clarification: Word_Application in CTD 1.5 is the generated Functional Class that will in CTD 2.x become a COM Proxy Class. Word_Application is derived from Word__Application which is derived from Object. The class hierarchy remains the same for both CTD versions and reflects the hierarchy of the ActiveX object. The difference being, in CTD 1.5 it will be generated as a Functional Class, in CTD 2.x it will be a COM Proxy Class.
All instances of Functional Classes that should now be instances of COM Proxy Classes need to be removed and reentered. (This causes the correct Outline Item Type to be used.)
Example: I have a form that needs to invoke MS Word. On that form I have a variable declared as CSCWord_Application: oWordApp. Since the original application outline was created using CTD 1.5, the outline has stored the appropriate information for a Functional Class. However, in CTD 2.x, it is no longer a Functional Class. The oWordApp variable is now a COM Proxy Class and it really needs COM Proxy Class information. To force the changes to the outline simply enter the exact same declaration as the original variable and delete the old one. Important note: simply commenting and un-commenting the item will not make the necessary outline changes.
All calls made to the Init function of a COM Proxy object need to be changed to Create.
Example: Call oWordApp.Init() becomes Call oWordApp.Create()
Clarification: When the new outline is generated the class function Init() no longer exists, it has been deprecated. This function used to be generated for the functional classes that now are represented by COM Proxy Classes. COM Proxy Classes have four new functions generated; they are CreateEx(), Create(), GetInterface(), and Release(). The Init() function is replaced by the Create() function in the COM Proxy Class. It has the same parameter list. It is also recommended that the Release() function be called when you are finished with the Object. In your old code this was probably done with a Call oWordApp.Detach(). The CreateEx() call is to create the object on another machine and takes the host name as a parameter (DCOM).
All Calls made to the Detach() function of a COM Proxy object need to be changed to Release().
Clarification: In CTD 1.5 when you were finished with the COM object you called Object.Detach(), in CTD 2.x you need to call the COM Proxy Class.Release( ). The Detach() function is still valid for interface classes and essentially is the same as setting an interface object equal to OBJ_Null.
Example: In CTD 1.5 after doing an oWordApp.Init( ) to create the object after you had completed using the object you would call oWordApp.Detach( ), this needs to be changed to oWordApp.Release( ). If you have called oWordApp.GetInterface( iDocs, Word_Documents ) a call to iDocs.Detach( ) or Set iDocs = OBJ_Null will accomplish the same thing.
Any Object name that is now longer than 32 Characters needs to be accounted for.
Clarification: If an Object was registered in CTD 1.5 with a name over 32 characters long, the name was truncated to 32 characters. Iin CTD 2.x it will not be truncated; it will have the same name that it was registered with.
Enumerations may need to have their names changed.
Clarification: In 1.5, it was possible for multiple ActiveX object libraries to expose multiple enumerations with the same name, but different values. That's because in 1.5, defined constants have the same 32-character issue as object names, with the additional challenge of a prefix being added. In CTD 2.x this problem was fixed. Thus CTD 2.x will produce different names for ActiveX APL constants than the names that were produced under CTD 1.5. This will affect your existing application written under CTD 1.5 if that application used references to the constant names within the application itself (not the APL). If you regenerate the APL using ActiveX Explorer in CTD 2.x, those references will now point to names that don't exist in the new APL. There are two ways to handle this. One way is to open the old APL generated under CTD 1.5, and cut and paste the portion of that APL that covered the constant definitions for enumerations. In essence you would now have the same constant defined twice in your application: once with the new name, from the new APL generated by version 2.x of the ActiveX Explorer, and once with the old (1.5) name from the code that you pasted into your .APP file from the old 1.5 APL. The second way is to correct the references by searching for the portion of the constant name that does not include the prefix. Note, however, that because of the 32-character limitation in CTD 1.5, you may not wish to search on the entire portion. See the example below to understand how the trailing characters of a constant name may be truncated in CTD 1.5. In such a case, you would want to search on only the truncated string.
Example: Enumeration constants are generated with a prefix. In CTD 1.5 this was necessarily short because of the 32-character limit for names. For example, wd was the prefix for Word, mso was the prefix for MS Office etc. On the other hand, CTD 2.x gives the full origin of the enumeration. Word_WdWordDialogTab_wd is the Microsoft prefix for a Word dialog constant. Thus a constant defined in CTD 1.5 as wdDialogToolsAutoCorrectExceptio = 1400000 becomes Word_WdWordDialogTab_wdDialogToolsAutoCorrectExceptionsTabFirstLetter = 1400000 in CTD 2.x.
All ActiveX Window Objects need to have their name changed appropriately.
Clarification: The new naming convention for the visual ActiveX Window Objects has AX_ pre-pended to the class name.
Example: In CTD 1.5 the ActiveX class for a MS Word object is Word_Document. In CTD 2.x that same class is generated as AX_ Word_Document.
ActiveX Differences
When developers start to move their application development environment from CTD 1.5.1 to CTD 2.x they will see a few notable changes in the behavior of applications that use certain ActiveX objects.
Most ActiveX objects have a type library associated with them. The Controls Palette and the ActiveX Explorer in CTD read the type library to determine which methods and events are exposed by the object, and they build a library (.APL) file from this information. But there are some ActiveX objects that either do not have type libraries, or have type libraries that are incomplete for purposes of automation. Examples are the "Image Document" and "Bitmap Image" objects.
With CTD 1.5.1 or earlier, one could drag and drop an ActiveX object onto a form and CTD would generate the required library (.APL) file that contains wrapper functions for all the methods exposed in the object's type library. In the case of missing or incomplete type libraries, CTD 1.5.1 generated a library (.APL) file containing a visual component class of the ActiveX object derived from the dispatch interface object. The ActiveX class was not fully functional and did not contain the "Init" function required to instantiate an object of that class.
Beginning with CTD 2.0 this behavior was altered, preventing CTD from generating the library (.APL) file if the object didn't expose sufficient functionality. Instead CTD throws an error stating, "This object does not support OLE Automation. You may need to re-install the component, or use it within the ActiveX container."
When you encounter any such error during your application development using CTD 2.x, try inserting the object inside an ActiveX container. You can find more details on how to do this in the online book "Developing with SQLWindows", in chapter 19, in the section titled "Using the Controls Palette".
For migration of existing applications (developed using CTD 1.5.1 or earlier versions) that use ActiveX objects without a type library, these will continue to work in CTD 2.x if you still have the generated library (.APL) file created by the earlier version of CTD.