Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 7 - Introduction to Scripting / Manipulating and Executing Scripts

Compiling, Saving, Modifying, and Executing Scripts

This section introduces some of the scripting component functions your application can use to compile, save, modify, and execute scripts.

To create and execute a script using the Script Editor application, a user can type the script, then press the Run button to execute it. Your application can provide similar capabilities by using these functions to compile source data and execute the resulting compiled script:

• The OSACompile function takes a descriptor record with a handle to source data (usually text) and a script ID. If you specify kOSANullScript instead of an existing script ID, OSACompile returns a script ID for the new compiled script, which you can then pass to the OSAExecute function.
• The OSAExecute function takes a script ID for a compiled script and a script ID for a script context, executes the script, and returns a script ID for the resulting script value.

The binding of any global variables in the compiled script is determined by the script context whose script ID you pass to OSAExecute. If you pass kOSANullScript instead of the script ID for a script context, the scripting component provides its own default context. If you want to provide your own script context rather than using the scripting component default context, you can use either OSACompile or OSAMakeContext to create a script context, which you can load and store just like a compiled script.

After creating a script and trying it out, a user may want to save it for future use. Your application should normally save its scripts as script data rather than source data, so that it can reload and execute the data without recompiling it. Before saving script data, you must first call the OSAStore function to get a handle to the data in the form of a descriptor record. You can then save the data to disk as a resource or write it to the data fork of a document.

To allow a user to reload and execute a previously compiled and saved script, your application can call these functions:

• The OSALoad function takes a descriptor record that contains a handle to the saved script data and returns a script ID for the compiled script.
• The OSAExecute function takes a script ID for a compiled script and a script ID for a script context, executes the script, and returns a script ID for the resulting script value.

In most cases you will want to allow users to modify saved scripts and save them again. To allow a user to modify and save a compiled script, your application can call these functions:

• The OSAGetSource function takes a script ID and returns a descriptor record with a handle to the equivalent source data.
• The OSACompile function takes a descriptor record with a handle to source data and a script ID, and returns the same script ID updated so that it refers to the modified and recompiled script.
• The OSAStore function takes a script ID and returns a copy of the corresponding script data in the form of a storage descriptor record.

You can pass the script ID for the compiled script to be modified to the OSAGetSource function, which returns a descriptor record with a handle to the equivalent source data. Your application can then present the source data to the user for editing. When the user has finished editing the source data, you can pass the modified source data and the original script ID to the OSACompile function to update the script ID so that it refers to the modified and recompiled script. Finally, to obtain a handle to the modified script data so you can save it in a resource or write it to the data fork of a document, you can pass the script ID for the modified compiled script to the OSAStore function.

If your application has no further use for a compiled script or a resulting script value after successfully loading, saving, compiling, or executing a script, you can use the OSADispose function to release the memory assigned to them. The OSADispose function takes a script ID and releases the memory assigned to the corresponding script data. A script ID is no longer valid after the memory associated with it has been released. This means, for example, that a scripting component may assign a different script ID to the same compiled script each time you load it, and that a scripting component may reuse a script ID that is no longer associated with a specific script.

"Using Scripting Component Routines," which begins on page 10-7, provides more information about the standard scripting component routines described in this section.