Do We Need to Remind you to always make Backups
of your apps before applying upgrades?
As at the time of writing this (February 2013) we offer over 30 products which actually
add code to your Clarion application. (We offer a bunch of other things as well, but for this
article I'm limiting the list to items that actually add code to your app.)
These products span 18 years of development, 9 major Clarion versions, were
worked on by 9 different programmers and have been through literally
thousands of releases. Not surprisingly there are things in them that work
differently from one product to the next
[1]. As we
move forward there are some changes you may need to make to your
applications, however in the long run consistency is a good thing, and while
getting there may take small amounts of pain we believe the end result will
be programs that are easier to maintain.
This document explains what we are doing, and also describes some of the
pain-points likely to occur when upgrading.
Broadly speaking the accessory products can be separated into two categories. the smaller
group, of older products, are procedurally based, and are shipped with DLL's.
These reflect the practices of the time they were created, and the fact they are
still available and still popular is testimony to the strength of this model.
However for the last 13 years or so the products have been class based, and
usually shipped as source code. Those that were class based, but shipped as
DLL's, have been, or will be, migrated over to shipping as source code. That
process takes some time but already Insight Graphing 2 and Office Inside 4 have
shipped as source code and only File Explorer currently remains in this
in-between state.
In early 2013 we identified a need to standardize some of the aspects of the
products, especially with regard to the way classes are generated, and how the
classes are used in Multi-DLL applications. While all the products are broadly
similar, there are differences between them and so a tidy-up is in order.
The current goals are as follows;
- Consistent template settings for objects, and consist generation of object
methods in applications and
- Consistent methodology for Multi-DLL applications.
As time goes on we expect to add more items to this list, and indeed to list some of the
things which are already standard across all products. Standardization is a process
not an event, and it's something we're paying a lot of attention to.
To make use of an object in an application, the Global Extension for that product must
be added to the APP. Once added objects can be instantiated in a procedure using either
embedded hand code or by making use of the Local Extension Template for that product.
Products instantiated by the template create potential embed points for all methods, and
these embed points are added to the Embed tree under
The object, and all methods, are also visible in the Embeditor (Right-Click on a procedure, choose Source).
This approach works identically regardless of whether you are using the ABC template chain or the Clarion Legacy
template chain.
The ideal approach for using Class code in Multi-DLL applications is to include
the code in the so-called "Data DLL"
[2] and then export the Class from that DLL so
it can be used in any app that uses that DLL
[3].
Each template has a global extension.
This global extension should be added to the Data DLL, and also added to each
other application (DLL or EXE) where the class is used.
On that global extension is a Multi-DLL tab. On that tab are two settings;
This is part of a Multi-DLL program
If your program is a set of multiple app
files, then tick this option on. It doesn't matter if you are in a DLL or EXE,
tick it on. The only time you would not tick this on is if you are making a
single APP program (which is being compiled to an EXE.)
Export whatever class from this DLL
If this is the Data DLL then tick this on.
Only one APP file in your Multi-APP suite should have this on.
Products that require other products
A number of our products are built
on top of other products. Insight is built on Draw, NetTalk makes
use of StringTheory, and so on. This means that code can progress
quickly, and effecient re-use of code is maintained. (This, in case you
were wondering, is a very good thing.)
One thing that is inconsistent though is the way in which one product
uses another. So, for example, Insight Apps require the Draw Extension
to be added to the application, whereas NetTalk used StringTheory
"transparently". In order to make this more consistent, and umtimaly
give you more control over each part, we're moving to an approach where
products will require you to add the Global Extension for all dependant
products to your app as well.
So, put another way, if you are adding (say) the NetTalk Global
Extension to your application, you will need to add the StringTheory
global extension to the application as well. If you are adding Insight,
you will need to add Draw, and so on. The benefits of this approach are
subtle, but ultimately give you more control over some of the finer
points of the products.
We make every effort to make sure that updating from one build of a product to the next is as smooth as it
possibly can be. However in some cases it is not possible to change the standard approach without causing
some incompatibilities. Rather than introduce endless hacks (and thus endless chances to make future problems
for everyone) some items need to be checked.
- The Multi-DLL tab for the updated product(s) should be checked in the Data DLL to ensure that the
class is being exported. If you encounter an error in a different APP in the suite then check the
Multi-DLL tab there as well to make sure it is correct.
- In a small number, of probably very rare cases, some embed code may be orphaned. Unfortunately there
is (currently) no automatic method to detect orphaned code other than visually inspecting the embed
tree for each procedure. Pre-emptive checking is probably unnecessary, however if you get compile errors
or missing functionality, check the procedure for orphaned embeds.
Five Second Guide to Updating
Single App
There's nothing to do - the update should be transparent.
Multi-App system
- Open Data DLL app. Make sure the product is added there. Check settings on Multi-DLL tab are both on.
- Open EXE app. If the product is added there check the
Multi-DLL tab and make sure "This is part of a Multi-DLL
program" is on.
What to Update?
You don't need to update everything all in one go. However as some products were further along than others the
following suggestions are offered;
- Start by updating SelfService, GPF Reporter, SafeUpdate 3, Cryptonite, StringTheory.
These are the ones that used the common
underlying templates prior to the revamp.
General Compile/Generate Errors
C1. You've upgraded something, and now you're getting lots of
Duplicate Symbol errors in your
application.
1. Check that only the Data DLL has the option "Export this Class"
ticked on.
2. Check the solution for the current app and remove any reference
to xxx.clw (where xxx.clw is the source module for the
product in question) from the list of CLW files to compile.
C2. You've upgraded something, and now you're getting a GPF in your application.
Some products, which use other products, would automatically include that code as required. This is convenient, but
has some disadvantages as time goes on. The system has now changed so that all products which use another product
require that extension to be added to the app as well. For example NetTalk
7 and Cryptonite both require StringTheory,
NetTalk 6 uses it if it's there, and it's now mandatory to have StringTheory explicitly added as a global extension in these apps. Failure to add the
extension will result in either a Template Error or a program GPF.
If this is a Multi-DLL system then you will likely need to add the
extension to the Data DLL, paying special attention to the Multi-DLL
settings there. See
Multi-DLL
applications above for more.
C3. I'm compiling the Data DLL and I get Unresolved External errors.
Try and figure out from the name in the errors which product is at fault from the method names listed in the errors.
Then go to the global extension for that product and check the settings on the Multi-DLL Tab. If this is the
Data DLL
then both the "This is part of a Multi-DLL program" AND "Export class from this DLL" should be ticked on.
C4. I'm compiling some other DLL, or EXE, and I get Unresolved External errors.
Try and figure out from the name in the errors which product is at fault from the method names listed in the errors.
Then go to the Data DLL and add that product (with both Multi-DLL switches on) to that Data DLL.
C5. I've upgraded something, now I'm getting errors
Group %ReadClasses not found when I open an app.
The full text of the error is probably something like;
Error: Group %GlobalDeclareClasses (SafeUpdate)
Not Found or
Error: Group %ReadClasses (SelfService) Not Found
where the product name may vary.
The solution is to update the Product name mentioned in the
brackets. In other words, in the above example it would be an
indication that SelfService and Cryptonite should be updated now as
well.
StringTheory
S1. You've upgraded StringTheory from before version 1.76, and now you're getting lots of Unresolved External errors in your
application.
S2. You've recently upgraded StringTheory from before version 1.76, and now your NetTalk application crashes.
S3. You've recently upgraded StringTheory from before version 1.76, and now your Cryptonite application crashes.
S4. You've recently upgraded StringTheory from before version 1.76, and now your application has Duplicate Symbol errors.
Duplicate symbols are caused when an application (called say AX)
compiles a CLW (in this case StringTheory.Clw) and also links in
another app (typically the Data DLL) which has also compiled, and
exported, the same CLW. The solution contains two checks.
a) Make sure that the StringTheory settings in this app (AX) are set
correctly. This is part of a Multi-DLL should be on, and Export
should be off.
b) Check the Solution to see if the StringTheory.Clw file has been
added to it in the past (and may still be there.) If so remove it
from the Solution.
NetTalk
N1. You've recently upgraded StringTheory from before version 1.76, and now your NetTalk application crashes.
Cryptonite
Y1. You've recently upgraded StringTheory from before version 1.76, and now your Cryptonite application crashes.