Active Templates - library modules on steroids

Active Templates are an extremely powerful way of providing a library of re-usable code modules for various functions. Active Templates can embody a great deal of specialist knowledge and math. You get to use that simply by adjusting some settings.

Automatic code generation

Configure setting to suit your needs

Built in expertise. All the hard work is done for you

In brief

An Active Template is a special kind of program that runs in your PC. It is dedicated to a particular function, say temperature measurement. It has the file extension .tp1 ("tee pee one"). Once you have installed the Active Template support package you can run a template in your PC by double clicking it. When you run the template you can adjust a number of setting to adapt it to your needs. The template then automatically generates the exact SPLat code required to implement the function according to your settings. When you save the template your settings get saved inside the template file. You can also launch a template from inside SPLat/PC using the menu File>Edit Template.

What you need

To use Active Templates you need:

• SPLat/PC 8.20.1 or later. Download
• The Active Template support package. This allows templates to be run standalone and also contains all the runtime support files. Download
• An active template to suit your needs. Download.

The Active Template system includes the ability to automatically check online for updates, and invite you to download newer versions of templates and the support package. You may from time to time update the support package if we write a template that requires support files that are not in existing releases.

When you download an Active Template file (*.tp1) you can simply save it alongside your SPLat program source files. The file name is used in the generated code as part of the subroutine names that you need to call to use the template. If you run a template, change its name field and save it, you will get a new tp1 file with the changed name.

Integrating into your program, overview

Active Templates are not stand-alone programs. They are software components that provide some specialized functionality. An Active Template no more generates a complete program than a timer relay is a complete control panel. To make use of a template you need to incorporate it into a larger program.

You can incorporate a template into your program by referring to it in a Builder file. Builder knows how to open a template, use your settings inside it to generate the correct SPLat code and then use the Builder tags to dovetail it into your SPLat program.

If you don't want to use Builder you can simply copy and paste the code generated by the template from the template screen directly into your program. Just follow the directions given in the comments in the generated code itself. This may seem quicker and easier initially, but it is harder to maintain. If you change one setting in the template you must rip the old code out of your program, possibly in several places, and graft in the new code. With Builder, once the .b1d file is set up it can be run any number of times on a click of your mouse.

Before trying to integrate an Active Template into your program, you need to understand what the template generated code needs to work. For example:

• Some templates may contain one or more tasks that need to run under MultiTrack. Such templates will require a GoSub to their initialization subroutine before they will work. They will also need a RunTasksForever instruction in the startup code of your program.
• Templates that allow your program to use Xwire peripherals will contain code to initialize Xwire and will require a GoSub to their initialization subroutine before they will work.
• Some templates will generate and use data stored in NVEM, typically a lookup table.
• Some templates give you a choice of how you select between several channels of something, say 4 temperature inputs. For this you need to understand the choices and pick one that suits your needs.
• You must communicate between your code and the template code using appropriate GoSubs.

All the information on feeding and caring for a template is provided in the header comment in the generated code and in the template's documentation here in the SPLat Knowledge Base. There you will find the subroutine names to use in your GoSubs and information on how data is passed (in which registers etc).

Integrating into your program using Builder

Using Builder with templates is initially the more complicated way but it pays off in very much easier ongoing program maintenance.

1. Read up on Builder. Without understanding Builder you will be lost.
2. Study the documentation on the particular template you are using.
3. Install the Active Template support package. This allows templates to be run standalone and also contains all the runtime support files. Download
4. Place a copy of the template in the same folder as your main SPLat program.
5. Rename it to something that suits your application. Keep it short, no more than 8 letters. Be very sure not to change the file extension. Let's say you call it mytmplt.tp1
6. Double-click the renamed copy. If you have successfully installed the Active Template support package, the template screen will come up.
7. Adjust the template settings to suit your needs. Make sure the Builder button is down.
8. Click the Save button. It will be saved with the same file name but with the new settings. (if you change the Name field the template will be saved with that new name).
9. Study the header comment on the generated code (in the code window of the template). You may find it useful to copy it into NotePad for more convenient viewing. Make most careful note of the Builder tags and subroutine names.
10. Exit the template.
11. Start a new SPLat file, say myprog.spt. In that file write the code that will use the template-generated code. Use Builder tags to distinguish initialization code segment, main program code segment, any NVEM0 segment(s), etc. Use segment names consistent with the template generated ones and the standard segment names documented under Builder. Save the file.
12. Create a Builder file (you can use NotePad or the SPLat/PC editor). It should name, in appropriate order, the various segments from myprog.spt and mytmplt.tp1., then is should list those two files (in either order). Save it as, say, mybld.b1d in the same folder as your other files.
13. Make sure you have a SPLat/PC that supports Active Templates, V8.20.1 or later. Download
14. Close all files.
15. Double-click the mybld.b1d file. This should launch SPLat/PC. You will be asked if you want to include trace information. Click Yes. If you have done everything correctly you will get an information box and then see the merged file in the SPLat/PC editor.
16. Study the trace comments left by the build process. They start well over to the right of the screen.

Encapsulation/data hiding

All access from your program to the template must be via GoSub subroutine calls. Any data gets passed on the register stack (X, Y etc) or floating point registers W and/or Q. You cannot directly access any of the RAM data stored within the template generated code.

This is called encapsulation or data hiding (the two terms tend to be used interchangeably). It means that the code generated by the template is a "black box" module that can only be accessed via its "interface", i.e. the subroutines that are there to allow you access. What goes on inside is private to the module.

All other labels within the code generated by the template include a random hex number that will change every time the template is run, specifically to "hide" them from your code.