Purpose:Create, modify or display user-defined variable functions


Format:Display mode:

FUNCTION [/G /L /P] [wildname]


Direct definition mode:

FUNCTION [/G /L] name[=]definition


Definition file mode:

FUNCTION [/G /L /O] /R [/Z] [file...]


fileOne or more input files to read function definitions from.
wildnameName of function whose definition is to be displayed (may contain * and ? wildcards)
nameThe name of the function you want to define.
definitionThe value or definition of what the function should return.


/G(lobal)/R(ead file)
/L(ocal)/Z (overwrite list)



See also: UNFUNCTION and ESET.




Onestep        Overview

Onestep        Displaying Functions

Onestep        Defining Functions

Onestep        Deleting Functions

Onestep        Local and Global Functions

Onestep        Saving and Reloading Your Functions

Onestep        Warnings




FUNCTION allows you to create or display user-defined variable functions that can be used anywhere Variable Functions can be used. User-defined functions are powerful alternatives to subroutines.


Displaying Functions


If you invoke the FUNCTION command with no parameters, it will display the current function list (the local function list if you have set local functions in TCMD.INI or the TCC startup command line; otherwise the global function list):




If you include a wildname, which may include wildcards (* or ?), with no equal sign and no definition, FUNCTION will display the current values, if any, of all functions matching wildname, .e.g.:


function *dx*


will display all functions which contain dx in their name.


You can use the /P option to control display scrolling when displaying functions.


Defining Functions


If you include the equal sign and definition, FUNCTION will create or update the function referred to by name. Any previous definition associated with name is discarded. Instead of the = sign, you may use one or more spaces or tab characters to separate name and definition.


Once a function is defined, the definition may be edited using ESET /F.


A function can optionally use references to parameters numbered from %0 to %511 which will be replaced with the matching parameter value when the function is called. %0 refers to the function name, %1 to the first parameter, etc. For example, the function


function leftmost=`%@left[1,%1]`


will return the leftmost character in its parameter, e.g. %@leftmost[xyz] will return x.


The parameter %n$ has a special meaning. TCC interprets it to mean "all arguments, from parameter n to the end."  If n is not specified, it has a default value of 1, so %$ means "all arguments passed to the function."


The parameter %-n$ means "the arguments from parameter 1 to n - 1".


The special variable reference %# expands to the number of parameters passed to the function.


A function definition need not reference any parameters at all. For example:


function tomorrow=`%@makedate[%@inc[%@date[%_date]]]`


could be simply invoked as %@tomorrow[].


To use the function name you invoke is as %@name[parameters],where you must specify enough parameters to assign a value to the highest numbered parameter referenced in the function definition. It may have more parameters, which will be silently ignored.


The Colors, Color Names and Codes topic shows a simple example of the use of a function in a batch file.


Deleting Functions


The normal method is to use the UNFUNCTION command. However, it is also possible to delete a function by redefining it without a definition, e.g., the command


 function fs=


deletes the function fs.


Local and Global Functions


Functions can be stored in either a local or global list.


With a local function list, any changes made to the functions will only affect the current copy of TCC. They will not be visible in other shells or other sessions.


With a global function list, all copies of TCC will share the same function list, and any changes made to the functions in one copy will affect all other copies. This is the default in TCC.


You can control the type of function list with the Local Functions configuration option, with the /L and /LF options of the START command, and with the /L and /LF startup options.


There is no fixed rule for determining whether to use a local or global function list. Depending on your work style, you may find it most convenient to use one type, or a mixture of types in different sessions or shells. We recommend that you start with the default approach, then modify it if you find a situation where the default is not convenient.


Whenever you start a second copy of TCC which uses a local function list, it inherits a copy of the functions from the previous shell. However, any changes to the functions made in the second shell will affect only that shell. If you want changes made in the second shell to affect the previous shell, use a global function list in both shells.


Saving and Reloading Your Functions


You can save your functions to a file (e.g., FUNCTIONS.LST) this way:


function > function.lst


You can then reload all the function definitions in the file the next time you start up with the command:


function /r function.lst


This is much faster than defining each function individually in a batch file. If you keep your function definitions in a separate file which you load when TCC starts, you can edit them with a text editor, reload the edited file with FUNCTION /R, and know that the same function list will be loaded the next time you start TCC.


When you define functions in a file that will be processed by the FUNCTION /R command, you do not need back quotes around definition, even if back quotes would normally be required when defining the same function at the command line or in a batch file.




When you define a function in the command line (i.e., without using the /R option), variables and functions not protected by back quotes or doubled % signs are immediately evaluated, and the result becomes part of the function definition.


Syntax errors in a function definition are not detected until it is used.




/GSwitch from a local to a global function list.


/LSwitch from a global to a local function list.


/ODon't overwrite existing values (only valid in combination with /R).


/PWait for a key to be pressed after each screen page before continuing the display.


/RThis option loads a list of functions from a file. If no filename is specified and input is redirected, /R will read from stdin. The format of the file is the same as that of the FUNCTION display:




where name is the name of the function and definition specifies how to determine its value. You may use the equal sign = or whitespace to separate name and definition. Back-quotes are not required.


You can add comments to the file by starting each comment line with a colon :.


You can load multiple files with one FUNCTION /R command by placing the names on the command line, separated by  spaces:


function /r func1.lst func2.lst


FUNCTION /R definitions can span multiple lines in the file if each line, except the last, is terminated with an Escape Character.


If there is no filename parameter and input is redirected, FUNCTION /R will read from stdin.


/ZOverwrite the existing function list with the contents of the specified file (must be used with /R). FUNCTION /R /Z is 20x faster than FUNCTION /R, because it doesn't have to check for existing functions and append new functions to the end of the list.