AppleScript 1.3.2 and 1.3.4 (Mac OS 8.5 and 8.5.1)

DOCUMENTATION FOR NEW APPLESCRIPT FEATURES
The following sources of information about AppleScript 1.3 are available, many of them as part of the standard Mac OS 8.5 installation:

Apple Help files in the Mac OS Help and AppleScript Help subfolders of the Help folder in the System Folder. These help files are fully indexed and searchable, and they are readily available via the Help menu in the menubar. They are very helpful on basic AppleScript usage, including how to use the Script Editor. They include many example scripts. An installer for updated and corrected AppleScript Help files, fixing errors and omissions in the original Mac OS 8.5 and 8.5.1 installation, is available on the official Apple AppleScript web site.

Mac OS 8.5 Scripting Overview is a growing online source of official information about the new AppleScript features in Mac OS 8.5 and 8.5.1.

About AppleScript, the readme file provided with the Script Editor and automated scripts in the AppleScript subfolder of the Apple Extras folder after installing Mac OS 8.5.

About Mac OS 8.5, the readme file provided in the Mac OS Read Me Files folder after installing Mac OS 8.5, contains a very brief note about AppleScript.

OT 2.0 ReadMe - Part 1, in the Mac OS Read Me Files folder after installing Mac OS 8.5, briefly notes that all Open Transport facilities are now scriptable.

About Plaintalk 1.5, which is installed if you elect to install speech recognition, has a lot of information about changes in speech recognition in Mac OS 8.5, including information about the new scripts installed in the Speakable Items folder.

Remote Access Read Me, in the Mac OS Read Me Files folder after installing Mac OS 8.5, briefly notes that ARA 3.0 is scriptable.

Sample scripts are scattered throughout after installation of Mac OS 8.5, including many sample scripts located here and there in the Help subfolder in the System Folder, the Automated Tasks and More Automated Tasks subfolders in the AppleScript folder, the Folder Action Scripts subfolder of the Scripts folder in the System Folder, the AppleScript Files subfolder in the ColorSync Extras folder, the Speakable Items subfolder in the Apple Menu Items folder and the More Speakable Items subfolder in the Speech Technology folder (if you elected to install speech recognition), the Sample AppleScripts folder in the Remote Access 3.1 folder, and the Script Menu Items subfolder in the Outlook Express 4.0 Folder. Additional scripts can be found on the CD which are not installed automatically.

Tech Info Library article #26165 confirms that the applet memory leak is the only AppleScript fix in Mac OS 8.5.1. Other Tech Info Library articles on specific AppleScript features of Mac OS 8.5 and 8.5.1 are linked below in connection with the discussion of each feature.

Apple’s Tech Info Library article Mac OS 8.5: AppleScript 1.3 Features lists and briefly describes some of the new AppleScript features, and AppleScript 1.3: New Scriptable Components lists some of the new scriptable components.

AppleScript for the Internet: Visual QuickStart Guide, written by Ethan Wilde and published by Peachpit Press, is the only third-party book that explains features of AppleScript 1.3 in Mac OS 8.5. Despite its focus on internet scripting techniques, it contains a wealth of information about AppleScript in general.

Apple Technote 1142 on Mac OS 8.5 contains some developer-oriented information about AppleScript 1.3, including a list of new features in the Finder’s AppleScript support and scripting support provided in various control panels.

The AppleScript 1.3.4 SDK includes sample code, documentation, Apple event registry information and other developer goodies never before seen, including a list of bugs fixed and material relating to the new Mac OS 8.5 AppleScript-savvy system components. It is available online as individually downloadable files and as a single, very large download but, according to reports, it will not be released on its own CD. It will be included in a monthly developer CD to be available shortly. It includes full source code for the Folder Actions faceless background application, as well as sample code for Scripting Additions and other AppleScript features. It includes documentation for Folder Actions, the Internet Suite, Macintosh Connectivity Classes, Network Setup Scripting, OSAX, Unicode, Pascal and C Strings, and Units. It includes these new terminology registry items: AEUserTerminology.r, InternetSuite.r and Mac OS 8.5 Registry. The Mac OS 8.5 Registry is a FileMaker Pro database with terminology resource information for a full Mac OS 8.5 install. It includes an aevt dcmd for macsbug. Most of the samples are updated to work with modern development environments.

The Mattman published his own Mac OS 8.5 AppleScript Migration Guide. 10/10/99

TESTING WHETHER APPLESCRIPT 1.3 IS INSTALLED

Before using new features of AppleScript, careful writers of scripts intended for public distribution will want to determine which version of AppleScript is present on the user’s machine. For the last few releases of the Mac OS (namely, all those which include the scriptable Finder), a good way to do this is to use the Finder’s ‘computer’ command. For the technically minded, this command provides access to the operating system’s gestalt function, which can be used to determine the presence and version of all manner of system resources. For a comprehensive list of gestalt selectors, browse Gestalt Selectors List 4.4. 10/13/99

The following script returns an integer indicating which version of AppleScript is installed:


tell application "Finder" to get computer ascv

The following values correspond to the publicly-released versions of AppleScript (hexadecimal values are shown in parentheses for those who are interested):

AS 1.0 = 16809984
(01008000) AS 1.1 = 17826064
(01100110) AS 1.1.2 = 17826066
(01100112) AS 1.3.2 = 17826098
(01100132) AS 1.3.4 = 17826100
(01100134)

The following script fragment can be used to verify that AppleScript 1.3.2 or newer is present.


tell application "Finder" 
	if computer ascv is greater than or < equal to 17826098
	then  --your script statements   
		else --report an error   
	end if
end tell

For the sake of completeness, note that the following script returns true if AppleScript is installed. However, this gestalt selector is not useful when called from an AppleScript; it will never return false because it won’t run if AppleScript is not installed.


tell application "Finder" 
	to get computer ascr has 0

The following script returns true if AppleScript PowerPC support is installed. I don’t know whether this means anything in AppleScript 1.3.x under Mac OS 8.5, which is all PowerPC code, in any event.


tell application "Finder" 
	to get computer ascr has 1

APPLESCRIPT-RELATED SYSTEM SOFTWARE COMPONENTS
Appearance control panel application

The Appearance control panel application combines the features of the old Desktop Pictures control panel with the new Mac OS 8.5 themes capability. Although Apple has not released any alternative themes, three that were once intended for public release are floating around in a state of questionable legality. Collections of desktop patterns and pictures are provided with the system software, and many third-party sources are available. Many third-party Mac OS 8.5 sound sets are also available. All of these features can be controlled from AppleScript. Basically, every feature of the Apperance control panel is represented as a property of class application, class theme or class monitor. Themes can be switched on the fly using AppleScript. You can also perform many other tasks relating to the appearance of your desktop, such as removing a desktop picture from a secondary monitor using this simple script.


tell application "Appearance"   
	if monitor 2 exists then
    	set picture file of monitor 2 to no picture
	end if
end tell

Note that the Appearance control panel implements a straightforward method for determining how many monitors are attached to a given system.

In early beta releases of Mac OS 8.5, the Options tab of the Appearance control panel allowed users to control the placement of scroll bar arrows in windows independently of the setting of proportional thumbs or scroll boxes, and also to place double arrows at both ends of scroll bars. When Mac OS 8.5 was released, some of this flexibility was removed. The terminology resource was also revised to eliminate these features from the public AppleScript interface. However, the code was left in the control panel, and raw Apple events can be sent to it to set these features. The following script places double arrows at both ends of scroll bars (the double chevrons are generated by typing option-backslash and shift-option-backslash):


tell application "Appearance"
	set scroll bar arrow style to <<constant ****dubl>>
end tell

Many enterprising scripters and programmers have released utilities that use this hidden capability to provide a simple desktop interface that restores the Appearance control panel’s original flexibility. Mitch Crane’s DubDub Scrollbars is an example.

The Mattman has explained the technique in detail: Instead of using the official syntax of:


tell application "Appearance"
   set scroll bar arrow style to both at one end -- or use 'single'
end tell

Use this instead:


tell application "Appearance"
   set scroll bar arrow style to dubl
end tell

NOTE the quotes. The three possible values are:
dubl – both arrows at both ends
sngl – normal; one arrow at each end
next – both at bottom/right.

These settings are also preserved when you save your Theme. Others have noted that <> is apparently the raw code for double arrows. 10/10/99

Kaleidoscope, a shareware product by Gregory D. Landweber, is not scriptable, but many Mac users know and love it as a powerful alternative to Apple’s Appearance control panel. Its penetration of the Macintosh consciousness is so pervasive that even Apple recognizes its influence. Apple’s AppleScript site contains some sample Kaleidoscope scripts for changing Kaleidoscope schemes (analogous to Appearance themes) using the Finder. Just to make them more interesting, they are cast as folder action scripts.

Apple Data Detectors Scripting scripting addition and actions

Apple Data Detectors (ADD) is a technology that was introduced with Mac OS 8. It was described in my report on AppleScript 1.1.2, which also includes links to third-party resources. ADD is not included on the Mac OS 8.5 installation CD, but version 1.0.2 is available for download on Apple’s AppleScript site and works correctly under Mac OS 8.5. (It disappeared from the web site briefly at one point, causing alarm, but promptly reappeared.)

Basically, ADD lets you use contextual menu commands to perform actions on all instances of text within a selection that meet pattern criteria specified by installed detectors. The Apple Data Detectors Extension enables ADD to work in applications that do not directly support the Contextual Menu Manager, such as Apple’s Script Editor. An example of ADD is Internet Address Detectors (IAD), a collection of detectors from Apple which recognize internet addresses beginning with http://, ftp:// and the like. ADD actions are nothing more than AppleScript scripts with special handlers. For example, there is a third-party action to let you use the contextual menu manager to add a nickname to Eudora Pro’s address book by selecting text containing an email address. 10/10/99

To write scripts that work with ADD, you must have the Apple Data Detectors Scripting scripting addition, which supplies some required new terminology. To write custom detectors (which are simple text files), download the Apple Data Detectors SDK, which includes the Detector Editor and a manual. The process is quite simple. I wrote the first version of the AppleScript Terminology detector and some actions for getting help with AppleScript in a weekend.

The Apple Data Detectors control panel application has a scripting dictionary, but it is not in fact scriptable.

Application Switcher

Apple’s recent penchant for making some features of system components available only via AppleScript has led to a deluge of AppleScript-based solutions. The Application Switcher seems to have drawn more attention than others.

Bill Reising has posted three AppleScripts for Mac OS 8.5 only. One is a copy of Apple’s own script to reset the Application Switcher to its default. Another places the Application Switcher where Bill likes it and with his favorite settings. Both are run-only, meaning that you can’t edit them to suit your own preferences, nor even see how he did it.
Raul has posted another set of similar scripts.
Trevor Page of MAX Consulting has written Application Switcher Prefs (formerly Dock Settings), a FaceSpan application which allows Mac users to set all the hidden preferences of the Mac OS 8.5 Application Switcher menu and tear-off palette using a control panel format.
Fraser Speirs posted SwitchBox 1.1, another FaceSpan application for controlling the Mac OS 8.5 Application Switcher. This one is unlike others in that it includes the ability to save sets of settings and switch among them. 10/13/99

Disk Copy application
Apple has posted Disk Image 6.3 scripts, a set of AppleScripts that extend the functionality of Disk Copy 6.3, showing how to use AppleScript to control Disk Copy and to gain access to features not present in the user interface, such as creating a self-mounting image. 10/13/99

Disk Copy is attachable. If you place compiled AppleScripts in a folder named Scripts in the same folder as your Disk Copy 6.1 or later application, they will appear in a Scripts menu in the Disk Copy application. 10/10/99

Folder Actions system extension
The Standard Additions scripting addition now includes several commands for use in folder action scripts. When a script containing these commands is attached to a folder, the script will be run automatically whenever the folder’s window is moved, opened or closed, or items are added to it or removed from it while its window is open. In addition, the Folder Actions system extension is itself scriptable, so that scripts can be attached to or removed from a specified folder under script control. Several sample folder action scripts are included in the Folder Action Scripts subfolder of the Scripts folder in the standard Mac OS 8.5 installation. My shareware Folder Action Setup control panel application uses FaceSpan and AppleScript to create a window-based interface for the Folder Actions extension.

Apple’s AppleScript site includes a QuickTime demonstration of folder actions by Sal Soghoian, and its workflow tutorial is based on folder actions. 10/10/99

Andy Bachorski of Apple has explained how folder actions are implemented: There is a modified alias record pointing to the attached script stored in the icon\r file (the \r is a return character). There can be multiple scripts attached to a folder, so there can be multiple alias records. The folder is marked as having an attached alias via a special ‘badge’ bit in one of the Finder information fields. Brett Gross noted that this makes it easy to lose attached folder actions (or at least their links) accidentally: Mac OS 8.5’s folder actions are stored in the resource fork of the invisible icon file for a folder. There are several utilities (none of which come to mind at this moment) that remove custom icons. It is possible for these utilities to remove a folder action by assuming it is a custom icon. Apple has released a Tech Note telling people to leave the invisible icon file alone. 10/10/99

These other Apple and third-party scripts have been released relating to folder actions:

A folder action script to switch Kaleidoscope schemes automatically when opening or closing a specific folder.

Steve Jones wrote CS Loader, two very clever Mac OS 8.5 folder action scripts. When attached to the Control Strip Modules folder in the System Folder, these scripts implement dynamic loading of control strip modules. When modules are dropped into or removed from the folder, they will automatically be enabled or disabled on the fly. Unfortunately, these scripts are run-only, so you cannot examine the code. (I can no longer find them on his web site; try email.) 10/13/99

Network Setup Scripting application
Network Setup Scripting is a faceless background application (FBA) in the Scripting Additions folder. It provides a scripting interface for creating and manipulating Open Transport (OT) configurations for the five OT control panels: AppleTalk, TCP/IP, Modem, Remote Access and InfraRed (the latter is only for machines supporting infrared communication). It even provides commands to make and break Remote Access connections, although this power is also provided by the Remote Access Commands scripting addition. (Note that the old OT/PPP control panel is replaced by the Remote Access control panel in Mac OS 8.5.)
None of the readme files released with Mac OS 8.5 explains how to use Network Setup Scripting, nor does Apple Help help. However, Apple has provided a basic explanation and a few sample scripts in AppleScript: Using Network Setup Scripting in Mac OS 8.5, Tech Info Library article #30829 (10/10/98). This article explains the general strategy for scripting the OT control panels, and the sample scripts show how to switch configurations in these control panels. A far more detailed explanation appears in the Network Setup Scripting article in the AppleScript 1.3.4 SDK. Additional sample scripts appear in the Sample Scripts folder in the SDK; some of them explain a few quirks which are far from obvious. Chapter 5 of Ethan Wilde’s book, AppleScript for the Internet: Visual QuickStart Guide, also includes several sample scripts, including a script to create a new TCP/IP configuration and a script to enable TCP/IP multi-homing. In general, some things in Network Setup Scripting don’t work as expected, but with a little trial and error you can make it work.

To understand Network Setup Scripting, you must understand the conceptual model of the OT control panels. All of the OT control panels except InfraRed contain a Configurations… item under the File menu, which opens a dialog in which you set applicable features, such as the port to which the modem is connected (in the Modem control panel) or whether AppleTalk is connected via Ethernet or through a particular port (in the AppleTalk control panel). More features become available in the dialog if you select a more advanced mode, using the User Mode… command under the Edit menu. You can create multiple configurations for each control panel, saving each configuration under a user-defined name. You make any one configuration in each control panel the active configuration by selecting a named configuration and clicking the Make Active button in the dialog. Behind the scenes, all of this configuration information is saved in a database. Note that the Location Manager can be used to switch OT configurations for all of the OT control panels, without using AppleScript.

What Network Setup Scripting does, in essence, is to let you use AppleScript to read configuration information from the database, and to change existing configurations or create new configurations and save them to the database. You can also use Network Setup Scripting to make particular configurations active, in effect switching between configurations under script control. You would do this if, for example, you wanted to use an external modem instead of an internal modem, to connect to a different Internet Service Provider, or to use a different configuration for any OT service. You can even create configuration sets, which lump together in one object related configurations and transport options from the OT control panels, to make it easy to switch all of the configuration information for a particular purpose at once as if there were a sort of super-OT control panel combining all of the existing control panels.

Network Setup Scripting implements these features using the object model. The Open Transport Suite defines an abstract ‘configuration’ class, from which each of the following real classes descends, corresponding to the OT control panels: ‘AppleTalk configuration’, ‘Infrared configuration’, ‘modem configuration’, ‘Remote Access configuration’ and ‘TCP/IP v4 configuration’. Each of these classes contains elements and properties corresponding to the features that can be set in the configuration dialog of the corresponding control panel, plus some that are not accessible in the control panels. Each class is described in a suite of the same name. One of the suites, the Remote Access Suite, also contains the ‘connect’ and ‘disconnect’ commands and a ‘Remote Access status’ class for monitoring an active connection. You can specify which Remote Access configuration to use when you connect. The Open Transport Suite also contains an abstract ‘transport options’ class defining properties common to all configurations within any one control panel class, and some of the control panel suites implement descendant classes with special-purpose properties. The ‘transport options’ class includes a property telling you whether a particular change requires reconnecting, restarting the machine or the like. Finally, the Open Transport Suite defines a ‘configuration set’ class and commands to ‘add’ or ‘delete’ configurations and transport options to any configuration set. You cannot define named configuration sets manually using the OT control panels, but only with AppleScript. If you ‘tell application Network Setup Scripting to get every configuration set’ before using AppleScript to create any, it will return ‘configuration set My Network Settings’.

The dictionary also provides a Configuration Database Suite containing commands to access the database, as well as a subset of the Standard Suite to determine whether an object exists, to count objects, to make new objects and other staples of the object model. Before reading from or writing to the database, you must open it, although you can make new objects and manipulate them on the fly without opening the database. You must always close the database when done with it. Opening and closing the database keeps it and the legacy preferences files for the control panels (included for backwards compatibility) sychrnonized; for this reason, you should open and close it quickly to preclude users from making changes in the control panels that would be overwritten when you close the database. Interestingly, Network Setup Scripting implements a little-used feature of AppleScript, the ‘begin transaction’ and ‘end transaction’ commands. Before writing to the database, you must begin a transaction; the changes will not be written to the database until you end the transaction, in order to assure its consistency. Other users cannot write to the database while your transaction is open, so close it quickly. Authentication password protection is also implemented.

Although the examples I have seen do not do so, I find it useful (at least during debugging) to open and close the database in ‘try’ blocks, in order to bypass error number -23 on opening it, if it is already open, and error number -24 on closing it, if it is already closed. If you try to access the database without opening it, or to write to it without starting a transaction, you will receive an error. Apple’s Tech Info Library article points out that it is prudent to enclose all actions taken while a write transaction is pending in a ‘try’ block, and in the ‘on error’ block you should abort the transaction and close the database in order to cancel all attempted changes and restore its status. Network Setup Scripting is a faceless background application, which means that you cannot use the ‘display dialog’ command within a ‘tell application Network Setup Scripting’ block; you must ‘tell application Finder to display dialog’ or redirect the command to some other context. The filter reference form ('whose clauses) is supported, but I have not been able to use it to select objects of a specific configuration class from a configuration set: ‘get configurations of current configuration set whose class is TCPIP v4 configuration’ compiles but does not run. The workaround is to use a repeat loop, as in the example below. Don’t forget to quit the Network Setup Scripting application when you are done with it, in order to reclaim the memory used by its process.

The following script gives an idea of how to obtain information about the current OT configuration set:


tell  application "Network Setup Scripting"   
	try      
		open database   
			on error number -23 -- database already open     
		 --continue   
		end try   
		try      
			set OTConfigSet to current configuration set      
			set OTConfigSetName to name of OTConfigSet      
			set TCPIPConfigName to "" --initialize     
				repeat with x from 1 to count configurations of OTConfigSet         
					set thisConfig to configuration x of OTConfigSet         
						if class of thisConfig is TCPIP v4 configuration then            
							set TCPIPConfigName to name of thisConfig            
							set TCPIPConnectVia to connecting via of thisConfig            
							exit repeat 
						end if 
			end repeat
		close database      
	quit      

tell application "Finder" 
activate
beep     
display dialog ("The current Open Transport configuration set is "") & (OTConfigSetName & "." & return & return) & 
				("Its TCP/IP configuration is " & TCPIPConfigName & "" ") & ("connecting via "  & TCPIPConnectVia & ".")   
           buttons {OK} default button OK with icon note      
end tell   
	on error 
		errText number errNum 
			try         
		close database      
			on error number -24 --database already closed         
			--ignore      
				end try      
			quit      
				tell application "Finder"
	 	        activate
		         beep
		         display dialog (errText & return & return & errNum) buttons {OK} default button OK with icon caution
		end tell   
	end try
end tell

Remote Access Commands scripting addition
In Mac OS 8.5, the former OT/PPP control panel and Remote Access control panel are combined into a single Remote Access control panel which can make both PPP (point-to-point protocol) and ARAP (Apple Remote Access protocol) connections. The scripting interface formerly provided by separate scripting additions for each control panel is now combined into a single Remote Access Commands scripting addition. Because this is a scripting addition, its commands can be used outside of a ‘tell’ block as if they were built into AppleScript itself. Remote Access 3.1 comes with a pdf manual, Remote Access User’s Manual, which includes in Appendix D a description of the provided sample scripts, a command reference and a list of error codes. Chapter 5 of Ethan Wilde’s book, AppleScript for the Internet: Visual QuickStart Guide, also includes several sample Remote Access scripts.

You can do almost everything with the new Network Setup Scripting application (installed by Mac OS 8.5 in the Scripting Additions folder) that you can do with Remote Access Commands, and more. The Remote Access Commands scripting addition can be regarded as present mainly for backwards compatibility with the many legacy PPP and Remote Access connection scripts that are publicly available. However, scripting with Remote Access Commands can be slightly easier, because you do not have to create, verify or specify an Open Transport configuration; the ‘RA connect’ command simply uses the currently active Remote Access configuration, while allowing you to provide whatever optional parameters you want to override the current settings. Also, it appears that Remote Access Commands offers one feature not present in Network Setup Scripting, namely, scripting control over connection logs using the ‘PPP save log’ and ‘RA save log’ commands. But for more complex environments, Network Setup Scripting is preferred because it provides additional facilities, such as control over alternate phone numbers, redialing, use of the DialAssist control panel and turning on the ‘answers calls’ property if you have ARA server installed. Also, of course, Network Setup Scripting provides a common interface not just for Remote Access, but also for Infrared connections, AppleTalk and TCP/IP, and for configuring modems.

Note that Apple Remote Access 3.1 does not update the server component of Apple Remote Access 3.0, and Mac OS 8.5 installs only the client, in any event. It is possible to run ARA 3.0 server under Mac OS 8.5 with ARA 3.1 client, if you follow Apple’s special installation instructions (basically, install the ARA 3.0 server component first, then install ARA 3.1).

Sherlock application
Extending and Controlling Sherlock, Technote 1141, contains an extensive discussion of AppleScript support in Sherlock (it was updated on October 5, 1999, coincident with the announcement of Mac OS 9). Apple has also posted four AppleScripts which enable you to activate, create, delete and edit sets of Sherlock Internet plugins. A comprehensive installation and use tutorial is also online. 10/10/99

FIXED BUGS
According to Technote 1142, the following bugs from AppleSript 1.1.2 have been fixed:

This is only the tip of the iceberg, however. The AppleScript 1.3 Bug Fix History in the AppleScript 1.3.4 SDK lists many, many fixes to bugs we didn’t even know about. 10/10/99

There are, of course, some old bugs that have not been fixed, and new bugs have been introduced.

Per Eric Hellman, these AppleScript bugs from earlier versions of the Mac OS are not fixed in 1.3.2:

32K string comparison gotcha: not fixed. You still can’t compare strings longer than 32K.

Bad soup bug: not fixed. Script applications will still unexpectedly quit if they are targeted with an event while waiting for a reply from another application that has quit. Thus, ACGI’s should never wait for a reply from another application.

Text thru bug: not fixed. Applescript will crash if you use text thru too often or on strings that are too big.

… and these are fixed:

Number of words bug: fixed. If you ask for the number of words in a string that has too many words, an error is now thrown correctly. (You can count more words than you can get the number of, but that’s another story.)

Set owner/group bug: fixed. The finder now lets you set the owner and group of a sharable container. 10/10/99