The Discus Template Language includes the ability to define and utilize subroutines to minimize the amount of repetitive code that must appear within a template. It is also possible to call directly a subroutine from within the Discus program, including its output within the template.

Subroutines are defined as follows:

<#define sub subroutine_name($var1,$var2,...)#>
  Code here
<#end sub#>

The subroutine_name must be entirely alphanumeric. Each variable ($var1, $var2 and so on) must be alphanumeric as well, except for the initial $. When a subroutine is called, the first argument will be put into $var1, the second into $var2, and so on. You can use any alphanumeric names for the variables if you wish.

The subroutine's "return value" will be any text that is printed as the subroutine is executed. If your code produces the text "hello" then wherever the subroutine is called within the template, the text "hello" will appear.

A defined subroutine is called as follows:

<#&subroutine_name(arg1,arg2,...)#>

The following is the definition and subsequent calling of a subroutine:

<#define sub plus($num1,$num2)#>
  <#mathdefine: $answer="SUM($num1,$num2)"#>
  $answer
<#end sub#>

Plus 2,3 = <#&plus(2,3)#>
<#define $text = "<#&plus(5,5)#>"#>
Text = $text

Plus 2,3 = 5
Text = 10

It is possible to call directly a subroutine within the Discus program and insert the result into a template. This should be used with caution and only by those who are very familiar with the structure and code employed by Discus. Otherwise, odd results may occur!

<#program sub "required_file" &subroutine_name(arg1,arg2,...)#>

The text above reads in the subroutine file required_file (if provided) and then executes the Discus program subroutine subroutine_name, supplying the arguments to the subroutine as you supply them in the template. The return value of the subroutine is inserted into the template.

Note that required_file must be the name of the file within the "source" directory that contains the subroutine to be executed. Drop the directory path and the final ".pl". If the file is found in the PRO_########## subdirectory, add the text "-PRO" after the name of the subroutine file. Examples of file names can be found in many "dreq" statements throughout the Discus programming.

Here is a real-world example of how a Discus program subroutine is called:

<#program sub "" &tree_icon_chooser($subtopic->{icon}, $subtopic->{param}, $subtopic->{islink}, 0)#>

In this case, there is no required file, since the subroutine is found in the "common.pl" file which is always read in. The tree icon chooser subroutine in that file is executed, with several parameters relating to the subtopic under consideration.

Subroutines are used extensively in the "admtree.tmpl" template file within the "ui" template subdirectory. This file generates complex code to prepare a proper tree view for the visitor. Subroutines are used to ensure that the icons selected are proper, so that the tree view output looks just like a Windows Explorer representation of the topic and subtopic structure.