Execute OSA Scripts from Applications

Complex Apple Events are simple with the OSA’s help

By Andrew Nemeth, Warrimoo, Australia

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<assert.h>

#include<OSAGeneric.h>
#include<Components.h>
#include<OSA.h>
#include<AppleScript.h>
#include<AEObjects.h>
#include<Gestalt.h>

• The ANSI C header file <assert.h> 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;

ComponentInstanceTRunOSA::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.

OSAErrorTRunOSA::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).

OSAErrorTRunOSA::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.

OSAErrorTRunOSA::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.

OSAErrorTRunOSA::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().

OSAErrorTRunOSA::runScript( 
 const AEEventClassaeclassSuite, 
 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.

OSAErrorTRunOSA::myRunScript( 
 const AEEventClassaeclassSuite, 
 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.

OSAErrorTRunOSA::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 AEEventClasskaeclassSuite = 'MySR';
 const AEEventID kaesuiteKind_1 = 'FRST',
 kaesuiteKind_2 = 'SCND';

 Str255 str255Dummy = { "\pHello Cruel World!" };
 OSErr  myErr = noErr;
 AEDesc aedescResult = { typeNull, NULL };
 long   lgSize = 0L;
 TRunOSAobjRunOSA;


    //    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

Paul Smith, Develop 18: “Programming for Flexibility ”,
pp. 28 - 42

Steve Maguire, Writing Solid Code, ISBN1-55615-55-4,
pp. 16 - 19

Acknowledgements

Thanks to both “Ed Anson <tulip@tiac.net>” and “Quinn The Eskimo <quinn@cs.uwa.edu.au>” for the initial ideas from which I developed this code.