Simply Clarion - Managing your embeds

by Don Reynolds

Published 1998-03-01    Printer-friendly version

Download the code here

Publisher's Note

At several points in this article, the template code is much too long to fit in a normal width document. We've used continuation characters ( the rule character | ) to show where the code is continued. This code will not work as shown in this article. You should use the enclosed templates instead. We hope this message helps eliminate the confusion that could be caused.

Embed Points

Embeds provide to the Clarion programmer a way to add functionality to the basic templates. From a set of many embed points, the programmer selects the correct one, then inserts his own code. Instead of the original template functionality, the programmer has created a variation. Sometimes this overrides the original functionality; sometimes it adds new functions. In either case, it acts differently.

Programmers who have done this repeatedly sometimes forget what it was like to enter their first embed point. Finding the correct embed point was not easy at first. Sometimes this involved trial and error. Eventually, the correct one was found. Success!

One success leads to another. Soon, depending on the nature of the project, there are many embed points with entries in them. More successes!

However, compared with the total number of embed points available, the number of embed points that a programmer regularly uses is quite small. He or she has a favorite set of embed points. The applications worked on reflect this. One programmer's set will probably be different than another's set.

Conversion to C4 ABC templates

When the ABC templates were released, some favorite embeds disappeared, some moved, some were renamed. Great care was taken in the IDE to help the programmer. All of this is useful to a programmer working on a single application at a time. But what about multiple applications?

Wouldn't it be nice if there was....

• A quick way to produce a list of the unique embed points you use as a programmer (in multiple systems)?
• An easy way to know which systems use which embed points (Tell me all the systems which use the embed AcceptLoopBeforeEventHandling).
• An easy way to know which embed points are used by any particular system.
• An easy way to identify specific procedures which use each embed point (Tell me all the procedures in all the systems which use BeforeFileOpen).
• A place to record conversion notes to the ABC templates for each Clarion embed point used. Of course this would be stored in one place for each unique embed point.
• A way to flag whether the embed point converts as is (OK) or whether it will need modification.
• A report of all the embed points showing which embed points needed modification.
• There was a template to extract the needed information from your apps.

If I had all that what could I do? I could.....manage!

For example,

• You could manage the set of embeds you use. Do not document the conversions necessary for the entire set of embeds. Do this only for the ones you use. The app conversion program which comes with Clarion 4 should facilitate this so it is not too difficult.
• You could build a test program to act as a benchmark for template changes. Include at least one example of each embed point. When a new beta of the templates is released, run it against your test program. Does it work? Here again, you're not testing all the embed points, only the ones you use. If you find a problem, provide input to the TopSpeed development team. If they know about it soon, your chances are better that something will be done about it. If you hope that someone else finds the problems, you're increasing your risks, and not 'managing' that risk very well.

OK, OK! Do you have the answer for everything I'll ever need?

No, but here are some tools which will do the things mentioned above. Like any tool, it grows over time and seems to take on a life of its own. This iteration is better than the last one, but not as good as the next one.

The solution comes in two pieces, a template and a program.

Actually the program could work without the template but it would be a lot of work. And since I avoid work whenever possible, the template makes life easier.

First, the Template

#TEMPLATE (EmbedPoints, 'Embed Points'),FAMILY('ABC','Clarion')
#! Version: 1.01
#!
#! Initially used at Devcon '97 version 1.00
#! Revised for use with revised embedmgr--version 1.01
#!
#!*****************************************************
#!
#UTILITY(PrintEmbedPoints, 'Print All Embed Points to App.EPT')
#!DECLARE(%OutputFile)
#DISPLAY('This Utility will dump all your Embed points to a file.')
#DISPLAY('')
#PROMPT('Save to File:',SAVEDIALOG('Pick File'|
        ,'Embed Source|*.EPT')),%OutputFile
#PREPARE
  #SET(%OutputFile,%Application & '.EPT')
#ENDPREPARE
#DECLARE(%ASCIIFileRecord)
#DECLARE(%InstancePrefix)
#DECLARE(%InstanceQueue),MULTI
#!
#CREATE(%OutputFile)
#MESSAGE(%Application,0)
Embeds: for %Application
#FOR(%Procedure)
  #MESSAGE('Exporting Embeds: ' & %Procedure,2)
  #SUSPEND
    #!?!******* The following line exports the procedure name
#?PROCEDURE %Procedure (%ProcedureTemplate)
    #CREATE(%Application & '.$$$')
    #EXPORT(%Procedure)
    #CLOSE(%Application & '.$$$')
    #OPEN(%Application & '.$$$'),READ
    #LOOP
      #READ(%ASCIIFileRecord)
      #IF(%ASCIIFileRecord = %EOF OR %ASCIIFileRecord = '[END]')
        #BREAK
      #ELSIF(%ASCIIFileRecord = '[EMBED]')
        #FREE(%InstanceQueue)
        #INSERT(%GetSection,%False)
      #ENDIF
    #ENDLOOP
    #CLOSE(%Application & '.$$$'),READ
  #RESUME
#ENDFOR
#CLOSE
#REMOVE(%Application & '.$$$')
#!=================================
#GROUP(%GetSection,%AddToEmbedTree)
#READ(%ASCIIFileRecord)
#!SET(%ASCIIFileRecord,SUB(%ASCIIFileRecord,7|
      ,LEN(%ASCIIFileRecord)-6))
#ADD(%InstanceQueue,%ASCIIFileRecord)
#INSERT(%LoopSections,%AddToEmbedTree)
#!=================================
#GROUP(%GetDefinitionSection)
#LOOP
  #READ(%ASCIIFileRecord)
  #CASE(%ASCIIFileRecord)
  #OF('[END]')
    #BREAK
  #OF('[SOURCE]')
  #OROF('[PROCEDURE]')
  #OROF('[GROUP]')
    #!==========The following code should print the embed instance
    #SET(%InstancePrefix,'')
    #FOR(%InstanceQueue)
  %InstancePrefix %InstanceQueue
      #SET(%InstancePrefix,%InstancePrefix & ' ')
    #ENDFOR
#!---------------------------------
  #ENDCASE
  #!YYY: %ASCIIFileRecord
#ENDLOOP
#!=================================
#GROUP(%LoopSections,%DeleteInstance)
#LOOP
  #READ(%ASCIIFileRecord)
  #IF(%ASCIIFileRecord = %EOF)
    #BREAK
  #ENDIF
  #CASE(%ASCIIFileRecord)
  #OF('[END]')
    #IF(%DeleteInstance AND ITEMS(%InstanceQueue) >= 1)
      #DELETE(%InstanceQueue,ITEMS(%InstanceQueue))
    #ENDIF
    #BREAK
  #OF('[INSTANCES]')
    #INSERT(%GetSection,%True)
  #OF('[DEFINITION]')
    #INSERT(%GetDefinitionSection)
  #ELSE
    #IF(SUB(%ASCIIFileRecord,1,6) = 'EMBED ')
      #IF(ITEMS(%InstanceQueue) >= 1)
        #DELETE(%InstanceQueue,ITEMS(%InstanceQueue))
      #ENDIF
      #ADD(%InstanceQueue,%ASCIIFileRecord)
      #SET(%DeleteInstance,%False)
    #ELSIF(SUB(%ASCIIFileRecord,1,5) = 'WHEN ')
      #IF(ITEMS(%InstanceQueue) >= 1)
        #DELETE(%InstanceQueue,ITEMS(%InstanceQueue))
      #ENDIF
      #ADD(%InstanceQueue,%ASCIIFileRecord)
      #SET(%DeleteInstance,%True)
    #ENDIF
  #ENDCASE
#ENDLOOP
#!

Comments on the template

Register this template as you would any template.

It should work both in the ABC family and the Clarion family.

To run the template do the following:

Open an App file. For our example I've chosen the personel.app from the examples subdirectory of Clarion4.

From the menu Application, select Template Utility

From the Select Utility screen, select PrintEmbedPoints from the Class EmbedPoints.

Press Select

A default file name will appear with the format of appname.EPT. Normally you can just press OK.

Your embed points are exported to a file.

You will need to do this for each app file you want to track.

The EmbedMgr Program

Normally you would unzip the embedmgr program into a directory of your choice and put an appropriate icon somewhere convenient. Let me walk you through running the program. When the program initially comes up it looks like this:

From the menu select Browse/Systems

Press the button Import EPT File

A screen comes up which allows you to enter the name of a file.

If you choose to press '...' you get a file lookup screen. Still following the Personel example, it would look like this.

Select the appropriate name and press OK. We now have the EPT file selected.

The information is imported for the EPT file. The screen looks like the following:

I followed the above procedure for two additional programs in the examples subdirectory: Clubmanager, and Invoice. Once these systems had been imported, the screen looked like this for ClubManager

It looked like this for Invoice

And it looked like this for Personel

When I closed this screen, selected browse/unique embed points, my screen looked like this:

If I highlight one embed point and select change, I get a screen where I can indicate that conversion is OK as is, or Needs Modifications. I can also input notes for C4 conversions into the program.

An abbreviated report sample looks like the following:

Comments

This template and program are designed to provide general guidelines for what happens at an embed point. Some embed points have several 'times' they are called. For example, in the above example, ControlEventHandling includes a time (WHEN) of Accepted, Drag, and Drop. Each of these is treated as a discrete entity in this system.

Note that the particular embeded code is not included. This could change from one system to the next depending on what is being used.

Codes in the report are really part of the next version, so they can be ignored in this one. As mentioned before, this system is in a state of change. Suggestions are welcome.

Conclusion

We now have a way to manage our total set of embed points. This can be managed like any other part of the toolset we manage in developing systems.

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