User defined functions allow to expand the Proteus language by adding new functionalities; when defined inside a program file (or added by using the !include directive), they can be used exactly in the same way as the library functions.

The UDFs can return any value: strings, integer and floating point numbers. UDF names follow the same rules valid for identifiers.

The method FUNCTION is used to define a UDF, according to the following syntax:

FUNCTION MyFunc([@]par1[,[@]par2[,[@]par3 ..]])
  [methods..]
RETURN [expr]

Every UDF can have 0 or more parameters, that get the values passed at the moment of the call. It is possible to access "external" variables by using the function PUB (or the prefix "_") and set their values by using PSET. Parameters can also be passed by explicit or implicit reference.

PUB takes the name of an identifier (literal, not inside double quotes) as its only parameter; this expression has the same meaning as using the identifier alone outside the function. PUB, just like PSET, should appear only inside UDFs.

All identifiers appearing inside a function are local and not visible from outside; they do not keep their values between function calls.

It is possible to specify more than one RETURN inside a function definition, even returning different data types (e.g. strings and numbers); the first RETURN outside conditional structures and loops terminates the definition.

E.g.

FUNCTION MyFact(n) 
  IF LT(n, 1)
    ; This RETURN does not ent definition, because inside IF
    RETURN 1
  FI
  ; This RETURN terminates the definition
RETURN MUL(n, MyFact(DEC(n))) 

Two special UDFs are ONSTART and ONEND; these functions, when defined, are invoked once before running the program (ONSTART) and once at the end, before exiting (ONEND, only invoked if ABORT is not used). They don't have any parameter, but regarding all other aspects they are standard UDF. In these UDFs the variables are usually set with PSET and read with PUB, because ONSTART is used most of the times to initialize counters and ONEND to print results.

It is forbidden to use the method IGNORE inside a function.

A UDF can be referenced before its definition, on condition that it is defined before the end of the script.

As a consequence, UDFs can also be recursive.

Proteus signals an error in the following cases:

• a function is defined twice;
• a function is called with a number of parameters which is different to the one specified in another call or in the definition;
• the script tries to define a UDF inside another.

Every function must end returning a value; if the return value is not significative, it can be omitted - Proteus defaults to "" (= 0 = 0.0); e.g.:

RETURN

is the same as:

RETURN ""

This example shows how to simulate a matrix using arrays by defining five UDFs:

FUNCTION MatNew(row, col) 
  ; Create a matrix (row by col)
  hmat = VECNEW(row)
  FOR r = 1 TO row
    VECSET(hmat, r, VECNEW(col))
  NEXT
RETURN hmat

FUNCTION MatLen(hmat) 
; Return the number of items in the matrix (row x col)
RETURN MUL(VECLEN(hmat), VECLEN(VECGET(hmat, 1)))

FUNCTION MatGet(hmat, row, col) 
; Return the item (row, col) in hmat
RETURN VECGET(VECGET(hmat, row), col)

FUNCTION MatSet(hmat, row, col, val) 
; Set the item (row, col) in hmat
RETURN VECSET(VECGET(hmat, row), col, val)

FUNCTION MatFree(hmat) 
  ; Free the memory reserved for the matrix hmat
  limit = VECLEN(hmat)
  FOR row = 1 TO limit
    VECFREE(VECGET(hmat, row))
  NEXT
RETURN VECFREE(hmat) 

As you can see, it is very easy to create multi-dimensional matrices; an advantage of this technique is the possibility of creating a matrix with rows of different lengths; besides, every item can be a string or a number (integer/floating point).