CapeSoft.Com
Clarion Accessories
Standards

Standardization

Introduction

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;
  1. Consistent template settings for objects, and consist generation of object methods in applications and
  2. 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.

Object Generation

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.

Multi-DLL Applications

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.

Updating

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.
  1. 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.
  2. 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

  1. Open Data DLL app. Make sure the product is added there. Check settings on Multi-DLL tab are both on.
  2. 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;
  1. Start by updating SelfService, GPF Reporter, SafeUpdate 3, Cryptonite, StringTheory. These are the ones that used the common underlying templates prior to the revamp.

Common Errors

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.

See C1 above.

S2. You've recently upgraded StringTheory from before version 1.76, and now your NetTalk application crashes.

See C2 above.

S3. You've recently upgraded StringTheory from before version 1.76, and now your Cryptonite application crashes.

See C2 above.

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.

See C2 above.

Cryptonite

Y1. You've recently upgraded StringTheory from before version 1.76, and now your Cryptonite application crashes.

See C2 above.

Product Status

ProductTypeMulti-Dll
Classes
Multi-Proj for
Clarion 8
Object
Gen Ver 4.
C9
AnyFontClass & Template1.641.64 1.64  
BreakInEXE Utilityn/an/an/a  
CryptoniteClass & Template1.52 1.521.52 
DrawClass & Template3.353.35 3.35  
EzHelpTemplate & DLLn/a n/a 3.11
File Explorer 5Class, template and DLL. Note 5   5.52
File Manager 3Template & DLLn/a  n/a 5.08
GPF ReporterClass & Template2.29 2.292.29 
HotDatesClass & Template1.871.87 1.87  
HyperActiveClass & Template2.11 2.112.11 
Insight Graphing 2Class & Template    2.06 / 1.90
Keeping TabsClass & Template      
MailSyncClass & Template      
MakeoverClass & Template2.972.97 2.97  
MessageBoxClass & Template     2.19
Multi-ProjTemplaten/a n/a  
NetTalk 7ABC Class, DLL & Template Note 4   7.10 / 6.52 / 4.59
OddJobClass & Template1.321.32 1.32  
Office Inside 4Class & Template4.13 4.134.13 / 3.78
ProfilerEXE Utilityn/an/an/a  
ProgressClass & Template1.231.23 1.23 1.24
ReplicateClass & Template      
Right ReportsClass & Template      
RunOnceTemplaten/an/an/a  
Safe Update 3Class & Template3.04 3.043.04 
Secwin 6DLL & Template    6.22 / 5.03
SelfServiceClass & Template3.40 3.403.40 
SendToClass & Template      
StringTheoryClass & Template1.78 1.781.78 
TabTreeClass & Template2.132.13 2.13  
TearoffTemplaten/an/an/a  
TickerTapeTemplaten/an/an/a  
WinEventTemplate & DLLn/a  n/a 3.83
xFilesClass & Template2.382.38 2.38  

Notes

  1. 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 standard.
  2. 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.
  3. 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 the objects.
  4. 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 multi-DLL standards.
  5. 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.
CapeSoft.Com
Clarion Accessories
Standards