Template Files
Template files are text files which define some piece of generic source code. They contain a combination of actual source code and 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 action. Some tokens cause some piece of information obtained from the metadata source to be written to the output file, while other tokens cause CodeGen to perform some specific action.
A simple template named 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 metadata, 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
You can override these default output file 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 Metadata
Template files which do not require a source of metadata are rare, because it is difficult to generate anything useful without a source of metadata! Most templates are written to create output based on a source of metadata, which is usually a repository structure.
Most of the useful metadata 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 metadata, 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 metadata 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, which us usually in this location:
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/SteveIves/CodeGen/tree/master/SampleTemplates.
Copyright © 2018 Synergex International, Inc.