Robo-FTP User's Guide > Script Programming

User-defined functions are a handy way to re-use a sequence of commands that may otherwise be repeated in a script file. Like functions or subroutines in other programming environments, Robo-FTP script file functions make script development easier and results in more easily read and maintained scripts.

A script may define up to 256 unique functions. Functions may call other functions and may call themselves recursively but the nesting depth of embedded functions is limited to 512 calls. If the nesting depth exceeds 512 then the function call fails and error $ERROR_FUNCS_NOT_RECURSIVE is returned.

Functions must be declared before they can be used. Robo-FTP provides two script directives to create what is referred to as a function declaration section within a script file. This section must be at the top of the script file.

;; an example function declaration section

BEGINFUNCTIONS

;; function(s) are defined here

ENDFUNCTIONS

Functions are defined within the function declaration section in the following manner.

;; an example function

FUNCTION MyFunction

;; function body is here

ENDFUNCTION

Putting it all together.

;; an example function declaration section

BEGINFUNCTIONS

;; function(s) are defined here

;; an example function

FUNCTION MyFunction

;; function body is here

ENDFUNCTION

ENDFUNCTIONS

There can be multiple functions.

;; an example function declaration section

BEGINFUNCTIONS

;; function(s) are defined here

;; example function #1

FUNCTION MyFunction1

;; function body is here

ENDFUNCTION

;; example function #2

FUNCTION MyFunction2

;; function body is here

ENDFUNCTION

ENDFUNCTIONS

Calling a function is accomplished by simply using the function name as a command in the script file. The following calls the two functions declared above.

;; call my functions

MyFunction1

MyFunction2

Up to 32 arguments may be passed to a function. The function must be declared showing the arguments and then called with the corresponding number of arguments.

;; an example function with two arguments

FUNCTION MyFunction arg1 arg2

;; function body is here

ENDFUNCTION

;; calling the function with two arguments

MyFunction "a" "b"

;; calling the function passing a variable as an argument

SET var = "I am an argument"

MyFunction var "b"

Because functions are global, they are accessible from the main script and any scripts that are invoked with CALL or CHAIN script commands. It is possible to define functions in one script file and then call those functions when running other script file(s).

Function arguments are local to a single call of a function unless they have the same name as a pre-existing variable. Any other variable modified or created inside a function is global in scope. In the script below, the first function argument has the same name as a pre-existing variable so it may be used both inside and outside the function:

;; declare our function

BEGINFUNCTIONS

FUNCTION MyFunction arg1 arg2

DISPLAY arg1

DISPLAY arg2

SET var1 = "hello" ;; creates variable named var1

ENDFUNCTION

ENDFUNCTIONS

;; script execution begin here

SET arg1 = "a" ;; creates variable named arg1

MyFunction arg1 "b"

DISPLAY arg1

DISPLAY arg2 ;; this line will cause an error

DISPLAY var1

STOP

All of the previous examples show a single return point from a function. Specifically, all of the preceding functions return when there are no more command(s) in the function to perform. Multiple return points are possible in more complex scripts by using the RETURN script command which returns script execution to the command immediately after the function call.

;; declare our function

BEGINFUNCTIONS

FUNCTION MyFunction arg1

;; complicated operations

GOTO more

RETURN

:more

;; more complicated operations

RETURN

ENDFUNCTION

ENDFUNCTIONS

The RETURN statement is not always required. In the preceding function, the second RETURN statement is redundant because the ENDFUNCTION directive is recognized as the end of the function so the RETURN command is implied. The script could be written as shown below:

;; declare our function

BEGINFUNCTIONS

FUNCTION MyFunction arg1

;; complicated operations

GOTO more

RETURN

:more

;; more complicated operations

ENDFUNCTION

ENDFUNCTIONS

Finally, the RETURN statement allows for a numeric return code to be passed back. Upon return to the calling script, the return code may be tested using the IFERROR script commands and is saved in the %lasterror variable. The following example shows how different return points from a function may be indicated to the calling script.

;; declare our function

BEGINFUNCTIONS

FUNCTION MyFunction arg1

;; complicated operations

GOTO more

RETURN $ERROR_INVALID_FILE_NAME

:more

;; more complicated operations

RETURN $ERROR_FTP_CONNECT_FAILURE

ENDFUNCTION

ENDFUNCTIONS

Testing a return code would look something like this.

;; call my functions

MyFunction1

IFERROR= $ERROR_INVALID_FILE_NAME GOTO from_Return1

IFERROR= $ERROR_FTP_CONNECT_FAILURE GOTO from_Return2

Related command(s): FUNCTION, ENDFUNCTION, BEGINFUNCTIONS, ENDFUNCTIONS, RETURN