|
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 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 ;; 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 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
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 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 |