What to Include

The more information you can give us about the problem and the environment in which it occurs, the faster we can resolve the problem. Below is a list of information that is helpful to us. Not every item is appropriate for a particular report, but please include whatever you can.

1. Shore software version number.

2. Operating system and architecture used to run Shore.

3. Tell us if you are using one of the binary releases (the debugging or no-debugging version?) or if you compiled Shore yourself. If you compiled it yourself, what version of the compiler did you use? What configuration options did you use (DEBUG_CODE, OPTIMIZE, etc.)?

4. Can you reproduce the problem? Reliably? If so, tell us exactly what sequence of events led up to the problem. Send us a typescript if possible.

5. Version number of the compiler you are using to compile your application (or value-added server, if that's what you are building). Run gcc -v to get this version number. If this is not of the versions of gcc with which Shore is know not to work (see the installation manual), don't send a problem report; install one of the versions that works and use it.

6. Any messages produced by the failed program. Yank the messages verbatim; better yet, reproduce the problem in a typescript. See the Unix manual pages for script(1).

7. If the program that failed is a client, what did the server have to say about it? Did the server produce any error messages? If your server is running in the foreground with a Tcl shell, in the shell type ``suppress off'' and ``log client info''.

   Rerun your client. Include the output of the server in your problem report.

8. If your program aborts with a segmentation fault or an assertion failure, try to get a stack trace with gdb and send us the result.

   If your program does not get a segmentation fault, but does get another error, run it with gdb and get a stack trace at perrstop (unless you are writing your own value-added server and using the Storage Manager directly).

   Please do your best to track down the source of the problem with gdb, debugging print statements, and other debugging tools at hand (that is, to give us a reasonable amount of detailed information). Remember that Shore is freeware; the project runs on limited resources, and every bit of help you can give us allows us to do more work on Shore extensions.

9. If you cannot compile your program because you get a compilation error that you do not understand, and if the error appears to be in the Shore sources, try using the -E -dD options on gcc. Send the output to a file junk.C.lines and look at the file. Often these problems are due to the fact that a file (included before ShoreApp.h or before the C++ language binding) defines a C-preprocessor-macro that confuses matters.

   If you cannot glean any useful information from this, use the -E -dD -P options on gcc, and pipe the results to a file junk.C. Compile junk.C with gcc. Often this will pinpoint the problem.

   If you still cannot glean any useful information, send us junk.C IN A SEPARATE MAIL MESSAGE, with the subject ``junk.C''; also send us junk.C.lines in a separate mail message with the subject ``junk.C.lines''.