There are two types of functions that can be called from TE programs:

a) TE language functions (function declared in a func..endfunc block).

b) External DLL functions.

There are very few differences between calling these two types of function and the calling syntax is the same.    Both type of functions return string values.       However there are a few differences that should be noted:

i) Some DLL functions can take a variable number of parameters whereas TE functions can only take a fixed number of parameters.

ii) DLL functions can result in the calling task becoming suspended (i.e the calling task will block until the calling libary wakes the task up at which point the function will return).

iii) A maximum of 32 arguments can be passed to a DLL function, whereas for a TE language function there is no limit to the number of arguments that can be passed to a function (except for a limit imposed by the stack depth or stack size which might be exceeded if not big enough to handle all of the function parameters).  

For example the CXTERMX.DLL library has functions for displaying information to a terminal console and for accepting input from the keyboard.      Some of these functions accept a variable number of parameters.    For example the applog() function which displays a message to the terminal screen (and writes the message to the application log) can take any number of parameters between 1 and 16.     Each of the parameters passed is concatenated together to make the final message string.  For example the following two calls would display the same message:

applog("This is a string");

applog("This"," is ","a string");

This allows the values of  variable to be easily displayed:

a=3;

b=34;

applog("a=",a," b=",b);

The kb_get() function provided by the CXTERMX.DLL library is an example of a function that causes the calling task to be suspended.         A call to kb_get() will not return control to the task until a key has been pressed on the keyboard (i.e. the function will block).     Of course this only blocks the calling task, all other tasks running on the Telecom Engine will continue to process commands( unless they are also in blocking functions):

var ch:1;

ch=kb_get();    // this will ‘block’ until a key is pressed

applog("Got key=",ch);

As mentioned in the discussion about indirection operators, arguments are passed to functions by value which means that a copy of the original value is pushed onto the program stack which can then be referenced by the function.    It is illegal to try and alter the value of an argument to a function:

func f(arg)

    arg=2;    // illegal

endfunc

If you wish to alter the value of a variable inside a function then a pointer to that variable should be passed rather than the value itself and the dereference operator should then be used inside the function.      It is advisable to indicate in the name the arguments of a function that it will be a pointer (e.g. by prefixing ptr_ or _p_ or something similar)

main

var str:127;

   f(&str);   // Pass pointer to variable

endmain

func f(_p_arg)

    * _p_arg= "New value"

endfunc

To return from a TE language function the return_statement can be used which can take one of two forms:

return ;

or

return expr ;

A return on its own will return the empty string “” as the result of the function, otherwise the value of the expr will be returned if one is given.      If the endfunc statement is reached before encountering an explicit return statement then the empty string “” will be returned by the function.

TE language functions can be declared inside the main .TES source file, or else they can be declared in a separate .FUN source file where the name of this source file is the same as the function itself.      For example a function called myfunction() would be declared in a .FUN file called myfunction.fun.

Also TE language functions can be merged into a TEL library file and linked into the main application by using the –L option with the TCL compiler (See TCL compiler reference).