What Is This Atom Trace Thing, Anyway?

An atom trace catches the stream of information exchanged between the AOL user (client) and the AOL service (host). The tool for doing this is called the "debugger" or "trace tool." The purpose of doing an atom trace is to find out what data is exchanged between host and client, and has some very specific pieces of information that are useful in creating & testing forms and host processes. One of the most useful things you can get from an atom trace is the GID of a form that is being delivered to the user's screen. This document will explain how to set up a master tool, aka 'star tool,' and tell you how to get the GID of a form from an atom trace.

The basic idea behind the trace tool is that you can "see" what is going on between your client and the host, which is otherwise invisible to the user. The users, for instance, don't know that every single screen name in the buddy list is refreshed when the list updates - it looks like only the changes are updated there.

Some of the other uses of atom traces are:

• Determining what kind of information is sent up from the user to the host. Example: If you invoke the Keyword form, and type in a keyword, then click the Go button, the atom trace can tell you what token is assigned to the Go button, and if any other information is sent up along with the keyword you typed in.
• Identifying the information servers are sending down to the client. Example: In parental controls, the buttons on the main edit screen have no actions assigned in form_edit. The server is supplying the button actions, and if you trace the form as it is being rendered to the user, you will see what action types, tokens, and arguments are being assigned to the buttons on that form.
• Sorting out errors in the display of forms. Example: You sign on with a Kids Only account, and the toolbar doesn't render completely - it's half blank. If you do a trace as you're signing on, you might see that the toolbar is trying to write to relative ID 253 when it stops. If you told the IMD that, he would immediately check the welcome screen form for RID 253, and see that it wasn't in there - then you'd know that the toolbar was incomplete because a call was being made to a relative ID that doesn't exist.
• Getting the GID of a form. Example: You are testing a QAR, and you find a bug. You quickly run a trace while loading up the form that's having the problem, and you identify the form as GID 41-29343. You include this information in the bug report, and the IMD is able to fix it faster because he already knows going in which form is having a problem. This helps to eliminate ambiguity about which form is being described in a bug.

Installing A Master Tool

To do an atom trace, you will need to install the master tool in your AOL or CompuServe client. There are some files you need to add to your AOL or CS directory to allow the tool to work. In your main software directory (eg: c:\aol_50\), you need:

Atoms.bin
Atomdbug.cfg
Atoms.ada

And in your tools directory (eg: c:\aol_50 ools\), you need:

Master.tol

A note about this file: It's the same file between most versions of AOL and CompuServe software, but there is a slight difference in what you name the file. For AOL 4.0, it's master.tol, for AOL 5.0 it's master.aol, and for CompuServe, it's master.cs.

I've found it's handy to keep a "master tool install" directory on my computer in the root (C:\master_install\) and then whenever I have a new copy of AOL or CSI that needs a master tool, I can simply copy the files over to the correct directories. In that same directory, I keep copies of the following files, which should come with your AOL or CSI software, but if they're not in there, the master tool won't work:

Ada.bin
Ada32.dll

If your AOL or CSI software is open when you copy these files over, you will need to relaunch it. If it's closed while you're moving files, simply launch the software, and you will see the asterisk (*) menu to the left of the File menu in the toolbar.

Starting A Trace

Now you're ready to do a trace. To start a trace, click on the * menu and scroll down until you see the item Atomic Debugger. Select this, and it will open the trace tool application.

To start a trace, select New on the File menu, then select the Setup menu. That will bring up the floating toolbar ("Settings") that you see in the picture above. Set up the conditions in your AOL or CSI software so that you are ready to trace before clicking in the Atoms Trace checkbox on the floating Setting toolbar. When you are all set, turn on the trace with the Atoms Trace checkbox, then flip back over to AOL or CSI and execute the action you are trying to trace.

For example, if you want to find out what form is invoked when you click the Setup button on your buddy list, you want to close all other windows, start your trace, and then click that button. Once you've clicked the button, you want to turn the trace off, to avoid getting unnecessary information in the trace.

One thing you want to keep in mind when you are tracing is that ANY communication between the host and client will be tracked during a trace. Therefore, if you are running a trace when your buddy list updates, you will see all the atoms for that in your trace window.

Once you've got your trace, you need to look in it to find the information you want. This can be a little daunting, because there is a LOT of information there, and locating the one single line you need is almost a needle in the haystack proposition. There are, however, a couple of tricks you can use to help make it fast and easy to locate your info.

The most common thing you'll probably be looking for is a GID. The GID of a form is generally going to be indicated in the first 10 lines of atoms that define the form. So, in order to locate your GID, you need to find the start of the form in your trace. The other thing that normally appears near the beginning of a form is the window title. So, you can search your trace for the window title text. Often, the GID of the form will appear somewhere in the lines close to that in the trace. When the title is assigned in form_edit, the GID will appear AFTER the title, in the trace. When the server is filling in the window title, the GID will appear BEFORE the title in the trace.

In the sample trace below, I started my trace and then invoked the keyword form, using ctrl + k. To find the GID in the trace, I did a find on "Keyword," which is the title of the window:

uni_start_stream <00x>
    man_close_update <32-5721>
    man_start_object 		ß this is the window title
      mat_style_id <40-5792>				ß this is the style ID
      mat_orientation 
      mat_color_face <255, 251, 240>
      mat_object_id <32-5721>				ß this is the GID of the form
      act_set_criterion <11>
      act_replace_action

You can see in the sample trace where the window title appears, and then the GID is 5 lines after that. You have to be wary of the style ID, because it does NOT indicate the GID of the form!

Once you get comfortable doing traces, you will be able to scan the trace visually to look for clues as to which part of the stream you're looking at, and know from that whether you need to scroll up or down to find it. However - that's that advanced technique, and will take some time to get that good. Until then, you're likely to get a few headaches trying to read these things!

Practice a little bit finding the GIDs of forms you're working with.

Next Page - Tokens>>