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

Syntax:	CHAIN	[ file name ] \| [ /options ]
Arguments:	[ file name ]	Variable or string defining a file or path name; if no path is defined the default path is searched for a matching file.
Options:	&arg&	Up to nine arguments may be passed to the chained 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.
	/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 transfers control to another script file. Unlike the CALL command, control does not return to the original script file when execution of the chained script is complete. Any changes made to the Robo-FTP environment in the original calling script will persist in the chained script. For example, if the working folder is changed in the original script then the chained script will also use that same folder rather than the default working folder; and if a user-defined script variable named count is set to the value "5" in the original script there will be a variable with the same name and value in the chained script. It helps if you view chained scripts as a appendage to the bottom of the original script, not as a separate environment.

Note: It is possible to simulate a separate environment by using the SET command by itself with no arguments to unassign all current user-defined script variables but this does not reset the values of internal variables. Consider using the EXEC command with the -s command line switch to launch another instance of Robo-FTP if you require a separate pristine environment.

Arguments 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 chained to script. The following example passes two arguments.

CHAIN "called_script.s" &arg1& &arg2&

When the new script is running, it will find %1 = “arg1” and %2 = “arg2”.

Note: It not often necessary or even desirable to pass arguments in this way because variables set in the original script will retain their value in the chained script.

Consider the following example where a variable named which_one has been previously populated with a value used to determine which of two script files are to be executed.

IFSTRCMP which_one "its2" GOTO chain_to2

DASHBOARDMSG "Launching script1.s"

CHAIN "script1.s"

:chain to2

DASHBOARDMSG "Launching script2.s"

CHAIN "script2.s"

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.

CHAIN "script1.s" /waitifrunning=abort

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

CHAIN "script1.s" /waitifrunning=30

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

Related command(s): CALL, EXEC