How to use the ClarionMag Library (CML)

Downloading the CML

If you haven't already done so, either download the CML or (preferably) clone the repository using GitHub for Windows.

You'll now have a directory tree that looks something like this:

You won't see the .git directory unless you have Windows Explorer configured to show hidden files/folders. 

The RED file: To modify or not to modify

In order to use the CML files you need to find some way of getting those files into Clarion's field of view. You have two choices:

1. Copy the files to the appropriate Clarion directories
2. Modify Clarion's redirection file to include the appropriate CML directories

I favor the latter approach because it means that Clarion is always using the latest CML files. The downside is I need to modify the redirection file.

There are four lines that have to be modified in the Clarionx0.red file (which you can find in Clarion's bin directory). Here is what the changes look like in my RED.

I know, I should write a utility to update the RED. 

Using the library

At present the CML is more of a hand coder's library, but if you're strictly an AppGen developer it's not that hard to take advantage of CML functionality. And yes, just like the RED utility, a comprehensive template to make it easier to use CML features is on my ToDo list. 

There are two ways to use the classes; you can compile the source code, or you can use use the precompiled DLL. 

In either case, to make use of any of the classes you need to include the appropriate .INC file somewhere in your source, e.g.

Include('CML_System_String.inc'),once

Make sure you use the ,ONCE attribute.

By default the CML assumes you want to use the supplied LIB and DLL, so you'll need to add CMagLib.lib to your project. If you don't do this you'll get any number of unresolved external error messages. 

Which version of the DLL/LIB do I need?

The default compiled version of the library is for the latest Clarion release (or at least the latest one I happen to have installed on my machine). As of this writing, that means Clarion 9.1 If you're using an earlier version of Clarion have a look under the bin\versions and lib\versions directories for a suitable LIB and DLL. You may want to update your RED file to look in those directories. 

If you want to compile the classes

If you want to compile the classes you won't need the LIB and DLL, but you will need to set a compile pragma in your project properties:

_Compile_CML_Class_Source_=>1

Your builds will take a little longer this way, which isn't a big hassle especially if you have just one APP that uses CML. It's more of a problem if you're using CML with multiple apps. If there are any changes to CML code you need to compile each and every one of those apps. Unless you really want to compile the source I suggest using CML in its default configuration.