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 
. 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 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
The ideal approach for using Class code in Multi-DLL applications is to include
the code in the so-called "Data DLL" 
and then export the Class from that DLL so
it can be used in any app that uses that DLL 
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
There's nothing to do - the update should be transparent.
- 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
1. Check that only the Data DLL has the option "Export this Class"
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
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
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
S1. You've upgraded StringTheory from before version 1.76, and now you're getting lots of Unresolved External errors in your
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.
N1. You've recently upgraded StringTheory from before version 1.76, and now your NetTalk application crashes.
Y1. You've recently upgraded StringTheory from before version 1.76, and now your Cryptonite application crashes.
|Multi-Proj for |
Gen Ver 4.
|AnyFont||Class & Template||1.64||1.64||
|Cryptonite||Class & Template||1.52||
|Draw||Class & Template||3.35||3.35||
|EzHelp||Template & DLL||n/a|| ||n/a||
|File Explorer 5||Class, template and DLL.
||Note 5|| || ||
|File Manager 3||Template & DLL||n/a|| ||
|GPF Reporter||Class & Template||2.29||
|HotDates||Class & Template||1.87||1.87||
|HyperActive||Class & Template||2.11||
|Insight Graphing 2||Class & Template|| ||
|| ||2.06 / 1.90|
|Keeping Tabs||Class & Template|| || ||
|MailSync||Class & Template|| || ||
|Makeover||Class & Template||2.97||2.97||
|MessageBox||Class & Template|| || ||
|NetTalk 7||ABC Class, DLL & Template||
Note 4|| || ||
7.10 / 6.52 / 4.59 |
|OddJob||Class & Template||1.32||1.32||
|Office Inside 4||Class & Template||4.13||
4.13||4.13|| / 3.78|
|Progress||Class & Template||1.23||1.23||
|Replicate||Class & Template|| || ||
|Right Reports||Class & Template|| || ||
|Safe Update 3||Class & Template||3.04||
|Secwin 6||DLL & Template|| || || ||
6.22 / 5.03|
|SelfService||Class & Template||3.40||
|SendTo||Class & Template|| || ||
|StringTheory||Class & Template||1.78||
|TabTree||Class & Template||2.13||2.13||
|WinEvent||Template & DLL||n/a|| ||
|xFiles||Class & Template||2.38||2.38||
- Standards are not something you can dream up before you start.
They evolve over time as best practices are discovered, and as the pros
and cons of doing things are understood. They are also not static, they
change with time, making use of new possibilities as they are made
available. From time to time you identify something as being good, and
you make the decision to re-work some older products to meet the new
- The Data DLL is conventionally the lowest DLL
in your calling chain, the one containing
the exported file structures, and if you are using ABC, the one
containing the ABC classes. With our standard the new classes don't have to be in
this APP, they could be added to, and exported from, any APP in the
chain. However after a product update this APP (and all APPs that use
this APP) need to be recompiled.
- Do not be confused between a Class and an Object.
The Class is the generic code that is compiled. Objects need to be
created from the Class to actually exist. The Objects belong in the APP,
and usually the Procedure where they are created and used. Only the
generic Class code is compiled into the Data DLL and exported from there, not
- NetTalk is the one class based product which makes itself into an
ABC Compliant Class. (Despite the name it works in Clarion Legacy apps
just fine.) It was the first class-based product we made, and there were
sufficient disadvantages to this approach that we did not make another
class like this. It follows different rules for Multi-DLL - in short it
lacks the Multi-DLL tab and you don't need to worry about that at all. In short
it behaves just like any other part of ABC. The global extension is
added to the Data DLL and to every app that uses a NetTalk object.
Because changing this product would orphan a lot of embed code, this
product won't be changed to the current object generation or
- File Explorer is scheduled for change in File Explorer 6 to remove the DLL.
At that point a change to the new Multi-DLL and object generation format
will be made.