Template Files
Template files are text files which define some piece of generic source code. They contain a combination of actual source code and special tokens that have special meaning to CodeGen. Template files have a .tpl file extension. When CodeGen processes a template file, any tokens that are encountered in the template cause it to take some specific action. Most tokens cause a piece of information obtained from the meta-data source to be written to the output file. Some special tokens cause CodeGen to perform other actions.
A simple template called HelloWorld.tpl might contain:
;;;; Description: A Synergy function that returns "Hello World"
;;
;; Author: <AUTHOR>
;;
;; Created: <DATE> at <TIME>
;;
function HelloWorld, a
endparams
proc
freturn "Hello World"
endfunction
This template is so simple that it does not require an external source of meta-data, as no tokens relating to any specific data structure are being used. The template contains three tokens, <AUTHOR>, <DATE> and <TIME>. You can probably guess what these tokens do:
1.The <AUTHOR> token will be replaced by the name of the person using CodeGen.
2.The <DATE> token will be replaced by the current date, in MM/DD/YYYY format.
3.The <TIME> token will be replaced by the current time, in HH:MM format.
If this template were processed by CodeGen an output file would be created and would contain containing something like:
;;
;; Description: A Synergy function that returns "Hello World"
;;
;; Author: Jodah Veloper
;;
;; Created: 03/11/2010 at 11:23
;;
function HelloWorld, a
endparams
proc
freturn "Hello World"
endfunction
Default Output File Names
The name of the output file created by CodeGen would be helloworld.dbl. This is because CodeGen has default rules for the naming of output files. If no repository structure is being used then the default output file name is the base name of the template being used, with a file extension of .dbl, in lowercase:
<template>.dbl
If a repository structure is being used then the default output file name is the name of the repository structure, followed by an underscore, followed by the base name of the template, with a file extension of .dbl, all in lowercase:
<structure>_<template>.dbl
Customizing Output File Names
Template developers can override these default naming rules by adding a special <CODEGEN_FILENAME> token to the template file which defines rules for naming the output file to be created. For example the template file could be updated like this:
<CODEGEN_FILENAME>HelloWorldFunction.dbl</CODEGEN_FILENAME>
;;
;; Description: A Synergy function that returns "Hello World"
;;
;; Author: <AUTHOR>
;;
;; Created: <DATE> at <TIME>
;;
function HelloWorld, a
endparams
proc
freturn "Hello World"
endfunction
If the template was then reprocessed the name of the output file would be changed to HelloWorldFunction.dbl.
The content of the output file would be exactly the same as in the earlier example, because the <CODEGEN_FILENAME> token is a special instruction to CodeGen and does not cause anything to be sent to the output file.
Template File Comments
Template files can contain special comments which can be used to document the template file, but which are also not sent to the output file. A template file comment is any text which follows the special sequence of characters ;//. For example, the template file could be updated like this:
<CODEGEN_FILENAME>HelloWorldFunction.dbl</CODEGEN_FILENAME>
;//--------------------------------------------------------
;// Template author: Jodah Veloper
;// Revision: 1.0
;// Date: 03/11/2010
;//--------------------------------------------------------
;;
;; Description: A Synergy function that returns "Hello World"
;;
;; Author: <AUTHOR>
;;
;; Created: <DATE> at <TIME>
;;
function HelloWorld, a
endparams
proc
freturn "Hello World"
endfunction
Using Repository Meta-Data
Template files which do not require a source of meta-data are rare, because it is difficult to generate anything useful without a source of meta-data! Most templates are written to create output based on a source of meta-data, which is usually a repository structure.
Most of the useful meta-data is found in repository structure and field definitions, but some tokens require you to define keys, tags, relations and files in the repository also. For more information, refer to Repository Setup.
For a simple example of how a repository structure can be used as a source of meta-data, consider the following hypothetical structure definition
STRUCTURE DEPARTMENT
DEPT_ID ,A10 ;Department ID (primary key)
DEPT_NAME ,A30 ;Department name
DEPT_MANAGER ,D4 ;Managers employee ID
ENDSTRUCTURE
If a programmer wanted to create a template for a Synergy external subroutine which would accept the value of the primary key for a record and then read and returned the record, they could write a template like this:
<CODEGEN_FILENAME>Get<StructureName>.dbl</CODEGEN_FILENAME>
;//<CATEGORY>Synergy Subroutines</CATEGORY>
;//<DESCRIPTION>Creates a subroutine that returns a record from a file</DESCRIPTION>
;//--------------------------------------------------------
;// Template author: Jodah Veloper
;// Revision: 1.0
;// Date: 03/11/2010
;//--------------------------------------------------------
;;
;; Description: Returns a <STRUCTURE_NAME> record
;;
;; Author: <AUTHOR>
;;
;; Created: <DATE> at <TIME>
;;
.include “<STRUCTURE_NAME>” repository, structure=”str<StructureName>”, end
subroutine Get<StructureName>
<PRIMARY_KEY>
<SEGMENT_LOOP>
required in a<SegmentName>, <segment_spec>
</SEGMENT_LOOP>
</PRIMARY_KEY>
required out a<StructureName>, str<StructureName>
endparams
stack record
ch<StructureName> ,int
endrecord
proc
<PRIMARY_KEY>
<SEGMENT_LOOP>
a<StructureName>.<segment_name> = a<SegmentName>
</SEGMENT_LOOP>
</PRIMARY_KEY>
try
begin
open(ch<StructureName>=syn_freechn(),i:i,”<FILE_NAME>”)
read(ch<StructureName>,a<StructureName>,keyval(ch<StructureName>,a<StructureName>,0))
end
catch (ex)
begin
clear a<StructureName>
end
finally
begin
if (chopen(ch<StructureName>))
close ch<StructureName>
end
endtry
xreturn
endsubroutine
Having created the template, the developer could then process the template in conjunction with the repository structure DEPARTMENT, and CodeGen would create an output file like the one below. Notice that the template file includes a <CODEGEN_FILENAME> rule, so in this case the name of the output file would be GetDepartment.dbl. The file would contain:
;;
;; Description: Returns a DEPARTMENT record
;;
;; Author: Jodah Veloper
;;
;; Created: 11/28/2014 at 12:00
;;
.include "DEPARTMENT" repository, structure="strDepartment", end
subroutine GetDepartment
required in aDeptId, a10
required out aDepartment, strDepartment
endparams
stack record
chDepartment ,int
endrecord
proc
aDepartment.dept_id = aDeptId
try
begin
open(chDepartment=syn_freechn(),i:i,”DAT:department.ism”)
read(chDepartment,aDepartment,keyval(chDepartment,aDepartment,0))
end
catch (ex)
begin
clear aDepartment
end
finally
begin
if (chopen(chDepartment))
close chDepartment
end
endtry
xreturn
endsubroutine
Notice how all of the tokens that were present in the original template have been replaced by meaningful pieces of information from the meta-data source, resulting in a useful piece of source code. We could just as easily use the same template to create a routine to read an employee record, or a location record, or a customer record. The idea is to define the rules in a template once, then use that template to generate many routines.
Sample Templates
CodeGen ships with a collection of sample template files. that are intended to provide you with examples of some of the types of output files that you can create with CodeGen, but you may be able to use some of the templates unaltered.
Having installed CodeGen you will find the sample templates in the Public Documents folder (C:\Users\Public\Documents\CodeGenTemplates).
You can also use the Template Browser utility to view the sample templates.
The sample templates may also be viewed directly on the GitHub web site at https://github.com/Synergex/CodeGen/tree/master/SampleTemplates.
Copyright © 2012 Synergex International, Inc.