RETURN        Return from a called script file or function

Top  Previous  Next

Syntax:

RETURN

[ retcode ]

Arguments:

[ retcode ]

Optional Variable or numeric value specifying a function return code (valid only within a function body).

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.

 

The following is an example of using the IFERROR script command to test for a function return code equal to 1.

 

FUNCTION MyFunction

;; body of MyFunction

RETURN 1

ENDFUNCTION

 

;; call the function

MyFunction

IFERROR= 1 GOTO function_ok

 

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

See also: Using Functions