|
RETURN Return from a called script file or function |
Top Previous Next |
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.
FUNCTION MyFunction ;; body of MyFunction RETURN
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 See also: Using Functions, Using the %lasterrormsg Variable, Using the %lasterror Variable, Returning Error Codes from Scripts
|