Legacy Document

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

Inside Macintosh: Processes: Chapter 2 - Process Manager / Using the Process Manager

Launching Other Applications
You can launch other applications by calling the high-level LaunchApplication function. This function lets your application control various options associated with launching an application. For example, you can

allow the application to be launched in a partition smaller than the preferred size but greater than the minimum size, or allow it to be launched only in a partition of the preferred size
launch an application without terminating your own application, bring the launched application to the front, and get information about the launched application
request that your application be notified if any application that it has launched terminates

Earlier versions of system software used a shorter parameter block as a parameter to the _Launch trap macro. The _Launch trap macro still supports the use of this parameter block. Applications using the LaunchApplication function should use the new launch parameter block (of type LaunchParamBlockRec). Use the Gestalt function and specify the selector gestaltOSAttr to determine which launch features are available.
Most applications don't need to launch other applications. However, if your application includes a desk accessory or another application, you might use either the high-level LaunchApplication function to launch an application or the LaunchDeskAccessory function to launch a desk accessory. For example, if you have implemented a spelling checker as a separate application, you might use the LaunchApplication function to open the spelling checker when the user chooses Check Spelling from one of your application's menus.
You specify a launch parameter block as a parameter to the LaunchApplication function. In this launch parameter block, you can specify the filename of the application to launch, specify whether to allow launching only in a partition of the preferred size or to allow launching in a smaller partition, and set various other options--for example, whether your application should continue or terminate after it launches the specified application.
The LaunchApplication function launches the application from the specified file and returns the process serial number, preferred partition size, and minimum partition size if the application is successfully launched.
Note that if you launch another application without terminating your application, the launched application does not actually begin executing until you make a subsequent call to WaitNextEvent or EventAvail.
The launch parameter block is defined by the LaunchParamBlockRec data type.
TYPE LaunchParamBlockRec = 
   RECORD
      reserved1:              LongInt;             {reserved}
      reserved2:              Integer;             {reserved}
      launchBlockID:          Integer;             {extended block}
      launchEPBLength:        LongInt;             {length of block}
      launchFileFlags:        Integer;             {app's Finder flags}
      launchControlFlags:     LaunchFlags;         {launch options}
      launchAppSpec:          FSSpecPtr;           {location of app's file}
      launchProcessSN:        ProcessSerialNumber; {returned psn}
      launchPreferredSize:    LongInt;             {returned pref size}
      launchMinimumSize:      LongInt;             {returned min size}
      launchAvailableSize:    LongInt;             {returned avail size}
      launchAppParameters:    AppParametersPtr;    {high-level event}
   END;
In the launchBlockID field, specify the constant extendedBlock to identify the parameter block and to indicate that you are using the fields following it in the launch parameter block.
CONST
   extendedBlock              = $4C43;    {extended block}
In the launchEPBLength field, specify the constant extendedBlockLen to indicate the length of the remaining fields in the launch parameter block (that is, the length of the fields following the launchEPBLength field). For compatibility, you should always specify the length value in this field.
CONST
   extendedBlockLen           = sizeof(LaunchParamBlockRec) - 12;
The launchFileFlags field contains the Finder flags for the application file. (See the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials for a description of the Finder flags.) The LaunchApplication function sets this field for you if you set the bit defined by the launchNoFileFlags constant in the launchControlFlags field. Otherwise, you must get the Finder flags from the application file and set this field yourself (by using the File Manager routine FSpGetFInfo, for example).
In the launchControlFlags field, you specify various options that control how the specified application is launched. See the section "Launch Options" on page 2-15 for information on the launch control flags.
You specify the application to launch in the launchAppSpec field of the launch parameter block. In this field, you specify a pointer to a file system specification record (FSSpec). See the chapter "File Manager" in Inside Macintosh: Files for a complete description of the file system specification record.
The LaunchApplication function sets the initial default directory of the application to the parent directory of the application file.
If it successfully launches the application, LaunchApplication returns, in the launchProcessSN field, a process serial number. You can use this number in Process Manager routines to refer to this application.
The LaunchApplication function returns the launchPreferredSize and launchMinimumSize fields of the launch parameter block. The values of these fields are based on their corresponding values in the 'SIZE' resource. These values may be greater than those specified in the application's 'SIZE' resource because the returned sizes include any adjustments to the size of the application's stack. See the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials for information on how the size of the application stack is adjusted. Values are always returned in these fields whether or not the launch was successful. These values are 0 if an error occurred--for example, if the application file could not be found .
The LaunchApplication function returns a value in the launchAvailableSize field only when the memFullErr result code is returned. This value indicates the largest partition size currently available for allocation.
The launchAppParameters field specifies the first high-level event sent to an application. If you set this field to NIL, the LaunchApplication function automatically creates and sends an Open Application event to the launched application. (See the chapter "Apple Event Manager" in Inside Macintosh: Interapplication Communication for a description of this event.) To send a particular high-level event to the launched application, you can specify a pointer to an application parameters record. The application parameters record is defined by the data type AppParameters.
TYPE AppParameters = 
   RECORD
      theMsgEvent:      EventRecord;       {event (high-level)}
      eventRefCon:      LongInt;           {reference constant}
      messageLength:    LongInt;           {length of buffer}
      messageBuffer:    ARRAY [0..0] OF SignedByte;
   END;
You specify the high-level event in the fields theMsgEvent, eventRefCon, messageLength, and messageBuffer.
Listing 2-2 demonstrates how you can use the LaunchApplication function.
Listing 2-2 Launching an application
PROCEDURE LaunchAnApplication (mySFReply: StandardFileReply);
VAR
   myLaunchParams:      LaunchParamBlockRec;
   launchedProcessSN:   ProcessSerialNumber;
   launchErr:           OSErr;
   prefSize:            LongInt;
   minSize:             LongInt;
   availSize:           LongInt;
BEGIN
   WITH myLaunchParams DO
   BEGIN
      launchBlockID := extendedBlock;
      launchEPBLength := extendedBlockLen;
      launchFileFlags := 0;
      launchControlFlags := launchContinue + launchNoFileFlags;
      launchAppSpec := @mySFReply.sfFile;
      launchAppParameters := NIL;
   END;
   launchErr := LaunchApplication(@myLaunchParams);

   prefsize := myLaunchParams.launchPreferredSize;
   minsize := myLaunchParams.launchMinimumSize;
   IF launchErr = noErr THEN
      launchedProcessSN := myLaunchParams.launchProcessSN
   ELSE IF launchErr = memFullErr THEN
      availSize := myLaunchParams.launchAvailableSize
   ELSE
      DoError(launchErr);
END;
Listing 2-2 indicates which application file to launch by using a file system specification record (perhaps returned by the StandardGetFile routine) and specifying, in the launchAppSpec field, a pointer to this record. The launchControlFlags field indicates that LaunchApplication should extract the Finder flags from the application file, launch the application in a partition of the preferred size, bring the launched application to the front, and not terminate the current process.
By default, LaunchApplication brings the launched application to the front and sends the foreground application to the background. If you don't want to bring an application to the front when it is first launched, set the launchDontSwitch flag in the launchControlFlags field of the launch parameter block.
In addition, if you want your application to continue to run after it launches another application, you must set the launchContinue flag in the launchControlFlags field of the launch parameter block. For a complete description of the available launch control options, see "Launch Options" on page 2-15.
If you want your application to be notified about the termination of an application it has launched, set the acceptAppDiedEvents flag in your 'SIZE' resource. If you set this flag and an application launched by your application terminates, your application receives an Application Died Apple event ('aevt' 'obit'). See "Terminating an Application" on page 2-11 for more information on the Application Died event.