How to use qd to debug the FAH client
From FaHWiki
Contents |
About qd
Dick Howell (rph_iv) created a small tool to display (dump) the contents of the queue.dat file generated by the Folding@Home client called qd (queue dump), which was announced in the Folding-Community forum topic Folding-community: QUEUE.DAT dump and benchmark utilities in May 2002.
It started out displaying the information fields in the queue.dat that it knew about, which were few in the beginning, but over time it evolved to being able to display almost all information fields 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 Howell's tragic passing in August, 2005, the latest version of qd and Dick's other Folding@Home-related tools were available on his website. After Dick's passing his website was mirrored by Larry Perry (TheWeatherMan, author of EM III) on August 4, 2005, and another mirror of Dick's website was made by Bas Couwenberg on August 11, 2005.
These days the mirrors on Dick Howell's 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. That 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 which 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 used 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 kind of output is not very useful for debugging but is very convenient for logging. 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 kind of output is not as easily readable by people 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 because if you were to double-click the qd binary in e.g. Windows Explorer, a DOS prompt would be opened in which qd would display its output, but this DOS prompt will also close immediately when it is finished, removing its output from the screen. Therefore you should open a DOS prompt before starting qd. You can do this by clicking
Start -> Run
(or you can 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. That 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 in other files (unless you use the -p commandline parameter to disallow looking in other files than queue.dat). 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:
Both options are described below, but redirecting the output is the more 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. If you want this file in a different directory you may specify a full pathname instead of just a filename.
- 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 >. Appending the output to a file with >> will create the file if it does not already exist.
You can then open this file with e.g. notepad to copy the content if for example you need to post this information to the Folding-Community forum. When posting qd output on the Folding-Community forum, please use the special Folding-Community debugging output.
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, then click
Edit -> Copy
to copy the text to the clipboard. You can then paste the copied text from the clipboard to a new notepad or word 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 in which it is developed, an environment where you can easily copy the text in your shell, xterm or tty. Note that qd expects to be in the same directory as the queue.dat file it is to read. For other usage run qd --help.
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 they are 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 it's therefore the preferred output format when reporting problems on the Folding-Community forum. So please use qd -P -i when reporting problems. Of course, if you admire terseness you can run qd -Pi.
Screenshot: Running qd -P -i
Links
- Dick Howell's website (as mirrored by Larry Perry on August 4, 2005)
- Dick Howell's website (as mirrored by Bas Couwenberg on August 11, 2005)
- qd-tools website for current versions of qd
- Folding-community: QUEUE.DAT dump and benchmark utilities
