Debugging q code in kdb

Kdb+ provides limited tools for debugging, we have break points but navigating the call stack to find current variable values is difficult as you will see below:

'Breakpoints / :Return
breaking on exceptional client calls
Interrupt a frozen q process

'Breakpoints / :Return

From within functions kdb supports both standard returns and exceptions. At any time :1 could be used within a function to return value 1 immediately and prevent further statements being executed. e.g. {a:x+1; :x+2; a} 1 will return the value 3.

Similarly an exception can be signaled and execution halted by using single quote e.g. 'err. You may have seen this happen when you cause an error e.g. {x+1} `a Execution is stopped inside the function and the console shows q)). While inside this break mode, remote calls are halted, variables inside the function are visible and execution control will only be returned to the main loop when you enter a single slash \. Here are some examples:

q)// :return a value immediately
q){a:x+1; :x*10; a} 1
10
q){a:x+1; if[x~100;:"one hundred"]; a} 1
2
q){a:x+1; if[x~100;:"one hundred"]; a} 100
"one hundred"

q)/ execution stops mid-function when an exceptions signaled
q){b:x+10; y+b}[200; `a]
{b:x+10; y+b}
'type
+
`a
210
q))/ we can access the variables within the function
q))x
200
q))y
`a
q))b
210
q))/ use a single slash to exit break mode
q))\
q)/ variables are no longer visible
q)b
'b

During break mode

When a break occurs, execution is halted at the level of the call stack that the exception was thrown. During a break we can:

Use :return or 'break to move further up the call stack.
Use .z.s to see what function we are in. (this is not always clear)
use show on complex variables like tables etc. to get standard output formats.

q)sqRoot:{{y-((y*y)-x)%2*y}[x]/[x%2]} / using newtons method
q)sqRoot 144
12f
q)sqRoot -10
{y-((y*y)-x)%2*y}
'stop
q))\
q)/ I used control-c to cancel the operation
q)/ let's put in a check and throw an exception for negatives
q)sqRoot:{if[0>x;'badNum]; {y-((y*y)-x)%2*y}[x]/[x%2]}
q)sqRoot -10
{if[0>x;'badNum]; {y-((y*y)-x)%2*y}[x]/[x%2]}
'badNum
q))\
q)

q) / exceptions within nested functions
q)f:{a:2; show c:sqRoot[2*x]; c + 100*x}
q)f -10 
{if[0>x;'badNum]; {y-((y*y)-x)%2*y}[x]/[x%2]}
'badNum
q))/ check where we are
q)).z.s
{if[0>x;'badNum]; {y-((y*y)-x)%2*y}[x]/[x%2]}
q))x
-20
q))/ try returning 3 instead
q)):3
{a:2; show c:sqRoot[2*x]; c + 100*x}
'stype
@
{if[0>x;'badNum]; {y-((y*y)-x)%2*y}[x]/[x%2]}
-20
q))/ didn't quite work, check where we are again
q)).z.s
{a:2; show c:sqRoot[2*x]; c + 100*x}
q))/ double check by looking at a
q))a
2
q))c
()
q))/ return 3 again
q))x
-10
q)):3
3
-997

Other useful functions

0N! - Shows a value in the console and pass it through an expression simultaneously
-3! - "returns the string representation of x."

q)sqRoot:{{y-((y*y)-x)%2*y}[x]/[x%2]}
q)sqRoot 144
q)// quickly use 0N! to print out value of each run to console
q)sqRoot:{{y-((y*y)-x)%2*0N!y}[x]/[x%2]}
q)sqRoot 144
72f
37f
20.44594594594595
13.74445347528626
12.11070348969896
12.00050596823884
12.00000001066638
12f
12f

Catching a break

Rather than break mode occurring, we can wrap a section of code using protected evaluation. Any exceptions that occur within protected evaluation can be handled without rising all the way up the stack and causing break mode. (similar to try/catch in other languages like java) e.g.:

q)sqRoot:{if[0>x;'badNum]; {y-((y*y)-x)%2*y}[x]/[x%2]};
q)h:{sqRoot x*10};
q)h -4
{if[0>x;'badNum]; {y-((y*y)-x)%2*y}[x]/[x%2]}
'badNum
q))\
q)@[h; 4; {show "error thrown, returning zero"; 0}]
6.324555320336759
q)@[h; -4; {show "error thrown, returning zero"; 0}]
"error thrown, returning zero"
0

Breaking on exceptional client calls

By default only functions entered at the console result in break mode being thrown, This can also be applied to client queries using system command \e 1 (0 turns off, 1 turns on) . This should only be used for testing for as mentioned, when in break mode remote queries are queued on a stack and not executed until the function returns.

Interrupt a frozen q process

At the q console Control-C can be used to interrupt a long running command in some cases. Control-C sends a SIGINT which if the running q command supports it, interrupts and returns early. It is also possible to send an interrupt from the linux terminal using the command kill -SIGINT processPIDHere. When interrupted successfully the console will show a 'stop exception and break at the current position in the stack:

q)f:{ 2 xexp 100000?100.}
q){ while[1b; f[]] }[]
{2 xexp 100000?100.}
'stop
q)).z.s
{2 xexp 100000?100.}
q))\
q)

Contents