ABC Embeds Are Easy

by Tom Giles

Published 1999-12-21    Printer-friendly version

I started using Clarion Professional Developer (CPD) 2.0 with Designer when it first came out in the early 80's. I found it had a fairly steep learning curve for a DOS product but once I understood it there was nothing I couldn't do, even though much hand coding was usually necessary.

When I finally had the time and need to move into Windows I started with Clarion4. I was overwhelmed as most users seemed to be. I looked at the embeds of one of my forms and found about two thousand possible entry points (click here for a partial listing screen shot). I had no idea where to start or how to begin to understand them. I never heard a clear explanation of embeds. It was as if no one really knew or if they did, they wanted to keep it a secret.

Over time I have gotten to the point of feeling I have a good understanding of the ABC embeds. And once you know what embeds are for and how they work, they're really quite easy to use. This article will discuss embeds based on a form procedure, since that is where the majority of them will probably be needed.

First of all embeds allow you to enter your personal code before or after each block of code (usually class methods in ABC) written by members of the TopSpeed Development Centre in London, England. The people in London do the hard work and optimize and debug the complicated code. You do your part to make it fit your program needs. It's really a very good arrangement.

In Legacy Clarion, the embed names were directly tied to the template so they generally followed the program flow in a logical start to finish order. They had specific and meaningful names even a beginning programmer could understand. ABC (Application Builder Classes) introduced OOP (Object Oriented Programming) which is based on a series of "black boxes" of small code snippets of debugged, highly efficient code. Since you can't easily get to that code, and probably wouldn't want to if you could, embeds allow you the programmer to put your code before or after the class's (or object's, if you prefer) code.

This arrangement offers a great deal of flexibility but at the same time gives an overwhelming number of possibilities. The embed names are purposely fuzzy (vague or cryptic) since the code objects could be used many different places for many different purposes. The upshot is the naming convention is actually logical but at the same time confusing, especially to the new programmer. Perhaps as ABC matures two sets of names could be evolved. One would be the strictly ABC names, the second set template-oriented similar to the Legacy embed names. This might also be an avenue (read revenue) for third party developers. The Clarion 5 Learning Your ABC's handbook has a partial listing that is helpful.

Not to be too nostalgic, but it was fairly simple in DOS. There were three major embed points or lines. Procedures had a Setup line, a Next line and edit lines for each data entry field. The Setup line allowed initialization entries for the procedure and the Next line allowed post procedure processing. The edit lines were for field validation and error checking as well as preprocessing for the next field. Remember that unlike Windows the programmer was in charge and specified the movement throughout the form. In Windows the users are in charge and can and will do as they desire when it comes to navigating the form.

OOP is also very simple at its heart but allows/creates the mega-multitude of embed points since you can add your code before or after each of the ABC code snippets from London. This is both an advantage and disadvantage. It means your hand coding will be minimized which should result in less work and bugs. The disadvantage is not knowing where to start.

Figure 2. The embed tree (collapsed except for one routine embed).

Procedure Routines (Routines)

I'll start with the easy one at the top, the Procedure Routines. This is just what it says, a place to put Routines for this procedure. Basically a Routine is a section of code that will be used a number of times within a procedure. Instead of embedding (placing) the same piece of code multiple places throughout the procedure, you put it in one place and just call it repeatedly as needed. This allows for easy maintenance as the code is in one location and is written only once. Notice the similarity to OOP. And you thought the concept was difficult.

In CPD the Model files did not support Routines so you had to do extra hand coding. Not bad once you figured out how but not as easy as just dropping the code in. The basic syntax for a routine is:

RoutineName ROUTINE
!Your code goes here

An END statement is not needed for the ROUTINE statement. To call the routine, just enter DO RoutineName at the appropriate embed points and the routine will execute. For an example look at the Finance tab in Figure 3.

Figure 3. A form in need of embedded code.

Here I want to calculate the Tax, Total Amount and Balance Due any time a change is made to any of the listed numbers as well as the PayoffDate and some others, (which are shown on other tabs). In CPD I would have used a computed field which would do the three calculations every pass through the Accept Loop (except of course it wasn't called an Accept Loop then). Similarly, the Clarion5 Formula Editor will do calculations at specific points as defined in the Class entry point. You could use one of the embed points such as TakeFieldEvent (it goes through this embed after every field acceptance) but the code would be somewhat buried amongst the others and would be hard to find if you needed to edit it. A Routine is good here. Click here for a (large) screen shot of my routine code.

For each of the fields at the right of the screen in Figure 3, and the Tax Rate, I enter DO Finance in the ControlEvents|?datafieldname|Perform field level validation embed point. Since the Price and Options came from previous tabs on that window I put a DO Finance at those points also. This way any time the user looks at the Finance tab it is correct.

Several other points about the above code you might want to consider: My top line of any embed is a one line explanation of the purpose of the embed for quick reference (i.e. six months from now). I also use a lot of white space in my formulas (formuli to be correct) since I find them easier to read. For the END statement I copy the corresponding starting line as a comment so there will be no doubt what it is for. This is helpful when there are several nested statements each with a corresponding END. I still use THEN and a period (.) in lieu of END as a carryover habit of my DOS days on occasion. You need to develop your personal programming style then stick with it.

Remember programming is basically logical thinking and attention to detail. A good style helps prevent errors and makes a later review of your code much easier. I also believe in a lot of comment statements, but not of the very obvious code. Stress the purpose or the why; don't just repeat the code a second time.

Control Events (Data Field Editing)

Referring back to Figure 2 you'll see that the next section in the embed list is Control Events. This is equivalent to the CPD Edit line. Here you put your code to validate the current field or preprocess the next field. Figure 5 shows the expanded list of embeds for ?CNB:Price.

Figure 5. An expanded Control Events embed list.

In Figure 5 you see the embeds for the Price field. I have my one liner DO Finance in the Accepted|Perform field level Validation|SOURCE embed. The Perform field evaluation is the one you will use the most often. The others may be needed under special circumstances but I very seldom use them. Note that you will not have to write the setup line of code and the END statement since the various possibilities (accepted, selected, etc.) are already set up for you. Just put the meat of the code in the appropriate place. It's another simplification for you.

I tend to use a lot of these embed points for error checking of data entries. Do all that you can to insure only good and valid data gets in the system as it will make your job much easier. I also tend to put a lot of error messages here (using the MESSAGE() function) to clearly explain what is wrong with the input so there will not be any confusion. You can't force the user to read the messages but try and let them know anyway.

There are two embeds you should not use here: they are ?OK and ?Cancel. If you embed code in these and the users clicks the X in the upper right corner of the screen then the Yes or No message about saving the Record your OK/Cancel code will be missed and users will complain and potentially bad things could happen or not happen depending on your code. See Local Objects|ThisWindow below for a solution.

Window Events (Advanced)

The next section is Windows Events. This allows embeds about the screen and the window itself. This is for special situations and probably won't be used that often, at least not by the beginning programmer. It's nice to have when you do need it, however.

Local Procedures (Advanced)

Local Procedures is another special use case more for the advanced user with special needs.

Local Objects (ThisWindow)

Local Objects is very intimidating for the novice. Your main concern will be with ThisWindow. If you use the toolbar you might be concerned with that also. Consider anything else here special cases for the advanced user and disregard for now. Even so ThisWindow is still very intimidating by itself. But there are only a few embeds you will need to be primarily concerned. Init is similar to the Setup line in CPD. In CPD 2.1 the files were opened as the program started. In Windows Clarion they are opened/closed as needed. Take this into account when embedding code in Init or Kill.

Kill is analogous to the CPD Next line. It will close all the files listed in the Files portion of the Procedures screen and allow for any post-processing code. The TakeCompleted embed should be used for your ?OK code as it will be triggered for the OK button as well as the X\Yes. The TakeCloseEvent (after the parent call, which is the Save This Record box) is the best place for the Cancel button and X\No code. See my upcoming article titled "An ABC Gotcha" for more information on this subject. TakeEvent is similar to the CPD Accept loop and will be triggered throughout the program. Some of the other Take????? Embeds may be needed on occasion.

Local Data (Advanced)

Local Data is another section you probably won't need. Use the Data section at the Properties screen instead.

Self Help

In trying to learn embeds I have tried several methods and techniques. I started by using the brute force approach of putting STOP statements in any embed that looked remotely usable, and even some others for good measure. I used STOP(1), STOP(2), STOP(3), etc. then ran the program making notes of what came up and when. This method works okay most of the time. You are good to the first STOP statement. Since you must respond, a message is sent to Windows which could be misinterpreted and cause unexpected results. Normally this is not a big problem but it has happened to me.

The technically better approach is MESSAGE(1), MESSAGE(2), etc. This should not confuse Windows as much as the STOP statement does. One advantage of the STOP statement is that it will allow Abort for an easy out. The MESSAGE statement can create an endless loop. I start with the STOP then maybe go to MESSAGE.

Another approach is to click on the red Legacy shield (see the tool bar in Figure 1 between the two activated buttons) to bring up the English-like Legacy embed names and chose from there. Write something such as STOP(embed name) then click off the Legacy shield to go back to ABC. Right click on the procedure and click on Source and do a search on STOP( to find your code. Move it up or down to the nearest ABC embed and erase the temporary Legacy embed.

Finally, the Debugger is not the easiest or quickest to use but can be instructive. (Click here for more on the debugger.) Click to halt on each code statement in the source. The "weird" code that goes by between each halt is the London code and is found in the \Clarion5\Libsrc directory. It's interesting, but also confusing, especially at first.

One More Technique

Another technique is to break a long embed into smaller segments (see Figure 6). As an example I have a Daily Report that is made of 10 separate reports. Five of these reports require reading data from 11 separate files. Needless to say the setup would be a very long embed. It would also be confusing while writing it, not to mention looking at it six months from now. I made a separate embed point for each complicated report, for a total of seven embeds plus the summary as shown.

Now the embeds dealt with smaller cohesive data with the same purpose in mind. The top line of each embed was the same with - sub-report name added at the end. To keep them in proper order I used the original priority for a dummy embed of just comments explaining what I would do. I added 1 to the priority for each of the others. This means they will be executed in the proper order and the sequential numbers (by 1) from 7600 to 7607. The numbers are another indication of a group that goes together. If other embeds were needed here I'd start another group of priority numbers. I find this technique makes code much more readable and manageable.

Click here for a screen shot showing prioritized source embeds.

Summary

That's basically it for ABC embeds. Use Routines if needed. Use Local Events for error trapping and field validation. Use a few selected Local Objects|ThisWindow embeds for initialization and getout (next) procedures plus a couple of others as needed. These few embeds are a good start and with time you may find the need for the multitude of other embed points. Start simple and investigate. Experiment and grow as you gain experience and confidence, and your needs expand. As I said at the start, ABC embeds are easy!

---

Tom Giles is a self-taught, long time CPD 2.1 programmer who started with interpretive BASIC for his business programs. He now uses Clarion 6 for all new projects. When not programming he is out skydiving or flying his homebuilt airplane. Isn't life grand?

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