Robo-FTP User's Guide > Script Programming > Script Commands > All Script Commands > CALL

Syntax:	CALL	[ file name ] \| [ /options ]
Arguments:	[ file name ]	Variable or string defining a file or path name; if no path is defined the alternate default path is searched for a matching file; if no matching file is found Robo-FTP searches for the file in the folder of the calling script.
Options:	/argnames &name=value&	Input arguments passed as name/value pairs. A variable with this name and value will be available to the logic of the called script. These variables go out of scope (become undefined) when the called script returns unless their values are changed by the called script.
	/silent	Do not echo script commands or results to log file or Robo-FTP window.
	&value&	Up to nine unnamed values may be passed to the called script in the same manner that they may be passed from the command line into Robo-FTP when it is launched; the first argument is saved in script variable %1, the second in %2, etc. up to %9. These variables always go out of scope (become undefined) when the called script returns.
	/waitifrunning=xx	Do not begin processing the script if the same exact script file is already running in another instance of Robo-FTP. Possible values are abort, continue, infinite or a number of seconds to wait for the previous instance to complete.

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"

RETURN

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.

Use /waitifrunning to prevent the simultaneous execution of the script specified in the file name argument. The following example will not begin processing the automation script if another instance of Robo-FTP is currently running the same script and that other script was also launched using either the /waitifrunning option or the -r command line switch.

CALL "called_script.s" /waitifrunning=abort

In the following example the CALL command times out if the same script is running in another instance and it does not complete within 30 seconds.

CALL "called_script.s" /waitifrunning=30

When the /waitifrunning=continue option is used, the script is run immediately without checking for previous instances.

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