Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Interapplication Communication /
Chapter 10 - Scripting Components / Scripting Components Reference
Optional Scripting Component Routines / Using Script Contexts to Handle Apple Events


OSAExecuteEvent

You can use the OSAExecuteEvent function to handle an Apple event with the aid of a script context and obtain a script ID for the resulting script value.

FUNCTION OSAExecuteEvent(scriptingComponent: ComponentInstance;
                         theAppleEvent: AppleEvent;
                         contextID: OSAID;
                         modeFlags: LongInt;
                         VAR resultingScriptValueID: OSAID)
                         : OSAError;
scriptingComponent
A component instance created by a prior call to the Component Manager function OpenDefaultComponent or OpenComponent (see page 10-4).
theAppleEvent
The Apple event to be handled.
contextID
The script ID for the script context to be used to handle the Apple event.
modeFlags
Information used by individual scripting components. To avoid setting any mode flags, specify kOSAModeNull. Other possible mode flags are listed in the description that follows.
resultingScriptValueID
A script ID for the resulting script value.
DESCRIPTION
The OSAExecuteEvent function attempts to use the script context specified by the contextID parameter to handle the Apple event specified by the theAppleEvent parameter. If the scripting component determines that the script context can't handle the event (for example, if a script written in AppleScript doesn't include statements that handle the event), OSAExecuteEvent immediately returns errAEEventNotHandled rather than errOSAScriptError.

If the scripting component determines that the script context can handle the event, OSAExecuteEvent executes the script context's handler and returns the resulting script ID. If execution of the script context's handler for the event generates an error, OSAExecuteEvent returns errOSAScriptError, and you can get more detailed error information by calling the OSAScriptError function.

You can control the way in which the scripting component executes a script context by adding any of these flags to the modeFlags parameter:
FlagDescription
kOSAModeNeverInteractAdds kAENeverInteract to sendMode parameter of AESend for events sent when script is executed.
kOSAModeCanInteractAdds kAECanInteract to sendMode parameter of AESend for events sent when script is executed.
kOSAModeAlwaysInteractAdds kAEAlwaysInteract to sendMode parameter of AESend for events sent when script is executed.
kOSAModeCantSwitchLayerPrevents use of kAECanSwitchLayer in sendMode parameter of AESend for events sent when script is executed (the opposite of the Apple Event Manager's interpretation of the same bit).
kOSAModeDontReconnectAdds kAEDontReconnect to sendMode parameter of AESend for events sent when script is executed.
kOSAModeDoRecordPrevents use of kAEDontRecord in sendMode parameter of AESend for events sent when script is executed (the opposite of the Apple Event Manager's interpretation of the same bit).

If the script context identified by the contextID parameter specifies that the Apple event should be passed to the application's default handler for that event (for example, with an AppleScript continue statement), OSAExecuteEvent passes the event to the resume dispatch function currently being used by the scripting component. The resume dispatch function dispatches the event directly to the application's standard handler for that event (that is, without calling OSAExecuteEvent again). If the contextID parameter is kOSANullScript, the OSAExecuteEvent function passes the event directly to the resume dispatch function. If a call to the resume dispatch function is successful, execution of the script context proceeds from the point at which the resume dispatch function was called.

IMPORTANT
The OSAExecuteEvent function can generate the result code errAEEventNotHandled in at least two ways. If the scripting component determines that a script context doesn't declare a handler for a particular event, OSAExecuteEvent immediately returns errAEEventNotHandled. If a scripting component calls its resume dispatch function during script execution and the application's standard handler for the event fails to handle it, OSAExecuteEvent returns errOSAScriptError and a call to OSAScriptError with kOSAErrorNumber in the selector parameter returns errAEEventNotHandled as the resulting error description.
RESULT CODES
noErr0No error
errAEEventNotHandled-1708Script context doesn't contain handler for event
errOSASystemError-1750General scripting system error
errOSAInvalidID-1751Invalid script ID
errOSAScriptError-1753Error occurred during execution or because of an attempt to pass event to a NIL resume dispatch function
badComponentInstance$80008001Invalid component instance

Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996