Simply Clarion - Documenting ABC Embed Points - Part 1 - -#AT

by Don Reynolds

Published 1998-07-01    Printer-friendly version

Download the code here

Scenario

You have designed but not coded a super template which will make your programming life much easier or make you rich and famous. As part of this template set you will have Control, Code and Extension templates, among others. As you get into these templates you find you will need the #AT command to indicate where the template generated code will be inserted into the source stream.

But finding the #AT embed point proves sometimes to be elusive.

What is the #AT statement

The #AT statement is structured as follows

#AT (location[,instances])[,WHERE(expression)][,AUTO][,PRESERVE]|
    [,PRIORITY(number)][,FIRST][,LAST]
    Your statements
#ENDAT

• location = a valid location (#EMBED identifier) within a #CONTROL, #CODE, or #EXTENSION template. For the ABC templates, this must correspond to an existing #EMBED location. (Yes, you must find out what this is.)

  instances = A specific instance of a multi-valued #EMBED identifier. There may be many parameters which are delimited by commas. Some or all of these may (must) be omitted. (Yes, you must find out which to omit also.)

  WHERE(expression) = Further restricts embed location to only those places where the expression is true.

  AUTO = Generates a new scope for the #AT; restricts #DECLARE statements.

  PRESERVE = Preserves current fixed instances of built-in multi-valued symbols when the #AT is called and restores them when the #AT terminates.

  PRIORITY(number) = Priority number assigned to this code insertion. Number must be in range 1 to 10000.

  FIRST = Equivalent to Priority(1).

  LAST = Equivalent to Priority(10000).

  Your Statements = The template code you write.

  #ENDAT = Terminates the section (Required).

  (See the Clarion 4 Programmer's Guide for more information on this command.)

Finding the #AT statement - initial tries

Because you have carefully read the Clarion 4 Programmer's guide, you know you can create a basic template like the following:

#TEMPLATE(TemplateHelper,'Helps for building templates'),FAMILY('ABC')
#CODE(ShowEmbedPoint,'Show this embed point')
#DISPLAY('Show me the Id and Parameters for this embed point')
#DISPLAY('')
#DISPLAY('Search keyword = SHOW')
#DISPLAY('')
#DISPLAY('There are no prompts for this template')
!SHOW this embed point parameters
! Embed point Id = %EmbedId
! Embed point parameters = %EmbedParameters
!-------End of ShowEmbedPoint--------------

After registering the template use it in the following way. Select a procedure (L_Fish) you want to work with. Press Properties.

The properties window appears for the selected procedure.

Press Embeds.

You may need to use the Expand All, Expand Filled, Contract All buttons, or expand the '+' folders to get to the right place. The "right place" is, of course, the place you want to put the embed code in your template. In this case the "right place" is highlighted. Press Insert. A list of possible templates available to embed at this point appears. Because you have registered your template you can highlight as follows:

Press Select. The prompts appear for this template:

Press OK. Filled embeds for this procedure now look like this:

Press Close.

We're back at the L_Fish properties screen. If the Embeds button was not checked before, it now is. Press OK to return to the application tree.

With the procedures highlighted, we right click and press Source to call the Embeditor.

The embeditor window appears with all the code that 'may' be generated. We want to quickly find the location just entered. Select Search/Find

We can now enter something to search for. Because of the way we built the template we choose to search for "Show".

The following appears as the first "match" for the search.

Of course if we had inserted multiple occurrences of our embed, we would Find Next until we arrived at the proper place

From the above information you format your initial #AT statement:

#AT (%WindowManagerMethodCodeSection,'Init, (),BYTE'),PRIORITY(4500)

You use this #AT statement and code wonderful code. When you include it in a program you find that the code is not included. It's as if the #AT statement is not being recognized.

Finding the #AT statement -An iterative process-- Hints for subsequent tries

The parameter indicated by %EmbedId (%WindowManagerMethodCodeSection) is correct.

The %EmbedParameters are causing the problem.

To find the right combination of embed parameters, I start eliminating comma delimited parameters one at a time going from right to left as follows:

Eliminate the ",BYTE".

#AT (%WindowManagerMethodCodeSection,'Init, ()),PRIORITY(4500)

This did not work either. Reduce again by eliminating the ", ()".

#AT(%WindowManagerMethodCodeSection,'Init'),PRIORITY(4500)

And this works. We now have our #AT embed point. We can insert our template code.

Refining the Template

We could refine the template by putting in comments that describe this reducing process. But you could do that yourself. Note that I have put the appropriate priorities in my created #AT statements. One way to get these priorities is to look at the embeditor generated code and select the priority most appropriate to what you want to do.

Hints on building Templates

Before you start building a template, it is wise to create the source you want the template to create and test it out first. Once you have the code in the correct embed points and you know it works, then create a template.

Of course some people who have lots of free time and like challenges may want to debug both the source and the templates at the same time.

Summary

While somewhat elusive, we can find the correct #AT parameters to help build our templates. Once we can identify these correctly there are several additional things we can do, which I'll talk about in part two.

Thanks

To Gus M. Creses for the original idea for this template functionality.

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