Debugging Projectors Using the traceLogFile

August 24, 1999
by Will Turnage

Inevitably, at one point in your career you'll have the chance to work on an incredibly cool project. This one will be different from the plain presentations and static lessons that are the bread and butter of your business. Face it, this project will rock. You'll test it to death, run it through exhaustive Q/A and finally send the gold master to your client for approval. After all that, you'll get a call from the client the next day saying the three words you dread most -- "it keeps crashing".

Fine. Let's go through the basics, you tell the client. Are there other applications open, did you run the installer properly, did you restart the machine? Yes, I did all those, but it still isn't working.

Lucky for you, Director 7 has some built in functions to help you debug your projects after you've created the projector. (Much of this lingo was available in previous versions of Director, but in authoring mode only.)

The Illegal Unsupported Way

One of the quickest ways to debug projectors is to open up your director.ini file, and add these two lines of code to it:

[Settings]
MessageWindow=1

Now when you relaunch your projector, it will open up a companion message window where you can check the value of global variables, call handlers, test objects, and watch the process of the program. Before you jump for joy, though, there's a catch.

This setting in the director.ini file is undocumented and unsupported by Macromedia, so if it causes any problems with your projector, it's your own fault and Macromedia won't help you. More importantly, this solution requires you to be sitting in front of the computer that keeps crashing. For many of us with clients in other cities or even other countries, this isn't always a possibility. Luckily, there are other options.

The Legal Macromedia Way

Lingo has two functions to help debug your projectors. They are:

the traceLoad
the traceLog

'the traceLoad' is a movie property that tells Director how much information to print in the Message Window when your cast members are loaded and purged from memory. You can set the traceLoad to one of three possible values: 0, 1, 2. If you include in your code

the traceLoad = 0

Director will not give you any information about loading cast members. This is the default setting for the traceLoad. If you set

the traceLoad = 1

Director will print in the Message Window one line of text telling you that a cast member has been loaded or purged. Here's some sample output:

member 1 of castLib 1 ("testMember1") was loaded into memory.
member 1 of castLib 1 ("testMember1") was purged from memory.
member 2 of castLib 1 ("testMember2") was loaded into memory.
member 2 of castLib 1 ("testMember2") was purged from memory.

When you set

the traceLoad = 2

you get extremely verbose information in the Message Window that looks like this:

Time = 3342 msec (3342 msec later).
Movie "traceTest" is on frame 10 (freeBytes = 68912948).
member 1 of castLib 1 ("testMember1") was loaded into memory.
Member is in movie "C:\DOUG\traceTest.dir" 
File seek info: Seeked between files!  
Seeked -31403 to find member at file pos 15398.  Read in 3619 bytes.
Time = 3873 msec (531 msec later).
Movie "traceTest" is on frame 17 (freeBytes = 68920784, 7836 bytes released).
member 1 of castLib 1 ("testMember1") was purged from memory.
Member is in movie "C:\DOUG\traceTest.dir" 
File seek info: No file access occurred.
Time = 4066 msec (193 msec later).
Movie "traceTest" is on frame 20 (freeBytes = 68912948, 7836 bytes consumed).
member 2 of castLib 1 ("testMember2") was loaded into memory.
Member is in movie "C:\DOUG\traceTest.dir" 
File seek info: Seeked 1883 to find member at file pos 20900.  Read in 6554 bytes.
Time = 4601 msec (535 msec later).
Movie "traceTest" is on frame 27 (freeBytes = 68920784, 7836 bytes released).
member 2 of castLib 1 ("testMember2") was purged from memory.
Member is in movie "C:\DOUG\traceTest.dir" 
File seek info: No file access occurred.

You'll notice that for each event, Director provides you with several pieces of information.

1. The time, in milliseconds, when each memory event occurred and the amount of time since the last memory event
2. The active movie name
3. The current frame number
4. The current freeBytes, including how many bytes were consumed or released
5. The member number, castLib, and name
6. Whether this member was loaded into or purged from memory.
7. The full path name of your movie
8. How far Director had to seek (on your hard drive or CD-ROM) to find the cast member.

This last bit of information helps when testing CD-ROM projects with large media elements. Often developers will discover huge lags in their program after they've been burned to CD-R. More often than not, the cause is Director seeking across the CD-R to find these large media elements.

'the traceLogFile' is a lingo system property that writes the output of the Message Window to a text file. Essentially, you set the traceLogFile equal to a file name, such as

the traceLogFile = 'debug.txt'

and Director will take all of the output it sends to the Message Window and write that to the file name you specified. If you set

the traceLogFile = EMPTY

then Director stops writing events to the text file you've named.

Putting it all together

So how does this lingo help you debug? If you don't document your code at all, the least you'll get is a detailed report from the traceLoad about your cast members loading in and out of memory. But to really take advantage of the traceLogFile, you have to change the way you document your code. For instance, a simple behavior in your code might look like this:

on mouseUp
  -- Received the mouseUp event
  nothing
end

But by changing your documentation to use the put statement

on mouseUp me
  put ("Sprite" && me.spriteNum && "received the mouseUp event")
end

you'll see many improvements. Unlike your original documentation, this new way of documenting code provides you with more detailed information. You can print the status of global variables and objects, and include information about sprites, members, and castLibs. More importantly, this method of documenting works great with the traceLogFile. So when your client's projector keeps crashing, you can create a new lingo.ini file like this one:

on startUp
  the traceLogFile = the applicationPath & "debug.txt"
  the traceLoad = 2
End

The client can then replace the lingo.ini file and launch the projector. Director will now write all of your documentation (including verbose memory events) to a file called 'debug.txt'. If the program crashes, you can have the client e-mail you the debug.txt file, and you'll have much more insight to what's causing the crash.

Copyright 1997-2024, Director Online. Article content copyright by respective authors.