| Navigation: Upgrading from prior Clarion versions >====== Clarion Win32 Migration Tips ====== |    |
This topic is designed as a quick reference for developers and programmers who are migrating applications to Clarion Win32 from versions prior to Clarion 6.
The following changes were documented in the Clarion 6 release notes and should be reviewed by developers migrating applications from versions prior to Clarion 6.
Change of EVALUATE Error Codes
Embedding code when closing a Process procedure
General Rules regarding your data and the new Thread Model
Heap Overflow Error when migrating applications
Migrating Large Dictionaries and Data Paths
Migration of hand coded project files
POINTER(File) and POSITION(File)
Remove MDI attribute from dockable toolbar windows
RTF Text Control and RTF Control Templates
Use of Error Managers during DLL Initialization
Use of ABC Classes with the Clarion template chain
Change of EVALUATE Error Codes
The error codes posted by the EVALUATE statement have been modified in Clarion 6:
1010 - formerly 800: Bad expression syntax
1011 - formerly 801: Unknown identifier in the expression
1012 - formerly 802: Mismatched POPBIND
Default Splash Procedure Icon
Loading a C55 application into Clarion 6 that uses the default splash screen will produce a link error that says 'C55.GIF' not found.
The best workaround is to simply change the icon, or just delete the old splash procedure and add a new one using the Clarion 6 default.
DLL Initialization
Enforcement of threaded variables in multi-DLL applications is critical in Clarion 6 and later versions. In versions pior to Clarion 6 if your file definitions are set to “open in current thread” in the dictionary (the THREAD attribute is set in the FILE definition), your file definitions in your DLLs must match that definition. To ensure this, examine each application's global file control section, and make sure that all of your files are set to 'ALL THREADED' in the Threaded drop list.
Regarding files that are defined across multiple DLLs (e.g., a Customer file defined in a data DLL and again in another DLL), you CANNOT mix thread and non-threaded attributes on the same files in a multi-dll application. Although this programming style was permitted in earlier versions of Clarion, the initialization of preemptive threads will not allow this in Clarion 6.
You can use either setting, thread or non-threaded, as long as it's consistent across all DLLs and your executable. And, of course, mixing the threaded and non-threaded attributes among different files is still permitted.
Embedding code when closing a Process procedure
The Process procedure used with the ABC templates calls ThisProcess.Close() after ThisWindow.Kill has fully completed. Consequently, any object created in the scope of the process window which is called inside ThisProcess.Close() will cause a GPF since the destructor for that object will already have completed during ThisWindow.Kill.
In Clarion 6, the ViewManager class destructor used with the ProcessClass is now calling ThisProcess.Close() to make sure that the VIEW is closed. This was not needed in previous versions of Clarion because local VIEWs were automatically closed when a procedure exited. With the new threading model, local VIEWs are now not automatically closed until the thread is destroyed.
There is a distinct chance that any call to a local object inside ThisWindow.Close() will cause a GPF when exiting the process procedure, because it has already been disposed by the time the final ThisProcess.Close() call happens.
Anyone embedding source code in the ThisWindow.Close() method needs to add some kind of condition surrounding any call to a local object that stops it happening after ThisWindow.Kill() has occurred.
General Rules regarding your data and the new Thread Model
1. Use the THREAD attribute on global Data (file, class, group, queue or simple types).
2. Use the THREAD attribute on module Data (file, class, group, queue or simple types).
3. Avoid the use of static variables.
4. Don't pass the address of anything within a START command - this was a
common trick used by people to communicate between threads.
If you do any of the above you must make them thread safe. Refer to the Multi Threaded Programming PDF for detailed information on this process.
Local data (including classes that are normally instantiated locally) is automatically threaded (unless you put the STATIC attribute on it).
See Also:
Special Considerations for One-Piece (Single) Executables
OLE Controls and the new thread model
Global EIP Classes
Some applications that use edit-in-place in prior versions will migrate to Clarion 6 with the EditClass defined as the default edit-in-place class. In Clarion 6, this class needs to be changed to the EditEntryClass. To do this, access the Global Properties in the Application Generator. In the Classes tab, press the Browser button and change the default edit in place class from EditClass to EditEntryClass.
Global Pools and GROUPs
In Clarion versions prior to 5.5H, if a GROUP were defined in the dictionary's Global Pool without using a prefix, the prefix of the Global Pool (which is required) would be used in its place.
For example:
GLOB:GROUPONE GROUP,PRE() !`GLOB' is the prefix of the Global Pool
GLOB:STRING1 STRING(20)
GLOB:STRING2 STRING(20)
END
With Clarion 6, this same group will be generated without the Global prefix, and would appear as follows:
GLOB:GROUPONE GROUP,PRE() !`GLOB' is the prefix of the Global Pool
STRING1 STRING(20)
STRING2 STRING(20)
END
Since it is possible to define multiple Global Pools in your dictionary, a second Global Pool could be created as follows:
GLO2:GROUPTWO GROUP,PRE() !`GLO2' is the prefix of the 2nd Global Pool
GLO2:STRING1 STRING(20)
GLO2:STRING2 STRING(20)
END
Which in Clarion 6 will be generated as follows:
GLO2:GROUPTWO GROUP,PRE() !`GLO2' is the prefix of the 2nd Global Pool
STRING1 STRING(20)
STRING2 STRING(20)
END
This will cause the compiler to generate “Duplicate Label” warnings when migrating your applications.
The solution to this is to add a prefix to each of your GROUPs that share common label names across Global Pools.
For example:
GLOB:GROUPONE GROUP,PRE(GLOB) !`GLOB' is the prefix of the 1st GROUP
STRING1 STRING(20)
STRING2 STRING(20)
END
GLO2:GROUPTWO GROUP,PRE(GLO2) !`GLO2' is the prefix of the 2nd GROUP
STRING1 STRING(20)
STRING2 STRING(20)
END
Heap Overflow Error when migrating applications
During the early testing phase of Clarion 6, it was noted that some applications would post a “Heap Overflow” error when attempting to load applications of prior Clarion versions into the Clarion 6 IDE.
In nearly all cases, the solution is to first export the application to a text file (TXA), and then import it as text into the Clarion 6 environment.
ISAM File Access Performance
Some users have reported that if there is any experience of slow file accesses when using ISAM files, switching off the Defer opening files until accessed in the application's Global Properties - File Control will improve the performance.
Large WINDOW structures
In each control that is populated in a WINDOW structure in Clarion 6, there is now extra information for each control that takes about 10 extra bytes per control. This may cause some large and complex windows to not import properly from prior versions.
You may need to shorten some use variables or remove controls and create/destroy them at runtime or redesign the window to make it a bit more efficient.
Migrating Large Dictionaries and Data Paths
One of the nice new features of this release is a new system property:
SYSTEM{PROP:DataPath}.
With this, you can set your data file names in the dictionary to have no path in them, and then set the data path once in the program start up. From there, each file will inherit the common data path.
With that in mind, dictionaries created in a prior version will continue to work. The only issue is where file names and structures are stored exclusively in a DLL and referenced from the EXE. In prior versions, you had to define these objects in the EXE as EXTERNAL, and did not care if the files in this object were threaded or not. In this release, any objects that contain threaded data must add the THREAD attribute to the object definition.
Mixing threaded and non-threaded data in an object is dangerous and likely to cause problems.
Migration of hand coded project files
All projects compiled in Clarion 6 are 32-bit. Prior to loading older project files (.PR or .PRJ) into the Clarion 6 environment, load them into your favorite text editor and make sure that the following pragma entry is set properly:
#system win32
You can also load the project into the project editor. When you press OK to close the project, the #system pragma will be automatically updated.
POINTER(File) and POSITION(File)
The behavior of POINTER(File) is different for different file systems. For example, the first record in a TopSpeed file doesn't have a pointer value of 1.
It may still be safe to use for certain file systems, but for code portability, POSITION(File) is the way to go.
Remove MDI attribute from dockable toolbar windows
In Clarion 6, the MDI attribute is no longer permitted on any toolbar window that is dockable (windows with the DOCK and TOOLBOX attributes).
RTF Text Control and RTF Control Templates
To all developers that used the RTF Control template in prior versions of Clarion, this template has been deprecated, and is now replaced by the new RTF Text Control template.
The RTF Control template is still included for users who wish to migrate their applications to Clarion 6, and avoid unnecessary template warnings or errors. Upon migration to Clarion 6, you will notice a message in the Actions tab of the control's properties that notifies you that this template should be replaced. You will also see a warning at source generation time that notifies you that this template has been deprecated.
TXA Comparison Technique
If you are having troubles with applications converted to Clarion 6 using DLLs, there is a possibility that the DLL that was converted contained hidden information (like a third party library) that was not detected by the conversion process.
To confirm this, try the following:
Export the old DLL application to TXA format (Export Text)
Export a new Clarion 6 DLL application to TXA format (Export Text)
Next, compare the TXA's up through the first procedure (i.e., the program/global area). This might give you some ideas regarding information converted from an old application that may not be compatible, or does not exist in Clarion 6.
Use of Error Managers during DLL Initialization
A change has also been made in the DLL initialization of ABC-based applications. During initialization, the DLL uses a LocalErrors Class rather than the Global executable's GlobalErrors Class.
For example, in a multi DLL application and during initialization of the DLL containing Global data, if errors need to be posted to the error manager, they will be posted to the DLL's local error manager (LocalErrors) instead of the application's global error manager. The reason for this is that the DLL's error manager is not set to use the application's error manager until after initialization of the DLL. During initialization, the DLL uses the LocalErrors Manager rather than the executable's GlobalErrors Manager. Inside the DLL Init procedure, extra code is generated to assign GlobalErrors, and also assign the passed error manager to the already initialized file managers and relation managers.
Developers who modified the global error manager in their applications using DLLs will now need to be aware of the new local error managers that are applied.
Use of ABC Classes with Clarion template based applications
This release of Clarion includes many new template features that are now supported in the Clarion template chain, but rely on the use of the ABC Library Classes. Examples of this are the support for RTF Text Controls, Pop-up Calendars, and the new enhanced edit-in-place.
The linking of the ABC class support requires the following default pragmas settings to be included in the project system:
_ABCDllMode_⇒0
_ABCLinkMode_⇒1
Template support to automatically include these pragmas can be found in the Global Properties Classes tab by checking the Enable the use of ABC Classes check box.