return

Stops the current handler and returns a value to the handler that call the current handler.

# Metadata

Platforms: desktop, server, mobile OS: mac, windows, linux, ios, android Introduced: 1.0 Changed:8.1.0 Security:

# Syntax

return value [ for { value | error } ]

# Params

- value : The value to return to the calling handler.

# Examples

function simpleFunction return 1 end simpleFunction on testSimpleFunction local tVar put simpleFunction() into tVar -- tVar contains 1, the result contains 1 end testSimpleFunction

function simpleFunction return 1 for value end simpleFunction on testSimpleFunction local tVar put simpleFunction() into tVar -- tVar contains 1, the result contains empty end testSimpleFunction

function simpleFunction return 1 for error end simpleFunction on testSimpleFunction local tVar put simpleFunction() into tVar -- tVar contains empty, the result contains 1 end testSimpleFunction

command simpleCommand return 1 end simpleCommand on testSimpleCommand simpleCommand -- the result contains 1 end testSimpleCommand

command simpleCommand return 1 for value end simpleCommand on testSimpleCommand simpleCommand -- it contains 1, the result contains empty end testSimpleCommand

command simpleCommand return 1 for error end simpleCommand on testSimpleCommand simpleCommand -- it contains empty, the result contains 1 end testSimpleCommand

# Description

Use the return control structure to return a value from a custom function or getProp handler, or to return an error message from a message handler or setProp handler.

**Form:** The return statement appears on a line by itself, anywhere inside a handler.

When the return control structure is execute, any remaining statements in the handler are skipped. Hence, the return control structure is usually used either at the end of a handler or within an if control structure.

The plain form of the return control structure always sets the result to value. Additionally, if it is used within a function or getProp handler then value is passed to the calling handler as the return value of the function, or value of the property.

The value form of the return control structure always sets the result to empty. If it is used within a command or message handler then the it variable in the calling handler will be set to value. If it is used within a function handler, then value is passed to the calling handler as the return value of the function, or value of the property.

The error form of the return control structure sets the result to value. If it is used within a command or message handler, then the it variable in the calling handler will be set to empty. If it is used within a function handler, then the return value of the function or the value of the property is returned as empty.

*Note:* The value and error forms can only be used within message, command and function handlers - not getProp or setProp handlers.

When a message handler executes a return statement, the message stops and is not pass to the next object in the message path. To halt the current message handler and pass the message on through the message path, use the pass control structure instead. To halt the current handler without returning a value, use the exit control structure instead.

The value and error forms of the return command allow much easier scripting of the distinction between a return value of a handler call, and an error return value of a handler call. If a command or function handler succeeds, then the 'return for value' form should be used to return the result of the execution to the calling handler. If a command or function handler fails, then the 'return for error' form should be used to return an error status to the calling handler.

Any callers of handlers using the new error and value forms of the return command can uniformly check the result is empty to determine if the operation succeeded, and if it did then either it or the return value can be processed to continue operation.

>*Note:* The return control structure is implemented internally as a command and appears in the commandNames.

# Tags

# See

- **control structure:** setProp, getProp, throw, if, pass, exit, on, function - **glossary:** object, message handler, call, property, pass, execute, command, control structure, message path, caller, message, statement, handler, return - **function:** result, commandNames, value, merge