Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 10 - Scripting Components / Using Scripting Component Routines

Loading and Executing Script Data

Figure 7-4 on page 7-10 illustrates how an application might execute a script whenever the user presses the Tab key after entering a customer's name in the "Customer Name" field of an electronic form. To execute a script in response to some user action, your application must be able to load and execute the script data for a compiled script.

This section describes how to load and execute a previously compiled and saved script. The next section, "Modifying and Recompiling a Compiled Script," describes how to allow a user to modify a compiled script.

The OSALoad function takes three input parameters: a component instance that identifies a connection with a scripting component; a descriptor record that contains a handle to the script data to be loaded; and a parameter that contains flags for use by individual scripting components. The function returns, in the fourth parameter, a script ID for the script data.

When your application calls OSALoad with a component instance that identifies a connection with the generic scripting component, the generic scripting component in turn uses a connection with the scripting component that created the script data (if that component is registered with the Component Manager on the local computer). If the descriptor record passed to OSALoad is of type typeOSAGenericStorage, the generic scripting component uses the trailer that follows the script data to determine which scripting component to open a connection with. If the descriptor record's type is the subtype value for some other scripting component, the generic scripting component does not look for a trailer and uses the descriptor type to identify the scripting component.

When your application calls OSALoad with a component instance that identifies a connection to any scripting component other than the generic scripting component, that component can load script data only if it was saved as the data for a descriptor record whose descriptor type matches the scripting component's subtype. In this case, however, your application easily can take advantage of additional routines and other special capabilities provided by that scripting component.

It is also possible to call OSALoad using the generic scripting component, then use generic scripting component routines to identify the specific component associated with the loaded script. This allows you to use component-specific routines with a script originally loaded by the generic scripting component. For information about how to do this, see "Routines Used by Scripting Components," which begins on page 10-91.

The OSALoad function returns a script ID for the loaded script data. The generic scripting component always associates the returned script ID with the scripting component that created the script. In this way, it can use a connection with that component again whenever the client application passes the returned script ID to other scripting component routines.

Listing 10-4 shows a procedure that loads and executes a script. The MyLoadAndExecute procedure takes a handle to script data that was previously saved using a generic storage descriptor record, obtains a script ID for the equivalent compiled script, executes the compiled script in the default context, and disposes of both the compiled script and the resulting script value ID. If the OSAExecute function returns a script execution error, MyLoadAndExecute obtains further information about the error and displays it to the user.

Listing 10-4 A routine that loads and executes script data previously saved using a generic storage descriptor record

PROCEDURE MyLoadAndExecute (scriptData: Handle);
VAR
   scriptDesc:                   AEDesc;
   scriptID, resultID:           OSAID;
   scriptText:                   AEDesc;
   myOSAErr, ignoreErr:          OSAError;
BEGIN
   {load the script data}
   scriptDesc.descriptorType := typeOSAGenericStorage;
   scriptDesc.dataHandle := scriptData;
   myOSAErr := OSALoad(gScriptingComponent, scriptDesc, 
                        kOSAModeNull, scriptID);
   IF myOSAErr = noErr THEN 
   BEGIN
      {execute the resulting compiled script in the default }
      { context}   
      myOSAErr := OSAExecute(gScriptingComponent, scriptID, 
                           kOSANullScript, kOSAModeNull, 
                           resultID);
      ignoreErr := OSADispose(gScriptingComponent, scriptID);
      ignoreErr := OSADispose(gScriptingComponent, resultID);
   END;
   IF myOSAErr = errOSAScriptError THEN 
      MyGetScriptErrorInfo;
END;

The OSALoad function in Listing 10-4 takes a component instance, a generic storage descriptor record for the script data to be loaded, and a parameter that contains the mode flags, if any, for loading the script. In this case the constant kOSAModeNull indicates that no mode flags are set. The OSALoad function returns a script ID for the resulting compiled script, which the MyLoadAndExecute procedure then passes to the OSAExecute function.

In addition to a component instance and the script ID for the compiled script to be executed, the OSAExecute function takes a script ID for a context and a parameter that contains the mode flags, if any, for script execution. In Listing 10-4, the script ID passed to OSAExecute for the script context is kOSANullScript, indicating that the scripting component can use its default context to bind any variables. The constant kOSAModeNull in the next parameter indicates that no mode flags are set for script execution.

After disposing of the compiled script and the resulting script value, MyLoadAndExecute checks the result code returned by OSAExecute. If it is errOSAScriptError, MyLoadAndExecute calls the MyGetScriptErrorInfo procedure (see Listing 10-3 on page 10-11), which in turn uses the OSAScriptError function to obtain more information about the error.

You can use the OSALoad and OSAExecute functions as shown in Listing 10-4 if you expect the user to execute the compiled script several times or manipulate it in some other way. If you want to load and execute a script just one time and don't need to keep the compiled script in memory after it has been executed, you can use OSALoadExecute instead of OSALoad, OSAExecute, and OSADispose. This function takes a component instance, a descriptor record for the script data to be loaded and executed, a context ID, and a modeFlags parameter. The OSALoadExecute function executes the resulting compiled script, disposes of the compiled script, and returns the script ID for the resulting script data.