Execute OSAs
Volume Number: 11
Issue Number: 10
Column Tag: APPLE SCRIPTING
Execute OSA Scripts from Applications
Complex Apple Events are simple with the OSA’s help
By Andrew Nemeth, Warrimoo, Australia
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
Reach Out and Touch Someone Else’s Program
One of the useful things to come out of Cupertino in recent years is AppleScript and its
associated support structure, the Open Scripting Architecture. This technology is well
known for its ability to manipulate Macintosh applications by the use of high-level
scripts, less well known however is the side of the OSA which enables the remote
manipulation of scriptable applications from within other applications. For instance,
you could use the OSA to search a FileMaker Pro database and then display the results
in PageMaker - all coordinated from within your own source code!
Although a few articles showing how to do this have appeared in recent years (see
items 2 & 3 in the “References” listing below), there has been little discussion of how
one could do this efficiently and simply, as well as how one could supply data to, and
receive data from AppleScripts at runtime. Hence this article.
Presented below is a sample AppleScript and custom C++ class called TRunOSA
which:
• Insulates the programmer from the technicalities of the OSA;
• Allows for the running of scripts, either embedded in the application’s resource
fork, or else stored in separate compiled AppleScript files;
• Shows how to create an AppleEvent-aware AppleScript;
• Enables the transmission of variables to compiled scripts by way of AppleEvents;
• Allows for the extraction of any results in text form.
Before we go any further, a warning: this code was developed using the Apple
Universal Headers which shipped with Metrowerks CodeWarrior Gold CW5. Because of
the recent nature of OSA technology, it may not work with older headers! [Or newer
headers for that matter. Any available updates will be available through the normal
channels. - jk]
OSL, OSA and AppleScript
A small note should be made about the Object Support Library. This is the foundation
upon which the OSA is built, and as such it can do everything the OSA can do without the
overhead associated with a higher level scripting language (such as AppleScript).
The main disadvantage of using the OSL however is its amazing complexity.
Everything has to be referenced by hand-assembled Object Specifiers; a pain at best,
at worst a nightmare. For example, to specify the “visibility” property of a process
running in the Finder (by no means a complicated thing) requires three calls to
AECreateDesc(), two to CreateObjSpecifier() and then all the paraphernalia required
to check for errors and dispose of allocated memory: a total of around 30 lines of code.
To do the same in AppleScript is simplicity itself:
tell application "Finder
set the visibility of process "Someone else's App" to false
end tell
You can see which is easier to develop, test and maintain; all we need is a way of
avoiding the overhead that calls to the OSA usually entail. The design of the C++ class
which follows goes out of its way to address this.
Sample AppleScript
In order to use our C++ class TRunOSA, we need to create a sample AppleScript which
can respond to AppleEvents. When it runs, TRunOSA will send events to the script to
indicate which portions of it are to execute; sometimes with, sometimes without
variables.
Open up the Script Editor application which comes with AppleScript and enter the
following script. (Note that the “” character is obtained by pressing option-enter;
“” by pressing option-\ and “” by option-shift-\. With the last two, Jasik users
should be prepared to Meet Thy Green Menu Bar )
-- Sample AppleScript which responds to different AppleEvents:
on event MySRFRST
-- Just run this portion of the script without any variable
display dialog
"No variables" buttons {"Okay"} default button "Okay
set result to "No variable Script ran okay!
end event MySRFRST
on event MySRSCND strparam
-- Run this portion of the script with the string variable ‘strparam’
display dialog
"Parameter: " & strparam buttons {"Okay"} default button "Okay
set result to "Variable Script ran okay!
end event MySRSCND
What makes this script unusual is that by using an event paradigm, we can break
a single script into any number of independent sub-scripts. Which means that we can
load only one script, and yet we call many different sub-scripts, effectively avoiding
loading a script, one of the sources overhead associated with running separate scripts
through the OSA.
Here, the first portion of the script will only execute when it receives a
‘MySR’/‘FRST’ AppleEvent. The second portion will respond only to ‘MySR’/‘SCND’;
it also extracts the typeChar variable contained in the event.
Save this script as a Compiled Script with the File:Save As menu. Later on, we
will copy the ‘scpt’ resource in this script to the resource fork of our own application.
Introducing TRunOSA: The C++ Declaration
TRunOSA.h
#pragma once
class TRunOSA
{
private:
static ComponentInstance scriptComponent;
public:
TRunOSA ();
~TRunOSA ();
OSAError initOSA ( void );
OSAError initOSA ( const FSSpec & );
OSAError runScript ( void );
OSAError runScript ( const AEEventClass, const AEEventID );
OSAError runScript ( const AEEventClass, const AEEventID,
Str255 );
OSAError getResultDesc ( AEDesc *, long * );
private:
AEDesc f_aedescScript;
OSAID f_osaidOriginal,
f_osaidResult;
OSAError myInitOSA ( Handle );
OSAError myRunScript ( const AEEventClass,
const AEEventID, AEDesc * );
private:
TRunOSA ( const TRunOSA & );
TRunOSA & operator= ( const TRunOSA & );
};
inline OSAError TRunOSA::runScript (
const AEEventClass aeclassSuite,
const AEEventID aesuiteKind )
{
return( myRunScript ( aeclassSuite, aesuiteKind, NULL ) );
}
Some notes on this:
• The ComponentInstance variable TRunOSA::scriptComponent is declared as a
private static class variable to make sure the scripting component is initialized
only once in an application, regardless of how many TRunOSA objects are created.
Being global in scope, it has been declared “private” to keep other’s hands off it;
• There are two initOSA() methods in addition to the default constructor because we
want to be able to return OSAErrors. This design has been chosen because in C++
you cannot return errors from constructors (and exception handling is at
present too compiler-specific to be useful);
• Although we will run the script by calling one of the runScript() overloaded
methods, the actual work is always done by the private myRunScript() method.
This use of wrapper functions allows for the extension of the class at a later date
by the addition of appropriate runScript() methods;
• The default copy constructor and assignment operators have been declared as
private to prevent others from copying objects. As the model for this class is
that of an “engine” which does something, rather than that of a “container”
which stores items, there is no need to support object copying here;
• One of the overloaded runScript() methods is made inline because it merely
wraps a call to the private myRunScript().
Getting to Know TRunOSA: The C++ Implementation
TRunOSA.cp
#include "TRunOSA.h
// #define NDEBUG
#include
#include
#include
#include
#include
#include
#include
• The ANSI C header file contains the macro declaration for assert(), a
utility which allows for the checking of dumb values during development. When
the code is shipped, we can knock out all theses checks (and thus avoid the
performance penalty extensive checking entails) by uncommenting the NDEBUG
pre-compile directive;
• All the other Apple headers should be included because they are (mostly) not part
of Metrowerks’ or Symantec’s pre-compiled Macintosh headers;
ComponentInstance TRunOSA::scriptComponent = NULL;
• Whenever a static variable is declared in a C++ class, it must also be physically
defined somewhere else. It makes sense to do this in the file which contains all
the class method implementations.
TRunOSA::TRunOSA( )
: f_osaidOriginal ( kOSANullScript ),
f_osaidResult ( kOSANullScript )
{
f_aedescScript.descriptorType = typeNull;
f_aedescScript.dataHandle = NULL;
}
TRunOSA::~TRunOSA()
{
if ( NULL != TRunOSA::scriptComponent )
{
::AEDisposeDesc( &f_aedescScript );
::OSADispose( TRunOSA::scriptComponent, f_osaidOriginal );
::OSADispose( TRunOSA::scriptComponent, f_osaidResult );
}
}
• Construction makes certain everything is initialized with sensible and harmless
values. Note that the class is not yet ready to use, for this to happen the
programmer must also put in a call to one of the initOSA() methods;
• The destructor as usual deallocates any allocated memory;
• The null delimiter “::” is used to prefix calls to the toolbox. Although this is not
strictly necessary, it does make it easier to differentiate any non-class function
calls when reading the code.
OSAError TRunOSA::initOSA( void )
{
Handle hScript = NULL;
OSAError osaErr = noErr;
hScript = ::Get1IndResource( typeOSAGenericStorage, 1 );
if ( NULL == hScript )
return( resNotFound );
::DetachResource( hScript );
osaErr = myInitOSA( hScript );
return( osaErr );
}
• The programmer calls this method when they want to use a script which is
embedded in the resource fork of the application. The advantage of doing this is
that there are no separate script files lying around, confusing users. The
disadvantage is that the programmer can have only one script, which must be
modified with a resource editor;
• Rather than hard-wire the toolbox call to explicitly grab a ‘scpt’ resource, we
use the OSA constant typeOSAGenericStorage to help make our code future-proof;
• Once the handle is loaded and detached (essential! Resource Map Corruption
otherwise), we pass the handle to myInitiOSA() where the actual initialization
takes place;
• Notice that we DO NOT dispose the handle! This is because the handle will, in due
course, become part of the AEDesc class var f_aedescScript (and be deallocated in
the destructor).
OSAError TRunOSA::initOSA( const FSSpec & fsspecScript )
{
Handle hScript = NULL;
short shResRefNum = -1;
OSAError osaErr = noErr;
shResRefNum = ::FSpOpenResFile( &fsspecScript, fsRdPerm );
if ( -1 == shResRefNum )
return( ::ResError() );
hScript = ::Get1IndResource( typeOSAGenericStorage, 1 );
if ( NULL == hScript )
return( resNotFound );
::DetachResource( hScript );
::CloseResFile( shResRefNum );
osaErr = myInitOSA( hScript );
return( osaErr );
}
• We use this method when we wish to run a script stored in a compiled
AppleScript file separate from the application;
• We have to do a little more work here because we grab the script handle from the
resource fork of an external file;
• This method allows us to use multiple script files (provided we make
corresponding calls to this version of initOSA());
• Again, after grabbing and detaching the handle, we pass it to myInitOSA() to do
the actual initialization.
OSAError TRunOSA::myInitOSA( Handle hScript )
{
const long klgGestaltMask = 1L;
long lgFeature = 0L;
AEDesc aedescDummy = { typeNull, NULL };
OSErr myErr = noErr;
OSAError osaErr = noErr;
assert( NULL != hScript );
if ( NULL == TRunOSA::scriptComponent )
{
myErr = ::Gestalt( gestaltAppleEventsAttr, &lgFeature );
if ( ( noErr == myErr ) &&
( lgFeature &
( klgGestaltMask << gestaltScriptingSupport ) ) )
NULL;
else
return( errOSACantOpenComponent );
TRunOSA::scriptComponent =
::OpenDefaultComponent( kOSAComponentType,
kOSAGenericScriptingComponentSubtype );
osaErr = ::OSASetDefaultScriptingComponent(
TRunOSA::scriptComponent,
kAppleScriptSubtype );
if ( noErr != osaErr )
return( osaErr );
}
::AEDisposeDesc( &f_aedescScript );
f_aedescScript.descriptorType = typeOSAGenericStorage;
f_aedescScript.dataHandle = hScript;
if ( kOSANullScript != f_osaidOriginal )
::OSADispose( TRunOSA::scriptComponent, f_osaidOriginal );
osaErr = ::OSALoad( TRunOSA::scriptComponent,
&f_aedescScript, kOSAModeNull, &f_osaidOriginal );
::OSADisplay( TRunOSA::scriptComponent, f_osaidOriginal,
typeChar, kOSAModeDisplayForHumans,
&aedescDummy );
::AEDisposeDesc( &aedescDummy );
return( osaErr );
}
• There are two reasons why this class uses init methods separate from the
constructor. Firstly (as noted above) this way we can have error codes returned
to see if we were successful during setup. Secondly, this helps us disguise the
time lag required to load and initialize the OSA. As most of the trap calls in
myInitOSA() take about a second to execute, by putting them all into one function,
we can effectively hide the delay from the user by calling it during application
startup;
• If the static class var TRunOSA::scriptComponent has not already been initialized,
we make a call to Gestalt() to make sure scripting is supported;
• We then put in calls to the OSA traps OpenDefaultComponent() and
OSASetDefaultScriptingComponent() to set up the scripting component configured
for AppleScript. Although this takes about half a second to complete, we need do it
only once;
• We deallocate any existing class var f_aedescScript and then build a new one by
filling in the AEDesc by hand. We have to deallocate first because this method
may be called more than once in the life of an object (when you want to run
different scripts stored in different files);
• Similarly, we always make sure we delete any existing OSAID script in
f_osaidOriginal before loading a new one by calling OSALoad(). This will also
take about half a second;
• Finally, we place a dummy call to OSADisplay(), knowing it will fail. As we will
have to make this call “for real” later, we may as well pay the load penalty for
this trap now while we are doing other time-consuming things. Depending on the
size of the script loaded, this call can take anywhere up to 2 seconds. Subsequent
calls take only a small fraction of this.
OSAError TRunOSA::runScript( void )
{
if ( NULL == TRunOSA::scriptComponent )
return( errOSAInvalidID );
if ( kOSANullScript != f_osaidResult )
::OSADispose( TRunOSA::scriptComponent, f_osaidResult );
return( ::OSAExecute( TRunOSA::scriptComponent,
f_osaidOriginal, kOSANullScript,
kOSAModeNull, &f_osaidResult ) );
}
• The first and simplest of the overloaded runScript() methods, use this when you
have a standard script you wish to run; i.e. one to which no AppleEvents are sent;
• Prior to calling OSAExecute(), checks are made to ensure the scripting
component is properly set up and that any prior OSAID result in f_osaidResult is
deallocated;
• The new result is loaded into the OSAID pointer to the f_osaidResult class var,
then the OSAError code is returned.
inline OSAError TRunOSA::runScript (
const AEEventClass aeclassSuite,
const AEEventID aesuiteKind )
{
return( myRunScript ( aeclassSuite, aesuiteKind, NULL ) );
}
• As part of the TRunOSA.h header file, the inline version of runScript() allows
for the running of scripts where AppleEvents are to be used, but where no
parameters are to be sent;
• The actual work is done by myRunScript().
OSAError TRunOSA::runScript(
const AEEventClass aeclassSuite,
const AEEventID aesuiteKind,
Str255 Âstr255Var )
{
AEDesc aedescVar = { typeNull, NULL };
OSAError osaErr = noErr;
assert( str255Var[0] > 0 );
osaErr = ::AECreateDesc( typeChar, &str255Var[1],
str255Var[0], &aedescVar );
if ( noErr == osaErr )
osaErr = myRunScript( aeclassSuite, aesuiteKind, &aedescVar );
::AEDisposeDesc( &aedescVar );
return( osaErr );
}
• Here the programmer supplies the type of AppleEvent they want to send, as well
as (in this case) the Str255 string they want sent as the variable;
• After asserting that there is indeed a string to send, an AEDesc is built to contain
the string;
• Again, this method wraps myRunScript(), where the actual work is done. We
deallocate the AEDesc before returning any OSAError.
OSAError TRunOSA::myRunScript(
const AEEventClass aeclassSuite,
const AEEventID aesuiteKind,
AEDesc Û* ptraedescVar )
{
AppleEvent aeEvent = { typeNull, NULL };
OSAError osaErr = noErr;
if ( NULL == TRunOSA::scriptComponent )
return( errOSAInvalidID );
assert( aeclassSuite > 0L );
assert( aesuiteKind > 0L );
osaErr = ::AECreateAppleEvent( aeclassSuite,
aesuiteKind,
&f_aedescScript,
kAutoGenerateReturnID,
kAnyTransactionID,
&aeEvent );
if ( NULL != ptraedescVar && noErr == osaErr )
osaErr = ::AEPutParamDesc( &aeEvent, keyDirectObject,
ptraedescVar );
if ( noErr == osaErr && ( kOSANullScript != f_osaidResult ) )
::OSADispose( TRunOSA::scriptComponent, f_osaidResult );
if ( noErr == osaErr )
osaErr = ::OSAExecuteEvent( TRunOSA::scriptComponent,
&aeEvent, f_osaidOriginal,
kOSAModeNull, &f_osaidResult );
::AEDisposeDesc( &aeEvent );
return( osaErr );
}
• This is the business-end of our class, the method which sends AppleEvents to our
loaded script via the OSA. The variable to be sent is a pointer to a generic
AEDesc, meaning that any type of variable can be sent, provided we supply the
appropriate “wrapper” method to fill the AEDesc;
• Before doing anything, we first check to make sure the scripting component has
been validly set and that there are indeed AppleEvents to send(!);
• An AppleEvent is created, targeted to the AEDesc f_aedescScript, which was
initialized in myInitOSA() earlier;
• If there is no error (and if there is also a variable to send!), then the AEDesc
variable is slotted into the keyDirectObject parameter of the AppleEvent;
• We deallocate any prior OSAID f_osaidResult script as part of our courageous
battle against memory leaks;
• We then place a call to OSAExecuteEvent() to execute the script with the variable
we want, passing as parameters the scripting component, a pointer to the event
containing the variable and pointers to the original and result OSAID scripts;
• Again, any result is placed into the pointer to the resulting OSAID script
f_osaidResult. After this, we remember to deallocate the AppleEvent we created
earlier.
OSAError TRunOSA::getResultDesc( AEDesc * ptraedescResult,
long * ptrlgSize )
{
OSAError osaErr = noErr;
if ( NULL == TRunOSA::scriptComponent &&
kOSANullScript == f_osaidResult )
return( errOSAInvalidID );
assert( NULL != ptraedescResult );
assert( NULL != ptrlgSize );
osaErr = ::OSADisplay( TRunOSA::scriptComponent,
f_osaidResult,
typeChar, kOSAModeDisplayForHumans,
ptraedescResult );
if ( noErr == osaErr )
*ptrlgSize = ::GetHandleSize( ptraedescResult->dataHandle );
else
*ptrlgSize = 0L;
::OSADispose( TRunOSA::scriptComponent, f_osaidResult );
f_osaidResult = kOSANullScript;
return( osaErr );
}
• Now we have run the script, all that remains is to extract the result. When
OSAExecute() or OSAExecuteEvent() run, they return results into the OSAID
class var f_osaidResult, if we want to make use of this then we have to convert it
to humanly readable form by calling the OSA’s trap OSADisplay();
• After making sure we have a result to process and that the pointers provided are
valid, we put in a call to OSADisplay() to “translate” the result. We pass as
parameters the scripting component, a pointer to the result script, the constants
typeChar and kOSAModeDisplayForHumans (we want the answer as words), as
well as a pointer to the AEDesc where we want the translated result placed.
Because we were clever in making a dummy call earlier in myInitOSA(),
completion of the call here involves minimal delay;
• Finally, we store the size of the result in the ptr provided and dispose of the
result-holding script in f_osaidResult, again, triumphantly, to defeat any
memory leaks.
Is That All There Is?
Well, almost. You will also have to make a few modifications to your project.
Specifically, you will have to add the OSACompLib.o.lib and AEObjectSupportLib.o.lib
libraries, as well as making sure your project is High Level AppleEvent aware by
setting the isHighLevelEventAware flag in the SIZE resource (you are sending and
receiving AppleEvents right?). For CodeWarrior users, the libraries are located in
the “Metrowerks C/C++ :Libraries :Mac OS 68K :MacOS Files ” folder.
I think it goes without saying that you will also have to install AppleScript and its
attendant files. And use System 7
Putting It All Together: Using TRunOSA
Using the sample AppleScript you created earlier, open the script file in a resource
editor and copy the ‘scpt’ resource into the resource fork of your application. Then
enter the following C++ code into your favorite source file:
#include "TRunOSA.h" // Script runner class
static void myFunAndGames( void );
...
void myFunAndGames( void )
{
const AEEventClass kaeclassSuite = 'MySR';
const AEEventID kaesuiteKind_1 = 'FRST',
kaesuiteKind_2 = 'SCND';
Str255 str255Dummy = { "\pHello Cruel World!" };
OSErr myErr = noErr;
AEDesc aedescResult = { typeNull, NULL };
long lgSize = 0L;
TRunOSA objRunOSA;
// init object and get ready for script running
myErr = objRunOSA.initOSA();
// run script without var
if ( noErr == myErr )
myErr = objRunOSA.runScript( kaeclassSuite, kaesuiteKind_1 );
// now run script WITH string var
if ( noErr == myErr )
myErr = objRunOSA.runScript( kaeclassSuite, kaesuiteKind_2,
str255Dummy );
// extract result & size as AEDesc & long
if ( noErr == myErr )
myErr = objRunOSA.getResultDesc( &aedescResult, &lgSize );
// extract result as Str255
if ( noErr == myErr )
{
lgSize = lgSize > 255 ? 255 : lgSize;
str255Dummy[0] = lgSize;
::HLock( aedescResult->dataHandle );
::BlockMoveData( *aedescResult->dataHandle,
&str255Dummy[1], lgSize );
str255Dummy[0] = lgSize;
::HUnlock( aedescResult->dataHandle );
}
// tidy up
::AEDisposeDesc( &aedescResult );
// death before dishonour
if ( noErr != myErr )
::ShutDwnPower();
}
The above will put up two AppleScript dialogs, one after the other. The extracted
string result (which is not used for anything here) can be viewed with a source-level
debugger if you wish. Should something goes wrong then we punish ourselves by
paying a visit to the ShutDown Manager.
Notice how slow the first call to initOSA() is? But also notice how fast the calls
to runScript() are thereafter!
As you can see, loading and running AppleScripts has become trivial. By using
the AEEventClass and AEEventID constants, you can specify only certain portions of
your loaded script are to be executed, greatly simplifying script manipulation.
References
Inside Macintosh: Inter-Application Communications,
Chapter 10
Dave Mark, Ultimate Mac Programming, ISBN 1-56884-195-7, pp. 163 - 187
pp. 28 - 42
Steve Maguire, Writing Solid Code, ISBN1-55615-55-4,
pp. 16 - 19
Acknowledgements
Thanks to both “Ed Anson ” and “Quinn The Eskimo