Robo-FTP User's Guide > Script Programming > Script Commands > All Script Commands > RETURN - Return from a called script file or function

Syntax:	RETURN	[ retcode ]
Arguments:	[ retcode ]	Optional Variable or numeric value specifying a function return code (valid only within a function body).
	[ lasterrormsg ]	Optional Variable or string specifying message to store in built-in %lasterrormsg variable
Options:	None

This script command is used to exit from a called script file or from a function, and resume script execution at the next command from the point of the call.

If the RETURN command appears in either a script that was not called from another script, or in a script that was chained from another script then its behavior is identical to the STOP script command and, like the STOP command, will cause the program to terminate in certain situations. Please consult the help topic about the STOP command for details.

Use of the RETURN command is not always required. For example, it is not required in the following case.

BEGINFUNCTIONS

FUNCTION MyFunction

;; body of MyFunction

RETURN

ENDFUNCTION

ENDFUNCTIONS

When there are no more script commands in a function to execute, the RETURN command is assumed as shown below.

BEGINFUNCTIONS

FUNCTION MyFunction

;; body of MyFunction

ENDFUNCTION

ENDFUNCTIONS

This also applies to called script files. At the end of file of a called script file, a RETURN is assumed.

When used to return from a function, an optional parameter permits there to be a return code from the function. The returned value may be tested using any of the IFERROR script commands and is saved in the %lasterror script variable. The return code must be numeric and the default value is zero or $ERROR_SUCCESS. A second optional parameter permits the function to return a human-readable error message that will be saved in the %lasterrormsg script variable.

The following is an example of using the IFERROR script command to test for a function return code equal to 1. If this error is found, the script displays the human-readable error message.

FUNCTION MyFunction

;; body of MyFunction

RETURN 1 "This is the human readable error message."

ENDFUNCTION

;; call the function

MyFunction

IFERROR= 1 GOTO function_ok

EXIT

:function_ok

DISPLAY %lasterrormsg

In complicated called script files or functions, multiple return points may be desired. For example, the RETURN command is used to provide alternate points of exit in the rather silly function below:

BEGINFUNCTIONS

FUNCTION MyFunction afile

:top

RCVFILE afile

IFERROR= $ERROR_SUCCESS GOTO success

;; return on error

RETURN

:success

MESSAGEBOX "a file received"

ASK "Receive again?" "Question"

IFYES GOTO top

;; user clicked 'No'

RETURN

ENDFUNCTION

ENDFUNCTIONS

Related command(s): CALL, FUNCTION, ENDFUNCTION, BEGINFUNCTIONS, ENDFUNCTIONS, STOP, EXIT