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/Synergex/CodeGen/tree/master/SampleTemplates.