The Novice's Corner - Getting A Grip On Clarion

by Dave Harms

Published 1999-02-22    Printer-friendly version

For those of us who have been using Clarion for years, the application development environment, with all of its idiosyncrasies, is second nature. If you've just picked up Clarion, however, your initial reaction may be more one of confusion than familiarity.

I don't think that Clarion is any more difficult to grasp than other development environments, but because it has some unique features it doesn't offer as many points of familiarity to the average programmer as, say, VB, Delphi, or most C++ environments. In this article I'll give you a road map to the Clarion development environment, including the use of templates and the "standard Clarion" approach to application design.

The Minimal Clarion Program

Most Clarion developers spend the majority of their time in the Dictionary Editor and the Application Generator, two tools that greatly facilitate the creation of large and complex applications. What these tools ultimately accomplish is simply the creation of files of Clarion source code (which typically have the extensions .CLW or .INC). These source files are then compiled and linked into a working program (EXE) or library (DLL or LIB).

With respect to compiling source code Clarion is not much different from Delphi, or a C++ or Java development environment. Where Clarion differs is that it gives you the ability to create quite large applications without ever having to look at a single line of Clarion source code. In practise, most developers do work with some source code, but the majority of the code writing, if you will, is done by the Application Generator, usually in conjunction with the Dictionary Editor. I'll have more to say about those tools a little later.

You might think that all of this code generating power came about because Clarion is a difficult language to work with. Quite the opposite is true. Clarion is a compact and highly readable language. For instance, the classic "Hello World" program in Clarion is brief and to the point. A number of variations come to mind, but one of the shortest is shown in Listing 1.

Listing 1. A Clarion "Hello World" program.

program
   map
   end

   code
   message('Hello, world.')
  

The one thing all Hello World programs have in common is that they're completely useless and often don't represent the way real world programs are written anyway. The same is true of this Clarion example. Hello World is contained one source file, or module. A smallish real-world application (say an invoicing program) would probably have from 30 to 50 separate procedures, and you could have one source file for each procedure. And each source module would be considerably bigger than hello.clw.

All of that means that to write an application line by line in a source code editor in the style of hello.clw can be a somewhat painful proposition, even with a highly expressive language like Clarion. Application developers typically look for ways to speed up this process.

There Has To Be A Better Way

One way to speed up your application development is to use a prewritten library, whether it's a procedural library or a class library (for the object-oriented among us). Libraries can save you a whole lot of time. They're not always as flexible as you might like, since you often can't change them, but well-written class libraries in particular can give you many ways of enhancing functionality without altering the original library.

Clarion has always used procedural libraries, and since version 4 has also had an extensive class library. In fact, since your application runs on Windows, one way or another it has to make extensive use of the libraries of code built into Windows. (Usually Clarion developers are shielded from Windows code by Clarion's libraries which act as an intermediary, but if you wish you can interact directly with Windows by using the Windows API.)

Using libraries improves development speed, but doesn't exactly get it racing. To really kick things up a notch you need to look at other technologies.

Speeding Development With Templates

Clarion has had some form of code generation capability since the second DOS version, called Clarion Professional Developer, or CPD. CPD introduced the Designer and the model file. The Designer was a visual design tool that let you create procedures, each of which could have an accompanying window or report on which you could place fields from a data dictionary. You could also add text and draw lines. Don't laugh. Back in the '80s this was exciting stuff!

The model file contained blocks of Clarion code for various kinds of functionality (menus, browses, etc) as well as symbols that could be replaced by information the user specified in the Designer. When it came time to compile, the Designer would read the model file and substitute field names and other information for the symbols, and presto! Instant source code.

There were some problems with this approach. If you wanted to change how Clarion generated code, you had to modify the model file, and you could only use one model file at a time, so it was difficult to mix and match features from different third party vendors. As well most of the decision-making code was internal to Designer, so even if you modified the model file you were under a lot of restrictions as to what you could do. You were seriously limited in the number of places you could add your own code to what Designer created, and any changes you made directly in the generated source would be lost on the next compile.

In the years since CPD Topspeed has improved this code generation technology radically. Designer has been replaced by the Application Generator, the Dictionary Editor is a separate entity, and the model files have been replaced by template files. The result is a far greater level of flexibility.

Fundamentally, however, the Clarion approach to development isn't that different from what it was in the early days. Do as much work as you can visually. Let the AppGen spit out the mundane, repetitious code. Write the code AppGen won't and embed it, or better yet modify or add to the templates or the class library and thereby extend the application development environment to suit your needs. You can, in effect, train Clarion to work the way you work.

Starting With The Dictionary Editor

Most Clarion application development starts with a data dictionary, which defines one or more data files (more commonly called "tables" by the rest of the programming world, and by Clarion developers working with SQL). If you wish you can create an application using the Quick Start method which lets you define a simple app with one data file, but the result is rarely good for much more than a test application because of the severe limitations on the type of file and fields you can create.

The focus on the dictionary editor reflects Clarion's origins as a business software development language. You can certainly write Clarion applications that don't use data files, but most of the time people buy Clarion because they have data they want to create, query, or otherwise manipulate.

Assuming you want to create an application that uses data files, begin by choosing File|New|Dictionary.

There are three main ways to define data files. You can create the files one at a time using Quick Load. If Quick Load is turned on (see Setup|Dictionary Options, File Options tab) when you click on the Add File button in the Dictionary Editor you have the option of using the built-in Quick Load tool to rapidly specify a data file (you can fine tune this file later). Quick Load only requires you to enter a file name and prefix, a file driver (to suit whichever database back end you're working with), a prefix to make the file's fields unique within the database. For each field you specify a field name, a picture token which indicates how the field should be displayed, and how long it will be, and optionally a key for the field. Quick Load only lets you have a single field per key, but again you can change this later if you wish.

If you decide to not use Quick Load (and after the first few tries, you probably won't), you'll need to specify a bit more information about the file and the fields. Even so a lot of information is set to default values. You'll also almost certainly want to create some keys, which greatly speed access to data and allow you to view the data in different orders.

The third way to define a data file is to import it from an existing database. You can import from any database for which you have a driver. There are a wide variety of flat file database drivers included with Clarion, as well as client/server drivers such as ODBC, Pervasive.SQL, MS SQL, and SQL Anywhere. Clarion Enterprise Edition also comes with a Dictionary Synchronizer that makes it easier to keep your dictionary aligned with the database.

A Clarion dictionary is much more than a repository of file formats. Field definitions in particular can contain a great deal of information that will be used to create the application, including the type of control to be populated on windows, the prompt text, column headings, and whether or not the field should be populated at all. You can specify field validations, and even embed information which controls which custom code you want generated along with the field (though this is a little-used feature at present). Figure 1 shows some of the field validation options.

Figure 1. Data dictionary field validation options.

As well, you can define relationships between files in the dictionary editor. Almost all databases are made up of files with connections to each other, such as invoice detail records which belong to a specific invoice header record.

Figure 2. The relationship editor.

The choices you make in the dictionary editor can have a great impact on the initial appearance of your application, and this will become increasingly important as Topspeed rolls out the Wizatrons, its latest application-generation technology (and the subject of an article by David Bayliss, which will appear in Clarion Magazine in early March, 1999).

In many cases, dictionaries get far less attention than they should because developers are eager to hurry on to the "real" work of creating their applications. Database design is a sometimes neglected aspect of application design, and usually steps missed here will result in considerably more work down the road.

Now Comes The Easy Part

Assuming you've created, imported, begged, borrowed, or stolen a dictionary, you're a couple of mouse clicks and keystrokes away from creating an application. If the dictionary is still open, close it. Choose File|New|Application and enter a name for the application (making sure use Quick Start is not checked), and click OK. Next you see the Application Properties window (see Figure 3). Enter the name of the dictionary you created in the Dictionary File field. Accept the default values for the rest of the fields, but make sure that Application Wizard is checked. (The Application Wizard is a special type of template that automatically builds procedures out of existing templates, data dictionary information, and some minimal user input.)

Figure 3. The Application Properties window (creating a new application)

Click OK, and the wizard will ask you a fairly small number of questions about which files you want to use, and a bit about the style of the application. After the wizard is done, it creates your application.

But what kind of application is it? How does Clarion know what you want to create?

Truth to tell, Clarion doesn't know what you want to create. It does make certain assumptions. One of these is that you want to create an MDI application, with a standard application frame which will contain all of the windows you may want to display, and a menu bar from which you can invoke these windows (each of which is contained in a procedure).

Another key assumption Clarion makes is that you wish to use the "browse-form" paradigm.

The Browse-Form Paradigm

In the browse-form world, you have choices on the main menu that allow you to bring up browse procedures. This means that the first time you see existing data from a database in a typical Clarion application, it will be in a scrolling list, or browse, as shown in Figure 4.

Figure 4. A typical browse.

Clarion browses are a bit different from some you may be familiar with in that they are (traditionally) page loaded. Only the records you see on screen have been loaded into memory, and if you scroll past the last or first record on screen, the next or previous record is retrieved (if possible) and the record that scrolls off screen is discarded. This is a useful feature when you're dealing with large data sets, although it does introduce some difficulties in managing the scroll bar, since it's more difficult to accurately position a scroll bar to indicate the record's relative position in the entire data set. In Clarion 5 you have the option of creating file loaded browses, in which all valid records are loaded into memory.

To update a browse, you typically click on an Insert, Change, or Delete button (or use a popup menu on the browse) to bring up another window (and therefore another window - you can have multiple windows in one procedure but it's awkward and not recommended) which allows you to update the browse record. In C4 and C5 (using the ABC templates) you have the option of not using the form. Instead you enter data directly into rows on the browse, but the templates still generate forms for your browses.

Forms will also be generated with browses if the file that's being updated has child records, as defined in the data dictionary. The controls used on the form (entry fields, spin boxes, drop combos, etc) are also taken from the data dictionary.

The appearance of a wizarded application is largely determined by what information has been placed in the dictionary, as well as by the overall concept of the browse/form. In general Clarion tends to steer you down the browse/form path. That's not a problem if browse/form is what you want, but if you're more accustomed to starting with a form and letting the user look up records from that form, you may need to do a bit of work or cast about for some suitable third party templates.

Maximum Wizards

You may want to consider starting your development of a particular application by going through the App Wizard process a number of times, recreating the application each time. After each app is created, compile and run, and evaluate the result against your final goal. Explore the dictionary options, fine tuning your files, fields, and relationships to get the automatically created application as close as possible to your desired result. This is particularly important if you expect to be creating multiple applications using the same dictionary, as you will want your applications to share the same look and feel.

When your dictionary has reached a suitable level of maturity, you can either modify your last wizarded application, or create a new application without using the Application Wizard option. In the latter case you begin building your application procedure by procedure, usually by starting with a Frame procedure as the main menu. Some procedure types (such as browses, forms, and reports) have accompanying wizards which you can use selectively to recreate what the application wizard did all at once.

The forthcoming Wizatron technology is going to further refine this process. Wizatrons use style sheets to apply user-defined formatting and functionality options to automatically-generated procedures, so it's entirely possible that at least in the early stages of application development you may be altering data dictionary and Wizatron style sheets to create your basic applications.

Beyond Wizards

As you become more proficient in Clarion, you will encounter situations where the various wizards (or even Wizatrons) aren't able to create the kinds of procedures you want, even with extensive modifications to the procedure after the wizard's done. Fortunately, Clarion provides several levels of template granularity for different kinds of tasks.

The Application Wizard is a template that creates procedures, and in the process calls other procedure wizard templates. Individual procedure wizard templates create procedures by combining non-wizard templates. A simple browse procedure, for instance, is a combination of a Window procedure template and a browse control template. This granularity makes it easy to add a second browse to a window, because that simply means adding another browse control template. Anything the wizard does, you can do too. You can combine various kinds of templates within a procedure to create exactly what you need.

Templates greatly automate the process of building applications, but even the most extensive set of templates (and you can easily integrate your own or third party templates) probably isn't going to do everything you want to do. There comes a time when you want to modify the behaviour of your application and the only way to do it is by writing some Clarion code. You may not need to know a lot about the Clarion language to accomplish your goal, but the more you know about Clarion code, and the templates, and the overall structure of "standard" Clarion procedures and applications, the more you'll be able to make your application dance to your tune.

At the beginning of this article I mentioned that any Clarion program is, ultimately, Clarion source code that is compiled into an EXE or DLL (or LIB). The Application Generator creates this code based on the templates you use, and so you might think that the best place to put your source code is in this generated code. The only problem with that idea is the next time you make a change to a procedure in the AppGen and regenerate the code, your changes will be lost. What you need is a way to insert your code into the templates.

This code insertion is done by means of source code embed points. Embed points are under the control of the templates, and they are just about everywhere. If a template is used multiple times in an application or procedure, then each instance of the template gets its own set of embed points.

A Place For Everything

All of the embedded source, as well as all of the information specified by you or by the various wizards regarding the appearance and behaviour of your application is stored in the .APP file created by the application generator. The data dictionary contains the database specification, as well as a great deal of optional information about field appearance and validation. And the templates are actually source files, but in order to be used by the AppGen they must be loaded into the template registry (REGISTRY.TRF, in the template directory). Under normal circumstances you will have both the text versions of the templates and the registry, although at a minimum you only really need the registry.

In addition to the template registry, dictionary editor, and application file, any given Clarion application needs some of the source files in the LIBSRC directory in order to compile, as well as some precompiled binaries in the BIN directory to link and run. To be completely safe on your backups, you should save, at a minimum, the APP and DCT files, and any changed files in the TEMPLATE and LIBSRC directories. The template registry can be recreated at any time with no ill effect on applications, unless a template file (or some part thereof) has gone missing in the interim.

Next in the Novice's Corner - Understanding Template Types and Embed Points.

---

David Harms is an independent software developer and the editor and publisher of Clarion Magazine. He is also co-author with Ross Santos of Developing Clarion for Windows Applications, published by SAMS (1995), and has written or co-written several Java books. David is a member of the American Society of Journalists and Authors (ASJA).

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942