on

Syntax on identifier (idParam1, idParam2, ..., idParamN)

statements
Action Defines a local script named identifier, with parameters idParam1 through idParamN. The body statements are not executed; that occurs only when the script is invoked with a function call, consisting of identifier followed by a list of parameters enclosed

in parentheses.
Examples on lockFiles (folder)
local (fName)

fileloop (fName in folder, infinity)

file.lock (fName)

lockFiles ("HD80:folder1:")
lockFiles ("HD80:folder2:")
Type this script into a script window. This example demonstrates the use of a local script to allow a particular bit of functionality - in this case locking all of the files in a folder - to be reused within a script. The on statement defines the
"lockFiles" local script, which takes a single parameter that is expected to be the path of a folder. Below the script definition are two calls to the script, passing two different folders to be operated on.

on countWindows ()
return (appleEvent (app.id, 'app1', 'twin'))

This is the script for app.countWindows in Frontier.root. In this case, the local script countWindows takes no parameters, and its body is the single return statement that returns the result of an appleEvent call. Since the entire script consists of a
local script definition, running the script will do nothing but define the script; there is no call to countWindows to cause its body statements to be executed. Scripts like these are intended to be called externally, by other scripts. A script that
wishes to execute countWindows must name its database cell in a function call, as in numWindows = app.countWindows ().

Notes The number of parameters defined in the on statement is strict; all calls to the script must provide exactly that number. If the script does not take any parameters, an empty parameter list - () - must be provided in both its definition and any calls to

it.

The scope of a script defined with the on statement is generally the same as that of local variables, lasting the rest of the statement block that contains it. However, if the script is the first local script in a script object, and its name matches

that of the database cell that contains it, then scripts elsewhere in the database can call it by naming the database cell (and providing the appropriate parameter list).

The on statement's parameter list defines the local script's name and the name of each parameter it requires. There is no specification made of what type of values are expected for each parameter, and thus there is no type validity checking when the

script is called. If a parameter is provided whose type is inappropriate for a statement in the script body, an error will occur when executing that statement.

If a script is intended to be callable from other scripts, it is important that its name match that of the database cell containing it. If the name does not match, the script will be assumed to be local to the implementation of the database script. The

on statement will be executed as a definition, with the expectation that a call to it will appear subsequently in the body of the database script.

Local scripts are database objects, just like other scripts that you work with in tables. As such, you can take their address with the address operator, and use that address in any context where the address of a script is called for.
See Also @

( )

bundle

local

return

Discuss