spec

Software for Diffraction

debug

set debugging level of diagnostic messages

SYNOPSIS

debug level

DESCRIPTION

A value assigned to the built-in global variable DEBUG enables various levels of debugging message output. A debugging level can also be set on startup with the -d option. The debug standard macro can also select a debugging level.

The following values when added together set the debugging level. Decimal values are shown in the first column, hexadecimal in the second. (Adding hexadecimal values together is easier when higher order bits are involved!)

       
  1 0x1 Input Tokens
  2 0x2 Execution Nodes
  4 0x4 Node Allocate/Free
  8 0x8 Symbol Table Creation/Lookup
  16 0x10 Values Get/Set
  32 0x20 Memory Misc
  64 0x40 Hardware Higher Level
  128 0x80 Hardware Lower Level
  256 0x100 Macro Substitution
  512 0x200 Memory Allocate/Free
  1024 0x400 Macro Expansion
  2048 0x800 Warnings
  4096 0x1000 Hardware Lowest Level
  8192 0x2000 Data Array Allocation
  etc. 0x4000 Signal Blocking
    0x8000 Hardware Low Level Details
    0x10000 Input Files and System Commands
    0x20000 Runtime Debugging
    0x40000 Input Context On Runtime Errors
    0x80000 Sleeps
    0x100000 Thread Locking (enormous amount of output)
    0x200000 State Changes (not normally available)
    0x400000 Hexadecimal For Socket/Serial
    0x800000 Server/Client Socket Messages

When invoking the debug macro, an argument of +value or -value adds or removes value from the current level.

For hardware debugging, the following levels may be useful. Level 128 generally displays higher level messages associated with hardware controllers. Level 64 displays lower level serial and socket messages. Level 4096 shows more detailed messages for some protocols, including the server mode messages between spec servers and clients. The detailed socket level messages used during spec server/client communication are only shown if level 0x800000 is active. Including level 0x400000 with level 64 or level 0x800000 will select a hex dump format for the low level serial and socket messages.

Level 0x40000 shows input context on execution errors and can be helpful to help pin down syntax errors in macros.

Other levels, such as those that show memory allocation (512), sleeps (0x80000) and thread locking (0x100000), produce copious output and are likely only useful to those working on the spec code.

Debugging mode can generate a large amount of output that will appear not only on the screen but also in any open output files, including the data file. However, if a special debugging log file is opened, the debugging output will only appear in that file, not on the screen and not in any other files. A debugging log file is an output file that is named dlog or ends with the string .dlog. For example:

fon hdw.dlog
debug 192

... commands to be debugged ...

debug 0
fclose hdw.dlog

GLOBAL VARIABLES

DEBUG
A built-in global variable that holds the value of the debugging level.

SEE ALSO

spec