Please enable JavaScript to view this site.

 

Navigation: Macros > Macro Language > Instructions

User-Defined Functions

Scroll Prev Up Next More

In addition to being able to use built-in functions, the macro language allows you to define your own functions.

 

 

Functions are declared at the top of macros, just after the compiler directives section (if present), or at the very top of the macro, if the macro has no compiler directives section.

 

If you declare a function before the compiler directives section, then a compiler error will be generated on the line of the first compiler directive.

 

Function Prototype

 

The first line of a function declaration is the function prototype.

 

A function prototype begins with the function keyword followed by the function name, then by its list of parameters in parentheses, and finally by its type.

Function Name

 

Function names can be any combination of the letters a to z and A to Z (no spaces). You do not need to preface your function name with s, b, or n to indicate that it is a string, boolean or integer function.

 

Function Parameters

function ChangeNumbertoText(nSomeDate): s // converts nSomeDate to text 
function CompareNumbers(nValue1 nValue2): b // true if nValue1 > nValue2

Function parameters consist of one or more, or zero, variable names separated by spaces, in parentheses, as shown above, each name following the usual variables naming rules.

function IsDiaryYearLeap(): b // uses system variable n_ScriptYear
function UpperCaseSResult(): s // uses macro variable sResult
function DeleteTextbox() // void function deletes box

If there are no parameters, the parentheses are still there, but empty. Some of the reasons why a function might not have any parameters, as shown above, are.

 

The function uses a system variable and therefore does not need to be fed a parameter.

The function uses one of the variables declared in the main body of the macro, to which it has full access, without the need to pass that value as parameter.

The function performs an action regardless of any variable's value.

 

The variable names in the function parameter string must be unique, as compared to the variables declared in the main body of the macro (the global, input and var sections) otherwise a compiler error will be generated.

 

However, the same variable can be defined in the list of parameters of more than one function, as each function is unaware of the functions of any other function.

 

Function Type

 

The function's result type is indicated by a colon followed by either s, b, or n to indicate that it is a string, boolean or integer function (in the case of a void function, nothing follows the list of parameters).

function ChangeNumbertoText(nSomeDate): s // string function 
function CompareNumbers(nValue1 nValue2): b // boolean function
function NextYear(nSomeDate): n // integer/date function
function DeletePage(nPageNumber) // void function deletes box

Note that the type of the parameters and the type of the function are totally unrelated.

 

Function Variables

 

User-defined functions can, optionally, define their own variables, as shown below.

function ZodiacNameOfDate(nSomeDate): s
var
   nIndex sBuffer // variables only accessible by this function
begin
   nIndex = MoonZodiacSignOf(nSomeDate,0,true,1)
   sBuffer = ZodiacName(nIndex)
   return sBuffer
end

Variables, defined in the var section of a user-defined function, are only accessible from within that function.

 

These variable names must be unique, as compared to the variables declared in the main body of the macro (the global, input and var sections) otherwise a compiler error will be generated.

 

However, the same variable name can be defined in more than one function, as each function is unaware of the functions of any other function.

 

Function Instruction Block

 

The instruction block of a function, delimited by the begin and end keywords, works in the same manner as the macro's main instructions block. In particular, in addition to having access to all of the function's variables, it also has access to all of the variables declared in the main body of the macro (the global, input and var sections).

 

Return Instruction

 

Each function, except void functions, must have a return instruction, followed by a variable or expression of the type of the function. The return instruction must be the last instruction of the function.

 

See also: calling built-in functions.