zLaunch(TM) for Macintosh
User's Guide
Copyright © 1996-1997.
Zeus Productions. All Rights Reserved.
Welcome!
Thank you for your interest in zLaunch
for Windows, one of the many utilities for Macromedia Director available
from Zeus Productions. Please visit our
web site for more information on our products
for both Mac and Windows and custom
development services.
zLaunch seamlessly launches other applications from Director:
- If you need to launch other applications or documents...
- If you are tired of the flashing desktop...
- If you are running low on RAM using Lingo's
open
command...
Then zLaunch is for you! If you are not sure if zLaunch
is appropriate for you, consult our Needs
Analysis FAQ.
If you have purchased zLaunch for Macintosh, this package contains everything
you need to run zLaunch on both standard (680x0) Macs and PowerMacs, using
either Director 4.0.4 or 5.0.1. Director 6.0 will be supported when it ships.
zLaunch is also available in a Windows
3.1/95 version, sold separately. The zLaunch
for Windows User's Guide is included in this package as well.
zLaunch for Macintosh can be obtained by contacting
Zeus Productions Sales at:
Be sure to download
the latest End-User and Run-Time licensing agreements, as you are bound
by these agreements if you use zLaunch. Note specifically that Run-Time
distribution is royalty-free, but limited to five (5) commercial products
per copy of zLaunch. Also note that you must include the Zeus logo and copyright
information in your product(s). Refer to the licensing information included
with this package, or licensing
information on our web site for complete details.
For Technical Support:
Table of Contents
- Line 1 - Projector to kill
- Line 2 - Projector to wait for to die
- Line 3 - Application and document to launch
- Line 4 - Application to wait for
- Line 5 - Projector to re-launch
Line 6 - Wait Control
Line 7 - Delay Control
1. Introduction
A. Introduction
We know that zLaunch will help you to use external applications with Director
and we hope that you find zLaunch easy to use.
This User's Guide, the zLaunch FAQs
and the example Director movie have been heavily revised. Even if you
are familiar previous versions, you will benefit from numerous additional
tips and trouble-shooting hints provided throughout this
guide. The latest versions of the Zeus
TechNotes cited throughout this publication are available on our
web site where you'll also find the
latest zLaunch information.
When viewing the latest
version of this User's Guide on our web site, all hyperlinks will access
the latest information. When viewing this HTML file locally on your machine,
some hyperlinks will not work. For example, the links to glossary
terms are only available on our web site.
B. zLaunch Product Features
zLaunch facilitates launching executables from Director. It allows you to
quit Director, so you can launch demos even in low RAM situations, and then
restart Director when the launched executable completes.
While the launched application is running, zLaunch's desktop cover remains
in effect, similar to a Projector running in "full-screen" mode.
zLaunch allows you to use Director as a front end to a software sampler
or other executables such as demos, ReadMe files, Acrobat PDF files, or
a web browser.
zLaunch allows you to:
- Cover the desktop between applications
- Quit Director to free up RAM for the sub-launched application.
- Launch an application, with an optional document, and wait for it
to finish
- Return seamlessly to Director when your application finishes
zLaunch is truly amazing, and is available for both Macintosh and Windows
(sold separately).
C. Latest Features in zLaunch for Macintosh
zLaunch for the Macintosh now offers:
- Ability to open a document when launching an application
- Ability to launch an application by its Creator Code without knowing
its exact location
- Improved prevention of flashing of the menu bar when switching applications
- Vastly improved documentation, including user's guide with example
and trouble-shooting, and FAQ
Note that this User's Guide, the FAQs and the Director example movie
have been heavily revised. Even if you are familiar previous versions, you
will benefit from numerous additional tips and trouble-shooting hints provided
throughout this guide.
2. Installing and Using zLaunch
"zLaunch" is a single Fat Binary executable, which means it runs
on all types of Macs, and runs natively
on PowerMacs. You can use it with any Macintosh Director projector: "Standard
Macintosh" (680x0), "Power Macintosh Only" (PowerMac native),
or "All Macintosh Models" (Fat Binary).
zLaunch does not require a formal installation procedure. Simply include
zLaunch and one or more external configuration files in the same folder
as your Director movie and/or Projector from which it is called. zLaunch
can reside in any folder, but it is easiest if it is in the same folder
with the Director movie during development or your Projector during run-time.
zLaunch can run from either a hard drive or a CD. There is no
need to copy it into the System Folder, or similar requirement.
Include your zLaunch configuration file in the same folder
with zLaunch, unless you are creating your configuration file
dynamically.
A. zLaunch on Standard (680x0) Macs
As stated above, there is a single Fat Binary version of zLaunch for all
Macs.
Naturally, you cannot run a PowerMac-only projector on a 680x0 Mac, nor
can zLaunch launch a PowerMac-only application on a 680x0 Mac.
You must either create a 680x0-compatible or Fat Binary version of the projector.
You must launch a 680x0-compatible or Fat Binary version of the external
executables, or, warn the user if the application only works on PowerMacs.
Important Note when using Fat Projectors on Standard Macs:
If you build a Fat projector, the process name when it is run on a Standard
Macintosh will always be "Projector". The internal name "Projector"
does not change even when you change the Projector's file name. The best
solution is the leave the Projector named "Projector", and refer
to this name on lines 1, 2 and 5 of your configuration file (see below).
You can create an alias to your projector and give the alias the name
you want your users to see.
B. zLaunch on PowerMacs
As stated above, there is a single Fat Binary version of zLaunch for all
Macs.
PowerMacs can run any type of Macintosh-compatible application, and zLaunch
can launch either native or non-native applications.
For optimal performance one would either run a Fat Binary or PowerMac version
of the executable(s) but you can also run a Standard (680x0) Mac executable.
C. Note for zLaunch for Windows Users
Due to differences between the two operating systems, the zLaunch calling
sequence is different under the two platforms. Be sure to consult the example
Director movie, and the zLaunch
for Windows user's guide separately for details.
Due to differences between the two operating systems, there are some notable
differences between zLaunch for Macintosh and zLaunch for Windows. Be sure
to consult the example Director movie, and the zLaunch
for Windows user's guide separately for details. Please note:
- The parameters required by zLaunch are similar but not identical on
the two platforms.
- zLaunch for Windows uses an INI file (a different format than the
Macintosh configuration file) to provide parameters to zLaunch. zLaunch
for Windows also supports passing the parameters via Lingo, which is not
supported on the Macintosh. Refer to the TechNote, "Creating Files
Dynamically".
- The syntax for path specifications is different under the Mac OS and
Windows. Refer to the TechNote, "File
and Path Specifications".
- zLaunch for Windows requires you to quit your Projector using the
Lingo
quit command, whereas zLaunch for Macintosh will
quit your projector for you (refer to the parameter specified on Line
1).
- zLaunch for Macintosh can launch an application based on its Macintosh
Creator Code, a feature that
is not supported under the Windows OS. zLaunch for Windows requires that
you specify the path to the application to be launched. zOpen
for Windows will locate an executable based on its association with
a Windows file extension or file type. Refer to the TechNote,
"File Types, Extensions and Creator
Codes".
3. Creating your Projectors
You can use zLaunch with Director 4, Director 5, or Director 6 (when it
ships).
A. Director 4.0 Projectors
When using Director 4.0, upgrade to Director 4.0.4, which fixes numerous
bugs and allows you to build Fat Binary Projectors. Be sure to complete
the update properly, as an improper updating of resource files can lead
to faulty projectors.
Refer to the Zeus
TechNote, "Creating Director
Projectors for Macintosh and Windows", for details on the different
projector types, and how to cover the Macintosh Desktop from within a projector.
B. Director 5.0 Projectors
When using Director 5.0, upgrade to Director 5.0.1, which fixes some bugs
in Director 5.0. Be sure to complete the update properly, as an improper
updating of resource files can lead to faulty projectors. If using FileIO,
obtain the latest version of the FileIO Xtra, as the one that shipped with
Director 5.0 was a beta version and had numerous bugs.
Refer to the Zeus
TechNote, "Creating Director
Projectors for Macintosh and Windows", for complete details on
projector options.
C. Director 6.0 Projectors
Director 6.0 will be fully supported when it ships. Zeus Productions will
make every effort to address any issues that arise with the new version
of Director. If you are aware of any such issues, please send
e-mail to Zeus.
D. Creating a Stub Projector
A "Stub Projector" is a small projector that references external
assets, including external DIR or DXR files. Stub Projectors are STRONGLY
recommended. Refer to the Zeus
TechNote, "Creating and Using Stub
Projectors", for complete details on creating stub projectors.
4. Passing Parameters to zLaunch
To control zLaunch on the Macintosh, you must specify a configuration file
(described below) that contains the parameters needed to launch your particular
application.
This configuration file is an ASCII text file, created in SimpleText. You
must create a separate configuration file for each different application
you launch with zLaunch. (zLaunch for Windows allows multiple sets of
parameters in a single INI file)
NOTE: Due to differences in the operating systems, zLaunch for Macintosh
uses a different method than zLaunch for Windows to specify its parameters.
The format of the Macintosh configuration file is different than the format
of the Windows configuration (INI) file. Refer to the zLaunch
for Windows User's Guide.
Furthermore, you can not use the parameterList method (available in zLaunch
for Windows) with zLaunch for the Macintosh. Refer to the TechNote "Creating
Files Dynamically" for more information on dynamically
setting the parameters. This is demostrated fully in the example DIR file.
A. Calling zLaunch from Lingo
To initiate zLaunch, use Lingo's "open...with" statement,
of the form:
open the pathName & "configFile" with the pathName &
"zLaunch"
Where configFile is the name of the configuration file described
in detail below.
Once you have created a configuration file, you can run zLaunch using the
following Lingo syntax:
open the pathName & "myConfigFile" with the pathName
& "zLaunch"
NOTE: You must substitute in the name of your configuration file in place
of "myConfigFile". This example assumes that the
configuration file and zLaunch are in the same folder as your Director movie,
as indicated by the Lingo property "the pathName".
B. Structuring your Director Movie
When the user clicks a button to launch an external application, you would
ordinarily do the following:
- Jump to a frame with a black stage, and switch to the Macintosh System
Palette
- Call zLaunch as described above from a Frame Script
- Wait in a subsequent frame for the projector to be killed by zLaunch.
For a full-blown example, refer to the ZLAUNCH.DIR example Director file.
Once zLaunch is started using Lingo's "open"
command, you should wait in the next frame for zLaunch to kill the projector.
You must NOT wait in a tight repeat loop. Wait in a frame using
"go the frame" instead:
on exitFrame
go the frame
end
5. Configuration File Format
The configuration must contain exactly seven line, with the parameters as
follows:
- Line 1 - Name of Projector (process) to
be killed by zLaunch, or "NONE"
- Line 2 - Name of Projector (process) to
wait for to die, or "NONE"
- Line 3 - Name of Executable and optional
document to be launched
- Line 4 - Name of Launched executable (process)
to wait for to terminate
- Line 5 - Complete Path to Projector to be
relaunched
- Line 6- Relaunching delay control - "WAIT"
or "NOWAIT"
- Line 7 - Delay time before quitting
zLaunch, in seconds
A. Example Configuration File
Several example files are provided in the Example Config Files folder. A
typical file may look like this:
MyProjector
MyProjector
HD:Desktop Folder:launchTest:SimpleText
SimpleText
HD:Desktop Folder:launchTest:MyProjector
WAIT
2
Here is a line-by-line explanation of this sample configuration file
Line 1 - Kills the process called "MyProjector"
(this is your Projector without any path)
Line 2 - Waits for process called "MyProjector"
(i.e. the projector named above) to die
Line 3 - Starts up SimpleText, located
at:
"HD:Desktop Folder:launchTest:SimpleText"
Line 4 - Waits until SimpleText is
terminated (presumably by the user).
Line 5 - Re-launches the projector located at
:
"HD:Desktop Folder:launchTest:MyProjector"
Line 6 - Waits for that projector to indicate
that it is started up
Line 7 - Waits an additional two seconds before
dismissing the black window that covers the desktop, and killing zLaunch.
B. Detailed Parameter Explanation
Each line in the configuration file corresponds to a parameter to be passed
to zLaunch. Below is a detailed explanation of each line of the configuration
file.
Line 1 - Name of the Projector (Process) to be Killed
by zLaunch, or "NONE"
The parameter on line 1 allows zLaunch to cover the desktop before killing
the projector in order to prevent the flash of the desktop. Line 1 should
contain the name of your projector that zLaunch should kill.
Technically, this is the task name or "process name" which zLaunch
should kill. This should be the name of your Projector as shown by its Finder
icon, excluding the path name. Do NOT include the file path to the projector
on this line. Use the projector's name, and NOT the name of the current
Director movie.
Important Note when using Fat Projectors on Standard Macs:
If you build a Fat projector, the process name when it is run on a Standard
Macintosh will always be "Projector". The internal name "Projector"
does not change even when you change the Projector's file name. The best
solution is the leave the Projector named "Projector", and refer
to this name on lines 1, 2 and 5 of your configuration file (see below).
You can create an alias to your projector and give the alias the name you
want your users to see.
Specify the special word NONE if you do not want zLaunch to kill
the projector (i.e. to leave the projector running). In this case, you may
want to quit the projector via Lingo manually, or not at all.
This is also useful for debugging when you are testing zLaunch from the
Finder. Refer to the debugging section below.
You should NOT quit the projector via Lingo if you are specifying that zLaunch
should kill it for you. Otherwise, the desktop may flash.
Do NOT allow any extraneous spaces on the line, as zLaunch is "whitespace-sensitive".
Do not use quotes around the text. "NONE" should be in all capital
letters, but the projector name is not case-sensitive.
Line 2 - Projector (Process) to Wait for to Die, or
"NONE".
Once zLaunch attempts to kill your projector, it may take several seconds
before the projector actually dies. Line 2 ensures that the projector has
died before zLaunch launches the secondary application, such as a demo.
This option gives the Projector a chance to quit in order that it frees
up RAM and releases system resources such as control over the palette.
Line 2 should contain the name of the process which zLaunch should wait
for to die.
This should ordinarily be the same as line 1, the name of the Projector,
excluding the path (process names don't include the path). Do NOT include
the file path to the projector on this line. Use the projector's name,
and NOT the name of the current Director movie.
Important Note when using Fat Projectors on Standard Macs:
If you build a Fat projector, the process name when it is run on a Standard
Macintosh will always be "Projector". The internal name "Projector"
does not change even when you change the Projector's file name. The best
solution is the leave the Projector named "Projector", and refer
to this name on lines 1, 2 and 5 of your configuration file. You can create
an alias to your projector and give the alias the name you want your users
to see.
If for some reason, you want to launch the secondary executable immediately,
specify NONE. This will prevent zLaunch from explicitly waiting for
the projector to die (although line 1 can still specify the projector to
be killed). In that case, the RAM in use by Director may not yet be available
to your executable.
Do NOT allow any extraneous spaces on the line, as zLaunch is "whitespace-sensitive".
Do not use quotes around the text. "NONE" should be in all capital
letters, but the projector name is not case-sensitive.
Line 3 - Application and Optional Document to be Launched.
Line 3 specifies the application for zLaunch to launch, plus an optional
document name. The proper format for this line depends on what parameters
you want to pass to zLaunch. There are three possible formats for this line,
depending on whether you need to launch:
Do NOT allow any extraneous spaces on the line, as zLaunch is "whitespace-sensitive".
Do not use quotes around the text. The application path is not case-sensitive.
Refer to the Zeus
TechNote, "Path and File Specifications"
for details on specifying a Macintosh file path.
A. Application in a Known Location without a Document
To launch an application in a known location without a document, simply
specify the full path to the application to be launched.
The general syntax is:
applicationPath:applicationName
The following example would run the application "MyDemo"
located in the "MyFolder" folder on the disk named
"MyCD":
MyCD:MyFolder:MyDemo
Refer to the example configuration file "Netscape No Doc" which
launches Netscape, as found by the complete path specification, without
a document.
B. Application in a Known Location with a Document
(This option is supported as of version 1.12 )
To launch an application in a known location with a document from a known
location, use the keyword OPEN, followed by the full path to the
application to be launched, followed by the full path to the document
to be opened. Separate the parameters with forward slashes ("/").
The general syntax is:
OPEN/applicationPath:applicationName/documentPath:documentName
The following example would open the document "ReadMe"
located in the "MyDocs" folder on the disk named "MyCD"
with the application "SimpleText" located in the
"MyApps" folder on the disk named "MyCD":
OPEN/MyCD:MyApps:SimpleText/MyCD:MyDocs:ReadMe
Slashes are used to separate the parameters because spaces, colons and commas
can be part of a Macintosh file names or path. Do NOT allow any extraneous
spaces at the beginning or end of the line, nor between the parameters or
adjacent to the slashes. Do not use quotes around the parameters. "OPEN"
should be in all capital letters, but the application and document paths
are not case-sensitive. Be sure to include any special characters, such
as the trademark symbol (tm) from the application's path or name.
Refer to the example configuration file "Netscape by path w/Doc"
which launches Netscape, as found by the complete path specification, and
a document, also specified by its complete path.
Using "OPen" (last two letters lowercase) instead of "OPEN"
will cause zLaunch not to hide the menu bar, if applicable.
C. Application in an Unknown Location with a Document
from a Known location
(This option is supported as of version 1.12 )
On the Macintosh, each file contains a unique, hidden Creator
Code or "signature". zLaunch can use this Creator Code to
locate the application and launch it. Refer to the Zeus
TechNote, "File Types, Creator
Codes and Extensions"
To launch an application from an unknown location with a document from a
known location, use the keyword OPSG (OPen SiGnature)
followed by the Creator Code of the application to be launched, followed
by the full path to the document to be opened. Separate the parameters
with forward slashes ("/").
The general syntax is:
OPEN/creatorCode/documentPath:documentName
The following example would open the document "ReadMe"
located in the "MyDocs" folder on the disk named
"MyCD" with the application whose Creator code is
"ttxt" (in this case SimpleText):
OPSG/ttxt/MyCD:MyDocs:ReadMe
Slashes are used to separate the parameters because spaces, colons and commas
can be part of a Macintosh file names or path. Do NOT allow any extraneous
spaces at the beginning or end of the line, nor between the parameters or
adjacent to the slashes. Do not use quotes around the parameters. "OPSG"
should be in all capital letters, and the Creator Code is case-sensitive.
The document path is not case-sensitive.
Not also that Creator Codes are always exactly four characters. Some
Creator Codes may be three letters followed by a space, which is mandatory.
Using "OPsg" (last two letters lowercase) instead of "OPSG"
will cause zLaunch not to hide the menu bar, if applicable.
Refer to the example configuration file "Netscape by Sig (Creator)
w/Doc" which launches Netscape Navigator, by it's Creator Code ("Signature
Code"), which happens to be "MOSS", with a document, specified
by its complete path.
Note:
- You need to know the name of the executable, because in line
4 (see below), you must specify the process name to wait for.
- You must specify the complete path to the document. If the application
does not ordinarily require a document, you must still use one, creating
a dummy one if necessary.
- You'll need to know the Creator Code of any application which you
wish to locate using the OPSG method. Refer to the Zeus
TechNote, "File Types, Creator
Codes and Extensions"
Line 4 - Launched Process to Wait for to Terminate
Once zLaunch launches your executable, you want it to wait for that process
to terminate.
Line 4 specifies the name of the launched executable that zLaunch should
wait for before relaunching the projector, allowing the user to interact
with the launched application at their leisure.
zLaunch simply waits in the background while this process is still active.
Once the specified process terminates, zLaunch will attempt to relaunch
the projector specified in line 5.
Technically, this is the task name or "process" name for which
zLaunch should wait. Typically the user must terminate the launched application,
although some applications may terminate automatically.
This is ordinarily the name of the launched application that was specified
in Line 3, excluding the path (process names don't include the path).
If for some reason, you do not want zLaunch to wait while the secondary
executable is active, specify NONE. This will prevent zLaunch from
explicitly waiting for the application. In that case, the RAM in use by
the application may not yet be available to relaunch your projector.
Do NOT allow any extraneous spaces on the line, as zLaunch is "whitespace-sensitive".
Do not use quotes around the text. "NONE" should be in all capital
letters, but the application name is not case-sensitive. Be sure to include
any special characters, such as the trademark symbol (tm) from the application's
name.
Note: You need to know the name of the executable, even if you launched
it using its Creator Code on Line 3.
Line 5 - Complete Path to Projector to be Relaunched
Line 5 specifies the name of the projector, including the path, to re-launch
when the launched application is exited by the user. (NOTE: This can be
different from the original projector, but is usually the same as lines
1 and 2, with the addition of the full path specification).
If for some reason, you do not want zLaunch to re-launch the projector,
specify NONE. In that case, zLaunch will simply terminate to the
Finder.
Do NOT allow any extraneous spaces on the line, as zLaunch is "whitespace-sensitive".
Do not use quotes around the text. "NONE" should be in all capital
letters, but the projector path is not case-sensitive. Be sure to include
any special characters, such as the trademark symbol (tm) from the projector's
name.
Refer to the Zeus
TechNote, "Path and File Specifications"
for details on specifying a Macintosh file path.
Line 6 - Relaunching Delay Control - "WAIT"
or "NOWAIT"
Line 6 controls whether zLaunch waits for the re-launched Projector to start
up again. This parameter is used ensure that the projector specified in
Line 5 has started before zLaunch kills itself.
Because applications may take a few seconds to start up, this parameter
helps prevent zLaunch from dismissing the desktop-covering black window
too early.
If you specify the keyword WAIT, zLaunch waits until the application
specified on Line 5 has started. If you specify the keyword NOWAIT,
zLaunch continues immediately once it relaunches the projector. Refer to
the parameter for Line 7 below.
Line 7 - Time Delay before Quitting zLaunch
Line 7 specifies the time delay (in seconds) to wait AFTER re-launching
the projector (as specified in Line 5) before zLaunch kills itself and its
desktop-covering black window.
Some applications do not take control of the screen as soon as they start.
In the case of Director, it does not cover the desktop immediately.
This parameter prevents zLaunch from dismissing the desktop-covering black
window before the projector opens a window to cover the desktop.
Start with a time delay of 2 (seconds), and adjust it as necessary.
6. Trouble-Shooting
The first step towards fixing a problem is to determine its exact nature.
To say "it doesn't work" is not very helpful. Try to narrow down
the problem by determining what does work, which will leave you with
a better understanding of where the problem lies.
A. Testing the External Application and Document
Before trying to launch an application from zLaunch, you should test it
from the Finder by double-clicking the application and verifying that it
performs as expected.
If the application does not work in the Finder, it will not work with zLaunch.
You may not be able to launch an application because:
- The file is not actually an application. Some installer documents
appear to be applications, whereas the real application is a different file.
Check that the file's File Type
is "APPL".
- The file is an application, but its File
Type is not "APPL".
If the file is truly an application, use ResEdit
to change its File Type to "APPL".
- The application is corrupted. Try re-downloading or re-installing
it.
- There is an extension conflict. Restart without extensions by rebooting
while holding down the SHIFT key.
- There may not be sufficient RAM to run the application. Try lowering
both the minimum and preferred memory allocations, in the "Get Info"
window. Many systems automatically start up applications every time the
computer boots. Quit all other running applications. Increase the Virtual
Memory settings, or preferably, install more RAM.
- It is a PowerMac application and you are trying to run it on a Standard
(680x0) Mac
- The application requires some component or extension that is not installed,
such as QuickTime or Adobe Type Manager. Re-install if necessary.
If the application works, also try double-clicking the document, if any,
that you are attempting to open via zLaunch. Verify that it launches the
correct application. Also, try opening the document from the application
using the "File...Open" command. Lastly, try dragging and dropping
the document onto the application in the Finder.
If the document does not work from the Finder, it will not work with zLaunch.
You may not be able to open a document because:
- It is not actually a document. Some installer applications appear
to be documents, whereas the real document is a different file.
- The document is corrupted. Try re-downloading or re-installing it.
- The application may not be able to open that particular document type.
- The document type is not set correctly. This is especially likely
if the file has been copied from a PC to the Macintosh. or downloaded from
a server. Set the document's File Type correctly with ResEdit or a utility
such as Drop-Info. Refer to the Zeus
TechNote, "File Types, Creator
Codes and Extensions".
- The required application or some of its components are not installed.
Re-install if necessary.
B. Verifying the File Paths
If the application and its document work from the Finder, try starting them
from Director's message window using Lingo's "open"
or "open...with" command. (Note that the document
name precedes the application name when using the "open...with"
command, ).
For example, to verify that you have the correct path to SimpleText, try
launching it using something like:
open "HD:docs:ReadMe" with "HD:Applications:SimpleText"
Likely sources of error include:
- Missing or incorrect drive name
- Omitting one or more folder names within the path
- Incorrect path separators. Use colons (:) to separate items in the
path
- Misspelled file or folder names
- Mistyped files or folder names
- Extraneous spaces at the beginning, middle or end of a file path
- Hidden "control" characters or missing special characters
in the file paths
- Improper path to items on the Macintosh Desktop.
- Referring to an alias, which is not supported.
Refer to the Zeus
TechNote, "Path and File Specifications"
for details on specifying a Macintosh file path.
C. Verifying Operation with zLaunch from the Finder
If you have determined the correct path to the application and the document,
you are ready to verify its operation with zLaunch.
First, verify that zLaunch itself is working by double-clicking the zLaunch
executable in the Finder. It should black out the entire screen, and the
screen should stay black until you hit Command-Q to quit zLaunch. If this
does not work, refer to the list of possible sources of error in section
A, "Testing the External Application and Document",
above. The most likely source of error is a file that was corrupted during
the download or while copying it from another machine over a network.
D. Verifying your Configuration File from the Finder
If both zLaunch and your external application appear functional, you should
test your configuration file in isolation of your Director Projector. First,
quit all other applications. Then, drag and drop your configuration file
onto the zLaunch icon. (The configuration file must have a file Type of
"TEXT". Refer to the Zeus
TechNote, "File Types, Creator
Codes and Extensions".) If you can't drag and drop the configuration
file onto zLaunch, make sure that the configuration file was created in
SimpleText. Also try rebooting and rebuilding your desktop.
zLaunch should attempt to launch the application specified in line 3 of
your configuration file. It should then wait for that application to run,
as specified by line 4 of your configuration file.
zLaunch may not work with aliases or with hidden files. If you are using
an alias or a hidden file, test it first with a normal file.
Most of the example configuration files use "NONE" as the projector
name, so that you can debug the launching of the application without repeatedly
running your projector.
Once you can successfully use zLaunch from the Finder, add your projector
name to the configuration file. Refer to the discussion of Lines 1, 2 and
5 of the configuration file for details.
If Lines 3, 4, 5, 6 and 7 of your configuration file are correct, from the
Finder, zLaunch should launch the specified application, wait for it to
terminate, and then re-launch the projector.
E. Verifying your Lingo Code
Once you have verified that lines 3 through 7 of your configuration file
are correct. You can test zLaunch from your Projector. Common sources of
error include:
- Your call to zLaunch is never being reached. Set a breakpoint in the
debugger to verify that Lingo is executing the lines of code that you think
it is. If zLaunch is working, you should see it cover the desktop. Use the
demo version of zLaunch (included) which includes an easily visible Zeus
wallpaper pattern.
- Your call to zLaunch is incorrect. Verify the syntax based on the
examples, and documentation in section 4, Passing Parameters
to zLaunch. Verify the path to the configuration file and the path to
zLaunch.
- Your configuration file has errors. Refer to the series of debugging
hints below.
7. Debugging FAQ
Below are listed some common problems, and their most likely solutions.
Problem: zLaunch seems to crash immediately.
You may be running the wrong executable, or
there may have been a problem with the download. Make sure that you have
the latest version of zLaunch and download it again if necessary.
Test the external application and zLaunch from the Finder as described above
to verify their basic operation.
Problem: zLaunch never launches the external application
If zLaunch does not launch your application,
there are several distinct possibilities:
- If zLaunch's cover screen never appears, it is never being started.
If not, refer to section E, "Verifying
your Lingo Code" above.
- If zLaunch's cover screen appears, then zLaunch is at least being
started. If nothing happens from that point on, there are several possibilities:
There is some sort of error in Line 3 of your configuration file. Refer to the section, "Line 3 - Application
and Optional Document to be Launched".
Test zLaunch from the Finder as described above to verify its basic operation.
Common sources of error include:
- Incorrect path to application or document to be launched
- Forgetting to specify the complete path to the executable when using
the standard or OPEN (Open with document) method. You must specify the complete
path to the executable in order for zLaunch to find it.
- Specifying the wrong Creator Code (Signature) when using the OPSG
(OPen by SiGnature) method. The Creator Code is CASE-SENSITIVE and must
be EXACTLY four characters. Refer to the Zeus
TechNote, "File Types, Creator
Codes and Extensions".
Specifying the incorrect path to the executable or document. For example,
the path to Netscape Navigator often includes the trademark symbol (tm).
Note that you must include the trademark symbol as it appears (The actual
Macintosh (tm) symbol is not supported by HTML, so it cannot be shown here.).
You can either cut and paste the character from the Netscape Navigator file
name, or create it using Option-2 on your keyboard. Also beware of missing
or extraneous spaces, especially at the beginning or end of file names where
they may not be noticeable.
- There may not be sufficient RAM to launch your application. Be sure
to instruct zLaunch to kill the projector. (Refer to line 1 and 2 of the
configuration file). If your system still has insufficient RAM, be sure
that all other applications are closed, and try lowering the minimum and
preferred required RAM for your application. For example, if the application
requires 16 MB of RAM, it will not run on an 8 MB system. Don't forget that
the Finder/System requires some RAM. You can check memory usage by choosing
"About the Macintosh..." under the Apple Menu (at the left side
of the menu bar) when the Finder is in the foreground.
Problem: zLaunch never quits the projector
The problem is either a syntax error in your
configuration file, or a problem with you Lingo technique.
Be sure to check the following:
- Line 1 of the configuration file must be the exact name of your projector,
excluding the path. If your projector is called "MyProjector",
then use "MyProjector" (Without the quotes) on Line 1 of your
configuration file.
- When specifying the path to the application, it must point to an executable,
not an ALIAS to an executable.
- Your projector may not be giving zLaunch the opportunity to quit it.
Test it with the example projector provided.
- Lingo does not always behave as one would expect when using the "open"
command and jumping to a frame. You should start zLaunch with the Lingo
"open" command inside a brief handler as described in the Lingo
example above.
- While waiting for zLaunch to kill the projector, do NOT wait in a
repeat loop or use the Tempo channel's "wait" option. Wait using
"go the frame" instead, as described in the Lingo example above.
Problem: There is a palette flash or other conflict when zLaunch launches
the application.
The likely cause is that you are not properly
waiting for the projector to die before launching the application. This
is controlled via Line 2 of the configuration file. This line tells zLaunch
to wait until the projector has died before proceeding. Line 2 of the configuration
file should ordinarily be the same as line 1 of the configuration file.
Problem: The projector restarts immediately after zLaunch launches the
first application.
For some reason, zLaunch is not waiting
for the launched application to terminate as you would expect.
There are two common causes:
- You did not properly instruct zLaunch to wait for the launched application
to terminate. This is controlled via Line 4 of the configuration file. Specify
the name of the executable, excluding the path, for which zLaunch should
wait. Refer to the discussion of this parameter above, and to the example
files.
- The launched application has in fact terminated. If this is the case,
the launched application may be a "stub" application which simply
launches a second application and then terminates. zLaunch detects this
termination and relaunches the projector. zLaunch does not work properly
with applications that in turn launch other applications and then quit themselves.
Consult the FAQ
on our web site for more information and possible work-arounds.
Problem: The application launches, but then it says it can't find some of
its assets or components.
Be sure that all of the components for the
application are present and in the required folder(s). Some applications
require hidden files which you may have accidentally omitted, or require
files to be in a certain location. Test the application separately from
zLaunch to verify its operation.
Verify the path to the executable to be sure you are running the desired
copy.
Problem: The application launches, but the document doesn't appear.
zLaunch is probably having trouble finding
the document:
- Specify the full path to the document as part of Line 3, using the
OPEN or OPSG method.
The document should be the third item on Line 3. The first item is either
OPEN or OPSG, followed by a slash, and then the executable's path or Creator
code, followed by another slash, and then the document name.
- ·Be sure that the specified document has a File
Type that is recognized by the application. Try dragging the document
onto the application in the Finder to see if it will read that document.
Refer to the TechNote, "File
Types, Creator Codes and Extensions"
Problem: The Projector starts from the beginning. How do I restart the projector
in the frame in which it left off?
A projector can only start at its beginning,
but you can simulate the desired behavior in one of two ways.
If you just need to return to a main menu, the easiest technique might be
to build a second projector which goes to the desired frame automatically.
Be sure to build just a "stub" projector, that just performs "go
frame x of movie y" in the first frame of the score.
It is generally a good idea to create stub projectors for all your projects.
Refer to the Zeus TechNote, "Creating
and Using Stub Projectors" for more information on stub projectors.
A second, more complicated technique is required to restart a projector
wherever it may have left off. Refer to the Zeus TechNote, "Restoring
the Projector State" for more information.
Problem: The menu bar at the top of the screen flashes.
If your application does not have any menu
resources, the Macintosh menu bar may flash when switching between applications.
Use a resource editor, such as ResEdit,
to copy the "mctb" resources
from zLaunch's resource fork
into the resource fork of your application. Be sure to make a backup copy
of both zLaunch and your application first.
Problem: There is a colored border around the stage area just before
the projector quits.
The color in palette position 120 is used to
draw a thin outline around the stage. If this color is bright, it will be
readily visible.
Use a Director palette with a dark color in position 120, so that the outline
is not as apparent. Instead of pure black, use an off-black color, such
as one with 1% values for Red, Green and Blue.
Problem: The screen goes black as zLaunch starts up and after a couple
of seconds, it quits and goes back to the Finder of the Projector.
There are a few possibilities:
- zLaunch can not find the application you are trying to launch. Verify
its path or Creator Code if using the OPSG method.
- You are launching an application which quits when it can't find an
appropriate document. Verify the path to the document. You must specify
a document to open when using the OPSG and OPEN command or it will behave
as described. If you do not want to specify a file, use the "plain"
method, without specifying OPEN or OPSG. If you really want to use OPSG,
but don't have a file to open, create a dummy file.
Q. Can I specify the OPSG or OPEN command without a file to open?
The OPSG command works only with a file. If
you do not want to open a file, don't use the OPEN command. Just specify
the application name alone on line 3 of the configuration file.
Q. What if the applications I need to open does not have a file to open?
Create a dummy resource-only file using ResEdit.
Set the Creator Code to match your application that you are launching.
Q. What if I am still having problems?
If you are still having problems:
- The most common error is an incorrect file name or file path. Verify
and physically retype the paths to make sure that they are correct.
Make sure that there are no extraneous spaces in the file paths.
- If using the OPSG method, the Creator Code is case-sensitive and must
be exactly four characters..
- Consult the example Director movie, and be sure that you understand
the Lingo involved
- Re-read this documentation, and be sure to follow the instructions
explicitly
- Try to determine exactly what is working and what is not. Then consult
the list of debugging questions once you have narrowed down the problem.
- Test on a system that is as "clean" as possible. Quit all
other applications. Temporarily disable other Xtras or XObjects. Reboot
using minimal extensions to reduce potential sources of conflict. You can
either hold down the shift key when re-booting to disable all extensions,
or use the Extensions Manager Control panel to disable extensions selectively.
- Test on another machine to determine if the problem is machine-specific.
- Test it on a machine with a well-tested version of the Mac OS. Avoid
older versions, or brand new untested versions, or systems with beta software
installed.
- Test on both a PowerPC and a 68K Macintosh to see if it is peculiar
to one machine
- Test a 68K Projector, a PowerMac-only Projector and a Fat Binary Projector
to determine if the problem is projector-specific.
- Test with a different application to determine if the problem is application-specific
- Test with different RAM allocations to determine if the problem is
memory-related. Be sure to shut off RAM Doubler and turn off Virtual
Memory.
- Make sure that you have the latest version of Director and/or zLaunch
installed. Re-install if necessary.
- Consult the zLaunch FAQ on
our web site which may answer your question, or at least point you in the
right direction
- Perhaps you are attempting to use zLaunch in an unsupported manner,
and a newer version or separate product may meet your needs.
- Before pulling your hair out, contact our World-Class technical
support at info@zeusprod.com
or 1-908-398-1682. We are very helpful.
Good luck in all your multimedia pursuits.
Zeus Productions
Last Updated 05/01/97
Copyright © 1996-1997. Zeus Productions. All Rights Reserved.
###