|
Using Functions |
Top Previous Next |
|
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 but the nesting depth of embedded functions is limited to 32 calls. Functions may not be called recursively (i.e., a function cannot call itself).
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. It must also be in the main script which is to say a function declaration section cannot be in a script that is invoked by way of a CALL script command.
;; an example function declaration section ;; function(s) are defined here
Functions are defined within the function declaration section in the following manner.
;; an example function FUNCTION MyFunction ;; function body is here
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 nine 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
;; how to call the function with two arguments 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. They are also persistent which is to say they remain defined after a script terminates. It is possible to define functions in one script file and then call those functions when running other script file(s).
All variables in the Robo-FTP script environment are global. Any variables that are created in association with function arguments are also global. This is demonstrated with the following script where both DISPLAY commands show the same value "a".
;; declare our function BEGINFUNCTIONS FUNCTION MyFunction arg1 DISPLAY arg1 ENDFUNCTION ENDFUNCTIONS ;; script execution begin here MyFunction "a" DISPLAY arg1
Pay close attention to variables used in a script and make certain that uniquely named variables are used whenever appropriate.
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 :more
;; more complicated operations RETURN ENDFUNCTION ENDFUNCTIONS
The RETURN statement is not always required. In the preceding function, the second RETURN statement is redundant. 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
In this case, the ENDFUNCTION directive is recognized as the end of the MyFunction function so the RETURN command is implied.
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 1 :more ;; more complicated operations RETURN 2 ENDFUNCTION ENDFUNCTIONS
Testing a return code would look something like this.
;; call my functions MyFunction1 IFERROR= 1 GOTO from_Return1 IFERROR= 2 GOTO from_Return2
|