Inside Macintosh: Interapplication Communication /

Chapter 10 - Scripting Components

Connecting to a Scripting Component

To manipulate and execute scripts written in different scripting languages, your application can use Component Manager routines either to open a connection with each corresponding scripting component individually or to open a single connection with the generic scripting component. The generic scripting component, in turn, attempts to open connections dynamically with the appropriate scripting component for each script. By opening a connection with the generic scripting component, your application can load and execute scripts created by any scripting component that is registered with the Component Manager on the current computer.

In general, you should use the generic scripting component to execute and manipulate existing scripts and a specific scripting component when you create new scripts. When you call OSACompile or OSAStartRecording, the generic scripting component examines the script ID to determine which scripting component to use. If instead of a script ID you pass the constant kOSANullScript to these routines, the generic scripting component uses its current default scripting component. Each instance of the generic scripting component has its own default scripting component. From the user's point of view, the default scripting component corresponds to the scripting language selected in the Script Editor application when the user first creates a new script.

The generic scripting component provides routines you can use to get and set the default scripting component, determine which scripting component created a particular script, and perform other useful tasks when you are using multiple scripting components. See the section "Generic Scripting Component Routines," which begins on page 10-83, for descriptions of these routines.

You can use the Component Manager function OpenComponent to open a connection to a scripting component you specify with the component identifier returned by the FindNextComponent function. You can also use the OpenDefaultComponent function to open a scripting component without calling the FindNextComponent function.

The OpenComponent and OpenDefaultComponent functions return a component instance. This value identifies your application's connection to a component. You must supply this value whenever you call a standard scripting component routine.

Note

Your application may maintain several connections to a single component, or it may have connections to several components at the same time. Because some scripting components (including the current version of AppleScript) can execute only one script at a time per component instance, a multithreaded application must provide a separate component instance for each script that it compiles or executes while it is simultaneously executing other scripts.

The Component Manager type code for scripting components that support the routines described in this chapter is 'osa ', and the subtype code for the generic scripting component is 'scpt'.

CONST
   kOSAComponentType                      = 'osa ';
   kOSAGenericscriptingComponentSubtype   = 'scpt';

You can open a connection to a scripting component by calling the OpenDefaultComponent function, which returns a component instance. For example, this code opens a connection with the generic scripting component and stores the returned value in an application-defined variable:

VAR
   gScriptingComponent: ComponentInstance;
{open connection to generic scripting component}
gScriptingComponent := OpenDefaultComponent(kOSAComponentType, 
                         kOSAGenericscriptingComponentSubtype);

The generic scripting component in turn opens connections with other scripting components as necessary. The generic scripting component provides routines you can use to get instances of other scripting components when you want to use component-specific routines.

It is also possible to open an explicit connection directly with a specific scripting component such as AppleScript:

VAR
   gScriptingComponent: ComponentInstance;
{open connection to AppleScript component}
gScriptingComponent := OpenDefaultComponent(kOSAComponentType,
                                             kAppleScriptSubtype);

The scripting component routines described in this chapter include eight groups of optional routines that scripting components can support. If necessary, you can use the FindNextComponent function and other Component Manager routines to find a scripting component that supports a specific group of routines or to determine whether a particular scripting component supports a specific group of routines.

When you call FindNextComponent, you can provide, in a component description record (a data structure of type ComponentDescription), information about the scripting component you wish to find. The flag bits in the componentFlags field of a component description record provide this information. To find a scripting component that supports a specific group of optional routines, you can specify one or more of these constants in the componentFlags field:

CONST
   kOSASupportsCompiling      = $0002;
   kOSASupportsGetSource      = $0004; 
   kOSASupportsAECoercion     = $0008; 
   kOSASupportsAESending      = $0010; 
   kOSASupportsRecording      = $0020; 
   kOSASupportsConvenience    = $0040; 
   kOSASupportsDialects       = $0080; 
   kOSASupportsEventHandling  = $0100; 

The routines that correspond to these constants are described in "Optional Scripting Component Routines," which begins on page 10-45.

Note

Although the generic scripting component supports all the scripting component routines represented by these flags, the support it can actually provide depends on the individual components with which it opens connections.

Listing 10-1 shows how you can use these flags and the FindNextComponent function to locate a scripting component with specific characteristics. The componentFlags field of the component description record passed to FindNextComponent specifies the flags kOSASupportsCompiling and kOSASupportsGetSource. Because the componentFlagsMask field also specifies these flags, the FindNextComponent function locates a scripting component that supports these routines, regardless of whether or not it supports any others. The FindNextComponent function returns a component identifier that you can then use to get more information about the component or to open it.

Listing 10-1 Locating a scripting component that supports specific optional routines

FUNCTION MyConnectToScripting (VAR scriptingComponent: ComponentInstance)
                              : OSAError;
VAR
   descr, descr2: componentDescription;
   comp:          component;
   myErr:         OSErr;
BEGIN
   {fill in the fields of the component description record}
   {first specify component type, subtype, and manufacturer}
   descr.componentType := kOSAComponentType; {must be scripting component}
   descr.componentSubType := OSType(0); {any OSA component matching spec}
   descr.componentManufacturer := OSType(0); {don't care about manufacturer}
   
   {specify component flags and flags mask}
   descr.componentFlags := kOSASupportsCompiling + kOSASupportsGetSource;
   descr.componentFlagsMask := 
      kOSASupportsCompiling + kOSASupportsGetSource;

   {locate and open the specified component}
   comp := FindNextComponent(Component(0), descr); {0 indicates all }
                                                   { registered components }
                                                   { will be searched}
   {check whether the found component is the generic scripting component; }
   { if so, skip it and find the next matching component}
   myErr := GetComponentInfo(comp, descr2, NIL, NIL, NIL);
   IF descr2.componentSubType = kOSAGenericScriptingComponentSubtype THEN
      comp := FindNextComponent(comp, descr);
   IF comp = 0 THEN 
      MyConnectToScripting := kComponentNotFound
   ELSE 
   BEGIN
      scriptingComponent := OpenComponent(comp);
      IF scriptingComponent = 0 THEN 
         MyConnectToScripting := kComponentNotFound
      ELSE 
         MyConnectToScripting := noErr;
   END;
END;

Because the generic scripting component supports all the standard scripting component routines, the MyConnectToScripting function in Listing 10-1 checks whether the found component is the generic scripting component and, if so, skips it. If for any reason FindNextComponent can't locate and open a scripting component that supports the specified routines, MyConnectToScripting returns the application-defined constant kComponentNotFound.

For more information about locating and opening components with specific characteristics, see the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox.