This is an HTML version of the FAH Wiki article I wrote:
http://fahwiki.net/index.php/Howto_use_qd_to_debug_the_FAH_client
Please see that Wiki page for the latest version of this document. This document is supplied for offline reading convenience only.
Contents
1 About qd
2 Getting qd
3 Running qd
3.1 Running qd on Windows
3.1.1 Copying the qd output
3.1.1.1 Redirecting the qd output to a file
3.1.1.2 Select all text in the DOS prompt and copy it
3.2 Running qd on Linux/FreeBSD/OpenBSD/Mac OS X
3.3 Special Folding-Community debugging output
4 Links
About qd
Dick Howell (rph_iv) created a small tool to display (dump) the content of the queue.dat file generated by the Folding@Home client called qd (queue dump), which was announced in the Folding-Community forum topic QUEUE.DAT dump and benchmark utilities in May 2002.
It started out displaying the information fields in the queue.dat it knew about, which were few in the beginning, but over time evolved to being able to display almost all information field in the queue.dat, the qd source code contains a comment about bytes 500-507 and byte 528 still sometimes containing unknown information. The layout of the queue.dat file is documented on this Wiki and as part of the qd-tools documentation now being maintained by Bas Couwenberg.
Getting qd
Before Dick Howells tragic passing in August 2005, the latest version of qd and Dicks other Folding@Home related tools were available on his website. After Dicks passing, his website was mirrored by Larry Perry (TheWeatherMan, author of EM III) on August 4th 2005, and another mirror of Dicks website was made by Bas Couwenberg on August 11th 2005.
These days the mirrors on Dick Howells website contain outdated (and buggy!) versions of qd. qd, qdiprint and qdinfo.dat are now being maintained as qd-tools by Bas Couwenberg with the help of several other Folding@Home contributors.
You can download precompiled binaries for Windows, Linux, FreeBSD, OpenBSD and Mac OS X from the qd-tools website. Or you can choose to compile qd from source yourself. If you choose to compile qd yourself, be sure to understand the effects of the compiler defines in the qd.c source code.
You can save the downloaded qd in the same directory as your Folding@Home client, or use a separate directory. If you wish to use the defaults built into qd, you should place it in the Folding@Home client directory, otherwise you can use the commandline parameters to override the defaults.
Running qd
qd is a simple console application which means that it only prints text output in a terminal, like a DOS prompt or UNIX xterm or tty. Because of this, qd will output the information in each queue index in the order of oldest to newest, meaning that the last index printed by qd contains the information of the (presumably) currently running Work Unit (WU). qd is a console application and lacks a graphical interface (GUI) because it is developed on Linux where console applications are still heavily used. In the future, a GUI wrapper around the XML output of qd is expected though.
By default qd expects to be run from inside the directory use by the Folding@Home client. But it's possible to tell qd which directory to use with the -f commandline parameter when your current working directory is something other than the directory of your Folding@Home client. See qd --help for the full list of commandline parameters.
It is possible to have qd display a compact output where a small subset of the total information available is printed (using the -L or -l commandline parameters) . This output type is not very useful for debugging, but is very convenient for logging purposes. It's also possible to have qd display its output as either Well Formed or Valid XML (using the -x or -X commandline parameters), but this output type is not as easily readable by humans as the normal output is. Therefore this article will focus on the normal qd output.
Running qd on Windows
On Windows qd should be run from a DOS prompt, if you were to double click the qd binary in e.g. Windows Explorer, a DOS prompt will be opened in which qd will display its output, but this DOS prompt will also close immediately when it is finished. Therefore you should first open a DOS prompt, you can do this by clicking
Start -> Run
(or use the Windows key on your keyboard together with the R key)
and typing
cmd.exe
This should open a DOS prompt as shown below.
Screenshot: DOS prompt
For those of you fancying the wallpaper: download tux-msn-butterfly.jpg
Use the cd command to change to the directory of your Folding@Home client. By default the Folding@Home GUI client uses the directory C:\Program Files\Folding@Home. The Console client uses the directory in which it was run, this can be any directory in your filesystem.
You can then run qd to have it display all the information it can find in the queue.dat, and also from other files (unless you disallow looking in other files than queue.dat with the -p commandline parameter). You can also use the -q commandline parameter to tell qd which queue.dat file to use, this parameter implies -p and will therefore also only use the queue.dat file as data source.
Screenshot: Running qd inside a DOS prompt
Copying the qd output
Copying the output of qd from the DOS prompt requires a little work. You have two options available:
* Redirecting the qd output to a file
* Select all text in the DOS prompt and copy it
Both options are described below, but redirecting the output is the most convenient.
Redirecting the qd output to a file
Redirecting the output of qd to a file is as easy as appending > qd-output.txt to the qd command. This will create a file called qd-output.txt in the currrent working directory which will contain the output printed by qd.
Note: Using > will overwrite the existing file or create it if it doesn't exist. To append the output to a file without overwriting its already existing content, use >> instead of >.
You can then open this file with e.g. notepad to copy the content. For instance if you need to post this information to the Folding-Community forum.
Screenshot: Redirect qd output to a file
Select all text in the DOS prompt and copy it
If you wish to use the text in the DOS prompt without redirecting to a file (for instance if you don't have permissions to write to a file or directory), you can select and copy all the text in the prompt through the Edit menu of the DOS prompt.
You can get to the Edit menu by clicking the DOS prompt icon in the top left corner of the DOS prompt window. Click
Edit -> Select All
to select all text in the DOS prompt. And after all text is selected, click
Edit -> Copy
to copy the text to the clipboard. You can then paste the copied text from the clipboard to a new notepad document for instance.
Screenshot: Select all text in DOS prompt
Running qd on Linux/FreeBSD/OpenBSD/Mac OS X
Running qd on Linux, FreeBSD, OpenBSD or Mac OS X, means running qd in an environment like the one it is developed in. An environment where you can easily copy the text in your shell, xterm or tty.
To run qd, open your favorite terminal emulator, cd to the Folding@Home client directory and run qd.
bas@osiris:~$ cd software/folding
bas@osiris:~/software/folding$ ./qd -i
qd released 27 October 2006 (fr 044)
Queue version 5.01
Current index: 7
Index 8: finished 18.5 X min speed
server: 171.65.103.68:8080; project: 1496
Folding: run 2, clone 5, generation 1; benchmark 823; misc: 500, 200
issue: Fri Aug 11 22:37:56 2006; begin: Sat Aug 12 05:29:53 2006
end: Sat Aug 19 02:03:58 2006; due: Sun Dec 17 04:29:53 2006 (127 days)
core URL: http://www.stanford.edu/~pande/Linux/x86/Core_a0.fah
CPU: 1,0 x86; OS: 4,0 Linux
assignment info (le): Sat Aug 12 05:29:36 2006; A728271B
CS: 171.65.103.100; P limit: 52427776
user: [DPC]_Fatal_Error_Group0smoking2000; team: 92; ID: 9E3B81209D0E757D; mach ID: 1
work/wudata_08.dat file size: 3208918; WU type: Folding@Home
[...index 0-6 & 9 removed for brevity...]
Index 7: folding now 7.85 X min speed; 83% complete
server: 171.65.103.68:8080; project: 1487, "p1487_DPPC_DOPC_CHOL"
Folding: run 0, clone 584, generation 0; benchmark 0; misc: 500, 200
issue: Thu Oct 12 19:41:15 2006; begin: Thu Oct 12 19:41:31 2006
expect: Tue Oct 31 21:00:00 2006; due: Sun Mar 11 18:41:31 2007 (150 days)
core URL: http://www.stanford.edu/~pande/Linux/x86/Core_a0.fah (V1.71)
CPU: 1,0 x86; OS: 4,0 Linux
assignment info (le): Thu Oct 12 19:41:14 2006; A7991A01
CS: 171.65.103.100; P limit: 52427776
user: [DPC]_Fatal_Error_Group0smoking2000; team: 92; ID: 9E3B81209D0E757D; mach ID: 1
work/wudata_07.dat file size: 3304996; WU type: Folding@Home
Average download rate 216.420 KB/s (u=4); upload rate 72.967 KB/s (u=4)
Performance fraction 0.953748 (u=4)
Average pph: 2.845, ppd: 68.27, ppw: 477.9, ppy: 24936
Special Folding-Community debugging output
As a convenience feature for moderators and administrators of the Folding-Community forum, qd supports the -P commandline parameter as of functional revision 041.
This will output an additional line with the Project, Run, Clone and Generation numbers in the same format as it is logged in the FAHlog.txt file.
Project: 1496 (Run 31, Clone 1, Gen 5)
The forum mods and admins can cut and paste this line into the Work Unit database, to which only they have access, and lookup the records associated with that particular WU.
In the screenshot below, qd is also run with the -i commandline parameter. This will make qd insert an empty line between each queue index and use an extra space for indenting the information in each queue index. This makes the output more readable, and is therefore the preferred output type when reporting problems on the Folding-Community forum.
Screenshot: Running qd -P -i
Links
Dick Howells website (as mirrored by Larry Perry on August 4th 2005)<
Dick Howells website (as mirrored by Bas Couwenberg on August 11th 2005)
qd-tools website for current versions of qd
Folding-Community: QUEUE.DAT dump and benchmark utilities