CALL Execute script file and return |
Top Previous Next |
Use of this script command temporarily transfers control to another script file. Unlike the CHAIN command, when the called script file exits, control returns to the original script file at the statement immediately following the CALL statement. Any changes made to the Robo-FTP environment in a called script will persist after returning to the original calling script. For example, if the working folder is changed the change will remain in effect upon the return; and if a user-defined script variable named count is set to the value "5" in the called script there will be a variable with the same name and value available to the original script after the called script returns. It helps if you view called scripts as extensions to the original script rather than a separate environment.
The following is an example of calling a script file and of the script file being called.
CALL "called_script.s"
Then the end of the called script file might contain the following:
DASHBOARDMSG "Now leaving called_script.s"
Values may be passed to a called script using the double ampersand syntax. Any strings found between two ampersand delimiters (ie &value&) are saved in sequence in internal variables named %1 through %9 which are then accessible within the called script. The following example passes two values to the called script:
CALL "called_script.s" &arg1& &arg2&
When the called script is running, it will find %1 = “arg1” and %2 = “arg2”. Since the variables %1 through %9 behave just like those passed into Robo-FTP via command line arguments it is possible to develop a single command script that could be executed either by an external process or via a CALL from another Robo-FTP script. The variables %1 through %9 go out of scope (are undefined) when the called script returns so attempting to use them back in the original calling script will cause an error. Use a regular variable if you need to pass values from the called script back to the calling script.
It is also possible to create local user-defined variables in a called script by using the /argnames option to specify a name/value pair between two ampersand delimiters. The following example creates three such variables in the called script:
CALL "called_script.s" /argnames &addr=ftp.mydomain.com& &usr=robo& &pw=secret&
When the called script is running, it will find addr = “ftp.mydomain.com” and usr = “robo” and pw = "secret". These internal variables go out of scope when the called script returns unless their value is changed by the called script.
A variable may be passed as the "value" portion of a name/value pair passed via the /argnames option. In the following example, the variable upload will be populated with the value of the variable source, unless there is no variable named source in which case it will be populated with the string "source":
CALL "called_script.s" /argnames &upload=source&
Note: It not often necessary or even desirable to pass values in this way because variables set in the original script will retain their value in the chained script.
Warning: If the WORKINGDIR command is used in the called script, we recommend that the current working folder be saved into a variable on entry and restored on exit to prevent unintended consequences. See the help topic for the %currentlocaldir internal variable for an example.
Related command(s): CHAIN, EXEC, RETURN See also: Passing External Values Into Command Scripts, Alternate Default Path |