21.1 Targeting Scriptable Applications

To target a scriptable application is to aim Apple events at it, like arrows. This section catalogues the various ways to do it.

21.1.1 Tell and Of

The primary linguistic device for targeting an application in AppleScript is the tell block containing an application specifier. This actually has two purposes: it determines the target, if no other target is specified within the block, and it also causes a dictionary to be loaded, which may be used in the resolution of terminology. Instead of a tell block, the of operator (or its equivalents) can be used to form a target; this does not affect resolution of terminology.

(See Section 10.2 and Section 10.2.4; Section 12.3 and Section 12.4; Section 13.9; and Section 19.1.)

21.1.2 Reference

A reference to an object belonging to an application can be used to target that application. The terminology within the reference has already been resolved (otherwise the reference could not have been formed in the first place); any further terminology prefixed to the reference when you actually use it will have to be resolved independently. (See Chapter 11.)

21.1.3 Local Applications

A local application is an application on the same computer as the script. The specifier for a local application may consist of a full pathname string (colon-delimited) or simply the name of the application; the name should usually be sufficient. AppleScript builds into a compiled script enough information about the application that if the compiled script is moved to a different machine containing the same application, AppleScript on that machine will usually be able to find it. (But this mechanism does sometimes go wrong; see Section 4.5.) If AppleScript can't find a local application when compiling, decompiling, or running a script, it will put up a dialog asking the user to locate it.

(See Section 4.4.3 and Section 19.1.1.)

21.1.4 Remote Applications

A remote application is an application running on a different computer from the script. Communication is performed over IP (not AppleTalk, as in the past); this has the advantage that it works over the Internet, but it also means that even locally the remote machine needs an IP number (or a Rendezvous name). On the remote computer, Remote Apple Events must first be turned on; this can be done in the Sharing preference pane.

To the application specifier you append a machine specifier that uses an eppc URL. In Panther, the machine specifier can be just a Rendezvous name; in that case, AppleScript will supply the eppc:// prefix and the .local suffix on compilation. Connection requires a username and password; these will be requested in a dialog when the connection is first established, or you can avoid the dialog by means of username:password@ syntax in the URL. A terms block referring to a local application may be needed in order to resolve terminology at compile time (see Section 12.4).

This example lets the user select the remote machine, supplies the username and password, and talks to the Finder on the remote machine. A terms block is needed because the machine is specified dynamically:

set u to choose URL showing Remote applications
set L to characters 8 thru -1 of u
set u to "eppc://mattneub:teehee@" & (L as string)
-- u is now e.g. "eppc://mattneub:teehee@169.254.168.138:3031/"
tell application "Finder" of machine u
        using terms from application "Finder"
                get name of disk 1
        end using terms from
end tell

As long as you're targeting an application on the remote machine, scripting addition commands you call are run on the remote machine. For example:

tell application "Finder" of machine "eppc://little-white-duck.local"
        say "Watson, come here, I want you."
end tell

When communicating with a remote machine, be careful with aliases. An alias is not a useful medium of communication between machines, because it will be resolved on the wrong machine. For example, don't ask the remote Finder for an alias list, and if you use the path to scripting addition command, ask for a string instead of an alias. For example:

tell application "Finder" of machine "eppc://little-white-duck.local"
        path to system folder as string
end tell

An even more devious variant of the same trick appears in the next example.

A remote application must already be running before you target it; you cannot target it and then launch it, as you can on a local machine. However, you can open an application from the remote Finder and then target it. If a tell block targets a literal application specifier for a remote application that isn't running, your script won't compile; so the trick is to put the name of the application in a variable, thus preventing AppleScript from trying to resolve the tell block until the script runs. By the time the tell block is executed, the application will be running. So, for example:

set m to "eppc://mattneub:teehee@little-white-duck.local"
tell application "Finder" of machine m
        set s to (run script "path to app \"System Events.app\" as string")
        open item s
end tell
set se to "System Events"
tell application se of machine m
        using terms from application "System Events"
                get every process
        end using terms from
end tell

21.1.5 XML-RPC and SOAP

XML-RPC and SOAP are web services allowing commands in a generalized form to be sent over the Internet by means of the http protocol, using a POST argument that contains XML structured according to certain conventions. This is clever because any CGI-capable web server can act as an XML-RPC server. The request is an ordinary POST request, and the server just passes it along to the appropriate CGI application, which pulls the XML out of the POST argument, parses it, does whatever it's supposed to do, and hands back the reply as a web page consisting of XML.

AppleScript can target XML-RPC and SOAP services through support built into the Apple Event Manager. The syntax is comparable to driving any scriptable application. You target the server by means of its URL, using a tell block. Within the tell block, you use either the call xmlrpc command or the call soap command; these terms are resolved only when the target is an http URL. Behind the scenes, the System acts as a web client: your command is translated into XML, the XML is shoved into the POST argument of an http request, the request is sent across the Internet, the reply comes back, the System extracts and interprets the XML from the reply, and this interpretation is returned as the result of the command.

The target can be expressed in this form:

tell application "http://www.xxx.com/someApplication"

or you can say this, which decompiles to the previous syntax:

tell application "someApplication" of machine "http://www.xxx.com"

The syntax for call xmlrpc is as follows:

call xmlrpc {method name: methodName, parameters: parameterList}

The syntax for call soap is as follows:

call soap {method name: methodName, ¬
        method namespace uri: uri, ¬
        parameters: parameterRecord, ¬
        SOAPAction: action}

You can omit an item of the record (such as method namespace uri or parameters) if it isn't applicable.

Now let's test these commands. There's a copy of UserLand Frontier on the Internet that is intended for users to test with XML-RPC and SOAP requests. By default, we access this server's XML-RPC functionality through a URL whose path is /rpc2. The server includes some simple test verbs, one of which is examples.getStateName. We can call this verb using AppleScript, as follows:

tell application "http://superhonker.userland.com/rpc2"
        call xmlrpc ¬
                {method name:"examples.getStateName", ¬
                parameters:30} -- "New Jersey"
end tell

Frontier is also a SOAP server. We can call the SOAP equivalent of the same verb using AppleScript, as follows:

tell application "http://superhonker.userland.com"
        call soap ¬
                {method name:"getStateName", ¬
                SOAPAction:"/examples", ¬
                parameters:{statenum:30}} -- "New Jersey"
end tell

If you happen to have a copy of Frontier or Radio UserLand, you can test all this on your own machine, without using the Internet. These programs run the very same server on port 8080. So with Frontier or Radio UserLand running, you can substitute "http://localhost:8080/rpc2" and "http://localhost:8080" as the application URLs for the tell block.

For further examples of call soap, see Section 1.6 and Section 12.4. In general, call xmlrpc and call soap are not difficult to use; you'll just have to study the documentation for the service you're trying to call, and it may take a little trial and error to get the parameters just right.